Skip to content

Commit d7f1a8e

Browse files
committed
docs(codex): another process can retarget the home symlink, so adjacency was never the mechanism
Round 8. Three things, the first proven by probe rather than argued. I had written that the fresh in-loop ambient read 'closes F2' and that parameterizing the residue guard was the eventual real fix. Both wrong. The adjacent read closes JavaScript task interleaving and nothing else — two realpath calls are two filesystem observations, and a third party owns the selector between them: check saw: clean-A <another process retargets current -> routed-B> guard saw: routed-B SAME SYNCHRONOUS STACK, DIFFERENT DIRECTORY: true The lock would have held coordinator A while the guard cleared B. So passing the canonical target into classifyNativeRoutedResidue is required for correctness in this phase; the adjacent read is demoted to defense-in-depth and says so. Second, instance #17: I declared that every accept criterion carries a mutation that turns it red, then wrote criteria whose mutation falsifies only part of the claim. The N->C criterion passed if the call edge stayed while any single seam escaped it. F1 passed if the refusal became a throw. F2 passed for the very implementation the probe above defeats. Two criteria had no mutation at all. The presence of a 'Red when' sentence was treated as proof it falsified the whole criterion — the same move, one level up. Third, the merge is now real everywhere rather than only where I looked: 000_plan's phase table, 005's OUT list, 040's CONSUME row (now NEW/IMPLEMENT), and 030's own opening line that still called WP11 independently landable. The merged wp11 shell no longer duplicates c5/c6/c7/c18, wp12 is in_progress, and F4 is a separate commit inside wp12 rather than an independent merge with no phase auditing it.
1 parent fa610fd commit d7f1a8e

4 files changed

Lines changed: 74 additions & 32 deletions

File tree

‎devlog/_plan/260804_codex_write_substrate/000_plan.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -43,11 +43,11 @@ it rather than inventing their share.
4343
| WP8b | `005_contract.md` | The shared surfaces: record schema + owner, `/api/sync` response contract, the single convergence entry point, generation counters, module names, and the config-snapshot admission result | — |
4444
| WP9 | `010_catalog_seam.md` | gather/commit split + typed outcome, consuming the contract | WP8b |
4545
| WP10 | `020_history_isolation.md` | history off the event loop, and the cross-process history protocol | WP8b |
46-
| WP11 | `030_lock_protocol.md` | the async per-home lock, per-USER namespace | WP8b, WP9, WP10 |
47-
| WP12 | `040_ownership_convergence.md` | tri-state authority, admission order, absence restoration | WP11 |
46+
| ~~WP11~~ | `030_lock_protocol.md` | **merged into WP12** — the lock has exactly one consumer, and the `AdmissionSnapshot` producer plus the `inject.ts` split that its API needs both live there | — |
47+
| WP12 | `040_ownership_convergence.md` + `030_lock_protocol.md` | the async per-home lock and per-USER namespace **with its first production caller**, plus tri-state authority, admission order, absence restoration | WP8b, WP9, WP10 |
4848
| WP13 | `050_composed_acceptance.md` | one acceptance suite against real production entry points | all |
4949

50-
WP9 and WP10 remain independent of each other and both precede WP11: a lock
50+
WP9 and WP10 remain independent of each other and both precede the lock: a lock
5151
around an unsplittable gather-and-write, or around a ten-second blocking history
5252
call, is the failure the last unit already proved. WP12 stays last of the four
5353
because its admission must run before the lock module creates anything.

‎devlog/_plan/260804_codex_write_substrate/005_contract.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,9 @@ SQLite transition row),
3030
`tests/codex-user-identity.test.ts` (NEW).
3131

3232
OUT: catalog mechanics (WP9), history mechanics (WP10), the full native-lock
33-
namespace/acquisition API and broad caller adoption (WP11), ownership mechanics
34-
(WP12). WP10 is the one narrow exception to the former native-lock boundary: it
33+
namespace/acquisition API, broad caller adoption, and ownership mechanics — all
34+
**WP12**, which absorbed the former WP11. WP10 is the one narrow exception to that
35+
native-lock boundary: it
3536
uses the already-owned N transaction as a compatibility native-handoff exclusion
3637
from each retained native mutation through its history authorization. The final
3738
coordinator path, transition table/CAS, config-generation API, shapes and funnel

‎devlog/_plan/260804_codex_write_substrate/030_lock_protocol.md‎

Lines changed: 67 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,13 @@ contract's exact `AdmissionSnapshot`; and the pinned Bun 1.3.14 probe showed bot
1717
Effective-user identity — uid on POSIX, SID on Windows — is the namespace authority
1818
(`005_contract.md` §§4, 7).
1919

