@sixb/core 0.1.17 → 0.1.19

package/src/actions/run/run-action.ts

@@ -0,0 +1,170 @@
+import { reportRunFailure } from "../../error-reporting/capability"
+import { createSixbError } from "../../errors/internal"
+import type { ActionRunFailure, RecordActionRunInput } from "../../storage"
+import { ActionRunError } from "../../storage"
+import type { CommittedActionRun } from "./edits-commit"
+import { runActionEffects } from "./effects"
+import { isActionPhaseFailure, toActionRunFailure, unwrapActionPhaseError } from "./normalize"
+import { executeActionPhases } from "./phases"
+import type { ActionRunSignals } from "./signals"
+import { ActionRunState, type FailedActionRunRecord } from "./state"
+import type { ActionRunContext, ActionRunOutcome, RunActionInput } from "./types"
+
+/**
+ * A run that ended, but whose terminal record could not be written.
+ *
+ * It carries that record, so that whoever reports this error still reports how the run ended. Its
+ * cause is the error that kept the record from being written.
+ */
+export class UnrecordedActionRunError extends Error {
+  override readonly name = "UnrecordedActionRunError"
+
+  constructor(
+    readonly record: RecordActionRunInput,
+    options: { readonly cause: unknown }
+  ) {
+    super(`[Sixb] Action run '${record.id}' ended, but its record could not be written.`, options)
+  }
+}
+
+/**
+ * Execute a requested run to its end, and record it once.
+ *
+ * A run with edits is recorded by the commit of its edits; any other run, succeeded or failed, is
+ * recorded as soon as it ends. The run's effects are left to the caller to start: see
+ * {@link ActionRunOutcome.effects}. This rejects when the run cannot execute here, or with an
+ * {@link UnrecordedActionRunError} when its record cannot be written.
+ */
+export async function runAction(input: RunActionInput): Promise<ActionRunOutcome> {
+  const { runtime, run, signals } = input
+  const ids = { actionId: run.actionId, runId: run.id }
+
+  if (run.projectId !== runtime.id) {
+    throw createSixbError(
+      "internal.unexpected",
+      `[Sixb] Action run '${run.id}' belongs to project '${run.projectId}', not '${runtime.id}'.`,
+      { details: { ...ids, durableProjectId: run.projectId } }
+    )
+  }
+
+  const state = new ActionRunState(run, new Date())
+  const action = runtime.actions.getById(run.actionId)
+  if (!action) {
+    const message = `[Sixb] Unknown action '${run.actionId}'.`
+    const error = createSixbError("internal.unexpected", message, { details: ids })
+    const failure = toActionRunFailure(error, "validation", { ...ids, at: new Date() })
+    return recordFailure(runtime, state.failed(failure), error)
+  }
+
+  let committed: CommittedActionRun | null
+  try {
+    committed = await executeActionPhases({ runtime, action, state, signals })
+  } catch (error) {
+    return recordFailure(runtime, state.failed(runFailure(error, state, signals)), error)
+  }
+
+  if (!committed) return recordRun(runtime, state.succeeded())
+  // A commit that already existed recorded the run with it, for another request.
+  if (!committed.commit.created) return findRecordedRun(runtime, committed.record)
+  const { commit } = committed
+  return {
+    record: committed.record,
+    recorded: true,
+    ...(action.phases.effects
+      ? {
+          effects: () =>
+            runActionEffects({
+              runtime,
+              action,
+              state,
+              commit,
+              startDeadline: () => signals.startEffects(),
+            }),
+        }
+      : {}),
+  }
+}
+
+/**
+ * The failure a run that threw records.
+ *
+ * A failed writeback fails the run with the writeback's own failure. Otherwise, only a run stopped
+ * before its boundary is the caller's or the deadline's doing. Past it, or when a phase classified
+ * its error before anything aborted, the run failed on its own merits.
+ */
+function runFailure(
+  error: unknown,
+  state: ActionRunState,
+  signals: ActionRunSignals
+): ActionRunFailure {
+  if (state.writeback?.status === "failed") return state.writeback.error
+  const stopped =
+    !state.pastBoundary && signals.beforeBoundary.aborted && !isActionPhaseFailure(error)
+  return toActionRunFailure(stopped ? signals.stopReason() : error, state.phase, {
+    actionId: state.run.actionId,
+    runId: state.run.id,
+    at: new Date(),
+  })
+}
+
+/**
+ * Record a failed run, and report its failure to `onError` once this request recorded it. A run its
+ * caller cancelled is not reported: it did not fail on its own.
+ */
+async function recordFailure(
+  runtime: ActionRunContext,
+  record: FailedActionRunRecord,
+  error: unknown
+): Promise<ActionRunOutcome> {
+  const outcome = await recordRun(runtime, record)
+  if (outcome.recorded && record.error.code !== "runtime.cancelled") {
+    reportRunFailure(runtime.errorReporterHost, unwrapActionPhaseError(error), {
+      projectId: runtime.id,
+      runKind: "action",
+      run: { runId: record.id, actionId: record.actionId },
+      failure: record.error,
+    })
+  }
+  return outcome
+}
+
+/**
+ * Write a run's terminal record. A run id is recorded once: when a concurrent request for the same
+ * run id recorded it first, with the same request, its record answers this one too.
+ */
+async function recordRun(
+  runtime: ActionRunContext,
+  record: RecordActionRunInput
+): Promise<ActionRunOutcome> {
+  try {
+    return { record: await runtime.actionRunsStorage.record(record), recorded: true }
+  } catch (error) {
+    if (error instanceof ActionRunError) return findRecordedRun(runtime, record, error)
+    throw new UnrecordedActionRunError(record, { cause: error })
+  }
+}
+
+/**
+ * The record another request wrote for this run. Whether it answers this request is the request's
+ * to decide, under the checks any record it finds gets.
+ */
+async function findRecordedRun(
+  runtime: ActionRunContext,
+  record: RecordActionRunInput,
+  cause?: unknown
+): Promise<ActionRunOutcome> {
+  try {
+    const stored = await runtime.actionRunsStorage.getById({
+      projectId: record.projectId,
+      id: record.id,
+    })
+    if (!stored) {
+      throw (
+        cause ?? new ActionRunError(`[Sixb] Action run '${record.id}' committed without a record.`)
+      )
+    }
+    return { record: stored, recorded: false }
+  } catch (error) {
+    throw new UnrecordedActionRunError(record, { cause: error })
+  }
+}

