@zieglar/pi-chat-exchange 0.2.0 → 0.2.1
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.
- package/README.md +95 -47
- package/dist/bin/ce-native.js +119 -0
- package/dist/control/mcp/server.js +1 -1
- package/dist/runtime/diagnostics.js +2 -2
- package/dist/runtime/executables.js +21 -26
- package/dist/runtime/native-readiness.js +131 -0
- package/dist/storage/connection.js +4 -3
- package/dist/storage/filesystem.js +58 -3
- package/dist/storage/native-artifact.js +234 -0
- package/dist/storage/native-compat.js +65 -0
- package/dist/storage/runtime.js +201 -58
- package/dist/storage/sqlite-driver-node.js +66 -0
- package/dist/storage/sqlite-driver-rust.js +121 -0
- package/dist/storage/sqlite-driver-selection.js +86 -0
- package/dist/storage/sqlite-driver.js +4 -0
- package/dist/storage/store.js +3 -3
- package/dist/storage/transaction.js +20 -23
- package/dist/tunnel/codes.js +1 -1
- package/package.json +8 -20
- package/pi-extension/index.ts +34 -0
- package/CHANGELOG.md +0 -70
- package/docs/architecture.md +0 -170
- package/docs/chatgpt-installation.md +0 -149
- package/docs/delivery-ack-contract.md +0 -86
- package/docs/independent-install.md +0 -156
- package/docs/multi-session-usage.md +0 -77
- package/docs/ownership-contract.md +0 -429
- package/docs/protocol-v2.md +0 -269
- package/docs/releases/0.2.0.md +0 -59
- package/docs/storage-contract.md +0 -1241
- package/docs/storage-security.md +0 -138
- package/docs/tunnel-manager-background.md +0 -169
- package/docs/tunnel-setup.md +0 -214
- package/pi-extension/README.md +0 -125
package/docs/storage-contract.md
DELETED
|
@@ -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`.
|