@sixb/core 0.1.1 → 0.1.2

package/src/testing/projection-execution.ts

@@ -0,0 +1,98 @@
+import type { TrustedPrimitiveRef } from "../execution"
+import type {
+  ProjectionRunClaim,
+  ProjectionRunRecord,
+  QueueProjectionRunInput,
+  StartOrReclaimProjectionRunInput,
+  Storage,
+} from "../storage"
+import type { ExecutionStorage } from "../storage/executions"
+
+type ProjectionRunQueueFixtureInput = QueueProjectionRunInput extends infer TInput
+  ? TInput extends QueueProjectionRunInput
+    ? Omit<TInput, "executionId">
+    : never
+  : never
+
+/** Create the durable execution required by a Projection-run storage fixture. */
+export async function createTestProjectionExecution(
+  executions: ExecutionStorage,
+  input: {
+    readonly projectId: string
+    readonly projectionId: string
+    readonly runId: string
+    readonly datasetId: string
+    readonly datasetVersionId: string
+    readonly executionId?: string
+  }
+): Promise<string> {
+  const executionId = input.executionId ?? `test_projection_execution:${input.runId}`
+  const existing = await executions.getById({ projectId: input.projectId, id: executionId })
+  if (existing) return executionId
+
+  const primitive: TrustedPrimitiveRef = {
+    kind: "projection",
+    id: input.projectionId,
+    runId: input.runId,
+  }
+  await executions.create({
+    id: executionId,
+    projectId: input.projectId,
+    executor: { type: "primitive", kind: primitive.kind, runId: primitive.runId },
+    source: {
+      type: "datasetVersion",
+      datasetId: input.datasetId,
+      versionId: input.datasetVersionId,
+    },
+    correlationId: `test_correlation:${input.runId}`,
+    authorizationRef: { type: "trustedPrimitive", primitive },
+  })
+  return executionId
+}
+
+/** Queue a Projection run with the valid durable execution fixture required by every provider. */
+export async function queueTestProjectionRun(
+  storage: Pick<Storage, "projectionRuns" | "executions">,
+  input: ProjectionRunQueueFixtureInput
+): Promise<ProjectionRunRecord> {
+  if (!storage.projectionRuns)
+    throw new Error("Projection run storage is not configured for this test.")
+  const executionId = await createTestProjectionExecution(storage.executions, {
+    projectId: input.projectId,
+    projectionId: input.identity.projectionId,
+    runId: input.id,
+    datasetId: input.identity.datasetVersion.datasetId,
+    datasetVersionId: input.identity.datasetVersion.versionId,
+  })
+  return storage.projectionRuns.queue({ ...input, executionId })
+}
+
+/** Start a Projection run after creating its durable execution and queued state. */
+export async function startTestProjectionRun(
+  storage: Pick<Storage, "projectionRuns" | "executions">,
+  input: StartOrReclaimProjectionRunInput
+): Promise<ProjectionRunClaim> {
+  const projectionRuns = storage.projectionRuns
+  if (!projectionRuns) throw new Error("Projection run storage is not configured for this test.")
+  const { startedAt, ...queuedRun } = input
+  await queueTestProjectionRun(storage, { ...queuedRun, queuedAt: startedAt })
+  return projectionRuns.startOrReclaim(input)
+}
+
+/** Claim a queued fixture, or rotate its attempt when the same durable run is reclaimed. */
+export async function claimTestProjectionRun(
+  storage: Pick<Storage, "projectionRuns" | "executions">,
+  input: StartOrReclaimProjectionRunInput
+): Promise<ProjectionRunClaim> {
+  if (!storage.projectionRuns)
+    throw new Error("Projection run storage is not configured for this test.")
+  const existing = await storage.projectionRuns.getById({
+    projectId: input.projectId,
+    id: input.id,
+  })
+  if (!existing) {
+    const { startedAt, ...queuedRun } = input
+    await queueTestProjectionRun(storage, { ...queuedRun, queuedAt: startedAt })
+  }
+  return storage.projectionRuns.startOrReclaim(input)
+}

package/src/testing/projection-run-storage-contract.ts

@@ -1,19 +1,46 @@
 import { describe, expect, test } from "bun:test"
+import type { SixbFailure } from "../errors/types"
 import type { ProjectionMaterializationIdentity } from "../materialization/model"
