> 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/phase08-session02-unified-erasure-contract-and-inventory/spec.md).

# Session Specification

**Session ID**: `phase08-session02-unified-erasure-contract-and-inventory` **Phase**: 08 - Release Hardening and Legacy Decommission **Status**: Not Started **Created**: 2026-05-31 **Package**: Cross-cutting **Package Stack**: TypeScript protocol contracts, server helpers, Worker helpers, release/security docs, and package README boundaries across `packages/protocol`, `apps/server`, `apps/warroom`, `apps/web`, `apps/cli`, `apps/hooks`, docs, and Phase 08 PRD artifacts

***

## 1. Session Overview

This session defines the shared trusted-erasure contract and release-scoped storage inventory that later Phase 08 sessions will consume. Session 01 established that FactionOS cannot claim trusted unified erasure until every relevant local, browser, Worker, archive, replay, export, diagnostic, backup, valid spool, workspace, and future hosted-state boundary has an owner, authority model, dry-run vocabulary, audit vocabulary, verification plan, and explicit unsupported-claim wording.

The work is protocol-led and cross-cutting. `packages/protocol` should own the common erasure vocabulary, inventory row shape, status labels, authority labels, dry-run and confirmation summary shapes, partial-failure vocabulary, audit entry shape, verification vocabulary, blocked payload labels, and negative-claim helpers before server, Worker, CLI, web, or docs describe erasure behavior. Server and Worker packages should add read-only mapping helpers that identify their owned boundaries without deleting data or exposing raw paths, tokens, room payloads, prompts, logs, backups, exports, replay buffers, or diagnostics.

This session must not perform destructive deletion or wire end-user CLI/web erasure controls. It creates the contract and inventory substrate for Session 03 local erasure runtime and Session 04 Worker erasure or no-claim gates.

***

## 2. Objectives

