> 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/archive/sessions/phase17-session01-protocol-notice-contract-parity/implementation-notes.md).

# Implementation Notes

**Session ID**: `phase17-session01-protocol-notice-contract-parity` **Package**: packages/protocol **Started**: 2026-06-05 19:06 **Last Updated**: 2026-06-05 19:24

***

## Session Progress

| Metric              | Value   |
| ------------------- | ------- |
| Tasks Completed     | 22 / 22 |
| Estimated Remaining | 0 hours |
| Blockers            | 0       |

***

## Task Log

### 2026-06-05 - Session Start

**Environment verified**:

* [x] Prerequisites confirmed for `.spec_system`
* [x] `packages/protocol` package context resolved
* [x] Local npm workspace available
* [x] Local Vitest binary available through `node_modules/.bin/vitest`
* [x] Directory structure ready

***

### Task T001 - Verify prerequisites and Notice Board evidence

**Started**: 2026-06-05 19:05 **Completed**: 2026-06-05 19:06 **Duration**: 1 minute

**Notes**:

* Verified active session state, Phase 17 Session 01 stub, Phase 17 PRD notice model, protocol README guidance, and ADR boundaries.
* Reviewed `EXAMPLES/package-0.4.1/server/dist/noticeBoardManager.js` as quarantined reference evidence only.

**Files Changed**:

* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/tasks.md` - marked T001 complete.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/implementation-notes.md` - recorded evidence.

**BQC Fixes**:

* N/A - setup and evidence review only.

***

### Task T002 - Verify protocol scripts and source layout

**Started**: 2026-06-05 19:06 **Completed**: 2026-06-05 19:07 **Duration**: 1 minute

**Notes**:

* Verified `packages/protocol/package.json`, source files, existing tests, and local Vitest availability.

**Files Changed**:

* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/tasks.md` - marked T002 complete.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/implementation-notes.md` - recorded evidence.

**BQC Fixes**:

* N/A - setup and source inventory only.

***

### Task T003 - Create notice contract test scaffold

**Started**: 2026-06-05 19:07 **Completed**: 2026-06-05 19:08 **Duration**: 1 minute

**Notes**:

* Created `packages/protocol/tests/notices.test.ts` and seeded compatibility shape coverage.

**Files Changed**:

* `packages/protocol/tests/notices.test.ts` - created focused notice contract test file.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/tasks.md` - marked T003 complete.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/implementation-notes.md` - recorded evidence.

**BQC Fixes**:

* N/A - test scaffold only.

***

### Task T004 - Define notice vocabularies

**Started**: 2026-06-05 19:08 **Completed**: 2026-06-05 19:10 **Duration**: 2 minutes

**Notes**:

* Added exported notice type, priority, author type, and severity vocabularies.
* Added union types and exhaustive severity derivation switch coverage.

**Files Changed**:

* `packages/protocol/src/notices.ts` - added canonical vocabularies and constants.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/tasks.md` - marked T004 complete.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/implementation-notes.md` - recorded evidence.

**BQC Fixes**:

* Contract alignment: exported vocabularies keep downstream packages synchronized.

***

### Task T005 - Expand Notice with canonical fields and aliases

**Started**: 2026-06-05 19:10 **Completed**: 2026-06-05 19:11 **Duration**: 1 minute

**Notes**:

* Expanded `Notice` with canonical Notice Board fields, room scope, resolution fields, related files, and author metadata.
* Preserved `body`, `targets`, `postedAt`, `severity`, and current local author compatibility fields.

**Files Changed**:

* `packages/protocol/src/notices.ts` - expanded notice models.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/tasks.md` - marked T005 complete.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/implementation-notes.md` - recorded evidence.

**BQC Fixes**:

* Contract alignment: canonical fields were added without breaking current alias consumers.

***

### Task T006 - Define Notice Board REST contracts

**Started**: 2026-06-05 19:11 **Completed**: 2026-06-05 19:12 **Duration**: 1 minute

**Notes**:

* Added canonical list, context, create, and resolve request/response contracts.
* Added compatibility list and create contracts for `/notices` and `/notice`.

**Files Changed**:

