> 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/phase06-session03-shared-collaboration-event-contracts/spec.md).

# Session Specification

**Session ID**: `phase06-session03-shared-collaboration-event-contracts` **Phase**: 06 - Collaboration, Isolation, and Mobile **Status**: Not Started **Created**: 2026-05-30 **Package**: Cross-package (`packages/protocol`, `apps/warroom`, `apps/web`) **Package Stack**: TypeScript, Cloudflare Workers, Durable Objects, React 18, Vite, Zustand, Vitest

***

## 1. Session Overview

This session hardens shared War Room collaboration event contracts after the Session 02 authority work. It keeps the optional Worker room relay limited to compact, allowlisted, sender-aware remote context: presence, cursor, focus, hero state, mission state, and room notices. It does not introduce hosted accounts, shared task queues, public replay hosting, analytics, remote execution, or trusted erasure.

The work starts in `packages/protocol`, where safe frame families, blocked payload categories, recent-event validation, and catch-up envelopes remain the shared source of truth. `apps/warroom` then consumes those contracts for socket ingest, persistence, sender-excluded broadcast, and bounded catch-up. `apps/web` uses the same contracts to build outbound frames and keep inbound remote context separate from local hero, mission, queue, replay, export, settings, adapter, scan, archive, memory, diagnostics, log, backup, and media state.

The result should make collaboration events visibly useful while failing closed for prompts, file contents, command bodies, terminal output, transcripts, secrets, broad paths, exports, replay buffers, scan payloads, media drafts, diagnostics, logs, backups, and quarantined historical content.

***

## 2. Objectives

