@sixb/core 0.1.0 → 0.1.2

package/src/syncs/run-dispatch.ts

@@ -0,0 +1,312 @@
+import { randomUUID } from "node:crypto"
+import { reportRunFailure } from "../error-reporting/capability"
+import { createSixbError, toSixbFailure } from "../errors/internal"
+import type { SixbFailure } from "../errors/types"
+import type { RunDispatcher } from "../execution/dispatch"
+import { createPrimitiveExecutionRecord } from "../execution/durable"
+import type { Queues } from "../queues"
+import type { SixbDefinitions } from "../runtime/definitions"
+import type { CreateExecutionInput, Storage, SyncRunFailureCode, SyncRunRecord } from "../storage"
+import { SYNC_RUN_FAILURE_CODES, SyncRunError } from "../storage"
+import { SyncValidationError } from "./errors"
+import type { SyncRunRequestOptions, SyncRunRequestResult } from "./request"
+import type { SyncDefinition } from "./types"
+
+export type AutomaticSyncExecutionSource =
+  | { readonly type: "schedule"; readonly eventId: string }
+  | { readonly type: "event"; readonly eventId: string }
+
+export interface AutomaticSyncRunDispatchInput extends SyncRunRequestOptions {
+  readonly syncId: string
+  readonly runId: string
+  readonly source: AutomaticSyncExecutionSource
+  readonly correlationId: string
+  readonly metadata?: Readonly<Record<string, string>>
+}
+
+export type SyncRunDispatchPort = RunDispatcher<AutomaticSyncRunDispatchInput, SyncRunRequestResult>
+
+export interface SyncRunDispatcherDependencies {
+  readonly id: string
+  readonly definitions: Pick<SixbDefinitions, "syncs">
+  readonly storage: Storage
+  readonly queues: Pick<Queues, "syncRuns">
+}
+
+interface DispatchSyncRunInput extends SyncRunRequestOptions {
+  readonly errorReporterHost: object
+  readonly projectId: string
+  readonly sync: SyncDefinition
+  readonly storage: Storage
+  readonly queue: Queues["syncRuns"]
+  readonly metadata?: Readonly<Record<string, string>>
+  readonly createExecution: (executionId: string, runId: string) => Promise<CreateExecutionInput>
+  readonly validateExistingRun?: (run: SyncRunRecord, storage: Storage) => Promise<void>
+}
+
+type PersistedSyncRun =
+  | { readonly publish: false; readonly run: SyncRunRecord }
+  | {
+      readonly publish: true
+      readonly run: SyncRunRecord
+      readonly execution: CreateExecutionInput
+      readonly queuedAt: Date
+      readonly created: boolean
+    }
+
+/** Core-owned durable dispatch boundary used by automatic Sync triggers. */
+export class SyncRunDispatcher implements SyncRunDispatchPort {
+  constructor(private readonly dependencies: SyncRunDispatcherDependencies) {}
+
+  async dispatch(input: AutomaticSyncRunDispatchInput): Promise<SyncRunRequestResult> {
+    assertAutomaticDispatchInput(input)
+    const sync = this.dependencies.definitions.syncs.getById(input.syncId)
+    if (!sync) throw new SyncValidationError(`[Sixb] Unknown sync '${input.syncId}'`)
+
+    return dispatchSyncRun({
+      errorReporterHost: this.dependencies,
+      projectId: this.dependencies.id,
+      sync,
+      storage: this.dependencies.storage,
+      queue: this.dependencies.queues.syncRuns,
+      runId: input.runId,
+      expectedLatestVersionId: input.expectedLatestVersionId,
+      commitMessage: input.commitMessage,
+      metadata: input.metadata,
+      validateExistingRun: (run, storage) =>
+        assertAutomaticExecutionIdentity(storage, this.dependencies.id, input, run),
+      createExecution: async (executionId, runId) =>
+        createPrimitiveExecutionRecord({
+          id: executionId,
+          primitive: { kind: "sync", id: sync.id, runId },
+          origin: {
+            type: "automatic",
+            projectId: this.dependencies.id,
+            source: input.source,
+            correlationId: input.correlationId,
+          },
+        }),
+    })
+  }
+}
+
+/** Persist a Sync execution and queued run before publishing its queue job. */
+export async function dispatchSyncRun(input: DispatchSyncRunInput): Promise<SyncRunRequestResult> {
+  const runId = createSyncRunId(input.runId)
+  const persisted = await persistSyncRun(input, runId)
+  if (!persisted.publish) return existingSyncRunResult(persisted.run)
+  return publishSyncRun(input, persisted)
+}
+
+async function persistSyncRun(
+  input: DispatchSyncRunInput,
+  runId: string
+): Promise<PersistedSyncRun> {
+  const syncRuns = requireSyncRunStorage(input.storage)
+  const existing = await syncRuns.getById({ projectId: input.projectId, id: runId })
+  if (existing) return reuseSyncRun(input, existing)
+
+  const execution = await input.createExecution(`exec_${randomUUID()}`, runId)
+  const queuedAt = new Date()
+  try {
+    return await input.storage.transaction(
+      async (tx): Promise<PersistedSyncRun> => {
+        const transactionalRuns = requireSyncRunStorage(tx)
+        const raced = await transactionalRuns.getById({ projectId: input.projectId, id: runId })
+        if (raced) {
+          assertExistingRunMatchesRequest(raced, input)
+          await input.validateExistingRun?.(raced, tx)
+          return { publish: false, run: raced }
+        }
+
+        await tx.executions.create(execution)
+        const run = await transactionalRuns.queue({
+          projectId: input.projectId,
+          id: runId,
+          executionId: execution.id,
+          syncId: input.sync.id,
+          datasetId: input.sync.target.dataset.id,
+          mode: input.sync.config.mode,
+          queuedAt,
+          expectedLatestVersionId: input.expectedLatestVersionId,
+          commitMessage: input.commitMessage,
+        })
+        return { publish: true, run, execution, queuedAt, created: true }
+      },
+      { isolation: "serializable" }
+    )
+  } catch (error) {
+    if (!(error instanceof SyncRunError)) throw error
+    const raced = await syncRuns.getById({ projectId: input.projectId, id: runId })
+    if (!raced) throw error
+    assertExistingRunMatchesRequest(raced, input)
+    await input.validateExistingRun?.(raced, input.storage)
+    return { publish: false, run: raced }
+  }
+}
+
+async function reuseSyncRun(
+  input: DispatchSyncRunInput,
+  existing: SyncRunRecord
+): Promise<PersistedSyncRun> {
+  assertExistingRunMatchesRequest(existing, input)
+  await input.validateExistingRun?.(existing, input.storage)
+  if (
+    existing.status !== "failed" ||
+    existing.error?.code !== "queue.enqueue_failed" ||
+    !existing.error.retryable
+  ) {
+    return { publish: false, run: existing }
+  }
+
+  const execution = await input.storage.executions.getById({
+    projectId: input.projectId,
+    id: existing.executionId,
+  })
+  if (!execution) {
+    throw new SyncRunError(
+      `[Sixb] Execution '${existing.executionId}' for Sync run '${existing.id}' was not found.`
+    )
+  }
+
+  const queuedAt = new Date()
+  const run = await requireSyncRunStorage(input.storage).queue({
+    projectId: input.projectId,
+    id: existing.id,
+    executionId: existing.executionId,
+    syncId: existing.syncId,
+    datasetId: existing.datasetId,
+    mode: existing.mode,
+    queuedAt,
+    expectedLatestVersionId: existing.expectedLatestVersionId,
+    commitMessage: existing.commitMessage,
+  })
+  return { publish: true, run, execution, queuedAt, created: false }
+}
+
+async function publishSyncRun(
+  input: DispatchSyncRunInput,
+  persisted: Extract<PersistedSyncRun, { readonly publish: true }>
+): Promise<SyncRunRequestResult> {
+  try {
+    const [job] = await input.queue.enqueue({
+      projectId: input.projectId,
+      jobs: [
+        {
+          id: persisted.run.id,
+          type: "sync.run.requested",
+          payload: { runId: persisted.run.id },
+          ...(input.metadata === undefined ? {} : { metadata: input.metadata }),
+        },
+      ],
+    })
+    return {
+      syncId: persisted.run.syncId,
+      runId: persisted.run.id,
+      queuedAt: persisted.queuedAt.toISOString(),
+      ...(job?.id ? { jobId: job.id } : {}),
+      created: persisted.created,
+    }
+  } catch (error) {
+    const failedAt = new Date()
+    const failure = toEnqueueFailure(error, persisted.run, failedAt)
+    const failed = await requireSyncRunStorage(input.storage).finish({
+      projectId: input.projectId,
+      id: persisted.run.id,
+      status: "failed",
+      finishedAt: failedAt,
+      error: failure,
+    })
+    reportRunFailure(input.errorReporterHost, error, {
+      projectId: input.projectId,
+      runKind: "sync",
+      run: { runId: failed.id, syncId: failed.syncId },
+      failure,
+    })
+    throw error
+  }
+}
+
+function assertExistingRunMatchesRequest(
+  existing: SyncRunRecord,
+  input: Pick<DispatchSyncRunInput, "sync" | "expectedLatestVersionId" | "commitMessage">
+): void {
+  if (
+    existing.syncId !== input.sync.id ||
+    existing.datasetId !== input.sync.target.dataset.id ||
+    existing.mode !== input.sync.config.mode ||
+    existing.expectedLatestVersionId !== input.expectedLatestVersionId ||
+    existing.commitMessage !== input.commitMessage
+  ) {
+    throw new SyncRunError(
+      `[Sixb] Sync run '${existing.id}' already exists with a different request payload.`
+    )
+  }
+}
+
+function existingSyncRunResult(existing: SyncRunRecord): SyncRunRequestResult {
+  return {
+    syncId: existing.syncId,
+    runId: existing.id,
+    queuedAt: existing.queuedAt.toISOString(),
+    created: false,
+  }
+}
+
+function requireSyncRunStorage(storage: Storage): NonNullable<Storage["syncRuns"]> {
+  if (!storage.syncRuns) throw new SyncValidationError("[Sixb] Sync run storage is not configured.")
+  return storage.syncRuns
+}
+
+function createSyncRunId(runId: string | undefined): string {
+  if (runId === undefined) return `run_${randomUUID()}`
+  if (!runId.trim()) throw new SyncValidationError("[Sixb] Sync run id must not be empty")
+  return runId
+}
+
+function assertAutomaticDispatchInput(input: AutomaticSyncRunDispatchInput): void {
+  assertNonBlank(input.syncId, "Sync id")
+  assertNonBlank(input.runId, "Sync run id")
+  assertNonBlank(input.source.eventId, "Sync source event id")
+  assertNonBlank(input.correlationId, "Sync correlation id")
+}
+
+async function assertAutomaticExecutionIdentity(
+  storage: Storage,
+  projectId: string,
+  input: AutomaticSyncRunDispatchInput,
+  run: SyncRunRecord
+): Promise<void> {
+  const execution = await storage.executions.getById({ projectId, id: run.executionId })
+  if (
+    !execution ||
+    execution.source.type !== input.source.type ||
+    execution.source.eventId !== input.source.eventId ||
+    execution.correlationId !== input.correlationId ||
+    execution.requestedBy !== undefined
+  ) {
+    throw new SyncValidationError(
+      `[Sixb] Sync run '${run.id}' already exists with different automatic provenance.`
+    )
+  }
+}
+
+function toEnqueueFailure(
+  error: unknown,
+  run: SyncRunRecord,
+  at: Date
+): SixbFailure<SyncRunFailureCode> {
+  const enqueueError = createSixbError(
+    "queue.enqueue_failed",
+    `[Sixb] Could not enqueue Sync run '${run.id}'.`,
+    {
+      cause: error,
+      details: { syncId: run.syncId, runId: run.id, phase: "enqueue" },
+    }
+  )
+  return toSixbFailure(enqueueError, { allowedCodes: SYNC_RUN_FAILURE_CODES, at })
+}
+
+function assertNonBlank(value: string, label: string): void {
+  if (!value.trim()) throw new SyncValidationError(`[Sixb] ${label} must not be empty.`)
+}