* `packages/protocol/src/notices.ts` - added REST contract types.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/tasks.md` - marked T006 complete.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/implementation-notes.md` - recorded evidence.

**BQC Fixes**:

* Contract alignment: route contracts separate canonical `/notice-board` and compatibility `/notice` payloads.

***

### Task T007 - Add notice enum guards and parsers

**Started**: 2026-06-05 19:12 **Completed**: 2026-06-05 19:12 **Duration**: 1 minute

**Notes**:

* Added boolean guards and explicit parser result helpers for type, priority, author type, and severity.

**Files Changed**:

* `packages/protocol/src/notices.ts` - added guard and parser helpers.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/tasks.md` - marked T007 complete.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/implementation-notes.md` - recorded evidence.

**BQC Fixes**:

* Trust boundary enforcement: invalid enum values fail closed at the shared protocol helper layer.

***

### Task T008 - Add bounded array helpers

**Started**: 2026-06-05 19:12 **Completed**: 2026-06-05 19:13 **Duration**: 1 minute

**Notes**:

* Added target session, tag, and related file normalizers.
* Helpers dedupe, sort deterministically, apply caps, and reject unsafe shapes.

**Files Changed**:

* `packages/protocol/src/notices.ts` - added bounded array helper behavior.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/tasks.md` - marked T008 complete.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/implementation-notes.md` - recorded evidence.

**BQC Fixes**:

* Trust boundary enforcement: related-file and target arrays reject malformed values before downstream use.

***

### Task T009 - Add severity and alias normalization helpers

**Started**: 2026-06-05 19:13 **Completed**: 2026-06-05 19:14 **Duration**: 1 minute

**Notes**:

* Added severity derivation across notice type and priority combinations.
* Added canonical and compatibility alias normalization for content, targets, timestamps, and event payload keys.

**Files Changed**:

* `packages/protocol/src/notices.ts` - added severity derivation and alias normalization helpers.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/tasks.md` - marked T009 complete.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/implementation-notes.md` - recorded evidence.

**BQC Fixes**:

* Contract alignment: compatibility payloads normalize into canonical keys without silently accepting invalid values.

***

### Task T010 - Update Notice Board server event payload keys

**Started**: 2026-06-05 19:14 **Completed**: 2026-06-05 19:15 **Duration**: 1 minute

**Notes**:

* Updated `notice_board_message` with canonical `notice` and compatibility `message`.
* Updated hydrate and resolution frames with canonical and compatibility payload keys.

**Files Changed**:

* `packages/protocol/src/events.ts` - expanded Notice Board event interfaces.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/tasks.md` - marked T010 complete.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/implementation-notes.md` - recorded evidence.

**BQC Fixes**:

* Contract alignment: canonical and recovered compatibility event payload keys are both typed.

***

### Task T011 - Update ClientPostNotice contract

**Started**: 2026-06-05 19:15 **Completed**: 2026-06-05 19:15 **Duration**: 1 minute

**Notes**:

* Expanded `ClientPostNotice` with canonical content, priority, author, target, room, related-file, and expiration fields.
* Preserved compatibility `body`, `severity`, and `targets`.

**Files Changed**:

* `packages/protocol/src/events.ts` - expanded client post contract.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/tasks.md` - marked T011 complete.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/implementation-notes.md` - recorded evidence.

**BQC Fixes**:

* Contract alignment: the WebSocket discriminator remains unambiguous through `noticeType`.

***

### Task T012 - Update REST exports

**Started**: 2026-06-05 19:15 **Completed**: 2026-06-05 19:16 **Duration**: 1 minute

**Notes**:

* Added REST aliases for canonical Notice Board list, context, create, and resolve contracts.
* Kept `NoticeCreateRequest` as the expanded compatibility `/notice` request.

**Files Changed**:

* `packages/protocol/src/rest.ts` - added Notice Board REST aliases and compatibility request mapping.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/tasks.md` - marked T012 complete.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/implementation-notes.md` - recorded evidence.

**BQC Fixes**:

* Contract alignment: REST contracts name canonical and compatibility notice surfaces separately.

***

