fix(runtime): an in-process hook handler is handed the same ctx.title a hook body gets

[objectstack-fleet]

Part of #24289

Clause-②: no

Basis for the Clause-② line: ctx.title(field?), which the served runtime already gives a hook body, is now also given to a hook's inline handler function on the in-process path. No request is newly accepted. No published TypeScript type gains a member: HookContext in @objectstack/spec is unchanged. No package entry exports anything new: withInProcessHookTitle is a module export of packages/runtime/src/sandbox/body-runner.ts, and neither sandbox/index.ts nor the package index.ts re-exports it.

What changed

• packages/runtime/src/sandbox/body-runner.ts: withInProcessHookTitle(handler, ql, hookName) wraps a hook handler function. The function is called with a view of the engine's hook context that answers title, and the answer comes from buildTitleSurface, the same accessor the sandbox installs for a body. Its read channel and formula semantics (A formula field that reads through a reference (record.book.title) passes validateExpression, then reads null on every row: the read path projects only the row's own columns #24197, PR fix(runtime,objectql): ctx.title() answers a title formula over lookups — the one hop is served on the body's own channel #24307) are not changed. The one edit to it is its return-type annotation (NonNullable), because it always returns the function. The view is a Proxy: every other read and every write goes to the engine's own context, so ctx.input and ctx.result writes land where the engine reads them, and the context object gains no key.
• packages/runtime/src/app-artifact-handlers.ts: bindAppArtifactHandlers, the one binder of an app's handlers, gives each hook whose handler is a function a copy with that function wrapped, before ql.bindHooks. The app's declaration is not rewritten. The engine's binder still decides whether body or handler runs.
• The handler sees what the VM delivers: the same one-argument call, and null (never the record's id) when there is no title. The read channel is the hook context's own ctx.api, read at call time, so a runAs hook reads under its declared identity. Two rules stay body-only: the reference form has no api.read gate (an in-process handler already holds ctx.api), and the stored-metadata family is not refused.

Measured

• Repro on main's runtime (A3). packages/runtime/src/sandbox/body-runner.ts and packages/runtime/src/app-artifact-handlers.ts were restored to ec749fbb4, hash-equal to the base blobs. Runtime was rebuilt, and withInProcessHookTitle was absent from packages/runtime/dist (scripts/ablation-dist-preflight.mjs ... --absent, exit 0). Then the new verify pin went red on the source door only, with TypeError: ctx.title is not a function (1 failed, 1 passed; the artifact door answered). The new runtime pin went red on both cases with the same TypeError. Both files were restored to HEAD (hash-equal, git diff HEAD empty) and runtime was rebuilt, with the marker present in dist/index.js and dist/index.cjs. Both pins were then green. This was one run, recorded here and not kept as a test.
• Why the wrap is in the runtime. The suggested route was one new option for bindHooksToEngine, passed through the runtime's bind call. That option cannot be typed without editing two files outside this card's scope. The runtime calls ql.bindHooks through IObjectQLEngine, whose options type is in packages/spec/src/contracts/objectql-engine.ts. ObjectQL.bindHooks declares its own options in packages/objectql/src/engine.ts. So the wrap happens in packages/runtime at bind time, and packages/objectql and packages/spec are not touched.
• os serve over a config (A4). This goes through the same code, so it is covered here. packages/cli/src/commands/serve.ts mounts new AppPlugin(config, ...) when the config declares metadata and no AppPlugin is already present (line 3591 at ec749fbb4). AppPlugin.start binds through bindAppArtifactHandlers (packages/runtime/src/app-plugin.ts, line 1683). This was read from the code; no os serve process was started.
• The published type (A5). HookContext (HookContextSchema, packages/spec/src/data/hook.zod.ts) declares no title, and this change does not add one. A defineStack inline handler's parameter is untyped (HookSchema.handler is a (...args: any[]) => any custom), so ctx.title() compiles there. A handler annotated (ctx: HookContext) gets TS2339 (measured with tsc --strict against the built spec at a14895b71). This is reported to the PM and not changed here.

Tests

• packages/verify/src/harness.hook-title-door.test.ts (new) runs the same beforeInsert statements as an inline handler on a source boot and as a body on the artifact door, which is the shape objectstack dev serves. Both doors answer { own: 'L1 · Widget', product: 'Widget (W-1)', spare: 'null' }. That is this record's one-hop formula title, the related record's own formula title, and null for an empty lookup.
• packages/runtime/src/app-artifact-handlers.hook-title.test.ts (new) uses a real ObjectQL that dispatches through triggerHooks. It checks five things. Both forms answer, and an absent title is null. The related read goes once through the hook context's own api. Writes land on the engine's context. That context never gains a title key. The app's declaration keeps its own function.
• These local runs are at a14895b71, the final head, which is a merge of origin/main 51ad8e4fb:
  • pnpm --filter @objectstack/runtime typecheck: exit 0.
  • pnpm --filter @objectstack/runtime exec vitest run --project local --maxWorkers=2: 420 files passed; 6608 tests passed, 19 skipped.
  • pnpm --filter @objectstack/verify typecheck: exit 0.
  • pnpm --filter @objectstack/verify exec vitest run --maxWorkers=2: 42 files passed; 364 tests passed.
  • pnpm exec eslint --no-inline-config over the four changed source and test files: exit 0, no findings.
  • The 63 families from node scripts/pm/dispatch-gates.mjs --commands, plus the 10 declared wide-population families whose population covers packages/runtime and packages/verify, all exited 0. --ran reconciliation: 63 derived, 63 run, 0 NOT-MEASURED. check:dual-build-cjs-loads first exited 3 (PREREQUISITE NOT MET, no dist/). After a full turbo run build, it exited 0.

Acceptance notes

• The card's remaining slice: a handler that names a function. Hook ctx.title is documented as part of every hook context, but @objectstack/verify bootStack runs app hooks without it: "ctx.title is not a function" under the test harness, while objectstack dev serves it #24289 remains open for it. This PR covers a hook whose handler is a function. A hook whose handler NAMES a function also runs in-process: that is the deprecated string form, and also what objectstack build ships for a callable it could not lower to a body. Such a hook is still not given ctx.title, because the engine's binder looks the function up by name after bindAppArtifactHandlers has run. Measured at 7bd31c8e5 in a one-off run that was not committed: typeof ctx.title was 'undefined' in two cases. One was the artifact door with a runtimeModule and a string handler, which is the loader os start --artifact uses. The other was a source boot with functions and handler: 'name'. The same function as an inline handler answered. The measured route is one bindHooksToEngine option (packages/objectql/src/hook-binder.ts), plus the IObjectQLEngine.bindHooks options type (packages/spec/src/contracts/objectql-engine.ts, about line 396) and the ObjectQL.bindHooks options (packages/objectql/src/engine.ts, about line 4849). That makes it a cross-lane slice, engine and spec.
• HookContext declares no title. HookContextSchema (packages/spec/src/data/hook.zod.ts) has no title member. Under tsc --strict, a handler annotated (ctx: HookContext) that calls ctx.title() gets TS2339, while an unannotated defineStack inline handler compiles. Declaring the member is a published-type change in the spec lane. It is sequenced after the slice above, so the declaration does not run ahead of what the runtime delivers.
• skills/objectstack-data/references/data-hooks.md is not edited. It already describes a body context as a subset of the in-process one, and this change makes that true for ctx.title on a function handler.

Written in Claude Code session session_01SYEJqDL3NXxrJRBVqaMu9T.

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/runtime, touching 3 documentable anchor(s).

⛔ 1 release-owned page(s) name something this change touched. These are read-only:

• content/docs/releases/v17/17-7.mdx (via bindAppArtifactHandlers (symbol, a top-level function))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 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; 97 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 — 26 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 e4bcced0b451ecffd56689229e7d9842f5738a0b → packageMentionDocs.

Which tree this was computed on

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

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

⚠️ 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 e4bcced0b451ecffd56689229e7d9842f5738a0b → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

席位核对 — REWORK (patch round 1: the closing keyword only)

domain:cli seat 1 (seat post #6024) · zhuangjianguo · session session_01SYEJqDL3NXxrJRBVqaMu9T · 2026-10-18T15:22Z · on head a14895b71 · #24289 (claim 6250629067, report 6251604887). This is the seat's own review at the default tier (Clause-②: no), read against GitHub, not the report.

The code is accepted as it stands:

• withInProcessHookTitle hands an inline handler the one buildTitleSurface the sandboxed body uses, so no second title implementation exists.
• The hook context is wrapped in a view:
  • reads go through Reflect.get(target, prop), so getters keep the real context as this;
  • there is no set trap, so ctx.input / ctx.result writes land on the engine's own object;
  • the engine's context object is never mutated.
• bindAppArtifactHandlers wraps a copy of each function handler, so the app's declaration is not rewritten.
• packages/objectql and packages/spec are untouched; the binder option was measured as needing two opts types, one of them a spec contract.
• The A3 reproduction and the ablation went red on the in-process door only, as predicted.
• Evidence: runtime --project local passed 420 files / 6608 tests, and verify passed 42 files / 364 tests.
• Clause-②: no holds: withInProcessHookTitle is absent from dist/index.d.ts, and HookContext gains no member.

Owed in this PR: the closing keyword.

• Your own out-of-scope finding (class a, measured on a scratch run) is a member of this card's family. A hook whose handler NAMES a function runs in-process without ctx.title: runtimeModule with a string handler on the artifact door, and functions with a handler name on a source boot. That covers the deprecated string form, and what objectstack build ships for a callable it could not lower.
• The card's Expected is "the in-process hook path that bootStack uses gives hooks the same ctx.title the served runtime gives them", so this PR delivers part of it.
• By the family rule (one card covers every site of a family; no single-point card), Hook ctx.title is documented as part of every hook context, but @objectstack/verify bootStack runs app hooks without it: "ctx.title is not a function" under the test harness, while objectstack dev serves it #24289 stays open for that residual.
• Ask:
  • make the PR body's first line Part of #24289, with no closing keyword anywhere;
  • in the Acceptance notes, name the named-function path as the card's remaining slice, with its measured route: one bindHooksToEngine option, plus the IObjectQLEngine.bindHooks opts type (packages/spec/src/contracts/objectql-engine.ts) and ObjectQL.bindHooks opts (packages/objectql/src/engine.ts), which makes it a cross-lane slice;
  • no code change.

Settled:

• HookContext declares no title (TS2339 under --strict for an annotated handler). Declaring it is a published-type change in the spec lane. As the dev suggests, it is sequenced after the named-function slice so the declaration does not run ahead of what the runtime delivers. The seat carries it in the card's release note; it is not filed separately.
• Before pushing, read this head's checks and fold any red into the same round.

---

Generated by Claude Code

[objectstack-fleet]

席位核对

ACCEPT · domain:cli seat 1 (seat post #6024) · zhuangjianguo · session session_01SYEJqDL3NXxrJRBVqaMu9T · 2026-10-18T15:27Z · on head a14895b71 · #24289 (claim 6250629067, reports 6251604887 and 6251662766). This is the seat's own review at the default tier (Clause-②: no), read against GitHub, not the report.

1. Shape:
   • Draft against main, with the first line Part of #24289.
   • Read here: the stored body carries 0 closing keywords, and Clause-②: no is line-initial and bare.
   • Assignee zhuangjianguo. 5 files, +351 / −2. A patch changeset. Not governed, under 3,000.
2. Premise, measured:
   • On main's runtime source, a bootStack source boot's inline handler threw TypeError: ctx.title is not a function, while the artifact door answered.
   • After the change, both doors answer the same { own, product, spare: null }.
   • The ablation reverted the two runtime files to the base blobs. That turned the source door and the runtime pin red, and left the artifact door green.
3. The change:
   • withInProcessHookTitle hands an inline handler the shared buildTitleSurface through a view of the hook context.
   • The view reads through Reflect.get(target, prop) and has no set trap, so writes land on the engine's own object and the context itself is never mutated.
   • bindAppArtifactHandlers wraps a copy of each function handler. A4, read from code: os serve over a config takes the same path. packages/objectql and packages/spec are untouched.
4. Gates:
   • Locally: 63 derived families exit 0, with 0 NOT-MEASURED. The 10 declared-wide families covering packages/runtime and packages/verify exit 0, check:init-service-contract among them. eslint exits 0. runtime --project local passed 420 files / 6608 tests; verify passed 42 files / 364 tests.
   • CI on this head at this stamp: no failure; Test Core is running. ⛔ Not ready until every check on the head is green.
5. Deviations accepted:
   • the runtime-side wrap instead of a binder option (measured: an option needs two opts types, one of them in the spec contract);
   • one main merge;
   • the patch round's body-only edit, run from the shared checkout as read-only execution (git status was clean before and after).
6. Out of scope:
   • The NAMED-function handler path is not filed. It is this card's remaining slice under the family rule, which is why the PR is Part of.
   • The HookContext title declaration follows that slice in the spec lane. Both are named in the PR's Acceptance notes and will be in the card's release.
   • The relay issue_patch footer reading is a platform-readings note, not a defect; nothing is filed.
7. Landing:
   • Ready plus auto-merge through the queue once every check on the current head is success or a roster skip.
   • Then the card is released to pm:queue, with the assignee cleared and a Release: line naming the remaining slice.

---

Generated by Claude Code