-import type { ProjectionRunClaim, ProjectionRunStorage } from "../storage/projection-runs"
+import type { ExecutionStorage } from "../storage/executions"
+import type {
+  ProjectionRunClaim,
+  ProjectionRunFailureCode,
+  ProjectionRunStorage,
+  QueueProjectionRunInput,
+  StartOrReclaimProjectionRunInput,
+} from "../storage/projection-runs"
+
+export interface ProjectionRunStorageContractContext<
+  TStorage extends ProjectionRunStorage = ProjectionRunStorage,
+> {
+  readonly projectionRuns: TStorage
+  readonly executions: ExecutionStorage
+}
 
 export interface ProjectionRunStorageContractSuiteOptions<
   TStorage extends ProjectionRunStorage = ProjectionRunStorage,
 > {
-  /** Factory that returns an isolated projection-run store for each test. */
-  readonly createStorage: () => TStorage | Promise<TStorage>
-  readonly setup?: (storage: TStorage) => void | Promise<void>
-  readonly cleanup?: (storage: TStorage) => void | Promise<void>
+  /** Factory that returns one isolated execution + projection-run store for each test. */
+  readonly createStorage: () =>
+    | ProjectionRunStorageContractContext<TStorage>
+    | Promise<ProjectionRunStorageContractContext<TStorage>>
+  readonly setup?: (context: ProjectionRunStorageContractContext<TStorage>) => void | Promise<void>
+  readonly cleanup?: (
+    context: ProjectionRunStorageContractContext<TStorage>
+  ) => void | Promise<void>
 }
 
 const projectId = "contract-project"
 const objectTarget = { objectTypeId: "Device" } as const
 
