Uh oh!
There was an error while loading. Please reload this page.
docs(skills): document the sandboxed hook body ctx/capability contract - #3314
Merged
Conversation
The objectstack-data hooks docs covered events + registration but never the
sandbox `body` form — the metadata-native shape a metadata-only runtime
actually executes. A third-party evaluator on 15.1.x got hooks working only by
reverse-engineering `@objectstack/runtime`'s dist (memory:
project_thirdparty_eval_15_1_findings).
Add a "Sandboxed Hook Bodies (`body`)" section to references/data-hooks.md,
verified against runtime source AND a live `create-objectstack@15.1.1` repro:
- `body` vs the deprecated inline `handler`; the `{ language, source,
capabilities }` shape; `source` is the function body wrapped as
`(async (ctx) => { … })(ctx)`.
- the sandbox `ctx` (input/previous/result/user/session/event/object/api/log/
crypto); `!ctx.previous` distinguishes create.
- `ctx.api.object(n)` repo — find/findOne/count/insert/update({id,...})/upsert/
delete; query key is `where` (object + $-operators), NOT `filter:[['id','=',x]]`.
- the six legal `HookBodyCapability` tokens + call-time gating/throw behaviour.
- sandbox globals (verified available vs absent) and build-rejected identifiers.
- gotcha: afterUpdate `ctx.result` is a PARTIAL patch → re-query for lookup FKs.
- gotcha: cross-object writes obey the TARGET's sharing model (public_read →
`FORBIDDEN`, admin not exempt).
- a copy-paste afterUpdate example (os:check-gated) + `[BodyRunner]` troubleshooting,
including that `ctx.log` emission is best-effort.
Also: a quick-ref `body` block in rules/hooks.md, a SKILL.md pointer, fix the
stale "14 events" → 8, and switch the handler-form Cross-Object API example to
the canonical `where`.
Verified end-to-end: scaffolded `create-objectstack@15.1.1`, wrote the doc's
hook verbatim, drove it over REST — hook fired, the cross-object update landed
(`position.status = filled`), zero `[BodyRunner] threw`. Skill gates
(skill-docs / skill-refs / skill-examples / doc-authoring) all green.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>The latest updates on your projects. Learn more about Vercel for GitHub.
|
Uh oh!
There was an error while loading. Please reload this page.
This was referenced Aug 17, 2026
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
The
objectstack-datahooks docs explained lifecycle events and registration, but never the sandboxedbodyform — the metadata-native shape ({ language, source, capabilities }) that a metadata-only runtime actually executes and that ships inside every build artifact. A third-party evaluator on 15.1.x got hooks working only by reverse-engineering@objectstack/runtime's dist (memoryproject_thirdparty_eval_15_1_findings). This fills that gap.Adds a "Sandboxed Hook Bodies (
body)" section toreferences/data-hooks.mdVerified against runtime source and a live
create-objectstack@15.1.1repro:bodyvs the deprecated inlinehandler— where each runs (QuickJS VM vs full Node), how each ships, thatbodywins when both are present.ctx—input/previous(undefinedon insert →!ctx.previous= create) /result/user/session/event/object/api/log/crypto, marshalled as a JSON snapshot.ctx.api.object(n)repo —find/findOne/count/insert/update({ id, ...fields })/upsert/delete. Query key iswhere(object +$-operators) — notfilter: [['id','=',x]](that array-of-triples value matches nothing).HookBodyCapabilitytokens (api.read,api.write,api.transaction,crypto.uuid,crypto.hash,log) + call-time gating/throw behaviour.Date/Math/JSON/Promise/Map/…) vs absent (console/fetch/setTimeout/URL/…), and build-rejected identifiers (import/process/eval/free identifiers).ctx.resultis a partial patch → re-query for a lookup FK it doesn't carry.public_read→FORBIDDEN: insufficient privileges, admin not exempt).<!-- os:check -->tsc gate) +[BodyRunner]troubleshooting (incl.ctx.logemission is best-effort).Plus: a quick-ref
bodyblock inrules/hooks.md, aSKILL.mdpointer, a stale "14 events" → 8 fix, and the handler-form Cross-Object API example switched to canonicalwhere.Correction vs the source brief
The brief specified
findOne({ filter: [['id','=',id]] }). Source + the #1867 real-engine/real-sandbox integration test + the objectstack-query skill all show the canonical key iswherewith an object value;filteris only a tolerated object-valued alias, and the triple-array value isn't supported. The docs teachwhereaccordingly.Verification
npx create-objectstack@latest(15.1.1), addedcandidate/positionobjects + the doc's hook verbatim,os dev, drove it over REST → hook fired, re-query + cross-objectupdatelanded (position.status = filled), zero[BodyRunner] threw. AbeforeInsertprobe confirmed the globals table.check:skill-docs,check:skill-refs,check:skill-examples(new example type-checks against built@objectstack/spec),check:doc-authoring.🤖 Generated with Claude Code