@sixb/core 0.1.1 → 0.1.2

package/src/testing/materializer-storage-contract.ts

@@ -10,12 +10,19 @@ import {
   prop,
   type Storage,
 } from ".."
+import type { TrustedPrimitiveRef } from "../execution"
+import { restoreTrustedPrimitiveExecutionScope } from "../execution/durable"
+import { createTestingScope } from "../execution/scopes"
+import type { OntologyMaterializer } from "../materializer"
 import {
   createOntologyMaterializer,
+  type OntologyEditOperation,
   ProjectionRegistry,
   type ProjectionSourceEntry,
 } from "../materializer"
 import type { ActionRunStorage, ProjectionRunStorage } from "../storage"
+import { createTestActionExecution, queueTestActionRun } from "./action-execution"
+import { createTestProjectionExecution, startTestProjectionRun } from "./projection-execution"
 
 export interface MaterializerStorageContractProvider<TStorage extends Storage> {
   readonly createStorage: () => TStorage | Promise<TStorage>
@@ -94,7 +101,6 @@ export function runMaterializerStorageContractSuite<TStorage extends Storage>(
         materializationId: () => `storage-contract-candidate-${++materializationOrdinal}`,
       },
     })
-
     try {
       const firstVersion = {
         datasetId: devices.id,
@@ -107,7 +113,13 @@ export function runMaterializerStorageContractSuite<TStorage extends Storage>(
         protocol: "replacement",
         datasetVersion: firstVersion,
       })
-      const first = await materializer.projections.replace({
+      const firstMaterializer = await projectionMaterializer(
+        materializer,
+        storage,
+        deviceProjection.id,
+        "replacement-v1"
+      )
+      const first = await firstMaterializer.projections.replace({
         source: { projectionId: deviceProjection.id },
         datasetVersion: firstVersion,
         execution: firstExecution,
@@ -133,7 +145,13 @@ export function runMaterializerStorageContractSuite<TStorage extends Storage>(
         protocol: "replacement",
         datasetVersion: secondVersion,
       })
-      const second = await materializer.projections.replace({
+      const secondMaterializer = await projectionMaterializer(
+        materializer,
+        storage,
+        deviceProjection.id,
+        "replacement-v2"
+      )
+      const second = await secondMaterializer.projections.replace({
         source: { projectionId: deviceProjection.id },
         datasetVersion: secondVersion,
         execution: secondExecution,
@@ -152,8 +170,18 @@ export function runMaterializerStorageContractSuite<TStorage extends Storage>(
         })
       ).toBeNull()
 
+      await createTestActionExecution(storage.executions, {
+        projectId: "materializer-storage-contract",
+        actionId: "renameDevice",
+        runId: "missing-action-run",
+      })
+      const missingActionMaterializer = await primitiveMaterializer(materializer, storage, {
+        kind: "action",
+        id: "renameDevice",
+        runId: "missing-action-run",
+      })
       await expect(
-        materializer.edits.commit({
+        missingActionMaterializer.edits.commit({
           mode: "atomic",
           source: { kind: "action", actionId: "renameDevice", runId: "missing-action-run" },
           operations: [
@@ -172,7 +200,7 @@ export function runMaterializerStorageContractSuite<TStorage extends Storage>(
         })
       ).rejects.toThrow("missing-action-run")
 
-      await storage.actionRuns.queue({
+      await queueTestActionRun(storage, {
         id: "action-run",
         projectId: "materializer-storage-contract",
         actionId: "renameDevice",
@@ -184,7 +212,12 @@ export function runMaterializerStorageContractSuite<TStorage extends Storage>(
         id: "action-run",
         projectId: "materializer-storage-contract",
       })
-      const actionCommit = await materializer.edits.commit({
+      const actionMaterializer = await primitiveMaterializer(materializer, storage, {
+        kind: "action",
+        id: "renameDevice",
+        runId: "action-run",
+      })
+      const actionCommit = await actionMaterializer.edits.commit({
         mode: "atomic",
         source: { kind: "action", actionId: "renameDevice", runId: "action-run" },
         operations: [
@@ -213,8 +246,20 @@ export function runMaterializerStorageContractSuite<TStorage extends Storage>(
         versionId: "readings-v1",
         createdAt: "2026-01-03T00:00:00.000Z",
       }
+      await createTestProjectionExecution(storage.executions, {
+        projectId: "materializer-storage-contract",
+        projectionId: temperatureProjection.id,
+        runId: "missing-telemetry-run",
+        datasetId: readings.id,
+        datasetVersionId: "missing-readings-run",
+      })
+      const missingTelemetryMaterializer = await primitiveMaterializer(materializer, storage, {
+        kind: "projection",
+        id: temperatureProjection.id,
+        runId: "missing-telemetry-run",
+      })
       await expect(
-        materializer.telemetry.append({
+        missingTelemetryMaterializer.telemetry.append({
           source: {
             kind: "projection",
             projection: { projectionId: temperatureProjection.id },
@@ -252,7 +297,13 @@ export function runMaterializerStorageContractSuite<TStorage extends Storage>(
         datasetVersion: telemetryVersion,
         fixedBatchSize: 1,
       })
-      const telemetry = await materializer.telemetry.append({
+      const telemetryMaterializer = await projectionMaterializer(
+        materializer,
+        storage,
+        temperatureProjection.id,
+        "telemetry-v1"
+      )
+      const telemetry = await telemetryMaterializer.telemetry.append({
         source: {
           kind: "projection",
           projection: { projectionId: temperatureProjection.id },
@@ -287,6 +338,157 @@ export function runMaterializerStorageContractSuite<TStorage extends Storage>(
       await provider.cleanup?.(createdStorage)
     }
   })
+
+  test(`${name} persists cardinality-one edit authority by scope`, async () => {
+    const createdStorage = await provider.createStorage()
+    const storage = requireContractStorage(createdStorage)
+    let materializationOrdinal = 0
+    const materializer = createOntologyMaterializer({
+      projectId: "materializer-storage-contract",
+      ontology,
+      projections,
+      storage,
+      dependencies: {
+        batching: { sourceStageRows: 1, statePageRows: 1, planChunkRows: 1 },
+        clock: () => new Date("2026-02-01T12:00:00.000Z"),
+        materializationId: () => `scope-contract-candidate-${++materializationOrdinal}`,
+      },
+    })
+    const runtimeMaterializer = materializer.withScope(runtimeScope())
+    const linkRef = (targetId: string) => ({
+      source: { objectTypeId: Device.id, primaryId: "document" },
+      linkId: "parent",
+      target: { objectTypeId: Device.id, primaryId: targetId },
+    })
+    const replace = async (versionId: string, parentId: string) => {
+      const datasetVersion = {
+        datasetId: devices.id,
+        versionId,
+        createdAt: `2026-01-0${versionId.slice(1)}T00:00:00.000Z`,
+      }
+      const execution = await claim(storage, {
+        runId: `scope-${versionId}`,
+        projectionId: deviceProjection.id,
+        protocol: "replacement",
+        datasetVersion,
+      })
+      const projectionMaterializerForRun = await projectionMaterializer(
+        materializer,
+        storage,
+        deviceProjection.id,
+        `scope-${versionId}`
+      )
+      await projectionMaterializerForRun.projections.replace({
+        source: { projectionId: deviceProjection.id },
+        datasetVersion,
+        execution,
+        entries: entries([
+          sourceEntry("document", "Document", parentId),
+          sourceEntry("rockland", "Rockland"),
+          sourceEntry("haverstraw", "Haverstraw"),
+        ]),
+      })
+    }
+    const edit = (requestId: string, operation: OntologyEditOperation) =>
+      runtimeMaterializer.edits.commit({
+        mode: "atomic",
+        source: { kind: "runtime", requestId },
+        operations: [operation],
+        expectedObjects: [],
+        expectedLinks: [],
+        expectedLinkScopes: [],
+      })
+    const targets = async () =>
+      (
+        await storage.objects.listLinks({
+          projectId: "materializer-storage-contract",
+          objectTypeId: Device.id,
+          objectId: "document",
+        })
+      ).map((row) => row.targetId)
+
+    try {
+      await replace("v1", "rockland")
+      await edit("scope-set", {
+        id: "set",
+        kind: "link.upsert",
+        ref: linkRef("rockland"),
+      })
+
+      await replace("v2", "haverstraw")
+      expect(await targets()).toEqual(["rockland"])
+
+      await edit("scope-reset", {
+        id: "reset",
+        kind: "link.reset",
+        ref: linkRef("rockland"),
+      })
+      expect(await targets()).toEqual(["haverstraw"])
+
+      await edit("scope-clear", {
+        id: "clear",
+        kind: "link.delete",
+        ref: linkRef("haverstraw"),
+      })
+      await replace("v3", "rockland")
+      expect(await targets()).toEqual([])
+
+      await edit("scope-clear-reset", {
+        id: "reset",
+        kind: "link.reset",
+        ref: linkRef("haverstraw"),
+      })
+      expect(await targets()).toEqual(["rockland"])
+    } finally {
+      await provider.cleanup?.(createdStorage)
+    }
+  })
+}
+
+function runtimeScope() {
+  return createTestingScope({
+    projectId: "materializer-storage-contract",
+    executionId: "materializer-storage-contract-runtime-execution",
+    requestId: "materializer-storage-contract-runtime-request",
+    correlationId: "materializer-storage-contract-runtime-correlation",
+  })
+}
+
+async function projectionMaterializer(
+  materializer: OntologyMaterializer,
+  storage: ContractStorage,
+  projectionId: string,
+  runId: string
+) {
+  return primitiveMaterializer(materializer, storage, {
+    kind: "projection",
+    id: projectionId,
+    runId,
+  })
+}
+
+async function primitiveMaterializer(
+  materializer: OntologyMaterializer,
+  storage: ContractStorage,
+  primitive: TrustedPrimitiveRef
+) {
+  const run =
+    primitive.kind === "action"
+      ? await storage.actionRuns.getById({
+          projectId: "materializer-storage-contract",
+          id: primitive.runId,
+        })
+      : await storage.projectionRuns.getById({
+          projectId: "materializer-storage-contract",
+          id: primitive.runId,
+        })
+  const executionId = run?.executionId ?? `test_${primitive.kind}_execution:${primitive.runId}`
+  const execution = await storage.executions.getById({
+    projectId: "materializer-storage-contract",
+    id: executionId,
+  })
+  if (!execution) throw new Error(`Test execution '${executionId}' is missing.`)
+  return materializer.withScope(restoreTrustedPrimitiveExecutionScope({ execution, primitive }))
 }
 
 function requireContractStorage(storage: Storage): ContractStorage {
@@ -359,7 +561,7 @@ async function claim(
   } as const
 
   if (definition._tag === "TelemetryProjectionDefinition") {
-    const claim = await storage.projectionRuns.startOrReclaim({
+    const claim = await startTestProjectionRun(storage, {
       ...common,
       identity: { ...identityBase, projectionKind: "telemetry", protocol: "telemetry" },
       target: { objectTypeId: definition.objectTypeId },
@@ -369,7 +571,7 @@ async function claim(
   }
 
   if (definition._tag === "LinkProjectionDefinition") {
-    const claim = await storage.projectionRuns.startOrReclaim({
+    const claim = await startTestProjectionRun(storage, {
       ...common,
       identity: { ...identityBase, projectionKind: "link", protocol: "replacement" },
       target: {
@@ -380,7 +582,7 @@ async function claim(
     return claim.execution
   }
 
-  const claim = await storage.projectionRuns.startOrReclaim({
+  const claim = await startTestProjectionRun(storage, {
     ...common,
     identity: { ...identityBase, projectionKind: "object", protocol: "replacement" },
     target: { objectTypeId: definition.objectTypeId },

package/src/testing/ontology-contract-fixture.ts

@@ -12,7 +12,13 @@ export interface OntologyContractStorage extends Storage {
 }
 
 const emptyChunk = {
-  overrides: { objectUpserts: [], objectDeletes: [], linkUpserts: [], linkDeletes: [] },
+  overrides: {
+    objects: { upserts: [], deletes: [] },
+    links: {
+      edges: { upserts: [], deletes: [] },
+      slots: { upserts: [], deletes: [] },
+    },
+  },
   effective: {
     objectUpserts: [],
     objectDeletes: [],
@@ -30,6 +36,7 @@ export function contractEditHeader(id: string): MaterializationPlanHeader {
       id,
       idempotencyKey: `runtime:${id}`,
       requestHash: `hash:${id}`,
+      executionId: `contract-execution:${id}`,
       origin: { kind: "runtime", requestId: id },
       ontologyRevision: "ontology-contract-revision",
       intent: { kind: "edit", mode: "atomic", operationCount: 0 },
@@ -61,7 +68,9 @@ export function contractEditResult(commitId: string, eventCount = 0) {
 
 export async function commitEmptyEdit(storage: OntologyContractStorage, id: string): Promise<void> {
   await storage.transaction(async (tx) => {
-    const session = await tx.ontology.materializations.begin(contractEditHeader(id))
+    const header = contractEditHeader(id)
+    await ensureContractExecution(tx, header)
+    const session = await tx.ontology.materializations.begin(header)
     await tx.ontology.materializations.finalize({
       session,
       finalization: { sourceActivations: [], result: contractEditResult(id) },
@@ -98,6 +107,7 @@ export async function commitExactObject(
     schemaVersion: 1 as const,
     projectId: header.commit.projectId,
     occurredAt: header.commit.committedAt,
+    correlationId: `contract-correlation:${id}`,
     origin: header.commit.origin,
     commitId: id,
     type: "object.created" as const,
@@ -134,6 +144,7 @@ export async function commitExactObject(
   ]
 
   await storage.transaction(async (tx) => {
+    await ensureContractExecution(tx, header)
     const materializations = tx.ontology.materializations
     const session = await materializations.begin(header)
     await materializations.stageWork({ session, records: work })
@@ -190,3 +201,25 @@ export async function commitExactObject(
 
   return { eventId }
 }
+
+export async function ensureContractExecution(
+  storage: Pick<Storage, "executions">,
+  header: MaterializationPlanHeader
+): Promise<void> {
+  if (
+    await storage.executions.getById({
+      projectId: header.commit.projectId,
+      id: header.commit.executionId,
+    })
+  ) {
+    return
+  }
+  await storage.executions.create({
+    id: header.commit.executionId,
+    projectId: header.commit.projectId,
+    executor: { type: "request", requestId: `contract-request:${header.commit.id}` },
+    source: { type: "http", requestId: `contract-request:${header.commit.id}` },
+    correlationId: `contract-correlation:${header.commit.id}`,
+    authorizationRef: { type: "disabled" },
+  })
+}

package/src/testing/ontology-storage-contract.ts

@@ -7,6 +7,7 @@ import type {
   MaterializationPlanFinalization,
   MaterializationPlanHeader,
   MaterializationSession,
+  OntologyOutboxFailure,
   OntologySourceRecord,
 } from "../storage/ontology"
 import type { ProjectionRunStorage } from "../storage/projection-runs"
@@ -15,8 +16,10 @@ import {
   commitExactObject,
   contractEditHeader,
   contractEditResult,
+  ensureContractExecution,
   type OntologyContractStorage,
 } from "./ontology-contract-fixture"
+import { startTestProjectionRun } from "./projection-execution"
 
 export interface OntologyStorageContractStorage extends OntologyContractStorage {
   readonly projectionRuns: ProjectionRunStorage
@@ -69,6 +72,16 @@ interface ReadyCandidate {
   readonly execution: ProjectionExecution
   readonly materializationId: string
   readonly source: { readonly projectionId: string }
+  readonly executionId: string
+}
+
+function ontologyOutboxFailure(message: string): OntologyOutboxFailure {
+  return {
+    code: "event.delivery_failed",
+    message,
+    retryable: true,
+    at: "2026-01-03T02:00:00.000Z",
+  }
 }
 
 /**
@@ -120,6 +133,7 @@ export function runOntologyStorageContractSuite<TStorage extends OntologyStorage
         ;(divergent.commit as { requestHash: string }).requestHash = "different-hash"
         await expect(
           storage.transaction(async (tx) => {
+            await ensureContractExecution(tx, divergent)
             await tx.ontology.materializations.begin(divergent)
           })
         ).rejects.toMatchObject({ kind: "idempotency" })
@@ -134,6 +148,30 @@ export function runOntologyStorageContractSuite<TStorage extends OntologyStorage
       })
     })
 
+    test("rejects an ontology commit whose execution does not exist", async () => {
+      await withStorage(async (storage) => {
+        const header = contractEditHeader("missing-execution")
+        await expect(
+          storage.transaction(async (tx) => {
+            const session = await tx.ontology.materializations.begin(header)
+            await tx.ontology.materializations.finalize({
+              session,
+              finalization: {
+                sourceActivations: [],
+                result: contractEditResult(header.commit.id),
+              },
+            })
+          })
+        ).rejects.toThrow()
+        await expect(
+          storage.ontology.commits.getById({
+            projectId: header.commit.projectId,
+            id: header.commit.id,
+          })
+        ).resolves.toBeNull()
+      })
+    })
+
     test("rejects unfinished sessions and rolls back their authoritative writes", async () => {
       await withStorage(async (storage) => {
         const header = contractEditHeader("session-contract")
@@ -170,9 +208,9 @@ export function runOntologyStorageContractSuite<TStorage extends OntologyStorage
         let leakedSession: MaterializationSession | undefined
         await expect(
           storage.transaction(async (tx) => {
-            leakedSession = await tx.ontology.materializations.begin(
-              contractEditHeader("leaked-session")
-            )
+            const leakedHeader = contractEditHeader("leaked-session")
+            await ensureContractExecution(tx, leakedHeader)
+            leakedSession = await tx.ontology.materializations.begin(leakedHeader)
           })
         ).rejects.toThrow("unfinished materialization session")
         if (!leakedSession) throw new Error("Expected an unfinished session handle")
@@ -194,7 +232,7 @@ export function runOntologyStorageContractSuite<TStorage extends OntologyStorage
     test("stages insert-only source rows, seals counts, and fences stale execution tokens", async () => {
       await withStorage(async (storage) => {
         const identity = replacementIdentity("01")
-        const claimed = await storage.projectionRuns.startOrReclaim({
+        const claimed = await startTestProjectionRun(storage, {
           id: "staging-run",
           projectId: "contract-project",
           identity,
@@ -583,7 +621,7 @@ export function runOntologyStorageContractSuite<TStorage extends OntologyStorage
           ids: [reclaimed[0].envelope.id],
           leaseId: "lease-two",
           availableAt: "2026-01-04T00:00:00.000Z",
-          error: "broker unavailable",
+          failure: ontologyOutboxFailure("broker unavailable"),
         })
         const retried = await storage.ontology.outbox.claim({
           projectId: "contract-project",
@@ -592,14 +630,34 @@ export function runOntologyStorageContractSuite<TStorage extends OntologyStorage
           leaseId: "lease-three",
           leaseExpiresAt: "2026-01-04T01:00:00.000Z",
         })
-        expect(retried[0]).toMatchObject({ attempts: 3, lastError: "broker unavailable" })
+        expect(retried[0]).toMatchObject({
+          attempts: 3,
+          lastFailure: ontologyOutboxFailure("broker unavailable"),
+        })
+        await storage.ontology.outbox.reschedule({
+          projectId: "contract-project",
+          ids: [retried[0].envelope.id],
+          leaseId: "lease-three",
+          availableAt: "2026-01-04T00:15:00.000Z",
+        })
+        const lifecycleRescheduled = await storage.ontology.outbox.claim({
+          projectId: "contract-project",
+          now: "2026-01-04T00:15:00.000Z",
+          limit: 1,
+          leaseId: "lease-four",
+          leaseExpiresAt: "2026-01-04T01:15:00.000Z",
+        })
+        expect(lifecycleRescheduled[0]).toMatchObject({
+          attempts: 4,
+          lastFailure: ontologyOutboxFailure("broker unavailable"),
+        })
         expect(
           await storage.ontology.outbox.summarize({ projectId: "contract-project" })
-        ).toMatchObject({ pendingCount: 2, retryingCount: 2, maxAttempts: 3 })
+        ).toMatchObject({ pendingCount: 2, retryingCount: 2, maxAttempts: 4 })
         await storage.ontology.outbox.markPublished({
           projectId: "contract-project",
-          ids: [retried[0].envelope.id],
-          leaseId: "lease-three",
+          ids: [lifecycleRescheduled[0].envelope.id],
+          leaseId: "lease-four",
           publishedAt: "2026-01-04T00:30:00.000Z",
         })
         expect(
@@ -672,7 +730,7 @@ export function runOntologyStorageContractSuite<TStorage extends OntologyStorage
           projectionRevision: "telemetry-contract-revision",
           ownershipHash: "telemetry-contract-ownership",
         }
-        const run = await storage.projectionRuns.startOrReclaim({
+        const run = await startTestProjectionRun(storage, {
           id: "telemetry-run",
           projectId: "contract-project",
           identity,
@@ -684,7 +742,7 @@ export function runOntologyStorageContractSuite<TStorage extends OntologyStorage
             if (!tx.projectionRuns) {
               throw new Error("Contract transaction omitted required storage facades.")
             }
-            const header = telemetryHeader(identity, run.run.id)
+            const header = telemetryHeader(identity, run.run.id, run.run.executionId)
             const session = await tx.ontology.materializations.begin(header)
             await tx.ontology.materializations.finalize({
               session,
@@ -754,7 +812,7 @@ async function createReadyEmptyCandidate(
   versionId: string
 ): Promise<ReadyCandidate> {
   const identity = replacementIdentity(versionId)
-  const run = await storage.projectionRuns.startOrReclaim({
+  const run = await startTestProjectionRun(storage, {
     id: runId,
     projectId: "contract-project",
     identity,
@@ -784,7 +842,7 @@ async function createReadyEmptyCandidate(
     assertionCount: 0,
     readyAt: new Date(Date.parse(identity.datasetVersion.createdAt) + 1_000).toISOString(),
   })
-  return { identity, execution, materializationId, source }
+  return { identity, execution, materializationId, source, executionId: run.run.executionId }
 }
 
 async function activateEmptyCandidate(
@@ -805,6 +863,7 @@ async function activateEmptyCandidate(
       id: commitId,
       idempotencyKey: `projection:${commitId}`,
       requestHash: `hash:${commitId}`,
+      executionId: candidate.executionId,
       origin: {
         kind: "projection",
         projectionId: candidate.source.projectionId,
@@ -878,7 +937,8 @@ async function activateEmptyCandidate(
 
 function telemetryHeader(
   identity: ProjectionMaterializationIdentity,
-  projectionRunId: string
+  projectionRunId: string,
+  executionId: string
 ): MaterializationPlanHeader {
   if (identity.protocol !== "telemetry") throw new Error("Expected telemetry identity")
   return {
@@ -887,6 +947,7 @@ function telemetryHeader(
       id: "telemetry-commit",
       idempotencyKey: "telemetry:telemetry-run:0",
       requestHash: "hash:telemetry-run:0",
+      executionId,
       origin: {
         kind: "telemetry",
         source: {

package/src/testing/pipeline-execution.ts

@@ -0,0 +1,64 @@
+import type { TrustedPrimitiveRef } from "../execution"
+import type { PipelineRunRecord, QueuePipelineRunInput, Storage } from "../storage"
+import type { ExecutionStorage } from "../storage/executions"
+
+/** Create the durable execution required by a Pipeline-run storage fixture. */
+export async function createTestPipelineExecution(
+  executions: ExecutionStorage,
+  input: {
+    readonly projectId: string
+    readonly pipelineId: string
+    readonly runId: string
+    readonly executionId?: string
+  }
+): Promise<string> {
+  const executionId = input.executionId ?? `test_pipeline_execution:${input.runId}`
+  const existing = await executions.getById({ projectId: input.projectId, id: executionId })
+  if (existing) return executionId
+
+  const primitive: TrustedPrimitiveRef = {
+    kind: "pipeline",
+    id: input.pipelineId,
+    runId: input.runId,
+  }
+  await executions.create({
+    id: executionId,
+    projectId: input.projectId,
+    executor: { type: "primitive", kind: primitive.kind, runId: primitive.runId },
+    source: { type: "event", eventId: `test_event:${input.runId}` },
+    correlationId: `test_correlation:${input.runId}`,
+    authorizationRef: { type: "trustedPrimitive", primitive },
+  })
+  return executionId
+}
+
+/** Queue a Pipeline run with the valid durable execution fixture required by every provider. */
+export async function queueTestPipelineRun(
+  storage: Pick<Storage, "pipelineRuns" | "executions">,
+  input: Omit<QueuePipelineRunInput, "executionId">
+): Promise<PipelineRunRecord> {
+  if (!storage.pipelineRuns)
+    throw new Error("Pipeline run storage is not configured for this test.")
+  const executionId = await createTestPipelineExecution(storage.executions, {
+    projectId: input.projectId,
+    pipelineId: input.pipelineId,
+    runId: input.id,
+  })
+  return storage.pipelineRuns.queue({ ...input, executionId })
+}
+
+/** Start a Pipeline run after creating its durable execution and queued state. */
+export async function startTestPipelineRun(
+  storage: Pick<Storage, "pipelineRuns" | "executions">,
+  input: Omit<QueuePipelineRunInput, "executionId" | "queuedAt"> & {
+    readonly startedAt?: Date
+  }
+): Promise<PipelineRunRecord> {
+  const { startedAt, ...queuedRun } = input
+  await queueTestPipelineRun(storage, { ...queuedRun, queuedAt: startedAt })
+  return storage.pipelineRuns!.start({
+    id: input.id,
+    projectId: input.projectId,
+    startedAt,
+  })
+}