### Task T013 - Add canonical and compatibility notice type tests

**Started**: 2026-06-05 19:16 **Completed**: 2026-06-05 19:16 **Duration**: 1 minute

**Notes**:

* Added tests for canonical vocabularies, `NoticeBoardNotice`, compatibility aliases, and request/response contracts.

**Files Changed**:

* `packages/protocol/tests/notices.test.ts` - added notice contract tests.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/tasks.md` - marked T013 complete.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/implementation-notes.md` - recorded evidence.

**BQC Fixes**:

* Contract alignment: tests assert old aliases and canonical fields remain available together.

***

### Task T014 - Add guard and parser failure tests

**Started**: 2026-06-05 19:16 **Completed**: 2026-06-05 19:17 **Duration**: 1 minute

**Notes**:

* Added guard and parser tests for invalid notice type, priority, author type, and severity values.
* Added compatibility event payload failure tests.

**Files Changed**:

* `packages/protocol/tests/notices.test.ts` - added fail-closed guard and parser coverage.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/tasks.md` - marked T014 complete.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/implementation-notes.md` - recorded evidence.

**BQC Fixes**:

* Trust boundary enforcement: tests prove invalid enum values and malformed compatibility payloads fail closed.

***

### Task T015 - Add bounded helper tests

**Started**: 2026-06-05 19:17 **Completed**: 2026-06-05 19:17 **Duration**: 1 minute

**Notes**:

* Added helper tests for target and tag bounds, duplicate handling, deterministic ordering, and unsafe related-file rejection.

**Files Changed**:

* `packages/protocol/tests/notices.test.ts` - added bounded helper coverage.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/tasks.md` - marked T015 complete.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/implementation-notes.md` - recorded evidence.

**BQC Fixes**:

* Trust boundary enforcement: tests assert unsafe file-path-like values are rejected.

***

### Task T016 - Add severity and alias normalization tests

**Started**: 2026-06-05 19:17 **Completed**: 2026-06-05 19:17 **Duration**: 1 minute

**Notes**:

* Added tests for severity derivation, critical priority override, compatibility alias normalization, and invalid aliases.

**Files Changed**:

* `packages/protocol/tests/notices.test.ts` - added severity and alias normalization coverage.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/tasks.md` - marked T016 complete.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/implementation-notes.md` - recorded evidence.

**BQC Fixes**:

* Contract alignment: tests ensure aliases normalize deterministically into canonical fields.

***

### Task T017 - Update event tests

**Started**: 2026-06-05 19:17 **Completed**: 2026-06-05 19:18 **Duration**: 1 minute

**Notes**:

* Added event tests for Notice Board message, hydrate, resolution, and expanded `post_notice` compatibility.

**Files Changed**:

* `packages/protocol/tests/events.test.ts` - added Notice Board event and client post coverage.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/tasks.md` - marked T017 complete.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/implementation-notes.md` - recorded evidence.

**BQC Fixes**:

* Contract alignment: tests prove realtime frames support both canonical and compatibility payload keys.

***

### Task T018 - Update REST type tests

**Started**: 2026-06-05 19:18 **Completed**: 2026-06-05 19:18 **Duration**: 1 minute

**Notes**:

* Added REST type tests for canonical Notice Board list, context, create, resolve, and compatibility `/notice`.

**Files Changed**:

* `packages/protocol/tests/rest.test.ts` - added Notice Board REST coverage.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/tasks.md` - marked T018 complete.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/implementation-notes.md` - recorded evidence.

**BQC Fixes**:

* Contract alignment: tests assert the canonical route family and legacy route remain typed.

***

### Task T019 - Update protocol README

**Started**: 2026-06-05 19:18 **Completed**: 2026-06-05 19:19 **Duration**: 1 minute

**Notes**:

* Added Phase 17 Notice Board ownership notes, downstream package order, compatibility aliases, and privacy/no-overclaim boundaries.

**Files Changed**:

* `packages/protocol/README_protocol.md` - added Notice Board contract ownership section.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/tasks.md` - marked T019 complete.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/implementation-notes.md` - recorded evidence.

**BQC Fixes**:

