@zieglar/pi-chat-exchange 0.2.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/README.md +41 -61
  2. package/dist/bin/ce-native.js +119 -0
  3. package/dist/control/mcp/server.js +1 -1
  4. package/dist/host/mcp-binding-config.js +1 -1
  5. package/dist/runtime/diagnostics.js +3 -3
  6. package/dist/runtime/executables.js +37 -30
  7. package/dist/runtime/native-readiness.js +131 -0
  8. package/dist/runtime/wrapper-identity.js +53 -0
  9. package/dist/storage/connection.js +4 -3
  10. package/dist/storage/filesystem.js +58 -3
  11. package/dist/storage/native-artifact.js +234 -0
  12. package/dist/storage/native-compat.js +65 -0
  13. package/dist/storage/runtime.js +201 -58
  14. package/dist/storage/sqlite-driver-node.js +66 -0
  15. package/dist/storage/sqlite-driver-rust.js +121 -0
  16. package/dist/storage/sqlite-driver-selection.js +86 -0
  17. package/dist/storage/sqlite-driver.js +4 -0
  18. package/dist/storage/store.js +3 -3
  19. package/dist/storage/transaction.js +20 -23
  20. package/dist/tunnel/background-manager.js +5 -52
  21. package/dist/tunnel/codes.js +1 -1
  22. package/dist/tunnel/keychain.js +1 -1
  23. package/dist/tunnel/managed-binding.js +1 -1
  24. package/dist/tunnel/manager-panel.js +1 -1
  25. package/dist/tunnel/profile.js +4 -2
  26. package/dist/tunnel/setup-ui.js +3 -3
  27. package/dist/tunnel/tunnel-id.js +4 -0
  28. package/package.json +8 -20
  29. package/pi-extension/index.ts +34 -0
  30. package/CHANGELOG.md +0 -70
  31. package/docs/architecture.md +0 -170
  32. package/docs/chatgpt-installation.md +0 -149
  33. package/docs/delivery-ack-contract.md +0 -86
  34. package/docs/independent-install.md +0 -156
  35. package/docs/multi-session-usage.md +0 -77
  36. package/docs/ownership-contract.md +0 -429
  37. package/docs/protocol-v2.md +0 -269
  38. package/docs/releases/0.2.0.md +0 -59
  39. package/docs/storage-contract.md +0 -1241
  40. package/docs/storage-security.md +0 -138
  41. package/docs/tunnel-manager-background.md +0 -169
  42. package/docs/tunnel-setup.md +0 -214
  43. package/pi-extension/README.md +0 -125