1. Define explicit safe collaboration event and catch-up contracts for the current allowed frame families.
2. Harden Worker socket ingest, sender exclusion, persistence, and catch-up filtering around malformed, unsafe, unknown, oversized, and legacy frames.
3. Update web outbound and inbound collaboration handling so remote context remains compact, summarized, and separate from local source-of-truth state.
4. Add focused protocol, Worker, and web tests for allowlists, blocked fields, sender exclusion, catch-up minimization, and remote-context isolation.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase06-session01-collaboration-requirements-and-safety-baseline` - Provides the Phase 06 collaboration boundary, safe payload categories, blocked categories, and routing matrix.
* [x] `phase06-session02-room-authority-and-participant-identity-contracts` - Provides authority, participant, role, revision, and socket prerequisites for collaboration event handling.
* [x] `phase05-session05-federation-event-redaction-and-cockpit-integration` - Provides the existing safe-frame, sender-excluded federation baseline.

### Required Tools/Knowledge

* Node 20+ and npm workspaces.
* TypeScript 5.9, Vitest 4.1, React Testing Library, and package-local typecheck commands.
* Existing War Room contracts in `packages/protocol/src/warroom.ts`.
* Existing Worker socket and recent-event handling in `apps/warroom/src/index.ts`.
* Existing web federation helpers in `apps/web/src/lib/warRoomFederation.ts`.

### Environment Requirements

* Cloudflare credentials are optional and must not be required for focused tests.
* Tests must use local, mocked, or in-memory Worker paths.
* No raw prompts, command bodies, file contents, terminal output, transcripts, tokens, broad local paths, diagnostics, logs, backups, or historical `EXAMPLES/` content may be committed as fixtures.

***

## 4. Scope

### In Scope (MVP)

* Protocol consumers can rely on explicit safe collaboration event families - Keep presence, cursor, focus, hero state, mission state, room notice, ping, recent-event, remote-event, and catch-up validation protocol-owned.
* Worker rooms can reject unsafe socket frames before persistence or broadcast - Validate unknown fields, invalid enums, non-finite coordinates, blocked keys, sensitive string values, malformed participants, and non-persistable ping frames at the Worker boundary.
* Reconnecting participants can receive bounded minimized catch-up - Revalidate stored events, cap event count, preserve deterministic ordering, and drop unsafe legacy entries before browser consumption.
* Browser state can consume remote context safely - Build outbound frames from safe IDs and labels only, merge inbound frames into dedicated remote context, summarize counts and family labels, and prune local or absent participants.
* Documentation readers can understand safe collaboration payload limits - Update package README files and stable docs with allowed families, blocked categories, and Phase 07/08 deferrals.

### Out of Scope (Deferred)

* New hosted identity, account-backed collaboration, hosted storage, analytics, public replay hosting, push, production-hosted validation, or trusted erasure
  * Reason: Phase 07/08 own hosted and release hardening work.
* Raw shared task queues, guarded-action payload sharing, proposal rationale, assistant text, handoff transcript sharing, or broad mission details - Reason: Current routing permits only compact safe context, not raw local workflow data.
* File, git, terminal, Docker, remote, Worker command execution, inbound chat commands, or hosted queues - Reason: Session 05 owns isolation posture and future executor threat models.
* Full collaborative cockpit UX redesign or mobile certification - Reason: Sessions 04 and 06 own user-facing collaboration UX and mobile/accessibility hardening.

***

## 5. Technical Approach

### Architecture

`packages/protocol` remains the contract boundary. This session should refine safe frame constants, blocked-key and sensitive-value checks, recent-event validation, catch-up envelopes, and family summary helpers there before Worker or web consumers rely on changed behavior.

`apps/warroom` remains the optional room relay. The Worker should accept only authority-validated socket participants, parse each client frame through the protocol, persist only safe frames, exclude the sender from remote broadcasts, and revalidate catch-up events before storage and before delivery.

`apps/web` remains the local source-of-truth owner. Web helpers may send presence, focus, hero, mission, cursor, and notice frames, but inbound remote context must stay in dedicated remote-context state and UI summaries. It must not mutate local heroes, missions, queues, guarded actions, replay, exports, notifications, settings, adapters, scans, archives, memory, diagnostics, logs, backups, or media records.

### Design Patterns

* Protocol-first contracts: Shared collaboration event shapes and validators lead Worker and web changes.
* Fail-closed validation: Unknown frame types, unknown fields, malformed IDs, invalid enums, blocked keys, and sensitive values are rejected or dropped before persistence, catch-up, logs, diagnostics, or browser state.
* Sender-excluded relay: Remote event broadcast continues to skip the sender.
* Dedicated remote state: Remote context is merged into separate browser state and summarized by counts and family labels instead of raw payloads.
* Bounded replay: Catch-up remains a capped ring buffer with revalidation and deterministic ordering.

### Technology Stack

* TypeScript 5.9 shared contracts and tests in `packages/protocol`.
* Cloudflare Workers, Durable Objects, WebSocket, and Wrangler 4.x in `apps/warroom`.
* React 18.3, Vite 6.4, Zustand 4.5, browser WebSocket APIs, and React Testing Library in `apps/web`.
* Vitest 4.1 for focused protocol, Worker, and web tests.
* Biome and package-local `tsc` typechecking for quality gates.

***

## 6. Deliverables

### Files to Create

| File                                                                                                | Purpose                                                 | Est. Lines |
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ---------- |
| `.spec_system/specs/phase06-session03-shared-collaboration-event-contracts/implementation-notes.md` | Implementation evidence, command results, and decisions | \~120      |
| `.spec_system/specs/phase06-session03-shared-collaboration-event-contracts/security-compliance.md`  | Session security and privacy review                     | \~100      |

### Files to Modify

| File                                       | Changes                                                                                                           | Est. Lines |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- | ---------- |
| `packages/protocol/src/warroom.ts`         | Refine safe collaboration frame, recent-event, catch-up, blocked-field, and sensitive-value contracts             | \~180      |
| `packages/protocol/tests/warroom.test.ts`  | Add protocol coverage for allowlists, blocked fields, invalid enums, sensitive values, ping, and catch-up parsing | \~180      |
| `packages/protocol/README_protocol.md`     | Document collaboration event ownership and blocked payload categories                                             | \~50       |
| `apps/warroom/src/index.ts`                | Harden socket ingest, recent-event persistence, sender-excluded broadcast, and catch-up filtering                 | \~180      |
| `apps/warroom/tests/warroom.test.ts`       | Add Worker tests for sender exclusion, malformed frames, blocked payloads, legacy unsafe catch-up, cap, and ping  | \~220      |
| `apps/warroom/README_warroom.md`           | Document Worker collaboration event behavior and catch-up limits                                                  | \~50       |
| `apps/web/src/lib/warRoomClient.ts`        | Tighten server socket frame parsing, safe send failure mapping, and remote-event validation                       | \~100      |
| `apps/web/src/lib/warRoomFederation.ts`    | Refine outbound frame building, inbound merge, summaries, pruning, and label scrubbing                            | \~180      |
| `apps/web/src/store/useWarRoomStore.ts`    | Keep remote context isolated during sends, catch-up, reconnect, participant changes, leave, and reset             | \~160      |
| `apps/web/src/components/WarRoomPanel.tsx` | Keep collaboration summary accessible and free of raw payload wording                                             | \~60       |
| `apps/web/tests/warRoomClient.test.ts`     | Add socket frame send/receive safety and failure mapping tests                                                    | \~120      |
| `apps/web/tests/warRoomFederation.test.ts` | Add outbound, inbound, catch-up, pruning, sensitive label, and summary tests                                      | \~180      |
| `apps/web/tests/warRoomStore.test.ts`      | Add store tests for remote context isolation, catch-up minimization, and duplicate send guards                    | \~160      |
| `apps/web/tests/WarRoomPanel.test.tsx`     | Add visible summary tests for safe family labels and no sensitive payloads                                        | \~100      |
| `apps/web/README_web.md`                   | Document browser remote-context separation and non-hosted collaboration limits                                    | \~60       |
| `docs/api/README_api.md`                   | Document safe collaboration frames, socket errors, and catch-up limits                                            | \~80       |
| `docs/privacy-and-security.md`             | Update transfer boundary and blocked collaboration data categories                                                | \~80       |
| `docs/runbooks/war-room-operations.md`     | Add operational guidance for blocked frames, catch-up, and non-erasure limits                                     | \~60       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Collaboration events are compact, typed, redacted, bounded, and explicitly allowlisted.
* [ ] Unknown, malformed, blocked, oversized, or sensitive frames fail closed before persistence, catch-up, diagnostics, logs, or browser state.
* [ ] Sender-excluded broadcast behavior is preserved for remote events.
* [ ] Catch-up is capped, deterministic, and revalidated before browser consumption.
* [ ] Remote context remains visibly collaborative but cannot mutate local source-of-truth state.
* [ ] UI and docs do not imply hosted identity, hosted storage, analytics, public replay hosting, remote execution, mobile certification, or trusted erasure.

### Testing Requirements

* [ ] Protocol tests cover safe frame parsing, blocked categories, sensitive values, recent events, and catch-up envelopes.
* [ ] Worker tests cover socket ingest, sender exclusion, malformed frames, blocked fields, ping, capped catch-up, and legacy unsafe event filtering.
* [ ] Web tests cover outbound frame redaction, inbound remote-context merge, catch-up summaries, pruning, duplicate send guards, and visible summaries.
* [ ] Focused package typechecks pass for protocol, Worker, and web packages.
* [ ] Manual implementation notes record command results and residual risks.

### Non-Functional Requirements

* [ ] Collaboration payloads remain bounded by existing participant, label, notice, and recent-event caps.
* [ ] Error envelopes and summaries do not echo raw request bodies, tokens, URLs, paths, prompts, command output, diagnostics, logs, exports, replay buffers, or media drafts.
* [ ] Core local cockpit workflows remain usable with no Worker URL, no Cloudflare credentials, no hosted account, no analytics, and no public replay hosting.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] `npm --workspace packages/protocol run typecheck` passes.
* [ ] `npm --workspace @factionos/warroom run typecheck` passes.
* [ ] `npm --workspace @factionos/web run typecheck` passes.
* [ ] Focused War Room-related Vitest coverage passes.

***

## 8. Implementation Notes

### Key Considerations

* Preserve the Session 02 authority model; collaboration frames should assume socket participants already passed room-local authority checks.
* Use current safe frame families unless the Phase 06 routing matrix is updated with source-backed evidence. Do not add raw handoff, queue, transcript, or diagnostic frames by implication.
* Treat remote context as a visual collaboration overlay only. Local state remains the source of truth.
* Keep Worker diagnostics and browser summaries compact: counts, timestamps, safe family labels, and visible status, not raw event payloads.

### Potential Challenges

* Existing code already has partial safe-frame behavior: Refine and centralize contracts without duplicating validators across packages.
* Catch-up can contain legacy unsafe events: Revalidate stored events and drop unsafe entries before delivery or browser merge.
* Tests may need in-memory Worker helpers: Reuse existing `WarRoom` and mock WebSocket test patterns instead of requiring Cloudflare credentials.

### Relevant Considerations

* \[P05] **Redaction is boundary-specific**: This session must keep Worker, browser, diagnostics, replay, export, archive, backup, and log boundaries separate instead of treating Worker-safe as globally share-safe.
* \[P03-packages/protocol] **Protocol leads cross-package work**: Safe collaboration event contracts should be updated before Worker or web consumers rely on them.
* \[P05-apps/warroom+apps/web] **War Room federation is optional and redacted**: The Worker remains optional external transfer and must degrade cleanly when absent or unavailable.
* \[P05] **Unified erasure still missing**: Leave, reset, disconnect, catch-up pruning, or blocked-frame cleanup must not be described as trusted erasure.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Unsafe local developer data could cross the Worker boundary through a new or malformed frame.
* Remote catch-up could replay stale or unsafe legacy entries after reconnect.
* Remote context could accidentally overwrite local source-of-truth state or surface raw payload details in UI summaries.

***

## 9. Testing Strategy

### Unit Tests

* Add protocol tests for allowed frame families, invalid enum values, unknown fields, sensitive values, blocked nested keys, ping persistence behavior, recent-event validation, and catch-up envelope parsing.
* Add web helper tests for outbound redaction, inbound merge, catch-up summaries, stale participant pruning, and sensitive label scrubbing.

### Integration Tests

* Extend Worker tests for socket message parsing, blocked frame errors, sender-excluded remote broadcasts, capped recent-event catch-up, ping non-persistence, and legacy unsafe event filtering.
* Extend web store/client tests for connected socket send behavior, incoming `remote_event` and `warroom_pending_catchup` handling, reconnect cleanup, and duplicate federation send guards.

### Manual Testing

* Review the War Room panel summary copy and docs to confirm they describe redacted optional Worker transfer without implying hosted identity, public sharing, remote execution, or trusted erasure.

### Edge Cases

* Unknown frame type, unknown fields, blocked nested keys, URL/path/token-like text, non-finite coordinates, invalid participant IDs, ping frames, sender reconnect, absent participants, local participant events, stale catch-up, send failures, and Worker-unavailable state.

***

## 10. Dependencies

### External Libraries

* TypeScript: `^5.9.3`
* Vitest: `^4.1.7`
* React: `18.3.1`
* Zustand: `^4.5.4`
* Wrangler: `^4.95.0` at the root and `^4.94.0` in `apps/warroom`

### Other Sessions

* **Depends on**: `phase06-session01-collaboration-requirements-and-safety-baseline`, `phase06-session02-room-authority-and-participant-identity-contracts`
* **Depended by**: `phase06-session04-collaborative-cockpit-ux-and-remote-context`, `phase06-session07-collaboration-isolation-and-mobile-validation-closeout`

***

## Next Steps

Run the implement workflow step to begin AI-led 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/phase06-session03-shared-collaboration-event-contracts/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.