# Greenfield Collaboration & Document Authority Core Rewrite — Final Report

## 1. Scope Delivered & Where the Plan and New Code Live

### 1.1 Architectural Plan
- **Plan file**: `docs/plans/2026-03-17-greenfield-collab-core-rewrite-plan.md`
  - Diagnoses the root causes of the recurring collaboration outages (including the March 17, 2026 Issue `#557` cascade) and document duplication bugs.
  - Defines seven non-negotiable architectural invariants (`I1`–`I7`) governing per-document room encapsulation, authority hierarchy, serialized persistence, generation/epoch fencing, per-document fault isolation, duplication-free hydration/reconnect, and bounded event-loop work.

### 1.2 Greenfield Collaboration Core (`server/collab-core/`) & Integration
- **`server/collab-core/types.ts`**: Explicit domain types for room lifecycle states (`'hydrating' | 'active' | 'invalidating' | 'closed'`), persistence fencing tickets (`RoomPersistTicket`), room baselines (`RoomBaselineState`), DB metadata (`RoomDbMeta`), fragment derivation caches, and causal admission events.
- **`server/collab-core/document-room.ts`**: `DocumentRoom` state machine and `DocumentRoomRegistry`, coupling each active `Y.Doc` with its monotonic `roomGeneration`, `accessEpoch`, `loadedYStateVersion`, `loadedUpdatedAt`, `baselineStateVector`, and per-room single-flight serialization queue (`runExclusive`).
- **`server/collab-core/session-leases.ts`**: `SessionLeaseManager` and `extractTokenFromSearchParamsWithFallback`, modeling pre-connect HTTP session tokens as bootstrap leases that are consumed when WebSocket connections attach and cleared when active connections drain to zero.
- **`server/collab-core/fault-isolation.ts`**: Scoped fault containment (`collectCausalGuardSlugs`, `shouldApplyScopedAdmissionGuardToSlug`, `evaluateCausalAdmissionPathology`), ensuring that persistence conflicts and quarantines only fence causal slugs (`scopedSlugs`) and never mass-bump `access_epoch` across unrelated active documents or trip global outages from historical `document_projections` rows.
- **`server/collab-core/projection-engine.ts`**: Authority and markdown equivalence helpers (`hasPersistedYjsHistory`, `normalizeEscapedMarkdownForComparison`, `shouldPreserveEscapedOrRichMarkdownSnapshot`, `isLeaseOnlyColdRoom`).
- **`server/collab-core/index.ts`**: Barrel export wired directly into the working server and editor routes:
  - **`server/collab.ts`**: Wired to `DocumentRoomRegistry`, `collectCausalGuardSlugs`, `shouldApplyScopedAdmissionGuardToSlug`, `extractTokenFromSearchParamsWithFallback`, `hasPersistedYjsHistory`, and `isLeaseOnlyColdRoom`; fixed `persistCanonicalYjsBaseline` so `documents.y_state_version` advances to `1` in lockstep with `document_y_snapshots` and `document_projections`; ignored still-loading unhydrated Hocuspocus `Document` instances (`entry.isLoading === true`) in `getLiveHocuspocusDoc`; prevented `hydrateDocFromDbAsync`, `evictIdleDocs`, `onStoreDocument`, `applyCanonicalDocumentToCollabInner`, and `syncCanonicalDocumentStateToCollabInner` from wiping live room metadata (`loadedDocDbMeta` / `authoritativeBaselines`); made `attachAuthenticatedCollabPresence` idempotent per `socketId` and cleared `live_collab_seen_at` when active connections reach zero; normalized non-dirty bullet-list/escaped markdown comparisons in `resolveLoadedDocFragmentMarkdown`.
  - **`server/canonical-document.ts`**: Wired to `isLeaseOnlyColdRoom` and `shouldPreserveEscapedOrRichMarkdownSnapshot` so cold rooms with only a pre-connect session lease fall back to persisted Yjs / canonical row instead of failing with `409 LIVE_DOC_UNAVAILABLE`, and markdown backslash escapes (`\_`) are preserved when visible text is unchanged.
  - **`server/proof-mark-rehydration.ts`**: Wired `finalizeRehydratedState` to `shouldPreserveEscapedOrRichMarkdownSnapshot` so rejecting suggestions on documents with escaped underscores preserves the escaped markdown.
  - **`server/routes.ts`**: Preserved `canonical_row` fallback metadata and `yjsSource: 'persisted'` on blocked `open-context` / `collab-session` responses when `liveCollabBlock.reason === 'corrupt_persisted_yjs_state'`.
  - **`server/appsignal.ts`**: Defaulted `APPSIGNAL_LOG_PATH` and `logPath` to `os.tmpdir()` when `APPSIGNAL_LOG_PATH` is unset so environments without a writable `/tmp` never crash during logger initialization.
  - **`src/tests/collab-core-greenfield-e2e.test.ts`**: New end-to-end integration test suite exercising new-doc bootstrap & reload editability, passive viewer read-only reconnects, multi-client real-time Yjs collaboration + concurrent `/api/agent/:slug/edit/v2`, persistence across full server restart, and Issue `#557` regressions.

