feat(spec): declare AutomationContext.recordLoadDenied, the flow face of the caller-scope record-load signal (#15143)

* feat(spec): declare AutomationContext.recordLoadDenied, the flow face of the record-load signal

Additive key `recordLoadDenied?: true` on `AutomationContext`, mirroring the
producer's spelling (`actionRecordLoadSignal` in the runtime's
`action-execution.ts` returns `{ recordLoadDenied?: true }`), with a type-level
pin (`true | undefined`, additive positive control, `false` refused) and a
minor changeset. Declared, not yet populated on the flow face — the runtime
half is a separate card.

Claude-Session: https://claude.ai/code/session_0174WZTU6XcFcS7g2kykC53i
Co-authored-by: Claude <noreply@anthropic.com>

* docs(ui): note the flow face of ctx.recordLoadDenied — declared on AutomationContext, not yet populated

Claude-Session: https://claude.ai/code/session_0174WZTU6XcFcS7g2kykC53i
Co-authored-by: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

.changeset/automation-context-record-load-denied.md

@@ -0,0 +1,42 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): declare `AutomationContext.recordLoadDenied` — the flow face of the caller-scope record-load signal (#14244)
+
+An action of `type: 'flow'` hands its target flow the same `record` object the
+script/body face receives, and the dispatcher stamps the requested `recordId`
+onto `record.id` whether or not the caller's own scope could read the row —
+new-record / record-less actions depend on that stamp. So a flow started on a
+row its invoker cannot read receives `record = { id: <recordId> }`, shaped
+exactly like a legitimate record-less start, with nothing on the run's context
+distinguishing the two. The script/body face got its distinguishing key in the
+previous release (`ctx.recordLoadDenied`, `@objectstack/runtime`); the flow face
+had no equivalent on its contract.
+
+**The addition: `AutomationContext.recordLoadDenied?: true`.** The exact shape
+the runtime's one shared producer emits (`actionRecordLoadSignal` in
+`action-execution.ts` returns `{ recordLoadDenied?: true }`), mirrored rather
+than respelled: `true` exactly when the dispatcher's caller-scope load did not
+deliver the row; **absent** — never `false` — otherwise, so a consumer reads
+`recordLoadDenied === true`. It reports "the row did not resolve for this
+caller", not "an authorization error was caught": a row hidden by row-level
+security and an id that names nothing both arrive as `RECORD_NOT_FOUND`,
+deliberately, and the key does not pretend to separate them.
+
+A `runAs: 'user'` flow re-derives the caller's scope on its own reads, so the
+stub resolves to nothing there. The key exists for the `runAs: 'system'` flow:
+it runs elevated **and** receives the stub, and this is what it guards on before
+acting on a row its invoker has not demonstrated read access to.
+
+- **Purely additive.** The key is optional; every existing `AutomationContext`
+  literal type-checks unchanged and no existing key changes value. Pinned at
+  the type level (`true | undefined`, `false` refused at compile time).
+- **Declared, not yet populated on the flow face.** This release declares the
+  key on the contract. `dispatchFlowAction` (both action doors — REST
+  `POST /api/v1/actions/...` and the MCP `run_action` bridge) does not yet pass
+  the producer's signal into the run's context; that is a separate runtime
+  change. Until it lands, a flow run never sees this key, so a guard on it is
+  inert (never `true`), never wrong.
+- **Nothing narrows.** `dispatchFlowAction` still starts the run;
+  `runAs: 'system'` stays a declared, documented authoring decision.

content/docs/ui/actions.mdx

@@ -374,6 +374,17 @@ Set `ctx.recordLoadDenied` aside only when your action is *meant* to run without
 a readable subject row (an "import this id from elsewhere" action, say). The
 default for a row-scoped action on a `private` object is to refuse.
 
+**Flow actions.** A `type: 'flow'` action hands its target flow the same
+`record` — `record.id` stamped the same way — and the flow run's context
+(`AutomationContext`, the `@objectstack/spec` contract) declares the same key
+in the same spelling, `recordLoadDenied?: true`, so a `runAs: 'system'` flow
+has something to guard on before it acts on a row its invoker could not read.
+On the flow face the key is **declared but not yet populated**: the flow
+dispatcher does not pass the signal into the run's context yet, so until that
+lands a flow run never sees it and a guard on it is inert (never `true`), never
+wrong. A `runAs: 'user'` flow needs no guard — it re-derives the caller's
+scope on its own reads, and the stub resolves to nothing.
+
 ## Call it over REST
 
 Every action is also an endpoint — the Console button and the API call run

packages/spec/src/contracts/automation-context-record-load-denied.pin.test.ts

