test: run action and hook bodies through the real QuickJS sandbox (#575 A1)

[yinlianghui]

Description

Issue #575 item A1 only — the action-sandbox test gap.

The action side had no sandbox harness. test/global-actions.test.ts ran each body.source through new Function, which proves what a body computes and is structurally blind to everything the runtime imposes on it: no module scope, a JSON-only boundary, a capability gate, and a ctx.api built by the engine rather than by the author. So the one constraint this repo relies on by name — the shared factory in src/objects/_line-item-price-fill.ts is safe only while its handler body never reads a factory parameter — lived in a comment, with nothing anywhere failing if it were violated.

test/helpers/action-sandbox.ts runs nothing of its own: it hands bodies to the same QuickJSScriptRunner + actionBodyRunnerFactory / hookBodyRunnerFactory the runtime wires at boot, lowered by the same extractHookBody pass the CLI build uses. The only stand-in is the engine underneath — an ObjectQL-shaped recorder, deliberately without .object() so the runtime builds the repo facade itself and a body meets the real update(data, options) signature. Its two hand-written rules are pinned against a real ObjectQL on the in-memory driver, the way test/hook-query-predicate.test.ts pins the read predicate.

Verified against main @ 3ed27b26 before starting: the gap still existed.

Type of Change

• New tests / test infrastructure
• Documentation update (the constraint comment in _line-item-price-fill.ts now names its guard)

Related Issues

Related to #575 (item A1 only — B-group items untouched, A2–A4 untouched)

Changes Made

• test/helpers/action-sandbox.ts (new) — real QuickJS harness: runActionBody builds the exact actionCtx both dispatch paths in @objectstack/runtime build (params: { ...params, recordId, objectName }, and no object key, so ctx.object is undefined in the sandbox); runHookBody executes a hook's shipped lowered body rather than its handler closure; extractSandboxBody is the CLI build's own lowering pass; makeSandboxEngine is the recording engine.
• test/action-sandbox.test.ts (new, 52 tests) —
  • the stub engine's update contract asserted against a real ObjectQL on the in-memory driver, then the same two calls made through the runtime's facade inside QuickJS;
  • the sandbox boundary: an undeclared capability is denied, a body has no module scope, the dispatcher's params arrive as input;
  • all 7 script action bodies executed, with behavioural assertions on clone_opportunity, mark_primary, create_campaign and send_email;
  • the price-fill constraint as an executable guard on both line-item objects, with a negative control (a factory whose handler reads a factory parameter is rejected, naming the identifier) and a consequence control (such a body ReferenceErrors in the VM);
  • the generalisation the build only mentions in passing: all 24 callables still lower to metadata-only bodies.
• test/global-actions.test.ts — same 18 assertions, now executed by the real sandbox instead of new Function.
• src/objects/_line-item-price-fill.ts — the sandbox note points at its guard, and records why a test has to do this: when extraction fails the build does not — it silently keeps the handler bundled and the hook stops being deployable as pure metadata.
• changeset added.

Finding recorded, not fixed

mass_update_stage calls ctx.api.object(...).update(id, { stage }), but ctx.api is the engine repo facade, whose update takes (data, options) — the id lands in the data slot and the engine rejects the write with Update requires an ID or options.multi=true on every invocation. Nothing before this harness could say so: the metadata is valid, the body parses, and #508 already documents the action as having no live invocation path. Fixing a shipped action is outside A1, so test/action-sandbox.test.ts asserts the current behaviour under a test name that says what it is; whoever revives the action will land on that assertion.

Same shape, larger and out of scope here: _hook-api.ts documents update: (id, doc) and nine hooks call it that way, while the kernel's ScopedContext / repo facade both take (data, options). Worth its own issue.

Testing

• pnpm verify green end to end (validate → typecheck → lint → hygiene → build → test): 532 passed, 2 skipped, 26 files
• Coverage thresholds still met (stmts 95.21 / branch 80.31 / funcs 95.12 / lines 99.59)
• New tests added, including a negative control that fails when the guard is violated
• No new dependencies — quickjs-emscripten arrives via @objectstack/runtime, already a direct dependency; lockfile untouched

Checklist

• I have added a changeset (.changeset/real-quickjs-action-sandbox-harness.md)
• New guards live in a new test file, not appended to test/metadata-references.test.ts
• Commit message uses Refs, not Closes — this PR is one item of Follow-up to #514: remaining behaviour fixes, conventions, and the action-sandbox test gap #575
• Self-reviewed; commented the non-obvious parts (why the stub has no .object(), why extraction failure is silent at build time)

Additional Notes

Cost: ~50 ms per sandboxed run (a fresh WASM context each time, as the runtime does). The suite went from 3.6 s to 9.3 s wall clock overall.

Convention 5 from the issue — re-run pnpm verify on main after merge — still applies.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hotcrm	Ignored		Jul 31, 2026 2:48pm