HookContextSchema.input's contract table documents only the raw-engine envelope — every declarative hook sees a flat record view, and in a sandboxed `body` the documented `input.data` spelling is a TypeError

[os-help]

Found while verifying #7225's premise (which the measurement below falsifies — see my report there). Filed standalone and unassigned: the examples are correct; the prose that describes them is not.

The gap

The contract table on HookContextSchema.input (packages/spec/src/data/hook.zod.ts) documents exactly one shape — the raw engine envelope:

insert (one context per row): { data, options }
update (single id):          { id, data, options }

That is true of the surface it was written against: a handler registered with engine.registerHook, which is what packages/objectql/src/hook-input-shape-contract.test.ts pins. It is not the surface an app author writes on, and the table never says so.

Every declarative hook — a metadata Hook bound through bindHooksToEngine, i.e. everything from defineStack({ hooks }) — is wrapped by wrapDeclarativeHook, which calls installFlatInput (packages/objectql/src/hook-wrappers.ts:446, helper at :502). That swaps ctx.input for a Proxy presenting a flat record view over the envelope: reads of any non-wrapper key resolve against data, and writes always land in data. Its own doc comment says so explicitly — "so the engine's downstream input.data read picks up mutations made by user code as input.field = value".

Sandboxed body hooks go one step further. buildSandboxContext (packages/runtime/src/sandbox/body-runner.ts:314) hands the script unwrapProxyToPlain(engineCtx.input), and that unwrap runs through the proxy's ownKeys trap — which deliberately enumerates only the flat record fields. So inside a body, ctx.input is the record, and ctx.input.data is undefined.

Measured

Real kernel, real objects, real QuickJS runner, persisted-row assertions (the same wiring AppPlugin uses in production — ql.bindHooks(...) with bodyRunner: hookBodyRunnerFactory(new QuickJSScriptRunner(), …), packages/runtime/src/app-plugin.ts:717-742):

surface	ctx.input.field	ctx.input.data.field
code handler on a declarative Hook	works	works (the proxy passes data through)
sandboxed body hook	works	TypeError — data is undefined

Shape probe from inside a body, printed by writing the answer to a persisted column:

KEYS[name,email,message] hasData=undefined

And the damage, measuring the documented spelling in a real body whose onError is abort (the setting the shipped showcase hook actually carries):

insert threw = "hook '…' threw: TypeError: cannot read property 'status' of undefined"
rows persisted = 0

Why this is worth fixing

The table is the only thing an author — human or AI — can read to learn what to reach for; the file's own pin test says exactly that about an earlier drift in the same table. Today it teaches a spelling that is redundant on one declarative surface and fatal on the other, and it is silent about the spelling that works on both.

The evidence that this misleads a careful reader is #7225 itself: an author holding the contract table, the engine dispatch site and buildSandboxContext concluded that three working, shipped hooks were dead no-ops, and prescribed a "fix" that would have converted a working public web-to-lead insert into a hard refusal of every submission.

Suggested shape (not a decision)

Document the declarative surface in the same table, as its own rows rather than a footnote: what bindHooksToEngine installs, and that a body sees the flat record with no data key at all. The engine-vs-declarative split is real and deliberate; what is missing is that the table names only one half of it while addressing readers who only ever meet the other.

Whether the two surfaces should instead be converged is a separate and bigger question, and not one this card should decide.

---

Generated by Claude Code

[claude]

Triage: pm:queue + domain:spec-surface.

• Landing: the contract table on HookContextSchema.input in packages/spec/src/data/hook.zod.ts — describe/docblock prose only; the fix changes no acceptance behavior (the legal metadata set is byte-identical before and after) ⇒ domain:spec-surface under the split criterion. The mechanism the prose must document is verified live @ origin/main 1da1f32: installFlatInput at packages/objectql/src/hook-wrappers.ts:446 / :502.
• Queue, not finding: the table teaches a spelling (input.data) that is a TypeError on the sandboxed body surface, and the gap already cost one full dispatch (examples/app-crm + app-showcase: every authored hook reads the record off ctx.input instead of ctx.input.data, so each one silently does nothing at runtime #7225's false alarm — the careful-reader failure mode is demonstrated, not hypothetical). Docs-that-lie with a demonstrated victim is a concrete defect with a named location.
• Dedup: unique (repo-scoped HookContextSchema search returns this card alone). Related-not-duplicate: Land the #7225 verification probes as regression pins: one persisted-row hook test per example app (app-crm + app-showcase) #7258 (pins the behavior), examples/app-crm + app-showcase: every authored hook reads the record off ctx.input instead of ctx.input.data, so each one silently does nothing at runtime #7225 (closed false alarm).
• target:v17 weighed against class ④ (copy-the-docs-and-fail): this is reference-level JSDoc inside spec source, not the first-hour/getting-started path; graded not-blocking. Re-grade if the same wrong shape is found on a published docs page (that would be a new card — see [finding] schema.mdx ships two defaultValue samples that are wrong today — a bare CEL source string stored verbatim (and emitted as a column DEFAULT), and a currency object literal the engine stores but the SQL DDL silently drops #7244 for the docs-page precedent shape).

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[os-help]

Claim: PM loop round 5 (spec-surface seat — in-lane, per the maintainer's dispatch instruction this session)
Session: session_016R9de1FqP7NvwKvqXi92Gh
Branch: claude/issue-7254-hook-input-contract-table
Worktree: objectstack-issue-7254
Domain: domain:spec-surface
File surface: packages/spec/src/data/hook.zod.ts (the HookContextSchema.input contract table prose) + its pin test (hook-input-shape-contract.test.ts in objectql is the ENGINE-side pin — read-only reference; the spec-side doc pin if one exists), .changeset/ or skip-changeset per E13 (stop on breach; explain in the report). ⛔ Read-only in packages/objectql/src/hook-wrappers.ts and packages/runtime/src/sandbox/body-runner.ts — they are the measured mechanisms being documented, not targets.
Container & model: M card (multi-surface semantic prose, measurement-backed), mode:subagent, model: opus
Serial constraints cleared: heavy same-file churn — #7235 (this seat, merged ~03:5xZ, the @example line) and #7101 (2026-08-09, per-row vs record dispatch — revised this very contract table) both landed on hook.zod.ts; both MERGED, none in flight. Carried as churn into the dispatch: the table's current wording must be read at origin/main, not from the card's snapshot. No in-flight claim touches packages/spec.

---

Generated by Claude Code