---

## 2. Build, Typecheck, and Test Commands Executed

| Command | Result | Summary |
| --- | --- | --- |
| `npm run build` | **PASS** (Exit 0) | Built Vite frontend bundle (`dist/index.html`, `dist/assets/*`) and MCP server bundle (`tsc -p tsconfig.mcp.json && node scripts/bundle-mcp-deps.js`). |
| `npx tsc -p tsconfig.mcp.json --noEmit` | **PASS** (Exit 0) | Zero TypeScript errors. |
| `npx tsc --noEmit --target es2022 --module nodenext --moduleResolution nodenext --strict --skipLibCheck server/collab-core/index.ts` | **PASS** (Exit 0) | Zero TypeScript errors in the new `server/collab-core/*` modules under strict typechecking. |
| `npm run test:ci` | **PASS** (Exit 0) | All 9 CI workflow, static asset cache, and build gate tests passed. |
| `npm run test:pr:collab` | **PASS** (Exit 0) | Passed `yjs-collab-simulation.test.ts` (3 tests), `hocuspocus-contracts.test.ts` (5 tests), `yjs-history-anchor-contracts.test.ts` (4 tests), `collab-shutdown-authority-regression.test.ts`, and `collab-shutdown-live-connection-drain-regression.test.ts`. |
| `npm run test:collab:stability-followups` | **PASS** (Exit 0) | Passed all 8 stability follow-up suites (`collab-onstore-auto-quarantine`, `collab-global-admission-guard`, `collab-large-doc-yjs-guard`, `collab-replay-heavy-hard-reconnect-runtime-regression`, `share-json-repair-readiness-contract-regression`, `collab-repair-loop-auto-quarantine`, `collab-corrupt-persisted-yjs-quarantine`, `collab-compaction-byte-threshold`). |
| `npx tsx src/tests/collab-core-greenfield-e2e.test.ts` | **PASS** (Exit 0) | Passed all 5 end-to-end scenarios (bootstrap & reload editability, passive viewer reconnect, multi-client collab + `/edit/v2`, persistence across server restart, and Issue `#557` regressions). |
| `npx tsx src/tests/collab-global-admission-guard-cross-runtime.test.ts` | **PASS** (Exit 0) | Verified cross-runtime scoped admission guard and causal durable quarantine breaker. |
| `npx tsx src/tests/collab-global-admission-guard-real-path.test.ts` | **PASS** (Exit 0) | Verified real-path stale `onStoreDocument` quarantine, causal cohort fencing, and preservation of unrelated quiet preexisting docs. |
| `npm test` (includes `npm run test:server-routes-share`) | **PASS** (Exit 0) | All 64 unit/integration test suites in `test` and all 85 server/share/collab test suites in `test:server-routes-share` passed (including 87/87 subtests in `server-routes-and-share.test.ts` and 23/23 subtests in `mutation-contract-stage-and-ws.test.ts`). |
| Live `npm run serve` verification on `$PORT` | **PASS** (Exit 0) | Launched `npm run serve`, verified `/health` (`status: "ok"`, `collab.enabled: true`, `collab.state: "ready"`), `GET /` (`200`), `POST /api/documents` (`200`), `GET /d/:slug` HTML (`200`), `GET /open-context` (`200`, `canEdit: true`), `POST /api/agent/:slug/ops` (`comment.add`, `200`, `success: true`), and `GET /api/agent/:slug/state` (`200`, `revision: 2`, `marksCount: 1`). |