20-
WP11 is independently landable. It consumes WP8b's identity/transition-state/types,
21-
WP9's synchronous candidate commit, and WP10's separate history protocol. The WP11
22-
commit typechecks and preserves the working WP9/WP10 funnel. WP12 later supplies
23-
stronger ownership/provenance decisions through the same `AdmissionSnapshot`; it is
24-
not required to replace a placeholder before this phase works.
20+
**This document is WP12's lock section.** It was written as a standalone WP11 and
21+
opened by asserting that WP11 was independently landable; round 7 established the
22+
opposite and merged the two phases (see the Round 6 resolution below). The lock
23+
consumes WP8b's identity/transition-state/types, WP9's synchronous candidate commit,
24+
and WP10's separate history protocol — and it is delivered together with the
25+
`AdmissionSnapshot` producer and the first production caller, because without those
26+
its API cannot be exercised by anything but a fabricated snapshot.
2527

2628
All current-code citations and diff context below were rechecked on 2026-08-04 at
2729
`7bde9e0c977721fc0b9d8617c85ff17de7c07658`.
@@ -140,9 +142,12 @@ So the merge is not a concession, it is the reading that makes three documents a
140142
- The goalplan work-phase is restructured accordingly: `wp11` is closed as *merged*,
141143
and `wp12` carries the mechanism, the admission producer, the `inject.ts`
142144
apply/restore split, and the first call edge as required tasks.
143-
- **F4 is the exception and lands alone.** The ACL pathname-cache defect is a live
144-
bug in shipped code (`src/lib/windows-secret-acl.ts`), independent of the lock, and
145-
it has its own falsifiable test. It does not wait for WP12.
145+
- **F4 is a separate COMMIT within WP12, not a separate merge.** The ACL
146+
pathname-cache defect is a live bug in shipped code
147+
(`src/lib/windows-secret-acl.ts`) and does not depend on the lock, so it is written
148+
and verified first rather than queued behind the admission producer. It is still
149+
audited under WP12's gate: "lands alone" would have meant a shipped repair with no
150+
active phase reviewing it, which is the gap the merge exists to close.
146151

147152
Everything below this line is therefore **WP12's lock section**, rewritten to the
148153
decisions above. Where the historical text conflicts with them, the decisions win —
@@ -698,10 +703,29 @@ Canonicalizing **both** sides is required, not tidiness. With no `CODEX_HOME` se
698703
(`src/codex/paths.ts:23`), so on a machine where `~/.codex` is a symlink an
699704
uncanonicalized ambient value refuses the very home it names.
700705

701-
The real fix is to parameterize `classifyNativeRoutedResidue()` with the canonical
702-
target and remove ambient authority from the guard entirely. The adjacency rule above
703-
is the bounded version that survives until that lands, and the merged WP12 phase
704-
carries the parameterization as a task.
706+
**Adjacency is not sufficient, and calling it "the bounded version until the real fix
707+
lands" was wrong.** It closes JavaScript task interleaving — nothing can run between
708+
two synchronous calls in one isolate — and closes nothing else. Another **process**
709+
needs no interleaving at all, because the two `realpath` calls are two separate
710+
filesystem observations of a selector that a third party owns:
711+
712+
```text
713+
CODEX_HOME=<base>/current, where current -> clean-A
714+
check saw: clean-A # the fresh adjacent read accepts A
715+
<another process atomically retargets current -> routed-B>
716+
guard saw: routed-B # the coordinator's own read resolves B
717+
SAME SYNCHRONOUS STACK, DIFFERENT DIRECTORY: true
718+
```
719+
720+
That is executed output, not a hypothetical. The lock would hold coordinator A while
721+
the safety guard cleared B.
722+
723+
So parameterizing `classifyNativeRoutedResidue()` with the canonical target is
724+
**required for correctness in this phase**, not deferred hardening: the guard must
725+
receive the resolved directory rather than resolve one for itself. The adjacent read
726+
stays as defense-in-depth against the in-isolate case, and it is explicitly not the
727+
mechanism. The acceptance criterion is mutation-named accordingly: restore ambient
728+
resolution inside the guard and a real second-process symlink-retarget test must fail.
705729

