> 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/phase19-session01-protocol-and-events/spec.md).

# Session Specification

**Session ID**: `phase19-session01-protocol-and-events` **Phase**: 19 - Orchestration Command Center Execution **Status**: Not Started **Created**: 2026-06-26 **Package**: packages/protocol **Package Stack**: TypeScript

***

## 1. Session Overview

This session defines the shared Phase 19 orchestration contracts in `packages/protocol` before server managers, web stores, routes, or panels consume them. It expands the current queue, template, lineage, guarded-action, plan, permission, and WebSocket vocabulary into a command-center contract surface for campaigns, attention, executor capability, file intent, workpad, evidence, verification, handoff, diagnostics, channel command, and usage families.

The session is next because Phase 19 has no completed sessions and the phase PRD requires contract-first work before broad server or web implementation. The output keeps execution local-first and guarded: unsupported or future executor families get explicit capability states and compact unavailable results instead of ambiguous placeholders or product claims.

The current protocol package is type/helper oriented and has no Zod dependency. This plan follows the established package style: exported const vocabularies, TypeScript interfaces, fail-closed parser or guard helpers, compact REST aliases, WebSocket event interfaces, and Vitest type/runtime coverage.

***

## 2. Objectives

1. Add shared Phase 19 orchestration DTOs, vocabularies, parser helpers, and compact error envelopes in `packages/protocol`.
2. Add WebSocket event contracts for plan, task, attention, executor, hero lifecycle, execution, permission, file intent, workpad, evidence, verification, handoff, diagnostic, channel command, and usage updates.
3. Add REST request/response aliases for the planned command-center route families without implementing server behavior.
4. Preserve current guarded action, queue, template, and lineage compatibility while documenting the new contract ownership and unavailable-state semantics.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase18-session11-validation-documentation-and-handoff` - Phase 18 completed and archived the Quest Board suggestion parity baseline.

### Required Tools Or Knowledge

* Node 26.2.0+ and npm 11.16.0 workspace commands.
* Existing protocol modules: `packages/protocol/src/taskQueue.ts`, `packages/protocol/src/agentTemplates.ts`, `packages/protocol/src/lineage.ts`, `packages/protocol/src/guardedActions.ts`, `packages/protocol/src/plans.ts`, `packages/protocol/src/events.ts`, and `packages/protocol/src/rest.ts`.
* Existing protocol parser patterns from `packages/protocol/src/suggestions.ts`, `packages/protocol/src/notices.ts`, `packages/protocol/src/warroom.ts`, and guardrail modules.

### Environment Requirements

* Run from the repository root with dependencies installed.
* No hosted credentials, provider credentials, Cloudflare access, real executors, or server runtime is required.

***

## 4. Scope

### In Scope (MVP)

* Protocol consumers can import Phase 19 command-center DTOs and validators - add shared contracts and fail-closed helpers in `packages/protocol/src/orchestrationCommandCenter.ts`.
* Server and web consumers can type planned REST and WebSocket families - add compact event interfaces in `packages/protocol/src/events.ts` and REST aliases in `packages/protocol/src/rest.ts`.
* Current queue, template, lineage, and guarded-action consumers remain compatible - preserve existing exported names and add tests that current payloads still typecheck.
* Future executor and inbound command families expose explicit unavailable or capability states - document non-executing semantics and blocked payload boundaries in `packages/protocol/README_protocol.md`.

### Out Of Scope (Deferred)

* Server managers, persistence, routes, or WebSocket emitters - Reason: Session 02 owns server backbone wiring after contracts land.
* Web store reducers, API clients, or React panels - Reason: Session 03 owns web shell and store wiring after server route shapes exist.
* Family-specific file, git, terminal, container, remote, or hosted executors - Reason: Later sessions own concrete executor behavior after permission, audit, redaction, and diagnostic gates exist.
* New runtime dependency such as Zod in `packages/protocol` - Reason: current package conventions use pure TypeScript types, const vocabularies, guards, and parser helpers.

***

## 5. Technical Approach

### Architecture

Create one protocol-owned module, `packages/protocol/src/orchestrationCommandCenter.ts`, for Phase 19 command-center vocabulary and DTO ownership. Keep it framework-independent and dependency-free. Use exported const arrays for every vocabulary, interfaces for DTOs and REST/event payloads, and fail-closed parser helpers for external payload boundaries that later server and web code can reuse.

Wire the new event payloads into `packages/protocol/src/events.ts` as compact WebSocket snapshots or deltas. Broad update frames must avoid raw prompts, command bodies, diffs, terminal output, file contents, transcript text, provider payloads, tokens, broad absolute paths, and hosted account data. Detailed content belongs to later scoped local detail routes, not broad event frames.

Extend `packages/protocol/src/rest.ts` with typed aliases for future route contracts while keeping runtime implementation out of this package. Update `packages/protocol/src/index.ts` and `packages/protocol/README_protocol.md` so downstream packages import from `@factionos/protocol` rather than duplicating route, event, or domain shapes.

### Design Patterns

* Const vocabulary plus derived union: matches existing `taskQueue`, `guardedActions`, `suggestions`, and hosted guardrail modules.
* Fail-closed parser result: matches `SuggestionValidationResult` and Notice/War Room parser patterns while avoiding a new validation dependency.
* Compact event envelope: matches current queue, template, lineage, guarded-action, Notice Board, and Quest Board realtime contracts.
* Protocol-first ownership: follows `CONSIDERATIONS.md` guidance that shared route, event, REST, WebSocket, and domain types land in `packages/protocol` before package-specific behavior.

***

## 6. Deliverables

### Files To Create

| File                                                         | Purpose                                                                                                   | Est. Lines |
| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- | ---------- |
| `packages/protocol/src/orchestrationCommandCenter.ts`        | Phase 19 command-center DTOs, vocabularies, parser helpers, compact errors, and event/REST payload shapes | \~900      |
| `packages/protocol/tests/orchestrationCommandCenter.test.ts` | Runtime and type tests for new DTO families, validators, blocked payloads, and fixtures                   | \~500      |

### Files To Modify

| File                                            | Changes                                                                                                   | Est. Lines |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------- |
| `packages/protocol/src/events.ts`               | Import and union new compact WebSocket event interfaces                                                   | \~120      |
| `packages/protocol/src/rest.ts`                 | Add route family aliases and REST request/response types for Phase 19 planned surfaces                    | \~160      |
| `packages/protocol/src/index.ts`                | Export the new orchestration command-center module                                                        | \~2        |
| `packages/protocol/tests/events.test.ts`        | Cover new event families and compact/no-raw-field behavior                                                | \~140      |
| `packages/protocol/tests/rest.test.ts`          | Cover new REST aliases and capability/unavailable statuses                                                | \~120      |
| `packages/protocol/tests/orchestration.test.ts` | Preserve current queue, template, lineage, and guarded-action compatibility checks                        | \~80       |
| `packages/protocol/README_protocol.md`          | Document Phase 19 contract ownership, unavailable-state semantics, and actual orchestration module layout | \~140      |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Every Phase 19 DTO family named by the session stub has an exported type, vocabulary where needed, and parser or guard coverage.
* [ ] Every new WebSocket family has a typed compact event interface and is included in `ServerEvent`.
* [ ] Every planned command-center route family has typed REST request/response aliases or capability envelopes in `src/rest.ts`.
* [ ] Current guarded action, queue, template, and lineage protocol tests still compile and pass.
* [ ] README documentation names the new contracts, owning surfaces, compatibility boundaries, and unavailable-state semantics.

### Testing Requirements

* [ ] Unit tests written and passing for new vocabularies, parsers, fixtures, REST aliases, event unions, and compatibility behavior.
* [ ] `npm --workspace packages/protocol run typecheck` passes.
* [ ] Focused protocol Vitest coverage passes for orchestration command center, events, REST, and orchestration compatibility tests.

### Non-Functional Requirements

* [ ] New broad WebSocket and REST snapshot shapes do not expose raw prompts, command bodies, diffs, terminal output, file contents, transcript text, secrets, tokens, broad absolute paths, provider payloads, or hosted account data.
* [ ] New contract helpers fail closed for unknown enum values, malformed IDs, absolute paths, traversal paths, URL-like paths, and oversized compact fields.
* [ ] No new runtime dependency is added to `packages/protocol`.

### Quality Gates

* [ ] All files ASCII-encoded
* [ ] Unix LF line endings
* [ ] Code follows project conventions
* [ ] Protocol package remains framework-independent

***

## 8. Implementation Notes

### Working Assumptions

* The selected package context is `packages/protocol`: the candidate stub declares that package, the Phase 19 PRD requires contract-first work, and `CONSIDERATIONS.md` says protocol leads cross-package route, event, REST, WebSocket, and domain changes. Planning can proceed without user arbitration because no other ready Phase 19 session has an earlier dependency position.
* `packages/protocol` should keep its existing dependency-free validation style: `package.json` has no Zod dependency and existing modules use const vocabularies plus guards/parsers. The PRD term "validators" is implemented as pure parser and guard helpers unless a later implementation proves a package-level schema dependency is already accepted.
* `packages/protocol/src/orchestration.ts` is not present even though the README names it. The session should preserve the actual current split (`taskQueue`, `agentTemplates`, `lineage`, `guardedActions`) and update README wording while adding the new Phase 19 module.

### Conflict Resolutions

* The phase PRD says execution is in scope for Phase 19, while the master PRD and security posture keep real executors deferred unless permission, audit, redaction, tests, docs, and unavailable states exist. This session resolves the conflict by adding contracts and capability states only; no real executor behavior or shipped execution claim is added.
* Existing plan events can include prompt-bearing `Plan` payloads, while Phase 19 requires broad command-center surfaces to avoid leaking sensitive developer data. New broad event payloads will use compact summary shapes and blocked-payload labels; existing compatibility events are preserved without expanding their use.

### Key Considerations

* `EXAMPLES/` is evidence only and must not be imported, copied, transformed, or shipped.
* Protocol types should be small, typed, and framework-independent.
* REST aliases in this package do not imply shipped routes until server sessions implement them.

### Potential Challenges

* Scope breadth: Mitigate by putting shared primitive contracts, status vocabularies, and compact snapshot shapes in one module while leaving manager behavior to later sessions.
* Event union size: Mitigate with grouped imported event interfaces and focused compile-time tests.
* Compatibility drift: Mitigate with tests that current queue, template, lineage, and guarded-action payloads still typecheck.
* Sensitive data exposure: Mitigate with explicit blocked payload labels, repo-relative path validation, compact event shapes, and tests that broad frames do not include raw fields.

### Relevant Considerations

* \[P03] **Real executors remain unimplemented by design**: This session defines capability and unavailable contracts but ships no real executor.
* \[P03-packages/protocol] **Protocol leads cross-package work**: Shared contracts are added before server and web implementation.
* \[P07] **Redaction is boundary-specific**: Event and REST summary shapes define blocked payload categories for future boundaries.
* \[P03-apps/server] **Local server boundary must stay conservative**: Future routes consume these contracts for validation, body limits, auth, and explicit unavailable behavior.
* \[P18-apps/web] **Pure normalization before store mutation**: Event payloads are designed for later pure web normalization before Zustand state changes.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Parser helpers accepting malformed or unknown payloads instead of failing closed.
* Broad REST/WebSocket shapes accidentally carrying sensitive local developer data.
* Typed-only future surfaces being mistaken for shipped server, web, hosted, or executor behavior.

***

## 9. Testing Strategy

### Unit Tests

* Test every vocabulary export and fail-closed parser helper in `packages/protocol/tests/orchestrationCommandCenter.test.ts`.
* Test representative valid and invalid fixtures for plan campaigns, attention, executor capability, execution runs, permission requests, file intents, workpad/evidence, verification, handoff, diagnostics, channel commands, and usage metrics.
* Test repo-relative path normalization rejects absolute paths, traversal, URL-like strings, backslashes, empty segments, and NUL bytes.

### Integration Tests

* Add compile-time and runtime smoke coverage in `packages/protocol/tests/events.test.ts` for every new compact WebSocket family included in `ServerEvent`.
* Add compile-time REST alias coverage in `packages/protocol/tests/rest.test.ts`.
* Extend `packages/protocol/tests/orchestration.test.ts` to prove existing queue, template, lineage, and guarded-action contracts remain compatible.

### Runtime Verification

* Run `npm --workspace packages/protocol run typecheck`.
* Run focused Vitest targets for protocol orchestration command center, events, REST, and orchestration compatibility tests.

### Edge Cases

* Unknown enum values, malformed IDs, oversized titles/summaries, non-finite metric values, stale expected revisions, duplicate idempotency keys, missing timestamps, unsupported capability states, absolute paths, traversal paths, URL-like paths, backslashes, NUL bytes, and raw-field attempts in compact event fixtures.

***

## 10. Dependencies

### Other Sessions

* Depends on: Phase 18 complete, Phase 19 PRD and Session 01 stub
* Depended by: `phase19-session02-server-backbone`, `phase19-session03-web-shell-and-store`, and later Phase 19 sessions that consume command-center DTOs, REST aliases, and event families

***

## Next Steps

Run the `implement` workflow step to begin implementation.


---

# 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/phase19-session01-protocol-and-events/spec.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.