package/src/actions/run/signals.ts

@@ -0,0 +1,118 @@
+import { createSixbError, isSixbError } from "../../errors/internal"
+
+/** How long an Action run has to reach its irreversible boundary, and its effects after commit. */
+export const ACTION_TIMEOUT_MS = 30_000
+
+/**
+ * How long a stopping process waits for its in-flight Action runs and their effects: a run's
+ * deadline, then its effects' deadline, plus a margin.
+ *
+ * It does not bound a whole run. Edits past the boundary are uninterruptible, and effects start
+ * only once they committed, so a run or its effects can still be executing when the wait ends. A
+ * deployment's kill timeout must exceed this bound.
+ */
+export const ACTION_RUN_DRAIN_TIMEOUT_MS = 2 * ACTION_TIMEOUT_MS + 5_000
+
+export interface ActionRunSignalsInput {
+  readonly actionId: string
+  readonly runId: string
+  /** The caller's cancellation. It applies before the boundary only. */
+  readonly caller?: AbortSignal
+  /** Test-only override of {@link ACTION_TIMEOUT_MS}. */
+  readonly timeoutMs?: number
+}
+
+/**
+ * The cancellation one Action run observes, phase by phase.
+ *
+ * The irreversible boundary is a succeeded writeback, or the commit of an Action without one. Before
+ * it, validation, writeback and edits run under {@link beforeBoundary}, which aborts when the run's
+ * deadline elapses or its caller aborts. After it, edits and commit run under
+ * {@link uninterruptible}: abandoning them would strand an external change that the ontology never
+ * records. Effects run after the commit under a deadline of their own, which
+ * {@link startEffects} starts.
+ *
+ * Cancellation is cooperative: a handler stops early only when it forwards its `signal` to what it
+ * awaits. The run stops waiting for one that does not, wherever abandoning it loses nothing:
+ * validation, edits before the boundary, and effects (`untilAborted`). A writeback is always waited
+ * for, since only its result says whether the external change happened.
+ */
+export class ActionRunSignals {
+  readonly beforeBoundary: AbortSignal
+  /**
+   * Never aborts, for the work that must run to completion once it starts. One per run: whatever
+   * listens to it is released with the run, not kept for the life of the process.
+   */
+  readonly uninterruptible: AbortSignal = new AbortController().signal
+
+  private readonly input: ActionRunSignalsInput
+  private readonly deadline: ActionDeadline
+
+  constructor(input: ActionRunSignalsInput) {
+    this.input = input
+    this.deadline = new ActionDeadline(input, "run")
+    this.beforeBoundary = input.caller
+      ? AbortSignal.any([this.deadline.signal, input.caller])
+      : this.deadline.signal
+  }
+
+  /**
+   * Why the run stopped before its boundary: its deadline's `action.timeout` when the deadline
+   * elapsed first, or else a `runtime.cancelled` error caused by what its caller aborted with.
+   */
+  stopReason(): unknown {
+    const reason = this.beforeBoundary.reason
+    if (isActionTimeout(reason)) return reason
+    return createSixbError(
+      "runtime.cancelled",
+      `[Sixb] Action run '${this.input.runId}' was cancelled by its caller.`,
+      { cause: reason, details: { actionId: this.input.actionId, runId: this.input.runId } }
+    )
+  }
+
+  /**
+   * Start the deadline the run's effects run under. It is independent of the run's own: effects
+   * start after the run is recorded, and the caller of the deadline disposes it once they end.
+   */
+  startEffects(): ActionDeadline {
+    return new ActionDeadline(this.input, "effects")
+  }
+
+  /** Release the run's deadline timer. */
+  dispose(): void {
+    this.deadline.dispose()
+  }
+}
+
+/** A signal that aborts with `action.timeout` once its scope's deadline elapses. */
+export class ActionDeadline {
+  readonly signal: AbortSignal
+  private readonly timer: ReturnType<typeof setTimeout>
+
+  constructor(
+    input: Pick<ActionRunSignalsInput, "actionId" | "runId" | "timeoutMs">,
+    scope: "run" | "effects"
+  ) {
+    const controller = new AbortController()
+    const timeoutMs = input.timeoutMs ?? ACTION_TIMEOUT_MS
+    this.signal = controller.signal
+    this.timer = setTimeout(() => {
+      controller.abort(
+        createSixbError(
+          "action.timeout",
+          `[Sixb] Action run '${input.runId}' exceeded its ${timeoutMs} ms ${scope} deadline.`,
+          { details: { actionId: input.actionId, runId: input.runId } }
+        )
+      )
+    }, timeoutMs)
+  }
+
+  /** Release the deadline timer. */
+  dispose(): void {
+    clearTimeout(this.timer)
+  }
+}
+
+export function isActionTimeout(error: unknown): boolean {
+  return isSixbError(error) && error.code === "action.timeout"
+}

