@@ -0,0 +1,10 @@
+---
+'@objectstack/cli': patch
+---
+
+feat(cli): `objectstack build` lowers a hook handler that reads `ctx.provenance` instead of bundling it
+
+Clause-②: no
+Metadata-protocol: none
+
+The sandboxed hook body now carries `ctx.provenance` (see the `@objectstack/runtime` entry), so the lowerer no longer refuses a handler that reads it. Such a handler ships as a metadata-only body, and `os lint` no longer reports `hook-body/bundled-fallback` for that read. The CLI's published type surface does not change: `dist/index.d.ts`, `dist/hook-body.d.ts` and `dist/console.d.ts` are byte-identical before and after. Nothing to migrate: a handler that read `ctx.provenance` was bundled before and runs in-process, where it behaves the same. Rebuilding turns it into a body.
@@ -0,0 +1,17 @@
+---
+'@objectstack/runtime': patch
+---
+
+feat(runtime): a hook body reads `ctx.provenance`, so a guard that tells a flow's write from a user's own write ships as metadata
+
+Clause-②: yes (widening)
+Metadata-protocol: none
+
+The sandboxed hook body now carries the declared `HookContext.provenance`, the same server-stamped write provenance an in-process handler reads. On a write from a flow data node, `ctx.provenance.flowRunId` is that flow run's id. `attributedUserId` and `performedByClientId` ride along when the engine stamps them. Each member is a string or absent, and `ctx.provenance` itself is absent on a write with no origin, such as a plain REST write. Read it as `ctx.provenance?.flowRunId`. The object is frozen in the VM. It is built from the server-side execution context, so a payload field named `provenance` stays on `ctx.input` and never reaches it.
+
+The widening is on the published type surface. `ScriptContext`, exported from the `@objectstack/runtime` barrel, gains one optional member: `provenance?: { flowRunId?: string; attributedUserId?: string; performedByClientId?: string }`. Measured on `dist/index.d.ts` before and after the change:
+- the file grows from 338119 to 339467 bytes;
+- the export list is byte-identical, with the same 184 names;
+- the only declaration that changes is that one member and its doc comment.
+
+Nothing to migrate: the member is optional, and a `ScriptRunner` that ignores it behaves exactly as before.
@@ -98,6 +98,7 @@ The script sees only what the surrounding `ctx` object exposes:
 | `ctx.input` | Mutable record being inserted/updated/etc. | none |
 | `ctx.previous` | Pre-update record (update events only). | none |
 | `ctx.user` / `ctx.session` | Identity context. | none |