package/src/syncs/sources.ts

@@ -0,0 +1,20 @@
+import type { AnyConnectorAdapter, ConnectorDefinition, ConnectorRuntime } from "../connectors"
+import {
+  type ConnectorExecutionSource,
+  type ConnectorExecutionSourceResolver,
+  getConnectorExecutionSourceResolver,
+} from "../connectors/execution"
+
+/** One connector client invocation contributing values to a Sync run. */
+export type SyncConnectorSource<TAdapter extends AnyConnectorAdapter = AnyConnectorAdapter> =
+  ConnectorExecutionSource<TAdapter>
+
+export type SyncConnectorSourceResolver = ConnectorExecutionSourceResolver
+
+/** Resolve the source invocations owned by one connector definition for a Sync execution. */
+export function resolveSyncConnectorSources<TAdapter extends AnyConnectorAdapter>(
+  connector: ConnectorRuntime,
+  definition: ConnectorDefinition<string, TAdapter>
+): Promise<readonly SyncConnectorSource<TAdapter>[]> {
+  return getConnectorExecutionSourceResolver(connector).list(definition)
+}

package/src/syncs/types.ts

@@ -1,11 +1,14 @@
 import type { BlobStorage } from "../blob-storage"
 import {
+  type AnyConnectorAdapter,
   type ConnectorAdapter,
   type ConnectorClient,
+  type ConnectorConnectionMetadata,
   type ConnectorDefinition,
   isConnectorDefinition,
+  type OAuthConnectorAdapter,
 } from "../connectors"