package/src/actions/run/state.ts

@@ -0,0 +1,95 @@
+import type { JsonValue } from "../../json"
+import type {
+  ActionRunFailure,
+  ActionRunPhase,
+  ActionRunWritebackRecord,
+  RecordActionRunInput,
+} from "../../storage"
+import type { PendingActionRun } from "./types"
+
+export type SucceededActionRunRecord = Extract<
+  RecordActionRunInput,
+  { readonly status: "succeeded" }
+>
+export type FailedActionRunRecord = Extract<RecordActionRunInput, { readonly status: "failed" }>
+
+/**
+ * What a run has done so far: the phase it reached and how its writeback ended.
+ *
+ * It lives in memory while the run executes, and nothing about the run is stored before it ends:
+ * its terminal record is built from this state once, when it succeeds or fails.
+ */
+export class ActionRunState {
+  private reached: ActionRunPhase = "validation"
+  private writebackRecord: ActionRunWritebackRecord | undefined
+
+  constructor(
+    readonly run: PendingActionRun,
+    /** When the run started executing, as its handlers and its record see it. */
+    readonly startedAt: Date
+  ) {}
+
+  /** The last phase the run reached. */
+  get phase(): ActionRunPhase {
+    return this.reached
+  }
+
+  get writeback(): ActionRunWritebackRecord | undefined {
+    return this.writebackRecord
+  }
+
+  /** The value a succeeded writeback returned, which edits and effects receive. */
+  get writebackValue(): JsonValue | undefined {
+    return this.writebackRecord?.status === "succeeded" ? this.writebackRecord.result : undefined
+  }
+
+  /**
+   * Whether the run's deadline and caller no longer apply to it.
+   *
+   * True once its writeback succeeded, or once its commit started for an Action without one: from
+   * there the run either commits or fails on its own merits.
+   */
+  get pastBoundary(): boolean {
+    return this.writebackRecord?.status === "succeeded" || this.reached === "commit"
+  }
+
+  /** Enter a phase before the commit. The run is recorded before its effects run. */
+  enter(phase: Exclude<ActionRunPhase, "effects">): void {
+    this.reached = phase
+  }
+
+  /** Keep how the writeback ended. A run calls its writeback once, so this is set once. */
+  recordWriteback(writeback: ActionRunWritebackRecord): void {
+    if (this.writebackRecord) {
+      throw new Error(`[Sixb] Action run '${this.run.id}' already ended its writeback.`)
+    }
+    this.writebackRecord = writeback
+  }
+
+  /** The record of the run succeeding in the phase it reached. */
+  succeeded(finishedAt: Date = new Date()): SucceededActionRunRecord {
+    return { ...this.recordFields(this.reached, finishedAt), status: "succeeded" }
+  }
+
+  /** The record of the run failing with `error`, in the phase the failure names. */
+  failed(error: ActionRunFailure, finishedAt: Date = new Date()): FailedActionRunRecord {
+    return { ...this.recordFields(error.details.phase, finishedAt), status: "failed", error }
+  }
+
+  private recordFields(phase: ActionRunPhase, finishedAt: Date) {
+    const { id, projectId, executionId, actionId, subject, params, idempotencyKey } = this.run
+    return {
+      id,
+      projectId,
+      executionId,
+      actionId,
+      subject,
+      params,
+      idempotencyKey,
+      phase,
+      startedAt: this.startedAt,
+      finishedAt,
+      ...(this.writebackRecord === undefined ? {} : { writeback: this.writebackRecord }),
+    }
+  }
+}