+| `ctx.provenance` | Where the write came from (hook bodies only) — see [Write provenance](#write-provenance--ctxprovenance). Absent on a write with no origin. | none |
 | `ctx.api.object(name).find\|count\|aggregate` | Cross-object reads, scoped to current tenant. | `api.read` |
 | `ctx.api.object(name).insert\|update\|delete` | Cross-object writes. | `api.write` |
 | `ctx.title()` | This record's title — the object's `nameField`, **including when it is a `formula`** (evaluated server-side against the record already in hand: no extra read over the record's own columns, one read per lookup a title such as `record.book.title + ' · ' + record.reader.name` reads through). | none |
@@ -106,6 +107,34 @@ The script sees only what the surrounding `ctx` object exposes:
 | `ctx.log.{info,warn,error}` | Structured logging. | `log` |
 | `ctx.connector(name).<method>(...)` _(planned)_ | Outbound HTTP / SaaS calls. **Not yet wired into the sandbox** — ships with the separate Connector spec. | (separate Connector spec) |
 
+### Write provenance — `ctx.provenance`
+
+A hook body sees the same server-stamped write provenance an in-process handler does — the declared [`HookContext.provenance`](/docs/references/data/hook), copied into the sandbox member by member:
+
+| Member | Present when |
+|---|---|
+| `ctx.provenance.flowRunId` | The write comes from an automation flow's data node; the value is that flow run's id. |
+| `ctx.provenance.attributedUserId` | The write is authorized as the system and credited to a real person (for example, the admin behind an identity-adapter call). |
+| `ctx.provenance.performedByClientId` | An AI client acting through the MCP OAuth door performed the write on behalf of the user in `ctx.session.userId`. |
+
+Each member is a string or absent, and `ctx.provenance` itself is **absent** when none applies — a plain REST write carries no provenance — so read it as `ctx.provenance?.flowRunId`. That is the guard that tells a flow's write apart from a user writing the same fields by hand, which matters most for a flow that runs `runAs: 'user'`: there `ctx.user`, `ctx.session` and `ctx.input` are identical for both writes.
+
+```ts
+// Only lead conversion may set `converted_from_lead`.
+handler: (ctx) => {
+  if (ctx.input.converted_from_lead && !ctx.provenance?.flowRunId) {
+    throw new Error('converted_from_lead is set by lead conversion only');
+  }
+},
+```
+
+Two guarantees hold, so the mark is safe to build a guard on:
+
+- **It cannot be forged through the data API.** The engine builds it from the server-side execution context, which a transport assembles from the authenticated session and never from request input (the automation engine sets `flowRunId` on its own data nodes); a payload field that happens to be named `provenance` stays a field on `ctx.input`.
+- **It is read-only in the sandbox.** The object is frozen and the key is not writable, so a body cannot change its own copy.
+
+It is a signal for app code, not an authorization input: no security middleware reads it, and each write is still authorized as its caller. Action bodies do not carry it.
+
 ### Naming a record — `ctx.title()`
 
 A body composing a message needs the record's **name**, and until this accessor
@@ -176,7 +205,7 @@ The CLI builder **rejects** any source that uses:
 - references to identifiers from value-only top-level imports
 - `.sudo(` and `.create(` — members that are real on the **in-process** `ScopedContext` / `ObjectRepository` and absent from the VM's `ctx.api`, so lowering them would ship a body that `TypeError`s on its first run. Write `.insert({ ... })` instead of `.create({ ... })` — it is the only insert verb the `IScopedObjectRepository` contract declares — and reach for [`runAs: 'system'`](/docs/automation/hooks#elevation--runas) instead of `.sudo()`. `Object.create()` is a real sandbox global and is **not** affected.
 - `ctx.dispatch.scope` and `ctx.submitted` — context members the **in-process** `HookContext` carries and the body face deliberately does not: a body's `ctx.dispatch` is `{ mode, index }` only, and it has no `ctx.submitted`. Lowered, a write through `scope` `TypeError`s on its first run and a read of `submitted` sees `undefined`, so a guard on it evaluates as if nothing were submitted. For cross-dispatch work, do it once at `ctx.dispatch.index === 0` or keep the state in the record through `ctx.api`; to derive from a read-only field, read the stored row on `ctx.previous`. `ctx.dispatch.mode` / `ctx.dispatch.index`, and a field that merely happens to be named `scope` or `submitted` (`ctx.input.scope`), are **not** affected.
-- `ctx.provenance`, `ctx.ql` and `ctx.transaction` (hook handlers) — the rest of the in-process `HookContext` the body face does not carry. A body reads `ctx.provenance` as `undefined`, so a guard on `ctx.provenance.flowRunId` evaluates as if the write had no origin; `ctx.ql` (the engine) and `ctx.transaction` (a driver handle) are live host objects no copy into the sandbox can carry. Reach other objects through `ctx.api.object(name)`, and group writes with `ctx.api.transaction(fn)`, which is **not** affected. The enumeration behind this list is derived, not remembered: a test compares every member `HookContextSchema` declares against every member the sandbox marshals, and fails on one that is neither refused here nor recorded as a deliberate exception.
+- `ctx.ql` and `ctx.transaction` (hook handlers) — the rest of the in-process `HookContext` the body face does not carry. `ctx.ql` (the engine) and `ctx.transaction` (a driver handle) are live host objects no copy into the sandbox can carry. Reach other objects through `ctx.api.object(name)`, and group writes with `ctx.api.transaction(fn)`, which is **not** affected. The enumeration behind this list is derived, not remembered: a test compares every member `HookContextSchema` declares against every member the sandbox marshals, and fails on one that is neither refused here nor recorded as a deliberate exception.
 
 Like `.sudo(` and `.create(`, these refuse the **body**, not the handler: `objectstack build` bundles the handler into its runtime module (`objectstack-runtime.*.mjs`) instead and still exits 0 (with a warning naming the hook), `os lint` reports it as `hook-body/bundled-fallback`, and `objectstack build --strict-body` fails on it. The bundled handler runs in-process wherever that module is served beside `objectstack.json`; a deployment that serves the artifact alone has no function to bind the hook to, so it logs the hook as refused at boot and the hook never fires — build with `--strict-body` when the artifact must be body-only.
 
 
@@ -265,6 +265,34 @@ describe('checkHookBodyLowering', () => {
     });
   });
 
