docs(objectql): record the deliberate lock-face/static-face asymmetry, and pin both faces

[os-musk]

Fixes #14259

Seam 1 residual only. Seam 2 landed as 00ff228fe (PR #14472) with a Part of line; the card was held open for this half.

No behaviour moves. Every changed line in packages/objectql/src/validation/rule-validator.ts is a comment line, mechanically verified — the diff of that file with comment lines filtered out is empty. The other two files are tests. This is an S card: it writes down a rule that already holds.

What the maintainer ruled (decision batch #12 item 4, #14259 comment 5511947941)

B. Seam 1 (isCallerSuppliedValue, behind stripReadonlyWhenFields / stripReadonlyWhenFieldsMulti) stays on value equality. On a readonlyWhen state lock, a before-phase hook assignment that writes back the value already on the key — data.x = data.x, or a normalisation that is the identity for canonical input — does not count as a hook write: the caller's value is stripped, with the existing warning and the same onFieldsDropped / strictReadonlyWrites reporting. LOCK 3b stands as the pin of that rule. The divergence from the provenance-based static face is recorded as a deliberate, lock-motivated asymmetry, and each face carries a measurement pin. The residual (a hook deriving a locked field while the caller echoed the identical value loses its write) is accepted; no instance exists in the tree.

The three things this PR is

1. The docblock correction

The false sentence, quoted verbatim from origin/main before this PR:

Shared by the single-id and bulk strips so the two can never disagree about what "caller-supplied" means, and written to be textually parallel with the same test inside stripReadonlyFields.

...and, four paragraphs up in the ReadonlyWhenStripOptions docblock the above @links to, the same claim stated more strongly:

a key is judged only when it is still the caller's — the identical two-part test stripReadonlyFields applies

Both were true when written and neither has held since #14088 moved stripReadonlyFields onto a record of the keys the before-phase hook chain assigned (options.hookWrittenKeys), asked ahead of the value comparison. Both are corrected in place to state the asymmetry and its reason, which is what each face guards:

• static face — stripReadonlyFields, and its insert-side twin stripRuntimeOwnedFields (fix(objectql): decide the insert-side runtime-owned strip by hook-write provenance #14472) — guards an author-declared readonly or a runtime-owned column. Hook authorship is the exemption on offer, so "the chain assigned this key" is the right evidence, and the record's blindness to the value is precisely what makes it correct: it separates the hook wrote the null the caller also sent from the hook never touched the key.
• lock face — this predicate — guards a readonlyWhen state lock, whose entire guarantee is that no caller write survives a TRUE predicate (Parent-scoped readonlyWhen is unenforced server-side — the field lock fails open, so a paid invoice's frozen lines can be rewritten over the API #4889's frozen paid-invoice lines). That same blindness would let the innocuous line above hand the caller's own value hook ownership and silently unlock the lock. Measured, not feared: threading the record into this predicate turned LOCK 3b red on fix(objectql): decide the insert-side runtime-owned strip by hook-write provenance #14472's branch.

The second correction is inside the same isCallerSuppliedValue region and is the same claim; leaving it would have left the docblock still asserting the falsehood this card exists to retire.

2. The two face pins, written to be read side by side

• Lock face — LOCK 3b in engine-readonly-when-derived-writes.test.ts. Assertions unchanged; its comment now names the asymmetry, the reason, and the sibling pin that records the opposite verdict for the identical hook spelling.
• Static face — new: MEASURED: a lone self-assigning hook leaves the CALLER value on the key, in stripReadonlyFields uses Object.is to tell a hook write from a caller write, so a hook cannot clear a readonly field the caller also sent as null #14088's own suite engine-readonly-strip-caller-values.test.ts.

Why a new pin rather than a reference to an existing one. The card asked me to check whether engine-hook-provenance-sibling-seams.test.ts already carries this. It carries a case with that exact name — but that suite is seam 2 — the insert-side runtime-owned strip reads PROVENANCE, its subject is engine.insert on an autonumber column, and it pins stripRuntimeOwnedFields. That is a different face from the update-side static readonly seam stripReadonlyFields the ruling names. Verified: nothing in engine-readonly-strip-caller-values.test.ts covered the self-assignment input, and hook-write-provenance.test.ts unit-tests the recorder rather than a strip face. So the update-side static face genuinely had no pin, and now has one.

Both new comment blocks state that a future ruling reversing this inverts the pins rather than deleting them.

3. One patch changeset

.changeset/lock-face-value-equality-recorded.md. isCallerSuppliedValue and ReadonlyWhenStripOptions are both package-internal and unexported, so neither docblock reaches dist/*.d.ts; the changeset is a plain patch, no ADR-0087 marker owed (not breaking).

Verification — all on the final merged head da2dc1967

• pnpm --filter @objectstack/objectql test — 263 files / 4553 tests passed.
• pnpm --filter @objectstack/objectql typecheck — green; verdict line check:test-typecheck: OK — @objectstack/objectql's test layer compiles under packages/objectql/tsconfig.test.json. The test layer is compiled by a sibling tsconfig.test.json, so the two edited test files really are type-checked.
• pnpm lint — full repo, eslint . --no-inline-config, exit 0. No narrowing claimed.
• Gate family re-derived on the final tree with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands (identical before and after the origin/main merge, 38 commands). 34 green. Four exit 3, each printing its own PREREQUISITE NOT MET / NOT MEASURED verdict rather than a finding, all needing a full workspace build or a saved turbo run test log this container cannot produce: check-test-completeness, check:dual-build-cjs-loads, check:type-check-debt, check-half-states. Recorded as NOT MEASURED, not as green and not as red. Exit codes were captured by redirecting to a file first, never through a pipe.

Reverse verification of the new pin

Committed first, then mutated, with an absolute-path trap restore. The pin's hook was retargeted from completed_at to title so no hook write is recorded for the locked key. Mutation proved on disk before running (target occurrences 1 to 0, injected 1, blob 986d3b0a to eb33cb5e). Predicted direction RED; observed RED:

AssertionError: expected '2026-08-01T09:00:00.000Z' to be '1999-01-01T00:00:00.000Z'

That is the stored STAMPED timestamp surviving — the strip taking the caller's forged value away once the self-assignment stops being recorded. The pin measures the provenance seam rather than restating a tautology. Restore proved byte-exact afterwards: blob back to 986d3b0a, git diff HEAD empty, git status --porcelain empty.

Scope

packages/objectql/src/engine.ts was not touched — it is held in flight by another dispatch (#14399). origin/main was merged immediately before opening this PR; #14311's checkStateMachine change landed around line 2180 of the same file, a different region, and merged cleanly. The full objectql suite and the gate family were re-run afterwards, on the merged head.

One stale-prose finding in engine-hook-provenance-sibling-seams.test.ts is filed separately rather than fixed here; it is named in the report comment on #14259.

🤖 Generated with Claude Code

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 1 changed file(s) yielded no anchor (packages/objectql/src/validation/rule-validator.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/objectql/src/validation/rule-validator.ts) — pages documenting those are invisible to this run
• 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.

Coarse fallback — 16 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 a3d5724c8857d8e31721feceadd1a62e04934674 → packageMentionDocs.

[os-musk]

Landing provenance (engine execution seat, session session_0112hMx9hjJ9BgB28X97DS68): flipped ready at 19:23Z and armed auto-merge (squash) at 19:23:52Z on head da2dc1967. The echo read method: MERGE; the queue build ref is the arming reading, not the echo.

• Review: ACCEPT on the card, comment 5514606510. Clause-② no — the ruling itself says so: no accept set moves, the behaviour written down is today's behaviour. In-seat review is in order; the CONTRACT_REVIEW_TIER requirement binds Clause-② yes cards, and this seat is currently off tier (claude-opus-5 served against claude-fable-5-1 required).
• Governed-surface test re-run on the final four-path file list: 0 of 4 path(s) hit the register — ordinary queue landing. Re-derived rather than recalled.
• Enqueue bar: all 33 check runs on da2dc1967 completed success or skipped, read with perPage: 50. Last standing was Test Core (1/6) (18:38:37Z → 19:02:15Z, 24 min — the long shard's usual band) and the Test Core rollup behind it at 19:02:32Z. The full page was re-read before calling it green rather than inferring the total from the one job that had been outstanding.
• Verified by this seat against the tree rather than the report: rule-validator.ts is comment-only (added lines filtered against ^\+\s*(\*|//) leave an empty set); packages/objectql/src/engine.ts is absent from the diff, so the serial slot held by The two SOURCE view-container registrars disagree on where the row's own name sits in the object-derivation chain #14399 was respected; LOCK 3b stands at engine-readonly-when-derived-writes.test.ts:219.

⭐ The substantive correction this PR carries is to the ruling's own parenthetical. Ruling B said the static face was "already pinned"; measured, the existing MEASURED: case sits in describe('seam 2 — the insert-side runtime-owned strip reads PROVENANCE') and pins stripRuntimeOwnedFields on engine.insert, which is a different face from the update-side static stripReadonlyFields the ruling names. The card therefore shipped two pins, not one. The dispatch carried that parenthetical as a Zone 2 item to verify rather than as a fact — the only reason it was caught.

⚠️ Known exposure: the queue build runs the full suite, so this PR meets packages/cli/test/run-dev-unbuilt-workspace.e2e.test.ts — the flake tracked on #14648, which ejected #14629 at 17:45Z. If ejected, the disposition is fixed: ⛔ no re-queue while #14648 is open, ⛔ no weakening of that test, and the card goes to pm:blocked with an Unlock-action: line rather than being re-dispatched.

Owed by the seat at MERGED: verify by content on origin/main that both docblock corrections landed and both face pins are present, then — because this is Fixes #14259 and closes the card — strip every pm:* label in the same stroke, post the landing record, and reconcile inventory. Seam 1 and seam 2 are both delivered at that point.

---

Generated by Claude Code