package/src/actions/run/types.ts

@@ -0,0 +1,61 @@
+import type { BlobsRuntime } from "../../blob-storage/execution"
+import type { ConnectorRuntime } from "../../connectors/execution"
+import type { LoggingService } from "../../logging/service"
+import type { ModelsRuntime } from "../../models/generation-types"
+import type { ObjectsRuntime } from "../../objects/execution"
+import type { SixbDefinitions } from "../../runtime/definitions"
+import type { OntologyMutationRuntime } from "../../runtime/ontology-mutations"
+import type { ActionRunRecord, ActionRunStorage, Storage } from "../../storage"
+import type { ActionsRuntime } from "../execution"
+import type { ActionRunSignals } from "./signals"
+
+/** Execution-bound primitives exposed to Action phase handlers. */
+export interface ActionExecutionFacade {
+  readonly models: ModelsRuntime
+  readonly objects: ObjectsRuntime
+  readonly actions: ActionsRuntime
+  readonly connector: ConnectorRuntime
+  readonly blobs: BlobsRuntime
+}
+
+export interface ActionRunContext {
+  readonly id: string
+  readonly errorReporterHost: object
+  readonly logging?: LoggingService
+  readonly storage: Storage
+  readonly actionRunsStorage: ActionRunStorage
+  readonly ontologyMutations: OntologyMutationRuntime
+  readonly sixb: ActionExecutionFacade
+  readonly actions: Pick<SixbDefinitions["actions"], "getById">
+}
+
+/**
+ * A requested run that has not ended: the request it executes, under the durable execution created
+ * for it. Nothing else about it is stored until its terminal record is written.
+ */
+export type PendingActionRun = Pick<
+  ActionRunRecord,
+  "id" | "projectId" | "executionId" | "actionId" | "subject" | "params" | "idempotencyKey"
+>
+
+export interface RunActionInput {
+  readonly runtime: ActionRunContext
+  readonly run: PendingActionRun
+  readonly signals: ActionRunSignals
+}
+
+/** How a request's run ended. */
+export interface ActionRunOutcome {
+  readonly record: ActionRunRecord
+  /**
+   * Whether this request wrote the record. When it did not, a concurrent request for the same run
+   * id recorded the run first, and the record is that request's, whatever it asked for.
+   */
+  readonly recorded: boolean
+  /**
+   * Runs the run's effects and records their outcome. The request starts it once it returns the
+   * record, and does not wait for it. An effects failure does not reject it: it is recorded on the
+   * run.
+   */
+  readonly effects?: () => Promise<void>
+}

package/src/actions/run/writeback.ts