* Error information boundaries: README explicitly blocks raw sensitive payload categories from Notice Board boundaries.

***

### Task T020 - Run focused Vitest coverage

**Started**: 2026-06-05 19:19 **Completed**: 2026-06-05 19:19 **Duration**: 1 minute

**Notes**:

* Ran `npx vitest run packages/protocol/tests/notices.test.ts packages/protocol/tests/events.test.ts packages/protocol/tests/rest.test.ts`.
* Result: 3 files passed, 29 tests passed.

**Files Changed**:

* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/tasks.md` - marked T020 complete.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/implementation-notes.md` - recorded evidence.

**BQC Fixes**:

* N/A - verification task.

***

### Task T021 - Run protocol package typecheck

**Started**: 2026-06-05 19:19 **Completed**: 2026-06-05 19:20 **Duration**: 1 minute

**Notes**:

* Ran `npm --workspace packages/protocol run typecheck`.
* Result: passed.

**Files Changed**:

* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/tasks.md` - marked T021 complete.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/implementation-notes.md` - recorded evidence.

**BQC Fixes**:

* N/A - verification task.

***

### Task T022 - Validate ASCII, LF, and final evidence

**Started**: 2026-06-05 19:20 **Completed**: 2026-06-05 19:24 **Duration**: 4 minutes

**Notes**:

* Ran Biome format and lint checks for touched TypeScript files.
* Ran focused Vitest and protocol typecheck after formatting.
* Reran focused Vitest and protocol typecheck after the final parser hardening tweak.
* Validated touched files are ASCII-only and have LF line endings.
* Ran `git diff --check` for touched files.

**Files Changed**:

* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/tasks.md` - marked T022 complete.
* `.spec_system/specs/phase17-session01-protocol-notice-contract-parity/implementation-notes.md` - recorded final verification evidence.

**BQC Fixes**:

* N/A - verification task.

***

## Validation Evidence

* `npx vitest run packages/protocol/tests/notices.test.ts packages/protocol/tests/events.test.ts packages/protocol/tests/rest.test.ts` - passed, 3 files, 29 tests.
* `npm --workspace packages/protocol run typecheck` - passed.
* `npx biome format packages/protocol/src/notices.ts packages/protocol/src/events.ts packages/protocol/src/rest.ts packages/protocol/tests/notices.test.ts packages/protocol/tests/events.test.ts packages/protocol/tests/rest.test.ts` - passed, no fixes after write-format.
* `npx biome lint packages/protocol/src/notices.ts packages/protocol/src/events.ts packages/protocol/src/rest.ts packages/protocol/tests/notices.test.ts packages/protocol/tests/events.test.ts packages/protocol/tests/rest.test.ts` - passed.
* ASCII scan for touched files - passed.
* LF line ending scan for touched files - passed.
* `git diff --check -- [touched files]` - passed.

***

## Design Decisions

### Decision 1: Preserve old Notice aliases as required compatibility fields

**Context**: Current server and web code still create and consume `body`, `targets`, `postedAt`, `severity`, and local author fields.

**Options Considered**:

1. Make all canonical fields required directly on `Notice`.
2. Keep compatibility fields required on `Notice` and expose `NoticeBoardNotice` for fully canonical notices.

**Chosen**: Option 2.

**Rationale**: This keeps Session 01 protocol work source-compatible for later runtime sessions while still giving downstream code a stricter canonical type.

***

## Session Summary

* Expanded `packages/protocol/src/notices.ts` with Notice Board vocabularies, canonical and compatibility contracts, guards, parsers, bounded array normalizers, related-file safety checks, severity derivation, and alias normalization helpers.
* Updated `packages/protocol/src/events.ts` for canonical and compatibility Notice Board realtime payload keys and expanded `post_notice` fields.
* Updated `packages/protocol/src/rest.ts` for canonical `/notice-board` route contracts and the expanded compatibility `/notice` request.
* Added focused protocol tests and README ownership/privacy guidance.

Ready for the validate workflow step.


---

# 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/archive/sessions/phase17-session01-protocol-notice-contract-parity/implementation-notes.md?ask=<question>&goal=<endgoal>
```

`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.