@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.
- package/README.md +41 -61
- package/dist/bin/ce-native.js +119 -0
- package/dist/control/mcp/server.js +1 -1
- package/dist/host/mcp-binding-config.js +1 -1
- package/dist/runtime/diagnostics.js +3 -3
- package/dist/runtime/executables.js +37 -30
- package/dist/runtime/native-readiness.js +131 -0
- package/dist/runtime/wrapper-identity.js +53 -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/background-manager.js +5 -52
- package/dist/tunnel/codes.js +1 -1
- package/dist/tunnel/keychain.js +1 -1
- package/dist/tunnel/managed-binding.js +1 -1
- package/dist/tunnel/manager-panel.js +1 -1
- package/dist/tunnel/profile.js +4 -2
- package/dist/tunnel/setup-ui.js +3 -3
- package/dist/tunnel/tunnel-id.js +4 -0
- 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
|
@@ -1,77 +0,0 @@
|
|
|
1
|
-
# 一个 Tunnel,多个项目与 Pi Session
|
|
2
|
-
|
|
3
|
-
每个真实 Pi Session 使用独立、稳定的 Endpoint,例如 `pi/project-A` 与 `pi/project-B`。项目目录不是身份;同一个项目也可有多个 Session,必须分别注册。ChatGPT 侧 `chatgpt/main` 是明确共享的 inbox,**不是 ChatGPT 对话隔离**。
|
|
4
|
-
|
|
5
|
-
先完成 [Tunnel 首次设置](tunnel-setup.md)。下面的配置操作不发送/读取/ACK 消息,也不会自动启停 Tunnel。
|
|
6
|
-
|
|
7
|
-
## 1. 从单 Session 显式转换
|
|
8
|
-
|
|
9
|
-
已有 single-session 配置可以继续使用,不必强制转换。需要多 Session 时:
|
|
10
|
-
|
|
11
|
-
1. 显式 `/ce-tunnel stop`,核实 transport **STOPPED**。ACTIVE/UNKNOWN 均拒绝转换,不自动 Stop。
|
|
12
|
-
2. 关闭所有旧 legacy Pi binding/runtime,或先更新并正常释放其 binding。旧二进制不能被新 revocation gates 约束,不能仅凭新配置就认为它们被撤销。
|
|
13
|
-
3. 当前旧 Session 可用 `/ce-tunnel deactivate` 确认正常解绑,不退出 Pi、不删历史、不停止 transport。未知释放停止操作,不“清理” Owner。
|
|
14
|
-
4. 从**未绑定**的交互 TUI 运行 `/ce-tunnel convert`;明确承认旧 runtime 限制并核对保留原 registration、Store、Exchange 与 grants。仍本地持有 legacy binding 时拒绝。
|
|
15
|
-
|
|
16
|
-
转换不创建新的默认宽权限,也不自动绑定保留的 legacy registration。
|
|
17
|
-
|
|
18
|
-
## 2. 在每个真实 Session 注册 Endpoint
|
|
19
|
-
|
|
20
|
-
从需要授权的那个 Pi Session 执行,Endpoint 必须与其他 Session 不同:
|
|
21
|
-
|
|
22
|
-
```text
|
|
23
|
-
/ce-tunnel register pi/project-B --payload-read --ack
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
- 仅注册当前可信 native Pi Session,不接受手填别的 Session ID;实际绑定仍需 reload 后显式 activate。
|
|
27
|
-
- `--payload-read` 与 `--ack` 独立可选,默认都 **off**;不要为了照抄示例就开启。
|
|
28
|
-
- 在确认前核对 Endpoint、当前 Session、Store、Exchange 与权限。
|
|
29
|
-
- register/revoke/convert 需 verified STOPPED transport;不会替你 Stop/Start,不要求重输原 credential。
|
|
30
|
-
|
|
31
|
-
使用不同项目时加载同一份扩展和同一所选 profile;不要在各项目初始化独立 Store 后期待自动路由。显式非空 `CE_ALLOWLIST` 保留 legacy 优先级,并阻止生成策略注册/转换。
|
|
32
|
-
|
|
33
|
-
## 3. 分别加载与激活
|
|
34
|
-
|
|
35
|
-
```text
|
|
36
|
-
/reload
|
|
37
|
-
/ce-tunnel activate
|
|
38
|
-
/ce-status
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
首次注册没有 CE mapping,reload 拒绝 `CE_HOST_MAPPING_INVALID` 可以是预期行为;随后显式 activate 并确认,以 requireUnowned 创建该 Session 的绑定。它不是 recovery,不接管已有 Owner,包括 expired Owner。
|
|
42
|
-
|
|
43
|
-
Pi grants 在 factory 加载时捕获,Save/register 不自动扩大旧运行时权限。MCP child 也需单独显式 `/ce-tunnel start`(此前已 Stop)读取所选 generation;不要把 Pi reload 视为远端 MCP reload。
|
|
44
|
-
|
|
45
|
-
`/ce-status` 中 native Pi Session 是 lookup,CE Session 是 Owner incarnation;Endpoint 是稳定消息 label,Participant 是 Exchange 中的参与者。lease/fencing 描述当前权威,不是 transport health。**Configured ≠ Pi-bound ≠ Connected ≠ 消息实证。**
|
|
46
|
-
|
|
47
|
-
## 4. 找到可用收件人
|
|
48
|
-
|
|
49
|
-
在当前已绑定、经授权的 multi-session runtime:
|
|
50
|
-
|
|
51
|
-
```text
|
|
52
|
-
/ce-tunnel sessions
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
它列出所选配置中 active 的精确 Endpoint IDs,可复制为 `ce_send.to`。它仍需当前 runtime、所载 registration epoch、current policy 与 process mutex 全部准入。未绑定、未加载、revoked、stale 或 uncertain 均拒绝,不列出其他目标。
|
|
56
|
-
|
|
57
|
-
该列表不读 Inbox,不证明 MCP child 已加载,也不证明消息已被接收;`to` 不使用 native/CE Session ID,不额外拼 adapter。ChatGPT 仍共享自己的历史/inbox,需操作者明确选择每次消息的收件 Endpoint。
|
|
58
|
-
|
|
59
|
-
## 5. 区分解绑、撤销、停止与 reload
|
|
60
|
-
|
|
61
|
-
| 操作 | 改变什么 | 不做什么 |
|
|
62
|
-
|---|---|---|
|
|
63
|
-
| `/ce-tunnel deactivate` | 确认后正常释放当前本地 CE Owner、detach 并停续租 | 不撤销 registration、不删历史、不 Stop Tunnel、不结束其他 Session |
|
|
64
|
-
| `/ce-tunnel revoke pi/project-B` | 确认后撤销一个确切稳定 registration 的后续准入,需 STOPPED | 不回滚已准入操作、不自动释放 durable Owner、不删消息 |
|
|
65
|
-
| `/ce-tunnel stop` | 停止可证明属于 Manager 的 transport 实例 | 不代表 Pi Owner 已释放或 registration 已撤销 |
|
|
66
|
-
| 有效 binding 的 `/reload` | 停旧 generation/drain,重验并 resume 原 durable mapping | 不创建额外 Owner、不自动 takeover |
|
|
67
|
-
| 已释放/未绑定 Session 的 `/reload` | 加载策略,仍不自动重绑 | 重新绑定须显式 activate;不能靠 reload 复活已结束 CE Session |
|
|
68
|
-
|
|
69
|
-
取消 deactivate 保留绑定;重复调用不重复 end。release/end 或证据持久化未知时保持 fail-closed,不把“无本地 handle”说成安全释放。正常退出/Session replacement 也走正常 end;正常 end/release 绕过 deny-only revocation 检查,便于安全归还权威。
|
|
70
|
-
|
|
71
|
-
撤销只挡之后新准入的操作(包括 reads/renew);已准入操作可能完成。其他 registrations 和共享 ChatGPT 历史保留。重新授权使用 fresh epoch,旧 handle 仍拒绝。不要删旧注册/Owner/Store 来“重置”。
|
|
72
|
-
|
|
73
|
-
## 安全与恢复限制
|
|
74
|
-
|
|
75
|
-
process guard 只做本地 exclusion,不是 CE authority 或 crash recovery。旧 registration epoch 不能复用 reload handoff;不确定清理保留 marker 与 failure latch。append-only records 可累积,没有自动回收,即使进程已死也不自动接管。需要恢复时另行授权、核实精确 durable evidence。
|
|
76
|
-
|
|
77
|
-
本页不启用自动 Inbox polling、payload execution、ACK、重试或 Wake Bridge。真实消息与 ACK 每次仍需授权;本地配置/隔离测试不替代真实用户验收。更多见 [Pi 工具指南](../pi-extension/README.md)与[排障](tunnel-setup.md#故障排查先定位层再进行最小修复)。
|
|
@@ -1,429 +0,0 @@
|
|
|
1
|
-
# B3-P2 Ownership Contract
|
|
2
|
-
|
|
3
|
-
Status: **clarified by CE-0002-B3-P2A-R1** (this document is the versioned
|
|
4
|
-
record of the P2 ownership design decisions). Scope: the private durable
|
|
5
|
-
storage plane only. No delivery, adapter, or Pi runtime surface is defined
|
|
6
|
-
here.
|
|
7
|
-
|
|
8
|
-
## Provenance
|
|
9
|
-
|
|
10
|
-
P2A shipped without an accepted B3-D0 design record in the repository; the
|
|
11
|
-
independent review (CE-0002-B3-P2A-INDEPENDENT-REVIEW-1) found the lease time
|
|
12
|
-
model unsafe (MAJOR-1) and five undecided design questions (Q1–Q5). R1 records
|
|
13
|
-
the decisions below. Each entry distinguishes **accepted existing behavior**
|
|
14
|
-
(from B2/P1A/P1B/P2A as implemented and reviewed) from the **newly clarified
|
|
15
|
-
decision** that governs from R1 onward.
|
|
16
|
-
|
|
17
|
-
## Q1 — Owner replacement is takeover
|
|
18
|
-
|
|
19
|
-
**Decision (new):** Replacing *any* existing Owner — including one whose lease
|
|
20
|
-
has expired — belongs to the P2B `takeover` scope. `attach` may acquire
|
|
21
|
-
ownership only when **no ownership row exists** for the Participant.
|
|
22
|
-
|
|
23
|
-
- An existing live row refuses acquisition with `OWNERSHIP_HELD` (accepted P2A
|
|
24
|
-
behavior, unchanged).
|
|
25
|
-
- An existing expired row — including a legacy v2 row, which is expired at
|
|
26
|
-
every instant — refuses acquisition with `OWNERSHIP_TAKEOVER_REQUIRED`
|
|
27
|
-
(new). No fencing token is allocated by a refused acquisition.
|
|
28
|
-
- `takeover` remains `CAPABILITY_SCOPE_UNSUPPORTED`; no takeover implementation
|
|
29
|
-
exists in R1.
|
|
30
|
-
- Consequence: after a lease expires, the Participant has a durable,
|
|
31
|
-
fenced, non-authorizing ownership record until P2B takeover exists. This is
|
|
32
|
-
deliberate fail-closed behavior, not an oversight.
|
|
33
|
-
|
|
34
|
-
## Q2 — Resume authority is Session-bound
|
|
35
|
-
|
|
36
|
-
**Decision (new):** `resume` authority must ultimately be Session-bound. R1
|
|
37
|
-
implements the minimum safe foundation:
|
|
38
|
-
|
|
39
|
-
- Schema v3 adds `participant_capability.session_id` (nullable; NULL for all
|
|
40
|
-
non-resume scopes and for legacy v2 rows).
|
|
41
|
-
- Issuing a `resume` capability requires `sessionId`, and the Session must be
|
|
42
|
-
currently bound to the Participant at issuance (checked in the same
|
|
43
|
-
transaction). `sessionId` is refused for every other scope.
|
|
44
|
-
- Every `resume` authorization compares the durable binding with the presented
|
|
45
|
-
Session inside the mutation's transaction; a legacy unbound row, a missing
|
|
46
|
-
presentation, or a mismatch classifies `SESSION_MISMATCH` and refuses.
|
|
47
|
-
- Revoking a `resume` capability requires presenting its bound Session.
|
|
48
|
-
- **Non-goal:** the Session ID is not a credential. No operation is authorized
|
|
49
|
-
by a Session ID alone; the bearer token, Participant binding, scope, trust
|
|
50
|
-
generation, revocation, and expiry checks are all unchanged.
|
|
51
|
-
|
|
52
|
-
P2A's Participant-wide resume tokens do not survive: on a migrated store, a
|
|
53
|
-
legacy (NULL) resume capability can never authorize. The host issues new
|
|
54
|
-
Session-bound resume capabilities. Fail closed, no silent widening.
|
|
55
|
-
|
|
56
|
-
## Q3 — Lease term boundaries are durably persisted
|
|
57
|
-
|
|
58
|
-
**Decision (new):** the lease term start is persisted
|
|
59
|
-
(`participant_ownership.lease_started_at`), written at acquisition and updated
|
|
60
|
-
at every renewal. Default TTL 120 s; allowed TTL 30–3600 s (unchanged from
|
|
61
|
-
P2A).
|
|
62
|
-
|
|
63
|
-
- Lease evaluation compares the operation clock against the persisted
|
|
64
|
-
boundaries `[leaseStartedAt, expiresAt)` only. A request TTL is used solely
|
|
65
|
-
to compute a *new* expiry at acquisition or renewal; it never reinterprets a
|
|
66
|
-
stored term. (This remediates R1-finding MAJOR-1: the P2A model derived the
|
|
67
|
-
term start as `expiresAt − requestTTL`, which falsely refused valid Owners
|
|
68
|
-
when TTLs differed between calls and allowed a rolled-back clock to extend a
|
|
69
|
-
lease by widening the presented TTL.)
|
|
70
|
-
- Renewal never shortens the term: a new expiry earlier than the current one
|
|
71
|
-
is refused (`LEASE_TERM_SHORTENED`).
|
|
72
|
-
- Exact-expiry refusal is preserved: `now >= expiresAt` is `LEASE_EXPIRED`.
|
|
73
|
-
- **Known limit (unchanged, documented):** a wall-clock rollback that lands
|
|
74
|
-
*inside* the current term cannot be distinguished from a valid instant
|
|
75
|
-
without a persisted monotonic observation. R1 does not claim detection of
|
|
76
|
-
every rollback. Refusals are zero-write.
|
|
77
|
-
- Legacy v2 ownership rows (NULL `lease_started_at`) are treated as expired at
|
|
78
|
-
every instant: no lease start is fabricated from an untrusted TTL, and no v3
|
|
79
|
-
operation authorizes against them.
|
|
80
|
-
|
|
81
|
-
## Q4 — Expired Owners cannot release
|
|
82
|
-
|
|
83
|
-
**Decision (confirmed existing P2A behavior, now contractual):** release
|
|
84
|
-
requires a live lease. An expired Owner's release refuses `LEASE_EXPIRED`; the
|
|
85
|
-
row persists (fenced, non-authorizing) until takeover.
|
|
86
|
-
|
|
87
|
-
## Q5 — A current Owner's Session binding cannot be deleted directly
|
|
88
|
-
|
|
89
|
-
**Decision (confirmed existing P2A behavior, now contractual):** P2A/P2A-R1
|
|
90
|
-
has no detach operation. A detached Session that is the current Owner is
|
|
91
|
-
inconsistent durable state (`STORAGE_OWNERSHIP_CORRUPT`, refused, never
|
|
92
|
-
repaired). Detach semantics (including the detach-versus-ownership ordering
|
|
93
|
-
rule) are deferred to P2B.
|
|
94
|
-
|
|
95
|
-
## Accepted existing behavior carried into R1 unchanged
|
|
96
|
-
|
|
97
|
-
- Session identity: opaque, non-secret `ses_<ULID>`; never a Participant
|
|
98
|
-
identity, never a credential. A Session belongs to exactly one Participant
|
|
99
|
-
(now also enforced by the durable `participant_session_unique_session_id`
|
|
100
|
-
index); a Participant may hold many historical Sessions. Binding never
|
|
101
|
-
confers ownership; Participant creation never creates Sessions or ownership.
|
|
102
|
-
- Fencing: first token 1; strictly monotonic high-water per Participant;
|
|
103
|
-
survives restart, expiry, and release; never reused; allocation past
|
|
104
|
-
`Number.MAX_SAFE_INTEGER` refuses (`FENCING_EXHAUSTED`); fencing and the
|
|
105
|
-
ownership write are one atomic unit; an ownership row must carry exactly the
|
|
106
|
-
current high-water token and a bound Session or the state is corrupt.
|
|
107
|
-
- Capability plane: bearer tokens, host-keyed digests, trust-generation
|
|
108
|
-
binding, revocation, expiry; one opaque `CAPABILITY_REJECTED`
|
|
109
|
-
classification; trust root re-validated per authorization.
|
|
110
|
-
- Transaction discipline: owned BEGIN IMMEDIATE transactions; BUSY /
|
|
111
|
-
ROLLED_BACK / INDETERMINATE classification; refusal over repair; zero-write
|
|
112
|
-
refusals; privacy boundaries (fixed sanitized details).
|
|
113
|
-
|
|
114
|
-
## P2B prerequisites recorded by R1
|
|
115
|
-
|
|
116
|
-
1. Takeover: replace an existing (expired or legacy) Owner under a `takeover`
|
|
117
|
-
capability, allocating the next fencing token and a fresh term; classify
|
|
118
|
-
and pin the takeover races. **Implemented by CE-0002-B3-P2B** — see below.
|
|
119
|
-
2. Detach: define the ordering rule — a current Owner's binding cannot be
|
|
120
|
-
detached while the ownership row references it (Q5) — and the fate of
|
|
121
|
-
Session-bound resume capabilities at detach.
|
|
122
|
-
3. Lease policy location: if TTL policy must outlive a single request (e.g. a
|
|
123
|
-
store-fixed policy), decide whether it belongs in durable metadata.
|
|
124
|
-
|
|
125
|
-
## P2B — Takeover implemented (CE-0002-B3-P2B)
|
|
126
|
-
|
|
127
|
-
Status: **implemented**. The Q1 decision is realized without changing any R1
|
|
128
|
-
boundary: `acquireOwnership` still refuses every existing row; replacement is
|
|
129
|
-
exclusively `takeoverOwnership` under the `takeover` scope.
|
|
130
|
-
|
|
131
|
-
- **Authority.** The `takeover` scope is operational and Session-bound to the
|
|
132
|
-
prospective new Owner Session, consistent with the accepted resume model
|
|
133
|
-
(Q2): issuance requires `sessionId` naming a currently bound Session of the
|
|
134
|
-
Participant, classification compares the durable binding inside the
|
|
135
|
-
mutation's transaction, and revocation requires presenting the bound
|
|
136
|
-
Session. A Session ID alone never grants takeover authority. `send`, `ack`,
|
|
137
|
-
and `read` remain inactive.
|
|
138
|
-
- **Eligibility.** Only an existing EXPIRED row — including a legacy v2 row
|
|
139
|
-
(NULL `lease_started_at`, expired at every instant) — may be taken over. A
|
|
140
|
-
live Owner refuses (`OWNERSHIP_HELD`, evaluated against the persisted term;
|
|
141
|
-
exact expiry is the boundary), a clock-regressed lease refuses
|
|
142
|
-
(`LEASE_CLOCK_REGRESSION`), and an absent row refuses
|
|
143
|
-
(`OWNERSHIP_TAKEOVER_INELIGIBLE`): initial acquisition remains the `attach`
|
|
144
|
-
operation. No force takeover of a live Owner exists in this phase.
|
|
145
|
-
- **Atomicity.** Eligibility, fencing allocation (exactly high-water + 1,
|
|
146
|
-
compare-and-set, `FENCING_EXHAUSTED` at the ceiling), and the Owner
|
|
147
|
-
replacement are one owned IMMEDIATE transaction guarded by the exact
|
|
148
|
-
pre-read values: exactly one winner, no partial fencing allocation, no
|
|
149
|
-
partial replacement, no token reuse, zero-write refusals. A takeover racing
|
|
150
|
-
a renewal of a live lease can never win (the lease is live at every instant
|
|
151
|
-
of the race).
|
|
152
|
-
- **Supersession.** The previous Session immediately loses current ownership:
|
|
153
|
-
its fencing token is stale and its `resume` capability cannot renew,
|
|
154
|
-
release, or verify the new Owner (`OWNERSHIP_NOT_CURRENT` /
|
|
155
|
-
`FENCING_STALE`). Historical Session bindings, Participant identity,
|
|
156
|
-
Endpoint binding, Exchange membership, join boundaries, and audit history
|
|
157
|
-
are untouched; capability rows are never mutated by a takeover.
|
|
158
|
-
- **Recovery.** `reconcileTakeover` is a zero-write, fail-closed
|
|
159
|
-
reconciliation read over the evidence the caller presents (Participant,
|
|
160
|
-
target Session, the exact persisted term boundaries, optional fencing
|
|
161
|
-
token): `COMMITTED` (exact durable match — do not retry), `NO_TRACE` (the
|
|
162
|
-
durable state carries no trace of the presented evidence — a fresh attempt
|
|
163
|
-
is freshly authorized and eligibility-checked), or `EVIDENCE_CONFLICT` (the
|
|
164
|
-
target Session is current under different evidence — operator review, never
|
|
165
|
-
auto-retry). All three are effect-level classifications of durable state,
|
|
166
|
-
never operation-level attribution of one invocation: `COMMITTED` is not an
|
|
167
|
-
exactly-once claim, and `NO_TRACE` is not proof that the original invocation
|
|
168
|
-
never committed (a committed takeover later superseded also reports
|
|
169
|
-
`NO_TRACE`). Documented limitations, deliberately not papered over with
|
|
170
|
-
exactly-once semantics: a refused and a rolled-back takeover leave identical
|
|
171
|
-
durable state; a committed-then-superseded takeover reports `NO_TRACE`; a
|
|
172
|
-
committed retry with identical parameters is the same logical request. No
|
|
173
|
-
background recovery workers.
|
|
174
|
-
- **Evidence availability (clarified, no behavior change).** The operation
|
|
175
|
-
clock is sampled inside the owned transaction (see B3-P2B-R1 below), so the
|
|
176
|
-
sampled instant is not an ordinary caller-supplied request field:
|
|
177
|
-
`leaseStartedAt` is that sample and `expiresAt` is `sample + ttl`. The exact
|
|
178
|
-
term normally reaches the caller only through a successful return, or when
|
|
179
|
-
the caller itself supplies and records the operation clock seam; a
|
|
180
|
-
default-clock caller whose call ended INDETERMINATE does not know it, and
|
|
181
|
-
pre-call wall-clock sampling does not reconstruct it. `reconcileTakeover`
|
|
182
|
-
currently requires `participantId`, `sessionId`, `leaseStartedAt`, and
|
|
183
|
-
`expiresAt`, with `fencingToken` optional, and callers must not fabricate,
|
|
184
|
-
estimate, or round term boundaries to satisfy that shape. INDETERMINATE is
|
|
185
|
-
not ROLLED_BACK: the invalidated connection must not be reused, inspection
|
|
186
|
-
requires a freshly opened store, and a lost acknowledgement never authorizes
|
|
187
|
-
a blind retry. When exact term evidence is unavailable the outcome simply
|
|
188
|
-
stays unknown to the caller — there is no UNKNOWN input and no UNKNOWN
|
|
189
|
-
disposition in the API. A pre-call `readFencingHighWater` snapshot that is
|
|
190
|
-
unchanged on a later valid read of the same Participant shows that no
|
|
191
|
-
fencing allocation committed for that Participant between the two reads; an
|
|
192
|
-
increased high-water identifies no invocation, proves nothing about this
|
|
193
|
-
caller's takeover, and never establishes a durable lease. The operator-only
|
|
194
|
-
recovery caller resolving CE-TAKEOVER-RECOVERY-CALLER-001 deliberately does
|
|
195
|
-
not call `reconcileTakeover`: before writing it requires exact endpoint and
|
|
196
|
-
old-owner evidence and an expired durable lease; it then binds a fresh
|
|
197
|
-
recovery Session, uses the existing Session-bound `takeover` primitive,
|
|
198
|
-
releases that lease, and detaches the recovery Session. A successful caller
|
|
199
|
-
returns a capability-free receipt plus durable fencing/session evidence. Any
|
|
200
|
-
INDETERMINATE stage remains unknown and is never retried automatically.
|
|
201
|
-
`reconcileTakeover` still has no production caller because a default-clock
|
|
202
|
-
caller cannot reconstruct exact term boundaries after losing acknowledgement
|
|
203
|
-
(CE-TAKEOVER-RECONCILIATION-EVIDENCE-001). Full statement:
|
|
204
|
-
`docs/storage-contract.md` §11 "Evidence availability after an uncertain
|
|
205
|
-
outcome".
|
|
206
|
-
- **Legacy ownership.** A migrated v2 row never authorizes and is never
|
|
207
|
-
repaired; it is takeover-eligible, and takeover replaces it with a fully
|
|
208
|
-
persisted v3 term at a fencing token strictly greater than the legacy token.
|
|
209
|
-
- Q4 and Q5 are unchanged: an expired Owner cannot release, and there is no
|
|
210
|
-
detach operation (P2B did not take detach; it remains prerequisite 2).
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
## B3-P2B-R1 — transaction-time clock sampling (remediation)
|
|
214
|
-
|
|
215
|
-
Status: **implemented**. Remediates the independently confirmed MAJOR-1 of
|
|
216
|
-
CE-0002-B3-P2B-INDEPENDENT-REVIEW-1 (stale pre-lock clock).
|
|
217
|
-
|
|
218
|
-
**The defect.** P2B sampled each operation's clock *before* `BEGIN
|
|
219
|
-
IMMEDIATE`. An operation that waited for the SQLite writer lock evaluated
|
|
220
|
-
authorization and lease state against the pre-lock instant: a renewal
|
|
221
|
-
initiated before expiry but serialized after it committed from the stale
|
|
222
|
-
sample, reviving an expired lease and locking out a legitimately eligible
|
|
223
|
-
takeover (reproduced by the reviewer with real processes and real lock
|
|
224
|
-
contention). A capability that expired during the lock wait was likewise
|
|
225
|
-
accepted.
|
|
226
|
-
|
|
227
|
-
**The decision (new, contractual):** every owned mutating transaction has
|
|
228
|
-
exactly one authoritative operation-time sampling point — *inside* the owned
|
|
229
|
-
transaction, after `BEGIN IMMEDIATE` has acquired the writer lock:
|
|
230
|
-
`BEGIN IMMEDIATE → sample now → validate authority → evaluate current state
|
|
231
|
-
→ mutate → COMMIT`. All checks within one mutation use this one consistent
|
|
232
|
-
instant. This applies to `bindSession`, `acquireOwnership`, `renewLease`,
|
|
233
|
-
`releaseOwnership`, `verifyOwnership`, `takeoverOwnership` (ownership plane)
|
|
234
|
-
and to `createParticipant` (sponsor authorization), `bindEndpointRef`,
|
|
235
|
-
`issueCapability`, `revokeCapability`, and `joinExchange` (capability/membership
|
|
236
|
-
plane). Lease start and expiry derive from the transaction-time clock;
|
|
237
|
-
capability expiry is evaluated at the transaction-time clock, so a capability
|
|
238
|
-
that expired during a lock wait can never be accepted. Request validation
|
|
239
|
-
(field shape, TTL range, identities) still precedes the transaction and
|
|
240
|
-
performs no state-dependent check.
|
|
241
|
-
|
|
242
|
-
**Preserved semantics.** Exact-expiry behavior is unchanged (`now >=
|
|
243
|
-
expiresAt` is expired); clock-regression refusal is unchanged (a pre-term
|
|
244
|
-
instant refuses `LEASE_CLOCK_REGRESSION`); the injected-clock test seam is
|
|
245
|
-
unchanged (it is simply invoked at the transaction-time sampling point); no
|
|
246
|
-
scheduler and no global clock is introduced. Audit of the remaining storage
|
|
247
|
-
mutation entry points (corrected by CE-0002-B3-P2C-A): B2 Exchange/Message
|
|
248
|
-
creation samples its clock during candidate generation, *before* `BEGIN
|
|
249
|
-
IMMEDIATE`; its timestamps are recorded creation metadata that authorize
|
|
250
|
-
nothing, so the accepted B2 contract is unchanged (its invalid-clock behavior
|
|
251
|
-
remains the accepted precedent). Migration/recovery/initialization
|
|
252
|
-
`appliedAt` ledger timestamps likewise authorize nothing and are unchanged.
|
|
253
|
-
|
|
254
|
-
**Lock-wait semantics (now defined).** Authorization and eligibility are
|
|
255
|
-
decided at the serialization instant, not the initiation instant. A renewal
|
|
256
|
-
initiated before expiry but serialized after it refuses `LEASE_EXPIRED`; a
|
|
257
|
-
takeover initiated before expiry but serialized after it is eligible and may
|
|
258
|
-
win; a takeover serialized while the lease is still live refuses
|
|
259
|
-
`OWNERSHIP_HELD`; a capability that expired during the wait refuses
|
|
260
|
-
`CAPABILITY_REJECTED`. Every such refusal is zero-write and never allocates
|
|
261
|
-
a fencing token.
|
|
262
|
-
|
|
263
|
-
**Remaining wall-clock limitations (unchanged, no new monotonicity claim).**
|
|
264
|
-
A wall-clock rollback that lands *inside* the current term remains
|
|
265
|
-
indistinguishable from a valid instant without a persisted monotonic
|
|
266
|
-
observation (Q3); transaction-time sampling decides each operation at its
|
|
267
|
-
own serialization instant and does not create a cross-transaction monotonic
|
|
268
|
-
clock. Refusals remain zero-write.
|
|
269
|
-
|
|
270
|
-
**Regression pins.** `test/storage/lease-lock-wait.test.ts` exercises the
|
|
271
|
-
renewal/takeover/capability lock-wait boundaries with real OS processes, a
|
|
272
|
-
real writer lock, observable initiation markers, and deadline waits against
|
|
273
|
-
durable expiries (no sleep-only assertions, no fake-clock simulation of
|
|
274
|
-
contention).
|
|
275
|
-
## P2C prerequisites recorded by P2B
|
|
276
|
-
|
|
277
|
-
1. Detach semantics (Q5 ordering rule and the fate of Session-bound
|
|
278
|
-
capabilities at detach).
|
|
279
|
-
2. Lease policy location (prerequisite 3 above, unchanged).
|
|
280
|
-
3. `send`/`ack`/`read` scopes remain for the delivery phases.
|
|
281
|
-
|
|
282
|
-
## B3-P2C-A — Irreversible Session lifecycle and schema v4 (CE-0002-B3-P2C-A)
|
|
283
|
-
|
|
284
|
-
Status: **implemented** (structural foundation only). Realizes the accepted
|
|
285
|
-
CE-0002-B3-P2C-D0 design decisions D1, D2, D5 (as a schema guard), D9 (read),
|
|
286
|
-
D14, and D15. **No detach operation exists yet**; capability scope semantics
|
|
287
|
-
are unchanged (no `detach` scope; `resume` is not yet widened to
|
|
288
|
-
self-detach). P3 is not started.
|
|
289
|
-
|
|
290
|
-
- **States.** A Session row is exactly ATTACHED (`detached_at IS NULL`,
|
|
291
|
-
`private_revision = 1`) or DETACHED (canonical `detached_at` not earlier
|
|
292
|
-
than `bound_at`, `private_revision = 2`). Every other combination is
|
|
293
|
-
`STORAGE_OWNERSHIP_CORRUPT`: refused, zero-write, never repaired. DETACHED
|
|
294
|
-
is terminal; a detached Session is never a current binding and never
|
|
295
|
-
regains authority.
|
|
296
|
-
- **Schema v4 (triggers only).** Session rows are born ATTACHED, never
|
|
297
|
-
deleted, and keep immutable Participant ID, Session ID, and `bound_at`; the
|
|
298
|
-
only permitted UPDATE is the one-way ATTACHED r1 → DETACHED r2 transition;
|
|
299
|
-
the current Owner Session cannot be detached; an ownership row can never
|
|
300
|
-
reference a detached Session. Session IDs are therefore never reused. No
|
|
301
|
-
table rebuild, no new column, no new capability scope.
|
|
302
|
-
R1: the transition also requires a canonical `detached_at` no earlier than
|
|
303
|
-
a canonical `bound_at`, enforced by SQLite itself — see
|
|
304
|
-
`docs/storage-contract.md` §12 for the exact SQLite-versus-application
|
|
305
|
-
validation boundary, the `recursive_triggers` requirement, and the
|
|
306
|
-
privileged-writer trust limits.
|
|
307
|
-
- **Ownership interaction (Q5 formalized).** The current Owner — live,
|
|
308
|
-
expired, legacy, or clock-regressed — cannot be detached while the
|
|
309
|
-
ownership row references it; the way out is the existing release or
|
|
310
|
-
takeover. Detach never deletes or replaces ownership and never touches the
|
|
311
|
-
fencing high-water.
|
|
312
|
-
- **Validation.** `issueCapability` (Session-bound scopes), `bindSession`,
|
|
313
|
-
`acquireOwnership`, `takeoverOwnership`, `renewLease`, `releaseOwnership`,
|
|
314
|
-
`verifyOwnership`, and every Session read strictly validate the row: a
|
|
315
|
-
DETACHED Session refuses `SESSION_NOT_BOUND`; a malformed row refuses
|
|
316
|
-
`STORAGE_OWNERSHIP_CORRUPT`; re-binding a detached Session ID refuses as
|
|
317
|
-
before (`SESSION_ALREADY_BOUND` / `SESSION_BOUND_TO_OTHER_PARTICIPANT`).
|
|
318
|
-
- **Lifecycle read.** `readSessionLifecycle` is a private, host-local,
|
|
319
|
-
zero-write read over one snapshot returning `ATTACHED` / `DETACHED` /
|
|
320
|
-
`NOT_FOUND` (a foreign pair is `NOT_FOUND`); it validates the
|
|
321
|
-
Participant's ownership state in the same snapshot and authorizes nothing.
|
|
322
|
-
- **Remaining P2C work (P2C-B): implemented** by CE-0002-B3-P2C-B — see the
|
|
323
|
-
next section. P3 (send/ack/read, delivery) is not started.
|
|
324
|
-
|
|
325
|
-
## B3-P2C-B — Authorized Session Detach (CE-0002-B3-P2C-B)
|
|
326
|
-
|
|
327
|
-
Status: **implemented**. Realizes the accepted P2C-D0 design decisions D4,
|
|
328
|
-
D7, D10, and D11 without changing any accepted boundary: schema v4 stays
|
|
329
|
-
frozen (no DDL, no new migration, no checksum change), no `detach` capability
|
|
330
|
-
scope exists, and Disconnect is not Detach — Detach is a durable binding
|
|
331
|
-
lifecycle fact of the private storage plane, never a transport event.
|
|
332
|
-
|
|
333
|
-
- **Operation (D4).** `detachSession(store, request)` performs the one-way
|
|
334
|
-
ATTACHED → DETACHED transition under the Session's own Session-bound
|
|
335
|
-
`resume` capability — self only. The capability must authorize exactly its
|
|
336
|
-
bound Session; a Session ID alone is never a credential. Inside one owned
|
|
337
|
-
BEGIN IMMEDIATE transaction, in order: transaction-time clock (sampled
|
|
338
|
-
after the writer lock is acquired), capability validation (trust
|
|
339
|
-
generation, expiry, revocation, Session binding), Participant identity,
|
|
340
|
-
Session binding, complete ownership-state validation, the
|
|
341
|
-
current-Owner refusal, the clock-regression refusal, and the guarded
|
|
342
|
-
`detached_at IS NULL AND private_revision = 1` → `detached_at = now,`
|
|
343
|
-
`private_revision = 2` update with exactly one changed row.
|
|
344
|
-
- **Ownership interaction (Q5).** The current Owner — live, expired, legacy
|
|
345
|
-
(NULL `lease_started_at`), or clock-regressed — refuses
|
|
346
|
-
`SESSION_IS_CURRENT_OWNER` while the ownership row references its Session,
|
|
347
|
-
regardless of lease expiry. The way out is the existing release (live
|
|
348
|
-
Owners only; Q4 preserved: an expired Owner cannot release) or an
|
|
349
|
-
authorized takeover, after which the superseded former Owner detaches
|
|
350
|
-
freely. Detach never modifies the ownership row, never touches the fencing
|
|
351
|
-
high-water, never deletes the Session row, and never mutates capability
|
|
352
|
-
rows. Concurrent release / takeover / renew outcomes are derived from the
|
|
353
|
-
serialized durable state; the real-process lock-wait scenarios F and G pin
|
|
354
|
-
the serialized boundaries.
|
|
355
|
-
- **Capability lifecycle (D7).** Session lifecycle validation is centralized
|
|
356
|
-
in capability classification: a Session-bound capability whose bound
|
|
357
|
-
Session is DETACHED is unusable for every presenter. The persisted
|
|
358
|
-
`detached_at` is the lifecycle source of truth — read-time invalidation
|
|
359
|
-
only, no bulk revocation, no capability-row rewrites. Caller-visible
|
|
360
|
-
refusals remain the one opaque `CAPABILITY_REJECTED`; the host-local
|
|
361
|
-
status read identifies `SESSION_DETACHED`. The future Session-bound
|
|
362
|
-
scopes (`send`, `ack`, `read` — not implemented in this phase) inherit the
|
|
363
|
-
check unchanged when they join `SESSION_BOUND_CAPABILITY_SCOPES`. A
|
|
364
|
-
Session-bound capability whose binding row is missing or malformed refuses
|
|
365
|
-
`STORAGE_OWNERSHIP_CORRUPT` — never adopted, never repaired. Deliberate
|
|
366
|
-
error-precedence change (documented, pinned): for a DETACHED Session, the
|
|
367
|
-
capability-plane refusal now outranks the operation-level
|
|
368
|
-
`SESSION_NOT_BOUND` that `renewLease` / `releaseOwnership` /
|
|
369
|
-
`verifyOwnership` / `takeoverOwnership` previously surfaced; `attach`
|
|
370
|
-
(not Session-bound) still refuses `SESSION_NOT_BOUND` at the operation.
|
|
371
|
-
Revoking a detached Session's capability refuses exactly like revoking an
|
|
372
|
-
expired one.
|
|
373
|
-
- **Recovery.** `reconcileDetach(store, evidence)` is the private, read-based,
|
|
374
|
-
zero-write, fail-closed reconciliation after an uncertain outcome (failure
|
|
375
|
-
before or after COMMIT, lost response, BUSY, ROLLED_BACK, INDETERMINATE):
|
|
376
|
-
COMMITTED / NO_TRACE / EVIDENCE_CONFLICT classified from the durable
|
|
377
|
-
Session state in one snapshot, with ownership coherence validated in the
|
|
378
|
-
same snapshot (concurrent takeovers and releases are simply part of the
|
|
379
|
-
observed state). The evidence `detachedAt` is optional: with it, an exact
|
|
380
|
-
match is COMMITTED and any mismatch is EVIDENCE_CONFLICT (operator
|
|
381
|
-
review); without it, a DETACHED row is COMMITTED because the terminal
|
|
382
|
-
durable effect exists. The durable effect is idempotent; the API response
|
|
383
|
-
is not — a retry of a committed detach refuses `CAPABILITY_REJECTED` — so
|
|
384
|
-
the discipline is reconcile first, never blindly retry, and a fresh
|
|
385
|
-
attempt after NO_TRACE is a new full authorization, not a replay. No
|
|
386
|
-
exactly-once execution is claimed. `reconcileTakeover` is unchanged.
|
|
387
|
-
- **Lease policy (D10/D11).** The host owns lease policy: default TTL 120 s,
|
|
388
|
-
accepted range 30–3600 s, renewal recommendation 30 s. An adapter may
|
|
389
|
-
REQUEST a TTL per operation (`leaseTtlSeconds`); the request only computes
|
|
390
|
-
the new expiry at acquisition or renewal and never reinterprets a stored
|
|
391
|
-
term. No policy is persisted — there is no policy table and none is
|
|
392
|
-
planned for this phase. Hosts should schedule renewal well before expiry
|
|
393
|
-
using the `expiresAt` returned by acquisition and renewal (and re-derive
|
|
394
|
-
the schedule from each renewal's returned `expiresAt`), because an
|
|
395
|
-
operation serialized after expiry refuses `LEASE_EXPIRED` and cannot
|
|
396
|
-
revive the term; the persisted `lease_started_at` / `expires_at` boundaries
|
|
397
|
-
always decide.
|
|
398
|
-
|
|
399
|
-
## B3-P3A — Scoped current-Owner authority
|
|
400
|
-
|
|
401
|
-
Status: **implemented for private storage send/read only**. The historical P2
|
|
402
|
-
sections above remain the record of their phase boundaries; where they say
|
|
403
|
-
`send`/`read` were inactive, this P3A amendment supersedes that status.
|
|
404
|
-
|
|
405
|
-
`send` and `read` are now operational and are Session-bound exactly like
|
|
406
|
-
`resume`/`takeover`: issuance requires a durable ATTACHED Session binding,
|
|
407
|
-
classification binds Participant + exact scope + trust generation + Session,
|
|
408
|
-
revocation presents that Session, and terminal detach makes the token unusable
|
|
409
|
-
without rewriting capability rows. `ack` remains inactive.
|
|
410
|
-
|
|
411
|
-
The shared current-Owner primitive defaults to `resume` for all accepted P2
|
|
412
|
-
renew/release/verification callers, preserving their API and refusal precedence.
|
|
413
|
-
P3A callers explicitly request only `send` or `read`; neither a resume token nor
|
|
414
|
-
a takeover token authorizes those operations. Inside the caller-owned IMMEDIATE
|
|
415
|
-
transaction, capability classification precedes Participant/Session checks, then
|
|
416
|
-
the durable ownership row establishes the current Owner, the presented fencing
|
|
417
|
-
token must equal the persisted monotonic token/high-water state, and the
|
|
418
|
-
persisted lease term must be active without clock regression.
|
|
419
|
-
|
|
420
|
-
P3A samples authority time only after the writer lock is acquired. A send racing
|
|
421
|
-
release serializes either before release and may commit, or after release and
|
|
422
|
-
refuses `OWNERSHIP_NOT_CURRENT`. A near-expiry send racing takeover similarly
|
|
423
|
-
commits only before replacement or refuses as the former Owner afterward; it
|
|
424
|
-
cannot commit under stale fencing. Independent-process tests pin both outcomes.
|
|
425
|
-
|
|
426
|
-
This amendment does not broaden takeover recovery, define Pi Session lifecycle
|
|
427
|
-
outside the existing durable binding, or grant authority from a Session ID,
|
|
428
|
-
Participant ID, Worker/Advisor label, endpoint label, or fencing token alone.
|
|
429
|
-
ACK and external delivery remain outstanding P3 work.
|