@@ -1,1241 +0,0 @@
1
- # Durable storage contract (CE-0002-B2-S6-2)
2
-
3
- Consolidated contract for the accepted private SQLite durable storage of
4
- Chat Exchange. Every normative claim below is backed by accepted test or
5
- implementation evidence; see the traceability matrix at the end.
6
-
7
- ## E2-A current-only v7 implementation candidate
8
-
9
- This section supersedes historical version/migration requirements below for the
10
- E2-A implementation candidate; parent review/acceptance remains pending.
11
-
12
- Fresh stores use the complete direct final `src/storage/current-schema.ts` v7
13
- foundation, not historical COPY/DROP/RENAME composition. The one fresh ledger row
14
- is `(7, b3-p3b-direct-current-ack-foundation,
15
- fd07d7a0e65183700c7f71e1f5522c59ef053f1e316eb4bb93596f5b3309b5b1)`.
16
- Metadata initialization version and user_version are both 7. Exact schema, ledger,
17
- identity, integrity, foreign keys, restore-hold and host trust root are validated
18
- before COMMIT and again before publishing a handle. A separately pinned static
19
- 94-object manifest is in `test/storage/support/current-v7-manifest.json`.
20
-
21
- Normal open refuses unsupported/old/mixed shapes with STORAGE_INCOMPATIBLE and
22
- separate operator-approved Dev Reset guidance; it never resets, deletes, repairs,
23
- reinitializes or migrates. Foreign identity, too-new, checksum, corruption,
24
- filesystem, hold and trust-root refusals keep their distinct typed meanings.
25
- Historical SQL/checksums and migration.ts remain unchanged; they are not a v7
26
- upgrade service or an E2-A normal-open prerequisite.
27
-
28
- Initialization owns exception-safe connection cleanup, including secret generation.
29
- Failed initialization can leave refused filesystem artifacts; no automatic deletion
30
- or repeat is performed. An uncertain/lost response can leave a complete committed
31
- Store. Failure never by itself proves rollback; fresh full validation is required.
32
-
33
- The new private ACK/receipt reconciliation semantics are specified in
34
- [delivery-ack-contract.md](delivery-ack-contract.md). No public ACK transport is added.
35
-
36
- Scope labels used throughout:
37
-
38
- - **public contract** — behavior callers can rely on;
39
- - **internal** — private implementation detail, not a caller guarantee;
40
- - **test-only** — capability existing only in the test harness;
41
- - **limitation** — known boundary of current evidence;
42
- - **deferred** — recorded future requirement, not implemented.
43
-
44
- This document does not change any architecture, production behavior, or test.
45
-
46
- ## 1. Storage contract
47
-
48
- ### Creation APIs (public contract)
49
-
50
- `createExchange(store, input)` and `createMessage(store, input)` are
51
- synchronous. Both return a frozen result `{ disposition, entity, record }`
52
- where `disposition` is `"CREATED"` or `"REPLAYED"` (`ExchangeCreation`,
53
- `MessageCreation` in `src/storage/creation.ts:24`, `:214`).
54
-
55
- - `createExchange` creates an Exchange row, an idempotency record, and one
56
- `exchange_opened` audit event with sequence 1, in a single owned
57
- transaction (implementation: `creation.ts:120`, audit insert at `:178`).
58
- - `createMessage` creates a Message row, an idempotency record, and one
59
- `message_created` audit event with a per-Exchange consecutive sequence,
60
- in a single owned transaction (implementation: `creation.ts:382`,
61
- sequence selection at `:346`, audit insert at `:456`).
62
- - Message identities are `msg_`-prefixed, audit identities `evt_`-prefixed
63
- (test: M2 in `test/storage/message-creation.test.ts`).
64
- - All three rows are visible to an independent read-only connection after
65
- COMMIT (test: M6).
66
-
67
- ### Public result shapes (public contract)
68
-
69
- A created or replayed Message exposes legitimate public fields only:
70
- `messageId`, `exchangeId`, `from`, `to`, `payloadDigest`, `payloadLength`,
71
- `createdAt`, `state`, plus the enclosing `disposition` and idempotency
72
- `record`. Endpoint identities (`from`, `to`) are **public by accepted M3
73
- contract**: the stored endpoint is embedded in the replayed Message and
74
- persisted exactly as requested (test: M3). Results are deeply frozen
75
- (test: M5).
76
-
77
- ### Private payload handling (public contract)
78
-
79
- The payload body is stored privately. Public results expose only the digest
80
- and length — never payload bytes, and no payload accessor (tests: SB6,
81
- M3, and the S6-1 sweep). An empty payload is stored as a zero-length body
82
- (test: M7); the maximum authorized size is accepted (M8); oversized payloads
83
- are rejected before any transaction starts (M9).
84
-
85
- ### Idempotency and replay (public contract)
86
-
87
- The idempotency key is scoped per Exchange with no in-memory state (test:
88
- I7). Repeating the same key with the identical request replays the original
89
- Message: `REPLAYED` disposition, preserved creation metadata and current
90
- stored state, zero writes, no hook invocation (tests: I1, I2, I3). Replay
91
- works after Store close/reopen and across concurrent processes (test: R4 in
92
- `test/storage/message-creation-recovery.test.ts`).
93
-
94
- ### Conflict (public contract)
95
-
96
- The same key carrying a different request (different payload or endpoint)
97
- is a nonretryable conflict — never a replace (tests: I4, I5; C2 race and
98
- serialized cases). A valid request conflicting with a stored different
99
- request is a conflict, not corruption (I8).
100
-
101
- ### Exchange admission (public contract)
102
-
103
- New creation is refused when the Exchange is missing (A1), CLOSED (A3), or
104
- carries a disposition row (A4; implementation: `creation.ts:334`). Zero-write
105
- replay remains allowed after CLOSED or disposition (A5, A6); conflict
106
- classification survives CLOSED admission without consulting it (A7). Externally
107
- committed disposition changes are observed through the open Store without
108
- reopening (tests: F2-A, F2-B, F3).
109
-
110
- ### Transaction ownership and outcomes (public contract)
111
-
112
- All mutations run inside `withImmediateTransaction` — a synchronous,
113
- exclusive owner of the connection (internal primitive; contract documented in
114
- `docs/storage-security.md` and covered by `transaction*.test.ts`). Public
115
- error classes are `CreationDomainError`, `StorageTransactionError`, and
116
- `ConditionalMutationError`, with fixed sanitized messages and codes
117
- (implementation: `creation.ts:50`, `transaction.ts:6`, `:26`).
118
-
119
- - **BUSY**: a contended transaction is classified
120
- `STORAGE_TRANSACTION_BUSY`, outcome `ROLLED_BACK`, retryable (test: S6-1
121
- "BUSY classification errors …").
122
- - **ROLLED_BACK**: a failed COMMIT with a proven rollback produces
123
- outcome `ROLLED_BACK` and no fabricated success (S6-1 commit-failure test).
124
- - **INDETERMINATE**: a failure of the owned ROLLBACK itself yields
125
- `STORAGE_TRANSACTION_FAILED`, outcome `INDETERMINATE`, non-retryable, and
126
- the connection is invalidated; subsequent calls repeat the same sanitized
127
- classification (S6-1 uncertain-rollback test; helper mechanics at
128
- `transaction.ts` `invalidated` WeakSet). INDETERMINATE does **not**
129
- guarantee zero durable writes; observed zero-write state belongs only to
130
- the controlled test fixtures (limitation).
131
-
132
- ### Audit behavior (public contract)
133
-
134
- Exactly one audit event per successful creation; replay performs zero
135
- audits (I3). Message audit sequences are consecutive per Exchange (C3).
136
- Corrupt or unexpected durable history is refused, never repaired (P3;
137
- `a51c091` unsafe-integer classification).
138
-
139
- ### Durable storage boundaries (public contract)
140
-
141
- Storage is private to the package: the public entry point re-exports
142
- protocol/core only (`src/index.ts:7-10`), and the contract gate enforces
143
- the private storage boundary (19 negative fixtures; Wayforge 19 architecture
144
- gates). Filesystem, refusal, schema-manifest, and snapshot-preflight
145
- boundaries are documented in `docs/storage-security.md`.
146
-
147
- ## 2. Crash and recovery evidence
148
-
149
- Accepted committed regression evidence:
150
-
151
- - **K1–K6 boundary markers**: creation is provably committed only after the
152
- full transaction completes; a crash before the boundary leaves no durable
153
- triple, and a crash after a proven COMMIT keeps the durable result with
154
- retry replaying it (K6; crash suite in
155
- `test/storage/message-creation-crash.test.ts`, commit `b3141ca`).
156
- - **SIGKILL lock release**: a killed writer releases its write lock and a
157
- later process creates cleanly (R1-A, commit `f178dec`).
158
- - **Contention during death**: a contender blocked on BEGIN IMMEDIATE
159
- resolves safely when the holder dies (R1-B).
160
- - **Reader snapshot isolation**: an open reader transaction is unaffected by
161
- a writer's uncommitted work and SIGKILL (R2).
162
- - **Store close/reopen and concurrent replay**: durable idempotency replays
163
- through close/reopen and concurrent processes with zero duplicate writes
164
- (R4, commit `bbf28f0`).
165
- - **K5 crash**: committed history survives; the uncommitted triple is absent
166
- (R3).
167
-
168
- **Distinction that must not be blurred (limitation):** in the accepted K5
169
- scenario the WAL file is zero bytes at crash time — K5 is an *uncommitted
170
- rollback* scenario. A zero-byte WAL does **not** prove the physical location
171
- of uncommitted pages. *Non-empty committed-WAL recovery* has independent
172
- review-harness evidence (45,352 WAL bytes surviving SIGKILL in the S5-2
173
- review probe) but is **not part of the accepted committed regression suite**;
174
- that is recorded as `CE-STORAGE-WAL-RECOVERY-REGRESSION`.
175
-
176
- ## 3. Privacy contract
177
-
178
- **Legitimate public fields** (not leaks): `messageId`, `exchangeId`,
179
- `from`, `to`, `payloadDigest`, `payloadLength`, `createdAt`, `state`,
180
- `disposition`. Endpoint identities are public per the accepted M3 contract.
181
-
182
- **Prohibited disclosures** on any public result or error: payload bytes (in
183
- hex, decimal-sequence, `Uint8Array`, or `Buffer` form), credentials, database
184
- paths, raw SQL, and internal exception causes (`cause` properties). Public
185
- errors carry fixed vocabulary; `Error.stack` may exist but must not contain
186
- protected information.
187
-
188
- Accepted S6-1 regression coverage (`test/storage/public-surface-privacy.test.ts`,
189
- commits `84e0603`, `f606594`): sweeps CREATED and REPLAYED Message results,
190
- REPLAYED Exchange results, and eight error paths (conflict, invalid request,
191
- admission rejection, BUSY, COMMIT-failure rollback, uncertain-rollback
192
- INDETERMINATE, hook-seam failure), with negative controls proving detection
193
- of each sentinel class (including binary payload forms) and a false-positive
194
- control for legitimate public fields. Production cause-leak mutation
195
- sensitivity was demonstrated: mutating the **createMessage** wrap site fails
196
- 4 tests (exit 1).
197
-
198
- **Non-blocking gap — `CE-PRIVACY-EXCHANGE-ERROR-COVERAGE` (deferred):**
199
- createExchange error paths have no direct privacy assertions; mutating the
200
- createExchange wrap site alone passes the suite. The two APIs do **not** have
201
- identical mutation sensitivity. The shared wrap mechanism and sanitization
202
- assertions are exercised through createMessage paths only.
203
-
204
- ## 4. Architecture boundaries
205
-
206
- Chat Exchange does **not** currently own: model routing, account rotation,
207
- automatic task retries, durable task execution, recovery scheduling, or
208
- cross-plugin orchestration. Chat Exchange message persistence (this contract)
209
- is distinct from Wayforge task durability; neither implies the other. This
210
- document records boundaries; it changes no architecture.
211
-
212
- ## 5. Deferred register
213
-
214
- Existing technical limitations / optional hardening:
215
-
216
- - **`CE-STORAGE-IMMUTABILITY-V2`** — Schema v1 lacks authenticated state
217
- integrity; privileged CLOSED→OPEN drift is characterized but not prevented
218
- (tests: F4, P4).
219
- - **`CE-STORAGE-WAL-RECOVERY-REGRESSION`** — no committed regression test for
220
- non-empty committed-WAL crash recovery; evidence is review-harness only.
221
- - **`CE-PRIVACY-EXCHANGE-ERROR-COVERAGE`** — createExchange error paths lack
222
- direct privacy mutation sensitivity (see §3).
223
-
224
- Future product capabilities (not implemented, not designed here):
225
-
226
- - **`CE-SESSION-CONTINUITY-001`** — a new Pi Session can safely resume
227
- participation in an existing Exchange without losing committed messages.
228
- Current boundary: persisted messages and Store reopening do not by
229
- themselves provide cross-session continuity; participant takeover is out
230
- of scope here.
231
- - **`CE-RECONNECT-001`** — recover communication after ChatGPT.app restart,
232
- update, or temporary disconnection. Distinct layers: persisted Exchange
233
- state (this contract), Pi-side connection restoration, ChatGPT.app
234
- integration, and task-execution recovery. ChatGPT.app must not be assumed
235
- to provide an automatic reconnect lifecycle hook.
236
-
237
- B2 scope is not expanded by these entries.
238
-
239
- ## 6. Traceability matrix
240
-
241
- | Contract claim | Test evidence | Accepted commit | Limitation |
242
- | --- | --- | --- | --- |
243
- | Exchange creation: 3 rows, one transaction, audit seq 1 | exchange-creation suite; `creation.ts:120`,`:178` | `deefd8e` | — |
244
- | Message creation: schema-valid CREATED, 3 rows visible | M1, M6 | `deefd8e` | — |
245
- | Public fields incl. endpoints; deep freeze | M3, M5; S6-1 sweep | `deefd8e`, `84e0603` | endpoints are public, not hidden |
246
- | Private payload; digest/length only; no accessor | SB1–SB10, M3, M7–M9 | `deefd8e` | — |
247
- | Idempotent replay: zero writes, metadata preserved | I1–I3, I7 | `deefd8e` | — |
248
- | Conflict nonretryable; no replace | I4, I5, I8, C2 | `deefd8e`, `1250800` | — |
249
- | Admission: missing/CLOSED/dispositioned refused | A1, A3–A8, F2-A/F2-B/F3 | `deefd8e`, `8318b36` | — |
250
- | Transaction outcomes: BUSY/ROLLED_BACK/INDETERMINATE + invalidation | transaction suites; S6-1 error tests | `deefd8e`, `84e0603` | INDETERMINATE ≠ zero-write guarantee |
251
- | Error precedence and corruption refusal | P1–P5 | `5005078`, `a51c091` | — |
252
- | Crash boundaries K1–K6, SIGKILL commit durability | crash suite (19 tests) | `263c191`, `b3141ca` | harness-based process fixtures |
253
- | Lock release, contention, reader isolation | R1-A, R1-B, R2 | `f178dec` | — |
254
- | Close/reopen + concurrent replay | R4, C5 | `bbf28f0`, `1250800` | — |
255
- | K5 uncommitted rollback survives crash | R3 | `bbf28f0` | WAL zero bytes; see CE-STORAGE-WAL-RECOVERY-REGRESSION |
256
- | Public-surface privacy sweep + binary controls | S6-1 suite (18 tests) | `84e0603`, `f606594` | createExchange error paths: CE-PRIVACY-EXCHANGE-ERROR-COVERAGE |
257
- | Private storage boundary / no public export | architecture contract gate (19 fixtures) | (workspace gates) | — |
258
-
259
-
260
- ## 7. B3-P1A schema v2, explicit migration, and host trust root
261
-
262
- Accepted B3-P1A amendment (CE-0002-B3-P1A). Everything in §§1-6 is preserved:
263
- every v1 table, trigger, index, and row is untouched; v2 only appends new
264
- schema objects and ledger rows. `store_metadata` is never UPDATEd or DELETEd
265
- (its v1 immutability trigger would abort the attempt);
266
- `store_metadata.schema_version` permanently records the schema version at
267
- initialization (1 for migrated stores, 2 for fresh v2 stores). The live
268
- schema version is `PRAGMA user_version`, which must equal the highest
269
- migration-ledger entry.
270
-
271
- ### Additive v2 schema
272
-
273
- New tables: `participant`, `participant_capability` (SHA-256 digests only,
274
- never plaintext capabilities), `participant_session` (schema only in P1A),
275
- `exchange_membership`, `participant_ownership`,
276
- `participant_fencing_high_water`, `delivery_cursor`, `host_trust_root`.
277
- New append-only/immutability triggers: `participant_identity_immutable`,
278
- `exchange_membership_immutable`/`_nodelete`,
279
- `host_trust_root_immutable`/`_nodelete`. The ownership, fencing, and cursor
280
- tables are inert schema in P1A: no code path reads or writes them before
281
- B3-P2/P3, and a migration test asserts they are empty.
282
-
283
- ### Version recognition (normal open)
284
-
285
- - Recognized pristine v1 (ledger exactly the v1 row, `user_version` 1,
286
- v1 manifest): refused with `STORAGE_MIGRATION_REQUIRED` — migration is
287
- never implicit and never runs during a normal open.
288
- - Migrated v2 (ledger v1 row + v2 migration row, `user_version` 2) or fresh
289
- v2 (single v2 foundation row, `user_version` 2): opens after full
290
- validation including the host trust root. Migrated and fresh stores share
291
- one byte-identical approved manifest (`INITIAL_SCHEMA_SQL + V2_ADDITIVE_SQL`).
292
- - `user_version` or metadata version above 2: `STORAGE_SCHEMA_TOO_NEW`.
293
- - Any ledger deviation: `STORAGE_MIGRATION_CHECKSUM_MISMATCH`. Any schema
294
- drift (extra, dropped, or altered objects, whitespace-level):
295
- `STORAGE_INCOMPATIBLE`. Refusal-over-repair is unchanged.
296
-
297
- ### Explicit migration (`migrateStore`)
298
-
299
- A dedicated host-local entry point, never reachable from `openStore`:
300
- requires the explicit `{ fromVersion: 1, toVersion: 2 }` path; preflights the
301
- exact v1 shape on a disposable read-only snapshot (integrity, foreign keys,
302
- identity, ledger, manifest, restore hold); bootstraps host trust-root
303
- generation 1; applies the additive DDL, appends the v2 ledger row, and
304
- advances `user_version` inside one owned BEGIN IMMEDIATE transaction; then
305
- proves success by a full v2 reopen. Interruption rolls back to a valid v1
306
- store (still answered by `STORAGE_MIGRATION_REQUIRED`); BUSY / ROLLED_BACK /
307
- INDETERMINATE propagate unchanged with no retry and no repair. A v2 store is
308
- structurally unopenable by a v1 binary (`user_version` 2 exceeds v1's
309
- supported version), so downgrade is impossible.
310
-
311
- ### Host trust root
312
-
313
- The host secret is a 256-bit random value hex-encoded into a `host-secret`
314
- file inside the private store directory: exclusive creation with O_NOFOLLOW,
315
- mode 0600, current-user-owned, no symlinks — the same artifact enforcement
316
- the database itself passes. Only its SHA-256 fingerprint is persisted, in the
317
- append-only `host_trust_root` table. Every v2 open re-reads the file, repeats
318
- the artifact checks, and compares the fingerprint: missing file
319
- `STORAGE_TRUST_ROOT_MISSING`, disagreement `STORAGE_TRUST_ROOT_MISMATCH`,
320
- insecure artifact `STORAGE_TRUST_ROOT_INSECURE`, preexisting secret during
321
- initialization/migration/recovery `STORAGE_TRUST_ROOT_AMBIGUOUS` — all fail
322
- closed with zero writes, no repair, no automatic regeneration, and no secret
323
- or fingerprint material in any error, result, or log surface.
324
-
325
- ### Trust-root recovery (`recoverTrustRoot`)
326
-
327
- Explicit operator-authorized only: the operator removes any old secret file
328
- first (the command refuses to overwrite one); the store must be a valid v2
329
- store; one owned transaction appends generation N+1 with the new fingerprint
330
- and revokes every existing capability row. A replacement secret inherits no
331
- authority: previous-generation capabilities fail by revocation and by
332
- generation binding, and fresh capability issuance is required per
333
- Participant. Capability issuance itself is B3-P1B scope and does not exist
334
- yet.
335
-
336
- ### Limitations
337
-
338
- Protection equals the documented filesystem trust boundary
339
- (`storage-security.md`): an attacker controlling both the database and the
340
- secret file can rewrite both consistently, and no protection against that
341
- actor is claimed. `CE-STORAGE-IMMUTABILITY-V2` remains open and unchanged;
342
- the new v2 tables inherit the same unauthenticated-state limitation.
343
-
344
-
345
- ## 8. B3-P1B Participant identity, capability authorization, and membership
346
-
347
- Implemented B3-P1B amendment (CE-0002-B3-P1B). Everything in §§1-7 is
348
- preserved: no v1 DDL, trigger, index, or row changes, no schema-v2 manifest
349
- change (P1B uses only tables the accepted v2 schema already defines), no
350
- change to B2 creation, request digests, idempotency/conflict semantics, audit
351
- ordering, or transaction classification. The ownership, fencing, and cursor
352
- tables remain inert.
353
-
354
- ### Participant identity (public contract within the private plane)
355
-
356
- `createParticipant` creates one durable, globally unique Participant
357
- (`prt_<ULID>`, generated by the frozen protocol ULID encoder) immutably bound
358
- to exactly one stable Endpoint identity `(adapter, endpointId)`. Identity and
359
- binding are immutable (`participant_identity_immutable`), the binding is 1:1
360
- (`UNIQUE (endpoint_adapter, endpoint_id)`), a second Participant for the same
361
- Endpoint identity is refused (`PARTICIPANT_ENDPOINT_CONFLICT`), and no
362
- reassignment or aliasing exists. A Session ID is never an identity:
363
- `participant_session` stays unused in P1B. `instanceId` is ephemeral — it is
364
- excluded from identity, from the request digest, and from the persisted
365
- binding, so a differing incarnation replays instead of conflicting. Creation
366
- is idempotency-keyed with the accepted B2 semantics (replay, conflict,
367
- corruption-before-conflict). No audit event is emitted: `audit_event` is
368
- Exchange-scoped by the accepted v1 DDL and Participant identity is global.
369
-
370
- `bindEndpointRef` is the authorized affirmation of that immutable binding: it
371
- requires a `bind` capability, performs zero writes, refuses a different
372
- Endpoint identity (`PARTICIPANT_BINDING_MISMATCH`) and an Endpoint identity
373
- owned by another Participant (`PARTICIPANT_ENDPOINT_CONFLICT`), and ignores
374
- `instanceId`.
375
-
376
- ### Host Capability authorization
377
-
378
- Only the P1 scopes `create`, `bind`, and `join` are operational; the remaining
379
- accepted schema scopes are refused with `CAPABILITY_SCOPE_UNSUPPORTED`. A
380
- capability is a 256-bit CSPRNG bearer token (`cap_<64 hex>`) returned once to
381
- the issuing host. Only an HMAC-SHA256 digest keyed by the host secret is
382
- persisted, bound to the current trust generation, the Participant, and the
383
- exact scope. Verification happens inside the same owned transaction as the
384
- mutation it authorizes and re-validates the host trust root (artifact policy
385
- plus fingerprint agreement) on every authorization. Forged, unknown,
386
- wrong-scope, wrong-Participant, wrong-generation, revoked, and expired
387
- capabilities are all refused with the single opaque `CAPABILITY_REJECTED`
388
- classification, so the refusal is not an oracle; the host-local
389
- `readCapabilityStatus` read retains the detail. Session IDs and Participant
390
- IDs never authorize anything. Since CE-0002-B3-P2C-B a Session-bound
391
- capability (`resume`, `takeover`; the future `send`/`ack`/`read` scopes
392
- inherit this when they become operational) whose bound Session is DETACHED
393
- is equally unusable: the persisted `detached_at` is the lifecycle source of
394
- truth, invalidated at read time with no capability-row rewrites, and the
395
- host-local status identifies `SESSION_DETACHED` while callers see the same
396
- opaque classification. A Session-bound capability whose binding row is
397
- missing or malformed refuses `STORAGE_OWNERSHIP_CORRUPT`. Revocation is
398
- explicit and one-way; there is no
399
- automatic capability recovery. After an operator trust-root recovery, previous
400
- capabilities fail both by revocation and by generation binding, and fresh
401
- issuance is required per Participant.
402
-
403
- ### Exchange membership and the join boundary
404
-
405
- `joinExchange` requires a valid `join` capability, verifies the Participant,
406
- and admits only an existing OPEN Exchange without an administrative
407
- disposition. It writes one `exchange_membership` row, one idempotency record,
408
- and exactly one `participant_joined` audit event, allocating the sequence
409
- through the accepted per-Exchange MAX(sequence)+1 discipline and persisting it
410
- as the immutable `join_boundary_seq`. Membership rows are immutable and
411
- undeletable (`exchange_membership_immutable`/`_nodelete`). A duplicate join is
412
- a zero-write replay that never moves the boundary; the same key with a
413
- different request is `IDEMPOTENCY_KEY_CONFLICT`. Historical Message rows are
414
- never rewritten: audit sequences below the boundary are pre-join history and
415
- sequences above it are post-join activity. Keys are Exchange-scoped, so one
416
- Participant may join many Exchanges and one Exchange may hold many
417
- Participants.
418
-
419
- **Membership eligibility is not delivery.** P1B provides no message listing,
420
- no delivery, no cursor or ACK behavior, and no adapter wiring; the delivery
421
- plane remains unauthorized B3-P2/P3 scope.
422
-
423
- ### Durable reads
424
-
425
- Minimal private reads only: Participant existence, stable Endpoint binding,
426
- Exchange membership with its join boundary, and host-local capability status.
427
- Nothing is added to the public package surface — the private storage boundary
428
- and its contract gate are unchanged.
429
-
430
- ### Interpretation notes
431
-
432
- - The `create` scope is operational through optional sponsored creation: when
433
- `createParticipant` receives a `sponsor`, that sponsor's `create` capability
434
- is verified in the same owned transaction. Making `create` gate accepted B2
435
- Exchange/Message creation would change accepted B2 contracts and is
436
- therefore out of scope.
437
- - `participant_joined` is a private storage audit kind. The frozen protocol
438
- `EVENT_KINDS` vocabulary and `prt_` identity prefix are deliberately not
439
- added to the publicly re-exported protocol surface; `audit_event.kind` is
440
- free text in the accepted v1 DDL.
441
-
442
- ### 8.1 R1 remediation (CE-0002-B3-P1B-R1)
443
-
444
- Remediation of the independent B3-P1B review. No schema change, no new
445
- dependency, no public export, no P2 scope.
446
-
447
- **Authorization precedes every protected result.** `joinExchange` and sponsored
448
- `createParticipant` previously evaluated the idempotent replay path before
449
- capability verification, so a caller holding a known idempotency key could
450
- obtain a `REPLAYED` Membership or Participant result while presenting a forged,
451
- expired, revoked, wrong-scope, wrong-Participant, or wrong-generation
452
- capability. Current authorization now runs first, inside the same owned
453
- transaction, for both newly created and replayed results. An idempotency key is
454
- never an authorization credential.
455
-
456
- **Deliberate error-precedence change.** On these two paths
457
- `CAPABILITY_REJECTED` now outranks replay, `IDEMPOTENCY_KEY_CONFLICT`, and
458
- `STORAGE_IDEMPOTENCY_CORRUPT` classification. Within the authorized replay path
459
- the accepted corruption-before-conflict ordering is unchanged. Unsponsored
460
- `createParticipant` is a trusted host-local operation and keeps its accepted
461
- semantics with no capability requirement.
462
-
463
- **Idempotency is unchanged otherwise.** An authorized replay remains
464
- zero-write, deterministic, byte-identical, and boundary-preserving, and emits
465
- no audit event, no capability record, and no ownership change. The B2 request
466
- digest and B2 Exchange/Message behavior are untouched.
467
-
468
- **`bindEndpointRef` is validation-only.** The accepted name is kept; the
469
- operation never creates or changes a binding. The binding is established once,
470
- atomically with identity creation.
471
-
472
- **Trust-root classification is aligned.** During capability verification, a
473
- missing trust-generation row is `STORAGE_CORRUPT` and a host-secret fingerprint
474
- disagreement is `STORAGE_TRUST_ROOT_MISMATCH` — typed trust-root refusals, as
475
- the capability plane already documented and as `issueCapability` already
476
- behaved. Capability refusals themselves stay a single opaque
477
- `CAPABILITY_REJECTED`, and both paths fail closed with zero writes.
478
-
479
- **`recoverTrustRoot` corruption classification.** When the owned transaction
480
- proves a non-retryable rollback caused by a typed lifecycle refusal, that
481
- refusal is now the top-level classification (for example `STORAGE_CORRUPT`
482
- instead of a generic transaction failure). The transaction outcome, its
483
- non-retryable classification, and the original transaction error remain
484
- available as the preserved `cause`. BUSY, INDETERMINATE, and unclassified
485
- outcomes propagate exactly as before; nothing is retried or repaired.
486
-
487
- ## 9. B3-P2A Session binding, ownership, leases, and fencing
488
-
489
- Implemented B3-P2A amendment (CE-0002-B3-P2A). Everything in §§1-8 is
490
- preserved: no DDL, trigger, index, or schema-v2 manifest change (P2A writes
491
- only the accepted v2 tables `participant_session`, `participant_ownership`,
492
- and `participant_fencing_high_water`), no change to B2 creation, P1A
493
- migration/recovery, P1B identity, Endpoint binding, membership, join
494
- boundaries, or audit ordering. `delivery_cursor` stays inert. Nothing is
495
- added to the public package surface; there is no delivery API, no adapter
496
- wiring, no background heartbeat, and no takeover.
497
-
498
- ### Scopes
499
-
500
- `attach` and `resume` become operational. `attach` authorizes Session
501
- binding and ownership acquisition; `resume` authorizes renewal, release, and
502
- zero-write Owner verification. `takeover`, `send`, `ack`, and `read` remain
503
- `CAPABILITY_SCOPE_UNSUPPORTED`. Authorization always runs in the same owned
504
- transaction as the mutation and re-validates the host trust root.
505
-
506
- ### SessionRef and binding
507
-
508
- A Session is an opaque, non-secret `ses_<ULID>` SessionRef. It is never a
509
- Participant identity and never a credential. `bindSession` records one
510
- `(participant, session)` row under an `attach` capability; binding confers no
511
- ownership, a duplicate binding is `SESSION_ALREADY_BOUND`, and a Session
512
- bound to another Participant is `SESSION_BOUND_TO_OTHER_PARTICIPANT` (a
513
- Session belongs to exactly one Participant; a Participant may hold many
514
- historical Sessions). Participant creation never creates a Session or
515
- ownership. P2A never detaches Sessions; a detached row is treated as not
516
- bound.
517
-
518
- ### Ownership and fencing
519
-
520
- `acquireOwnership` makes one bound Session the single current Owner of a
521
- Participant with no current Owner. A live lease, including one held by the
522
- requesting Session itself, is `OWNERSHIP_HELD`: no silent adoption, no
523
- takeover. Acquisition allocates the fencing token and writes the ownership
524
- row in one owned transaction. **Superseded by §10:** the P2A text here
525
- allowed acquisition over an *expired* row ("supersession"); R1 (design
526
- clarification Q1) moves every replacement of an existing Owner to the
527
- inactive P2B `takeover` scope.
528
-
529
- **First-token rule:** with no `participant_fencing_high_water` row the first
530
- acquisition allocates token 1 and inserts the row; every later acquisition
531
- allocates exactly high-water + 1 (compare-and-set on the previous value).
532
- The high-water row is never decremented or deleted, so tokens survive
533
- restart, lease expiry, and release and are never reused; counters are per
534
- Participant. Allocation past `Number.MAX_SAFE_INTEGER` is
535
- `FENCING_EXHAUSTED`. Tokens are never derived from timestamps or Session IDs.
536
- An ownership row whose token differs from the high-water, a missing
537
- high-water row, an out-of-range stored token, an invalid stored deadline, or
538
- an ownership row for an unbound Session is `STORAGE_OWNERSHIP_CORRUPT` —
539
- refused, never adopted or repaired.
540
-
541
- ### Owner authorization and leases
542
-
543
- Renewal, release, and verification verify, in order: a currently valid
544
- `resume` capability (Participant, scope, trust generation, revocation,
545
- expiry), the Participant, a bound Session, the Session being the durable
546
- current Owner (`OWNERSHIP_NOT_CURRENT`), the presented fencing token being
547
- current (`FENCING_STALE`), and the lease (`LEASE_EXPIRED`,
548
- `LEASE_CLOCK_REGRESSION`). Ownership is never inferred from a Session ID.
549
- After a takeover (§11) every Owner operation by the previous Session is refused.
550
-
551
- Default TTL 120 s, configurable 30–3600 s (request-validated). 30 s is a
552
- renewal recommendation for hosts, not a scheduler. Time comes only from the
553
- injected clock. Release removes only the ownership row.
554
-
555
- **Superseded by §10:** the P2A text here derived the term start as
556
- `expiresAt - ttl` from the *request* TTL and claimed a rolled-back clock
557
- could never extend a lease. The independent review (MAJOR-1) showed both the
558
- derivation and the claim were unsafe: a request TTL change falsely refused
559
- live Owners as `LEASE_CLOCK_REGRESSION`, and a rollback presented with a
560
- larger TTL could renew and extend. R1 persists the term start. A rollback
561
- that lands inside the current term remains indistinguishable from a valid
562
- instant (refusals are zero-write).
563
-
564
- ### Durable reads
565
-
566
- Private host-local reads only: `readSessionBinding`, `readSessionBindings`,
567
- `readCurrentOwnership` (the durable row regardless of expiry),
568
- `readFencingHighWater` (0 when never allocated), and `readLeaseStatus`
569
- (`UNOWNED`/`ACTIVE`/`EXPIRED`/`CLOCK_REGRESSION`). Each runs against one
570
- read snapshot and applies the same consistency validation.
571
-
572
- ### P1B hardening pins
573
-
574
- The four MINOR gaps from the P1B-R1 final gate are regression-pinned:
575
- missing trust generation during capability verification (`STORAGE_CORRUPT`
576
- on join, bind, sponsored create, and Session attach); corruption-before-conflict
577
- on authorized join and sponsored-create replay; each `recoverTrustRoot`
578
- unwrap guard (the classifier was extracted unchanged as
579
- `classifyRecoveryFailure` and is unit-pinned, plus end-to-end BUSY,
580
- unclassified-rollback, and typed-rollback cases); and the sponsored replay
581
- negative authorization matrix.
582
-
583
- ## 10. B3-P2A-R1 lease term persistence, acquisition boundary, and schema v3
584
-
585
- Remediating amendment (CE-0002-B3-P2A-R1), governed by the versioned P2
586
- ownership contract (`docs/ownership-contract.md`, decisions Q1–Q5). Everything
587
- in §§1-9 is preserved except where §10 explicitly supersedes §9.
588
-
589
- ### Schema v3 (additive, explicit migration only)
590
-
591
- - `participant_ownership.lease_started_at TEXT` (nullable): the persisted
592
- start of the current lease term, written at acquisition and updated at every
593
- renewal. NULL marks a legacy v2 row, which is treated as expired at every
594
- instant: no lease start is fabricated from an untrusted TTL and no v3
595
- operation authorizes against a legacy row.
596
- - `participant_capability.session_id TEXT` (nullable): the durable Session
597
- binding of a `resume` capability. NULL for every other scope and for legacy
598
- v2 rows; a legacy unbound resume capability can never authorize (fail
599
- closed).
600
- - `participant_session_unique_session_id`: durable uniqueness of a Session
601
- across Participants. The v2→v3 migration refuses (`STORAGE_CORRUPT`, zero
602
- writes) when historical rows bind one Session to more than one Participant;
603
- conflicting history is rejected, never repaired.
604
- - Migration paths are explicit and approved: v1→v2 (accepted P1A, unchanged),
605
- v2→v3, and the chain v1→v3. Each step commits independently; interruption
606
- rolls back the interrupted step only. The v2→v3 step re-validates the
607
- existing trust root and never creates, rotates, or deletes the host secret.
608
- Normal open requires the current v3 shape; v1 and v2 stores refuse with
609
- `STORAGE_MIGRATION_REQUIRED`. Fresh v3 and migrated v3 stores converge to a
610
- byte-identical schema manifest.
611
-
612
- ### Lease term model (supersedes §9's derived term start)
613
-
614
- Lease evaluation compares the operation clock against the persisted
615
- boundaries `[leaseStartedAt, expiresAt)` only. A request TTL (default 120 s,
616
- allowed 30–3600 s) is used solely to compute a *new* expiry at acquisition or
617
- renewal and never reinterprets a stored term. `verifyOwnership`,
618
- `releaseOwnership`, and `readLeaseStatus` no longer accept a TTL. Renewal sets
619
- `lease_started_at = now` and refuses to shorten the term
620
- (`LEASE_TERM_SHORTENED`). Exact-expiry refusal is preserved. A wall-clock
621
- rollback before the persisted term start is `LEASE_CLOCK_REGRESSION` and can
622
- never renew or extend a lease; a rollback inside the current term remains
623
- undetectable (documented limitation, zero-write refusals).
624
-
625
- ### Acquisition boundary (design clarification Q1)
626
-
627
- `acquireOwnership` is admitted only when no ownership row exists for the
628
- Participant. Any existing row refuses acquisition: `OWNERSHIP_HELD` while the
629
- lease is live at the operation's clock, `OWNERSHIP_TAKEOVER_REQUIRED` once
630
- expired (including legacy v2 rows). A refused acquisition allocates no fencing
631
- token. **Updated by §11:** CE-0002-B3-P2B activated the `takeover` scope and
632
- implemented explicit takeover; the acquisition boundary itself is unchanged.
633
-
634
- ### Session-bound resume (design clarification Q2)
635
-
636
- A `resume` capability is issued for exactly one currently bound Session
637
- (`sessionId` required at issuance, refused for other scopes) and authorizes
638
- only that Session; classification adds the host-local detail
639
- `SESSION_MISMATCH`. Revoking a resume capability requires presenting its bound
640
- Session. The Session binding narrows authority; it is never a credential, and
641
- no operation is authorized by a Session ID alone.
642
-
643
- ### Regression coverage (R1)
644
-
645
- New real-SQLite pins cover: TTL-independent term evaluation (no false
646
- `LEASE_CLOCK_REGRESSION`), rollback-plus-TTL-widening refusal, persisted term
647
- start on renewal, exact-expiry refusal, expired-Owner renew/release refusal,
648
- expired-Owner acquisition refusal (`OWNERSHIP_TAKEOVER_REQUIRED`), initial
649
- acquisition, fencing monotonicity across release and restart, restart
650
- persistence, v2→v3 migration with legacy-row policy, fresh/migrated manifest
651
- convergence, conflicting-history migration refusal, durable Session
652
- uniqueness, a multi-process renewal-vs-acquisition race, missing trust
653
- generation across all ownership operations, and BUSY/ROLLED_BACK/
654
- INDETERMINATE classification with privacy and zero-write refusals.
655
-
656
- ## 11. B3-P2B durable takeover, supersession, and reconciliation
657
-
658
- Additive amendment (CE-0002-B3-P2B). No schema change: takeover reuses the
659
- accepted v3 columns. Everything in §§1-10 is preserved except where §11
660
- explicitly updates §10. CE-0002-B3-P2B-R1 amends this section further (see
661
- "Transaction-time clock sampling" below), remediating the independently
662
- confirmed stale pre-lock clock defect without changing any takeover
663
- authority, eligibility, fencing, supersession, or reconciliation contract.
664
-
665
- ### Takeover authority
666
-
667
- The `takeover` capability scope is operational and Session-bound, consistent
668
- with the accepted resume model: issuance requires `sessionId` naming a
669
- currently bound Session of the Participant (the prospective new Owner),
670
- `sessionId` is refused for non-Session-bound scopes, classification compares
671
- the durable binding inside the mutation's transaction (`SESSION_MISMATCH`),
672
- and revocation requires presenting the bound Session. A Session ID alone
673
- never grants takeover authority; the bearer token, Participant binding,
674
- scope, trust generation, revocation, and expiry checks are unchanged.
675
- `send`/`ack`/`read` remain `CAPABILITY_SCOPE_UNSUPPORTED`.
676
-
677
- ### Takeover eligibility
678
-
679
- `takeoverOwnership` replaces an EXISTING ownership row whose lease is expired
680
- at the operation's clock, including a legacy v2 row (NULL `lease_started_at`,
681
- expired at every instant). It refuses: a live Owner (`OWNERSHIP_HELD`,
682
- evaluated against the persisted term — one millisecond before expiry still
683
- refuses, exact expiry is eligible); a clock-regressed lease
684
- (`LEASE_CLOCK_REGRESSION`); a Participant with no ownership row
685
- (`OWNERSHIP_TAKEOVER_INELIGIBLE` — initial acquisition remains the `attach`
686
- operation); corrupt ownership state (`STORAGE_OWNERSHIP_CORRUPT`, never
687
- repaired); and any invalid, revoked, expired, wrong-Participant,
688
- wrong-Session, wrong-scope, or wrong-generation capability
689
- (`CAPABILITY_REJECTED`). There is no force takeover of a live Owner in this
690
- phase.
691
- ### Transaction-time clock sampling (B3-P2B-R1)
692
-
693
- **Updates §10 lease-time wording and resolves the R1 review's MINOR-1.** P2B
694
- sampled each operation's clock before `BEGIN IMMEDIATE`; an operation that
695
- waited for the SQLite writer lock then evaluated authorization and lease
696
- state against the stale pre-lock instant (the independently confirmed
697
- MAJOR-1: a renewal initiated before expiry but serialized after it committed
698
- and revived an expired lease; a capability that expired during the wait was
699
- accepted).
700
-
701
- R1 defines one authoritative operation-time sampling point for every owned
702
- mutating transaction: inside the transaction, after `BEGIN IMMEDIATE` has
703
- acquired the writer lock — `BEGIN IMMEDIATE → sample now → validate
704
- authority → evaluate current state → mutate → COMMIT`. All checks within one
705
- mutation use this one consistent instant. This governs `bindSession`,
706
- `acquireOwnership`, `renewLease`, `releaseOwnership`, `verifyOwnership`,
707
- `takeoverOwnership`, and the capability/membership mutations
708
- (`createParticipant` sponsor authorization, `bindEndpointRef`,
709
- `issueCapability`, `revokeCapability`, `joinExchange`). Lease start and
710
- expiry derive from the transaction-time clock; capability expiry is
711
- evaluated at the transaction-time clock, so a capability that expired during
712
- a lock wait is never accepted. Request validation (shape, TTL range,
713
- identities) still precedes the transaction and performs no state-dependent
714
- check.
715
-
716
- Lock-wait semantics, now defined: a renewal initiated before expiry but
717
- serialized after it refuses `LEASE_EXPIRED`; a takeover initiated before
718
- expiry but serialized after it is eligible and may win; a takeover
719
- serialized while the lease is live refuses `OWNERSHIP_HELD`; a capability
720
- that expired during the wait refuses `CAPABILITY_REJECTED`. Every such
721
- refusal is zero-write and allocates no fencing token.
722
-
723
- Preserved: exact-expiry behavior (`now >= expiresAt` is expired),
724
- clock-regression refusal, the injected-clock test seam (invoked at the
725
- transaction-time sampling point), and the documented wall-clock limitation —
726
- a rollback landing inside the current term remains indistinguishable from a
727
- valid instant; no cross-transaction monotonic clock is claimed, no scheduler
728
- and no global clock is introduced. B2 Exchange/Message creation samples its
729
- clock during candidate generation, before `BEGIN IMMEDIATE` (wording
730
- corrected by CE-0002-B3-P2C-A); its timestamps are recorded creation metadata
731
- that authorize nothing, and the accepted B2 contract is unchanged.
732
- Migration/recovery/initialization `appliedAt` ledger timestamps likewise
733
- authorize nothing and are unchanged. Regression pins:
734
- `test/storage/lease-lock-wait.test.ts` (real OS processes, real writer-lock
735
- contention, observable initiation, deadline waits). Worker initiation
736
- markers are published atomically (CE-0002-B3-P2C-A-R1): the complete
737
- marker is staged beside its final path and renamed into place, so a
738
- parent can never read a partially written marker; the scenarios and
739
- timing assertions are unchanged.
740
-
741
- ### Atomic replacement and fencing transition
742
-
743
- Eligibility, fencing allocation, and the Owner replacement are one owned
744
- IMMEDIATE transaction: the high-water advances by exactly one (compare-and-set
745
- on the previous value, `FENCING_EXHAUSTED` at the ceiling) and the ownership
746
- row is rewritten in place (new Session, new token, `lease_started_at = now`,
747
- `expires_at = now + ttl`), guarded by the exact pre-read values so any
748
- interleaved change fails the single-row check and rolls back. Exactly one
749
- concurrent takeover wins; losers serialize into `OWNERSHIP_HELD` or time out
750
- as `STORAGE_TRANSACTION_BUSY` (retryable). No partial fencing allocation, no
751
- partial replacement, no token reuse, zero-write refusals. A takeover racing a
752
- renewal of a live lease refuses whenever the lease is live at the takeover's
753
- serialization instant (see "Transaction-time clock sampling" below): a live
754
- lease at serialization is `OWNERSHIP_HELD`, regardless of what the clock read
755
- at initiation. A renewal serialized while its lease is still live extends it;
756
- a renewal serialized after expiry refuses `LEASE_EXPIRED` and can never revive
757
- it. A renewal/takeover race is therefore decided by the durable lease state at
758
- each operation's own serialization instant — exactly one winner, no
759
- stale-time distortion in either direction.
760
-
761
- ### Supersession
762
-
763
- After a successful takeover the previous Session is no longer the current
764
- Owner: its fencing token is stale (`FENCING_STALE`), its `resume` capability
765
- cannot renew, release, or verify the new Owner (`OWNERSHIP_NOT_CURRENT` — the
766
- durable ownership row decides, never the Session ID). Historical Session
767
- bindings are preserved for audit continuity. Takeover never creates a
768
- Participant, never rewrites Endpoint bindings, Exchange membership, join
769
- boundaries, or audit history, and never mutates capability rows.
770
-
771
- ### Recovery and reconciliation
772
-
773
- An uncertain takeover outcome (for example an INDETERMINATE transaction
774
- result) is reconciled explicitly through `reconcileTakeover`, a zero-write
775
- read that compares the evidence the caller presents (Participant, target
776
- Session, the exact persisted term boundaries, optional fencing token) against
777
- the durable row in one consistent snapshot — never a Session ID alone:
778
-
779
- - `COMMITTED`: the current row matches the presented evidence exactly. This is
780
- effect-level recognition of the durable state, not operation-level
781
- attribution of one invocation and not an exactly-once claim: a retry of the
782
- same logical request persists identical evidence, so the match cannot say
783
- which invocation wrote the row. Do not retry. A later authorized takeover or
784
- renewal may still supersede this term afterwards.
785
- - `NO_TRACE`: the current state carries no trace of the presented evidence (no
786
- row, a legacy row, a different Owner Session, or a same-Session row whose
787
- term predates the presented evidence). This is **not** proof that the
788
- original invocation never committed: a request that did not commit, a
789
- refused request, and a committed request whose effects were later superseded
790
- are indistinguishable post-hoc. A fresh attempt is safe only because it is
791
- freshly authorized and eligibility-checked, never because `NO_TRACE` proved a
792
- non-commit.
793
- - `EVIDENCE_CONFLICT`: the target Session is the current Owner under
794
- different term or token evidence — the current state was installed by a
795
- different request. Never auto-retry; operator review.
796
-
797
- Documented limitations (fail-closed, no invented exactly-once semantics): a
798
- refused and a rolled-back takeover leave identical durable state; a committed
799
- takeover later superseded reports `NO_TRACE`; a committed retry with identical
800
- parameters is the same logical request and indistinguishable from the
801
- original commit. There are no background recovery workers.
802
-
803
- #### Evidence availability after an uncertain outcome
804
-
805
- `takeoverOwnership` samples its operation clock **inside** the owned
806
- `BEGIN IMMEDIATE` transaction (see "Transaction-time clock sampling" above).
807
- That instant is not an ordinary caller-supplied request field: `leaseStartedAt`
808
- is exactly that sample and `expiresAt` is `sample + ttl`. The exact term is
809
- therefore normally available to the caller only from the successful return
810
- value of `takeoverOwnership`, or when the caller itself supplies and records
811
- the operation clock seam. A caller using the default wall clock whose call
812
- ended INDETERMINATE does **not** know the exact term, and pre-call wall-clock
813
- sampling does not reconstruct it (the sample is taken after the writer lock is
814
- acquired, a lock wait of unrecorded, caller-unknown duration later).
815
-
816
- `reconcileTakeover` currently requires `participantId`, `sessionId`,
817
- `leaseStartedAt`, and `expiresAt`; `fencingToken` is optional. A caller must
818
- not fabricate, estimate, or round term boundaries to satisfy that input shape:
819
- a term guessed later than the durable one misreads a committed takeover as
820
- `NO_TRACE`, and a term guessed earlier misattributes a same-Session row as
821
- `EVIDENCE_CONFLICT`. When exact term evidence is unavailable the outcome simply
822
- remains unknown to the caller. `reconcileTakeover` accepts no UNKNOWN input and
823
- returns no UNKNOWN disposition — preserving that uncertainty is a caller-level
824
- judgment, not an existing API disposition, and the three dispositions above
825
- keep their exact meanings.
826
-
827
- INDETERMINATE is not ROLLED_BACK. A connection invalidated by an indeterminate
828
- transaction outcome must not be reused; recovery inspection requires a freshly
829
- opened store. A lost acknowledgement never authorizes a blind retry.
830
-
831
- A caller may also snapshot `readFencingHighWater` for the Participant before
832
- the call. If a later valid read of the same Participant still returns the same
833
- value, then no fencing allocation — and therefore no successful takeover or
834
- acquisition for that Participant — committed between the two reads, assuming
835
- both reads are valid, correctly ordered, and about the same Participant. An
836
- increased high-water proves only that some allocation committed; it never
837
- identifies which invocation committed, never proves that this caller's takeover
838
- committed, and never establishes a durable ownership lease (only the ownership
839
- row does). High-water evidence is effect-level only.
840
-
841
- `reconcileTakeover` still has no production caller
842
- (CE-TAKEOVER-RECONCILIATION-EVIDENCE-001): a real-clock caller cannot
843
- reconstruct exact term evidence after an INDETERMINATE result and therefore
844
- must not fabricate evidence or retry blindly.
845
-
846
- CE-TAKEOVER-RECOVERY-CALLER-001 is resolved by the explicit operator-only
847
- caller in `src/host/ownership-recovery.ts` and
848
- `scripts/recover-stale-ownership.mjs`. It requires an exact Endpoint plus the
849
- operator-confirmed old Session, fencing token, lease start, and expiry. It
850
- refuses absent, mismatched, clock-regressed, or live ownership before recovery
851
- writes; uses only `bindSession`, Session-bound capabilities,
852
- `takeoverOwnership`, `releaseOwnership`, and `detachSession`; preserves
853
- monotonic fencing; and emits a capability-free structured receipt. It is not
854
- an MCP/Pi tool and is never invoked by normal host startup. Any unknown outcome
855
- stops for fresh durable inspection without automatic retry.
856
-
857
- ### Legacy ownership recovery
858
-
859
- A migrated v2 ownership row (NULL `lease_started_at`) never authorizes as a
860
- live lease and is never repaired. It is takeover-eligible: an explicit
861
- Session-bound takeover replaces it with a fully persisted v3 term
862
- (`lease_started_at = now`), allocating the fencing token strictly greater
863
- than the legacy token (the v2 high-water survives migration untouched).
864
-
865
- ## 12. B3-P2C-A irreversible Session lifecycle and schema v4
866
-
867
- Additive amendment (CE-0002-B3-P2C-A), governed by the accepted
868
- CE-0002-B3-P2C-D0 design and recorded in `docs/ownership-contract.md`.
869
- Everything in §§1-11 is preserved. No detach operation, no capability scope
870
- change, no delivery.
871
-
872
- ### Schema v4 (additive triggers, explicit migration only)
873
-
874
- `V4_ADDITIVE_SQL` appends seven triggers and nothing else:
875
- `participant_session_insert_attached`, `participant_session_nodelete`,
876
- `participant_session_identity_immutable`, `participant_session_detach_once`,
877
- `participant_session_detach_not_owner`,
878
- `participant_ownership_session_attached_insert`, and
879
- `participant_ownership_session_attached_update`. Fresh initialization applies
880
- `V4_FOUNDATION_SQL = V3_FOUNDATION_SQL + V4_ADDITIVE_SQL` with one v4
881
- foundation ledger row; fresh and migrated v4 stores converge to one
882
- byte-identical manifest. The triggers fire only on defects or privileged
883
- tampering (code checks refuse first, typed and zero-write); an actor able to
884
- drop them is outside the protection claim (`CE-STORAGE-IMMUTABILITY-V2`
885
- unchanged).
886
-
887
-
888
- ### Timestamp validation boundary (CE-0002-B3-P2C-A-R1)
889
-
890
- The detach transition is the only write path that can set `detached_at`,
891
- and schema v4 enforces the accepted canonical representation on it, not
892
- only the one-way revision transition:
893
-
894
- - **SQLite enforces**, on the `participant_session_detach_once` UPDATE path
895
- only: `detached_at` is a canonical UTC instant — GLOB shape
896
- (`YYYY-MM-DDTHH:MM:SS.mmmZ`), a `strftime` parse round trip (so month 13,
897
- February 30, non-leap February 29, day 00, minute 60, and leap seconds
898
- are refused rather than silently normalized), and hour < 24 (SQLite's own
899
- date parser accepts `24:00:00`; the accepted representation does not) —
900
- and `bound_at` is canonical too, with `detached_at >= bound_at` compared
901
- as text (safe: fixed-width canonical UTC instants order chronologically
902
- as text). NULL and the empty string are refused, and a STRICT TEXT column
903
- cannot hold BLOB, so no wrong storage class can reach the predicate as
904
- anything but non-matching text.
905
- - **The application parser enforces** (`session-state.ts`): the same
906
- canonicality on every row read — shape, `Date.parse` finiteness, and an
907
- `toISOString` round trip for `bound_at` and `detached_at` — plus the
908
- identity patterns and the two-state revision matrix. It remains the
909
- authority: the insert trigger checks only born-ATTACHED, so a privileged
910
- writer can still insert a malformed `bound_at`; such a row is refused as
911
- `STORAGE_OWNERSHIP_CORRUPT` on every read, and the detach path refuses it
912
- fail-closed.
913
-
914
- **Trust boundary.** The triggers protect only while they exist and run. A
915
- connection with `recursive_triggers` disabled bypasses the delete trigger
916
- through conflict-resolution (`INSERT OR REPLACE`) deletes; the storage
917
- connection asserts `recursive_triggers=ON` (with `foreign_keys=ON` and
918
- `trusted_schema=OFF`) on every open. An actor with unrestricted database
919
- write access can drop the triggers or rewrite rows directly — no protection
920
- is claimed against that (`CE-STORAGE-IMMUTABILITY-V2`, unchanged).
921
-
922
- ### Version recognition and migration
923
-
924
- - Normal open requires v4; v1, v2, and v3 stores refuse
925
- `STORAGE_MIGRATION_REQUIRED` with zero writes. A v4 store carries
926
- `user_version` 4, so every older binary (supported maximum 3) refuses it
927
- with `STORAGE_SCHEMA_TOO_NEW`.
928
- - Approved explicit paths: single steps 1→2, 2→3, 3→4 and chains 1→3, 2→4,
929
- 1→4. Each step is one owned IMMEDIATE transaction and commits
930
- independently; an interrupted step rolls back to a valid store at the
931
- previous version, and the remaining step can be retried. Intermediate
932
- targets (v2, v3) are proven by a shape-validated proof open.
933
- - The v3→v4 step re-validates the existing trust root (never creates,
934
- rotates, or deletes the secret), preserves every Session, ownership,
935
- fencing, and capability row untouched, and refuses (`STORAGE_CORRUPT`, zero
936
- writes, never repaired) any pre-v4 Session row that is not exactly ATTACHED
937
- r1, or any ownership row referencing a detached Session. For v2 and v3
938
- sources this precondition also runs on the disposable preflight snapshot,
939
- so a chain refuses before any step commits; it is re-checked on the live
940
- writer inside the v4 step.
941
-
942
- ### Session lifecycle validation and read
943
-
944
- ATTACHED (NULL, r1) and DETACHED (canonical instant ≥ `bound_at`, r2) are the
945
- only valid Session rows; anything else is `STORAGE_OWNERSHIP_CORRUPT`
946
- wherever a Session row is read, including capability issuance. A DETACHED
947
- Session is never a current binding (`SESSION_NOT_BOUND`), never receives a
948
- new Session-bound capability, and can never be the target of acquisition or
949
- takeover. `readSessionLifecycle` is the private host-local, zero-write,
950
- single-snapshot read (`ATTACHED` / `DETACHED` / `NOT_FOUND`); it is not
951
- re-exported and its refusals use the fixed sanitized details.
952
-
953
- ### Regression coverage
954
-
955
- `test/storage/session-lifecycle.test.ts`: fresh v4 shape, every trigger
956
- (including standalone identity enforcement), Session-ID reuse refusal,
957
- current-Owner detach guard (live, expired, after supersession), ownership
958
- referencing a detached Session, detached-Session refusals across every
959
- operation, malformed-state matrix with privacy and zero-write assertions,
960
- restart persistence, the lifecycle read, v3→v4 / v2→v4 / v1→v4 migrations,
961
- interruption and per-step atomicity, trust-root continuity, zero-write
962
- preflight refusal of foreign lifecycle state, and manifest convergence.
963
- CE-0002-B3-P2C-A-R1 adds the trigger-level timestamp matrix: NULL, empty,
964
- wrong storage class, malformed, noncanonical, and calendar-invalid
965
- `detached_at` values, `detached_at` earlier than `bound_at`, and detach
966
- over a malformed `bound_at` are all refused by SQLite itself, with the
967
- application-level refusals still pinned.
968
-
969
- CE-0002-B3-P2C-B adds the authorized detach surface:
970
- `test/storage/detach-lifecycle.test.ts` (authorization matrix incl. forged /
971
- expired / revoked / wrong-scope / wrong-Session capabilities; the full
972
- ownership-interaction matrix incl. no-ownership, released, superseded,
973
- active / expired / legacy / clock-regressed current Owner, clock regression
974
- before `bound_at`, corrupt ownership, and serialized concurrent
975
- release / takeover / renew / detach outcomes; capability lifecycle pins incl.
976
- `SESSION_DETACHED` host-local status, opaque caller refusals, no bulk
977
- revocation, and revocation-refuses-like-expiry; and the
978
- `reconcileDetach` COMMITTED / NO_TRACE / EVIDENCE_CONFLICT matrix);
979
- `test/storage/detach-crash.test.ts` (real OS-process SIGKILL at the
980
- before-commit and after-commit boundaries, with durable forensics and
981
- fail-closed reconciliation: rollback → NO_TRACE + fresh-attempt success,
982
- commit → COMMITTED + terminal retry refusal); and the lock-wait scenarios
983
- F and G in `test/storage/lease-lock-wait.test.ts` (real processes, real
984
- writer lock: a detach serialized after lease expiry still refuses
985
- `SESSION_IS_CURRENT_OWNER` zero-write, and a non-Owner detach serialized
986
- after the lock wait commits at the serialization instant without touching
987
- ownership or fencing).
988
-
989
- ## B3-P3A — Session-authorized durable send/read (CE-0002-B3-P3A)
990
-
991
- Status: **implemented as a private storage slice**. Schema v4 and the frozen
992
- public `Message` entity are unchanged. This amendment does not define endpoint
993
- delivery, ACK, workers, retries, reconciliation, Pi runtime integration, or a
994
- public payload-listing API. The broader P3 delivery scope remains outstanding.
995
-
996
- ### Preserved B2 creation
997
-
998
- `createMessage` remains the accepted trusted-host operation: existing callers
999
- do not acquire a Session requirement and retain the same request digest,
1000
- Exchange-scoped idempotency, replay-before-new-write admission, atomic
1001
- Message/idempotency/audit triple, audit ordering, payload handling, and
1002
- BUSY/ROLLED_BACK/INDETERMINATE classifications. P3A reuses its extracted
1003
- transaction-scoped persistence helper; it does not rebuild the Message store.
1004
-
1005
- ### Authorized send
1006
-
1007
- `sendMessage` is private storage authority. It captures and validates the
1008
- request before `BEGIN IMMEDIATE`, then samples one authoritative instant after
1009
- the writer lock is held. In that same transaction it validates, in order: the
1010
- exact Session-bound `send` capability and ATTACHED lifecycle; current durable
1011
- Owner; presented monotonic fencing token; active persisted lease; Exchange
1012
- membership; and the sender Participant's immutable `(adapter, endpointId)`
1013
- binding. A Session ID or caller label is never authority.
1014
-
1015
- All checks above precede protected idempotency replay. An authorized historical
1016
- replay remains zero-write even after Exchange close; a new Message then applies
1017
- the accepted OPEN/no-disposition admission. New persistence atomically commits
1018
- the Message, its idempotency record, and one `message_created` audit event.
1019
- No result escapes before COMMIT. There is no blind retry after an INDETERMINATE
1020
- outcome and no exactly-once or remote-duplicate-prevention claim.
1021
-
1022
- ### Protected recipient metadata read
1023
-
1024
- `readMessageMetadata` is a repeatable private operation serialized under the
1025
- same writer lock. It requires the exact Session-bound `read` capability, an
1026
- ATTACHED current Owner with active lease and current fencing, durable membership,
1027
- the requested Exchange identity, and a stable endpoint binding matching the
1028
- stored recipient. Missing and wrong-recipient identities share the same opaque
1029
- eligibility refusal. It returns only the frozen `Message` metadata plus a private
1030
- `auditSequence`; payload bytes never leave this API.
1031
-
1032
- Eligibility is `message_created.sequence > exchange_membership.join_boundary_seq`.
1033
- The correlated audit row must be unique and exactly match the Message identity,
1034
- Exchange, creation instant, payload digest, and length; missing, duplicate, or
1035
- inconsistent correlation fails closed as durable corruption. Audit sequence is
1036
- a private projection and is not a new `Message.seq` property.
1037
-
1038
- ### Cursor and remaining delivery scope
1039
-
1040
- P3A never inserts or updates `delivery_cursor`. Sending, replaying, reading,
1041
- refusing, rolling back, contending, crashing, and recovering therefore fabricate
1042
- no ACK progress. `ack` remains `CAPABILITY_SCOPE_UNSUPPORTED`. ACK/cursor
1043
- advancement, endpoint delivery, workers, automatic retry, remote duplicate
1044
- prevention, delivery reconciliation, and takeover-recovery API redesign remain
1045
- outside this amendment.
1046
-
1047
- ### P3A evidence
1048
-
1049
- `test/storage/message-send-read.test.ts` pins authority-before-replay, B2
1050
- preservation, exact capability/Session/Participant/Owner/lease/fencing checks,
1051
- membership and endpoint binding, close/replay admission, recipient-only and
1052
- join-boundary visibility, exact audit correlation, rollback, BUSY,
1053
- INDETERMINATE fresh-store inspection, metadata privacy, and cursor non-mutation.
1054
- `test/storage/message-send-concurrency.test.ts` uses independent OS processes
1055
- for same-key sends and send-versus-release/takeover serialization.
1056
- `test/storage/message-send-crash.test.ts` uses real SIGKILL at after-BEGIN,
1057
- after-Message, after-idempotency, after-audit, and after-COMMIT boundaries and
1058
- proves only a complete transaction survives.
1059
-
1060
- ## B3-P3C — Minimal Audit correlation index (CE-ARCH-P3C-INDEX-001)
1061
-
1062
- Schema v5 appends exactly one non-unique index:
1063
- `idx_audit_event_correlation ON audit_event(exchange_id, kind, subject_id)`.
1064
- Every Schema v1-v4 SQL string, object name, and checksum remains frozen. The
1065
- index accelerates the existing exact P3A correlation predicate without asserting
1066
- uniqueness or changing Message, Audit Sequence, membership, endpoint, capability,
1067
- Session, lease, fencing, or ACK semantics.
1068
-
1069
- Fresh initialization writes the v5 foundation ledger and exact v5 manifest.
1070
- Existing v4 stores require the explicit approved `4→5` migration; normal open
1071
- never migrates. Historical approved paths through v4 remain available but stop at
1072
- the exact v4 shape. The v5 step re-validates the host trust root, creates the
1073
- index, appends the v5 ledger row, and advances `user_version` in one owned
1074
- `BEGIN IMMEDIATE` transaction. A failure proven to have rolled back before commit
1075
- returns the store to exact v4. An indeterminate commit outcome does not establish
1076
- whether the store is v4 or v5: the operator must inspect the durable store shape
1077
- before any retry, and must never retry blindly. A preexisting same-name index is
1078
- schema drift and refuses; the migration does not use `IF NOT EXISTS`, repair, or
1079
- downgrade.
1080
-
1081
- P3A exact-correlation validation retains every existing check and now reads at
1082
- most two matching rows. Zero rows, two rows, or more than two rows all remain
1083
- durable corruption; the sole row must still match Exchange, Message subject,
1084
- creation instant, digest, length, event schema, outcome, and private revision.
1085
- The index cannot prove existence, uniqueness, field agreement, or absence of
1086
- orphan rows. The Schema v5 amendment itself added no Inbox API; the separate
1087
- bounded private operation below uses that frozen schema without changing it.
1088
-
1089
- ## B3-P3C — Bounded storage Inbox Discovery (HANDOFF-731845)
1090
-
1091
- Status: **implemented as a private storage slice**. The implementation
1092
- adds no schema object, migration, table, index, persistent cursor, public package
1093
- export, provider integration, background poller, retry loop, ACK behavior, delivery
1094
- cursor behavior, or Completion Authority.
1095
-
1096
- ### Private operation and authority
1097
-
1098
- `discoverInboxMessages` in `src/storage/inbox-discovery.ts` reuses the exact
1099
- Session-bound `read` capability and the existing serialized `BEGIN IMMEDIATE`
1100
- transaction boundary. Before reading protected metadata it validates request shape,
1101
- capability and Exchange/Participant/Session binding, ATTACHED lifecycle, current
1102
- ownership, current fencing token, active lease, Exchange membership, and the
1103
- Participant's immutable endpoint binding. Refusals retain the existing sanitized
1104
- error taxonomy, and transaction BUSY/ROLLED_BACK/INDETERMINATE classifications are
1105
- unchanged.
1106
-
1107
- ### Bounded Audit-first enumeration
1108
-
1109
- The operation computes `max(afterAuditSequence, joinBoundarySeq)` and reads at most
1110
- `rawScanLimit` Audit rows for the Exchange using `sequence > ? ORDER BY sequence
1111
- ASC LIMIT ?`. It never uses Message sequence, timestamps, `OFFSET`, or `K+1`. The
1112
- private implementation limits are 50 eligible Messages and 2,000 raw Audit rows;
1113
- callers may request smaller positive safe-integer limits only, and `pageSize` may
1114
- not exceed `rawScanLimit`. These are implementation parameters, not frozen protocol
1115
- constants.
1116
-
1117
- Each `message_created` candidate loads only Message metadata—never `payload_body`—
1118
- then invokes the unchanged Schema v5 exact-correlation lookup with `LIMIT 2`. That
1119
- validator still requires exactly one matching Audit and validates Exchange, subject,
1120
- event kind/schema, Audit Sequence, creation instant, digest, length, revision, and
1121
- outcome. Every examined raw row must use the recognized protocol or private membership
1122
- Audit vocabulary and valid identity/sequence fields. An observed missing Message,
1123
- duplicate correlation, malformed metadata or stable Participant endpoint binding, or
1124
- field mismatch fails the whole operation without returning partial metadata. Valid
1125
- Messages are filtered against the authorized Participant's stable recipient endpoint.
1126
-
1127
- The result is frozen `{ messages, continuationAuditSequence,
1128
- scanBudgetExhausted }`. A non-null continuation is exactly the last raw Audit
1129
- Sequence actually examined, including filtered events. It is null when no raw row
1130
- was examined. Reaching the eligible-message limit stops immediately without
1131
- advancing past unexamined rows. `scanBudgetExhausted` is true only when the complete
1132
- raw budget was examined and does not assert that another eligible Message exists.
1133
- The continuation is stateless caller input on a later request; it is never persisted
1134
- or interpreted as ACK progress.
1135
-
1136
- ### Integrity limitation and evidence
1137
-
1138
- Audit-first discovery cannot find a Message that has no `message_created` Audit row,
1139
- so an empty bounded result is not proof of global database integrity and the operation
1140
- does not claim to detect every orphaned Message. This is deliberate: observable
1141
- corruption in an inspected `message_created` candidate fails closed, while unreferenced
1142
- Message rows remain outside the bounded Audit window.
1143
-
1144
- `test/storage/inbox-discovery.test.ts` covers authority, pagination, recipient and
1145
- Exchange filtering, join boundaries, scan limits, corruption, privacy, zero writes,
1146
- BUSY and INDETERMINATE classification, restart behavior, and query plans.
1147
- `test/storage/inbox-discovery-concurrency.test.ts` uses independent OS processes to
1148
- prove send/list, revocation/list, and release/list valid before-or-after outcomes, plus
1149
- a deterministically held Inbox transaction that excludes an overlapping sender.
1150
-
1151
- ## B3-P4C — Schema v6 independent payload capability (HANDOFF-427916)
1152
-
1153
- Status: **implemented for schema and capability authority only**. This phase adds
1154
- no payload-read Storage operation, Session Host issuance, Pi tool, delivery behavior,
1155
- ACK, cursor mutation, receipt, consumption state, takeover, or Completion Authority.
1156
-
1157
- ### Schema v6
1158
-
1159
- Schema v6 changes only the closed `participant_capability.scope` vocabulary by
1160
- adding `payload_read`. Every Schema v1-v5 SQL string and checksum remains frozen.
1161
- The explicit v5→v6 migration creates `participant_capability_v6`, copies every
1162
- column and row, verifies equal counts plus bidirectional `EXCEPT` equivalence, drops
1163
- the v5 table, and renames the replacement. The same owned `BEGIN IMMEDIATE` step
1164
- then requires an empty `PRAGMA foreign_key_check`, appends the checksummed v6
1165
- migration ledger row, and advances `user_version` to 6. Any proven failure rolls
1166
- the whole v6 step back to a valid v5 Store; an indeterminate outcome requires
1167
- durable shape inspection and is never retried automatically.
1168
-
1169
- Fresh v6 initialization applies the unchanged v5 foundation followed by the exact
1170
- same v6 rebuild SQL. Fresh and migrated Stores therefore converge on one strict
1171
- approved manifest. Normal Store open accepts only v6 and returns
1172
- `STORAGE_MIGRATION_REQUIRED` for recognized v1-v5 Stores; migration remains an
1173
- explicit operator action. Approved chains from every v1-v5 source to v6 execute
1174
- historical steps in order, with one transaction and commit boundary per step.
1175
-
1176
- ### Independent `payload_read` authority
1177
-
1178
- `payload_read` is a new P4C operational, Session-bound scope. The historical P3A
1179
- scope list remains exactly `send` and `read`; `read` remains metadata-only and
1180
- cannot authorize payload disclosure. Capability HMAC derivation includes the exact
1181
- scope, so `read` and `payload_read` tokens are cryptographically non-interchangeable.
1182
-
1183
- Issuance requires the same existing durable ATTACHED Session binding as other
1184
- Session-bound scopes. Participant binding, Session binding, trust generation,
1185
- revocation, expiry, and DETACHED lifecycle invalidation are inherited unchanged.
1186
- The shared current-Owner authorization primitive accepts `payload_read` as an exact
1187
- future operation scope, preserving its ownership, fencing, and active-lease checks.
1188
- No component automatically issues this capability in this phase, and no plaintext
1189
- bearer token is persisted, logged, or exposed through a public DTO.
1190
-
1191
- Evidence is pinned by `test/storage/schema-v6.test.ts` and
1192
- `test/storage/payload-read-capability.test.ts`, plus the unchanged migration, Store,
1193
- capability, messaging, Inbox, ownership, and recovery regression suites.
1194
-
1195
- ## B3-P4D — Authorized Message payload read (HANDOFF-583207)
1196
-
1197
- Status: **implemented across Storage, the Pi session host, and the operator-opted-in
1198
- Pi extension tool**. Schema v6, the `payload_read` capability, and every frozen
1199
- contract from B3-P4C are unchanged; this amendment adds no schema object,
1200
- capability scope, ACK, cursor, receipt, delivery lifecycle, or Completion
1201
- Authority semantics.
1202
-
1203
- ### Private Storage operation
1204
-
1205
- `readMessagePayload` in `src/storage/messaging.ts` takes the same request shape
1206
- as the metadata read and the same owned `BEGIN IMMEDIATE` serialization. Inside one
1207
- transaction it authorizes the exact `payload_read` scope (never the metadata
1208
- `read` scope, and vice versa), the ATTACHED Session, current Owner, current fencing
1209
- token, and active lease; then Exchange membership, Message metadata, the opaque
1210
- missing/wrong-recipient refusal, the recipient endpoint binding, the exact
1211
- `message_created` audit correlation, and the recipient's join boundary — all
1212
- metadata-only. Only after that chain passes does `readMessagePayloadBodyInTransaction`
1213
- in `src/storage/creation.ts` materialize `payload_body`, validate the BLOB type,
1214
- exact byte length, and SHA-256 digest against the authorized metadata, and return
1215
- a fresh complete byte copy after commit. The operation is a pure read: repeated
1216
- authorized reads return identical bytes and no Message, Audit, receipt, cursor,
1217
- lease, ownership, or capability state ever changes. `DELIVERY_UNKNOWN` stays
1218
- `DELIVERY_UNKNOWN`.
1219
-
1220
- ### Session host and Pi extension
1221
-
1222
- `CeSessionHost.readPayload` keeps the raw Store and the plaintext capability
1223
- inside the host/storage boundary. The `payloadRead.enabled` operator policy —
1224
- exact boolean `true` only; missing, false, or malformed fails closed — is fixed
1225
- for the lifetime of a host instance, gates capability issuance in `beginSession`
1226
- and validated `resume` alike, and answers a fixed sanitized
1227
- `CE_HOST_PAYLOAD_DISABLED` when disabled. The fixed exposure limit is 65,536
1228
- encoded bytes, checked before decoding (`CE_HOST_PAYLOAD_TOO_LARGE`), and decoding
1229
- is strict UTF-8 (`CE_HOST_PAYLOAD_INVALID_UTF8`); nothing partial ever escapes.
1230
-
1231
- The extension registers `ce_read_payload` (input: `messageId` only) only when the
1232
- opt-in is enabled — a disabled deployment registers no payload tool at all. Every
1233
- invocation reads the guarded current Pi context, resolves the allowlist, checks the
1234
- startup binding, and delegates synchronously. A successful result is a fixed
1235
- untrusted-content warning plus the exact decoded text; the payload never appears
1236
- in details, logs, failures, or mappings, and no automatic ACK, consumption, polling,
1237
- injection, or takeover exists.
1238
-
1239
- Evidence: `test/storage/message-payload-read.test.ts`,
1240
- `test/endpoints/pi/session-host-payload.test.ts`, and
1241
- `test/endpoints/pi/extension-payload.test.ts`.