@frontera-sdk/automation 1.43.9 → 1.44.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/automation",
-  "version": "1.43.9",
+  "version": "1.44.0",
   "description": "Author Frontera automations: manifest, triggers and the typed handler contract.",
   "keywords": [
     "frontera",
@@ -38,7 +38,7 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@frontera-sdk/blueprint": "1.43.6",
+    "@frontera-sdk/blueprint": "1.43.10",
     "cron-parser": "^5.0.6"
   }
 }

package/src/index.ts

@@ -1,7 +1,14 @@
 export { automation } from './define'
 export { validateManifest } from './manifest'
 export type { ValidationResult } from './manifest'
-export { duplicateStepMessage, missingGrantMessage } from './messages'
+export {
+  duplicateStepMessage,
+  duplicateSubmissionMessage,
+  emptySubmissionKeyMessage,
+  lostStepRowMessage,
+  missingGrantMessage,
+  submitOutsideStepMessage,
+} from './messages'
 export { createTestContext } from './testing'
 export type { TestCall, TestContext, TestContextOptions } from './testing'
 export type * from './types'

package/src/manifest.ts

@@ -33,11 +33,22 @@ const HOST_RE = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0
 // and then never be satisfiable — no such secret can be created. A validator that
 // accepts the unsatisfiable is worse than one that is strict.
 const SECRET_NAME_RE = /^[A-Z][A-Z0-9_]*$/