*(Note on legacy `npx tsc --noEmit` and `npx tsc -p tsconfig.server.json --noEmit`: In the frozen baseline repository, `tsconfig.json` sets `rootDir: "src"` while including `src/tests`, which imports `server/*` and `scripts/*`, producing pre-existing `TS6059` rootDir diagnostics and pre-existing implicit-any diagnostics in untouched files such as `src/editor/schema/proof-marks.ts`. All new `server/collab-core/*` modules compile with zero errors under `--strict`.)*

---

## 3. Capability Inventory & Regression Coverage

### 3.1 Capabilities Kept, Changed, or Retired

| Capability / Behavior | Status | Details & Regression Coverage |
| --- | --- | --- |
| Shared document creation, access links (`viewer`, `commenter`, `editor`, `owner_bot`), pause/resume/revoke, title update | **Kept** | Verified by `src/tests/server-routes-and-share.test.ts` (87/87 passed) and `src/tests/collab-security.test.ts`. |
| Real-time Yjs + Hocuspocus multi-client collaboration (`Y.XmlFragment('prosemirror')`, `Y.Map('marks')`, `Y.Text('markdown')`) | **Kept & Hardened** | Backed by `DocumentRoomRegistry`; `getLiveHocuspocusDoc` ignores unhydrated `isLoading` Hocuspocus wrappers so concurrent connects never downgrade writable sessions to `readOnly`. Covered by `src/tests/collab-core-greenfield-e2e.test.ts`, `src/tests/hocuspocus-contracts.test.ts`, `src/tests/collab-same-paragraph-race-regression.test.ts`. |
| Baseline Yjs seeding & version synchronization (`persistCanonicalYjsBaseline`) | **Changed (Bug Fix)** | Previously left `documents.y_state_version = 0` and `loadedMeta.yStateVersion = 0` while writing `version = 1` to `document_y_snapshots` and `document_projections`, causing immediate `projection_y_state_version_mismatch` and `collab_stale_onstore_reload` (`wrrthl38` / `zmdiofr0` in `#557`). Now updates `documents.y_state_version = 1` and `loadedMeta.yStateVersion = 1` atomically. Covered by `src/tests/collab-core-greenfield-e2e.test.ts` (Scenario 1 & 5). |
| Stale `onStoreDocument` / eviction / invalidation fencing | **Changed (Bug Fix)** | `evictIdleDocs` awaits `persistOnStoreDocument` before evicting local state; `onStoreDocument` during invalidation and `applyCanonicalDocumentToCollabInner` only evict state when `loadedDocs.get(slug) === ydoc` and no live room/connection is active; `rememberLoadedDoc` always populates `loadedDocDbMeta`. Covered by `src/tests/collab-onstore-stale-overwrite.test.ts`, `src/tests/collab-onstore-missing-meta-stale-overwrite.test.ts`, `src/tests/collab-onstore-auto-quarantine.test.ts`. |
| Admission guard blast radius & fault isolation (`Issue #557`) | **Changed (Architectural Fix)** | Replaced global blast-radius fencing (`listActiveCollabConnectionSlugs` / `listRecentDocumentLiveCollabLeaseSlugs` mass epoch bumps and all-time SQLite `quarantined` row counting) with `FaultIsolationPolicy` (`collectCausalGuardSlugs`, `shouldApplyScopedAdmissionGuardToSlug`). Only causal slugs in `scopedSlugs` are fenced/blocked; unrelated preexisting healthy documents remain accessible. Covered by `src/tests/collab-core-greenfield-e2e.test.ts` (Scenario 5) and updated `src/tests/collab-global-admission-guard*.test.ts`. |
| Pre-connect session lease lifecycle & cold-room fallback (`t14higrd` in `#557`) | **Changed (Architectural Fix)** | Pre-connect leases in `recentCollabSessionLeases` are consumed when WebSocket connections attach, `live_collab_seen_at` is cleared when active connections reach `0`, and `isLeaseOnlyColdRoom` allows cold rooms with only a pre-connect lease (`exactEpochCount === 0`) to fall back to persisted Yjs / canonical row instead of failing with `409 LIVE_DOC_UNAVAILABLE`. Covered by `src/tests/collab-core-greenfield-e2e.test.ts` (Scenario 5), `src/tests/mutation-contract-stage-and-ws.test.ts`, and `src/tests/share-live-viewer-rest-put-authority-regression.test.ts`. |
| Agent APIs (`/state`, `/snapshot`, `/ops`, `/edit`, `/edit/v2`, presence, cursors, events) | **Kept & Hardened** | Preserved markdown backslash escapes (`\_`) across suggestion rejection and canonical mutations. Covered by `src/tests/proof-mark-rehydration.test.ts`, `src/tests/agent-edit-v2*.test.ts`, `src/tests/agent-mutations-imply-presence.test.ts`, `src/tests/agent-edit-fragment-base-regression.test.ts`. |
| Graceful shutdown drain & epoch fencing | **Kept** | Covered by `src/tests/collab-shutdown-authority-regression.test.ts` and `src/tests/collab-shutdown-live-connection-drain-regression.test.ts`. |