@@ -0,0 +1,79 @@
+import type { JsonValue } from "../../json"
+import { assertJsonValue, cloneJsonValue } from "../../json"
+import type { ActionReadRecorder } from "../read-facade"
+import { isObjectActionDefinition } from "../validation"
+import {
+  type BasePhaseContext,
+  requireObjectTarget,
+  toActionReadFacade,
+  toActionRuntimeFacade,
+} from "./context"
+import { toActionRunFailure, translateActionPhaseError } from "./normalize"
+import type { LoadedObjectTarget, PhaseExecutionBase, RuntimePhaseHandler } from "./phase-types"
+import type { ActionRunState } from "./state"
+
+/**
+ * Calls the Action's writeback, when it has one, and keeps how it ended on the run's state.
+ *
+ * A failed writeback fails the run with the writeback's own failure; a succeeded one is the run's
+ * irreversible boundary.
+ */
+export async function runWritebackPhase(
+  input: PhaseExecutionBase & {
+    readonly state: ActionRunState
+    readonly baseContext: BasePhaseContext
+    readonly objectTarget: LoadedObjectTarget | null
+    readonly reads: ActionReadRecorder
+  }
+): Promise<void> {
+  const handler = input.action.phases.writeback as RuntimePhaseHandler | undefined
+  if (!handler) return
+
+  const { state } = input
+  const ids = { actionId: input.action.id, runId: state.run.id }
+  state.enter("writeback")
+
+  let result: JsonValue
+  try {
+    // Reads are side-effect-free, so the writeback phase can safely enrich its external payload
+    // before the edit batch exists. Object, link-scope, and returned query/list rows share the
+    // edits phase's recorder and are fenced by the same CAS. Query membership and telemetry
+    // history remain call-level snapshots.
+    const context = {
+      ...input.baseContext,
+      signal: input.signal,
+      sixb: toActionRuntimeFacade(input.runtime),
+      read: toActionReadFacade(input.runtime, input.reads),
+    }
+    const rawResult = isObjectActionDefinition(input.action)
+      ? await handler({
+          ...context,
+          target: requireObjectTarget(input.objectTarget, ids).snapshot,
+        })
+      : await handler(context)
+    result = normalizeWritebackResult(rawResult)
+  } catch (error) {
+    const completedAt = new Date()
+    const phaseError = translateActionPhaseError(error, "writeback", {
+      ...ids,
+      signal: input.signal,
+    })
+    state.recordWriteback({
+      status: "failed",
+      completedAt,
+      error: toActionRunFailure(phaseError, "writeback", { ...ids, at: completedAt }),
+    })
+    throw error
+  }
+
+  state.recordWriteback({ status: "succeeded", completedAt: new Date(), result })
+}
+
+function normalizeWritebackResult(result: unknown): JsonValue {
+  if (result === undefined) {
+    return null
+  }
+
+  assertJsonValue(result, "Action writeback result")
+  return cloneJsonValue(result)
+}

package/src/actions/run-authorization.ts

