feat(engine)!: findOne, update and delete declare what they answer, and their hook seams are guarded (#16231)

[os-musk]

Fixes #16231

Clause-②: yes

Executes the maintainer ruling on #16231 — option A, 「同意」, director seat summon #17, decision batch #2, comment 5572153316. Options B (declare only, no enforcement) and C (record any as intended) were refused there and nothing here reopens them.

Angle brackets do not survive this body's sanitizer, so declared types are spelled with square brackets, the same convention the card uses: Promise[Record[string, any] | null] is the real generic.

What this changes

engine.ts has four return hookContext.result sites, one per hook-bearing verb. #15823 closed the find() one — an afterFind handler that replaced the array made a method declared Promise[any[]] resolve to an envelope, silently — and recorded that it could close only that one, because the other three declared Promise[any] and carried nothing a handler could break. A guard cannot exist before a declaration worth guarding does. This PR writes the three declarations down and then closes their seams.

verb	declared before	declared now	where the shape comes from
findOne	Promise[any]	Promise[Record[string, any] | null]	driver.findOne → Promise[Record[string, unknown] | null]
update	Promise[any]	Promise[Record[string, any] | number | null]	by-id driver.update → record-or-null; predicate driver.updateMany → affected count (#4639)
delete	Promise[any]	Promise[boolean | number]	by-id driver.delete → boolean; predicate driver.deleteMany → affected count

⭐ The shapes were derived from the code, not from an assumed symmetry with findOne. update and delete each have TWO driver exits and the dispatch ladder (resolveEngineUpdateDispatch / its delete twin) picks between them, which is exactly why their declaration is a UNION and findOne's is not. engine.ts states the predicate half in its own prose at the branch that feeds the realtime publish — the sentence cites #4639 and reads: "A predicate update … an affected-row COUNT, which the strip skips as a non-object." (The verb between those two words is a closing keyword, so it is elided here rather than parked beside a card number.)

⚠️ Row FIELD values stay erased (Record[string, any], not Record[string, unknown]). That is #15823's precedent extended exactly rather than softened: find() declares Promise[any[]], so the CONTAINER is the contract and the rows inside are any. It is also the only spelling that can state "record or null" at all, since any | null collapses to any in TypeScript. The strict alternative was measured and is reported on the card as a strictly larger option.

The census — done FIRST, posted on the card before any declaration shipped

The maintainer accepted ruling A on a stated precondition: count the consumers whose compilation the narrowing breaks, and post the number on the card. Discharged in comment 5578614790.

18 files · 92 compile errors, measured by compiling all 31 workspace packages twice:

• control — turbo run typecheck --continue on the unmodified worktree at origin/main 5e53d73d83: 142 tasks, 142 successful, exit 0. A clean baseline, so every treatment error is attributable.
• treatment — the same command with the declarations narrowed: 136 successful, 6 failed.
• 3 non-test src files / 9 sites; 15 test-and-pin files / 83 errors. ⭐ A census scoped to non-test sources would have said 3 files and been wrong by a factor of six — the pins are where this contract is encoded.
• The dominant signature is TS18047: 'row' is possibly 'null': the null check the declaration exists to force.
• objectstack-ai/objectui, cloned at 67299bf43b: 0 consumers (386 files import @objectstack/spec — the positive control fires — and zero name IDataEngine, IObjectQLEngine, IScopedObjectRepository or IScopedContext). objectstack-ai/cloud is not reachable by this session and is unmeasured; so are npm consumers outside the org.

Every one of the 92 is repaired here.

A second drift class the GUARD found, that the type could not

Four test doubles answered shapes their own IDataDriver contract does not have, invisible while the engine door said any:

• { deleted: 1 } / { deleted: 0 } from delete / deleteMany — packages/spec/src/contracts/data-engine.test.ts, packages/runtime/src/seed-loader.test.ts, packages/objectql/src/engine-filter-tokens.test.ts
• an ARRAY of rows from updateMany, which declares Promise[number] — packages/objectql/src/plugin.integration.test.ts (two doubles)
• undefined from a bare vi.fn() on update / delete — packages/objectql/src/engine.test.ts (two doubles)

All repaired to the declared shapes, and the { deleted: n } envelope now has a pin of its own so it cannot come back.

⚠️ That discovery changed the refusal's wording, and the change is load-bearing. find()'s refusal can say "your handler replaced ctx.result" because the value at that seam always comes from driver.find, which every driver answers with an array. These three verbs have exits that can answer off-contract themselves, so the sentence now names the SEAM and accuses nobody — "after the 'afterUpdate' dispatch 'ctx.result' is undefined" — and developerMessage names BOTH possible sources. A sentence blaming the handler would have sent four of the repairs above to the wrong file.

Symbols re-derived on origin/main, with firing controls

The card's own anchors (:9565 / :9784 / :12103 / :13537, at bdc02182b) had all drifted, so everything was re-derived by symbol via git show origin/main:..., never from a working tree.

• Firing control: hookContext occurs 116 times in engine.ts, which is 15,020 lines — both matching the dispatch's stated readings exactly.
• four return hookContext.result sites: :9599, :9818, :12137, :13572
• find :9439 → Promise[any[]]; findOne :9705, update :10871, delete :13089 → all Promise[any]
• packages/spec/src/contracts/data-engine.ts :276 / :278 / :279; scoped-context.ts :148 / :164

The surface the ruling does not name — reported, not absorbed

ObjectRepository at engine.ts :14498+ is the same contract, not a separate one: export class ObjectRepository implements IScopedObjectRepository, the very interface the ruling names at scoped-context.ts:148/164. But narrowing the interface does not narrow the class, because TypeScript's implements accepts Promise[any] against any declared return — any is assignable in both directions.

That matters because ScopedContext.object(name): ObjectRepository returns the class, and ScopedContext IS HookContext.api. ⇒ a hook author writing ctx.api.object('task').findOne(...) still reads any after this PR; only a consumer who annotates the api as IScopedContext gets the narrowed answer. ⛔ Not fixed here — it needs its own consumer census, and widening this PR to take it is what the dispatch forbade. Same for IScopedObjectRepository.updateById (scoped-context.ts:167), still Promise[any]; the ruling names :148/164 and not :167.

Verification

Two-leg ablation, blob-hash-verified restore. The three shape predicates in verb-hook-result-shape.ts were mutated to always answer "legal".

• ⚠️ Two earlier attempts are reported rather than hidden. The first mutation did not COMPILE (TS6133, an unused symbol), so dist never carried it and ablation-dist-preflight correctly said ABSENT. The second compiled but carried its marker in a // comment, which the bundler strips — again ABSENT. Only the third, whose marker is a live string literal read through .length, is the measurement below.
• mutate leg: marker on disk 0 → 3 · blob eb59c5c9… → 352bd54d… · pnpm --filter @objectstack/objectql build exit 0 · ablation-dist-preflight … ABLATION_16231_GUARD_DISABLED → ✓ marker present in 4 built files, exit 0 · pin suite 15 failed | 14 passed (29).
• restore leg: git checkout HEAD -- PATH · RESTORE ok: blob eb59c5c9e87e67ceb0371bb3084d85ec70338310 == HEAD · git diff HEAD for the path EMPTY · preflight --absent → ✓ marker absent from all 14 built files and ✓ tree: working tree clean against HEAD, exit 0 · pin suite 29 passed (29).
• ⭐ The 14 that stayed green are held by DESIGN, and that is the correct reading, not a broken ablation. They are exactly the "declared limbs are answerable" cases (7), the "shaping stays legal" cases (5) and the vocabulary cases (2) — none of which exercises a refusal. Every one of the 15 refusal cases went red. The layer holding those 14 is the ENGINE's own dispatch and the driver contract, which the guard does not create and must not disturb; a guard-ablation that reddened them would mean the guard had taken over behaviour it only checks.

Tests, all re-run after the final commit — git rev-parse --short HEAD = c5935b2445, working tree clean:

package	result
@objectstack/objectql	286 files / 4837 passed, 0 skipped
@objectstack/spec	465 files / 12952 passed, 0 skipped
@objectstack/metadata	52 files / 797 passed, 0 skipped
@objectstack/metadata-protocol	169 passed + 2 skipped files / 2433 passed + 10 skipped tests
@objectstack/plugin-auth	104 files / 2191 passed, 0 skipped
@objectstack/plugin-approvals	42 files / 705 passed, 0 skipped
@objectstack/rest	192 files / 3241 passed, 0 skipped
@objectstack/runtime	240 files / 3340 passed, 0 skipped
@objectstack/service-automation	125 files / 1486 passed, 0 skipped

⚠️ The skipped faces, named and counted — 2 files, 10 tests, both environment-gated on OS_TEST_MYSQL_URL and unrelated to this change: src/migrations/seed-tenancy-backfill.live-mysql.test.ts (5) and src/migrations/sys-setting-identity-index.live-mysql.test.ts (5), both describe.skipIf(!MYSQL_URL).

typecheck legs. tsc --noEmit and the per-package check:test-typecheck ratchet both ran. The ratchet is the leg that matters here, because it sees the test layer the plain build does not: @objectstack/objectql OK (44 files / 242 errors / 69 pinned signatures held), @objectstack/spec OK (54 / 261 / 145), @objectstack/runtime OK (27 / 191 / 69). @objectstack/service-automation compiles its tests through plain tsc --noEmit, which went from 30 errors to exit 0.

Gate reconciliation, verbatim — derived and re-run in full on the FINAL head c5935b2445 (node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --ran RANFILE, exit 0), with all 111 exiting 0:

Run reconciliation — 111 derived, 111 run, 0 NOT-MEASURED, 0 UNRUN.
✓ dispatch-gates --ran: 111 derived famil(ies) accounted for — 111 run, 0 NOT-MEASURED.

⚠️ The union was re-run on the final head deliberately: the ratchet families (check:type-check-debt, check:type-check-coverage, check:test-source-alias, check:cross-package-test-inputs, check:dual-build-cjs-loads, check:engine-double-contract) measure the tree, so a late commit moves exactly the readings a stale run would have quoted.

The first derivation named 88; regenerating content/docs/references/** (the error-code ledger gained three codes) grew the change set and the re-derivation named 111. The extra 23 were run and reconciled. Two went red and were fixed rather than argued: @objectstack/spec check:docs (generated docs out of date — regenerated with gen:schema && gen:docs) and check:doc-authoring (a tracker id had landed inside a runtime string, which reaches operators who cannot resolve one). ⛔ Neither check:type-check-debt nor check:dual-build-cjs-loads refused with PREREQUISITE NOT MET: both ran on a fully built closure and reported real measurements (5 ledger entries re-measured, 55 raw tsc errors, none above its recorded number; entries/packages/cjsFiles/probes 104/67/620/1 vs floors 90/58/520/1).

Changeset level, and the text it is based on

minor for @objectstack/spec and @objectstack/objectql, patch for the three repaired consumers, with the **BREAKING** banner and an ADR-0087 disposition.

• Governing text — the one this level is based on: the WHICH LEVEL maintainer ruling of 2026-09-04 (decision batch [WIP] Add query enhancements and advanced validation features #35, on finding(changeset): two independent contract reviews read the repo's own history to opposite bumps for "add an exported symbol to a published index" #15294), recorded at .github/workflows/pr-automation.yml: "During the launch window major stays refused by check-changeset-no-major and breaking-ness is carried by the BREAKING banner plus the ADR-0087 disposition, not by the level", and "A purely additive widening of a published package's public surface … takes at least minor" — which this PR is on its own, since it adds three exported error classes, their codes and their shape predicates to @objectstack/objectql's index.
• Text REJECTED as the ceiling: AGENTS.md's "a bug fix in a released package takes a patch changeset — never none". That is the floor against none, not a ceiling, and reading it as one would have shipped this at patch.
• ⛔ A green from check-changeset-no-major is not by itself the justification: its level axis has a measured blind spot for nested package dirs (carded as [finding] The changeset LEVEL axis is blind to every NESTED package: packages/*/src/** matches one segment, so 51 of 74 workspace packages (all drivers/services/adapters) can pair Clause-②: yes with patch and stay green #16713). packages/spec/* and packages/objectql/* do match it, so it genuinely grades this one — but the argument above is the reason, not the gate.
• ADR-0087 disposition: not-required (no-migration-prescription). Nothing authorable moves — no spec key, no authored metadata property, no accepted request shape, nothing for objectstack migrate meta to rewrite. ⚠️ type-surface-only is the category built for exactly this class and it is not claimed, because its predicate 2 (no-spec-diff) is mechanically false here: the surface the ruling names IS packages/spec/src/contracts/**. Reported below rather than worked around, and ⛔ the **BREAKING** token is carried rather than dropped — dropping it is the erosion [finding] check-adr-0087-registration has no honest disposition for a published TYPE-surface narrowing — every category is refused, so the class is pushed to drop the **BREAKING** token instead #13080 was filed to stop.

验收备注

Findings met on the way, recorded here rather than fixed in this PR:

1. ScopedContext.object(name) returns the CLASS, so the ruled narrowing does not reach ctx.api. Detailed above. A one-line annotation change plus its own consumer census.
2. IScopedObjectRepository.updateById (scoped-context.ts:167) stays Promise[any] while its update sibling narrows. Not named by the ruling.
3. @objectstack/metadata-protocol declares record / data non-null on its row receipts, while engine.update's by-id exit can answer null — updateData's own comment states the mechanism ("the post-write readback … is also null when the row still exists but the write moved it out of the caller's row scope"). While the door said any this was invisible. This PR preserves the behaviour exactly and writes the disagreement down at byIdUpdateRecord rather than widening a shipped response shape as a rider.
4. check-adr-0087-registration's type-surface-only category cannot be claimed by the class it was built for when the narrowed declaration lives in packages/spec/src/contracts/**. Predicate 2 is no-spec-diff, and a spec-owned contract narrowing is the most likely shape of a published type-surface narrowing in this repo. The category's own header says the alternative an author reaches for is dropping the **BREAKING** token, which [finding] check-adr-0087-registration has no honest disposition for a published TYPE-surface narrowing — every category is refused, so the class is pushed to drop the **BREAKING** token instead #13080 exists to prevent.
5. core-boundary.ratchet.test.ts flags a forbidden package name in any QUOTED string in core.ts's closure, import or not. Prose in a developerMessage naming the metadata protocol package reddened it. Correct-by-construction for the ratchet's purpose, surprising to hit from a message string; worked around in-file with a comment naming why.

⛔ #15267 does not ride along. It is the driver-layer twin (driver-sql / driver-turso publishing Promise[any] on five IDataDriver doors). Neither card contains the other, and ⛔ neither closes as a duplicate of the other.

Draft only. ⛔ Never ready, never auto-merge, never queue — the in-seat contract-tier review runs before anything lands, and needs:contract-review is hung on this PR.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 5 package(s): @objectstack/metadata-protocol, @objectstack/metadata, @objectstack/objectql, @objectstack/plugin-auth, @objectstack/spec, touching 35 documentable anchor(s). ⚠️ 2 changed file(s) yielded no anchor (packages/objectql/src/find-hook-result-shape.ts, packages/objectql/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

37 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json ed7243d52bbc1b6d00a3b621b0dcea4925df32b5.

⛔ 4 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 2 changed file(s) yielded no anchor (packages/objectql/src/find-hook-result-shape.ts, packages/objectql/src/index.ts) — pages documenting those are invisible to this run
• 1 cross-cutting symbol(s) contributed no route anchor: updateData (4 routes)
• 1 anchor(s) matched too much of the corpus to be a work list: ObjectQL (symbol, 66 pages)
• 4 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 61 of 219 client-bound route-ledger rows — the other 158 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 158: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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.

Coarse fallback — 136 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 ed7243d52bbc1b6d00a3b621b0dcea4925df32b5 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 223f889a0977c0efee9ee8ec4e162551912d17d6 — the merge of head c5935b2445a301181271767e9b2718242eec1dd9 into base ed7243d52bbc1b6d00a3b621b0dcea4925df32b5, 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 223f889a0977c0efee9ee8ec4e162551912d17d6 && git checkout 223f889a0977c0efee9ee8ec4e162551912d17d6
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin ed7243d52bbc1b6d00a3b621b0dcea4925df32b5 c5935b2445a301181271767e9b2718242eec1dd9 && git checkout -B drift-repro ed7243d52bbc1b6d00a3b621b0dcea4925df32b5 && git merge --no-ff c5935b2445a301181271767e9b2718242eec1dd9

node scripts/docs-audit/affected-docs.mjs --json ed7243d52bbc1b6d00a3b621b0dcea4925df32b5

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

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs ed7243d52bbc1b6d00a3b621b0dcea4925df32b5 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-zhuang]

Contract review (CONTRACT_REVIEW_TIER, isolated seat) — PR #16783 @ c5935b2

Verdict: CHANGES REQUIRED — one required gate is red on the head (Check Changeset, level axis), which makes the PR unmergeable regardless of the review; the contract work itself is sound and would be PASS WITH FINDINGS once F1 is fixed.

Ruling implemented: exactly — three declarations (data-engine.ts findOne/update/delete, scoped-context.ts:148/164, ObjectQL itself), three seam guards mirroring find()'s, pins per verb, the census posted on the card before any declaration moved (comment 5578614790), consumer repairs the census names, changeset minor on @objectstack/spec + @objectstack/objectql with the **BREAKING** banner and an ADR-0087 disposition, #15267 not ridden along. Wider only by the three exported predicates/error classes on @objectstack/objectql's index, which is the #15823 precedent's own pattern. Two surfaces outside the ruling's anchors (ObjectRepository/ctx.api, updateById) are reported, not absorbed — see F6.

Read independently: PR body, its one bot comment, card #16231 body + all 8 comments; code via git fetch of the head into a throwaway ref against origin/main (merge-base 8ccf7a1d); CI via check runs and the failing job's log. Nothing in the PR body was taken on trust.

1. The ruling, verbatim, and its provenance

Card #16231, comment 5572153316 (hotlong, MEMBER, director seat), 2026-09-07:

Ruling recorded — A: findOne / update / delete declare what they answer, and the hook seam is guarded the way find() is — after the breakage is measured first (director seat, summon #17, decision batch #2, 2026-09-07)

Provenance (who / verbatim / where): maintainer, live PM chat with the director seat (session_01XesLUWmuhjuRwmU618AZ1M), 2026-09-07T14:4xZ, batch #2 presented as 1B · 2A · 3(1) · 4A · 5(2) with this card as item 4 recommending A with a measure-first premise (the 5571647365 four-facet block); reply, verbatim: 「同意」.

Ruled. The find() rule from #15823 extends to the other three verbs: ObjectQL.findOne declares a record-or-null result, update and delete declare their result shapes (packages/spec/src/contracts/data-engine.ts:276-279 and the scoped-context mirrors at scoped-context.ts:148/164, read on origin/main), and each hook seam guards hookContext.result against its declaration exactly as find() now does. Options B (declare only) and C (record any as intended) are refused.

Premise the dev verifies before any declaration moves (the confidence gap the maintainer accepted): count the consumers, in-repo and in the consuming repos this session can reach, whose compilation the narrowing breaks; post the number on this card. A large number is a fork to report with the list, ⛔ not a reason to fall back to B silently — the ruling stands, the sequencing is the seat's.

Execution, domain:engine lane: one PR — three declarations, three seam guards, pins per verb, consumer repairs the census names, changeset minor for @objectstack/spec (and the engine package) with the BREAKING banner + ADR-0087 disposition (a published .d.ts narrows). Clause-②: yes ⇒ dispatch at CONTRACT_REVIEW_TIER or with the carrier as compensation. #15267 (the driver-layer twin) does not ride along.

This is a maintainer ruling (verbatim 「同意」 to a batch whose item 4 recommended A), recorded by the director seat with provenance — not a seat or triage preference. Triage (5571647365, os-zhuang) recommended A but explicitly did not rule. The "WHICH LEVEL" text the changeset cites is likewise a maintainer ruling (batch #35, on #15294) recorded verbatim in .github/workflows/pr-automation.yml:667-682. The PR body's citations are accurate.

2. Files vs merge-base, governed paths

31 files (A 3, M 28), 8 commits on the branch. Governed paths (docs/adr/**, .claude/**, skills/**, AGENTS.md, CLAUDE.md, content/docs/releases/**): none touched. The two content/docs/references/api/*.mdx edits are the AUTO-GEN surface (AGENTS.md:677), regenerated by gen:schema && gen:docs; the drift bot's "4 release-owned pages affected" is about pages that name touched symbols, not pages this diff edits.

3. The contract change

verb	origin/main	head	driver exit(s) actually reached
IDataEngine.findOne / ObjectQL.findOne / IScopedObjectRepository.findOne	Promise<any>	Promise<Record<string, any> | null>	driver.findOne → Record<string, unknown> | null
IDataEngine.update / ObjectQL.update / IScopedObjectRepository.update	Promise<any>	Promise<Record<string, any> | number | null>	by-id driver.update → record-or-null; predicate driver.updateMany → count (only two result = assignments exist inside update(), engine.ts:11839 and :12047)
IDataEngine.delete / ObjectQL.delete	Promise<any>	Promise<boolean | number>	by-id driver.delete → boolean; predicate driver.deleteMany → count

No throw arm was added to the declarations; the guards add one runtime arm each. "Hook seams are guarded" in code: verb-hook-result-shape.ts exports three typeof/Array.isArray container predicates (isFindOneResultShape, isUpdateResultShape, isDeleteResultShape — identity-free, so in-place mutation and reassignment to a legal shape stay legal; false/0/null are admitted where declared; undefined refused everywhere), and engine.ts calls each immediately after the after* dispatch and before maskSecretFields/stripSearchCompanion*/realtime publish (:9819, :12105, :13585), throwing an error class with code+status (500) — the same placement and envelope as #15823's find() guard.

Consumers (in-repo, non-test, head): packages/metadata/src/loaders/database-loader.ts (3 sites), packages/metadata-protocol/src/protocol.ts (4 by-id engine.update sites + updateData), packages/plugins/plugin-auth/src/objectql-adapter.ts (2), packages/runtime/src/sandbox/body-runner.ts (2), packages/objectql/src/lifecycle/lifecycle-service.ts (2), packages/objectql/src/validation/rule-validator.ts, packages/core/src/utils/{bulk-write,metadata-activation-store}.ts, packages/platform-objects/src/system/migration-flag.ts, packages/metadata-protocol/src/migrations/recorded-by-sentinel.ts, spec migration entries (prose examples), examples/app-showcase (3 ql.update calls, result discarded), examples/app-todo (its own engine shape on the action ctx, not IDataEngine). apps/* and examples/* are workspace members (pnpm-workspace.yaml) and were inside the turbo run typecheck census. Compiled types move only where a result is read without a null check or where the number limb reaches a record slot — the three non-test files the census names, plus 15 test files; I found no fourth. Runtime behaviour on the published doors: yes (Clause-②) — three new 500 refusal paths at the seams. Against every in-repo driver (memory results[0] || null, sql results[0] || null / formatOutput(...) || null / count > 0, mongodb ?? null / deletedCount > 0, turso ?? null / rowsAffected > 0) every exit is on-contract, so no in-repo caller's runtime output changes; the only measured runtime effects were the seven off-contract test doubles the PR repairs. The consumer repairs are no-ops on reachable paths (number limb unreachable from by-id calls) — verified against resolveEngineUpdateDispatch's use at :11252.

4. Changeset

.changeset/engine-verb-result-declarations.md: @objectstack/spec: minor, @objectstack/objectql: minor, @objectstack/metadata: patch, @objectstack/metadata-protocol: patch, @objectstack/plugin-auth: patch. **BREAKING** banner present; <!-- adr-0087: not-required (no-migration-prescription) … --> parses — check-adr-0087-registration on the head logs [BREAKING+bang] not-required (no-migration-prescription); the ! commit owes both and both are present. major correctly refused/absent. But the level axis is red — see F1. Type FROM/TO per door is stated; runtime FROM/TO is stated once for all three doors — see F3.

5. Tests

packages/objectql/src/engine-verb-hook-result-shape.test.ts: 29 cases (9/9/9 per verb + 2 vocabulary), counted independently; 15 refusal cases assert instanceof + code + status + event + object + observed via an outcomeOf capture (no bare toThrow()), 14 answerability/shaping cases exercise the real engine over an on-contract driver. Refusal cases redden if any guard is removed (consistent with the PR's 15/14 ablation; the 14 greens are held by the engine/driver, correctly). The { deleted: 1 } envelope has its own pin; the sanitizeRowError SQL-verb constraint is pinned. ErrorCode.safeParse control rejects a near-miss spelling. No it.skip/.only/.todo/xit in any changed test file (scanned all 17). Typecheck coverage: tsconfig.test.json includes src/**/*, typecheck chains check:test-typecheck; CI Type Check · workspace / debt ledger green. The seven double repairs (data-engine.test.ts, engine.test.ts, plugin.integration.test.ts, engine-filter-tokens.test.ts, seed-loader.test.ts) are as described. Gap: the declarations themselves have no pin — see F2.

6. ADR-0112 / vocabulary ledger

FIND_ONE_HOOK_RESULT_NOT_RECORD, UPDATE_HOOK_RESULT_NOT_WRITE_SHAPE, DELETE_HOOK_RESULT_NOT_WRITE_SHAPE are registered in ERROR_CODE_LEDGER (error-code-ledger.zod.ts) with owner/meaning comments, carry readonly status = 500 (what check:error-status-conformance derives from), and the generated contract.mdx / error-code-ledger.mdx are regenerated (+3). The registration footprint is byte-for-byte the precedent's: the six non-test files naming FIND_HOOK_RESULT_NOT_ARRAY on main are exactly the six naming the new codes on the head. ADR-0130 in this repo is the release-artifact co-ownership boundary and has no interplay with these codes; the runtime vocabulary these must be in is ADR-0112 D3/D4's ledger, and they are.

7. CI on head c5935b2445

38 check runs: failure 2 (Check Changeset, both workflow runs — same cause, F1), success 30, skipped 6 (Auto Label/Check PR Size duplicates, Packed-tarball smoke (opt-in) ×2, Console Pin Gate), in_progress 0. mergeable_state: unstable. Head is 17 commits behind origin/main (dd2184ae), merge-base 8ccf7a1d.

Findings

F1 — BLOCKING. Check Changeset is red on the level axis. Log, verbatim: ⛔ This PR declares clause-② YES and grades a package it grew patch. naming @objectstack/metadata: patch and @objectstack/metadata-protocol: patch. @objectstack/plugin-auth: patch is the same case and escapes only through the gate's packages/*/src/** blind spot the PR body itself cites (#16713). The PR body's "111 derived, 111 run, all exit 0" is not a reading of this axis: run locally, check-changeset-no-major has no $GITHUB_EVENT_PATH, reads no declaration, and reports NOT MEASURED with exit 0. Expectation: raise the three consumer entries to minor (the fixed group versions in lockstep, so the published version outcome is identical) — or, if the seat rules the declaration wrong for consumer repairs, have that ruled rather than tolerated in the gate; and correct the body's gate claim to say the level axis was NOT MEASURED locally.

F2 — The three declarations have no pin; only the guards do. Reverting findOne/update/delete to Promise<any> while keeping the guards reddens nothing: every census repair (if (!row), typeof x === 'number' ? … : …, result!.assignee) and the one new typed helper (writtenRow(result: Record<string, any> | number | null)) compiles identically against any. Ruling A's declaration half is therefore unenforced (ADR-0049). Expectation: a type-level pin under check:test-typecheck in packages/spec/src/contracts/data-engine.test.ts — e.g. // @ts-expect-error on an un-null-checked property read of findOne's result and on delete's result used as a record, and a number-limb narrowing that fails to compile if update widens back to any.

F3 — Changeset runtime FROM/TO is aggregated, not per door. The type FROM/TO is per verb, but the runtime change ("a host that installs after* handlers … now receives a refusal") is one sentence for three doors, and omits the second source the PR's own developerMessage names: an off-contract driver answer now trips the refusal too. Expectation: three FROM/TO lines (per door: FROM whatever the dispatch left, returned silently → TO 500 <CODE>), each naming both sources.

F4 — byIdUpdateRecord (metadata-protocol/src/protocol.ts) throws a bare Error with no ADR-0112 code on the number limb. Unreachable by construction today, so acceptable as an invariant assertion; note that if it ever fires at an HTTP door it demotes to a generic 500 with no branchable code.

F5 — Observation, no change owed. The update guard checks the batch hookContext after the per-row afterUpdate fan-out; per-row contexts are separate objects (buildPerRowAfterContexts), so a per-row handler's ctx.result reassignment never reaches the seam. That matches the ruling (the batch context is what the call returns) but the engine.ts:12117 comment "a per-row handler can reassign it" overstates it, and no pin covers the per-row path.

F6 — Reported gap is real; needs a card number before landing. ScopedContext.object(name): ObjectRepository (engine.ts:14728) returns the class, whose five verbs still declare Promise<any> (:14571–:14612), so the hook author's door ctx.api.object(x).findOne() is not narrowed. The PR reports it and the PM seat said it will file; no card is referenced yet on the PR or #16231. Expectation: the follow-up card numbers (this and the type-surface-only gate defect) appear on the PR before it leaves draft.

F7 — 17 commits behind main; mergeable_state: unstable. Bring the branch up to date after F1 so the gate re-reads on a current merge-base.

Seat boundaries: no approval/review action, no label, title, body or branch change, no merge, no file edited; throwaway review refs deleted.

---

Generated by Claude Code