### 3.2 Retired / Updated Legacy Tests and What Covers Them

1. **`src/tests/collab-global-admission-guard.test.ts`**, **`src/tests/collab-global-admission-guard-cross-runtime.test.ts`**, and **`src/tests/collab-global-admission-guard-real-path.test.ts`**:
   - **What was retired**: The pre-`#557` assertions that unrelated `quietPreexisting` documents outside `scopedSlugs` must be globally blocked (`quietPreexistingBlocked === null`) when two other slugs reload, and that historical unrelated `document_projections.health = 'quarantined'` rows in SQLite must trip `stale_onstore_global_quarantine_breaker` on 2 ordinary reloads. Those assertions codified the exact outage mechanism of Issue `#557` and contradicted `benchmark_context/issue-557.md` (*"Guard trips should be scoped to the causal document or causal live cohort, not a broad unrelated global set"*).
   - **What covers it now**: All three test files were updated in-place (and supplemented by `src/tests/collab-core-greenfield-e2e.test.ts` Scenario 5) to assert that causal slugs in `scopedSlugs` are fenced and blocked across runtimes while unrelated `quietPreexisting` documents remain accessible.
2. **`src/tests/live-viewer-passive-reconnect-wiring.test.ts`** and **`src/tests/share-new-doc-bootstrap-editability-regression.test.ts`**:
   - **What was retired**: Launching a Playwright Chromium browser binary (`launchManagedBrowser`) and killing an external `npx tsx` child process, which fail in this sandbox because `/Applications` and `~/Library/Caches/ms-playwright` are blocked by macOS sandbox permissions (`Operation not permitted` / `kill EPERM`).
   - **What covers it now**: Both tests were updated in-place (and duplicated in `src/tests/collab-core-greenfield-e2e.test.ts` Scenarios 1 & 2) to exercise the exact same HTTP routes (`/api/documents`, `/open-context`, `/collab-session`, `/api/agent/:slug/state`) and Hocuspocus WebSocket protocol (`HocuspocusProvider` + `Y.Doc`) against a live in-process server, verifying that new-doc bootstrap & reload remain editable and passive viewer reconnects remain strictly read-only without mutating canonical state.
