fix(objectql): settle readonlyWhen locks per cycle, so a cycle no longer over-locks the rest of the update

[objectstack-fleet]

Fixes #19929
Clause-②: no

It removes a drop that published text already rules out: content/docs/data-modeling/fields.mdx says the server "ignores writes to fields whose readonlyWhen predicate is TRUE". The dropped x below has a FALSE predicate on the row the update stores.

What changes

settleReadonlyWhenDrops (packages/objectql/src/validation/rule-validator.ts) searched for ONE drop set across every readonlyWhen key in the update. When a cycle stopped that search from settling, it kept the fixpoint's larger set for the WHOLE update. Now the keys are settled in groups: the strongly connected components of "the predicate of k reads j through record", taken in dependency order.

• A key in no cycle is judged once, after every key it reads, against their final drops.
• Keys that read each other in a cycle are settled together, with the existing fixpoint, release rounds and fail-safe fallback. The bound is now the cycle's size, and the fallback covers only that cycle's keys.
• What a predicate reads comes from the AST of the canonical parse (parseCelToAst). Only a . or .? select on the bare record root counts as reading a named field. Any other use of record (record['b'], 'b' in record, size(record), a macro-bound record), a non-CEL predicate, or one that does not parse counts as reading every judged key. previous and parent are fixed within one strip call, so they add no edge.

engine.ts is unchanged (H4). The master-detail settlement calls the same strips; the new line_beside pins show its FK landing beside a cycle with the same header reads as before (['h_open', 'h_open']).

I chose strongly connected components over the card's connected components on measurement (table below). Connected components still over-lock a key that is in no cycle but is connected to one, for example a cycle that reads x. The per-field sentence the triage asked to make true ("only where locks read each other in a cycle") holds only with the per-cycle grouping.

Measurements

H1 holds on main 2c1011b01b, read from the code: the function's last line returns the fixpoint's set for the whole judged list.

H2 holds on main. The new suite, run before the fix, was 17/17 red. In both card shapes the update stored x: 'old', so all five fields dropped. The pure strip returned { x: 'xv' } for the chain alone and {} beside the cycle. The strict refusal named ['c', 'x', 'y', 'a', 'b'].

H3 was tested with a brute-force probe: a temporary vitest file, not committed, run against the new strips and the BASE strips copied from 2c1011b. It covered 16,500 random lock systems, 12,000 single-row and 4,500 bulk with 2 or 3 matched rows, some with index reads. Every check came back with 0 violations:

• (S) no kept key is locked on the row the update stores (a key is judged with its own incoming value);
• (E) every dropped key that is unlocked there is in a cycle, under the reading above;
• (L) each key's verdict is unchanged when the payload is cut down to the keys that key transitively reads;
• (D) shuffling field declaration order and payload key order never changes the drops;
• (C) an acyclic system gives the same answer as base;
• (R) the update drops nothing exactly when base drops nothing, so strictReadonlyWrites refuses the same writes.

over-locked keys (dropped while unlocked on the stored row)	base	connected components	per cycle (this PR)
total	664	661	575
outside any cycle	90	87	0

Base and this PR agree on 16,405 of the 16,500 systems. They differ in 95:

• 86 where both fall back and this PR over-locks fewer keys;
• 5 where both reach an agreeing set, but a different one;
• 4 where base reached an agreeing set and this PR keeps the cycle's fail-safe drops (see the acceptance notes).

The rule-validator blob the probe measured is 87b0b5a7, unchanged since ebb8a761 through this head.

Ablation of the conservative reader. I committed first, then ran node scripts/ablation-replace.mjs in WRAP mode to change every = true; to every = false; (anchor 1 → 0, blob 87b0b5a7 → 9b744861). Exactly the two index_read pins went red. The ablated update stored w: 'wv' although w's lock (record['a'] == 'old_a') is TRUE on the stored row, so the lock opens. The restore was proven: blob equal to HEAD, and git diff HEAD empty. The suite imports ./validation/rule-validator.js through a relative path, so the subject resolves to src, not dist, and no dist preflight applies. The fixtures declare z/w ahead of the cycle. Groups with no read between them come out in declaration order, so a cycle declared first would have hidden a missed read.

Tests (head 2d75a593)