1. Add protocol-owned erasure vocabulary and types for storage boundaries, authority, dry-runs, confirmation, idempotency, partial failure, audit output, verification, blocked payloads, and unsupported claims.
2. Create a complete release-scoped storage-boundary inventory with owner, status, authority model, dry-run support, verification plan, and no-overclaim wording for every Phase 08 erasure boundary.
3. Add server and Worker mapping helpers that consume the protocol inventory and expose sanitized, read-only boundary summaries for later runtime work.
4. Add focused tests and docs proving one-boundary cleanup, browser reset, Worker leave, diagnostics recovery, uninstall, and manual file removal cannot be labeled trusted unified erasure.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase08-session01-release-requirements-and-risk-baseline` - provides release claim gates, requirement routing, risk ownership, and trusted-erasure no-claim wording.
* [x] `phase07-session07-hosted-guardrails-validation-and-documentation-closeout` - provides disabled, planned, and unavailable hosted-service guardrails plus Phase 08 erasure deferral.
* [x] `phase06-session07-collaboration-isolation-and-mobile-validation-closeout` - provides Worker authority, browser hint, leave/reset, and local-only UX boundaries.
* [x] `phase05-session07-war-room-validation-and-documentation-closeout` - provides optional Worker room relay, Durable Object persistence, safe frame, and catch-up boundaries.
* [x] `phase03-session06-cli-diagnostics-and-recovery-controls` - provides narrow local recovery, listener PID, log, and valid spool boundaries.

### Required Tools/Knowledge

* TypeScript contract patterns in `packages/protocol/src/hostedPersistence.ts`, `hostedOperations.ts`, `isolation.ts`, and `warroom.ts`.
* Current server archive, export, memory, diagnostic, backup, and local state helpers.
* Current Worker Durable Object participant, recent event, authority hash, and idempotency metadata shape.
* Current web browser localStorage, replay, settings, auth hint, and War Room hint behavior.
* Release docs, privacy/security docs, API docs, package READMEs, Phase 08 matrices, and active security finding `P06-S07-ERASURE`.

### Environment Requirements

* Node 20+ and npm workspaces installed.
* No Cloudflare, Supabase, Umami, VAPID, provider, hosted account, or production credential is required.
* Implementation and tests must not delete real local state, browser state, Worker state, logs, backups, exports, replay buffers, archives, or workspace files.
* Test fixtures must use temporary directories and synthetic values only.

***

## 4. Scope

### In Scope (MVP)

* Maintainers can use shared erasure vocabulary from `packages/protocol` - add types, const arrays, guards, summary builders, inventory rows, blocked payload labels, unsupported claims, and negative-claim helpers.
* Release reviewers can inspect one storage inventory - create a Phase 08 inventory artifact listing local, browser, Worker, archive, replay, export, diagnostic, backup, valid spool, workspace, and future hosted placeholders with owner, authority, dry-run, verification, and status.
* Server-owned boundaries are mapped without mutation - add read-only helper coverage for FactionOS home, archives, memory, settings, lifecycle files, project-root state, logs, backups, valid/malformed spool posture, exports, diagnostics, and scan/runtime memory.
* Worker-owned boundaries are mapped without mutation - add read-only helper coverage for Durable Object room participants, recent events, authority hashes, idempotency records, room revisions, and browser-hint adjacency.
* Docs distinguish cleanup from trusted erasure - update release, privacy/security, API, and package README wording so local reset, diagnostics recovery, CLI uninstall, Worker leave, browser cleanup, and one-boundary deletion remain non-erasure until later sessions prove the full workflow.

### Out of Scope (Deferred)

* Destructive deletion, purge, clear, or reset behavior - *Reason: Session 03 owns local/browser runtime deletion and Session 04 owns Worker erasure or no-claim behavior.*
* End-user CLI or web controls - *Reason: Session 03 owns preview, confirmation, progress, audit, verification, and visible failure UX.*
* Worker room deletion endpoint or Durable Object purge - *Reason: Session 04 owns Worker erasure authority and release gate behavior.*
* Active hosted account deletion, hosted storage deletion, public replay takedown, analytics deletion, push deletion, or remote cleanup - *Reason: hosted surfaces remain planned, disabled, unavailable, or later-scope unless a future accepted session activates them.*
* Production-hosted validation, certification evidence, media gate revalidation, or legacy decommission - *Reason: Sessions 05 through 07 own those release gates.*

***

## 5. Technical Approach

### Architecture

Use a protocol-first contract modeled after the existing hosted guardrail modules. `packages/protocol/src/erasure.ts` should export literal value arrays, TypeScript union types, inventory row interfaces, summary builders, lookup helpers, guard functions, blocked payload labels, unsupported claims, and negative-claim helpers. The contract should be pure and deterministic so package consumers can import it without runtime side effects.

The inventory should distinguish boundary families such as local files, local runtime memory, browser storage, Worker Durable Object storage, user-exported artifacts, backups, logs, diagnostics, workspace files, and future hosted placeholders. Each row should name the owner package or surface, current status, authority requirement, dry-run support, verification method, audit expectation, release-scope status, blocked payload categories, docs references, and a non-erasure warning where applicable.

Server and Worker helpers should be read-only adapters over the protocol contract. Server helpers should map known local state families without reading raw payload contents or emitting raw absolute paths. Worker helpers should map Durable Object persisted fields without returning raw authority tokens, room payloads, participant secrets, request bodies, client IPs, or event bodies. The helpers prepare later runtime sessions but do not execute deletion.

### Design Patterns

* Protocol-owned vocabulary: shared values start in `packages/protocol` before package-specific consumers use them.
* Inventory-as-contract: release-scoped storage boundaries live in one typed inventory, with package helpers deriving summaries from it.
* Negative-claim testing: tests assert cleanup-like operations are not trusted unified erasure.
* Boundary-specific redaction: previews, summaries, audits, and docs expose labels, counts, booleans, docs paths, and synthetic ids only.
* Deterministic summaries: dry-run and inventory summaries sort and count boundaries consistently so later idempotency tests have a stable baseline.

### Technology Stack

* TypeScript in `packages/protocol`, `apps/server`, and `apps/warroom`.
* Vitest root test runner with package-focused test files.
* Markdown docs and Phase 08 PRD artifact updates.
* Root quality gates: Biome, TypeScript, `git diff --check`, ASCII/LF scan.

***

## 6. Deliverables

### Files to Create

| File                                                     | Purpose                                                                                                                          | Est. Lines |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `packages/protocol/src/erasure.ts`                       | Shared erasure vocabulary, inventory contracts, summary builders, guards, and negative-claim helpers                             | \~320      |
| `packages/protocol/tests/erasure.test.ts`                | Protocol tests for vocabulary uniqueness, inventory completeness, blocked overclaims, idempotent summaries, and sanitized output | \~190      |
| `apps/server/src/lib/erasureInventory.ts`                | Read-only server/local boundary inventory mapper for later local erasure runtime work                                            | \~140      |
| `apps/server/tests/erasureInventory.test.ts`             | Tests for server boundary mapping, redaction, no mutation, and no raw path output                                                | \~120      |
| `apps/warroom/src/erasureInventory.ts`                   | Read-only Worker Durable Object boundary inventory mapper for later Worker erasure gate work                                     | \~110      |
| `apps/warroom/tests/erasureInventory.test.ts`            | Tests for Worker boundary mapping and raw authority/room payload exclusion                                                       | \~100      |
| `.spec_system/PRD/phase_08/unified_erasure_inventory.md` | Human-readable release-scoped erasure inventory and authority model handoff                                                      | \~180      |

### Files to Modify

| File                                   | Changes                                                                                              | Est. Lines |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------- |
| `packages/protocol/src/index.ts`       | Export the new erasure contract module                                                               | \~1        |
| `packages/protocol/README_protocol.md` | Document protocol ownership for Phase 08 erasure vocabulary and inventory                            | \~35       |
| `apps/server/README_server.md`         | Document server/local erasure inventory boundaries and no-destructive-action status                  | \~30       |
| `apps/warroom/README_warroom.md`       | Document Worker Durable Object erasure inventory and Session 04 handoff                              | \~30       |
| `docs/privacy-and-security.md`         | Update personal data and trusted-erasure coverage with inventory references                          | \~45       |
| `docs/release.md`                      | Add Session 02 inventory evidence and keep no-claim release wording until runtime sessions validate  | \~35       |
| `docs/api/README_api.md`               | Clarify current cleanup, diagnostics, export, and Worker boundaries versus trusted erasure contracts | \~30       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Protocol exports erasure status, boundary family, authority, dry-run, confirmation, partial-failure, audit, verification, blocked payload, and unsupported-claim vocabulary.
* [ ] Protocol inventory covers every Phase 08 release-scoped boundary named by Session 01: archives, memory, settings, lifecycle files, browser state, War Room Durable Object state, replay/export buffers, diagnostics, logs, backups, valid spool state, workspace files, and future hosted surfaces.
* [ ] Each inventory row has owner, current status, authority model, dry-run expectation, verification plan, audit expectation, docs paths, and explicit no-overclaim wording.
* [ ] Server and Worker mapping helpers expose bounded summaries without mutation, raw paths, tokens, room payloads, prompts, commands, logs, backups, exports, replay buffers, or diagnostics payloads.
* [ ] Tests prove one-boundary cleanup, browser reset, Worker leave, diagnostics recovery, CLI uninstall, and manual file removal are not trusted unified erasure.
* [ ] Docs distinguish cleanup, reset, leave, diagnostics recovery, uninstall, inventory, and future trusted unified erasure.

### Testing Requirements

* [ ] Protocol tests written and passing.
* [ ] Server erasure inventory helper tests written and passing.
* [ ] Worker erasure inventory helper tests written and passing.
* [ ] Focused TypeScript typecheck passes for affected TypeScript workspaces.
* [ ] Manual docs review completed for no-overclaim erasure wording.

### Non-Functional Requirements

* [ ] Contract output uses labels, counts, booleans, docs paths, and synthetic identifiers only.
* [ ] No destructive filesystem, browser, Worker, hosted, or workspace mutation is introduced.
* [ ] Local-first workflows still do not require hosted credentials, Cloudflare credentials, provider keys, analytics config, push config, or real executors.
* [ ] Current security finding `P06-S07-ERASURE` remains open until runtime deletion and Worker gates are implemented and validated by later sessions.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] `git diff --check` passes.

***

## 8. Implementation Notes

### Key Considerations

* This session should make trusted erasure harder to overclaim, not easier. Inventory and vocabulary are necessary but not sufficient release evidence.
* Protocol contracts should include future hosted placeholders, but active hosted auth, storage, public replay, analytics, push, remote access, and hosted deletion remain unavailable or later-scope.
* Server and Worker helpers must be read-only. They can identify boundary families and planned evidence needs, but must not delete, purge, clear, or mutate anything.
* Browser state is in release scope even if this session does not add browser controls. The inventory should capture settings, replay buffers, URL fragments, local auth hints, War Room hints, and in-memory Worker authority constraints.
* Workspace files are sensitive and broad. The inventory should name them as a boundary with explicit authority and verification constraints, not silently include them in local cleanup.

### Potential Challenges

* Inventory incompleteness: mitigate with explicit tests that compare required Phase 08 boundary ids against exported inventory ids.
* Overclaiming by helper names: use inventory, preview, summary, or boundary names rather than erase/delete runtime names unless the function is clearly non-mutating.
* Raw output leakage: serialize helper outputs in tests and assert synthetic prompts, paths, tokens, room payloads, backups, logs, exports, and replay buffers are absent.
* Hosted placeholder ambiguity: mark hosted identity/storage/public replay/analytics/push/remote data as planned, unavailable, disabled, or no-claim until later scoped work exists.
* Worker authority confusion: preserve room-local authority boundaries and never treat authority hashes, participant hints, or Worker leave as hosted identity or erasure proof.

### Relevant Considerations

* \[P07] **Unified erasure deferred to Phase 08 (P07-R023)**: this session defines the contract and inventory for the unified workflow, but does not ship deletion.
* \[P07] **Redaction is boundary-specific**: diagnostics, exports, archives, replay, Worker, backups, logs, and future hosted payloads need explicit blocked categories and sanitized summaries.
* \[P03] **Local backups are sensitive state**: backup tarballs must stay local and need explicit authority, retention, verification, and erasure design.
* \[P03] **Protocol leads cross-package work**: shared release-sensitive vocabulary starts in `packages/protocol` before package-specific helpers consume it.
* \[P06] **Do not call Worker leave or reset trusted erasure**: browser leave/reset clears local room context only; Durable Object state and related local artifacts remain in scope for later erasure work.
* \[Security] **P06-S07-ERASURE**: trusted unified erasure remains an open finding until later sessions implement and validate runtime behavior.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* One-boundary cleanup could be mislabeled as trusted unified erasure.
* Inventory summaries could expose raw paths, prompts, tokens, room payloads, logs, backups, exports, replay buffers, or diagnostics.
* Missing a boundary now could make Session 03 or Session 04 delete too little while claiming too much.
* Future destructive runtime could lack authority, dry-run, idempotency, audit, partial-failure, or verification semantics if the contract is vague.

***

## 9. Testing Strategy

### Unit Tests

* Test protocol value arrays for uniqueness, guard behavior, exhaustive inventory ids, blocked payload labels, unsupported claims, and deterministic summary counts.
* Test protocol negative-claim helpers for reset, leave, cleanup, uninstall, recovery, one-boundary deletion, and manual removal.
* Test server inventory helper output for expected local boundaries, no mutation, no raw path output, and no raw sensitive fixture values.
* Test Worker inventory helper output for Durable Object fields, authority hash metadata, idempotency metadata, recent events, participant metadata, and no raw token or room payload output.

### Integration Tests

* Run focused Vitest files for protocol, server, and Worker erasure inventory work.
* Run affected workspace typechecks for `packages/protocol`, `apps/server`, and `apps/warroom`.
* Run `git diff --check` after docs and code changes.

### Manual Testing

* Review `.spec_system/PRD/phase_08/unified_erasure_inventory.md` against the Session 01 baseline and routing matrix.
* Confirm docs keep trusted erasure no-claim wording until Session 03 and Session 04 produce runtime evidence.
* Confirm package README updates direct future implementation to protocol-owned contracts.

### Edge Cases

* Missing FactionOS home, missing backup directory, unreadable logs, malformed spool entries, valid spool entries, empty exports, absent browser storage, storage-unavailable browser state, stale Worker authority, duplicate idempotency keys, expired authority records, missing Worker rooms, future hosted unavailable state, and workspace files outside approved scope.
* Partial inventory rows should produce explicit unsupported or planned status, not silent success.
* Dry-run summaries must stay deterministic across repeated calls and must not depend on raw filesystem ordering or raw Durable Object payload content.

***

## 10. Dependencies

### External Libraries

* None expected. Use existing TypeScript, Vitest, and workspace tooling.

### Other Sessions

* **Depends on**: `phase08-session01-release-requirements-and-risk-baseline`
* **Depended by**: `phase08-session03-local-erasure-runtime-and-controls`, `phase08-session04-war-room-and-hosted-identity-release-gate`, `phase08-session08-release-candidate-validation-and-documentation-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/phase08-session02-unified-erasure-contract-and-inventory/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.