-import type { DatasetDefinition } from "../datasets"
+import type { DatasetDefinition, DatasetPrimaryKey, MergeChange } from "../datasets"
 import { isDatasetDefinition } from "../datasets"
 import type { Logger } from "../logging"
 import type { ScheduleDefinition, ScheduleReference } from "../schedules"
@@ -14,8 +17,19 @@ import { isScheduleReference } from "../schedules"
 /** Blob operations available to sync read handlers. */
 export type SyncBlobContext = Pick<BlobStorage, "put" | "open" | "stat">
 
+/** Non-secret connector connection metadata available to OAuth-backed Sync handlers. */
+export type SyncConnectorConnection = ConnectorConnectionMetadata
+
+type SyncConnectionContext<TAdapter extends AnyConnectorAdapter> =
+  TAdapter extends OAuthConnectorAdapter
+    ? { readonly connection: SyncConnectorConnection }
+    : { readonly connection?: undefined }
+
 /** Context passed to a sync read handler. */
-export type SyncReadContext<TCheckpoint = never> = {
+export type SyncReadContext<
+  TCheckpoint = never,
+  TAdapter extends AnyConnectorAdapter = ConnectorAdapter,
+> = {
   readonly projectId: string
   readonly syncId: string
   readonly signal: AbortSignal
@@ -26,20 +40,30 @@ export type SyncReadContext<TCheckpoint = never> = {
   : {
       readonly checkpoint?: TCheckpoint
       setCheckpoint(next: TCheckpoint): void
-    })
+    }) &
+  SyncConnectionContext<TAdapter>
+
+export type SyncMode = "snapshot" | "append" | "merge"
+
+type MergeSyncChange = MergeChange<
+  Readonly<Record<string, unknown>>,
+  Readonly<Record<string, unknown>>
+>
 
 /** A sync read handler may return one item, a sync iterable, or an async iterable. */