@@ -0,0 +1,112 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#14244] `AutomationContext.recordLoadDenied` is exactly the producer's
+ * shape — `{ recordLoadDenied?: true }`, the return type of
+ * `actionRecordLoadSignal` (`@objectstack/runtime`, `action-execution.ts`) —
+ * the flow face of #14143's handler-face signal, MIRRORED rather than
+ * respelled (triage ruling on #14244, 2026-09-02: the key must mirror the
+ * producer's spelling rather than invent a second one).
+ *
+ * Four things are pinned, because each drifts on its own:
+ *
+ *  1. **The key's type, at the type level.** Exactly `true | undefined` — a
+ *     widening to `boolean` would let a producer emit `false`, which the
+ *     handler face documents it never does (`ctx.recordLoadDenied === true`,
+ *     absent otherwise). A TypeScript interface member has no Zod schema, so
+ *     the only assertion is a compile-time identity (`Eq`, the
+ *     `automation-result-status.pin.test.ts` form), read by
+ *     `check:test-typecheck` under `tsconfig.test.json`.
+ *  2. **Additive.** A context literal WITHOUT the key still type-checks, so no
+ *     existing caller of `IAutomationService.execute` moves.
+ *  3. **`false` is refused at compile time** (`@ts-expect-error`). A phantom
+ *     unless this file is compiled — and it is: `tsconfig.test.json` includes
+ *     `src/**`, and its ledger (`test-typecheck-debt.json`) lists this file
+ *     nowhere, so the file must compile with exactly zero errors.
+ *  4. **The JSDoc says who sets it and that the flow face does not yet
+ *     populate it.** Prose is unassertable except by reading it; the contract
+ *     source is read and the doc block above the key is required to name the
+ *     producer and the not-yet-populated state, so the day the runtime half
+ *     lands, this test tells its author which sentence to retire.
+ *
+ * ⛔ Not pinned, deliberately: that any flow run actually RECEIVES the key.
+ * That is the runtime half (`dispatchFlowAction` / the REST `/actions` door
+ * passing the producer's signal into the run's context), a separate card.
+ */
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import { describe, it, expect } from 'vitest';
+
+import type { AutomationContext, IAutomationService } from './automation-service';
+
+/** Type-level identity: true iff A and B are the same type. */
+type Eq< A, B > = (< T >() => T extends A ? 1 : 2) extends (< T >() => T extends B ? 1 : 2) ? true : false;
+/** Compile error when the argument is not `true`. */
+type Assert< T extends true > = T;
+
+/**
+ * Exported deliberately — an unread alias inside a test body is TS6196, and a
+ * pin no program compiles is no pin at all.
+ */
+export type RecordLoadDeniedIsExactlyTrueOrUndefined = Assert< Eq< AutomationContext['recordLoadDenied'], true | undefined > >;
+/** The producer's return shape, spelled here as the runtime spells it. */
+type ProducerSignal = { recordLoadDenied?: true };
+/** The contract key is assignable FROM the producer's signal — the mirror holds in the direction that matters. */
+export type ProducerSignalSpreadsIntoContext = Assert< Eq< ProducerSignal['recordLoadDenied'], AutomationContext['recordLoadDenied'] > >;
+
+/** Positive control (additive): the key is optional, so a pre-#14244 context still type-checks. */
+export const contextWithoutTheKey: AutomationContext = { record: { id: 'rec-1', name: 'Alice' }, object: 'crm_deal', userId: 'u1' };
+/** The one value the key may carry. */
+export const contextWithTheKey: AutomationContext = { record: { id: 'rec-1' }, object: 'crm_deal', userId: 'u1', recordLoadDenied: true };
+// @ts-expect-error — `false` is not a member: the key is ABSENT, never `false` (handler-face convention, mirrored).
+export const contextWithFalse: AutomationContext = { record: { id: 'rec-1' }, object: 'crm_deal', recordLoadDenied: false };
+
+describe('[#14244] AutomationContext.recordLoadDenied mirrors the producer signal', () => {
+  it('reads the key back as exactly `true`, and its absence as `undefined` (anti-vacuity)', () => {
+    expect(contextWithTheKey.recordLoadDenied).toBe(true);
+    expect(contextWithoutTheKey.recordLoadDenied).toBeUndefined();
+    expect('recordLoadDenied' in contextWithoutTheKey).toBe(false);
+  });
+
+  it('a service implementation can guard on it WITHOUT a cast, the way a runAs:system flow would', async () => {
+    const seen: Array<true | undefined> = [];
+    const service: IAutomationService = {
+      execute: async (_flowName, context?) => {
+        seen.push(context?.recordLoadDenied);
+        // The documented predicate, verbatim: `=== true`, never a truthiness of `false`.
+        if (context?.recordLoadDenied === true) return { success: false, error: 'RECORD_NOT_FOUND' };
+        return { success: true };
+      },
+      listFlows: async () => [],
+    };
+    expect((await service.execute('guarded', contextWithTheKey)).success).toBe(false);
+    expect((await service.execute('guarded', contextWithoutTheKey)).success).toBe(true);
+    expect(seen).toEqual([true, undefined]);
+  });
+
+  it('the contract JSDoc names the producer, both doors, and the not-yet-populated flow face', () => {
+    const source = readFileSync(fileURLToPath(new URL('./automation-service.ts', import.meta.url)), 'utf8');
+    const declaration = 'recordLoadDenied?: true;';
+    const at = source.indexOf(declaration);
+    expect(at).toBeGreaterThan(-1);
+    // Exactly one declaration of the key on the contract — a second spelling
+    // anywhere in this file is the drift the ruling forbids.
+    expect(source.indexOf('recordLoadDenied', at + declaration.length)).toBe(-1);
+    // The doc block immediately above the declaration — from its last `/**`.
+    const docStart = source.lastIndexOf('/**', at);
+    const doc = source.slice(docStart, at);
+    expect(doc).toContain('loadActionSubjectRecord');
+    expect(doc).toContain('actionRecordLoadSignal');
+    expect(doc).toContain('{ recordLoadDenied?: true }');
+    expect(doc).toMatch(/both doors/i);
+    expect(doc).toMatch(/run_action/);
+    expect(doc).toMatch(/runAs: 'system'/);
+    // The honesty clause: declared, not yet populated on the flow face.
+    expect(doc).toMatch(/NOT YET POPULATED/);
+    expect(doc).toContain('dispatchFlowAction');
+    // Absence semantics, in the handler face's own words.
+    expect(doc).toMatch(/never\s+\*?\s*`false`/);
+  });
+});

packages/spec/src/contracts/automation-service.ts

@@ -25,6 +25,42 @@ import type { ConversionNotice, ConversionConflictNotice } from '../conversions/
 export interface AutomationContext {
     /** Record that triggered the automation (if applicable) */
     record?: Record<string, unknown>;
+    /**
+     * `true` exactly when the dispatcher's caller-scope load of the subject row
+     * did NOT deliver it — so {@link record} is the stamped `{ id }` stub the
+     * dispatcher puts in place of the row, not the row (#14244; the flow face of
+     * #14143's handler-face signal, `ctx.recordLoadDenied`). Absent — never
+     * `false` — otherwise, including for a record-less start that attempted no
+     * load, so a consumer reads `recordLoadDenied === true`.
+     *
+     * Who sets it: the runtime's action dispatch, both doors — REST
+     * `POST /api/v1/actions/...` and the MCP `run_action` bridge — through ONE
+     * producer, `loadActionSubjectRecord` in `@objectstack/runtime`'s
+     * `action-execution.ts`, whose `actionRecordLoadSignal(load)` returns
+     * exactly `{ recordLoadDenied?: true }` (line 1278 on `2cc46103`). This key
+     * IS that producer's spelling, mirrored — not a second one.
+     *
+     * What a flow guards on: a `type: 'flow'` action's dispatcher stamps the
+     * requested `recordId` onto `record.id` whether or not the caller could
+     * read the row (new-record / record-less actions depend on the stamp), so
+     * `record.id` is present either way and a node branching on it never
+     * refuses. A `runAs: 'user'` flow re-derives the caller's scope on its own
+     * reads and the stub resolves to nothing; a `runAs: 'system'` flow runs
+     * elevated AND receives the stub — this key is what such a flow guards on
+     * before acting on a row its invoker has not demonstrated read access to.
+     * It reports "the row did not resolve for this caller", not "an
+     * authorization error was caught": an RLS-hidden row and an id that names
+     * nothing both arrive as `RECORD_NOT_FOUND`, deliberately, and the key does
+     * not pretend to separate them.
+     *
+     * Declared, NOT YET POPULATED on the flow face: the handler face carries it
+     * today, but `dispatchFlowAction` still hands `automation.execute` a context
+     * without it, so until the runtime half lands a flow run never sees this key
+     * and a guard on it is inert (never `true`), never wrong. Additive — no
+     * existing key changes value. Callers other than the action dispatcher do
+     * NOT set this.
+     */
+    recordLoadDenied?: true;
     /**
      * Prior state of the record for update triggers (the "old" row). Lets
      * record-change-triggered flows gate on transitions (e.g.