+  // [#25905] `ctx.provenance` used to sit in the family above. The body face now
+  // carries it, so a guard telling a flow data node's write from a user's own
+  // write ships as a metadata-only body and lint has nothing to say about it.
+  describe('a body reading the write provenance the sandbox carries (#25905)', () => {
+    const flowOnlyHook = {
+      name: 'account_protection',
+      object: 'account',
+      events: ['beforeInsert', 'beforeUpdate'],
+      handler: (ctx: any) => {
+        if (ctx.input.converted_from_lead && !ctx.provenance?.flowRunId) {
+          throw new Error('converted_from_lead is set by lead conversion only');
+        }
+      },
+    };
+
+    it('reports nothing for it, the bundled-fallback rule included', () => {
+      expect(checkHookBodyLowering({ hooks: [flowOnlyHook] })).toEqual([]);
+    });
+
+    it('and the build lowers it to a body that reads the member', () => {
+      const lowering = lowerCallables({ hooks: [{ ...flowOnlyHook }] });
+      expect(lowering.bodyExtractionWarnings).toEqual([]);
+      expect(lowering.bodyExtracted).toBe(1);
+      const lowered = (lowering.lowered.hooks as Array<Record<string, unknown>>)[0];
+      expect((lowered.body as { source: string }).source).toContain('ctx.provenance?.flowRunId');
+    });
+  });
+
   it('truncates the multi-line offending-source dump to one line', () => {
     const [issue] = checkHookBodyLowering({ hooks: [forbiddenTokenHook] });
     expect(issue.message).not.toContain('--- offending body source ---');
 
@@ -474,21 +474,13 @@ const FORBIDDEN_PATTERNS: Array<{ rx: RegExp; reason: string; face?: LoweringFac
   // are measured against the HOOK context; the action face's lowering is
   // unchanged.
   //
-  // `provenance` is the silent half, like `submitted`: a guard on
-  // `ctx.provenance?.flowRunId` reads `undefined` once lowered and evaluates as
-  // if the write had no origin. ⛔ Marshalling it into the VM instead is a body
-  // contract decision (the body face is declared key by key), not a fix to make
-  // here — the same posture `dispatch.scope` records above.
-  {
-    rx: hookContextMemberRx('provenance'),
-    face: 'hook',
-    reason:
-      '`ctx.provenance` is not reachable from a sandboxed body — the VM\'s `ctx` is assembled key by key '
-      + 'and does not carry the write\'s provenance, so it reads `undefined` there: a guard written on '
-      + '`ctx.provenance.flowRunId` or `ctx.provenance.attributedUserId` evaluates as if the write had no '
-      + 'origin, and reaching into it is a TypeError at run time. A body has no equivalent today; leave '
-      + 'this handler bundled so it runs in-process, where `ctx.provenance` carries the server-stamped marks',
-  },
+  // `provenance` WAS the silent half of this family, like `submitted`, and is
+  // no longer a member of it: since #25905 `buildSandboxContext` carries the
+  // declared `HookContextSchema.provenance` across the sandbox boundary (its
+  // three members, each a string or absent, frozen in the VM), so a body reads
+  // `ctx.provenance?.flowRunId` exactly as an in-process handler does and a
+  // handler reading it lowers. The enumeration pin
+  // (test/lowered-body-face-enumeration.test.ts) holds that classification.
   // `ql` and `transaction` are live host objects — the engine, a driver
   // transaction handle — that a copy into the VM heap cannot carry, the
   // `.sudo(` shape one level up: real in-process, absent from the body.
 
@@ -296,9 +296,6 @@ describe('capability inference follows the rebound names', () => {
 
 describe('the hook-context members the enumeration found unrefused (#22837)', () => {
   it.each([
-    ['provenance', async (ctx: any) => { if (ctx.provenance?.flowRunId) ctx.input.note = 'flow'; }],
-    ['provenance', async (ctx: any) => { const { provenance } = ctx; ctx.input.note = String(provenance); }],
-    ['provenance', async ({ input, provenance }: any) => { input.note = String(provenance?.attributedUserId); }],
     ['ql', async (ctx: any) => { await ctx.ql.find('t', {}); }],
     ['ql', async (ctx: any) => { const c = ctx; await c['ql'].find('t', {}); }],
     ['transaction', async (ctx: any) => { ctx.input.note = ctx.transaction ? 'tx' : 'none'; }],
@@ -309,6 +306,17 @@ describe('the hook-context members the enumeration found unrefused (#22837)', ()
     expect(err.message).toContain(`\`ctx.${member}\``);
   });
 
+  // [#25905] `provenance` left this family: the body face now carries it, so
+  // every spelling that used to be refused lowers — the parameter-destructured
+  // one through the rebind prologue, like any other carried member.
+  it.each([
+    async (ctx: any) => { if (ctx.provenance?.flowRunId) ctx.input.note = 'flow'; },
+    async (ctx: any) => { const { provenance } = ctx; ctx.input.note = String(provenance); },
+    async ({ input, provenance }: any) => { input.note = String(provenance?.attributedUserId); },
+  ])('lowers a `ctx.provenance` read (%#), which the body face carries', (fn) => {
+    expect(() => lower(fn)).not.toThrow();
+  });
+
   it('does NOT refuse the body face\'s own transaction route, or a field of the same name', () => {
     const lowered: Fn[] = [
       async (ctx: any) => { await ctx.api.transaction(async () => { await ctx.api.object('t').insert({}); }); },
 
@@ -279,6 +279,9 @@ describe('the lowered body face, against the in-process HookContext (#22837)', (
     expect(inProcess.get('dispatch')).toEqual(new Set(['mode', 'index', 'scope']));
     expect(body.get('dispatch')).toEqual(new Set(['mode', 'index']));
     expect(body.get('session')).toBe('passthrough');
+    // [#25905] Carried member by member, so a member the spec adds to it later is seen as absent.
+    expect(inProcess.get('provenance')).toEqual(new Set(['flowRunId', 'attributedUserId', 'performedByClientId']));
+    expect(body.get('provenance')).toEqual(new Set(['flowRunId', 'attributedUserId', 'performedByClientId']));
     // A tombstone is no member: `session.roles` is `retiredKey(…)`.
     expect(inProcess.get('session')).not.toContain('roles');
     expect(absent.length).toBeGreaterThan(0);
@@ -306,16 +309,11 @@ describe('the lowered body face, against the in-process HookContext (#22837)', (
     }
   });
 
-  // The measured state on the base of #22837, so a reader sees the classification
-  // without running the derivation — and so a member moving class is a visible diff.
-  it('classifies today: one exception, five refusals', () => {
-    expect(absent).toEqual(['dispatch.scope', 'id', 'provenance', 'ql', 'submitted', 'transaction']);
-    expect(absent.filter((p) => refusalOf(p) !== null)).toEqual([
-      'dispatch.scope',
-      'provenance',
-      'ql',
-      'submitted',
-      'transaction',
-    ]);
+  // The measured state, so a reader sees the classification without running the
+  // derivation — and so a member moving class is a visible diff. `provenance`
+  // left the absent set at #25905, when the body face started carrying it.
+  it('classifies today: one exception, four refusals', () => {
+    expect(absent).toEqual(['dispatch.scope', 'id', 'ql', 'submitted', 'transaction']);
+    expect(absent.filter((p) => refusalOf(p) !== null)).toEqual(['dispatch.scope', 'ql', 'submitted', 'transaction']);
   });
 });
@@ -1206,6 +1206,22 @@ function buildSandboxContext(
     if ('where' in bag) inputOptions.where = bag.where;
   }
 
+  // [#25905] The declared write provenance (`HookContextSchema.provenance`),
+  // carried across the sandbox boundary BY CONTRACT, so a lowered body can tell
+  // a flow data node's write (`flowRunId`) from a user's own write exactly as an
+  // in-process handler does. Projected member by member, each in its declared
+  // shape (a string) only — the same unrecognised-shape rule as `dispatch`
+  // above — and the whole key left ABSENT when nothing survives, which is what
+  // the engine face carries on a write with no origin. The source is the
+  // engine's own `buildProvenance()` output, read off the execution context and
+  // never off the payload, so nothing a request submits reaches it.
+  const provenanceRaw = engineCtx?.provenance;
+  const provenance = declaredStringMarks({
+    flowRunId: provenanceRaw?.flowRunId,
+    attributedUserId: provenanceRaw?.attributedUserId,
+    performedByClientId: provenanceRaw?.performedByClientId,
+  });
+
   return {
     input: inputSnapshot ?? {},
     // Preserve `undefined` for `previous` on insert events so hooks can
@@ -1255,10 +1271,27 @@ function buildSandboxContext(
     // keeps no envelope key for this fact at all, so `ctx.api` carries nothing
     // a body could sniff instead.
     ...(engineCtx?.referentialCascadeDelete === true ? { referentialCascadeDelete: true } : {}),
+    provenance,
     crypto: globalThis.crypto,
   };
 }
 
+/**
+ * The string-valued members of `marks`, or `undefined` when none is a string —
+ * so a member in any other shape is left absent rather than guessed at, and an
+ * all-absent envelope is no envelope at all.
+ */
+function declaredStringMarks<K extends string>(
+  marks: Record<K, unknown>,
+): Partial<Record<K, string>> | undefined {
+  const out: Partial<Record<K, string>> = {};
+  for (const key of Object.keys(marks) as K[]) {
+    const value = marks[key];
+    if (typeof value === 'string') out[key] = value;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
 function buildActionSandboxContext(
   actionCtx: any,
   ql: any,