-export type SyncReadResult = unknown | Iterable<unknown> | AsyncIterable<unknown>
+export type SyncReadResult<TMode extends SyncMode = SyncMode> = TMode extends "merge"
+  ? MergeSyncChange | Iterable<MergeSyncChange> | AsyncIterable<MergeSyncChange>
+  : unknown | Iterable<unknown> | AsyncIterable<unknown>
 
 /** User-facing batch sync options accepted by `defineSync(...)`. */
-export interface BatchSyncConfig {
-  readonly mode?: "snapshot" | "append"
+export interface BatchSyncConfig<TMode extends SyncMode = SyncMode> {
+  readonly mode?: TMode
 }
 
 /** Normalized batch sync config stored on the final sync definition. */
-export interface BatchSyncDefinitionConfig {
+export interface BatchSyncDefinitionConfig<TMode extends SyncMode = SyncMode> {
   readonly kind: "batch"
-  readonly mode: "snapshot" | "append"
+  readonly mode: TMode
 }
 
 /** V1 syncs always target a named raw dataset. */
@@ -56,11 +80,15 @@ export interface DatasetSyncTarget {
  * builder still gives users precise `context.checkpoint` and `setCheckpoint(...)` types when
  * they author a sync.
  */
-export type SyncReadHandler<TAdapter extends ConnectorAdapter, TCheckpoint = never> = {
+export type SyncReadHandler<
+  TAdapter extends AnyConnectorAdapter,
+  TCheckpoint = never,
+  TMode extends SyncMode = SyncMode,
+> = {
   bivarianceHack(
     client: ConnectorClient<TAdapter>,
-    context: SyncReadContext<TCheckpoint>
-  ): SyncReadResult | Promise<SyncReadResult>
+    context: SyncReadContext<TCheckpoint, TAdapter>
+  ): SyncReadResult<TMode> | Promise<SyncReadResult<TMode>>
 }["bivarianceHack"]
 
 /**
@@ -71,42 +99,62 @@ export type SyncReadHandler<TAdapter extends ConnectorAdapter, TCheckpoint = nev
  */
 export interface SyncDefinition<
   TId extends string = string,
-  TConnector extends ConnectorDefinition = ConnectorDefinition,
+  TConnector extends ConnectorDefinition<string, AnyConnectorAdapter> = ConnectorDefinition<
+    string,
+    AnyConnectorAdapter
+  >,
   TCheckpoint = unknown,
+  TMode extends SyncMode = SyncMode,
 > {
   readonly kind: "sync"
   readonly id: TId
-  readonly config: BatchSyncDefinitionConfig
+  readonly config: BatchSyncDefinitionConfig<TMode>
   readonly triggers: readonly ScheduleReference[]
   readonly connector: TConnector
-  readonly read: SyncReadHandler<TConnector["adapter"], TCheckpoint>
+  readonly read: SyncReadHandler<TConnector["adapter"], TCheckpoint, TMode>
   readonly target: DatasetSyncTarget
 }
 
 export interface SyncTargetBuilder<
   TId extends string = string,
-  TConnector extends ConnectorDefinition = ConnectorDefinition,
+  TConnector extends ConnectorDefinition<string, AnyConnectorAdapter> = ConnectorDefinition<
+    string,
+    AnyConnectorAdapter
+  >,
   TCheckpoint = never,
+  TMode extends SyncMode = SyncMode,
 > {
-  intoDataset(dataset: DatasetDefinition): SyncDefinition<TId, TConnector, TCheckpoint>
+  intoDataset<TDataset extends DatasetDefinition>(
+    dataset: TMode extends "merge"
+      ? TDataset & { readonly primaryKey: DatasetPrimaryKey }
+      : TDataset
+  ): SyncDefinition<TId, TConnector, TCheckpoint, TMode>
 }
 
 export interface SyncReadBuilder<
   TId extends string = string,
-  TConnector extends ConnectorDefinition = ConnectorDefinition,
+  TConnector extends ConnectorDefinition<string, AnyConnectorAdapter> = ConnectorDefinition<
+    string,
+    AnyConnectorAdapter
+  >,
   TCheckpoint = never,
+  TMode extends SyncMode = SyncMode,
 > {
   read(
-    handler: SyncReadHandler<TConnector["adapter"], TCheckpoint>
-  ): SyncTargetBuilder<TId, TConnector, TCheckpoint>
+    handler: SyncReadHandler<TConnector["adapter"], TCheckpoint, TMode>
+  ): SyncTargetBuilder<TId, TConnector, TCheckpoint, TMode>
 }
 
-export interface SyncBuilder<TId extends string = string, TCheckpoint = never> {
-  when(schedule: ScheduleDefinition): SyncBuilder<TId, TCheckpoint>
-  checkpoint<TNextCheckpoint>(): SyncBuilder<TId, TNextCheckpoint>
-  from<TConnector extends ConnectorDefinition>(
+export interface SyncBuilder<
+  TId extends string = string,
+  TCheckpoint = never,
+  TMode extends SyncMode = SyncMode,
+> {
+  when(schedule: ScheduleDefinition): SyncBuilder<TId, TCheckpoint, TMode>
+  checkpoint<TNextCheckpoint>(): SyncBuilder<TId, TNextCheckpoint, TMode>
+  from<TConnector extends ConnectorDefinition<string, AnyConnectorAdapter>>(
     connector: TConnector
-  ): SyncReadBuilder<TId, TConnector, TCheckpoint>
+  ): SyncReadBuilder<TId, TConnector, TCheckpoint, TMode>
 }
 
 /** Runtime type guard for values discovered from `syncs/` modules. */
@@ -120,7 +168,9 @@ export function isSyncDefinition(value: unknown): value is SyncDefinition {
     typeof value.id === "string" &&
     isRecord(value.config) &&
     value.config.kind === "batch" &&
-    (value.config.mode === "snapshot" || value.config.mode === "append") &&
+    (value.config.mode === "snapshot" ||
+      value.config.mode === "append" ||
+      value.config.mode === "merge") &&
     Array.isArray(value.triggers) &&
     (value.triggers as unknown[]).every((reference) => isScheduleReference(reference)) &&
     isConnectorDefinition(value.connector) &&

package/src/syncs/validation.ts

@@ -0,0 +1,77 @@
+import type { DatasetDefinition } from "../datasets"
+import type { PipelineDefinition } from "../pipelines"
+import type { TelemetryProjectionDefinition } from "../projections"
+import { SyncValidationError } from "./errors"
+import type { SyncDefinition } from "./types"
+
+interface DatasetWriter {
+  readonly datasetId: string
+  readonly label: string
+}
+
+export function validateKeyedDatasetWriterTopology(input: {
+  readonly datasetsById: ReadonlyMap<string, DatasetDefinition>
+  readonly syncs: readonly SyncDefinition[]
+  readonly pipelines: readonly PipelineDefinition[]
+}): void {
+  for (const sync of input.syncs) {
+    const dataset = input.datasetsById.get(sync.target.dataset.id)
+    if (sync.config.mode === "merge" && dataset?.primaryKey === undefined) {
+      throw new SyncValidationError(
+        `[Sixb] Merge sync '${sync.id}' targets dataset '${sync.target.dataset.id}', which must define a primaryKey.`
+      )
+    }
+  }
+
+  const firstWriterByDataset = new Map<string, DatasetWriter>()
+  for (const writer of datasetWriters(input.syncs, input.pipelines)) {
+    const dataset = input.datasetsById.get(writer.datasetId)
+    if (dataset?.primaryKey === undefined) continue
+
+    const first = firstWriterByDataset.get(writer.datasetId)
+    if (!first) {
+      firstWriterByDataset.set(writer.datasetId, writer)
+      continue
+    }
+
+    throw new SyncValidationError(
+      `[Sixb] Keyed dataset '${writer.datasetId}' has multiple registered writers: ${first.label} and ${writer.label}. V1 allows one writer per keyed dataset.`
+    )
+  }
+}
+
+export function validateMergeSyncProjectionSafety(input: {
+  readonly syncs: readonly SyncDefinition[]
+  readonly telemetryProjections: readonly TelemetryProjectionDefinition[]
+}): void {
+  const mergeSyncByDataset = new Map(
+    input.syncs
+      .filter((sync) => sync.config.mode === "merge")
+      .map((sync) => [sync.target.dataset.id, sync] as const)
+  )
+
+  for (const projection of input.telemetryProjections) {
+    const sync = mergeSyncByDataset.get(projection.datasetId)
+    if (!sync) continue
+    throw new SyncValidationError(
+      `[Sixb] Telemetry projection '${projection.id}' cannot read merge-written dataset '${projection.datasetId}' from sync '${sync.id}'. V1 merge syncs support object and link replacement projections only.`
+    )
+  }
+}
+
+function* datasetWriters(
+  syncs: readonly SyncDefinition[],
+  pipelines: readonly PipelineDefinition[]
+): Iterable<DatasetWriter> {
+  for (const sync of syncs) {
+    yield { datasetId: sync.target.dataset.id, label: `sync '${sync.id}'` }
+  }
+  for (const pipeline of pipelines) {
+    for (const node of pipeline.graph.nodes) {
+      yield {
+        datasetId: node.step.output.id,
+        label: `pipeline '${pipeline.id}' step '${node.step.id}'`,
+      }
+    }
+  }
+}

package/src/testing/action-execution.ts

@@ -0,0 +1,61 @@
+import type { TrustedPrimitiveRef } from "../execution"
+import type { ActionRunRecord, QueueActionRunInput, Storage } from "../storage"
+import type { ExecutionStorage } from "../storage/executions"
+
+/** Create the durable execution chain required by an Action-run storage fixture. */
+export async function createTestActionExecution(
+  executions: ExecutionStorage,
+  input: {
+    readonly projectId: string
+    readonly actionId: string
+    readonly runId: string
+    readonly executionId?: string
+  }
+): Promise<string> {
+  const parentExecutionId = `test_request_execution:${input.runId}`
+  const executionId = input.executionId ?? `test_action_execution:${input.runId}`
+  const primitive: TrustedPrimitiveRef = {
+    kind: "action",
+    id: input.actionId,
+    runId: input.runId,
+  }
+
+  const existing = await executions.getById({ projectId: input.projectId, id: executionId })
+  if (existing) return executionId
+
+  const parent = await executions.getById({ projectId: input.projectId, id: parentExecutionId })
+  if (!parent) {
+    await executions.create({
+      id: parentExecutionId,
+      projectId: input.projectId,
+      executor: { type: "request", requestId: `test_request:${input.runId}` },
+      source: { type: "http", requestId: `test_request:${input.runId}` },
+      correlationId: `test_correlation:${input.runId}`,
+      authorizationRef: { type: "disabled" },
+    })
+  }
+  await executions.create({
+    id: executionId,
+    projectId: input.projectId,
+    executor: { type: "primitive", kind: primitive.kind, runId: primitive.runId },
+    source: { type: "execution", executionId: parentExecutionId },
+    correlationId: `test_correlation:${input.runId}`,
+    authorizationRef: { type: "trustedPrimitive", primitive },
+  })
+
+  return executionId
+}
+
+/** Queue an Action run with the valid durable execution fixture required by every provider. */
+export async function queueTestActionRun(
+  storage: Pick<Storage, "actionRuns" | "executions">,
+  input: Omit<QueueActionRunInput, "executionId">
+): Promise<ActionRunRecord> {
+  if (!storage.actionRuns) throw new Error("Action run storage is not configured for this test.")
+  const executionId = await createTestActionExecution(storage.executions, {
+    projectId: input.projectId,
+    actionId: input.actionId,
+    runId: input.id,
+  })
+  return storage.actionRuns.queue({ ...input, executionId })
+}