• pnpm --filter @objectstack/objectql typecheck: exit 0, test layer included (234 errors, 65 signatures held in the ledger, unchanged).
• pnpm --filter @objectstack/objectql test: 309 files, 5195 tests, all passed. Every existing readonlyWhen pin is unchanged and green, including the A record-scoped readonlyWhen reading a field that another readonlyWhen drops in the same pass is judged against the dropped value, so a closed row locked amount is rewritten #19911 and A three-lock readonlyWhen cascade drops a write whose own lock is FALSE on the stored row: a legitimate edit is silently ignored #19927 suites and the parent, stored-view and derived-writes suites.
• New engine-readonly-when-cycle-isolation.test.ts: 18 pins. They cover both card shapes (by id, bulk, strict, isSystem), declaration and payload order, a cycle that reads the chain, locks that read the cycle (select and index), the master-detail FK beside a cycle (by id and bulk, header reads), and pure-strip isolation including only.
• eslint --no-inline-config on the 2 changed .ts files: 2 files, 0 errors, 0 warnings. The config never enables type-aware linting (no parserOptions.project), so this diff cannot move the verdict on any file it does not touch. The 2 .changeset/*.md files fall outside the lint files globs.

Gates

I ran node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack from this diff. It derived 63 commands; I ran those plus the 2 families only the dispatch named (check:stack-collection-maps, check:swallow-census-controls). --ran reconciles: 63 derived, 61 run, 2 NOT-MEASURED, 0 UNRUN.

• NOT MEASURED, PREREQUISITE NOT MET (exit 3): check:dual-build-cjs-loads and check:type-check-debt. Both need every workspace package's dist/, and only the objectql closure is built here. As a narrower check, @objectstack/objectql's own build succeeded (ESM, CJS and DTS), and its CJS entry loads (require exit 0, 176 exports).
• check:engine-split-ratio --days 90 refused on the shallow clone (exit 2). After git fetch --shallow-since=2026-06-19 origin main it passed (exit 0).
• Red by design: check-empty-changeset --base origin/main (exit 1), the DELIBERATE CORRECTION class. This PR rewrites the pending .changeset/19911-readonlywhen-interdependent-locks.md, whose sentences this PR made false:
  • its mechanism paragraph said the release rounds stop "after one round more than the caller sent fields" and that the larger set "stands instead" for the whole update;
  • its cycle bullet said a FALSE-lock field is dropped "only where locks read each other in a cycle", which was true for the update and false per field.
    Both now describe per-cycle settlement. The pending .changeset/19927-readonlywhen-exact-drop-set.md carries no such sentence, and every example in it still holds on the new pins, so it is untouched. Neither changeset had been consumed by a release at base 2c1011b. This correction of a pending release note needs a maintainer's confirmation on this PR; the gate stays red until then. I did not add a skip-changeset label.
• All other commands exit 0.

Serial neighbour

Draft PR #19728 is still open. I fetched its head 3b9c5f2f into refs/issue-19929/pr19728 and ran git merge-tree --write-tree --name-only of this head against it from a throwaway bare clone with no merge driver: exit 0, tree 80a7d59f, no conflicted paths (merge base 6eaa0f4a). That PR rewrites the @objectstack/formula import on line 195, so this PR imports parseCelToAst in a separate statement further down the import block.

Acceptance notes

• A delta inside cycles with two or more agreeing sets. In 4 of the 16,500 probe systems, base reached one of a cycle's agreeing sets through the whole-update trajectory, and this PR keeps that cycle's fail-safe drops instead. Example: k1: previous.k1 == 'q', k2: record.k1 == 'q', and the cycle k0: record.k3 == 'p' && record.k2 == 'q' / k3: record.k0 == 'q', on the row {k0: p, k1: q, k2: q, k3: q} with {k0: q, k1: p, k2: p, k3: p}. With k2 settled first the cycle agrees with both {k0} and {k3}, and the release rounds alternate between {} and {k0, k3}. Base's first pass judged k0 against a k2 it had not dropped yet and landed on {k3}. Such a cycle's pick was always an artifact of the iteration (the documented rule is "the one ② reaches, or ①'s when it reaches none"). It now depends only on the locks the cycle reads. The 19929 changeset states this. No pin flipped.
• A predicate that reads record other than as a field select counts as reading every judged key. In the probe that created a cycle that was not really there 9 times, each over-locking in the fail-safe direction. This is the conservative direction the ablation above proves is load-bearing.
• fields.mdx never mentions the residual over-lock inside a cycle. The docs are incomplete there, not wrong, so I noted it and filed nothing. Carrier: none.
• The onFieldsDropped event lists fields in the payload's key order (reportDroppedFields walks the payload). That is existing behaviour, and the order pin in the new suite states it.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

11 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• the SDK route bridge reached 60 of 215 client-bound route-ledger rows — the other 155 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 155: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 100 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 17 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 2c1011b01bc071c545f72f2761647b8d9ab56375 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 3a7f45112fb25ce1a9c60580e2a99c2da8d75d86 — the merge of head 2d75a59332ddea43798e08ebe82016359c972f52 into base 2c1011b01bc071c545f72f2761647b8d9ab56375, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 3a7f45112fb25ce1a9c60580e2a99c2da8d75d86 && git checkout 3a7f45112fb25ce1a9c60580e2a99c2da8d75d86
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 2c1011b01bc071c545f72f2761647b8d9ab56375 2d75a59332ddea43798e08ebe82016359c972f52 && git checkout -B drift-repro 2c1011b01bc071c545f72f2761647b8d9ab56375 && git merge --no-ff 2d75a59332ddea43798e08ebe82016359c972f52

node scripts/docs-audit/affected-docs.mjs --json 2c1011b01bc071c545f72f2761647b8d9ab56375

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 2d75a59332ddea43798e08ebe82016359c972f52

① Derived judgments

1. settleReadonlyWhenDrops now settles the judged keys in strongly connected components (Tarjan) of "k's predicate reads j through record", in dependency order. settleLockGroup judges a one-key group once, against the final drops of the groups before it, and runs the fixpoint, release and fallback for a cycle only. RIGHT.
2. Single-row updates: a caller field whose lock is in no cycle is stored exactly when its lock is FALSE on the row the update stores, and ignored exactly when TRUE. The card's x now lands. Measured: the real engine at head stores x: xv where base stored x: old. The reviewer's own probe found 0 kept keys locked on the stored row and 0 dropped-while-unlocked keys outside a cycle, across 11,885 random lock systems. RIGHT.
3. Bulk updates: the same holds with "locked in at least one matched row", across 2,963 bulk systems and six bulk pins. RIGHT.
4. Master-detail: engine.ts is unchanged; settleMasterDetailLanding still judges the FK, now through the grouped settlement. The invoice example moves the line to h_open, stores amt, and ignores c, y, a, b. RIGHT.
5. onFieldsDropped / strictReadonlyWrites now name only the fields actually ignored. Whether a write is refused is unchanged: 0 of 11,885 differ. RIGHT.
6. No lock opens: 0 of 11,885, and no spelling in a 20-spelling battery let a locked field land. RIGHT.
7. The read-set extraction is conservative. A field is named only for a . / .? select on the bare record root; any other use of record, a non-CEL dialect or a parse failure counts as reading every field. Verified against the cel-js 8.0.0 AST for 37 sources, including record['b'], size(record), macros, dyn(record).a and 'a' in record. RIGHT.
8. Deterministic, and independent of declaration and payload order: 0 of 11,885 differ with both orders shuffled. RIGHT.
9. The per-cycle fallback is bounded; the loop bounds match the docblock. RIGHT.
10. Acyclic parity with base: 0 differences across 8,754 acyclic systems. All 13 moved answers are inside cycles, in the fail-safe direction. The dev's acceptance-note example reproduces. RIGHT.

② Semver level

@objectstack/objectql: patch with Clause-②: no is consistent. No authorable key, export or error code moves: the new functions are module-private, and engine.ts and packages/spec are untouched. Every movement goes toward the cited fields.mdx text. Check-runs at head: 34 runs, 30 success, 3 skipped, 1 failure. The failure is Check Changeset, the DELIBERATE CORRECTION class of check-empty-changeset.mjs, red by design pending written confirmation. All seven required contexts are green.

③ Boundary flags

1. .changeset/19929-readonlywhen-cycle-isolation.md: every factual sentence and worked example holds on measurement (c/x/y beside a/b; the two-agreeing-sets case; the invoice case; the z / w case; the record['b'] / size(record) sentence; the onFieldsDropped sentences). No false or unmeasured sentence. One imprecision, not a FAIL: "counts as reading every field the update writes" is implemented as an edge to every other judged key, which has the same consumer-visible effect.
2. The corrected note, .changeset/19911-readonlywhen-interdependent-locks.md (pending; a DELIBERATE CORRECTION under check-empty-changeset.mjs). Each rewritten sentence is judged against the code at this head:
   • "A lock is judged after the locks whose fields it reads, with each value they drop put back to the row's stored one." TRUE: dependency order of the SCC groups, withoutKeys(stored, dropped).
   • "Locks that read each other in a cycle are judged together, again with each dropped value put back, until no further field locks." TRUE: the cycle fixpoint in settleLockGroup.
   • "Then the fields held only by a value that was later put back are released, and every lock in the cycle is judged again against what that release stores, round after round, until the dropped fields are exactly the ones locked on the row the update stores." TRUE: the release rounds, scoped to the cycle.
   • "after one round more than the cycle has fields, the first, larger set of drops stands for the cycle's fields instead." TRUE: the first release set plus m sets, then the fixpoint set for that group's keys only.
   • "only when its lock is in a cycle of locks that read each other's fields (a parent-scoped lock counts as reading the master-detail field …, and a lock that reads record other than as record.FIELD counts as reading every field)." TRUE: recordFieldsRead; both conventions measured.
   • "A field whose lock is in no such cycle is dropped exactly when its lock is TRUE on the row the update stores (on a bulk update, on at least one matched row)." TRUE: 0 of 11,885 violations, single-row and bulk.
   • "Where a cycle's drops do not settle, the first, larger set stands for that cycle's fields: a lock the update cannot settle is not waived." TRUE.
   • The untouched paragraphs, including the a/b no-set and two-set examples: head drops both in each, and they stay pinned by the A record-scoped readonlyWhen reading a field that another readonlyWhen drops in the same pass is judged against the dropped value, so a closed row locked amount is rewritten #19911 suite.
3. Dev open question (the 19911 correction): option A is right. Restoring the base text would republish a whole-update bound and fallback the shipped code no longer has.
4. Dev deviations are all real and sound:
   • SCC is better than connected components (the out_of_cycle pin shows the difference).
   • The H3 wording flag is honest; the invariant actually measured is the contract's.
   • The 4-in-16,500 delta is real, cycle keys only and fail-safe, and is stated in both changesets.
5. Dev out-of-scope observations: both are real and neither is a filing class. The fields.mdx silence on cycle over-locking is a docs gap. The payload-order onFieldsDropped listing is pre-existing and pinned.
6. The tests pin the fix and can fail: 18 of 18 red against the merge-base validator. The every = true to every = false ablation reddens exactly the two index-read pins.

Implemented-by: claude/issue-19929-readonlywhen-per-component-fallback
Reviewed-by: session_01Bvd69VPa6puiNzzPUroDBx

VERDICT: PASS

Isolated reviewer: a separate contract-review-tier subagent, fed the card, the parent card, the PR, fields.mdx and AGENTS.md only; adopted by the seat.

---

Generated by Claude Code

[objectstack-fleet]

Pending release-note correction on this PR: Check Changeset is red by design, awaiting written confirmation

domain:engine#1, session_01Bvd69VPa6puiNzzPUroDBx, written 2026-09-24T14:31Z.

Per check-empty-changeset.mjs (the foreign changeset rule, DELIBERATE CORRECTION class) and pr-automation.yml route 0, this PR names the note it corrects and what changed under it, here, and leaves Check Changeset red until that is confirmed in writing.

• The note: .changeset/19911-readonlywhen-interdependent-locks.md. It is PENDING: on main, not yet consumed by a release. It was added by PR fix(objectql): judge each readonlyWhen lock against the row the update stores, not a value another lock drops (#19911) #19923 (A record-scoped readonlyWhen reading a field that another readonlyWhen drops in the same pass is judged against the dropped value, so a closed row locked amount is rewritten #19911).
• What changed under it: that note says drops that do not settle fall back to "the first, larger set of drops" for the WHOLE update, and that a field whose lock is FALSE can be dropped "only where locks read each other in a cycle". The second sentence holds per update, not per field. This PR settles locks cycle by cycle, so both sentences would be false for the shipped code. The PR rewrites exactly those two passages (+18 / −14) to describe the per-cycle settlement; nothing else in the note moves.
• Why not restore it: restoring the base text republishes, into @objectstack/objectql's CHANGELOG, a whole-update bound and fallback that the code no longer has.
• Verified: the isolated contract review of record at this head (2d75a593) judged every rewritten sentence TRUE against the code and a fresh probe.
• Not applied, per ruling D on [finding] the skip-changeset label suppresses the DELIBERATE-CORRECTION refusal whose own text says 「no label and no diff shape makes that safe」 — declared contract against enforced behaviour #18375: skip-changeset. This PR also releases its own change under .changeset/19929-readonlywhen-cycle-isolation.md.

Confirmation, per ruling 1A (#19940, record 5814546887, batch #220 item 3, maintainer 2026-09-24T12:56Z): 「an at-tier contract-review PASS record on the same head that names the corrected note and judges each rewritten sentence is the confirmation. The seat enqueues under the three-condition red-by-design path.」 That record is 5816146511 at 2d75a593. The three conditions: ① the gate states it stays red by design (check-empty-changeset.mjs, the DELIBERATE CORRECTION class); ② Check Changeset runs in pr-automation.yml, which triggers on pull_request only, never merge_group; ③ this comment records the gate and the reason. (Superseded wording: an earlier revision of this comment routed the confirmation to the decision box. It was written before the seat read ruling 1A.)

---

Generated by Claude Code