+// Matches `apiNameSchema` in the Blueprint Action definition schema exactly.
+// Same reasoning as SECRET_NAME_RE: a looser grammar here would accept
+// `governed:Approve_Invoice`, validate cleanly, and name an Action that can
+// never exist — no published Action carries that apiName, so the grant is
+// unsatisfiable and the automation fails at its first submit instead of at
+// deploy.
+const ACTION_API_NAME_RE = /^[a-z][A-Za-z0-9]{0,99}$/
 
 /** Namespaces whose value is not a SEGMENT. */
 const TYPED_NAMESPACES: Record<string, { re: RegExp; hint: string }> = {
   http: { re: HOST_RE, hint: 'a hostname, e.g. "http:api.stripe.com" (no scheme, no path, no wildcard)' },
   secret: { re: SECRET_NAME_RE, hint: 'a workspace secret name, e.g. "secret:STRIPE_KEY"' },
+  governed: {
+    re: ACTION_API_NAME_RE,
+    hint: 'one published Action apiName, e.g. "governed:approveInvoice" (camelCase, no wildcard)',
+  },
 }
 
 const KNOWN_KEYS = new Set([

package/src/messages.ts

@@ -1,5 +1,5 @@
 /**
- * The two things an author reads when the platform turns their code away.
+ * Everything an author reads when the platform turns their code away.
  *
  * They live in the SDK, not in the runner, because three surfaces have to say
  * exactly the same sentence: the runner refusing a call before it makes it, the
@@ -34,3 +34,75 @@ export function duplicateStepMessage(name: string): string {
     `ctx.step.run(\`${name}:\${i}\`, ...)`
   )
 }
+
+/**
+ * A submit inside a step whose own row never recorded.
+ *
+ * Recording a step is contractually non-fatal — telemetry must not fail a run —
+ * so the id comes back empty and everything else carries on. A submission
+ * cannot: the row is what the idempotency key is derived from, and improvising
+ * one is how the same effect happens twice. Named here rather than left to the
+ * service's generic invalid-submission, which would blame the payload.
+ */
+export function lostStepRowMessage(stepName: string): string {
+  return (
+    `ctx.action.submit cannot run in step "${stepName}": the step's own record failed to write, ` +
+    'so there is nothing stable to key the submission on and it is refused rather than sent ' +
+    'twice. This is a transient service failure — retry the run.'
+  )
+}
+
+/**
+ * The same Action submitted twice from one step with no way to tell them apart.
+ *
+ * Refused HERE, locally, rather than left to the write plane, because the plane
+ * cannot refuse it: two identical submissions derive one idempotency key AND
+ * one semantic fingerprint, so it replays the first request and answers both
+ * calls with the same request id. Nothing errors, one effect happens, and the
+ * run reports success — the failure mode a batch loop hits on its second row
+ * and not on a one-row fixture.
+ *
+ * Naming the remedy matters more than usual: `submissionKey` is the one field
+ * an author has to reach for to fix this, and it is not guessable from a 409.
+ */
+export function duplicateSubmissionMessage(apiName: string): string {
+  return (
+    `Step already submitted "${apiName}" with the same submissionKey. Two submissions the ` +
+    'platform cannot tell apart become ONE request — the plane replays the first and the second ' +
+    'effect never happens. If this is a batch, give each submission a distinct submissionKey ' +
+    "keyed on what it acts on: ctx.action.submit({ action: '" + apiName + "', submissionKey: " +
+    'row.id, ... }). If it is a retry, it is already idempotent — drop the loop.'
+  )
+}
+
+/**
+ * An empty `submissionKey`.
+ *
+ * Refused rather than treated as absent, and refused in both layers: the
+ * service rejects it by name, so folding it into the no-key identity here
+ * would make the SDK and the service disagree about what the author asked for.
+ */
+export function emptySubmissionKeyMessage(apiName: string): string {
+  return (
+    `ctx.action.submit("${apiName}") was given an empty submissionKey. Omit it entirely to mean ` +
+    '"this step submits once", or pass a value identifying what this submission acts on.'
+  )
+}
+
+/**
+ * `ctx.action.submit` called outside a step.
+ *
+ * States the consequence rather than the rule, because the rule on its own
+ * reads as ceremony: code outside a step runs again after EVERY step the
+ * handler completes, so a submit there is not one submission with a retry
+ * risk — it is one submission per step boundary, every time the run resumes.
+ * The step row is also what the idempotency key is derived from, so there is
+ * nothing to derive one from out here.
+ */
+export function submitOutsideStepMessage(apiName: string): string {
+  return (
+    `ctx.action.submit("${apiName}") must be called inside ctx.step.run. Code outside a step ` +
+    're-executes every time the run resumes, so this would submit once per step boundary. ' +
+    `Wrap it: ctx.step.run('submit-${apiName}', () => ctx.action.submit({ ... }))`
+  )
+}

package/src/runtime-context.ts

@@ -20,8 +20,14 @@ import { AsyncLocalStorage } from 'node:async_hooks'
 import {
   duplicateStepMessage as duplicateStepMessageText,
   missingGrantMessage as missingGrantMessageText,
+  submitOutsideStepMessage as submitOutsideStepMessageText,
+  lostStepRowMessage as lostStepRowMessageText,
+  duplicateSubmissionMessage as duplicateSubmissionMessageText,
+  emptySubmissionKeyMessage as emptySubmissionKeyMessageText,
 } from './messages'
 import type {
+  ActionSubmission,
+  ActionSubmitResult,
   AutomationContext,
   BlueprintQueryOptions,
   BlueprintQueryResult,
@@ -89,7 +95,14 @@ interface Deps {
   runnerToken?: string
 }
 
-export { duplicateStepMessage, missingGrantMessage } from './messages'
+export {
+  duplicateStepMessage,
+  duplicateSubmissionMessage,
+  emptySubmissionKeyMessage,
+  lostStepRowMessage,
+  missingGrantMessage,
+  submitOutsideStepMessage,
+} from './messages'
 
 export class DuplicateStepNameError extends Error {
   constructor(readonly stepName: string) {
@@ -139,7 +152,20 @@ export function buildContext(deps: Deps): AutomationContext {
    * `b` depending on interleaving. This is per-run, not module-global: two runs
    * in one process must never see each other's scope.
    */
-  const stepScope = new AsyncLocalStorage<{ stepId: string }>()
+  const stepScope = new AsyncLocalStorage<{
+    stepId: string
+    stepName: string
+    /**
+     * `action` + `submissionKey` for every submit this step body has made.
+     *
+     * The write plane CANNOT catch a repeat: two identical submissions derive
+     * one key and one semantic fingerprint, so it replays the first request and
+     * answers both calls with the same id — no error, one effect, a green run.
+     * The check has to be local, and per step EXECUTION so that a genuine
+     * resumption or retry (which re-enters the body from scratch) is unaffected.
+     */
+    submitted: Set<string>
+  }>()
 
   /**
    * Append a row to the run's audit trail, returning the id the service gave it.
@@ -301,7 +327,16 @@ export function buildContext(deps: Deps): AutomationContext {
       })
       const t0 = Date.now()
       try {
-        const out = await stepScope.run({ stepId }, fn)
+        // `stepName` rides alongside `stepId` because `ctx.action.submit` needs
+        // the NAME, not the row id: the id is fresh on every execution, and an
+        // idempotency key derived from it would differ on each resumption —
+        // which is the exact duplicate-submission this scope exists to prevent.
+        // The service reads the name off the row rather than trusting this
+        // copy; it travels here only so a refusal can name it.
+        const out = await stepScope.run(
+          { stepId, stepName: name, submitted: new Set<string>() },
+          fn,
+        )
         await completeStep(stepId, { status: 'ok', durationMs: Date.now() - t0 })
         return out
       } catch (err) {
@@ -366,6 +401,98 @@ export function buildContext(deps: Deps): AutomationContext {
         }) as Promise<HttpResponse>,
     },
 
+    action: {
+      submit: (request: ActionSubmission) =>
+        step('action', `action:${request.action}`, async () => {
+          // Step scope BEFORE the grant. Both are the author's mistake, but this
+          // one is structural: a submit outside a step is wrong even with every
+          // grant in place, and the remedy is a code change rather than a
+          // manifest change. Naming the manifest first would send them to the
+          // wrong file.
+          const scope = stepScope.getStore()
+          if (!scope) throw new Error(submitOutsideStepMessageText(request.action))
+          // A step whose own row was lost cannot be submitted from. `recordStep`
+          // is contractually non-fatal and hands back an empty id, which is
+          // right for telemetry — one lost row must not cost the calls made
+          // inside it — but a submission has nothing to key on without it, and
+          // improvising a key is how an effect happens twice. Refused HERE so
+          // the cause is named; the service would otherwise see an empty string
+          // and answer with a generic invalid-submission.
+          if (!scope.stepId) throw new Error(lostStepRowMessageText(scope.stepName))
+          // NUL-joined because both halves are author strings; `a:b` with no
+          // key must not collide with `a` keyed `b`.
+          // Refused locally, matching the service's own field-named rejection
+          // — folding `''` into the no-key identity would make the two layers
+          // disagree about what the author asked for.
+          if (request.submissionKey !== undefined && request.submissionKey.length === 0) {
+            throw new Error(emptySubmissionKeyMessageText(request.action))
+          }
+          // Ahead of the reservation, and synchronous so check-and-reserve still
+          // land in one tick. Below it, a missing grant left the identity
+          // reserved and the author's next attempt was told they had duplicated
+          // a submission that never left the process — pointing at
+          // `submissionKey` when the fix is one line in the manifest. A call
+          // that is both ungranted and a duplicate now reports the grant, which
+          // is the more actionable of the two.
+          requireGrant(`governed:${request.action}`)
+          const submissionIdentity = `${request.action}\u0000${request.submissionKey ?? ''}`
+          // RESERVE, synchronously. The check and the record must land in one
+          // tick: with an await between them, `Promise.all([submit(x),
+          // submit(x)])` passes both checks before either records, both reach
+          // the plane, and — same key, same fingerprint — the plane replays the
+          // first for the second. Two calls, one effect, a green run, which is
+          // the exact failure this guard exists to prevent.
+          //
+          // Released again in the catch below, so a submission that never
+          // landed does not burn its identity and the author's retry loop still
+          // works. Reserve-then-release is what satisfies both at once.
+          if (scope.submitted.has(submissionIdentity)) {
+            throw new Error(duplicateSubmissionMessageText(request.action))
+          }
+          scope.submitted.add(submissionIdentity)
+          // The step ROW id, which the service issued. The service resolves the
+          // row, takes the step NAME off it, and derives the key from that — so
+          // what identifies the submission comes from the database rather than
+          // from this process. No ordinal: a positional one made an in-body
+          // retry mint a fresh key and duplicate the effect, and reordered
+          // concurrent submits bind each other's keys. `submissionKey` is how an
+          // author says two submissions are genuinely two.
+          let res: Response
+          try {
+            res = await scoped('/ctx/action-submit', {
+              method: 'POST',
+              body: JSON.stringify({ ...request, stepId: scope.stepId }),
+            })
+          } catch (err) {
+            // Never reached the service. Release, so a retry is a retry rather
+            // than a duplicate accusation for a step that submitted zero times.
+            scope.submitted.delete(submissionIdentity)
+            throw err
+          }
+          if (!res.ok) {
+            // Refused, so nothing was bound to this identity. A 5xx is the
+            // interesting case: the author catches it and submits again, and
+            // that second call must be allowed through to the plane, where the
+            // key — unchanged — makes it a replay rather than a second effect.
+            scope.submitted.delete(submissionIdentity)
+            throw new Error(`ctx.action.submit → ${res.status} ${await refusal(res)}`)
+          }
+          try {
+            return ((await res.json()) as { data: ActionSubmitResult }).data
+          } catch (err) {
+            // The submission LANDED, so keeping the reservation would be
+            // defensible — but the reasoning that releases a 503 applies here
+            // with more force: the key is unchanged, so a resubmit can only
+            // replay, and replaying is the only way the author recovers a
+            // request id they never received. Keeping it ends the run accusing
+            // them of two submissions when there was one and an unreadable
+            // answer.
+            scope.submitted.delete(submissionIdentity)
+            throw err
+          }
+        }) as Promise<ActionSubmitResult>,
+    },
+
     blueprint: {
       query: <T = Record<string, unknown>>(objectType: string, options?: BlueprintQueryOptions) =>
         step('blueprint', `query:${objectType}`, async () => {

package/src/testing.ts

@@ -1,5 +1,14 @@
-import { duplicateStepMessage, missingGrantMessage } from './messages'
+import { AsyncLocalStorage } from 'node:async_hooks'
+import {
+  duplicateStepMessage,
+  duplicateSubmissionMessage,
+  emptySubmissionKeyMessage,
+  missingGrantMessage,
+  submitOutsideStepMessage,
+} from './messages'
 import type {
+  ActionSubmission,
+  ActionSubmitResult,
   AutomationContext,
   BlueprintQueryOptions,
   BlueprintQueryResult,
@@ -26,14 +35,25 @@ import type {
  * everything the handler did is recorded on `calls`.
  */
 
+/**
+ * A call REFUSED before it happened is not recorded.
+ *
+ * A missing grant, a missing stub, a submit outside a step, a duplicate
+ * submission — none of these appear in `calls`, because none of them did
+ * anything. A real run differs here in one direction worth knowing: it writes
+ * an errored ctx-call row for a refused `ctx.action.submit`, so the Console
+ * trace shows the attempt where this list does not. Assert on the thrown error
+ * for a refusal, and on `calls` for what ran.
+ */
 export interface TestCall {
-  kind: 'step' | 'log' | 'agent' | 'http' | 'blueprint'
-  /** Step name, log message, agent slug, URL, or object type. */
+  kind: 'step' | 'log' | 'agent' | 'http' | 'blueprint' | 'action'
+  /** Step name, log message, agent slug, URL, object type, or Action apiName. */
   label: string
   /** Present on a step: how it ended. */
   status?: 'ok' | 'error'
 }
 
+
 export interface TestContextOptions {
   runId?: string
   workspaceId?: string
@@ -55,6 +75,19 @@ export interface TestContextOptions {
   /** Rows per object type. An unstubbed type returns no rows, which is a real
    *  answer and usually the branch worth testing. */
   blueprint?: Record<string, BlueprintQueryResult<never> | BlueprintQueryResult<Record<string, unknown>>>
+  /**
+   * Per-apiName Action outcomes. An unstubbed Action throws rather than
+   * answering.
+   *
+   * Throws for the same reason the agent stub does, and the reason is sharper
+   * here: the returned `lifecycle` is a branch an author writes code against —
+   * `awaiting_approval` means a human still has to decide — so inventing
+   * `ready` would silently pick one arm and pass.
+   */
+  actions?: Record<
+    string,
+    (request: ActionSubmission) => Promise<ActionSubmitResult> | ActionSubmitResult
+  >
 }
 
 export interface TestContext {
@@ -71,6 +104,21 @@ export function createTestContext(options: TestContextOptions = {}): TestContext
   const steps: string[] = []
   const logs: TestContext['logs'] = []
   const seenNames = new Set<string>()
+  /**
+   * Which step the running code is inside.
+   *
+   * `AsyncLocalStorage`, matching the real context exactly, and NOT a stack.
+   * A stack gets the concurrent case wrong in the direction that matters:
+   * `Promise.all([ctx.step.run('a', …), ctx.action.submit(…)])` is legal, and
+   * with a shared mutable stack the bare submit sees `a` open and is allowed —
+   * so the test double passes what production refuses, which is the one failure
+   * mode a test double must not have.
+   *
+   * Enforced here for the same reason grants and duplicate names are: a rule
+   * the unit test does not apply is a rule the author meets for the first time
+   * in a deployed run.
+   */
+  const stepScope = new AsyncLocalStorage<{ stepName: string; submitted: Set<string> }>()
 
   const requireGrant = (grant: string): void => {
     // No grant list means the test is not about grants. Enforcing an empty list
@@ -88,14 +136,16 @@ export function createTestContext(options: TestContextOptions = {}): TestContext
         if (seenNames.has(name)) throw new Error(duplicateStepMessage(name))
         seenNames.add(name)
         steps.push(name)
-        try {
-          const out = await fn()
-          calls.push({ kind: 'step', label: name, status: 'ok' })
-          return out
-        } catch (err) {
-          calls.push({ kind: 'step', label: name, status: 'error' })
-          throw err
-        }
+        return await stepScope.run({ stepName: name, submitted: new Set<string>() }, async () => {
+          try {
+            const out = await fn()
+            calls.push({ kind: 'step', label: name, status: 'ok' })
+            return out
+          } catch (err) {
+            calls.push({ kind: 'step', label: name, status: 'error' })
+            throw err
+          }
+        })
       },
     },
 
@@ -145,6 +195,50 @@ export function createTestContext(options: TestContextOptions = {}): TestContext
       },
     },
 
+    action: {
+      async submit(request: ActionSubmission): Promise<ActionSubmitResult> {
+        const scope = stepScope.getStore()
+        if (!scope) throw new Error(submitOutsideStepMessage(request.action))
+        // The batch loop is the shape this catches, and a one-row fixture never
+        // reaches it — so the double has to enforce it or an author meets it
+        // for the first time on their second production row, after the first
+        // has already been applied.
+        if (request.submissionKey !== undefined && request.submissionKey.length === 0) {
+          throw new Error(emptySubmissionKeyMessage(request.action))
+        }
+        requireGrant(`governed:${request.action}`)
+        const stub = options.actions?.[request.action]
+        // Both refusals that mean "this never happened" come BEFORE the
+        // reservation, matching the runtime's grant check: reserving first left
+        // an author who fixed the missing stub and re-ran a loop facing a
+        // duplicate accusation for a call that never answered.
+        if (!stub) {
+          throw new Error(
+            `No action stub for "${request.action}". Pass actions: { '${request.action}': ` +
+              "() => ({ requestId: 'req-1', lifecycle: 'ready' }) } to createTestContext.",
+          )
+        }
+        const submissionIdentity = `${request.action}\u0000${request.submissionKey ?? ''}`
+        // Reserved synchronously and released on failure, matching the runtime
+        // exactly. A double that checked and recorded across an await would let
+        // `Promise.all([submit(x), submit(x)])` through — and a double that
+        // permits what production refuses is the one failure mode a double must
+        // not have.
+        if (scope.submitted.has(submissionIdentity)) {
+          throw new Error(duplicateSubmissionMessage(request.action))
+        }
+        scope.submitted.add(submissionIdentity)
+        calls.push({ kind: 'action', label: request.action })
+        try {
+          return await stub(request)
+        } catch (err) {
+          // A throwing stub stands in for a submission that never landed.
+          scope.submitted.delete(submissionIdentity)
+          throw err
+        }
+      },
+    },
+
     blueprint: {
       async query<T = Record<string, unknown>>(
         objectType: string,

package/src/types.ts

@@ -41,6 +41,13 @@ export type Grant =
   /** The NAME of a workspace secret. Its VALUE never enters this process: you
    *  name it, the platform injects it server-side. */
   | `secret:${string}`
+  /** One EXACT published Action apiName. `governed:approveInvoice` permits
+   *  submitting that Action and nothing else.
+   *
+   *  Not wildcardable, for the same reason `http:` is not: a reviewer reading
+   *  `governed:*` would have to know the whole current Action catalog — and the
+   *  answer changes with every release — to know what the automation may do. */
+  | `governed:${string}`
 
 export interface AutomationManifest {
   name: string
@@ -126,7 +133,112 @@ export interface StepApi {
   run<T>(name: string, fn: () => Promise<T>): Promise<T>
 }
 
-/** Read-only for now. `governed`/`notify` arrive with Governed Writes. */
+/**
+ * The 13 lifecycle states a governed Action Request can hold.
+ *
+ * A deliberate copy of a WIRE contract, not shared code — same reasoning as
+ * `RegistryEntry` in the runner: this package must install from public npm with
+ * a three-package dependency list, and importing the service's own enum would
+ * drag drizzle and the schema into an author's `bun install`. The service's
+ * `ACTION_REQUEST_LIFECYCLE_STATES` is the source of truth; the response proves
+ * the two agree.
+ */
+export type ActionRequestLifecycle =
+  | 'received'
+  | 'awaiting_approval'
+  | 'ready'
+  | 'executing'
+  | 'finalizing'
+  | 'succeeded'
+  | 'rejected'
+  | 'expired'
+  | 'cancelled'
+  | 'failed'
+  | 'outcome_unknown'
+  | 'awaiting_resolution'
+  | 'closed_unknown'
+
+/**
+ * `subjectRef` and `expectedSubjectVersion` are paired deliberately.
+ *
+ * The plane requires BOTH for an Action over an existing subject and refuses
+ * BOTH for a create Action, so independently-optional fields would let an
+ * author write a submission that cannot be accepted and only find out at
+ * runtime. Which arm applies is the Action's decision, not the caller's — read
+ * it off the Action's `subject.mode`.
+ */
+export type ActionSubmission = {
+  /** Published Action apiName. Requires a `governed:<apiName>` grant. */
+  action: string
+  input: Record<string, unknown>
+  /** Required when the Action's definition says so. */
+  reason?: string
+  /**
+   * Tells two submissions from the SAME step apart.
+   *
+   * A step submits once by default. The idempotency key is derived from the run
+   * and the step alone, so a submission re-reached by a resumption or by a
+   * retried attempt is the SAME key and the plane hands back the original
+   * request instead of making a second one. Your own retry loop behaves the
+   * same way: a submission that FAILED is not recorded, so submitting again
+   * after catching a transport error re-sends and the plane replays.
+   *
+   * What you cannot do by default is submit twice on purpose. Two submissions
+   * the platform cannot tell apart derive one key AND one semantic
+   * fingerprint, so the plane would replay the first and answer both calls with
+   * the same id — no error, one effect, a green run. Rather than let that
+   * happen, the second call is refused before it leaves your process, naming
+   * this field.
+   *
+   * Pass a distinct `submissionKey` per submission to say you meant it — a
+   * business identity is the right value, not a counter:
+   *
+   * ```ts
+   * await ctx.step.run('flag', async () => {
+   *   for (const row of rows) {
+   *     await ctx.action.submit({
+   *       action: 'flagForAudit',
+   *       // Stable for THIS row across every attempt. An array index is not:
+   *       // if the re-read returns the rows in another order, an index would
+   *       // bind row B's submission to row A's key.
+   *       submissionKey: row.id,
+   *       input: { rowId: row.id },
+   *     })
+   *   }
+   * })
+   * ```
+   *
+   * It must be stable across attempts for the same intended submission, which
+   * is why the platform cannot derive it for you — only your code knows which
+   * of two submissions is "the same one again". An empty string is refused;
+   * omit it entirely to mean "this step submits once".
+   */
+  submissionKey?: string
+} & (
+  | {
+    subjectRef: { objectTypeId: string; objectId: string }
+    /** The version you believe the subject is at: a submission built from a
+     *  stale read must lose rather than overwrite. */
+    expectedSubjectVersion: string
+  }
+  | { subjectRef?: never; expectedSubjectVersion?: never }
+)
+
+export interface ActionSubmitResult {
+  requestId: string
+  /**
+   * Where the request stopped, NOT whether the effect happened.
+   *
+   * `ready` means accepted and queued for dispatch. `awaiting_approval` means
+   * the Action requires a human and one has not decided yet — a normal return,
+   * not an error. Neither is a completed business fact.
+   */
+  lifecycle: ActionRequestLifecycle
+}
+
+/**
+ * `notify` still arrives with a later slice; `governed` is here.
+ */
 export interface AutomationContext {
   runId: string
   workspaceId: string
@@ -163,6 +275,41 @@ export interface AutomationContext {
    * resumed.
    */
   step: StepApi
+  action: {
+    /**
+     * Ask the governed write plane to perform one named business change.
+     *
+     * This is the ONLY way an automation changes a system of record. Your code
+     * never holds a write handle: you describe the change, and the plane
+     * authorizes it, approves it if the Action says so, dispatches it, confirms
+     * it and records it. An Action that declares `approval: required` cannot be
+     * talked out of it by the caller.
+     *
+     * Two rules:
+     *
+     * 1. **It must be called inside `ctx.step.run`.** Code outside a step
+     *    re-executes after every step boundary, so a submit sitting there would
+     *    fire once per boundary. Inside a step it runs once, and the step —
+     *    identified by the row the service itself issued — is what makes the
+     *    idempotency key stable across resumption and across a retried run.
+     *
+     *    The service checks this rather than taking your word for it: the
+     *    submission carries a step row id, and a submission whose id names no
+     *    open step of this run is refused. What that check cannot do is make a
+     *    determined bundle behave — your code runs unsandboxed in the same
+     *    process as the run token, so it could open a step row purely to submit
+     *    inside it. The bound is that such a step is a real row and shows up in
+     *    the run trace, not that it is impossible.
+     * 2. **It never waits.** It returns as soon as the request is durably
+     *    accepted. A run has nobody to ask for an approval and ten minutes to
+     *    live, so blocking on a human is not something this can offer —
+     *    `awaiting_approval` is a normal return value.
+     *
+     * The returned `lifecycle` is where the request stopped, not proof of
+     * effect. Poll the ledger, or let the Action's Business Event tell you.
+     */
+    submit(request: ActionSubmission): Promise<ActionSubmitResult>
+  }
 }
 
 export interface HttpRequest {