fix(runtime): bind action-body ctx.api/ctx.engine to a real execution context (#3914)

[os-zhuang]

Fixes #3914.

The defect

An action body's ctx.api was never bound. buildSandboxApi walked its whole 3-way fallback — no actionCtx.api, and the raw ObjectQL engine has no .object() (that lives on ScopedContext, reachable only via engine.createContext(), which the action path never called) — and landed on a repo facade that proxied every call to the engine with no context. ctx.engine (buildActionEngineFacade) had the identical hole.

Context-less is not "trusted", it is identity-less, and identity-less is strictly worse than either coherent posture:

• plugin-sharing's canEdit short-circuits on !context.userId — there is no user to own anything;
• its bypass needs context.isSystem — which was never set.

So every owner-scoped write from an action body died FORBIDDEN: insufficient privileges to update <object> — as the built-in admin — while the [action-audit] line on the same request announced RLS-bypassing TRUSTED execution. Objects with a public sharing model, no owner field, or a bypass listing passed the gate early, which is why only some actions broke and the defect read as object-dependent flakiness.

The fix

Both dispatch paths — REST /actions/:object/:action and MCP run_action — now bind ctx.api to engine.createContext(...) and thread the same envelope through ctx.engine, matching what hook bodies already get from the engine's buildHookApi.

The envelope (buildActionExecutionContext) is the caller's ExecutionContext elevated with isSystem: true. Of the two coherent options the issue offered, this is the one that matches the documented model: elevation is the posture #2849 already documents and gates for at invoke time (capability gate + ai.exposed), so RLS-scoping instead would silently break bodies that legitimately act beyond the caller.

One refinement on the bare { isSystem: true } that hooks fall back to — the caller's fields are spread first, so writes stay:

• attributable — userId stamps created_by / updated_by;
• org-scoped — tenantId stamps the org column and drives driver-level tenant isolation;
• transactional — an open transaction handle is joined,

instead of the unattributable, org-less rows bare elevation would write.

The sandbox's last-resort repo facade is elevated from the same envelope via ctx.executionContext, so a host predating createContext is not left proxying context-less either. The [action-audit] wording now describes what the body actually gets ("system-elevated context") rather than the false "context-less engine".

Changes

File	Change
packages/runtime/src/action-execution.ts	New buildActionExecutionContext + buildActionApi; buildActionEngineFacade takes the caller envelope and threads context through every verb; MCP actionContext gains api + executionContext; audit line + stale security-model comments corrected
packages/runtime/src/domains/actions.ts	REST path drops its duplicated inline facade for the shared (context-carrying) one, gains api + executionContext, audit line corrected
packages/runtime/src/sandbox/body-runner.ts	buildSandboxApi prefers ql.createContext(ctx.executionContext); the last-resort repo facade threads that context through every call
packages/runtime/src/action-body-identity.test.ts	New — 15 regression tests
content/docs/ui/actions.mdx	The trusted-facade callout named only engine; now covers ctx.api and states the elevation posture

Verification

The regression tests use an engine stub that refuses a write carrying neither userId nor isSystem, the way the real sharing gate does. Reverting just the domain wiring reproduces the reported failure verbatim:

FAIL src/action-body-identity.test.ts > REST /actions dispatch binds ctx.api and ctx.engine
Error: FORBIDDEN: insufficient privileges to update crm_case

With the fix, full monorepo suite green — 132/132 turbo tasks, including runtime (735 tests), objectql (1163), and the dogfood suite (395 passed / 3 skipped). ESLint clean on the changed files.

Out of scope

• The HTTP-200-on-failure half ([17.0.0-rc.0] Global actions unreachable: registered under key 'global', REST fallback probes '*' — and handler failures return HTTP 200 {success:true,data:{success:false}} #3913) is untouched.
• No changeset — AGENTS.md exempts pure bug fixes.

---

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)
objectstack	Ignored		Jul 29, 2026 9:43am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/runtime.

18 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/api/client-sdk.mdx (via packages/runtime)
• content/docs/api/index.mdx (via @objectstack/runtime)
• content/docs/api/wire-format.mdx (via @objectstack/runtime)
• content/docs/automation/hook-bodies.mdx (via @objectstack/runtime)
• content/docs/concepts/north-star.mdx (via packages/runtime)
• content/docs/data-modeling/drivers.mdx (via @objectstack/runtime)
• content/docs/deployment/index.mdx (via @objectstack/runtime)
• content/docs/deployment/production-readiness.mdx (via @objectstack/runtime)
• content/docs/deployment/single-project-mode.mdx (via @objectstack/runtime)
• content/docs/deployment/vercel.mdx (via @objectstack/runtime)
• content/docs/getting-started/your-first-project.mdx (via @objectstack/runtime)
• content/docs/permissions/authentication.mdx (via @objectstack/runtime)
• content/docs/permissions/authorization.mdx (via packages/runtime)
• content/docs/plugins/packages.mdx (via @objectstack/runtime)
• content/docs/protocol/kernel/http-protocol.mdx (via @objectstack/runtime)
• content/docs/protocol/kernel/index.mdx (via @objectstack/runtime)
• content/docs/protocol/kernel/lifecycle.mdx (via @objectstack/runtime)
• content/docs/releases/implementation-status.mdx (via @objectstack/runtime)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.