docs(privacy): session-custody requirements checklist + gap analysis

[myselfsiddharth]

Closes #37.

Summary

docs/privacy/session-custody.md restates PRD §7's Fork-A session-custody requirements as six checkable rows (SC-01..SC-06) and audits the code at HEAD against each — citing file:function for every "enforced" claim and verifying it, not assuming it, per the issue's core ask.

Id	Requirement	Status
SC-01	Encrypted at rest, per-tenant keys	not addressed — no persistence mechanism exists at all yet
SC-02	Never written to trajectories	enforced by construction (one residual bypass gap)
SC-03	Never written to logs	conventional only — and empirically weaker than documented
SC-04	Excluded from compiler's input by construction	enforced by construction
SC-05	Explicit consent language	not addressed
SC-06	Documented ToS per anchor site	not addressed, currently inapplicable (no vertical locked, Track 1 is self-hosted)

Notable findings

• SC-02/SC-04 are genuinely solid. TrajectoryRecorder.toTrajectory() never serializes runtime bindings (only the type map), and additionalProperties: false closes every schema in the pipeline (trajectory → cache-row → assertion → metrics) — a cookie field isn't just unpopulated, it's invalid. Verified by walking the schemas directly, not by reading the doc comment.
• SC-03 has a real, verified hole. CONTRIBUTING.md claims "Secret-scanning CI fails the build on matches" for session/storage dumps. I built a synthetic (fake-valued) fixture shaped exactly like a real Playwright storageState() dump and ran it against all eight of secret-scan.mjs's patterns: zero matched. The existing patterns look for Set-Cookie: text or a "sessionid"-named key — not the cookies: [{name, value, domain, httpOnly, sameSite}] array shape Playwright actually produces. No real session material was used or committed anywhere in this process.
• The custody-vs-pooling distinction is stated explicitly, per the issue's ask: docs/privacy/boundary-spec.md's canary tests (verified by reading tests/canary/*.test.ts) seed fake account ids/names/thresholds and prove they don't reach the pool — that's a different boundary (cross-tenant leakage) with a different failure mode than custody (session material at rest anywhere, including tenant-scoped rows and logs).
• Track-1 relevance stated plainly: the gate authenticates to a local, self-hosted Grafana container with fixture credentials the project provisions itself — no real customer session, no third party. SC-05/SC-06 become required the moment anything targets a real account or a portal this project doesn't own.

Follow-up issues filed (linked from the doc's table)

• Encrypted-at-rest storage-state persistence, gated by a plaintext-write canary #98 — SC-01: encrypted-at-rest persistence gated by a plaintext-write canary
• Canary-test the TrajectoryRecorder.write() bypass + auto-discover trajectories for schema validation #99 — SC-02: close the toTrajectory() bypass gap + auto-discover trajectories for schema validation
• secret-scan.mjs does not catch a real Playwright storageState() shape #100 — SC-03: extend secret-scan.mjs to catch a real storageState() shape (with the empirical gap reproduced as a fixture)
• Pin the compiler/repair no-cookie guarantee with a tripwire test #101 — SC-04: tripwire test pinning the forbidden-key absence
• Design and ship explicit session-automation consent language (PRD §7) #102 — SC-05: product/legal — design and ship consent language
• Documented ToS position per anchor site — required before any paid pilot #103 — SC-06: product/legal — ToS position, gated on a vertical being locked

One-line fix taken inline

docs/architecture.md invariant 3 cited src/recorder/redact.ts:66-81 for assertNoLiteralSecrets; verified the function is actually at lines 102-117 at HEAD. Corrected, and bumped the doc's updated date.

Test plan

• npm run secret-scan — clean (had to reword three spots in the new doc that literally contained the trigger substring Set-Cookie: while describing the existing pattern — confirmed the fix empirically before and after)
• npm run test:canary — clean, confirms the canary still only tests the pooling boundary, not custody
• npm run lint:docs — clean (46 docs)
• npm run ci — clean (secret-scan, contracts, lint, typecheck, unit + integration)
• No real session material anywhere in the diff or in the follow-up issues — only synthetic, disposed-of fixtures used to verify claims empirically

Checklist (from the issue)

• Every PRD §7 requirement has a row and a status
• Every "enforced" claim cites a file and function and was verified, not assumed
• Custody vs pooling-allowlist distinction stated explicitly
• Follow-up issues filed for each gap and linked from the table
• No real session material anywhere in the diff
• docs/README.md privacy table row added
• Branch track1/b5-session-custody

🤖 Generated with Claude Code