@@ -35,7 +35,7 @@ export async function canDelegationAccessActionRun(input: {
 export async function actionRunBelongsToShareGrant(input: {
   readonly storage: Storage
   readonly projectId: string
-  readonly run: ActionRunRecord
+  readonly run: Pick<ActionRunRecord, "id" | "actionId" | "executionId">
   readonly grantId: string
 }): Promise<boolean> {
   const parent = await findPrimitiveParentRequestExecution({

package/src/actions/run-persistence.ts

@@ -0,0 +1,105 @@
+import { randomUUID } from "node:crypto"
+import type { ActionRunParams, ActionRunRecord, CreateExecutionInput, Storage } from "../storage"
+import { ActionRunError } from "../storage"
+import { actionRunRequestsEqual } from "../storage/action-runs/idempotency"
+import type { ExecutionRecord } from "../storage/executions"
+import type { PendingActionRun } from "./run/types"
+import { createActionRunIdempotencyKey } from "./run-id"
+import type { ActionSubject } from "./types"
+
+/** What a request asks its run id to run. */
+export interface ActionRunRequestPayload {
+  readonly actionId: string
+  readonly subject: ActionSubject
+  readonly params: ActionRunParams
+}
+
+/** A run that already exists under a requested run id, recorded or still executing. */
+export type ExistingActionRun = Pick<
+  ActionRunRecord,
+  "id" | "executionId" | "actionId" | "subject" | "params"
+>
+
+/** Refuses an existing run the requesting caller may not have. */
+export type AssertCanReuseActionRun = (run: ExistingActionRun) => void | Promise<void>
+
+/**
+ * Answer a request with the run that already exists under its run id only when its caller may have
+ * that run, and only for the same request.
+ *
+ * The caller's right to the run is checked first, so that a refused caller learns nothing about it,
+ * not even whether it carries the same request.
+ */
+export async function assertCanReuseActionRun(
+  run: ExistingActionRun,
+  request: {
+    readonly payload: ActionRunRequestPayload
+    readonly assertCanReuse: AssertCanReuseActionRun
+  }
+): Promise<void> {
+  await request.assertCanReuse(run)
+  if (!actionRunRequestsEqual(run, request.payload)) {
+    throw new ActionRunError(
+      `[Sixb] Action run '${run.id}' already exists with a different request payload.`
+    )
+  }
+}
+
+interface PersistActionRunInput {
+  readonly projectId: string
+  readonly storage: Storage
+  readonly runId: string
+  readonly payload: ActionRunRequestPayload
+  readonly createExecution: (executionId: string, runId: string) => Promise<CreateExecutionInput>
+  readonly assertCanReuse: AssertCanReuseActionRun
+  /** Checks that hold only for a run this call creates; a replayed run keeps its accepted params. */
+  readonly assertNewRun?: () => Promise<void>
+}
+
+/** A run this request is to execute, or the record of an earlier request with the same run id. */
+export type PersistedActionRun =
+  | {
+      readonly kind: "new"
+      readonly run: PendingActionRun
+      readonly execution: ExecutionRecord
+    }
+  | { readonly kind: "recorded"; readonly run: ActionRunRecord }
+
+/**
+ * Persist what a requested run needs before it executes: the durable execution it runs under.
+ *
+ * Nothing else is stored before the run ends. A run id that is already recorded must carry the same
+ * request, and its record answers this request without running anything.
+ */
+export async function persistActionRun(input: PersistActionRunInput): Promise<PersistedActionRun> {
+  const { projectId, runId, payload } = input
+  if (!input.storage.actionRuns) {
+    throw new ActionRunError("[Sixb] Action run storage is not configured.")
+  }
+
+  const recorded = await input.storage.actionRuns.getById({ projectId, id: runId })
+  if (recorded) {
+    await assertCanReuseActionRun(recorded, input)
+    return { kind: "recorded", run: recorded }
+  }
+
+  await input.assertNewRun?.()
+  // The execution is immutable provenance, created before the run executes: its record references
+  // it, and so do the commit of its edits and the model calls it makes.
+  const execution = await input.storage.executions.create(
+    await input.createExecution(`exec_${randomUUID()}`, runId)
+  )
+  return {
+    kind: "new",
+    run: {
+      id: runId,
+      projectId,
+      executionId: execution.id,
+      actionId: payload.actionId,
+      subject: payload.subject,
+      params: payload.params,
+      idempotencyKey: createActionRunIdempotencyKey(projectId, runId),
+    },
+    execution,
+  }
+}

package/src/actions/types/context.ts

@@ -61,6 +61,10 @@ export type ActionBinding<TObjectType extends ObjectType = ObjectType> =
 export interface ActionRunPhaseInfo {
   readonly id: string
   readonly startedAt: Date
+  /**
+   * Identifies this run to external systems. Send it as the idempotency key of the external call a
+   * writeback makes, so that call applies once even when it is retried.
+   */
   readonly idempotencyKey: string
 }
 
@@ -180,6 +184,12 @@ export interface BaseActionPhaseContext<TParams extends Record<string, unknown>>
   readonly run: ActionRunPhaseInfo
   readonly params: TParams
   readonly subject: ActionSubject
+  /**
+   * Aborts when the caller cancels the run or it runs out of time: a run has 30 seconds until its
+   * writeback succeeds or its edits commit, and its effects have 30 more after the commit. Forward
+   * it to every call the handler awaits. Edits that follow a succeeded writeback always complete, so
+   * their signal never aborts.
+   */
   readonly signal: AbortSignal
   readonly logger: Logger
 }

package/src/actions/validation.ts

@@ -1,6 +1,7 @@
 import type { ValueType } from "../ontology"
 import { OntologyValidationError } from "../ontology/errors"
 import type { ObjectTypeWithPropertyTokens } from "../ontology/tokens"
+import { assertValidFileRefs } from "../ontology/validation"
 import { coerceParamsToTyped, normalizeParams } from "../shared/params/validation"
 import type { ActionRunParams } from "../storage/action-runs"
 import { ActionDefinitionError } from "./errors"
@@ -52,10 +53,12 @@ export function normalizeActionParams(
   params: Record<string, unknown>,
   pathPrefix: string
 ): ActionRunParams {
-  return normalizeParams(runtime.ontology.getValueTypesById(), paramsConfig, params, {
+  const normalized = normalizeParams(runtime.ontology.getValueTypesById(), paramsConfig, params, {
     kind: "action",
     id: pathPrefix,
   })
+  assertValidFileRefs(normalized, pathPrefix)
+  return normalized
 }
 
 /**