706730
```diff
707731
+const transaction = openCodexCoordinatorTransaction(finalDatabasePath);
@@ -904,20 +928,27 @@ and the ones that did were rewritten rather than kept.
904928
children must stop sharing one lock.
905929
- Config generation, authoritative admission re-read, native/provenance writes,
906930
and the conditional transition-row update share N->C; C releases before N commits.
907-
*Red when:* the apply/restore → N call edge is removed — the production-path test
908-
must fail. This criterion is unmeetable without the WP12 caller, which is exactly
909-
why the phases are merged.
931+
This is **four independent claims**, so it takes four mutations. One that only
932+
deletes the whole call edge still passes while any single seam escapes N->C.
933+
*Red when (each separately):* (a) the apply/restore → N call edge is removed;
934+
(b) the config-generation read/update moves outside N->C; (c) the
935+
provenance/integration-record update moves outside it; (d) the native writes move
936+
outside it. Each must fail its own test.
937+
Unmeetable without the WP12 caller, which is exactly why the phases are merged.
910938
- **F1** — a routed CODEX_HOME returns a typed refusal carrying the coordinator's
911939
legacy-ambiguous reason rather than throwing, **and** the existing catalog commit
912-
still succeeds on that same routed home.
913-
*Red when:* the catalog commit is moved under N — the routed-home catalog test
914-
must fail. That is the regression this finding exists to prevent.
915-
- **F2** — the successful matched-home path reaches `BEGIN IMMEDIATE`, and a home
916-
changed **during acquisition retry** is caught.
917-
*Red when:* the fresh adjacent ambient read is replaced by the value captured
918-
before the retry sleeps — the environment-change-during-retry test must fail. A
919-
test that only exercises mismatched-home refusal is insufficient: it passes even
920-
if the matched path never acquires anything.
940+
still succeeds on that same routed home. Two claims, two mutations.
941+
*Red when:* (a) the catalog commit is moved under N — the routed-home catalog test
942+
must fail; (b) the typed refusal is replaced by a thrown exception — the refusal
943+
test must fail. (a) alone would let a throwing implementation pass.
944+
- **F2** — the successful matched-home path reaches `BEGIN IMMEDIATE`; a home changed
945+
**during acquisition retry** is caught; and a home changed by **another process**
946+
retargeting the selector symlink is caught.
947+
*Red when:* (a) the fresh adjacent ambient read is replaced by the value captured
948+
before the retry sleeps — the environment-change-during-retry test must fail;
949+
(b) `classifyNativeRoutedResidue` is restored to resolving the home itself — the
950+
second-process symlink-retarget test must fail. (a) alone is satisfied by the
951+
adjacent-read-only implementation that the executed probe above defeats.
921952
- **F3** — same-process reentrancy returns `refused/reentrant`, distinguishable from
922953
the `busy` SQLite alone produces.
923954
*Red when:* ALS is removed — the reason must degrade to `busy`. Asserting only
@@ -933,11 +964,21 @@ and the ones that did were rewritten rather than kept.
933964
classification test must fail.
934965
- `transition-state.ts` alone owns native generation/txId/history scheduling; JSON
935966
owns none of them, and the lock never opens a second coordinator connection in C.
967+
*Red when:* (a) a second coordinator connection is opened inside C — it must
968+
self-contend and fail, not silently succeed; (b) `nativeGeneration` or `currentTxId`
969+
is written into `integrations/codex.json` — the JSON-ownership test must fail.
936970
- Lock edges are N->C and short fail-fast H->N only; stale history jobs are rejected
937971
by generation/transaction identity without any C->N, C->H, or held N->H edge.
972+
*Red when:* (a) each inverse edge is added in turn (C->N, C->H, held N->H) — the
973+
dependency-graph test must fail for each; (b) the generation/txId stale-job
974+
rejection is removed — a stale job must be observed overwriting the winner.
938975
- **Phase honesty** — the goalplan records the merge: `wp11` closed as *merged*, and
939976
`wp12` carrying the mechanism, the admission producer, the `inject.ts` split, and
940977
the first call edge as required tasks. If the caller does not land, the PR body
941978
says the lock is unused, in those words.
942-
*Red when:* the WP12 admission producer is removed — the production-entry test or
943-
the compile must fail.
979+
*Red when:* (a) the WP12 admission producer is removed — the production-entry test
980+
or the compile must fail; (b) the goalplan merge state is reverted so a standalone
981+
WP11 could be declared done; (c) the PR body claims a live substrate while the
982+
caller is absent. (b) and (c) are checked by reading them, not by a test — and
983+
saying so is the point, because a criterion that pretends to be automated when it
984+
is not is worse than one that admits it.

‎devlog/_plan/260804_codex_write_substrate/040_ownership_convergence.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ IN:
5757
| `src/codex/convergence-types.ts` | IMPORT ONLY | Consume `AdmissionSnapshot`, `CodexObservedState`, `ConvergeOutcome`, `CodexProvenanceLedger`, and section types; no WP12 union. |
5858
| `src/codex/integration-record.ts` | USE/MODIFY THROUGH OWNER API | Read/update provenance and extension keys through the contract owner; no transition pair, history state/schedule, path/schema/parser, or parallel merge here. |
5959
| `src/codex/transition-state.ts` | CONSUME | Use `readCodexTransitionState`, `beginCodexTransition`, and `updateCodexHistoryTransition` for the canonical-CODEX_HOME pair and history state/schedule. |
60-
| `src/codex/codex-write-lock.ts` | CONSUME | Correct WP11 module name; no lock redesign. |
60+
| `src/codex/codex-write-lock.ts` | **NEW / IMPLEMENT** | This phase CREATES the module; `030_lock_protocol.md` is its design specification. It was WP11's until round 7 merged the phases. |
6161
| `src/codex/journal.ts` | MODIFY | Read-only typed inspection; authorized recovery only inside convergence. |
6262
| `src/codex/inject.ts` | MODIFY | Receipt-gated internal apply/restore mechanics; remove filename-based deletion authority. |
6363
| `src/codex/sync.ts` | MODIFY | Remove the remaining alternate native orchestration; delegate to `convergeCodex`. |

0 commit comments

Comments
 (0)