+const failure = {
+  code: "internal.unexpected",
+  message: "Projection failed",
+  retryable: false,
+  at: "2026-06-01T12:00:00.000Z",
+  details: { projectionId: "contract.devices", runId: "failed-run" },
+} as const satisfies SixbFailure<ProjectionRunFailureCode>
+
 const replacementIdentity = {
   projectionId: "contract.devices",
   projectionKind: "object",
@@ -47,20 +74,94 @@ export function runProjectionRunStorageContractSuite<TStorage extends Projection
   label: string,
   options: ProjectionRunStorageContractSuiteOptions<TStorage>
 ): void {
-  const withStorage = async (body: (storage: TStorage) => Promise<void>): Promise<void> => {
-    const storage = await options.createStorage()
+  const withStorage = async (
+    body: (context: ProjectionRunStorageContractContext<TStorage>) => Promise<void>
+  ): Promise<void> => {
+    const context = await options.createStorage()
     try {
-      await options.setup?.(storage)
-      await body(storage)
+      await options.setup?.(context)
+      await body(context)
     } finally {
-      await options.cleanup?.(storage)
+      await options.cleanup?.(context)
     }
   }
 
   describe(label, () => {
+    test("admits a queued run only after its durable execution exists", async () => {
+      await withStorage(async (context) => {
+        const input = replacementInput("queued-run")
+        await expect(
+          context.projectionRuns.queue({
+            ...input,
+            executionId: "missing-execution",
+          })
+        ).rejects.toThrow()
+
+        const wrongSourceExecutionId = "execution:wrong-source"
+        await context.executions.create({
+          id: wrongSourceExecutionId,
+          projectId: input.projectId,
+          executor: { type: "primitive", kind: "projection", runId: input.id },
+          source: { type: "event", eventId: "wrong-source" },
+          correlationId: input.id,
+          authorizationRef: {
+            type: "trustedPrimitive",
+            primitive: { kind: "projection", id: input.identity.projectionId, runId: input.id },
+          },
+        })
+        await expect(
+          context.projectionRuns.queue({
+            ...input,
+            executionId: wrongSourceExecutionId,
+          })
+        ).rejects.toThrow("does not authorize Projection run")
+
+        const admission = await admitProjectionRun(context, input)
+        await expect(
+          context.projectionRuns.getById({ projectId: input.projectId, id: input.id })
+        ).resolves.toMatchObject({
+          id: input.id,
+          executionId: admission.executionId,
+          status: "queued",
+          attempt: 0,
+        })
+      })
+    })
+
+    test("requeues the same admission after an enqueue failure", async () => {
+      await withStorage(async (context) => {
+        const input = replacementInput("enqueue-retry-run")
+        const admission = await admitProjectionRun(context, input)
+        await expect(
+          context.projectionRuns.failEnqueue({
+            id: input.id,
+            projectId: input.projectId,
+            error: {
+              code: "queue.enqueue_failed",
+              message: "queue unavailable",
+              retryable: true,
+              at: "2026-06-01T12:00:00.000Z",
+              details: { projectionId: input.identity.projectionId, runId: input.id },
+            },
+          })
+        ).resolves.toMatchObject({
+          status: "failed",
+          error: { code: "queue.enqueue_failed", message: "queue unavailable" },
+        })
+
+        await expect(context.projectionRuns.queue(admission)).resolves.toMatchObject({
+          executionId: admission.executionId,
+          status: "queued",
+          attempt: 0,
+        })
+      })
+    })
+
     test("keeps one run while reclaim rotates its execution", async () => {
-      await withStorage(async (storage) => {
+      await withStorage(async (context) => {
+        const storage = context.projectionRuns
         const input = replacementInput("replacement-run")
+        await admitProjectionRun(context, input)
         const first = await storage.startOrReclaim(input)
         const second = await storage.startOrReclaim(input)
 
@@ -77,8 +178,10 @@ export function runProjectionRunStorageContractSuite<TStorage extends Projection
     })
 
     test("fences every stale lock, progress, and terminal write", async () => {
-      await withStorage(async (storage) => {
+      await withStorage(async (context) => {
+        const storage = context.projectionRuns
         const input = replacementInput("fenced-run")
+        await admitProjectionRun(context, input)
         const stale = await storage.startOrReclaim(input)
         const current = await storage.startOrReclaim(input)
 
@@ -109,8 +212,10 @@ export function runProjectionRunStorageContractSuite<TStorage extends Projection
     })
 
     test("rejects immutable identity and target drift", async () => {
-      await withStorage(async (storage) => {
+      await withStorage(async (context) => {
+        const storage = context.projectionRuns
         const input = replacementInput("identity-run")
+        await admitProjectionRun(context, input)
         const claim = await storage.startOrReclaim(input)
         const changedIdentity = { ...replacementIdentity, ownershipHash: "different-ownership" }
 
@@ -130,7 +235,9 @@ export function runProjectionRunStorageContractSuite<TStorage extends Projection
     })
 
     test("keeps physical progress monotone and internally consistent", async () => {
-      await withStorage(async (storage) => {
+      await withStorage(async (context) => {
+        const storage = context.projectionRuns
+        await admitProjectionRun(context, replacementInput("progress-run"))
         const claim = await storage.startOrReclaim(replacementInput("progress-run"))
         const execution = executionInput(claim)
         await expect(
@@ -150,10 +257,10 @@ export function runProjectionRunStorageContractSuite<TStorage extends Projection
     })
 
     test("rejects immutable dataset-version metadata reuse", async () => {
-      await withStorage(async (storage) => {
-        await storage.startOrReclaim(replacementInput("dataset-metadata-first"))
+      await withStorage(async (context) => {
+        await admitProjectionRun(context, replacementInput("dataset-metadata-first"))
         await expect(
-          storage.startOrReclaim({
+          admitProjectionRun(context, {
             ...replacementInput("dataset-metadata-conflict"),
             identity: {
               ...replacementIdentity,
@@ -168,14 +275,17 @@ export function runProjectionRunStorageContractSuite<TStorage extends Projection
     })
 
     test("advances telemetry in contiguous fixed physical batches", async () => {
-      await withStorage(async (storage) => {
-        const claim = await storage.startOrReclaim({
+      await withStorage(async (context) => {
+        const storage = context.projectionRuns
+        const input = {
           id: "telemetry-run",
           projectId,
           identity: telemetryIdentity,
           target: objectTarget,
           fixedBatchSize: 3,
-        })
+        } as const
+        await admitProjectionRun(context, input)
+        const claim = await storage.startOrReclaim(input)
         const execution = executionInput(claim)
         expect(claim.run).toMatchObject({
           telemetryCheckpoint: {
@@ -230,14 +340,17 @@ export function runProjectionRunStorageContractSuite<TStorage extends Projection
     })
 
     test("keeps a missing target until the batch it blocks commits", async () => {
-      await withStorage(async (storage) => {
-        const claim = await storage.startOrReclaim({
+      await withStorage(async (context) => {
+        const storage = context.projectionRuns
+        const input = {
           id: "telemetry-missing-target-run",
           projectId,
           identity: telemetryIdentity,
           target: objectTarget,
           fixedBatchSize: 2,
-        })
+        } as const
+        await admitProjectionRun(context, input)
+        const claim = await storage.startOrReclaim(input)
         const execution = executionInput(claim)
         const firstSeenAt = new Date("2026-06-01T12:00:00.000Z")
         const missingTarget = {
@@ -307,14 +420,17 @@ export function runProjectionRunStorageContractSuite<TStorage extends Projection
     })
 
     test("requires and records explicit telemetry EOF with terminal success", async () => {
-      await withStorage(async (storage) => {
-        const claim = await storage.startOrReclaim({
+      await withStorage(async (context) => {
+        const storage = context.projectionRuns
+        const input = {
           id: "empty-telemetry-run",
           projectId,
           identity: telemetryIdentity,
           target: objectTarget,
           fixedBatchSize: 10,
-        })
+        } as const
+        await admitProjectionRun(context, input)
+        const claim = await storage.startOrReclaim(input)
 
         await expect(
           storage.finish({
@@ -345,10 +461,51 @@ export function runProjectionRunStorageContractSuite<TStorage extends Projection
       })
     })
 
+    test("validates, detaches, and persists scoped failures", async () => {
+      await withStorage(async (context) => {
+        const storage = context.projectionRuns
+        await admitProjectionRun(context, replacementInput("failed-run"))
+        const claim = await storage.startOrReclaim(replacementInput("failed-run"))
+        const finished = await storage.finish({
+          ...executionInput(claim),
+          protocol: "replacement",
+          status: "failed",
+          finishedAt: new Date(failure.at),
+          error: failure,
+        })
+
+        expect(finished).toMatchObject({
+          status: "failed",
+          finishedAt: new Date(failure.at),
+          error: failure,
+        })
+        expect(finished.error).not.toBe(failure)
+        await expect(storage.getById({ projectId, id: "failed-run" })).resolves.toMatchObject({
+          error: failure,
+        })
+
+        await admitProjectionRun(context, replacementInput("invalid-failure-run"))
+        const invalid = await storage.startOrReclaim(replacementInput("invalid-failure-run"))
+        await expect(
+          storage.finish({
+            ...executionInput(invalid),
+            protocol: "replacement",
+            status: "failed",
+            error: { ...failure, code: "dataset.not_found" } as never,
+          })
+        ).rejects.toThrow("code is not allowed by this failure contract")
+      })
+    })
+
     test("keeps equal run ids isolated by project", async () => {
-      await withStorage(async (storage) => {
-        await storage.startOrReclaim({ ...replacementInput("shared-id"), projectId: "project-a" })
-        await storage.startOrReclaim({ ...replacementInput("shared-id"), projectId: "project-b" })
+      await withStorage(async (context) => {
+        const storage = context.projectionRuns
+        const projectA = { ...replacementInput("shared-id"), projectId: "project-a" } as const
+        const projectB = { ...replacementInput("shared-id"), projectId: "project-b" } as const
+        await admitProjectionRun(context, projectA)
+        await admitProjectionRun(context, projectB)
+        await storage.startOrReclaim(projectA)
+        await storage.startOrReclaim(projectB)
 
         expect(await storage.getById({ projectId: "project-a", id: "shared-id" })).not.toBeNull()
         expect(await storage.getById({ projectId: "project-b", id: "shared-id" })).not.toBeNull()
@@ -358,6 +515,35 @@ export function runProjectionRunStorageContractSuite<TStorage extends Projection
   })
 }
 
+async function admitProjectionRun<TStorage extends ProjectionRunStorage>(
+  context: ProjectionRunStorageContractContext<TStorage>,
+  input: StartOrReclaimProjectionRunInput
+): Promise<QueueProjectionRunInput> {
+  const executionId = `execution:${input.projectId}:${input.id}`
+  await context.executions.create({
+    id: executionId,
+    projectId: input.projectId,
+    executor: { type: "primitive", kind: "projection", runId: input.id },
+    source: {
+      type: "datasetVersion",
+      datasetId: input.identity.datasetVersion.datasetId,
+      versionId: input.identity.datasetVersion.versionId,
+    },
+    correlationId: input.id,
+    authorizationRef: {
+      type: "trustedPrimitive",
+      primitive: { kind: "projection", id: input.identity.projectionId, runId: input.id },
+    },
+  })
+  const admission = {
+    ...input,
+    executionId,
+    queuedAt: new Date("2026-01-01T00:00:01.000Z"),
+  } satisfies QueueProjectionRunInput
+  await context.projectionRuns.queue(admission)
+  return admission
+}
+
 function replacementInput(id: string) {
   return { id, projectId, identity: replacementIdentity, target: objectTarget } as const
 }