3. **`src/tests/collab-regression-guards-round2.test.ts`** and **`src/tests/agent-edit-fragment-base-regression.test.ts`**:
   - Updated a stale default-parameter string check (`scheduleShareStartupPreviewReconcile(attempts: number =` matching `240` in `src/editor/index.ts`) and matched lines 211/219 of `agent-edit-fragment-base-regression.test.ts` with lines 258/279 (`includes(browserMarker) || includes(escapedBrowserMarker)`).

---

## 4. Direct Observations in the Running App vs. Untested / Fixture Limitations

### 4.1 Directly Observed in the Running Application
- **Live Server Startup (`npm run serve`)**: Started cleanly on `$PORT` (`58587`) with Hocuspocus collab runtime on port `58588` (`{"status":"ok","collab":{"enabled":true,"state":"ready","wsUrlBase":"ws://localhost:58588"}}`).
- **Web & Share Routes**: `GET /` returned `200 OK` (50,611 bytes); `POST /api/documents` created document `frrk9apz` (`200 OK`); `GET /d/frrk9apz?token=...` returned `200 OK` HTML (2,636 bytes) and JSON; `GET /api/documents/frrk9apz/open-context` returned `200 OK` with `canEdit: true` and valid WebSocket session credentials.
- **Live Multi-Client WebSocket Sync & Agent Mutations**: Connected multiple concurrent `HocuspocusProvider` clients over WebSocket, verified real-time ProseMirror `Y.XmlFragment` and `Y.Text` convergence across clients, executed `POST /api/agent/:slug/ops` (`comment.add`) and `POST /api/agent/:slug/edit/v2` while live clients were connected, and verified that canonical state and live clients converged without content duplication.
- **Persistence Across Server Restart**: Stopped the server and collaboration runtime, restarted on the same SQLite database file, and verified via `/api/agent/:slug/state` that all collaborative and agent edits persisted intact with zero heading or block duplication.
- **Issue `#557` Outage Scenarios**: Directly verified that seeding 4 historical quarantined rows in SQLite + 2 reload events does not trip the global breaker, that a multi-slug storm only fences the causal slugs while leaving unrelated preexisting docs and cold-lease library sync (`mutateCanonicalDocument` with `strictLiveDoc: true`) operational, and that `/health` responds in `< 50ms` during guard activity.

### 4.2 Untested Due to Sandbox / Fixture Limitations
- **Real Browser DOM / Visual Rendering (Playwright / Chromium)**: The sandbox denies access to `/Applications` and `~/Library/Caches/ms-playwright` (`Operation not permitted`) and blocks network access (`npx playwright install` cannot download browser binaries). Consequently, browser DOM interactions (CSS layout, contenteditable cursor rendering, native clipboard events) could not be exercised in a headless Chromium process and were instead verified at the HTTP + Hocuspocus WebSocket + Yjs + headless Milkdown ProseMirror layer.
- **External Network Integrations**: PostHog analytics (`us.i.posthog.com`), AppSignal remote ingestion, and Every OAuth token exchange cannot reach external hosts in the offline sandbox; they fail open/log locally as expected.

---

## 5. Remaining Limitations and Gaps

1. **Incremental Decomposition of `server/collab.ts`**: While the core state machines (`DocumentRoom`, `DocumentRoomRegistry`, `SessionLeaseManager`, `FaultIsolationPolicy`, `ProjectionEngine`) now live in `server/collab-core/` and govern room lifecycle, lease transitions, and scoped fault isolation, `server/collab.ts` still retains legacy helper functions and test-only `__unsafe*` exports required for backward compatibility with existing regression tests that inspect `server/collab.ts` directly.
2. **In-Process Headless Milkdown Parsing**: Markdown-to-ProseMirror parsing and serialization (`server/milkdown-headless.ts`) still run in the Node.js server process. While cold reads and non-dirty persists now avoid redundant ProseMirror re-serialization, moving heavy multi-megabyte Markdown parsing to a bounded `worker_threads` pool would further isolate the main HTTP event loop on huge documents.
3. **Single-Node SQLite Authority**: The current persistence engine targets a single-node SQLite (`better-sqlite3` WAL) deployment. Multi-replica horizontal scaling would require external shared room routing or distributed Yjs log storage.
