> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/specs/phase25-session01-ceremony-registry-and-test-harness/implementation-notes.md). # Implementation Notes **Session ID**: `phase25-session01-ceremony-registry-and-test-harness` **Package**: apps/web **Started**: 2026-07-09 22:13 **Last Updated**: 2026-07-09 23:15 *** ## Session Progress | Metric | Value | | ------------------- | ------- | | Tasks Completed | 18 / 18 | | Estimated Remaining | 0 hours | | Blockers | 0 | *** ## Task Log ### 2026-07-09 - Session Start **Environment verified**: * [x] Prerequisites confirmed * [x] Tools available * [x] Directory structure ready ### Task T001 - Verify helper contracts and baseline **Started**: 2026-07-09 22:13 **Completed**: 2026-07-09 22:14 **Duration**: 1 minute **Notes**: * Confirmed the Phase 24 world cue, alert-focus, and scanner-state pure helper contracts are present and the active package resolves to `apps/web`. * Confirmed the existing focused tests and web TypeScript baseline pass before Session 01 application-code edits. **Files Changed**: * `apps/web/package.json` - inspected workspace commands; no content change. **Verification**: * Command/check: `npm test -- apps/web/tests/worldCues.test.ts apps/web/tests/scryingAndAlertFocus.test.ts apps/web/tests/battlefieldScannerState.test.ts` * Result: PASS - 3 files and 22 tests passed. * Command/check: `npm --workspace @factionos/web run typecheck` * Result: PASS - TypeScript build check exited successfully. * UI product-surface check: N/A - pure helper baseline only. * UI craft check: N/A - no UI changed. **BQC Fixes**: * Contract alignment: established a clean baseline for the pure helper seams consumed by later ceremony selectors. ### Task T002 - Create pure module and test skeleton **Started**: 2026-07-09 22:14 **Completed**: 2026-07-09 22:15 **Duration**: 1 minute **Notes**: * Created the dependency-free TypeScript module boundary and a focused Vitest file that proves the module loads without browser or application setup. **Files Changed**: * `apps/web/src/lib/verbCeremony.ts` - added the documented pure module boundary. * `apps/web/tests/verbCeremony.test.ts` - added the module-load regression. **Verification**: * Command/check: `npm test -- apps/web/tests/verbCeremony.test.ts` * Result: PASS - 1 file and 1 test passed. * Command/check: dependency scan for React, Zustand, DOM, storage, timer, and audio runtime tokens in `apps/web/src/lib/verbCeremony.ts` * Result: PASS - no forbidden dependency token found. * UI product-surface check: N/A - pure module and test skeleton only. * UI craft check: N/A - no UI changed. **BQC Fixes**: * Resource cleanup and mutation safety: kept the module free of resources and mutable runtime state by construction. ### Task T003 - Define ceremony contracts **Started**: 2026-07-09 22:15 **Completed**: 2026-07-09 22:16 **Duration**: 1 minute **Notes**: * Added literal-derived types for all 13 verbs, eight tones, ten primary surfaces, fixed audio/privacy posture, complete spec fields, data attributes, and minimal read-only input contracts for all selector families. **Files Changed**: * `apps/web/src/lib/verbCeremony.ts` - added registry and selector type contracts. **Verification**: * Command/check: focused Vitest plus `npm --workspace @factionos/web run typecheck` * Result: PASS - 1 test passed and TypeScript exited successfully. * Command/check: literal ID count inspection * Result: PASS - exactly 13 Phase 4 IDs detected. * UI product-surface check: N/A - pure contracts only. * UI craft check: N/A - no UI changed. **BQC Fixes**: * Contract alignment and trust boundaries: selector inputs use closed literal vocabularies and read-only fields, with runtime validation scheduled before selector completion. ### Task T004 - Populate the canonical registry **Started**: 2026-07-09 22:16 **Completed**: 2026-07-09 22:19 **Duration**: 3 minutes **Notes**: * Added one frozen spec per Phase 4 verb with bounded copy, static and motion classes, accessible summaries, semantic cue IDs, and source-only media IDs. * Corrected the provisional selector contracts to the live protocol and pure helper vocabularies before downstream integration. **Files Changed**: * `apps/web/src/lib/verbCeremony.ts` - added all 13 canonical specs and aligned type-only selector contracts. **Verification**: * Command/check: `npm --workspace @factionos/web run typecheck` * Result: PASS - TypeScript exited successfully. * Command/check: runtime module inventory inspection * Result: PASS - 13 IDs, 13 specs, and 18 semantic audio cues. * UI product-surface check: N/A - pure registry only. * UI craft check: N/A - no UI changed. **BQC Fixes**: * Contract alignment: replaced invented toast, War Room, channel, hero, and scanner states with live repository vocabulary before selectors were added. * Error information boundaries: all registry copy is fixed and does not include caller-provided payload data. ### Task T005 - Encode inert claim attributes **Started**: 2026-07-09 22:19 **Completed**: 2026-07-09 22:20 **Duration**: 1 minute **Notes**: * Added registry-owned inert attributes for reserved class affinity, no-reward discharge/Banish posture, and local-existing-action Emissary behavior. **Files Changed**: * `apps/web/src/lib/verbCeremony.ts` - added typed inert attribute construction. **Verification**: * Command/check: web typecheck plus direct registry attribute inspection * Result: PASS - all three required literal attributes are present on the intended specs and absent from the core builder input surface. * UI product-surface check: N/A - pure attributes only. * UI craft check: N/A - no UI changed. **BQC Fixes**: * Contract alignment: machine-readable no-claim posture now travels with the canonical registry rather than depending on later component convention. ### Task T006 - Implement exact ID guards **Started**: 2026-07-09 22:20 **Completed**: 2026-07-09 22:21 **Duration**: 1 minute **Notes**: * Added a closed-set runtime guard and internal exact registry lookup. * Prototype property names, malformed values, and non-strings fail closed. **Files Changed**: * `apps/web/src/lib/verbCeremony.ts` - added ID set, type guard, and lookup. **Verification**: * Command/check: web typecheck and direct guard matrix * Result: PASS - all 13 IDs accepted; malformed and prototype names rejected. * UI product-surface check: N/A - pure guard only. * UI craft check: N/A - no UI changed. **BQC Fixes**: * Trust boundary enforcement: unknown values must pass an exact closed-set check before becoming registry keys. ### Task T007 - Implement bounded text safety **Started**: 2026-07-09 22:21 **Completed**: 2026-07-09 22:23 **Duration**: 2 minutes **Notes**: * Added fail-closed redaction for secrets, provider/channel payloads, URLs, absolute paths, shell commands, diffs, and opaque token-shaped values. * Added ASCII normalization, whitespace/control cleanup, safe fallback handling, finite length clamping, 160-character body bounds, and 80-character titles. **Files Changed**: * `apps/web/src/lib/verbCeremony.ts` - added text safety helpers and patterns. **Verification**: * Command/check: web typecheck and direct privacy/ASCII/boundary matrix * Result: PASS - all redaction categories, ASCII normalization, fallback, and title bounds behaved as specified. * UI product-surface check: N/A - pure text helper only. * UI craft check: N/A - no UI changed. **BQC Fixes**: * Trust boundary enforcement: unknown input is type-checked and unsafe text is replaced with stable bounded markers. * Error information boundaries: broad internal payload categories cannot be copied into user-visible ceremony copy. ### Task T008 - Export attributes and audio guard **Started**: 2026-07-09 22:23 **Completed**: 2026-07-09 22:24 **Duration**: 1 minute **Notes**: * Added exact semantic audio-cue validation and canonical data-attribute projection that accepts only registry-created canonical or derived specs and preserves registry-owned inert posture only. **Files Changed**: * `apps/web/src/lib/verbCeremony.ts` - added cue guard and attribute helper. **Verification**: * Command/check: web typecheck and direct cue/attribute forgery matrix * Result: PASS - 18 cues accepted, unknown/prototype values rejected, forged spec objects rejected, and unknown specs raise a stable error. * UI product-surface check: N/A - pure helper only. * UI craft check: N/A - no UI changed. **BQC Fixes**: * Trust boundary enforcement: attribute output is rebuilt from canonical state instead of spreading caller-owned data. * Failure path completeness: invalid specs fail with a stable bounded error. ### Task T009 - Implement toast, attention, and notice selectors **Started**: 2026-07-09 22:24 **Completed**: 2026-07-09 22:27 **Duration**: 3 minutes **Notes**: * Added deterministic known-keyword toast classification without copying title text into returned presentation state. * Added alert-focus mapping for flares, gates, and new scanner fronts, including a static/audio-off derived flare state after repeated fanfare. * Added critical/error Notice decree mapping and neutral contract fallback. **Files Changed**: * `apps/web/src/lib/verbCeremony.ts` - added derived specs and three selectors. **Verification**: * Command/check: web typecheck and direct selector matrix * Result: PASS - 12 toast cases, supported/unsupported attention, fatigue, and Notice priority/severity behavior passed. * UI product-surface check: N/A - pure selectors only. * UI craft check: N/A - no UI changed. **BQC Fixes**: * Contract alignment: selector signatures now follow the canonical source plan and live repository enum vocabularies. * Error information boundaries: toast titles are used only for static keyword classification and are never returned. * Failure path completeness: unsupported attention categories return `null`. ### Task T010 - Implement quest and hero selectors **Started**: 2026-07-09 22:27 **Completed**: 2026-07-09 22:28 **Duration**: 1 minute **Notes**: * Mapped assign, accept, normal dismiss, and codebase-issue Banish semantics to muster, rally, contract, and no-reward discharge specs. * Mapped spawning, newly active, awaiting-input, and dismissed hero transitions while keeping unchanged active, idle, verifying, and error states quiet. **Files Changed**: * `apps/web/src/lib/verbCeremony.ts` - added quest and hero selectors. **Verification**: * Command/check: web typecheck and direct 4-case quest / 8-case hero matrix * Result: PASS - all supported and quiet-state mappings matched. * UI product-surface check: N/A - pure selectors only. * UI craft check: N/A - no UI changed. **BQC Fixes**: * Contract alignment: codebase Banish remains the existing dismiss action and newly active rally is transition-sensitive. * Failure path completeness: non-ceremonial hero states return `null`. ### Task T011 - Implement plan and permission selectors **Started**: 2026-07-09 22:28 **Completed**: 2026-07-09 22:30 **Duration**: 2 minutes **Notes**: * Added approved/rejected plan twins with wax-seal versus scroll-tear cues. * Added approved/denied/expired gate twins with raise, drop, or silent static posture while preserving original decision authority. **Files Changed**: * `apps/web/src/lib/verbCeremony.ts` - added plan/permission selectors and two variant cue IDs. **Verification**: * Command/check: web typecheck and direct decision-state matrix * Result: PASS - plan approve/reject, gate approve/deny/expire, attributes, cues, and invalid boolean failure paths passed. * UI product-surface check: N/A - pure selectors only. * UI craft check: N/A - no UI changed. **BQC Fixes**: * Failure path completeness: invalid runtime booleans fail closed with `null`; expired decisions are silent and explicitly no-action. * Contract alignment: derived state twins remain frozen presentation copies of one canonical verb without mutating the registry. ### Task T012 - Implement scroll, War Room, and channel selectors **Started**: 2026-07-09 22:30 **Completed**: 2026-07-09 22:32 **Duration**: 2 minutes **Notes**: * Added collected/available scroll twins with bounded rarity classes. * Added approved, connected, and caught-up War Room presentation while keeping incomplete, unavailable, rejected, reconnecting, disconnected, and left states quiet. * Added inbound command presentation with replay, validation, direction, local approval, and failed/unavailable guards. **Files Changed**: * `apps/web/src/lib/verbCeremony.ts` - added scroll, War Room, and channel selectors. **Verification**: * Command/check: web typecheck and direct selector matrix * Result: PASS - scroll state/rarity, 12 War Room states, and inbound/outbound, replay, handled, failed channel cases passed. * UI product-surface check: N/A - pure selectors only. * UI craft check: N/A - no UI changed. **BQC Fixes**: * Duplicate action prevention: duplicate/replayed/blocked command records are ineligible for ceremony. * Trust boundary enforcement: channel selectors inspect only bounded protocol state fields and never receive raw bodies. * Failure path completeness: rejected, failed, unavailable, and premature lifecycle states return `null`. ### Task T013 - Implement scanner-state selector **Started**: 2026-07-09 22:32 **Completed**: 2026-07-09 22:34 **Duration**: 2 minutes **Notes**: * Added running-scout and completed-report presentation with distinct horn and report-unfurl cues. * Failed, drill, and not-run states remain quiet; completed reports remain eligible after the short-lived dispatch flag clears. **Files Changed**: * `apps/web/src/lib/verbCeremony.ts` - added scanner selector and cue variants. **Verification**: * Command/check: web typecheck and direct scanner matrix * Result: PASS - running, clean report, front report, failed, drill, not-run, and durable completion cases passed. * UI product-surface check: N/A - pure selector only. * UI craft check: N/A - no UI changed. **BQC Fixes**: * Contract alignment: selector consumes the existing pure `BattlefieldScannerState` contract. * Failure path completeness: synthetic drill and failed/admin states cannot receive success ceremony. ### Task T014 - Add registry completeness tests **Started**: 2026-07-09 22:35 **Completed**: 2026-07-09 22:36 **Duration**: 1 minute **Notes**: * Added structural coverage for exact ID/spec counts, uniqueness, complete fields, fixed cues, frozen objects, source-only references, ASCII copy, accessibility, reduced-motion attributes, and inert no-claim attributes. **Files Changed**: * `apps/web/tests/verbCeremony.test.ts` - added four registry-focused tests. **Verification**: * Command/check: `npm test -- apps/web/tests/verbCeremony.test.ts` * Result: PASS - 1 file and 5 tests passed. * UI product-surface check: N/A - pure registry tests only. * UI craft check: N/A - no UI changed. **BQC Fixes**: * Contract alignment: every required field and attribute now has exhaustive registry-level regression coverage. ### Task T015 - Add selector matrix tests **Started**: 2026-07-09 22:36 **Completed**: 2026-07-09 22:38 **Duration**: 2 minutes **Notes**: * Added table-driven coverage for all 11 selectors, state twins, fatigue, rarity, lifecycle completion, replay suppression, and quiet failure/admin states. * Repaired the first toast no-copy assertion to use a unique caller-only needle rather than fixed canonical copy that intentionally matched the title. **Files Changed**: * `apps/web/tests/verbCeremony.test.ts` - added seven selector-focused tests. **Verification**: * Command/check: focused Vitest and web typecheck * Result: PASS - 1 file and 12 tests passed; TypeScript exited successfully. * UI product-surface check: N/A - pure selector tests only. * UI craft check: N/A - no UI changed. **BQC Fixes**: * Contract alignment: every selector signature and supported state family is now covered against live repository vocabulary. * Failure path completeness: unsupported combat, lifecycle, replay, scan, failure, and admin states have explicit null assertions. ### Task T016 - Add adversarial privacy and purity tests **Started**: 2026-07-09 22:38 **Completed**: 2026-07-09 22:40 **Duration**: 2 minutes **Notes**: * Added redaction tests for secrets, payloads, URLs, Windows/POSIX paths, commands, diffs, opaque tokens, Unicode, controls, unsafe fallbacks, and length edge cases. * Added malformed guard/attribute/selector failures, raw selector-field no-copy assertions, an independent-process import-purity check with trapped browser globals, and a source-level forbidden-dependency scan. **Files Changed**: * `apps/web/tests/verbCeremony.test.ts` - added four adversarial regression tests. **Verification**: * Command/check: focused Vitest and web typecheck * Result: PASS - 1 file and 18 tests passed; TypeScript exited successfully. * UI product-surface check: N/A - pure privacy and dependency tests only. * UI craft check: N/A - no UI changed. **BQC Fixes**: * Trust boundary enforcement and error information boundaries: adversarial categories and extra raw fields now have explicit no-leak evidence. * Resource cleanup: source scan proves the module has no timer, browser, state-manager, or audio-runtime acquisition path. ### Task T017 - Run focused tests and typecheck **Started**: 2026-07-09 22:40 **Completed**: 2026-07-09 22:41 **Duration**: 1 minute **Notes**: * Ran the complete Session 01 focused suite and package typecheck after all implementation and adversarial coverage landed. **Files Changed**: * `apps/web/src/lib/verbCeremony.ts` - verified final implementation state. * `apps/web/tests/verbCeremony.test.ts` - verified final focused coverage. **Verification**: * Command/check: `npm test -- apps/web/tests/verbCeremony.test.ts` * Result: PASS - 1 file and 18 tests passed. * Command/check: `npm --workspace @factionos/web run typecheck` * Result: PASS - TypeScript exited successfully. * UI product-surface check: N/A - Session 01 intentionally changes no UI. * UI craft check: N/A - Session 01 intentionally changes no UI. ### Task T018 - Validate encoding, formatting, and scope **Started**: 2026-07-09 22:41 **Completed**: 2026-07-09 22:42 **Duration**: 1 minute **Notes**: * Applied repository formatting to the two Session 01 application files. * Confirmed the only application files added are the planned pure module and focused test; no React, CSS, store, protocol, server, storage, or runtime media file changed. **Files Changed**: * `apps/web/src/lib/verbCeremony.ts` - formatted and scope-verified. * `apps/web/tests/verbCeremony.test.ts` - formatted and scope-verified. **Verification**: * Command/check: `npx biome check apps/web/src/lib/verbCeremony.ts apps/web/tests/verbCeremony.test.ts` * Result: PASS - 2 files checked with no issues. * Command/check: ASCII, CRLF, `git diff --check`, and `git status --short` * Result: PASS - ASCII-only LF files, clean diff, and only the two planned application files plus workflow artifacts are changed. * Command/check: final focused Vitest and web typecheck after formatting * Result: PASS - 1 file / 18 tests and TypeScript passed. * UI product-surface check: N/A - Session 01 intentionally changes no UI. * UI craft check: N/A - Session 01 intentionally changes no UI. *** ## Checkpoint **2026-07-09 22:35**: * Focused module test passed: 1 file / 1 test. * Web workspace typecheck passed. * Re-read all four objectives; implementation remains limited to the pure registry, selectors, privacy helpers, and focused tests. * No React, CSS, store, protocol implementation, persistence, or runtime media file has changed. ## Earlier Audit Repairs **2026-07-09 22:54**: * Restricted toast ceremony to explicit semantic outcomes, added token-boundary classification, and kept administrative, failed, completed-mission, and keyword-collision toasts quiet. * Corrected awaiting-input completion, durable scan-report, and Quest dismiss surface mappings so ceremonies follow actual state transitions. * Changed every public selector to fail closed on malformed top-level or nested runtime enum values, and rejected valid-looking forged ceremony spec clones. * Expanded privacy redaction to root/system/forward-slash Windows paths, common shell commands, and spaced API-key labels. * Replaced the in-process purity assertion with an independent Node import that traps browser globals; the source-level dependency scan remains supplemental. * Focused suite now passes 18 tests and web TypeScript passes after repairs. ## Implementation Resume Repairs ### Tasks T003, T004, and T008 - Close fixed ceremony vocabularies **Completed**: 2026-07-09 23:05 **Notes**: * Froze exported runtime vocabularies and added closed plan, permission, and source-asset ID unions so registry references cannot drift to arbitrary IDs. **Files Changed**: * `apps/web/src/lib/verbCeremony.ts` - closed and froze ceremony vocabularies. * `apps/web/tests/verbCeremony.test.ts` - asserted exact membership and immutability. **Verification**: * Command/check: focused Vitest and web typecheck * Result: PASS - 18 tests passed and TypeScript exited successfully. **BQC Fixes**: * Contract alignment: runtime collections now match their literal TypeScript unions. ### Tasks T005, T009, T010, and T011 - Fail closed on unsupported ceremony states **Completed**: 2026-07-09 23:09 **Notes**: * Kept real scan, War Room, channel, and generic failures quiet, rejected contradictory error/outcome toasts, and limited Quest ceremony to actionable cards. * Added pending/resolved/duplicate decision vocabulary, no-reward normal dismissal, and a static hero awaiting-input treatment that does not create a second pulse. **Files Changed**: * `apps/web/src/lib/verbCeremony.ts` - repaired selectors and inert attributes. * `apps/web/tests/verbCeremony.test.ts` - added live-vocabulary regression matrices. **Verification**: * Command/check: direct Node selector probe plus `npm test -- apps/web/tests/verbCeremony.test.ts` * Result: PASS - failure inputs returned null and 18 focused tests passed. **BQC Fixes**: * Failure path completeness: failed, administrative, duplicate, and informational states stay quiet. * Contract alignment: Quest action combinations now follow live card action support. ### Task T007 - Harden bounded privacy redaction **Completed**: 2026-07-09 23:10 **Notes**: * Added normalized and Unicode-folded inspection, bounded inspection input, expanded terminal/channel labels, unified diffs, relative paths, commands, and secret forms. **Files Changed**: * `apps/web/src/lib/verbCeremony.ts` - hardened fail-closed text inspection. * `apps/web/tests/verbCeremony.test.ts` - added adversarial bypass regressions. **Verification**: * Command/check: direct Node privacy matrix and focused Vitest * Result: PASS - all raw, obfuscated, path, command, diff, token, and payload cases redacted. **BQC Fixes**: * Trust boundary enforcement: control and non-ASCII marker obfuscation no longer bypasses redaction. * Error information boundaries: terminal output and channel bodies cannot enter ceremony copy. ### Tasks T014, T015, and T016 - Expand contract regression coverage **Completed**: 2026-07-09 23:11 **Notes**: * Added exact tone, surface, attribute, asset, decision, selector-combination, malformed timestamp, no-claim, product-copy, and import-purity assertions. **Files Changed**: * `apps/web/tests/verbCeremony.test.ts` - strengthened all focused contract matrices. **Verification**: * Command/check: `npm test -- apps/web/tests/verbCeremony.test.ts` * Result: PASS - 1 file and 18 tests passed with expanded assertions. **BQC Fixes**: * Contract alignment: derived variants and fixed registry values now have regression evidence. ### Tasks T017 and T018 - Re-run final implementation gates **Completed**: 2026-07-09 23:15 **Notes**: * Re-ran the focused and adjacent pure-helper suites, package typecheck, repository formatting, repository lint, and session scope checks after all repairs. **Files Changed**: * `apps/web/src/lib/verbCeremony.ts` - final implementation verified. * `apps/web/tests/verbCeremony.test.ts` - final focused suite verified. **Verification**: * Command/check: focused plus adjacent Vitest suites * Result: PASS - 4 files and 40 tests passed. * Command/check: web typecheck, `npm run format:check`, and `npm run lint` * Result: PASS - TypeScript passed; Biome checked 796 formatted and 798 linted files. * UI product-surface check: N/A - no rendered UI changed; banned product copy is tested. * UI craft check: N/A - Session 01 remains pure TypeScript. **Next Task**: none - implementation is complete and ready for `creview`. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/specs/phase25-session01-ceremony-registry-and-test-harness/implementation-notes.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.