fix(cli): refuse to lower hook bodies that reference globals the sandbox does not provide (#14301)

.changeset/hook-body-sandbox-globals-allowlist.md

@@ -0,0 +1,64 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): stop lowering hook/action bodies that reference globals the sandbox does not provide (#14301)
+
+`detect-free-identifiers`' ambient allowlist was ONE generous list, documented as
+"assume the runtime has it". The runtime a lowered body actually runs in is the
+QuickJS sandbox, not the Node process that runs `objectstack build` — and the
+list named `Intl` beside `JSON`, under the comment "Web-ish that the sandbox /
+Node commonly provide". So a handler calling `Intl.DateTimeFormat` had no free
+identifier at all: `extractHookBody` lowered it into `body.source`, the #13651
+lint rule had nothing to report (it fires only on a *refused* lowering),
+`validate` / `typecheck` / `test` / `build` were all green because the
+in-process test runs the RAW function in Node where `Intl` exists — and
+production threw `ReferenceError: Intl is not defined`. Under the
+`onError: 'abort'` a validation-shaped hook must declare, that refuses every
+write to the object.
+
+The allowlist is now two sets, and membership is **measured**, never recalled: a
+`typeof X`/`'X' in globalThis` probe is evaluated inside the same
+`QuickJSScriptRunner` the runtime evaluates a body in, and
+`sandbox-globals-probe.test.ts` fails unless each set is exactly the probe's
+present/absent partition.
+
+- **`SANDBOX_GLOBALS` (53, measured present)** — the ECMAScript surface:
+ `Math` `JSON` `Date` `Object` `Array` `String` `Number` `Boolean` `RegExp`
+ `Map` `Set` `WeakMap` `WeakSet` `Promise` `Symbol` `BigInt` `Function`
+ `Reflect` `Proxy`, the typed-array/buffer family, the eight error
+ constructors, `parseInt` `parseFloat` `isNaN` `isFinite` and the four URI
+ functions, plus `undefined` `NaN` `Infinity` `globalThis`.
+- **`NODE_ONLY_GLOBALS` (15, measured absent)** — `Intl`, `structuredClone`,
+ `queueMicrotask`, `atob`, `btoa`, `setTimeout`, `clearTimeout`,
+ `setInterval`, `clearInterval`, `URL`, `URLSearchParams`, `TextEncoder`,
+ `TextDecoder`, `console`, `arguments`.
+
+A free reference to one of the 15 is now a lowering refusal whose reason names
+the identifier and the remedy — a string handler ref (`functions:` map plus
+`handler: 'fn_name'`) or a validation rule, and for `console` specifically the
+capability-gated `ctx.log`. It travels the SAME path #1876 already used: the
+refusal is `kind: 'free-identifiers'` with the host-only half carried
+separately as `nodeOnlyIdentifiers`, `lowerCallables` catches it and ships the
+callable through the `.mjs` bundle (where it runs in-process in Node and
+works), `os build` still exits 0 with a warning, and `os lint` reports it under
+`hook-body/not-lowerable` as an `error` — the ACCIDENTAL class, because `Intl`
+is a standard global in every browser and in Node and writing it is not the
+recognisable "I am reaching for the host" act that `fetch(` and `process.` are.
+The remedy sentence `os lint` prints is chosen from the refusal's own
+classification: "inline the value" is impossible for a host global, and
+printing it anyway would send an author after a second broken shape.
+
+⛔ Not changed here: whether `os build` fails on the lowering class (#13838),
+and what the sandbox provides (giving it `Intl` would be a capability
+expansion). Nothing under `packages/runtime/**` is touched — the probe reads
+that sandbox, it does not change it.
+
+**Why `patch`.** No published accept-set moves: the metadata a valid app may
+declare is identical, `HookBodySchema` is untouched, and no key is added,
+removed or re-shaped. What narrows is which handlers the build LOWERS, and for
+every handler affected the previous outcome was a body that could not run. An
+app hitting this gains a warning and a working bundled closure in place of a
+production `ReferenceError`; the deployment shape it loses was never one it had
+in working order. Measured corpus: zero in-repo example or template handlers
+reference any of the 15.

packages/cli/src/lint/hook-body-lowering.test.ts

@@ -42,6 +42,19 @@ const forbiddenTokenHook = {
  },
 };
 
+// [#14301] A global the NODE HOST provides and the sandbox does not. Reads as
+// self-contained — `Intl` is standard in every browser and in Node — which is
+// precisely why it is the ACCIDENTAL class and not the structural one.
+const nodeOnlyGlobalHook = {
+ name: 'stamp_due_label',
+ object: 'task',
+ events: ['beforeInsert'],
+ handler: (ctx: any) => {
+ const f = new Intl.DateTimeFormat('en-US', { timeZone: 'UTC' });
+ ctx.input.due_label = f.format(new Date(ctx.input.due_at));
+ },
+};
+
 const selfContainedHook = {
  name: 'normalize_name',
  object: 'account',
@@ -91,6 +104,41 @@ describe('checkHookBodyLowering', () => {
  expect(issues[0].message).toContain('deployment shape');
  });
 
+ describe('a host global the sandbox lacks is the ACCIDENTAL class (#14301)', () => {
+ it('reports it as an ERROR under the not-lowerable rule', () => {
+ const issues = checkHookBodyLowering({ hooks: [nodeOnlyGlobalHook] });
+
+ expect(issues).toHaveLength(1);
+ expect(issues[0].severity).toBe('error');
+ expect(issues[0].rule).toBe(NOT_LOWERABLE_RULE);
+ expect(issues[0].path).toBe('hooks[0].handler');
+ expect(issues[0].message).toContain("hook 'stamp_due_label'");
+ expect(issues[0].message).toContain('Intl');
+ expect(issues[0].message).toContain('deployment shape');
+ });
+
+ it('prints the remedy that is POSSIBLE, not the inline one', () => {
+ // The wrong-remedy failure is worse than none: there is nothing to inline
+ // `Intl` from, so an author (or a code-writing model) told to inline it
+ // lands on a second broken shape. The remedy sentence is chosen from the
+ // refusal's own `nodeOnlyIdentifiers`, never re-derived here.
+ const [issue] = checkHookBodyLowering({ hooks: [nodeOnlyGlobalHook] });
+ expect(issue.message).toContain('provided by the Node host');
+ expect(issue.message).toContain('cannot be inlined');
+ expect(issue.message).toContain('string handler ref');
+ expect(issue.message).toContain('validation rule');
+ expect(issue.message).not.toContain('Inline the value(s) into the handler');
+ });
+
+ it('leaves the module-scope remedy exactly as it was', () => {
+ // The reverse leg: the #13651 sentence must not have been rewritten for
+ // every author by a branch added for one new sub-case.
+ const [issue] = checkHookBodyLowering({ hooks: [freeIdentifierHook] });
+ expect(issue.message).toContain('Inline the value(s) into the handler, or reach them through `ctx`.');
+ expect(issue.message).not.toContain('provided by the Node host');
+ });
+ });
+
  it('keeps the STRUCTURAL refusal a warning — the bundle is its designed answer', () => {
  const issues = checkHookBodyLowering({ hooks: [forbiddenTokenHook] });
 

packages/cli/src/lint/hook-body-lowering.ts

@@ -38,13 +38,22 @@
  * Today both arrive through one catch, so they share one fate. They are not
  * the same event, and the refusal kind already tells them apart:
  *
- * `free-identifiers` ACCIDENTAL. The handler IS expressible as a metadata
- * body; it merely names a module-scope const/helper/
- * import. The author wrote something that reads
+ * `free-identifiers` ACCIDENTAL. The author wrote something that reads
  * self-contained, and the platform quietly re-shaped the
  * deployment behind them — its own message even says "no
  * behavior change", which is true of behaviour and false
- * of shape. Remedy is local: inline the value. => `error`.
+ * of shape. => `error`, for both sub-cases:
+ * · a module-scope const/helper/import — remedy is
+ * local: inline the value.
+ * · a global the NODE HOST has and the sandbox does not
+ * (#14301, `Intl`) — NOT inlinable, and still
+ * accidental rather than a chosen bundle: `Intl` is a
+ * standard global in every browser and in Node, so
+ * writing it is not the recognisable "I am reaching
+ * for the host" act that `fetch(`/`process.` are.
+ * That is why it is an `error` here and not the
+ * `warning` its structural cousin gets — and why the
+ * remedy sentence below is CHOSEN per sub-case.
  * `forbidden-token` STRUCTURAL. `fetch`/`require`/`process`/`eval`/… are
  * capabilities the sandbox does not have, so the handler
  * can NEVER be a metadata body. Writing one IS choosing a
@@ -129,12 +138,37 @@ function judge(fn: AnyFn, originLabel: string, path: string): HookBodyLintIssue
  } catch (err: unknown) {
  const kind = err instanceof HookBodyExtractionError ? err.kind : 'unknown';
  const free = err instanceof HookBodyExtractionError ? err.freeIdentifiers : [];
+ // [#14301] The half of `free` the Node HOST provides and the sandbox does
+ // not. Read off the refusal rather than re-derived here: this rule's whole
+ // parity claim is that it cannot disagree with what `os build` did to the
+ // same handler, and a second membership table in this file would be exactly
+ // such a disagreement waiting to happen.
+ const nodeOnly = err instanceof HookBodyExtractionError ? err.nodeOnlyIdentifiers : [];
  // Only the first line: the refusal text carries a multi-line offending-source
  // dump for `--strict-body`'s per-callable diagnostic, which would swamp a
  // lint report. `os build --strict-body` remains the place to read it whole.
  const firstLine = String((err as Error)?.message ?? err).split('\n')[0];
 
  if (kind === 'free-identifiers') {
+ // The remedy sentence is chosen, not fixed. "Inline the value(s)" is
+ // right for a module-scope helper and IMPOSSIBLE for a host global —
+ // there is nothing to inline `Intl` from — so printing it for both would
+ // send an author (or a code-writing model) after a second broken shape.
+ const moduleScope = free.filter((n) => !nodeOnly.includes(n));
+ const hostRemedy =
+ `${nodeOnly.join(', ')} ${nodeOnly.length === 1 ? 'is' : 'are'} provided by the Node host ` +
+ `and NOT by the sandbox, so ${nodeOnly.length === 1 ? 'it' : 'they'} cannot be inlined: ` +
+ `keep the check in a string handler ref, or move it to a validation rule.`;
+ const inlineRemedy =
+ `Inline the value(s) into the handler, or reach them through \`ctx\`.`;
+ const remedy =
+ nodeOnly.length === 0
+ ? inlineRemedy
+ : moduleScope.length === 0
+ ? hostRemedy
+ : `${hostRemedy} ${moduleScope.join(', ')} ${moduleScope.length === 1 ? 'is' : 'are'} ` +
+ `module-scope: inline ${moduleScope.length === 1 ? 'it' : 'them'} into the handler, ` +
+ `or reach ${moduleScope.length === 1 ? 'it' : 'them'} through \`ctx\`.`;
  return {
  severity: 'error',
  rule: NOT_LOWERABLE_RULE,
@@ -143,8 +177,7 @@ function judge(fn: AnyFn, originLabel: string, path: string): HookBodyLintIssue
  `${free.length === 1 ? 'the identifier' : 'identifiers'} ${free.join(', ')}, which ` +
  `${free.length === 1 ? 'is' : 'are'} not in scope inside the sandbox. The handler is ` +
  `BUNDLED instead, so this app is no longer shippable as pure metadata — a change of ` +
- `deployment shape, not of behaviour. Inline the value(s) into the handler, or reach ` +
- `them through \`ctx\`. ${DELIBERATE_BUNDLE_REMEDY}`,
+ `deployment shape, not of behaviour. ${remedy} ${DELIBERATE_BUNDLE_REMEDY}`,
  path,
  };
  }

packages/cli/src/utils/detect-free-identifiers.test.ts

@@ -1,7 +1,11 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { describe, it, expect } from 'vitest';
-import { detectFreeIdentifiers } from './detect-free-identifiers.js';
+import {
+ detectFreeIdentifiers,
+ NODE_ONLY_GLOBALS,
+ SANDBOX_GLOBALS,
+} from './detect-free-identifiers.js';
 
 /** Helper: stringify a real function so we test the exact `.toString()` path. */
 const src = (fn: (...a: any[]) => any) => String(fn);
@@ -53,6 +57,14 @@ describe('detectFreeIdentifiers (#1876 — body self-containment)', () => {
  ['nested destructuring', '({ a: { b } }) => b + 1'],
  ['rest params', '(...args) => args.length'],
  ['typeof a local', '(ctx) => { const v = ctx.v; return typeof v; }'],
+ // #14301 — the node-only refusal is a SCOPE analysis, not a token scan.
+ // A locally-bound name that happens to spell a host global is bound, and
+ // a member NAMED after one is not a reference at all. Both would be
+ // false refusals, and a false refusal here costs an author a body they
+ // were entitled to.
+ ['a local shadowing a host global', '(ctx) => { const Intl = ctx.fmt; return Intl.format(ctx.d); }'],
+ ['a member named after a host global', '(ctx) => { return ctx.Intl.format(ctx.d); }'],
+ ['a param named after a host global', '(ctx, Intl) => Intl.format(ctx.d)'],
  ];
  for (const [label, source] of selfContained) {
  it(label, () => {
@@ -81,4 +93,79 @@ describe('detectFreeIdentifiers (#1876 — body self-containment)', () => {
  expect(detectFreeIdentifiers('').free).toEqual([]);
  expect(detectFreeIdentifiers('{ not: valid').free).toEqual([]);
  });
+ // ── #14301 — globals the NODE HOST has and the sandbox does not ──────────
+ //
+ // The reported shape: `Intl` sat in one generous allowlist beside `JSON`, so
+ // a handler calling `Intl.DateTimeFormat` had no free identifier, lowered
+ // into `body.source`, and threw `ReferenceError` in production while every
+ // local gate was green. The split makes the reference visible again; the
+ // membership of the two sets is not asserted here from knowledge — it is
+ // measured inside the real sandbox by `sandbox-globals-probe.test.ts`.
+ describe('reports host globals the sandbox does not provide', () => {
+ it('the card reproduction — Intl.DateTimeFormat', () => {
+ const r = detectFreeIdentifiers(
+ "(ctx) => { const f = new Intl.DateTimeFormat('en-US'); ctx.input.label = f.format(new Date(ctx.input.at)); }",
+ );
+ expect(r.unparsed).toBe(false);
+ expect(r.free).toEqual(['Intl']);
+ expect(r.nodeOnly).toEqual(['Intl']);
+ });
+
+ it('`nodeOnly` is a labelled SUBSET of `free`, not a second list', () => {
+ // Both halves at once. The caller needs them apart because the remedies
+ // are opposite — inline the helper, but a host global cannot be inlined
+ // — and needs them together because the refusal names every name.
+ const r = detectFreeIdentifiers('(ctx) => { ctx.x = slugify(ctx.name) + Intl.NumberFormat; }');
+ expect(r.free).toEqual(['Intl', 'slugify']);
+ expect(r.nodeOnly).toEqual(['Intl']);
+ expect(r.nodeOnly.every((n) => r.free.includes(n))).toBe(true);
+ });
+
+ it('a sandbox-provided global is still waived — the positive control', () => {
+ const r = detectFreeIdentifiers('(ctx) => { ctx.x = JSON.stringify(Math.round(ctx.n)); }');
+ expect(r.free).toEqual([]);
+ expect(r.nodeOnly).toEqual([]);
+ });
+
+ it('every member of NODE_ONLY_GLOBALS is reported when referenced free', () => {
+ // Set-wide rather than per-name: a member added to the set without the
+ // detector reading it would otherwise sit inert, which is the exact
+ // shape of the defect being closed one level up.
+ for (const name of NODE_ONLY_GLOBALS) {
+ const r = detectFreeIdentifiers(`(ctx) => { ctx.x = ${name}; }`);
+ expect({ name, free: r.free, nodeOnly: r.nodeOnly }).toEqual({
+ name,
+ free: [name],
+ nodeOnly: [name],
+ });
+ }
+ });
+
+ it('every member of SANDBOX_GLOBALS is waived when referenced free', () => {
+ for (const name of SANDBOX_GLOBALS) {
+ const r = detectFreeIdentifiers(`(ctx) => { ctx.x = ${name}; }`);
+ expect({ name, free: r.free, nodeOnly: r.nodeOnly }).toEqual({
+ name,
+ free: [],
+ nodeOnly: [],
+ });
+ }
+ });
+
+ it('junk input reports neither list (conservative — never blocks extraction)', () => {
+ // The bias the file's header states, restated over the NEW field: a
+ // source this analysis cannot make sense of must not produce a refusal.
+ // Asserted over the same three junk shapes the #1876 case uses, and
+ // without asserting `unparsed` — TS error-recovery decides that, and the
+ // invariant that matters is that neither list fills.
+ for (const junk of ['this is not a function', '', '{ not: valid']) {
+ const r = detectFreeIdentifiers(junk);
+ expect({ junk, free: r.free, nodeOnly: r.nodeOnly }).toEqual({
+ junk,
+ free: [],
+ nodeOnly: [],
+ });
+ }
+ });
+ });
 });

.changeset/hook-body-sandbox-globals-allowlist.md

@@ -0,0 +1,64 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): stop lowering hook/action bodies that reference globals the sandbox does not provide (#14301)
+
+`detect-free-identifiers`' ambient allowlist was ONE generous list, documented as
+"assume the runtime has it". The runtime a lowered body actually runs in is the
+QuickJS sandbox, not the Node process that runs `objectstack build` — and the
+list named `Intl` beside `JSON`, under the comment "Web-ish that the sandbox /
+Node commonly provide". So a handler calling `Intl.DateTimeFormat` had no free
+identifier at all: `extractHookBody` lowered it into `body.source`, the #13651
+lint rule had nothing to report (it fires only on a *refused* lowering),
+`validate` / `typecheck` / `test` / `build` were all green because the
+in-process test runs the RAW function in Node where `Intl` exists — and
+production threw `ReferenceError: Intl is not defined`. Under the
+`onError: 'abort'` a validation-shaped hook must declare, that refuses every
+write to the object.
+
+The allowlist is now two sets, and membership is **measured**, never recalled: a
+`typeof X`/`'X' in globalThis` probe is evaluated inside the same
+`QuickJSScriptRunner` the runtime evaluates a body in, and
+`sandbox-globals-probe.test.ts` fails unless each set is exactly the probe's
+present/absent partition.
+
+- **`SANDBOX_GLOBALS` (53, measured present)** — the ECMAScript surface:
+ `Math` `JSON` `Date` `Object` `Array` `String` `Number` `Boolean` `RegExp`
+ `Map` `Set` `WeakMap` `WeakSet` `Promise` `Symbol` `BigInt` `Function`
+ `Reflect` `Proxy`, the typed-array/buffer family, the eight error
+ constructors, `parseInt` `parseFloat` `isNaN` `isFinite` and the four URI
+ functions, plus `undefined` `NaN` `Infinity` `globalThis`.
+- **`NODE_ONLY_GLOBALS` (15, measured absent)** — `Intl`, `structuredClone`,
+ `queueMicrotask`, `atob`, `btoa`, `setTimeout`, `clearTimeout`,
+ `setInterval`, `clearInterval`, `URL`, `URLSearchParams`, `TextEncoder`,
+ `TextDecoder`, `console`, `arguments`.
+
+A free reference to one of the 15 is now a lowering refusal whose reason names
+the identifier and the remedy — a string handler ref (`functions:` map plus
+`handler: 'fn_name'`) or a validation rule, and for `console` specifically the
+capability-gated `ctx.log`. It travels the SAME path #1876 already used: the
+refusal is `kind: 'free-identifiers'` with the host-only half carried
+separately as `nodeOnlyIdentifiers`, `lowerCallables` catches it and ships the
+callable through the `.mjs` bundle (where it runs in-process in Node and
+works), `os build` still exits 0 with a warning, and `os lint` reports it under
+`hook-body/not-lowerable` as an `error` — the ACCIDENTAL class, because `Intl`
+is a standard global in every browser and in Node and writing it is not the
+recognisable "I am reaching for the host" act that `fetch(` and `process.` are.
+The remedy sentence `os lint` prints is chosen from the refusal's own
+classification: "inline the value" is impossible for a host global, and
+printing it anyway would send an author after a second broken shape.
+
+⛔ Not changed here: whether `os build` fails on the lowering class (#13838),
+and what the sandbox provides (giving it `Intl` would be a capability
+expansion). Nothing under `packages/runtime/**` is touched — the probe reads
+that sandbox, it does not change it.
+
+**Why `patch`.** No published accept-set moves: the metadata a valid app may
+declare is identical, `HookBodySchema` is untouched, and no key is added,
+removed or re-shaped. What narrows is which handlers the build LOWERS, and for
+every handler affected the previous outcome was a body that could not run. An
+app hitting this gains a warning and a working bundled closure in place of a
+production `ReferenceError`; the deployment shape it loses was never one it had
+in working order. Measured corpus: zero in-repo example or template handlers
+reference any of the 15.

packages/cli/src/lint/hook-body-lowering.test.ts

@@ -42,6 +42,19 @@ const forbiddenTokenHook = {
  },
 };
 
+// [#14301] A global the NODE HOST provides and the sandbox does not. Reads as
+// self-contained — `Intl` is standard in every browser and in Node — which is
+// precisely why it is the ACCIDENTAL class and not the structural one.
+const nodeOnlyGlobalHook = {
+ name: 'stamp_due_label',
+ object: 'task',
+ events: ['beforeInsert'],
+ handler: (ctx: any) => {
+ const f = new Intl.DateTimeFormat('en-US', { timeZone: 'UTC' });
+ ctx.input.due_label = f.format(new Date(ctx.input.due_at));
+ },
+};
+
 const selfContainedHook = {
  name: 'normalize_name',
  object: 'account',
@@ -91,6 +104,41 @@ describe('checkHookBodyLowering', () => {
  expect(issues[0].message).toContain('deployment shape');
  });
 
+ describe('a host global the sandbox lacks is the ACCIDENTAL class (#14301)', () => {
+ it('reports it as an ERROR under the not-lowerable rule', () => {
+ const issues = checkHookBodyLowering({ hooks: [nodeOnlyGlobalHook] });
+
+ expect(issues).toHaveLength(1);
+ expect(issues[0].severity).toBe('error');
+ expect(issues[0].rule).toBe(NOT_LOWERABLE_RULE);
+ expect(issues[0].path).toBe('hooks[0].handler');
+ expect(issues[0].message).toContain("hook 'stamp_due_label'");
+ expect(issues[0].message).toContain('Intl');
+ expect(issues[0].message).toContain('deployment shape');
+ });
+
+ it('prints the remedy that is POSSIBLE, not the inline one', () => {
+ // The wrong-remedy failure is worse than none: there is nothing to inline
+ // `Intl` from, so an author (or a code-writing model) told to inline it
+ // lands on a second broken shape. The remedy sentence is chosen from the
+ // refusal's own `nodeOnlyIdentifiers`, never re-derived here.
+ const [issue] = checkHookBodyLowering({ hooks: [nodeOnlyGlobalHook] });
+ expect(issue.message).toContain('provided by the Node host');
+ expect(issue.message).toContain('cannot be inlined');
+ expect(issue.message).toContain('string handler ref');
+ expect(issue.message).toContain('validation rule');
+ expect(issue.message).not.toContain('Inline the value(s) into the handler');
+ });
+
+ it('leaves the module-scope remedy exactly as it was', () => {
+ // The reverse leg: the #13651 sentence must not have been rewritten for
+ // every author by a branch added for one new sub-case.
+ const [issue] = checkHookBodyLowering({ hooks: [freeIdentifierHook] });
+ expect(issue.message).toContain('Inline the value(s) into the handler, or reach them through `ctx`.');
+ expect(issue.message).not.toContain('provided by the Node host');
+ });
+ });
+
  it('keeps the STRUCTURAL refusal a warning — the bundle is its designed answer', () => {
  const issues = checkHookBodyLowering({ hooks: [forbiddenTokenHook] });
 

packages/cli/src/lint/hook-body-lowering.ts

@@ -38,13 +38,22 @@
  * Today both arrive through one catch, so they share one fate. They are not
  * the same event, and the refusal kind already tells them apart:
  *
- * `free-identifiers` ACCIDENTAL. The handler IS expressible as a metadata
- * body; it merely names a module-scope const/helper/
- * import. The author wrote something that reads
+ * `free-identifiers` ACCIDENTAL. The author wrote something that reads
  * self-contained, and the platform quietly re-shaped the
  * deployment behind them — its own message even says "no
  * behavior change", which is true of behaviour and false
- * of shape. Remedy is local: inline the value. => `error`.
+ * of shape. => `error`, for both sub-cases:
+ * · a module-scope const/helper/import — remedy is
+ * local: inline the value.
+ * · a global the NODE HOST has and the sandbox does not
+ * (#14301, `Intl`) — NOT inlinable, and still
+ * accidental rather than a chosen bundle: `Intl` is a
+ * standard global in every browser and in Node, so
+ * writing it is not the recognisable "I am reaching
+ * for the host" act that `fetch(`/`process.` are.
+ * That is why it is an `error` here and not the
+ * `warning` its structural cousin gets — and why the
+ * remedy sentence below is CHOSEN per sub-case.
  * `forbidden-token` STRUCTURAL. `fetch`/`require`/`process`/`eval`/… are
  * capabilities the sandbox does not have, so the handler
  * can NEVER be a metadata body. Writing one IS choosing a
@@ -129,12 +138,37 @@ function judge(fn: AnyFn, originLabel: string, path: string): HookBodyLintIssue
  } catch (err: unknown) {
  const kind = err instanceof HookBodyExtractionError ? err.kind : 'unknown';
  const free = err instanceof HookBodyExtractionError ? err.freeIdentifiers : [];
+ // [#14301] The half of `free` the Node HOST provides and the sandbox does
+ // not. Read off the refusal rather than re-derived here: this rule's whole
+ // parity claim is that it cannot disagree with what `os build` did to the
+ // same handler, and a second membership table in this file would be exactly
+ // such a disagreement waiting to happen.
+ const nodeOnly = err instanceof HookBodyExtractionError ? err.nodeOnlyIdentifiers : [];
  // Only the first line: the refusal text carries a multi-line offending-source
  // dump for `--strict-body`'s per-callable diagnostic, which would swamp a
  // lint report. `os build --strict-body` remains the place to read it whole.
  const firstLine = String((err as Error)?.message ?? err).split('\n')[0];
 
  if (kind === 'free-identifiers') {
+ // The remedy sentence is chosen, not fixed. "Inline the value(s)" is
+ // right for a module-scope helper and IMPOSSIBLE for a host global —
+ // there is nothing to inline `Intl` from — so printing it for both would
+ // send an author (or a code-writing model) after a second broken shape.
+ const moduleScope = free.filter((n) => !nodeOnly.includes(n));
+ const hostRemedy =
+ `${nodeOnly.join(', ')} ${nodeOnly.length === 1 ? 'is' : 'are'} provided by the Node host ` +
+ `and NOT by the sandbox, so ${nodeOnly.length === 1 ? 'it' : 'they'} cannot be inlined: ` +
+ `keep the check in a string handler ref, or move it to a validation rule.`;
+ const inlineRemedy =
+ `Inline the value(s) into the handler, or reach them through \`ctx\`.`;
+ const remedy =
+ nodeOnly.length === 0
+ ? inlineRemedy
+ : moduleScope.length === 0
+ ? hostRemedy
+ : `${hostRemedy} ${moduleScope.join(', ')} ${moduleScope.length === 1 ? 'is' : 'are'} ` +
+ `module-scope: inline ${moduleScope.length === 1 ? 'it' : 'them'} into the handler, ` +
+ `or reach ${moduleScope.length === 1 ? 'it' : 'them'} through \`ctx\`.`;
  return {
  severity: 'error',
  rule: NOT_LOWERABLE_RULE,
@@ -143,8 +177,7 @@ function judge(fn: AnyFn, originLabel: string, path: string): HookBodyLintIssue
  `${free.length === 1 ? 'the identifier' : 'identifiers'} ${free.join(', ')}, which ` +
  `${free.length === 1 ? 'is' : 'are'} not in scope inside the sandbox. The handler is ` +
  `BUNDLED instead, so this app is no longer shippable as pure metadata — a change of ` +
- `deployment shape, not of behaviour. Inline the value(s) into the handler, or reach ` +
- `them through \`ctx\`. ${DELIBERATE_BUNDLE_REMEDY}`,
+ `deployment shape, not of behaviour. ${remedy} ${DELIBERATE_BUNDLE_REMEDY}`,
  path,
  };
  }

packages/cli/src/utils/detect-free-identifiers.test.ts

@@ -1,7 +1,11 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { describe, it, expect } from 'vitest';
-import { detectFreeIdentifiers } from './detect-free-identifiers.js';
+import {
+ detectFreeIdentifiers,
+ NODE_ONLY_GLOBALS,
+ SANDBOX_GLOBALS,
+} from './detect-free-identifiers.js';
 
 /** Helper: stringify a real function so we test the exact `.toString()` path. */
 const src = (fn: (...a: any[]) => any) => String(fn);
@@ -53,6 +57,14 @@ describe('detectFreeIdentifiers (#1876 — body self-containment)', () => {
  ['nested destructuring', '({ a: { b } }) => b + 1'],
  ['rest params', '(...args) => args.length'],
  ['typeof a local', '(ctx) => { const v = ctx.v; return typeof v; }'],
+ // #14301 — the node-only refusal is a SCOPE analysis, not a token scan.
+ // A locally-bound name that happens to spell a host global is bound, and
+ // a member NAMED after one is not a reference at all. Both would be
+ // false refusals, and a false refusal here costs an author a body they
+ // were entitled to.
+ ['a local shadowing a host global', '(ctx) => { const Intl = ctx.fmt; return Intl.format(ctx.d); }'],
+ ['a member named after a host global', '(ctx) => { return ctx.Intl.format(ctx.d); }'],
+ ['a param named after a host global', '(ctx, Intl) => Intl.format(ctx.d)'],
  ];
  for (const [label, source] of selfContained) {
  it(label, () => {
@@ -81,4 +93,79 @@ describe('detectFreeIdentifiers (#1876 — body self-containment)', () => {
  expect(detectFreeIdentifiers('').free).toEqual([]);
  expect(detectFreeIdentifiers('{ not: valid').free).toEqual([]);
  });
+ // ── #14301 — globals the NODE HOST has and the sandbox does not ──────────
+ //
+ // The reported shape: `Intl` sat in one generous allowlist beside `JSON`, so
+ // a handler calling `Intl.DateTimeFormat` had no free identifier, lowered
+ // into `body.source`, and threw `ReferenceError` in production while every
+ // local gate was green. The split makes the reference visible again; the
+ // membership of the two sets is not asserted here from knowledge — it is
+ // measured inside the real sandbox by `sandbox-globals-probe.test.ts`.
+ describe('reports host globals the sandbox does not provide', () => {
+ it('the card reproduction — Intl.DateTimeFormat', () => {
+ const r = detectFreeIdentifiers(
+ "(ctx) => { const f = new Intl.DateTimeFormat('en-US'); ctx.input.label = f.format(new Date(ctx.input.at)); }",
+ );
+ expect(r.unparsed).toBe(false);
+ expect(r.free).toEqual(['Intl']);
+ expect(r.nodeOnly).toEqual(['Intl']);
+ });
+
+ it('`nodeOnly` is a labelled SUBSET of `free`, not a second list', () => {
+ // Both halves at once. The caller needs them apart because the remedies
+ // are opposite — inline the helper, but a host global cannot be inlined
+ // — and needs them together because the refusal names every name.
+ const r = detectFreeIdentifiers('(ctx) => { ctx.x = slugify(ctx.name) + Intl.NumberFormat; }');
+ expect(r.free).toEqual(['Intl', 'slugify']);
+ expect(r.nodeOnly).toEqual(['Intl']);
+ expect(r.nodeOnly.every((n) => r.free.includes(n))).toBe(true);
+ });
+
+ it('a sandbox-provided global is still waived — the positive control', () => {
+ const r = detectFreeIdentifiers('(ctx) => { ctx.x = JSON.stringify(Math.round(ctx.n)); }');
+ expect(r.free).toEqual([]);
+ expect(r.nodeOnly).toEqual([]);
+ });
+
+ it('every member of NODE_ONLY_GLOBALS is reported when referenced free', () => {
+ // Set-wide rather than per-name: a member added to the set without the
+ // detector reading it would otherwise sit inert, which is the exact
+ // shape of the defect being closed one level up.
+ for (const name of NODE_ONLY_GLOBALS) {
+ const r = detectFreeIdentifiers(`(ctx) => { ctx.x = ${name}; }`);
+ expect({ name, free: r.free, nodeOnly: r.nodeOnly }).toEqual({
+ name,
+ free: [name],
+ nodeOnly: [name],
+ });
+ }
+ });
+
+ it('every member of SANDBOX_GLOBALS is waived when referenced free', () => {
+ for (const name of SANDBOX_GLOBALS) {
+ const r = detectFreeIdentifiers(`(ctx) => { ctx.x = ${name}; }`);
+ expect({ name, free: r.free, nodeOnly: r.nodeOnly }).toEqual({
+ name,
+ free: [],
+ nodeOnly: [],
+ });
+ }
+ });
+
+ it('junk input reports neither list (conservative — never blocks extraction)', () => {
+ // The bias the file's header states, restated over the NEW field: a
+ // source this analysis cannot make sense of must not produce a refusal.
+ // Asserted over the same three junk shapes the #1876 case uses, and
+ // without asserting `unparsed` — TS error-recovery decides that, and the
+ // invariant that matters is that neither list fills.
+ for (const junk of ['this is not a function', '', '{ not: valid']) {
+ const r = detectFreeIdentifiers(junk);
+ expect({ junk, free: r.free, nodeOnly: r.nodeOnly }).toEqual({
+ junk,
+ free: [],
+ nodeOnly: [],
+ });
+ }
+ });
+ });
 });

.changeset/hook-body-sandbox-globals-allowlist.md

@@ -0,0 +1,64 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): stop lowering hook/action bodies that reference globals the sandbox does not provide (#14301)
+
+`detect-free-identifiers`' ambient allowlist was ONE generous list, documented as
+"assume the runtime has it". The runtime a lowered body actually runs in is the
+QuickJS sandbox, not the Node process that runs `objectstack build` — and the
+list named `Intl` beside `JSON`, under the comment "Web-ish that the sandbox /
+Node commonly provide". So a handler calling `Intl.DateTimeFormat` had no free
+identifier at all: `extractHookBody` lowered it into `body.source`, the #13651
+lint rule had nothing to report (it fires only on a *refused* lowering),
+`validate` / `typecheck` / `test` / `build` were all green because the
+in-process test runs the RAW function in Node where `Intl` exists — and
+production threw `ReferenceError: Intl is not defined`. Under the
+`onError: 'abort'` a validation-shaped hook must declare, that refuses every
+write to the object.
+
+The allowlist is now two sets, and membership is **measured**, never recalled: a
+`typeof X`/`'X' in globalThis` probe is evaluated inside the same
+`QuickJSScriptRunner` the runtime evaluates a body in, and
+`sandbox-globals-probe.test.ts` fails unless each set is exactly the probe's
+present/absent partition.
+
+- **`SANDBOX_GLOBALS` (53, measured present)** — the ECMAScript surface:
+ `Math` `JSON` `Date` `Object` `Array` `String` `Number` `Boolean` `RegExp`
+ `Map` `Set` `WeakMap` `WeakSet` `Promise` `Symbol` `BigInt` `Function`
+ `Reflect` `Proxy`, the typed-array/buffer family, the eight error
+ constructors, `parseInt` `parseFloat` `isNaN` `isFinite` and the four URI
+ functions, plus `undefined` `NaN` `Infinity` `globalThis`.
+- **`NODE_ONLY_GLOBALS` (15, measured absent)** — `Intl`, `structuredClone`,
+ `queueMicrotask`, `atob`, `btoa`, `setTimeout`, `clearTimeout`,
+ `setInterval`, `clearInterval`, `URL`, `URLSearchParams`, `TextEncoder`,
+ `TextDecoder`, `console`, `arguments`.
+
+A free reference to one of the 15 is now a lowering refusal whose reason names
+the identifier and the remedy — a string handler ref (`functions:` map plus
+`handler: 'fn_name'`) or a validation rule, and for `console` specifically the
+capability-gated `ctx.log`. It travels the SAME path #1876 already used: the
+refusal is `kind: 'free-identifiers'` with the host-only half carried
+separately as `nodeOnlyIdentifiers`, `lowerCallables` catches it and ships the
+callable through the `.mjs` bundle (where it runs in-process in Node and
+works), `os build` still exits 0 with a warning, and `os lint` reports it under
+`hook-body/not-lowerable` as an `error` — the ACCIDENTAL class, because `Intl`
+is a standard global in every browser and in Node and writing it is not the
+recognisable "I am reaching for the host" act that `fetch(` and `process.` are.
+The remedy sentence `os lint` prints is chosen from the refusal's own
+classification: "inline the value" is impossible for a host global, and
+printing it anyway would send an author after a second broken shape.
+
+⛔ Not changed here: whether `os build` fails on the lowering class (#13838),
+and what the sandbox provides (giving it `Intl` would be a capability
+expansion). Nothing under `packages/runtime/**` is touched — the probe reads
+that sandbox, it does not change it.
+
+**Why `patch`.** No published accept-set moves: the metadata a valid app may
+declare is identical, `HookBodySchema` is untouched, and no key is added,
+removed or re-shaped. What narrows is which handlers the build LOWERS, and for
+every handler affected the previous outcome was a body that could not run. An
+app hitting this gains a warning and a working bundled closure in place of a
+production `ReferenceError`; the deployment shape it loses was never one it had
+in working order. Measured corpus: zero in-repo example or template handlers
+reference any of the 15.

packages/cli/src/lint/hook-body-lowering.test.ts

@@ -42,6 +42,19 @@ const forbiddenTokenHook = {
  },
 };
 
+// [#14301] A global the NODE HOST provides and the sandbox does not. Reads as
+// self-contained — `Intl` is standard in every browser and in Node — which is
+// precisely why it is the ACCIDENTAL class and not the structural one.
+const nodeOnlyGlobalHook = {
+ name: 'stamp_due_label',
+ object: 'task',
+ events: ['beforeInsert'],
+ handler: (ctx: any) => {
+ const f = new Intl.DateTimeFormat('en-US', { timeZone: 'UTC' });
+ ctx.input.due_label = f.format(new Date(ctx.input.due_at));
+ },
+};
+
 const selfContainedHook = {
  name: 'normalize_name',
  object: 'account',
@@ -91,6 +104,41 @@ describe('checkHookBodyLowering', () => {
  expect(issues[0].message).toContain('deployment shape');
  });
 
+ describe('a host global the sandbox lacks is the ACCIDENTAL class (#14301)', () => {
+ it('reports it as an ERROR under the not-lowerable rule', () => {
+ const issues = checkHookBodyLowering({ hooks: [nodeOnlyGlobalHook] });
+
+ expect(issues).toHaveLength(1);
+ expect(issues[0].severity).toBe('error');
+ expect(issues[0].rule).toBe(NOT_LOWERABLE_RULE);
+ expect(issues[0].path).toBe('hooks[0].handler');
+ expect(issues[0].message).toContain("hook 'stamp_due_label'");
+ expect(issues[0].message).toContain('Intl');
+ expect(issues[0].message).toContain('deployment shape');
+ });
+
+ it('prints the remedy that is POSSIBLE, not the inline one', () => {
+ // The wrong-remedy failure is worse than none: there is nothing to inline
+ // `Intl` from, so an author (or a code-writing model) told to inline it
+ // lands on a second broken shape. The remedy sentence is chosen from the
+ // refusal's own `nodeOnlyIdentifiers`, never re-derived here.
+ const [issue] = checkHookBodyLowering({ hooks: [nodeOnlyGlobalHook] });
+ expect(issue.message).toContain('provided by the Node host');
+ expect(issue.message).toContain('cannot be inlined');
+ expect(issue.message).toContain('string handler ref');
+ expect(issue.message).toContain('validation rule');
+ expect(issue.message).not.toContain('Inline the value(s) into the handler');
+ });
+
+ it('leaves the module-scope remedy exactly as it was', () => {
+ // The reverse leg: the #13651 sentence must not have been rewritten for
+ // every author by a branch added for one new sub-case.
+ const [issue] = checkHookBodyLowering({ hooks: [freeIdentifierHook] });
+ expect(issue.message).toContain('Inline the value(s) into the handler, or reach them through `ctx`.');
+ expect(issue.message).not.toContain('provided by the Node host');
+ });
+ });
+
  it('keeps the STRUCTURAL refusal a warning — the bundle is its designed answer', () => {
  const issues = checkHookBodyLowering({ hooks: [forbiddenTokenHook] });
 

packages/cli/src/lint/hook-body-lowering.ts

@@ -38,13 +38,22 @@
  * Today both arrive through one catch, so they share one fate. They are not
  * the same event, and the refusal kind already tells them apart:
  *
- * `free-identifiers` ACCIDENTAL. The handler IS expressible as a metadata
- * body; it merely names a module-scope const/helper/
- * import. The author wrote something that reads
+ * `free-identifiers` ACCIDENTAL. The author wrote something that reads
  * self-contained, and the platform quietly re-shaped the
  * deployment behind them — its own message even says "no
  * behavior change", which is true of behaviour and false
- * of shape. Remedy is local: inline the value. => `error`.
+ * of shape. => `error`, for both sub-cases:
+ * · a module-scope const/helper/import — remedy is
+ * local: inline the value.
+ * · a global the NODE HOST has and the sandbox does not
+ * (#14301, `Intl`) — NOT inlinable, and still
+ * accidental rather than a chosen bundle: `Intl` is a
+ * standard global in every browser and in Node, so
+ * writing it is not the recognisable "I am reaching
+ * for the host" act that `fetch(`/`process.` are.
+ * That is why it is an `error` here and not the
+ * `warning` its structural cousin gets — and why the
+ * remedy sentence below is CHOSEN per sub-case.
  * `forbidden-token` STRUCTURAL. `fetch`/`require`/`process`/`eval`/… are
  * capabilities the sandbox does not have, so the handler
  * can NEVER be a metadata body. Writing one IS choosing a
@@ -129,12 +138,37 @@ function judge(fn: AnyFn, originLabel: string, path: string): HookBodyLintIssue
  } catch (err: unknown) {
  const kind = err instanceof HookBodyExtractionError ? err.kind : 'unknown';
  const free = err instanceof HookBodyExtractionError ? err.freeIdentifiers : [];
+ // [#14301] The half of `free` the Node HOST provides and the sandbox does
+ // not. Read off the refusal rather than re-derived here: this rule's whole
+ // parity claim is that it cannot disagree with what `os build` did to the
+ // same handler, and a second membership table in this file would be exactly
+ // such a disagreement waiting to happen.
+ const nodeOnly = err instanceof HookBodyExtractionError ? err.nodeOnlyIdentifiers : [];
  // Only the first line: the refusal text carries a multi-line offending-source
  // dump for `--strict-body`'s per-callable diagnostic, which would swamp a
  // lint report. `os build --strict-body` remains the place to read it whole.
  const firstLine = String((err as Error)?.message ?? err).split('\n')[0];
 
  if (kind === 'free-identifiers') {
+ // The remedy sentence is chosen, not fixed. "Inline the value(s)" is
+ // right for a module-scope helper and IMPOSSIBLE for a host global —
+ // there is nothing to inline `Intl` from — so printing it for both would
+ // send an author (or a code-writing model) after a second broken shape.
+ const moduleScope = free.filter((n) => !nodeOnly.includes(n));
+ const hostRemedy =
+ `${nodeOnly.join(', ')} ${nodeOnly.length === 1 ? 'is' : 'are'} provided by the Node host ` +
+ `and NOT by the sandbox, so ${nodeOnly.length === 1 ? 'it' : 'they'} cannot be inlined: ` +
+ `keep the check in a string handler ref, or move it to a validation rule.`;
+ const inlineRemedy =
+ `Inline the value(s) into the handler, or reach them through \`ctx\`.`;
+ const remedy =
+ nodeOnly.length === 0
+ ? inlineRemedy
+ : moduleScope.length === 0
+ ? hostRemedy
+ : `${hostRemedy} ${moduleScope.join(', ')} ${moduleScope.length === 1 ? 'is' : 'are'} ` +
+ `module-scope: inline ${moduleScope.length === 1 ? 'it' : 'them'} into the handler, ` +
+ `or reach ${moduleScope.length === 1 ? 'it' : 'them'} through \`ctx\`.`;
  return {
  severity: 'error',
  rule: NOT_LOWERABLE_RULE,
@@ -143,8 +177,7 @@ function judge(fn: AnyFn, originLabel: string, path: string): HookBodyLintIssue
  `${free.length === 1 ? 'the identifier' : 'identifiers'} ${free.join(', ')}, which ` +
  `${free.length === 1 ? 'is' : 'are'} not in scope inside the sandbox. The handler is ` +
  `BUNDLED instead, so this app is no longer shippable as pure metadata — a change of ` +
- `deployment shape, not of behaviour. Inline the value(s) into the handler, or reach ` +
- `them through \`ctx\`. ${DELIBERATE_BUNDLE_REMEDY}`,
+ `deployment shape, not of behaviour. ${remedy} ${DELIBERATE_BUNDLE_REMEDY}`,
  path,
  };
  }

packages/cli/src/utils/detect-free-identifiers.test.ts

@@ -1,7 +1,11 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { describe, it, expect } from 'vitest';
-import { detectFreeIdentifiers } from './detect-free-identifiers.js';
+import {
+ detectFreeIdentifiers,
+ NODE_ONLY_GLOBALS,
+ SANDBOX_GLOBALS,
+} from './detect-free-identifiers.js';
 
 /** Helper: stringify a real function so we test the exact `.toString()` path. */
 const src = (fn: (...a: any[]) => any) => String(fn);
@@ -53,6 +57,14 @@ describe('detectFreeIdentifiers (#1876 — body self-containment)', () => {
  ['nested destructuring', '({ a: { b } }) => b + 1'],
  ['rest params', '(...args) => args.length'],
  ['typeof a local', '(ctx) => { const v = ctx.v; return typeof v; }'],
+ // #14301 — the node-only refusal is a SCOPE analysis, not a token scan.
+ // A locally-bound name that happens to spell a host global is bound, and
+ // a member NAMED after one is not a reference at all. Both would be
+ // false refusals, and a false refusal here costs an author a body they
+ // were entitled to.
+ ['a local shadowing a host global', '(ctx) => { const Intl = ctx.fmt; return Intl.format(ctx.d); }'],
+ ['a member named after a host global', '(ctx) => { return ctx.Intl.format(ctx.d); }'],
+ ['a param named after a host global', '(ctx, Intl) => Intl.format(ctx.d)'],
  ];
  for (const [label, source] of selfContained) {
  it(label, () => {
@@ -81,4 +93,79 @@ describe('detectFreeIdentifiers (#1876 — body self-containment)', () => {
  expect(detectFreeIdentifiers('').free).toEqual([]);
  expect(detectFreeIdentifiers('{ not: valid').free).toEqual([]);
  });
+ // ── #14301 — globals the NODE HOST has and the sandbox does not ──────────
+ //
+ // The reported shape: `Intl` sat in one generous allowlist beside `JSON`, so
+ // a handler calling `Intl.DateTimeFormat` had no free identifier, lowered
+ // into `body.source`, and threw `ReferenceError` in production while every
+ // local gate was green. The split makes the reference visible again; the
+ // membership of the two sets is not asserted here from knowledge — it is
+ // measured inside the real sandbox by `sandbox-globals-probe.test.ts`.
+ describe('reports host globals the sandbox does not provide', () => {
+ it('the card reproduction — Intl.DateTimeFormat', () => {
+ const r = detectFreeIdentifiers(
+ "(ctx) => { const f = new Intl.DateTimeFormat('en-US'); ctx.input.label = f.format(new Date(ctx.input.at)); }",
+ );
+ expect(r.unparsed).toBe(false);
+ expect(r.free).toEqual(['Intl']);
+ expect(r.nodeOnly).toEqual(['Intl']);
+ });
+
+ it('`nodeOnly` is a labelled SUBSET of `free`, not a second list', () => {
+ // Both halves at once. The caller needs them apart because the remedies
+ // are opposite — inline the helper, but a host global cannot be inlined
+ // — and needs them together because the refusal names every name.
+ const r = detectFreeIdentifiers('(ctx) => { ctx.x = slugify(ctx.name) + Intl.NumberFormat; }');
+ expect(r.free).toEqual(['Intl', 'slugify']);
+ expect(r.nodeOnly).toEqual(['Intl']);
+ expect(r.nodeOnly.every((n) => r.free.includes(n))).toBe(true);
+ });
+
+ it('a sandbox-provided global is still waived — the positive control', () => {
+ const r = detectFreeIdentifiers('(ctx) => { ctx.x = JSON.stringify(Math.round(ctx.n)); }');
+ expect(r.free).toEqual([]);
+ expect(r.nodeOnly).toEqual([]);
+ });
+
+ it('every member of NODE_ONLY_GLOBALS is reported when referenced free', () => {
+ // Set-wide rather than per-name: a member added to the set without the
+ // detector reading it would otherwise sit inert, which is the exact
+ // shape of the defect being closed one level up.
+ for (const name of NODE_ONLY_GLOBALS) {
+ const r = detectFreeIdentifiers(`(ctx) => { ctx.x = ${name}; }`);
+ expect({ name, free: r.free, nodeOnly: r.nodeOnly }).toEqual({
+ name,
+ free: [name],
+ nodeOnly: [name],
+ });
+ }
+ });
+
+ it('every member of SANDBOX_GLOBALS is waived when referenced free', () => {
+ for (const name of SANDBOX_GLOBALS) {
+ const r = detectFreeIdentifiers(`(ctx) => { ctx.x = ${name}; }`);
+ expect({ name, free: r.free, nodeOnly: r.nodeOnly }).toEqual({
+ name,
+ free: [],
+ nodeOnly: [],
+ });
+ }
+ });
+
+ it('junk input reports neither list (conservative — never blocks extraction)', () => {
+ // The bias the file's header states, restated over the NEW field: a
+ // source this analysis cannot make sense of must not produce a refusal.
+ // Asserted over the same three junk shapes the #1876 case uses, and
+ // without asserting `unparsed` — TS error-recovery decides that, and the
+ // invariant that matters is that neither list fills.
+ for (const junk of ['this is not a function', '', '{ not: valid']) {
+ const r = detectFreeIdentifiers(junk);
+ expect({ junk, free: r.free, nodeOnly: r.nodeOnly }).toEqual({
+ junk,
+ free: [],
+ nodeOnly: [],
+ });
+ }
+ });
+ });
 });

.changeset/hook-body-sandbox-globals-allowlist.md

@@ -0,0 +1,64 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): stop lowering hook/action bodies that reference globals the sandbox does not provide (#14301)
+
+`detect-free-identifiers`' ambient allowlist was ONE generous list, documented as
+"assume the runtime has it". The runtime a lowered body actually runs in is the
+QuickJS sandbox, not the Node process that runs `objectstack build` — and the
+list named `Intl` beside `JSON`, under the comment "Web-ish that the sandbox /
+Node commonly provide". So a handler calling `Intl.DateTimeFormat` had no free
+identifier at all: `extractHookBody` lowered it into `body.source`, the #13651
+lint rule had nothing to report (it fires only on a *refused* lowering),
+`validate` / `typecheck` / `test` / `build` were all green because the
+in-process test runs the RAW function in Node where `Intl` exists — and
+production threw `ReferenceError: Intl is not defined`. Under the
+`onError: 'abort'` a validation-shaped hook must declare, that refuses every
+write to the object.
+
+The allowlist is now two sets, and membership is **measured**, never recalled: a
+`typeof X`/`'X' in globalThis` probe is evaluated inside the same
+`QuickJSScriptRunner` the runtime evaluates a body in, and
+`sandbox-globals-probe.test.ts` fails unless each set is exactly the probe's
+present/absent partition.
+
+- **`SANDBOX_GLOBALS` (53, measured present)** — the ECMAScript surface:
+ `Math` `JSON` `Date` `Object` `Array` `String` `Number` `Boolean` `RegExp`
+ `Map` `Set` `WeakMap` `WeakSet` `Promise` `Symbol` `BigInt` `Function`
+ `Reflect` `Proxy`, the typed-array/buffer family, the eight error
+ constructors, `parseInt` `parseFloat` `isNaN` `isFinite` and the four URI
+ functions, plus `undefined` `NaN` `Infinity` `globalThis`.
+- **`NODE_ONLY_GLOBALS` (15, measured absent)** — `Intl`, `structuredClone`,
+ `queueMicrotask`, `atob`, `btoa`, `setTimeout`, `clearTimeout`,
+ `setInterval`, `clearInterval`, `URL`, `URLSearchParams`, `TextEncoder`,
+ `TextDecoder`, `console`, `arguments`.
+
+A free reference to one of the 15 is now a lowering refusal whose reason names
+the identifier and the remedy — a string handler ref (`functions:` map plus
+`handler: 'fn_name'`) or a validation rule, and for `console` specifically the
+capability-gated `ctx.log`. It travels the SAME path #1876 already used: the
+refusal is `kind: 'free-identifiers'` with the host-only half carried
+separately as `nodeOnlyIdentifiers`, `lowerCallables` catches it and ships the
+callable through the `.mjs` bundle (where it runs in-process in Node and
+works), `os build` still exits 0 with a warning, and `os lint` reports it under
+`hook-body/not-lowerable` as an `error` — the ACCIDENTAL class, because `Intl`
+is a standard global in every browser and in Node and writing it is not the
+recognisable "I am reaching for the host" act that `fetch(` and `process.` are.
+The remedy sentence `os lint` prints is chosen from the refusal's own
+classification: "inline the value" is impossible for a host global, and
+printing it anyway would send an author after a second broken shape.
+
+⛔ Not changed here: whether `os build` fails on the lowering class (#13838),
+and what the sandbox provides (giving it `Intl` would be a capability
+expansion). Nothing under `packages/runtime/**` is touched — the probe reads
+that sandbox, it does not change it.
+
+**Why `patch`.** No published accept-set moves: the metadata a valid app may
+declare is identical, `HookBodySchema` is untouched, and no key is added,
+removed or re-shaped. What narrows is which handlers the build LOWERS, and for
+every handler affected the previous outcome was a body that could not run. An
+app hitting this gains a warning and a working bundled closure in place of a
+production `ReferenceError`; the deployment shape it loses was never one it had
+in working order. Measured corpus: zero in-repo example or template handlers
+reference any of the 15.

packages/cli/src/lint/hook-body-lowering.test.ts

@@ -42,6 +42,19 @@ const forbiddenTokenHook = {
  },
 };
 
+// [#14301] A global the NODE HOST provides and the sandbox does not. Reads as
+// self-contained — `Intl` is standard in every browser and in Node — which is
+// precisely why it is the ACCIDENTAL class and not the structural one.
+const nodeOnlyGlobalHook = {
+ name: 'stamp_due_label',
+ object: 'task',
+ events: ['beforeInsert'],
+ handler: (ctx: any) => {
+ const f = new Intl.DateTimeFormat('en-US', { timeZone: 'UTC' });
+ ctx.input.due_label = f.format(new Date(ctx.input.due_at));
+ },
+};
+
 const selfContainedHook = {
  name: 'normalize_name',
  object: 'account',
@@ -91,6 +104,41 @@ describe('checkHookBodyLowering', () => {
  expect(issues[0].message).toContain('deployment shape');
  });
 
+ describe('a host global the sandbox lacks is the ACCIDENTAL class (#14301)', () => {
+ it('reports it as an ERROR under the not-lowerable rule', () => {
+ const issues = checkHookBodyLowering({ hooks: [nodeOnlyGlobalHook] });
+
+ expect(issues).toHaveLength(1);
+ expect(issues[0].severity).toBe('error');
+ expect(issues[0].rule).toBe(NOT_LOWERABLE_RULE);
+ expect(issues[0].path).toBe('hooks[0].handler');
+ expect(issues[0].message).toContain("hook 'stamp_due_label'");
+ expect(issues[0].message).toContain('Intl');
+ expect(issues[0].message).toContain('deployment shape');
+ });
+
+ it('prints the remedy that is POSSIBLE, not the inline one', () => {
+ // The wrong-remedy failure is worse than none: there is nothing to inline
+ // `Intl` from, so an author (or a code-writing model) told to inline it
+ // lands on a second broken shape. The remedy sentence is chosen from the
+ // refusal's own `nodeOnlyIdentifiers`, never re-derived here.
+ const [issue] = checkHookBodyLowering({ hooks: [nodeOnlyGlobalHook] });
+ expect(issue.message).toContain('provided by the Node host');
+ expect(issue.message).toContain('cannot be inlined');
+ expect(issue.message).toContain('string handler ref');
+ expect(issue.message).toContain('validation rule');
+ expect(issue.message).not.toContain('Inline the value(s) into the handler');
+ });
+
+ it('leaves the module-scope remedy exactly as it was', () => {
+ // The reverse leg: the #13651 sentence must not have been rewritten for
+ // every author by a branch added for one new sub-case.
+ const [issue] = checkHookBodyLowering({ hooks: [freeIdentifierHook] });
+ expect(issue.message).toContain('Inline the value(s) into the handler, or reach them through `ctx`.');
+ expect(issue.message).not.toContain('provided by the Node host');
+ });
+ });
+
  it('keeps the STRUCTURAL refusal a warning — the bundle is its designed answer', () => {
  const issues = checkHookBodyLowering({ hooks: [forbiddenTokenHook] });
 

packages/cli/src/lint/hook-body-lowering.ts

@@ -38,13 +38,22 @@
  * Today both arrive through one catch, so they share one fate. They are not
  * the same event, and the refusal kind already tells them apart:
  *
- * `free-identifiers` ACCIDENTAL. The handler IS expressible as a metadata
- * body; it merely names a module-scope const/helper/
- * import. The author wrote something that reads
+ * `free-identifiers` ACCIDENTAL. The author wrote something that reads
  * self-contained, and the platform quietly re-shaped the
  * deployment behind them — its own message even says "no
  * behavior change", which is true of behaviour and false
- * of shape. Remedy is local: inline the value. => `error`.
+ * of shape. => `error`, for both sub-cases:
+ * · a module-scope const/helper/import — remedy is
+ * local: inline the value.
+ * · a global the NODE HOST has and the sandbox does not
+ * (#14301, `Intl`) — NOT inlinable, and still
+ * accidental rather than a chosen bundle: `Intl` is a
+ * standard global in every browser and in Node, so
+ * writing it is not the recognisable "I am reaching
+ * for the host" act that `fetch(`/`process.` are.
+ * That is why it is an `error` here and not the
+ * `warning` its structural cousin gets — and why the
+ * remedy sentence below is CHOSEN per sub-case.
  * `forbidden-token` STRUCTURAL. `fetch`/`require`/`process`/`eval`/… are
  * capabilities the sandbox does not have, so the handler
  * can NEVER be a metadata body. Writing one IS choosing a
@@ -129,12 +138,37 @@ function judge(fn: AnyFn, originLabel: string, path: string): HookBodyLintIssue
  } catch (err: unknown) {
  const kind = err instanceof HookBodyExtractionError ? err.kind : 'unknown';
  const free = err instanceof HookBodyExtractionError ? err.freeIdentifiers : [];
+ // [#14301] The half of `free` the Node HOST provides and the sandbox does
+ // not. Read off the refusal rather than re-derived here: this rule's whole
+ // parity claim is that it cannot disagree with what `os build` did to the
+ // same handler, and a second membership table in this file would be exactly
+ // such a disagreement waiting to happen.
+ const nodeOnly = err instanceof HookBodyExtractionError ? err.nodeOnlyIdentifiers : [];
  // Only the first line: the refusal text carries a multi-line offending-source
  // dump for `--strict-body`'s per-callable diagnostic, which would swamp a
  // lint report. `os build --strict-body` remains the place to read it whole.
  const firstLine = String((err as Error)?.message ?? err).split('\n')[0];
 
  if (kind === 'free-identifiers') {
+ // The remedy sentence is chosen, not fixed. "Inline the value(s)" is
+ // right for a module-scope helper and IMPOSSIBLE for a host global —
+ // there is nothing to inline `Intl` from — so printing it for both would
+ // send an author (or a code-writing model) after a second broken shape.
+ const moduleScope = free.filter((n) => !nodeOnly.includes(n));
+ const hostRemedy =
+ `${nodeOnly.join(', ')} ${nodeOnly.length === 1 ? 'is' : 'are'} provided by the Node host ` +
+ `and NOT by the sandbox, so ${nodeOnly.length === 1 ? 'it' : 'they'} cannot be inlined: ` +
+ `keep the check in a string handler ref, or move it to a validation rule.`;
+ const inlineRemedy =
+ `Inline the value(s) into the handler, or reach them through \`ctx\`.`;
+ const remedy =
+ nodeOnly.length === 0
+ ? inlineRemedy
+ : moduleScope.length === 0
+ ? hostRemedy
+ : `${hostRemedy} ${moduleScope.join(', ')} ${moduleScope.length === 1 ? 'is' : 'are'} ` +
+ `module-scope: inline ${moduleScope.length === 1 ? 'it' : 'them'} into the handler, ` +
+ `or reach ${moduleScope.length === 1 ? 'it' : 'them'} through \`ctx\`.`;
  return {
  severity: 'error',
  rule: NOT_LOWERABLE_RULE,
@@ -143,8 +177,7 @@ function judge(fn: AnyFn, originLabel: string, path: string): HookBodyLintIssue
  `${free.length === 1 ? 'the identifier' : 'identifiers'} ${free.join(', ')}, which ` +
  `${free.length === 1 ? 'is' : 'are'} not in scope inside the sandbox. The handler is ` +
  `BUNDLED instead, so this app is no longer shippable as pure metadata — a change of ` +
- `deployment shape, not of behaviour. Inline the value(s) into the handler, or reach ` +
- `them through \`ctx\`. ${DELIBERATE_BUNDLE_REMEDY}`,
+ `deployment shape, not of behaviour. ${remedy} ${DELIBERATE_BUNDLE_REMEDY}`,
  path,
  };
  }

packages/cli/src/utils/detect-free-identifiers.test.ts

@@ -1,7 +1,11 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { describe, it, expect } from 'vitest';
-import { detectFreeIdentifiers } from './detect-free-identifiers.js';
+import {
+ detectFreeIdentifiers,
+ NODE_ONLY_GLOBALS,
+ SANDBOX_GLOBALS,
+} from './detect-free-identifiers.js';
 
 /** Helper: stringify a real function so we test the exact `.toString()` path. */
 const src = (fn: (...a: any[]) => any) => String(fn);
@@ -53,6 +57,14 @@ describe('detectFreeIdentifiers (#1876 — body self-containment)', () => {
  ['nested destructuring', '({ a: { b } }) => b + 1'],
  ['rest params', '(...args) => args.length'],
  ['typeof a local', '(ctx) => { const v = ctx.v; return typeof v; }'],
+ // #14301 — the node-only refusal is a SCOPE analysis, not a token scan.
+ // A locally-bound name that happens to spell a host global is bound, and
+ // a member NAMED after one is not a reference at all. Both would be
+ // false refusals, and a false refusal here costs an author a body they
+ // were entitled to.
+ ['a local shadowing a host global', '(ctx) => { const Intl = ctx.fmt; return Intl.format(ctx.d); }'],
+ ['a member named after a host global', '(ctx) => { return ctx.Intl.format(ctx.d); }'],
+ ['a param named after a host global', '(ctx, Intl) => Intl.format(ctx.d)'],
  ];
  for (const [label, source] of selfContained) {
  it(label, () => {
@@ -81,4 +93,79 @@ describe('detectFreeIdentifiers (#1876 — body self-containment)', () => {
  expect(detectFreeIdentifiers('').free).toEqual([]);
  expect(detectFreeIdentifiers('{ not: valid').free).toEqual([]);
  });
+ // ── #14301 — globals the NODE HOST has and the sandbox does not ──────────
+ //
+ // The reported shape: `Intl` sat in one generous allowlist beside `JSON`, so
+ // a handler calling `Intl.DateTimeFormat` had no free identifier, lowered
+ // into `body.source`, and threw `ReferenceError` in production while every
+ // local gate was green. The split makes the reference visible again; the
+ // membership of the two sets is not asserted here from knowledge — it is
+ // measured inside the real sandbox by `sandbox-globals-probe.test.ts`.
+ describe('reports host globals the sandbox does not provide', () => {
+ it('the card reproduction — Intl.DateTimeFormat', () => {
+ const r = detectFreeIdentifiers(
+ "(ctx) => { const f = new Intl.DateTimeFormat('en-US'); ctx.input.label = f.format(new Date(ctx.input.at)); }",
+ );
+ expect(r.unparsed).toBe(false);
+ expect(r.free).toEqual(['Intl']);
+ expect(r.nodeOnly).toEqual(['Intl']);
+ });
+
+ it('`nodeOnly` is a labelled SUBSET of `free`, not a second list', () => {
+ // Both halves at once. The caller needs them apart because the remedies
+ // are opposite — inline the helper, but a host global cannot be inlined
+ // — and needs them together because the refusal names every name.
+ const r = detectFreeIdentifiers('(ctx) => { ctx.x = slugify(ctx.name) + Intl.NumberFormat; }');
+ expect(r.free).toEqual(['Intl', 'slugify']);
+ expect(r.nodeOnly).toEqual(['Intl']);
+ expect(r.nodeOnly.every((n) => r.free.includes(n))).toBe(true);
+ });
+
+ it('a sandbox-provided global is still waived — the positive control', () => {
+ const r = detectFreeIdentifiers('(ctx) => { ctx.x = JSON.stringify(Math.round(ctx.n)); }');
+ expect(r.free).toEqual([]);
+ expect(r.nodeOnly).toEqual([]);
+ });
+
+ it('every member of NODE_ONLY_GLOBALS is reported when referenced free', () => {
+ // Set-wide rather than per-name: a member added to the set without the
+ // detector reading it would otherwise sit inert, which is the exact
+ // shape of the defect being closed one level up.
+ for (const name of NODE_ONLY_GLOBALS) {
+ const r = detectFreeIdentifiers(`(ctx) => { ctx.x = ${name}; }`);
+ expect({ name, free: r.free, nodeOnly: r.nodeOnly }).toEqual({
+ name,
+ free: [name],
+ nodeOnly: [name],
+ });
+ }
+ });
+
+ it('every member of SANDBOX_GLOBALS is waived when referenced free', () => {
+ for (const name of SANDBOX_GLOBALS) {
+ const r = detectFreeIdentifiers(`(ctx) => { ctx.x = ${name}; }`);
+ expect({ name, free: r.free, nodeOnly: r.nodeOnly }).toEqual({
+ name,
+ free: [],
+ nodeOnly: [],
+ });
+ }
+ });
+
+ it('junk input reports neither list (conservative — never blocks extraction)', () => {
+ // The bias the file's header states, restated over the NEW field: a
+ // source this analysis cannot make sense of must not produce a refusal.
+ // Asserted over the same three junk shapes the #1876 case uses, and
+ // without asserting `unparsed` — TS error-recovery decides that, and the
+ // invariant that matters is that neither list fills.
+ for (const junk of ['this is not a function', '', '{ not: valid']) {
+ const r = detectFreeIdentifiers(junk);
+ expect({ junk, free: r.free, nodeOnly: r.nodeOnly }).toEqual({
+ junk,
+ free: [],
+ nodeOnly: [],
+ });
+ }
+ });
+ });
 });

.changeset/hook-body-sandbox-globals-allowlist.md

@@ -0,0 +1,64 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): stop lowering hook/action bodies that reference globals the sandbox does not provide (#14301)
+
+`detect-free-identifiers`' ambient allowlist was ONE generous list, documented as
+"assume the runtime has it". The runtime a lowered body actually runs in is the
+QuickJS sandbox, not the Node process that runs `objectstack build` — and the
+list named `Intl` beside `JSON`, under the comment "Web-ish that the sandbox /
+Node commonly provide". So a handler calling `Intl.DateTimeFormat` had no free
+identifier at all: `extractHookBody` lowered it into `body.source`, the #13651
+lint rule had nothing to report (it fires only on a *refused* lowering),
+`validate` / `typecheck` / `test` / `build` were all green because the
+in-process test runs the RAW function in Node where `Intl` exists — and
+production threw `ReferenceError: Intl is not defined`. Under the
+`onError: 'abort'` a validation-shaped hook must declare, that refuses every
+write to the object.
+
+The allowlist is now two sets, and membership is **measured**, never recalled: a
+`typeof X`/`'X' in globalThis` probe is evaluated inside the same
+`QuickJSScriptRunner` the runtime evaluates a body in, and
+`sandbox-globals-probe.test.ts` fails unless each set is exactly the probe's
+present/absent partition.
+
+- **`SANDBOX_GLOBALS` (53, measured present)** — the ECMAScript surface:
+ `Math` `JSON` `Date` `Object` `Array` `String` `Number` `Boolean` `RegExp`
+ `Map` `Set` `WeakMap` `WeakSet` `Promise` `Symbol` `BigInt` `Function`
+ `Reflect` `Proxy`, the typed-array/buffer family, the eight error
+ constructors, `parseInt` `parseFloat` `isNaN` `isFinite` and the four URI
+ functions, plus `undefined` `NaN` `Infinity` `globalThis`.
+- **`NODE_ONLY_GLOBALS` (15, measured absent)** — `Intl`, `structuredClone`,
+ `queueMicrotask`, `atob`, `btoa`, `setTimeout`, `clearTimeout`,
+ `setInterval`, `clearInterval`, `URL`, `URLSearchParams`, `TextEncoder`,
+ `TextDecoder`, `console`, `arguments`.
+
+A free reference to one of the 15 is now a lowering refusal whose reason names
+the identifier and the remedy — a string handler ref (`functions:` map plus
+`handler: 'fn_name'`) or a validation rule, and for `console` specifically the
+capability-gated `ctx.log`. It travels the SAME path #1876 already used: the
+refusal is `kind: 'free-identifiers'` with the host-only half carried
+separately as `nodeOnlyIdentifiers`, `lowerCallables` catches it and ships the
+callable through the `.mjs` bundle (where it runs in-process in Node and
+works), `os build` still exits 0 with a warning, and `os lint` reports it under
+`hook-body/not-lowerable` as an `error` — the ACCIDENTAL class, because `Intl`
+is a standard global in every browser and in Node and writing it is not the
+recognisable "I am reaching for the host" act that `fetch(` and `process.` are.
+The remedy sentence `os lint` prints is chosen from the refusal's own
+classification: "inline the value" is impossible for a host global, and
+printing it anyway would send an author after a second broken shape.
+
+⛔ Not changed here: whether `os build` fails on the lowering class (#13838),
+and what the sandbox provides (giving it `Intl` would be a capability
+expansion). Nothing under `packages/runtime/**` is touched — the probe reads
+that sandbox, it does not change it.
+
+**Why `patch`.** No published accept-set moves: the metadata a valid app may
+declare is identical, `HookBodySchema` is untouched, and no key is added,
+removed or re-shaped. What narrows is which handlers the build LOWERS, and for
+every handler affected the previous outcome was a body that could not run. An
+app hitting this gains a warning and a working bundled closure in place of a
+production `ReferenceError`; the deployment shape it loses was never one it had
+in working order. Measured corpus: zero in-repo example or template handlers
+reference any of the 15.

packages/cli/src/lint/hook-body-lowering.test.ts

@@ -42,6 +42,19 @@ const forbiddenTokenHook = {
  },
 };
 
+// [#14301] A global the NODE HOST provides and the sandbox does not. Reads as
+// self-contained — `Intl` is standard in every browser and in Node — which is
+// precisely why it is the ACCIDENTAL class and not the structural one.
+const nodeOnlyGlobalHook = {
+ name: 'stamp_due_label',
+ object: 'task',
+ events: ['beforeInsert'],
+ handler: (ctx: any) => {
+ const f = new Intl.DateTimeFormat('en-US', { timeZone: 'UTC' });
+ ctx.input.due_label = f.format(new Date(ctx.input.due_at));
+ },
+};
+
 const selfContainedHook = {
  name: 'normalize_name',
  object: 'account',
@@ -91,6 +104,41 @@ describe('checkHookBodyLowering', () => {
  expect(issues[0].message).toContain('deployment shape');
  });
 
+ describe('a host global the sandbox lacks is the ACCIDENTAL class (#14301)', () => {
+ it('reports it as an ERROR under the not-lowerable rule', () => {
+ const issues = checkHookBodyLowering({ hooks: [nodeOnlyGlobalHook] });
+
+ expect(issues).toHaveLength(1);
+ expect(issues[0].severity).toBe('error');
+ expect(issues[0].rule).toBe(NOT_LOWERABLE_RULE);
+ expect(issues[0].path).toBe('hooks[0].handler');
+ expect(issues[0].message).toContain("hook 'stamp_due_label'");
+ expect(issues[0].message).toContain('Intl');
+ expect(issues[0].message).toContain('deployment shape');
+ });
+
+ it('prints the remedy that is POSSIBLE, not the inline one', () => {
+ // The wrong-remedy failure is worse than none: there is nothing to inline
+ // `Intl` from, so an author (or a code-writing model) told to inline it
+ // lands on a second broken shape. The remedy sentence is chosen from the
+ // refusal's own `nodeOnlyIdentifiers`, never re-derived here.
+ const [issue] = checkHookBodyLowering({ hooks: [nodeOnlyGlobalHook] });
+ expect(issue.message).toContain('provided by the Node host');
+ expect(issue.message).toContain('cannot be inlined');
+ expect(issue.message).toContain('string handler ref');
+ expect(issue.message).toContain('validation rule');
+ expect(issue.message).not.toContain('Inline the value(s) into the handler');
+ });
+
+ it('leaves the module-scope remedy exactly as it was', () => {
+ // The reverse leg: the #13651 sentence must not have been rewritten for
+ // every author by a branch added for one new sub-case.
+ const [issue] = checkHookBodyLowering({ hooks: [freeIdentifierHook] });
+ expect(issue.message).toContain('Inline the value(s) into the handler, or reach them through `ctx`.');
+ expect(issue.message).not.toContain('provided by the Node host');
+ });
+ });
+
  it('keeps the STRUCTURAL refusal a warning — the bundle is its designed answer', () => {
  const issues = checkHookBodyLowering({ hooks: [forbiddenTokenHook] });
 

packages/cli/src/lint/hook-body-lowering.ts

@@ -38,13 +38,22 @@
  * Today both arrive through one catch, so they share one fate. They are not
  * the same event, and the refusal kind already tells them apart:
  *
- * `free-identifiers` ACCIDENTAL. The handler IS expressible as a metadata
- * body; it merely names a module-scope const/helper/
- * import. The author wrote something that reads
+ * `free-identifiers` ACCIDENTAL. The author wrote something that reads
  * self-contained, and the platform quietly re-shaped the
  * deployment behind them — its own message even says "no
  * behavior change", which is true of behaviour and false
- * of shape. Remedy is local: inline the value. => `error`.
+ * of shape. => `error`, for both sub-cases:
+ * · a module-scope const/helper/import — remedy is
+ * local: inline the value.
+ * · a global the NODE HOST has and the sandbox does not
+ * (#14301, `Intl`) — NOT inlinable, and still
+ * accidental rather than a chosen bundle: `Intl` is a
+ * standard global in every browser and in Node, so
+ * writing it is not the recognisable "I am reaching
+ * for the host" act that `fetch(`/`process.` are.
+ * That is why it is an `error` here and not the
+ * `warning` its structural cousin gets — and why the
+ * remedy sentence below is CHOSEN per sub-case.
  * `forbidden-token` STRUCTURAL. `fetch`/`require`/`process`/`eval`/… are
  * capabilities the sandbox does not have, so the handler
  * can NEVER be a metadata body. Writing one IS choosing a
@@ -129,12 +138,37 @@ function judge(fn: AnyFn, originLabel: string, path: string): HookBodyLintIssue
  } catch (err: unknown) {
  const kind = err instanceof HookBodyExtractionError ? err.kind : 'unknown';
  const free = err instanceof HookBodyExtractionError ? err.freeIdentifiers : [];
+ // [#14301] The half of `free` the Node HOST provides and the sandbox does
+ // not. Read off the refusal rather than re-derived here: this rule's whole
+ // parity claim is that it cannot disagree with what `os build` did to the
+ // same handler, and a second membership table in this file would be exactly
+ // such a disagreement waiting to happen.
+ const nodeOnly = err instanceof HookBodyExtractionError ? err.nodeOnlyIdentifiers : [];
  // Only the first line: the refusal text carries a multi-line offending-source
  // dump for `--strict-body`'s per-callable diagnostic, which would swamp a
  // lint report. `os build --strict-body` remains the place to read it whole.
  const firstLine = String((err as Error)?.message ?? err).split('\n')[0];
 
  if (kind === 'free-identifiers') {
+ // The remedy sentence is chosen, not fixed. "Inline the value(s)" is
+ // right for a module-scope helper and IMPOSSIBLE for a host global —
+ // there is nothing to inline `Intl` from — so printing it for both would
+ // send an author (or a code-writing model) after a second broken shape.
+ const moduleScope = free.filter((n) => !nodeOnly.includes(n));
+ const hostRemedy =
+ `${nodeOnly.join(', ')} ${nodeOnly.length === 1 ? 'is' : 'are'} provided by the Node host ` +
+ `and NOT by the sandbox, so ${nodeOnly.length === 1 ? 'it' : 'they'} cannot be inlined: ` +
+ `keep the check in a string handler ref, or move it to a validation rule.`;
+ const inlineRemedy =
+ `Inline the value(s) into the handler, or reach them through \`ctx\`.`;
+ const remedy =
+ nodeOnly.length === 0
+ ? inlineRemedy
+ : moduleScope.length === 0
+ ? hostRemedy
+ : `${hostRemedy} ${moduleScope.join(', ')} ${moduleScope.length === 1 ? 'is' : 'are'} ` +
+ `module-scope: inline ${moduleScope.length === 1 ? 'it' : 'them'} into the handler, ` +
+ `or reach ${moduleScope.length === 1 ? 'it' : 'them'} through \`ctx\`.`;
  return {
  severity: 'error',
  rule: NOT_LOWERABLE_RULE,
@@ -143,8 +177,7 @@ function judge(fn: AnyFn, originLabel: string, path: string): HookBodyLintIssue
  `${free.length === 1 ? 'the identifier' : 'identifiers'} ${free.join(', ')}, which ` +
  `${free.length === 1 ? 'is' : 'are'} not in scope inside the sandbox. The handler is ` +
  `BUNDLED instead, so this app is no longer shippable as pure metadata — a change of ` +
- `deployment shape, not of behaviour. Inline the value(s) into the handler, or reach ` +
- `them through \`ctx\`. ${DELIBERATE_BUNDLE_REMEDY}`,
+ `deployment shape, not of behaviour. ${remedy} ${DELIBERATE_BUNDLE_REMEDY}`,
  path,
  };
  }

packages/cli/src/utils/detect-free-identifiers.test.ts

@@ -1,7 +1,11 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { describe, it, expect } from 'vitest';
-import { detectFreeIdentifiers } from './detect-free-identifiers.js';
+import {
+ detectFreeIdentifiers,
+ NODE_ONLY_GLOBALS,
+ SANDBOX_GLOBALS,
+} from './detect-free-identifiers.js';
 
 /** Helper: stringify a real function so we test the exact `.toString()` path. */
 const src = (fn: (...a: any[]) => any) => String(fn);
@@ -53,6 +57,14 @@ describe('detectFreeIdentifiers (#1876 — body self-containment)', () => {
  ['nested destructuring', '({ a: { b } }) => b + 1'],
  ['rest params', '(...args) => args.length'],
  ['typeof a local', '(ctx) => { const v = ctx.v; return typeof v; }'],
+ // #14301 — the node-only refusal is a SCOPE analysis, not a token scan.
+ // A locally-bound name that happens to spell a host global is bound, and
+ // a member NAMED after one is not a reference at all. Both would be
+ // false refusals, and a false refusal here costs an author a body they
+ // were entitled to.
+ ['a local shadowing a host global', '(ctx) => { const Intl = ctx.fmt; return Intl.format(ctx.d); }'],
+ ['a member named after a host global', '(ctx) => { return ctx.Intl.format(ctx.d); }'],
+ ['a param named after a host global', '(ctx, Intl) => Intl.format(ctx.d)'],
  ];
  for (const [label, source] of selfContained) {
  it(label, () => {
@@ -81,4 +93,79 @@ describe('detectFreeIdentifiers (#1876 — body self-containment)', () => {
  expect(detectFreeIdentifiers('').free).toEqual([]);
  expect(detectFreeIdentifiers('{ not: valid').free).toEqual([]);
  });
+ // ── #14301 — globals the NODE HOST has and the sandbox does not ──────────
+ //
+ // The reported shape: `Intl` sat in one generous allowlist beside `JSON`, so
+ // a handler calling `Intl.DateTimeFormat` had no free identifier, lowered
+ // into `body.source`, and threw `ReferenceError` in production while every
+ // local gate was green. The split makes the reference visible again; the
+ // membership of the two sets is not asserted here from knowledge — it is
+ // measured inside the real sandbox by `sandbox-globals-probe.test.ts`.
+ describe('reports host globals the sandbox does not provide', () => {
+ it('the card reproduction — Intl.DateTimeFormat', () => {
+ const r = detectFreeIdentifiers(
+ "(ctx) => { const f = new Intl.DateTimeFormat('en-US'); ctx.input.label = f.format(new Date(ctx.input.at)); }",
+ );
+ expect(r.unparsed).toBe(false);
+ expect(r.free).toEqual(['Intl']);
+ expect(r.nodeOnly).toEqual(['Intl']);
+ });
+
+ it('`nodeOnly` is a labelled SUBSET of `free`, not a second list', () => {
+ // Both halves at once. The caller needs them apart because the remedies
+ // are opposite — inline the helper, but a host global cannot be inlined
+ // — and needs them together because the refusal names every name.
+ const r = detectFreeIdentifiers('(ctx) => { ctx.x = slugify(ctx.name) + Intl.NumberFormat; }');
+ expect(r.free).toEqual(['Intl', 'slugify']);
+ expect(r.nodeOnly).toEqual(['Intl']);
+ expect(r.nodeOnly.every((n) => r.free.includes(n))).toBe(true);
+ });
+
+ it('a sandbox-provided global is still waived — the positive control', () => {
+ const r = detectFreeIdentifiers('(ctx) => { ctx.x = JSON.stringify(Math.round(ctx.n)); }');
+ expect(r.free).toEqual([]);
+ expect(r.nodeOnly).toEqual([]);
+ });
+
+ it('every member of NODE_ONLY_GLOBALS is reported when referenced free', () => {
+ // Set-wide rather than per-name: a member added to the set without the
+ // detector reading it would otherwise sit inert, which is the exact
+ // shape of the defect being closed one level up.
+ for (const name of NODE_ONLY_GLOBALS) {
+ const r = detectFreeIdentifiers(`(ctx) => { ctx.x = ${name}; }`);
+ expect({ name, free: r.free, nodeOnly: r.nodeOnly }).toEqual({
+ name,
+ free: [name],
+ nodeOnly: [name],
+ });
+ }
+ });
+
+ it('every member of SANDBOX_GLOBALS is waived when referenced free', () => {
+ for (const name of SANDBOX_GLOBALS) {
+ const r = detectFreeIdentifiers(`(ctx) => { ctx.x = ${name}; }`);
+ expect({ name, free: r.free, nodeOnly: r.nodeOnly }).toEqual({
+ name,
+ free: [],
+ nodeOnly: [],
+ });
+ }
+ });
+
+ it('junk input reports neither list (conservative — never blocks extraction)', () => {
+ // The bias the file's header states, restated over the NEW field: a
+ // source this analysis cannot make sense of must not produce a refusal.
+ // Asserted over the same three junk shapes the #1876 case uses, and
+ // without asserting `unparsed` — TS error-recovery decides that, and the
+ // invariant that matters is that neither list fills.
+ for (const junk of ['this is not a function', '', '{ not: valid']) {
+ const r = detectFreeIdentifiers(junk);
+ expect({ junk, free: r.free, nodeOnly: r.nodeOnly }).toEqual({
+ junk,
+ free: [],
+ nodeOnly: [],
+ });
+ }
+ });
+ });
 });

.changeset/hook-body-sandbox-globals-allowlist.md

@@ -0,0 +1,64 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): stop lowering hook/action bodies that reference globals the sandbox does not provide (#14301)
+
+`detect-free-identifiers`' ambient allowlist was ONE generous list, documented as
+"assume the runtime has it". The runtime a lowered body actually runs in is the
+QuickJS sandbox, not the Node process that runs `objectstack build` — and the
+list named `Intl` beside `JSON`, under the comment "Web-ish that the sandbox /
+Node commonly provide". So a handler calling `Intl.DateTimeFormat` had no free
+identifier at all: `extractHookBody` lowered it into `body.source`, the #13651
+lint rule had nothing to report (it fires only on a *refused* lowering),
+`validate` / `typecheck` / `test` / `build` were all green because the
+in-process test runs the RAW function in Node where `Intl` exists — and
+production threw `ReferenceError: Intl is not defined`. Under the
+`onError: 'abort'` a validation-shaped hook must declare, that refuses every
+write to the object.
+
+The allowlist is now two sets, and membership is **measured**, never recalled: a
+`typeof X`/`'X' in globalThis` probe is evaluated inside the same
+`QuickJSScriptRunner` the runtime evaluates a body in, and
+`sandbox-globals-probe.test.ts` fails unless each set is exactly the probe's
+present/absent partition.
+
+- **`SANDBOX_GLOBALS` (53, measured present)** — the ECMAScript surface:
+ `Math` `JSON` `Date` `Object` `Array` `String` `Number` `Boolean` `RegExp`
+ `Map` `Set` `WeakMap` `WeakSet` `Promise` `Symbol` `BigInt` `Function`
+ `Reflect` `Proxy`, the typed-array/buffer family, the eight error
+ constructors, `parseInt` `parseFloat` `isNaN` `isFinite` and the four URI
+ functions, plus `undefined` `NaN` `Infinity` `globalThis`.
+- **`NODE_ONLY_GLOBALS` (15, measured absent)** — `Intl`, `structuredClone`,
+ `queueMicrotask`, `atob`, `btoa`, `setTimeout`, `clearTimeout`,
+ `setInterval`, `clearInterval`, `URL`, `URLSearchParams`, `TextEncoder`,
+ `TextDecoder`, `console`, `arguments`.
+
+A free reference to one of the 15 is now a lowering refusal whose reason names
+the identifier and the remedy — a string handler ref (`functions:` map plus
+`handler: 'fn_name'`) or a validation rule, and for `console` specifically the
+capability-gated `ctx.log`. It travels the SAME path #1876 already used: the
+refusal is `kind: 'free-identifiers'` with the host-only half carried
+separately as `nodeOnlyIdentifiers`, `lowerCallables` catches it and ships the
+callable through the `.mjs` bundle (where it runs in-process in Node and
+works), `os build` still exits 0 with a warning, and `os lint` reports it under
+`hook-body/not-lowerable` as an `error` — the ACCIDENTAL class, because `Intl`
+is a standard global in every browser and in Node and writing it is not the
+recognisable "I am reaching for the host" act that `fetch(` and `process.` are.
+The remedy sentence `os lint` prints is chosen from the refusal's own
+classification: "inline the value" is impossible for a host global, and
+printing it anyway would send an author after a second broken shape.
+
+⛔ Not changed here: whether `os build` fails on the lowering class (#13838),
+and what the sandbox provides (giving it `Intl` would be a capability
+expansion). Nothing under `packages/runtime/**` is touched — the probe reads
+that sandbox, it does not change it.
+
+**Why `patch`.** No published accept-set moves: the metadata a valid app may
+declare is identical, `HookBodySchema` is untouched, and no key is added,
+removed or re-shaped. What narrows is which handlers the build LOWERS, and for
+every handler affected the previous outcome was a body that could not run. An
+app hitting this gains a warning and a working bundled closure in place of a
+production `ReferenceError`; the deployment shape it loses was never one it had
+in working order. Measured corpus: zero in-repo example or template handlers
+reference any of the 15.

packages/cli/src/lint/hook-body-lowering.test.ts

@@ -42,6 +42,19 @@ const forbiddenTokenHook = {
  },
 };
 
+// [#14301] A global the NODE HOST provides and the sandbox does not. Reads as
+// self-contained — `Intl` is standard in every browser and in Node — which is
+// precisely why it is the ACCIDENTAL class and not the structural one.
+const nodeOnlyGlobalHook = {
+ name: 'stamp_due_label',
+ object: 'task',
+ events: ['beforeInsert'],
+ handler: (ctx: any) => {
+ const f = new Intl.DateTimeFormat('en-US', { timeZone: 'UTC' });
+ ctx.input.due_label = f.format(new Date(ctx.input.due_at));
+ },
+};
+
 const selfContainedHook = {
  name: 'normalize_name',
  object: 'account',
@@ -91,6 +104,41 @@ describe('checkHookBodyLowering', () => {
  expect(issues[0].message).toContain('deployment shape');
  });
 
+ describe('a host global the sandbox lacks is the ACCIDENTAL class (#14301)', () => {
+ it('reports it as an ERROR under the not-lowerable rule', () => {
+ const issues = checkHookBodyLowering({ hooks: [nodeOnlyGlobalHook] });
+
+ expect(issues).toHaveLength(1);
+ expect(issues[0].severity).toBe('error');
+ expect(issues[0].rule).toBe(NOT_LOWERABLE_RULE);
+ expect(issues[0].path).toBe('hooks[0].handler');
+ expect(issues[0].message).toContain("hook 'stamp_due_label'");
+ expect(issues[0].message).toContain('Intl');
+ expect(issues[0].message).toContain('deployment shape');
+ });
+
+ it('prints the remedy that is POSSIBLE, not the inline one', () => {
+ // The wrong-remedy failure is worse than none: there is nothing to inline
+ // `Intl` from, so an author (or a code-writing model) told to inline it
+ // lands on a second broken shape. The remedy sentence is chosen from the
+ // refusal's own `nodeOnlyIdentifiers`, never re-derived here.
+ const [issue] = checkHookBodyLowering({ hooks: [nodeOnlyGlobalHook] });
+ expect(issue.message).toContain('provided by the Node host');
+ expect(issue.message).toContain('cannot be inlined');
+ expect(issue.message).toContain('string handler ref');
+ expect(issue.message).toContain('validation rule');
+ expect(issue.message).not.toContain('Inline the value(s) into the handler');
+ });
+
+ it('leaves the module-scope remedy exactly as it was', () => {
+ // The reverse leg: the #13651 sentence must not have been rewritten for
+ // every author by a branch added for one new sub-case.
+ const [issue] = checkHookBodyLowering({ hooks: [freeIdentifierHook] });
+ expect(issue.message).toContain('Inline the value(s) into the handler, or reach them through `ctx`.');
+ expect(issue.message).not.toContain('provided by the Node host');
+ });
+ });
+
  it('keeps the STRUCTURAL refusal a warning — the bundle is its designed answer', () => {
  const issues = checkHookBodyLowering({ hooks: [forbiddenTokenHook] });
 

packages/cli/src/lint/hook-body-lowering.ts

@@ -38,13 +38,22 @@
  * Today both arrive through one catch, so they share one fate. They are not
  * the same event, and the refusal kind already tells them apart:
  *
- * `free-identifiers` ACCIDENTAL. The handler IS expressible as a metadata
- * body; it merely names a module-scope const/helper/
- * import. The author wrote something that reads
+ * `free-identifiers` ACCIDENTAL. The author wrote something that reads
  * self-contained, and the platform quietly re-shaped the
  * deployment behind them — its own message even says "no
  * behavior change", which is true of behaviour and false
- * of shape. Remedy is local: inline the value. => `error`.
+ * of shape. => `error`, for both sub-cases:
+ * · a module-scope const/helper/import — remedy is
+ * local: inline the value.
+ * · a global the NODE HOST has and the sandbox does not
+ * (#14301, `Intl`) — NOT inlinable, and still
+ * accidental rather than a chosen bundle: `Intl` is a
+ * standard global in every browser and in Node, so
+ * writing it is not the recognisable "I am reaching
+ * for the host" act that `fetch(`/`process.` are.
+ * That is why it is an `error` here and not the
+ * `warning` its structural cousin gets — and why the
+ * remedy sentence below is CHOSEN per sub-case.
  * `forbidden-token` STRUCTURAL. `fetch`/`require`/`process`/`eval`/… are
  * capabilities the sandbox does not have, so the handler
  * can NEVER be a metadata body. Writing one IS choosing a
@@ -129,12 +138,37 @@ function judge(fn: AnyFn, originLabel: string, path: string): HookBodyLintIssue
  } catch (err: unknown) {
  const kind = err instanceof HookBodyExtractionError ? err.kind : 'unknown';
  const free = err instanceof HookBodyExtractionError ? err.freeIdentifiers : [];
+ // [#14301] The half of `free` the Node HOST provides and the sandbox does
+ // not. Read off the refusal rather than re-derived here: this rule's whole
+ // parity claim is that it cannot disagree with what `os build` did to the
+ // same handler, and a second membership table in this file would be exactly
+ // such a disagreement waiting to happen.
+ const nodeOnly = err instanceof HookBodyExtractionError ? err.nodeOnlyIdentifiers : [];
  // Only the first line: the refusal text carries a multi-line offending-source
  // dump for `--strict-body`'s per-callable diagnostic, which would swamp a
  // lint report. `os build --strict-body` remains the place to read it whole.
  const firstLine = String((err as Error)?.message ?? err).split('\n')[0];
 
  if (kind === 'free-identifiers') {
+ // The remedy sentence is chosen, not fixed. "Inline the value(s)" is
+ // right for a module-scope helper and IMPOSSIBLE for a host global —
+ // there is nothing to inline `Intl` from — so printing it for both would
+ // send an author (or a code-writing model) after a second broken shape.
+ const moduleScope = free.filter((n) => !nodeOnly.includes(n));
+ const hostRemedy =
+ `${nodeOnly.join(', ')} ${nodeOnly.length === 1 ? 'is' : 'are'} provided by the Node host ` +
+ `and NOT by the sandbox, so ${nodeOnly.length === 1 ? 'it' : 'they'} cannot be inlined: ` +
+ `keep the check in a string handler ref, or move it to a validation rule.`;
+ const inlineRemedy =
+ `Inline the value(s) into the handler, or reach them through \`ctx\`.`;
+ const remedy =
+ nodeOnly.length === 0
+ ? inlineRemedy
+ : moduleScope.length === 0
+ ? hostRemedy
+ : `${hostRemedy} ${moduleScope.join(', ')} ${moduleScope.length === 1 ? 'is' : 'are'} ` +
+ `module-scope: inline ${moduleScope.length === 1 ? 'it' : 'them'} into the handler, ` +
+ `or reach ${moduleScope.length === 1 ? 'it' : 'them'} through \`ctx\`.`;
  return {
  severity: 'error',
  rule: NOT_LOWERABLE_RULE,
@@ -143,8 +177,7 @@ function judge(fn: AnyFn, originLabel: string, path: string): HookBodyLintIssue
  `${free.length === 1 ? 'the identifier' : 'identifiers'} ${free.join(', ')}, which ` +
  `${free.length === 1 ? 'is' : 'are'} not in scope inside the sandbox. The handler is ` +
  `BUNDLED instead, so this app is no longer shippable as pure metadata — a change of ` +
- `deployment shape, not of behaviour. Inline the value(s) into the handler, or reach ` +
- `them through \`ctx\`. ${DELIBERATE_BUNDLE_REMEDY}`,
+ `deployment shape, not of behaviour. ${remedy} ${DELIBERATE_BUNDLE_REMEDY}`,
  path,
  };
  }

packages/cli/src/utils/detect-free-identifiers.test.ts

@@ -1,7 +1,11 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { describe, it, expect } from 'vitest';
-import { detectFreeIdentifiers } from './detect-free-identifiers.js';
+import {
+ detectFreeIdentifiers,
+ NODE_ONLY_GLOBALS,
+ SANDBOX_GLOBALS,
+} from './detect-free-identifiers.js';
 
 /** Helper: stringify a real function so we test the exact `.toString()` path. */
 const src = (fn: (...a: any[]) => any) => String(fn);
@@ -53,6 +57,14 @@ describe('detectFreeIdentifiers (#1876 — body self-containment)', () => {
  ['nested destructuring', '({ a: { b } }) => b + 1'],
  ['rest params', '(...args) => args.length'],
  ['typeof a local', '(ctx) => { const v = ctx.v; return typeof v; }'],
+ // #14301 — the node-only refusal is a SCOPE analysis, not a token scan.
+ // A locally-bound name that happens to spell a host global is bound, and
+ // a member NAMED after one is not a reference at all. Both would be
+ // false refusals, and a false refusal here costs an author a body they
+ // were entitled to.
+ ['a local shadowing a host global', '(ctx) => { const Intl = ctx.fmt; return Intl.format(ctx.d); }'],
+ ['a member named after a host global', '(ctx) => { return ctx.Intl.format(ctx.d); }'],
+ ['a param named after a host global', '(ctx, Intl) => Intl.format(ctx.d)'],
  ];
  for (const [label, source] of selfContained) {
  it(label, () => {
@@ -81,4 +93,79 @@ describe('detectFreeIdentifiers (#1876 — body self-containment)', () => {
  expect(detectFreeIdentifiers('').free).toEqual([]);
  expect(detectFreeIdentifiers('{ not: valid').free).toEqual([]);
  });
+ // ── #14301 — globals the NODE HOST has and the sandbox does not ──────────
+ //
+ // The reported shape: `Intl` sat in one generous allowlist beside `JSON`, so
+ // a handler calling `Intl.DateTimeFormat` had no free identifier, lowered
+ // into `body.source`, and threw `ReferenceError` in production while every
+ // local gate was green. The split makes the reference visible again; the
+ // membership of the two sets is not asserted here from knowledge — it is
+ // measured inside the real sandbox by `sandbox-globals-probe.test.ts`.
+ describe('reports host globals the sandbox does not provide', () => {
+ it('the card reproduction — Intl.DateTimeFormat', () => {
+ const r = detectFreeIdentifiers(
+ "(ctx) => { const f = new Intl.DateTimeFormat('en-US'); ctx.input.label = f.format(new Date(ctx.input.at)); }",
+ );
+ expect(r.unparsed).toBe(false);
+ expect(r.free).toEqual(['Intl']);
+ expect(r.nodeOnly).toEqual(['Intl']);
+ });
+
+ it('`nodeOnly` is a labelled SUBSET of `free`, not a second list', () => {
+ // Both halves at once. The caller needs them apart because the remedies
+ // are opposite — inline the helper, but a host global cannot be inlined
+ // — and needs them together because the refusal names every name.
+ const r = detectFreeIdentifiers('(ctx) => { ctx.x = slugify(ctx.name) + Intl.NumberFormat; }');
+ expect(r.free).toEqual(['Intl', 'slugify']);
+ expect(r.nodeOnly).toEqual(['Intl']);
+ expect(r.nodeOnly.every((n) => r.free.includes(n))).toBe(true);
+ });
+
+ it('a sandbox-provided global is still waived — the positive control', () => {
+ const r = detectFreeIdentifiers('(ctx) => { ctx.x = JSON.stringify(Math.round(ctx.n)); }');
+ expect(r.free).toEqual([]);
+ expect(r.nodeOnly).toEqual([]);
+ });
+
+ it('every member of NODE_ONLY_GLOBALS is reported when referenced free', () => {
+ // Set-wide rather than per-name: a member added to the set without the
+ // detector reading it would otherwise sit inert, which is the exact
+ // shape of the defect being closed one level up.
+ for (const name of NODE_ONLY_GLOBALS) {
+ const r = detectFreeIdentifiers(`(ctx) => { ctx.x = ${name}; }`);
+ expect({ name, free: r.free, nodeOnly: r.nodeOnly }).toEqual({
+ name,
+ free: [name],
+ nodeOnly: [name],
+ });
+ }
+ });
+
+ it('every member of SANDBOX_GLOBALS is waived when referenced free', () => {
+ for (const name of SANDBOX_GLOBALS) {
+ const r = detectFreeIdentifiers(`(ctx) => { ctx.x = ${name}; }`);
+ expect({ name, free: r.free, nodeOnly: r.nodeOnly }).toEqual({
+ name,
+ free: [],
+ nodeOnly: [],
+ });
+ }
+ });
+
+ it('junk input reports neither list (conservative — never blocks extraction)', () => {
+ // The bias the file's header states, restated over the NEW field: a
+ // source this analysis cannot make sense of must not produce a refusal.
+ // Asserted over the same three junk shapes the #1876 case uses, and
+ // without asserting `unparsed` — TS error-recovery decides that, and the
+ // invariant that matters is that neither list fills.
+ for (const junk of ['this is not a function', '', '{ not: valid']) {
+ const r = detectFreeIdentifiers(junk);
+ expect({ junk, free: r.free, nodeOnly: r.nodeOnly }).toEqual({
+ junk,
+ free: [],
+ nodeOnly: [],
+ });
+ }
+ });
+ });
 });

.changeset/hook-body-sandbox-globals-allowlist.md

@@ -0,0 +1,64 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): stop lowering hook/action bodies that reference globals the sandbox does not provide (#14301)
+
+`detect-free-identifiers`' ambient allowlist was ONE generous list, documented as
+"assume the runtime has it". The runtime a lowered body actually runs in is the
+QuickJS sandbox, not the Node process that runs `objectstack build` — and the
+list named `Intl` beside `JSON`, under the comment "Web-ish that the sandbox /
+Node commonly provide". So a handler calling `Intl.DateTimeFormat` had no free
+identifier at all: `extractHookBody` lowered it into `body.source`, the #13651
+lint rule had nothing to report (it fires only on a *refused* lowering),
+`validate` / `typecheck` / `test` / `build` were all green because the
+in-process test runs the RAW function in Node where `Intl` exists — and
+production threw `ReferenceError: Intl is not defined`. Under the
+`onError: 'abort'` a validation-shaped hook must declare, that refuses every
+write to the object.
+
+The allowlist is now two sets, and membership is **measured**, never recalled: a
+`typeof X`/`'X' in globalThis` probe is evaluated inside the same
+`QuickJSScriptRunner` the runtime evaluates a body in, and
+`sandbox-globals-probe.test.ts` fails unless each set is exactly the probe's
+present/absent partition.
+
+- **`SANDBOX_GLOBALS` (53, measured present)** — the ECMAScript surface:
+ `Math` `JSON` `Date` `Object` `Array` `String` `Number` `Boolean` `RegExp`
+ `Map` `Set` `WeakMap` `WeakSet` `Promise` `Symbol` `BigInt` `Function`
+ `Reflect` `Proxy`, the typed-array/buffer family, the eight error
+ constructors, `parseInt` `parseFloat` `isNaN` `isFinite` and the four URI
+ functions, plus `undefined` `NaN` `Infinity` `globalThis`.
+- **`NODE_ONLY_GLOBALS` (15, measured absent)** — `Intl`, `structuredClone`,
+ `queueMicrotask`, `atob`, `btoa`, `setTimeout`, `clearTimeout`,
+ `setInterval`, `clearInterval`, `URL`, `URLSearchParams`, `TextEncoder`,
+ `TextDecoder`, `console`, `arguments`.
+
+A free reference to one of the 15 is now a lowering refusal whose reason names
+the identifier and the remedy — a string handler ref (`functions:` map plus
+`handler: 'fn_name'`) or a validation rule, and for `console` specifically the
+capability-gated `ctx.log`. It travels the SAME path #1876 already used: the
+refusal is `kind: 'free-identifiers'` with the host-only half carried
+separately as `nodeOnlyIdentifiers`, `lowerCallables` catches it and ships the
+callable through the `.mjs` bundle (where it runs in-process in Node and
+works), `os build` still exits 0 with a warning, and `os lint` reports it under
+`hook-body/not-lowerable` as an `error` — the ACCIDENTAL class, because `Intl`
+is a standard global in every browser and in Node and writing it is not the
+recognisable "I am reaching for the host" act that `fetch(` and `process.` are.
+The remedy sentence `os lint` prints is chosen from the refusal's own
+classification: "inline the value" is impossible for a host global, and
+printing it anyway would send an author after a second broken shape.
+
+⛔ Not changed here: whether `os build` fails on the lowering class (#13838),
+and what the sandbox provides (giving it `Intl` would be a capability
+expansion). Nothing under `packages/runtime/**` is touched — the probe reads
+that sandbox, it does not change it.
+
+**Why `patch`.** No published accept-set moves: the metadata a valid app may
+declare is identical, `HookBodySchema` is untouched, and no key is added,
+removed or re-shaped. What narrows is which handlers the build LOWERS, and for
+every handler affected the previous outcome was a body that could not run. An
+app hitting this gains a warning and a working bundled closure in place of a
+production `ReferenceError`; the deployment shape it loses was never one it had
+in working order. Measured corpus: zero in-repo example or template handlers
+reference any of the 15.

packages/cli/src/lint/hook-body-lowering.test.ts

@@ -42,6 +42,19 @@ const forbiddenTokenHook = {
  },
 };
 
+// [#14301] A global the NODE HOST provides and the sandbox does not. Reads as
+// self-contained — `Intl` is standard in every browser and in Node — which is
+// precisely why it is the ACCIDENTAL class and not the structural one.
+const nodeOnlyGlobalHook = {
+ name: 'stamp_due_label',
+ object: 'task',
+ events: ['beforeInsert'],
+ handler: (ctx: any) => {
+ const f = new Intl.DateTimeFormat('en-US', { timeZone: 'UTC' });
+ ctx.input.due_label = f.format(new Date(ctx.input.due_at));
+ },
+};
+
 const selfContainedHook = {
  name: 'normalize_name',
  object: 'account',
@@ -91,6 +104,41 @@ describe('checkHookBodyLowering', () => {
  expect(issues[0].message).toContain('deployment shape');
  });
 
+ describe('a host global the sandbox lacks is the ACCIDENTAL class (#14301)', () => {
+ it('reports it as an ERROR under the not-lowerable rule', () => {
+ const issues = checkHookBodyLowering({ hooks: [nodeOnlyGlobalHook] });
+
+ expect(issues).toHaveLength(1);
+ expect(issues[0].severity).toBe('error');
+ expect(issues[0].rule).toBe(NOT_LOWERABLE_RULE);
+ expect(issues[0].path).toBe('hooks[0].handler');
+ expect(issues[0].message).toContain("hook 'stamp_due_label'");
+ expect(issues[0].message).toContain('Intl');
+ expect(issues[0].message).toContain('deployment shape');
+ });
+
+ it('prints the remedy that is POSSIBLE, not the inline one', () => {
+ // The wrong-remedy failure is worse than none: there is nothing to inline
+ // `Intl` from, so an author (or a code-writing model) told to inline it
+ // lands on a second broken shape. The remedy sentence is chosen from the
+ // refusal's own `nodeOnlyIdentifiers`, never re-derived here.
+ const [issue] = checkHookBodyLowering({ hooks: [nodeOnlyGlobalHook] });
+ expect(issue.message).toContain('provided by the Node host');
+ expect(issue.message).toContain('cannot be inlined');
+ expect(issue.message).toContain('string handler ref');
+ expect(issue.message).toContain('validation rule');
+ expect(issue.message).not.toContain('Inline the value(s) into the handler');
+ });
+
+ it('leaves the module-scope remedy exactly as it was', () => {
+ // The reverse leg: the #13651 sentence must not have been rewritten for
+ // every author by a branch added for one new sub-case.
+ const [issue] = checkHookBodyLowering({ hooks: [freeIdentifierHook] });
+ expect(issue.message).toContain('Inline the value(s) into the handler, or reach them through `ctx`.');
+ expect(issue.message).not.toContain('provided by the Node host');
+ });
+ });
+
  it('keeps the STRUCTURAL refusal a warning — the bundle is its designed answer', () => {
  const issues = checkHookBodyLowering({ hooks: [forbiddenTokenHook] });
 

packages/cli/src/lint/hook-body-lowering.ts

@@ -38,13 +38,22 @@
  * Today both arrive through one catch, so they share one fate. They are not
  * the same event, and the refusal kind already tells them apart:
  *
- * `free-identifiers` ACCIDENTAL. The handler IS expressible as a metadata
- * body; it merely names a module-scope const/helper/
- * import. The author wrote something that reads
+ * `free-identifiers` ACCIDENTAL. The author wrote something that reads
  * self-contained, and the platform quietly re-shaped the
  * deployment behind them — its own message even says "no
  * behavior change", which is true of behaviour and false
- * of shape. Remedy is local: inline the value. => `error`.
+ * of shape. => `error`, for both sub-cases:
+ * · a module-scope const/helper/import — remedy is
+ * local: inline the value.
+ * · a global the NODE HOST has and the sandbox does not
+ * (#14301, `Intl`) — NOT inlinable, and still
+ * accidental rather than a chosen bundle: `Intl` is a
+ * standard global in every browser and in Node, so
+ * writing it is not the recognisable "I am reaching
+ * for the host" act that `fetch(`/`process.` are.
+ * That is why it is an `error` here and not the
+ * `warning` its structural cousin gets — and why the
+ * remedy sentence below is CHOSEN per sub-case.
  * `forbidden-token` STRUCTURAL. `fetch`/`require`/`process`/`eval`/… are
  * capabilities the sandbox does not have, so the handler
  * can NEVER be a metadata body. Writing one IS choosing a
@@ -129,12 +138,37 @@ function judge(fn: AnyFn, originLabel: string, path: string): HookBodyLintIssue
  } catch (err: unknown) {
  const kind = err instanceof HookBodyExtractionError ? err.kind : 'unknown';
  const free = err instanceof HookBodyExtractionError ? err.freeIdentifiers : [];
+ // [#14301] The half of `free` the Node HOST provides and the sandbox does
+ // not. Read off the refusal rather than re-derived here: this rule's whole
+ // parity claim is that it cannot disagree with what `os build` did to the
+ // same handler, and a second membership table in this file would be exactly
+ // such a disagreement waiting to happen.
+ const nodeOnly = err instanceof HookBodyExtractionError ? err.nodeOnlyIdentifiers : [];
  // Only the first line: the refusal text carries a multi-line offending-source
  // dump for `--strict-body`'s per-callable diagnostic, which would swamp a
  // lint report. `os build --strict-body` remains the place to read it whole.
  const firstLine = String((err as Error)?.message ?? err).split('\n')[0];
 
  if (kind === 'free-identifiers') {
+ // The remedy sentence is chosen, not fixed. "Inline the value(s)" is
+ // right for a module-scope helper and IMPOSSIBLE for a host global —
+ // there is nothing to inline `Intl` from — so printing it for both would
+ // send an author (or a code-writing model) after a second broken shape.
+ const moduleScope = free.filter((n) => !nodeOnly.includes(n));
+ const hostRemedy =
+ `${nodeOnly.join(', ')} ${nodeOnly.length === 1 ? 'is' : 'are'} provided by the Node host ` +
+ `and NOT by the sandbox, so ${nodeOnly.length === 1 ? 'it' : 'they'} cannot be inlined: ` +
+ `keep the check in a string handler ref, or move it to a validation rule.`;
+ const inlineRemedy =
+ `Inline the value(s) into the handler, or reach them through \`ctx\`.`;
+ const remedy =
+ nodeOnly.length === 0
+ ? inlineRemedy
+ : moduleScope.length === 0
+ ? hostRemedy
+ : `${hostRemedy} ${moduleScope.join(', ')} ${moduleScope.length === 1 ? 'is' : 'are'} ` +
+ `module-scope: inline ${moduleScope.length === 1 ? 'it' : 'them'} into the handler, ` +
+ `or reach ${moduleScope.length === 1 ? 'it' : 'them'} through \`ctx\`.`;
  return {
  severity: 'error',
  rule: NOT_LOWERABLE_RULE,
@@ -143,8 +177,7 @@ function judge(fn: AnyFn, originLabel: string, path: string): HookBodyLintIssue
  `${free.length === 1 ? 'the identifier' : 'identifiers'} ${free.join(', ')}, which ` +
  `${free.length === 1 ? 'is' : 'are'} not in scope inside the sandbox. The handler is ` +
  `BUNDLED instead, so this app is no longer shippable as pure metadata — a change of ` +
- `deployment shape, not of behaviour. Inline the value(s) into the handler, or reach ` +
- `them through \`ctx\`. ${DELIBERATE_BUNDLE_REMEDY}`,
+ `deployment shape, not of behaviour. ${remedy} ${DELIBERATE_BUNDLE_REMEDY}`,
  path,
  };
  }

packages/cli/src/utils/detect-free-identifiers.test.ts

@@ -1,7 +1,11 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { describe, it, expect } from 'vitest';
-import { detectFreeIdentifiers } from './detect-free-identifiers.js';
+import {
+ detectFreeIdentifiers,
+ NODE_ONLY_GLOBALS,
+ SANDBOX_GLOBALS,
+} from './detect-free-identifiers.js';
 
 /** Helper: stringify a real function so we test the exact `.toString()` path. */
 const src = (fn: (...a: any[]) => any) => String(fn);
@@ -53,6 +57,14 @@ describe('detectFreeIdentifiers (#1876 — body self-containment)', () => {
  ['nested destructuring', '({ a: { b } }) => b + 1'],
  ['rest params', '(...args) => args.length'],
  ['typeof a local', '(ctx) => { const v = ctx.v; return typeof v; }'],
+ // #14301 — the node-only refusal is a SCOPE analysis, not a token scan.
+ // A locally-bound name that happens to spell a host global is bound, and
+ // a member NAMED after one is not a reference at all. Both would be
+ // false refusals, and a false refusal here costs an author a body they
+ // were entitled to.
+ ['a local shadowing a host global', '(ctx) => { const Intl = ctx.fmt; return Intl.format(ctx.d); }'],
+ ['a member named after a host global', '(ctx) => { return ctx.Intl.format(ctx.d); }'],
+ ['a param named after a host global', '(ctx, Intl) => Intl.format(ctx.d)'],
  ];
  for (const [label, source] of selfContained) {
  it(label, () => {
@@ -81,4 +93,79 @@ describe('detectFreeIdentifiers (#1876 — body self-containment)', () => {
  expect(detectFreeIdentifiers('').free).toEqual([]);
  expect(detectFreeIdentifiers('{ not: valid').free).toEqual([]);
  });
+ // ── #14301 — globals the NODE HOST has and the sandbox does not ──────────
+ //
+ // The reported shape: `Intl` sat in one generous allowlist beside `JSON`, so
+ // a handler calling `Intl.DateTimeFormat` had no free identifier, lowered
+ // into `body.source`, and threw `ReferenceError` in production while every
+ // local gate was green. The split makes the reference visible again; the
+ // membership of the two sets is not asserted here from knowledge — it is
+ // measured inside the real sandbox by `sandbox-globals-probe.test.ts`.
+ describe('reports host globals the sandbox does not provide', () => {
+ it('the card reproduction — Intl.DateTimeFormat', () => {
+ const r = detectFreeIdentifiers(
+ "(ctx) => { const f = new Intl.DateTimeFormat('en-US'); ctx.input.label = f.format(new Date(ctx.input.at)); }",
+ );
+ expect(r.unparsed).toBe(false);
+ expect(r.free).toEqual(['Intl']);
+ expect(r.nodeOnly).toEqual(['Intl']);
+ });
+
+ it('`nodeOnly` is a labelled SUBSET of `free`, not a second list', () => {
+ // Both halves at once. The caller needs them apart because the remedies
+ // are opposite — inline the helper, but a host global cannot be inlined
+ // — and needs them together because the refusal names every name.
+ const r = detectFreeIdentifiers('(ctx) => { ctx.x = slugify(ctx.name) + Intl.NumberFormat; }');
+ expect(r.free).toEqual(['Intl', 'slugify']);
+ expect(r.nodeOnly).toEqual(['Intl']);
+ expect(r.nodeOnly.every((n) => r.free.includes(n))).toBe(true);
+ });
+
+ it('a sandbox-provided global is still waived — the positive control', () => {
+ const r = detectFreeIdentifiers('(ctx) => { ctx.x = JSON.stringify(Math.round(ctx.n)); }');
+ expect(r.free).toEqual([]);
+ expect(r.nodeOnly).toEqual([]);
+ });
+
+ it('every member of NODE_ONLY_GLOBALS is reported when referenced free', () => {
+ // Set-wide rather than per-name: a member added to the set without the
+ // detector reading it would otherwise sit inert, which is the exact
+ // shape of the defect being closed one level up.
+ for (const name of NODE_ONLY_GLOBALS) {
+ const r = detectFreeIdentifiers(`(ctx) => { ctx.x = ${name}; }`);
+ expect({ name, free: r.free, nodeOnly: r.nodeOnly }).toEqual({
+ name,
+ free: [name],
+ nodeOnly: [name],
+ });
+ }
+ });
+
+ it('every member of SANDBOX_GLOBALS is waived when referenced free', () => {
+ for (const name of SANDBOX_GLOBALS) {
+ const r = detectFreeIdentifiers(`(ctx) => { ctx.x = ${name}; }`);
+ expect({ name, free: r.free, nodeOnly: r.nodeOnly }).toEqual({
+ name,
+ free: [],
+ nodeOnly: [],
+ });
+ }
+ });
+
+ it('junk input reports neither list (conservative — never blocks extraction)', () => {
+ // The bias the file's header states, restated over the NEW field: a
+ // source this analysis cannot make sense of must not produce a refusal.
+ // Asserted over the same three junk shapes the #1876 case uses, and
+ // without asserting `unparsed` — TS error-recovery decides that, and the
+ // invariant that matters is that neither list fills.
+ for (const junk of ['this is not a function', '', '{ not: valid']) {
+ const r = detectFreeIdentifiers(junk);
+ expect({ junk, free: r.free, nodeOnly: r.nodeOnly }).toEqual({
+ junk,
+ free: [],
+ nodeOnly: [],
+ });
+ }
+ });
+ });
 });

.changeset/hook-body-sandbox-globals-allowlist.md

@@ -0,0 +1,64 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): stop lowering hook/action bodies that reference globals the sandbox does not provide (#14301)
+
+`detect-free-identifiers`' ambient allowlist was ONE generous list, documented as
+"assume the runtime has it". The runtime a lowered body actually runs in is the
+QuickJS sandbox, not the Node process that runs `objectstack build` — and the
+list named `Intl` beside `JSON`, under the comment "Web-ish that the sandbox /
+Node commonly provide". So a handler calling `Intl.DateTimeFormat` had no free
+identifier at all: `extractHookBody` lowered it into `body.source`, the #13651
+lint rule had nothing to report (it fires only on a *refused* lowering),
+`validate` / `typecheck` / `test` / `build` were all green because the
+in-process test runs the RAW function in Node where `Intl` exists — and
+production threw `ReferenceError: Intl is not defined`. Under the
+`onError: 'abort'` a validation-shaped hook must declare, that refuses every
+write to the object.
+
+The allowlist is now two sets, and membership is **measured**, never recalled: a
+`typeof X`/`'X' in globalThis` probe is evaluated inside the same
+`QuickJSScriptRunner` the runtime evaluates a body in, and
+`sandbox-globals-probe.test.ts` fails unless each set is exactly the probe's
+present/absent partition.
+
+- **`SANDBOX_GLOBALS` (53, measured present)** — the ECMAScript surface:
+ `Math` `JSON` `Date` `Object` `Array` `String` `Number` `Boolean` `RegExp`
+ `Map` `Set` `WeakMap` `WeakSet` `Promise` `Symbol` `BigInt` `Function`
+ `Reflect` `Proxy`, the typed-array/buffer family, the eight error
+ constructors, `parseInt` `parseFloat` `isNaN` `isFinite` and the four URI
+ functions, plus `undefined` `NaN` `Infinity` `globalThis`.
+- **`NODE_ONLY_GLOBALS` (15, measured absent)** — `Intl`, `structuredClone`,
+ `queueMicrotask`, `atob`, `btoa`, `setTimeout`, `clearTimeout`,
+ `setInterval`, `clearInterval`, `URL`, `URLSearchParams`, `TextEncoder`,
+ `TextDecoder`, `console`, `arguments`.
+
+A free reference to one of the 15 is now a lowering refusal whose reason names
+the identifier and the remedy — a string handler ref (`functions:` map plus
+`handler: 'fn_name'`) or a validation rule, and for `console` specifically the
+capability-gated `ctx.log`. It travels the SAME path #1876 already used: the
+refusal is `kind: 'free-identifiers'` with the host-only half carried
+separately as `nodeOnlyIdentifiers`, `lowerCallables` catches it and ships the
+callable through the `.mjs` bundle (where it runs in-process in Node and
+works), `os build` still exits 0 with a warning, and `os lint` reports it under
+`hook-body/not-lowerable` as an `error` — the ACCIDENTAL class, because `Intl`
+is a standard global in every browser and in Node and writing it is not the
+recognisable "I am reaching for the host" act that `fetch(` and `process.` are.
+The remedy sentence `os lint` prints is chosen from the refusal's own
+classification: "inline the value" is impossible for a host global, and
+printing it anyway would send an author after a second broken shape.
+
+⛔ Not changed here: whether `os build` fails on the lowering class (#13838),
+and what the sandbox provides (giving it `Intl` would be a capability
+expansion). Nothing under `packages/runtime/**` is touched — the probe reads
+that sandbox, it does not change it.
+
+**Why `patch`.** No published accept-set moves: the metadata a valid app may
+declare is identical, `HookBodySchema` is untouched, and no key is added,
+removed or re-shaped. What narrows is which handlers the build LOWERS, and for
+every handler affected the previous outcome was a body that could not run. An
+app hitting this gains a warning and a working bundled closure in place of a
+production `ReferenceError`; the deployment shape it loses was never one it had
+in working order. Measured corpus: zero in-repo example or template handlers
+reference any of the 15.

packages/cli/src/lint/hook-body-lowering.test.ts

@@ -42,6 +42,19 @@ const forbiddenTokenHook = {
  },
 };
 
+// [#14301] A global the NODE HOST provides and the sandbox does not. Reads as
+// self-contained — `Intl` is standard in every browser and in Node — which is
+// precisely why it is the ACCIDENTAL class and not the structural one.
+const nodeOnlyGlobalHook = {
+ name: 'stamp_due_label',
+ object: 'task',
+ events: ['beforeInsert'],
+ handler: (ctx: any) => {
+ const f = new Intl.DateTimeFormat('en-US', { timeZone: 'UTC' });
+ ctx.input.due_label = f.format(new Date(ctx.input.due_at));
+ },
+};
+
 const selfContainedHook = {
  name: 'normalize_name',
  object: 'account',
@@ -91,6 +104,41 @@ describe('checkHookBodyLowering', () => {
  expect(issues[0].message).toContain('deployment shape');
  });
 
+ describe('a host global the sandbox lacks is the ACCIDENTAL class (#14301)', () => {
+ it('reports it as an ERROR under the not-lowerable rule', () => {
+ const issues = checkHookBodyLowering({ hooks: [nodeOnlyGlobalHook] });
+
+ expect(issues).toHaveLength(1);
+ expect(issues[0].severity).toBe('error');
+ expect(issues[0].rule).toBe(NOT_LOWERABLE_RULE);
+ expect(issues[0].path).toBe('hooks[0].handler');
+ expect(issues[0].message).toContain("hook 'stamp_due_label'");
+ expect(issues[0].message).toContain('Intl');
+ expect(issues[0].message).toContain('deployment shape');
+ });
+
+ it('prints the remedy that is POSSIBLE, not the inline one', () => {
+ // The wrong-remedy failure is worse than none: there is nothing to inline
+ // `Intl` from, so an author (or a code-writing model) told to inline it
+ // lands on a second broken shape. The remedy sentence is chosen from the
+ // refusal's own `nodeOnlyIdentifiers`, never re-derived here.
+ const [issue] = checkHookBodyLowering({ hooks: [nodeOnlyGlobalHook] });
+ expect(issue.message).toContain('provided by the Node host');
+ expect(issue.message).toContain('cannot be inlined');
+ expect(issue.message).toContain('string handler ref');
+ expect(issue.message).toContain('validation rule');
+ expect(issue.message).not.toContain('Inline the value(s) into the handler');
+ });
+
+ it('leaves the module-scope remedy exactly as it was', () => {
+ // The reverse leg: the #13651 sentence must not have been rewritten for
+ // every author by a branch added for one new sub-case.
+ const [issue] = checkHookBodyLowering({ hooks: [freeIdentifierHook] });
+ expect(issue.message).toContain('Inline the value(s) into the handler, or reach them through `ctx`.');
+ expect(issue.message).not.toContain('provided by the Node host');
+ });
+ });
+
  it('keeps the STRUCTURAL refusal a warning — the bundle is its designed answer', () => {
  const issues = checkHookBodyLowering({ hooks: [forbiddenTokenHook] });
 

packages/cli/src/lint/hook-body-lowering.ts

@@ -38,13 +38,22 @@
  * Today both arrive through one catch, so they share one fate. They are not
  * the same event, and the refusal kind already tells them apart:
  *
- * `free-identifiers` ACCIDENTAL. The handler IS expressible as a metadata
- * body; it merely names a module-scope const/helper/
- * import. The author wrote something that reads
+ * `free-identifiers` ACCIDENTAL. The author wrote something that reads
  * self-contained, and the platform quietly re-shaped the
  * deployment behind them — its own message even says "no
  * behavior change", which is true of behaviour and false
- * of shape. Remedy is local: inline the value. => `error`.
+ * of shape. => `error`, for both sub-cases:
+ * · a module-scope const/helper/import — remedy is
+ * local: inline the value.
+ * · a global the NODE HOST has and the sandbox does not
+ * (#14301, `Intl`) — NOT inlinable, and still
+ * accidental rather than a chosen bundle: `Intl` is a
+ * standard global in every browser and in Node, so
+ * writing it is not the recognisable "I am reaching
+ * for the host" act that `fetch(`/`process.` are.
+ * That is why it is an `error` here and not the
+ * `warning` its structural cousin gets — and why the
+ * remedy sentence below is CHOSEN per sub-case.
  * `forbidden-token` STRUCTURAL. `fetch`/`require`/`process`/`eval`/… are
  * capabilities the sandbox does not have, so the handler
  * can NEVER be a metadata body. Writing one IS choosing a
@@ -129,12 +138,37 @@ function judge(fn: AnyFn, originLabel: string, path: string): HookBodyLintIssue
  } catch (err: unknown) {
  const kind = err instanceof HookBodyExtractionError ? err.kind : 'unknown';
  const free = err instanceof HookBodyExtractionError ? err.freeIdentifiers : [];
+ // [#14301] The half of `free` the Node HOST provides and the sandbox does
+ // not. Read off the refusal rather than re-derived here: this rule's whole
+ // parity claim is that it cannot disagree with what `os build` did to the
+ // same handler, and a second membership table in this file would be exactly
+ // such a disagreement waiting to happen.
+ const nodeOnly = err instanceof HookBodyExtractionError ? err.nodeOnlyIdentifiers : [];
  // Only the first line: the refusal text carries a multi-line offending-source
  // dump for `--strict-body`'s per-callable diagnostic, which would swamp a
  // lint report. `os build --strict-body` remains the place to read it whole.
  const firstLine = String((err as Error)?.message ?? err).split('\n')[0];
 
  if (kind === 'free-identifiers') {
+ // The remedy sentence is chosen, not fixed. "Inline the value(s)" is
+ // right for a module-scope helper and IMPOSSIBLE for a host global —
+ // there is nothing to inline `Intl` from — so printing it for both would
+ // send an author (or a code-writing model) after a second broken shape.
+ const moduleScope = free.filter((n) => !nodeOnly.includes(n));
+ const hostRemedy =
+ `${nodeOnly.join(', ')} ${nodeOnly.length === 1 ? 'is' : 'are'} provided by the Node host ` +
+ `and NOT by the sandbox, so ${nodeOnly.length === 1 ? 'it' : 'they'} cannot be inlined: ` +
+ `keep the check in a string handler ref, or move it to a validation rule.`;
+ const inlineRemedy =
+ `Inline the value(s) into the handler, or reach them through \`ctx\`.`;
+ const remedy =
+ nodeOnly.length === 0
+ ? inlineRemedy
+ : moduleScope.length === 0
+ ? hostRemedy
+ : `${hostRemedy} ${moduleScope.join(', ')} ${moduleScope.length === 1 ? 'is' : 'are'} ` +
+ `module-scope: inline ${moduleScope.length === 1 ? 'it' : 'them'} into the handler, ` +
+ `or reach ${moduleScope.length === 1 ? 'it' : 'them'} through \`ctx\`.`;
  return {
  severity: 'error',
  rule: NOT_LOWERABLE_RULE,
@@ -143,8 +177,7 @@ function judge(fn: AnyFn, originLabel: string, path: string): HookBodyLintIssue
  `${free.length === 1 ? 'the identifier' : 'identifiers'} ${free.join(', ')}, which ` +
  `${free.length === 1 ? 'is' : 'are'} not in scope inside the sandbox. The handler is ` +
  `BUNDLED instead, so this app is no longer shippable as pure metadata — a change of ` +
- `deployment shape, not of behaviour. Inline the value(s) into the handler, or reach ` +
- `them through \`ctx\`. ${DELIBERATE_BUNDLE_REMEDY}`,
+ `deployment shape, not of behaviour. ${remedy} ${DELIBERATE_BUNDLE_REMEDY}`,
  path,
  };
  }

packages/cli/src/utils/detect-free-identifiers.test.ts

@@ -1,7 +1,11 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { describe, it, expect } from 'vitest';
-import { detectFreeIdentifiers } from './detect-free-identifiers.js';
+import {
+ detectFreeIdentifiers,
+ NODE_ONLY_GLOBALS,
+ SANDBOX_GLOBALS,
+} from './detect-free-identifiers.js';
 
 /** Helper: stringify a real function so we test the exact `.toString()` path. */
 const src = (fn: (...a: any[]) => any) => String(fn);
@@ -53,6 +57,14 @@ describe('detectFreeIdentifiers (#1876 — body self-containment)', () => {
  ['nested destructuring', '({ a: { b } }) => b + 1'],
  ['rest params', '(...args) => args.length'],
  ['typeof a local', '(ctx) => { const v = ctx.v; return typeof v; }'],
+ // #14301 — the node-only refusal is a SCOPE analysis, not a token scan.
+ // A locally-bound name that happens to spell a host global is bound, and
+ // a member NAMED after one is not a reference at all. Both would be
+ // false refusals, and a false refusal here costs an author a body they
+ // were entitled to.
+ ['a local shadowing a host global', '(ctx) => { const Intl = ctx.fmt; return Intl.format(ctx.d); }'],
+ ['a member named after a host global', '(ctx) => { return ctx.Intl.format(ctx.d); }'],
+ ['a param named after a host global', '(ctx, Intl) => Intl.format(ctx.d)'],
  ];
  for (const [label, source] of selfContained) {
  it(label, () => {
@@ -81,4 +93,79 @@ describe('detectFreeIdentifiers (#1876 — body self-containment)', () => {
  expect(detectFreeIdentifiers('').free).toEqual([]);
  expect(detectFreeIdentifiers('{ not: valid').free).toEqual([]);
  });
+ // ── #14301 — globals the NODE HOST has and the sandbox does not ──────────
+ //
+ // The reported shape: `Intl` sat in one generous allowlist beside `JSON`, so
+ // a handler calling `Intl.DateTimeFormat` had no free identifier, lowered
+ // into `body.source`, and threw `ReferenceError` in production while every
+ // local gate was green. The split makes the reference visible again; the
+ // membership of the two sets is not asserted here from knowledge — it is
+ // measured inside the real sandbox by `sandbox-globals-probe.test.ts`.
+ describe('reports host globals the sandbox does not provide', () => {
+ it('the card reproduction — Intl.DateTimeFormat', () => {
+ const r = detectFreeIdentifiers(
+ "(ctx) => { const f = new Intl.DateTimeFormat('en-US'); ctx.input.label = f.format(new Date(ctx.input.at)); }",
+ );
+ expect(r.unparsed).toBe(false);
+ expect(r.free).toEqual(['Intl']);
+ expect(r.nodeOnly).toEqual(['Intl']);
+ });
+
+ it('`nodeOnly` is a labelled SUBSET of `free`, not a second list', () => {
+ // Both halves at once. The caller needs them apart because the remedies
+ // are opposite — inline the helper, but a host global cannot be inlined
+ // — and needs them together because the refusal names every name.
+ const r = detectFreeIdentifiers('(ctx) => { ctx.x = slugify(ctx.name) + Intl.NumberFormat; }');
+ expect(r.free).toEqual(['Intl', 'slugify']);
+ expect(r.nodeOnly).toEqual(['Intl']);
+ expect(r.nodeOnly.every((n) => r.free.includes(n))).toBe(true);
+ });
+
+ it('a sandbox-provided global is still waived — the positive control', () => {
+ const r = detectFreeIdentifiers('(ctx) => { ctx.x = JSON.stringify(Math.round(ctx.n)); }');
+ expect(r.free).toEqual([]);
+ expect(r.nodeOnly).toEqual([]);
+ });
+
+ it('every member of NODE_ONLY_GLOBALS is reported when referenced free', () => {
+ // Set-wide rather than per-name: a member added to the set without the
+ // detector reading it would otherwise sit inert, which is the exact
+ // shape of the defect being closed one level up.
+ for (const name of NODE_ONLY_GLOBALS) {
+ const r = detectFreeIdentifiers(`(ctx) => { ctx.x = ${name}; }`);
+ expect({ name, free: r.free, nodeOnly: r.nodeOnly }).toEqual({
+ name,
+ free: [name],
+ nodeOnly: [name],
+ });
+ }
+ });
+
+ it('every member of SANDBOX_GLOBALS is waived when referenced free', () => {
+ for (const name of SANDBOX_GLOBALS) {
+ const r = detectFreeIdentifiers(`(ctx) => { ctx.x = ${name}; }`);
+ expect({ name, free: r.free, nodeOnly: r.nodeOnly }).toEqual({
+ name,
+ free: [],
+ nodeOnly: [],
+ });
+ }
+ });
+
+ it('junk input reports neither list (conservative — never blocks extraction)', () => {
+ // The bias the file's header states, restated over the NEW field: a
+ // source this analysis cannot make sense of must not produce a refusal.
+ // Asserted over the same three junk shapes the #1876 case uses, and
+ // without asserting `unparsed` — TS error-recovery decides that, and the
+ // invariant that matters is that neither list fills.
+ for (const junk of ['this is not a function', '', '{ not: valid']) {
+ const r = detectFreeIdentifiers(junk);
+ expect({ junk, free: r.free, nodeOnly: r.nodeOnly }).toEqual({
+ junk,
+ free: [],
+ nodeOnly: [],
+ });
+ }
+ });
+ });
 });