@sixb/core 0.1.1 → 0.1.2

package/src/testing/queues-contract.ts

@@ -1,6 +1,14 @@
 import { describe, expect, test } from "bun:test"
 import { QueueError } from "../queues/errors"
-import type { Queues } from "../queues/types"
+import type { PipelineQueueJobFailureCode, QueueJobFailure, Queues } from "../queues/types"
+
+const TERMINAL_FAILURE = {
+  code: "internal.unexpected",
+  retryable: false,
+  message: "boom",
+  at: "2026-01-01T00:00:00.000Z",
+  details: { pipelineId: "p-1" },
+} as const satisfies QueueJobFailure<PipelineQueueJobFailureCode>
 
 export interface QueueContractSuiteOptions {
   /** Factory that produces a fresh `Queues` instance for each test case. */
@@ -56,7 +64,7 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
             jobs: [
               {
                 type: "sync.run.requested",
-                payload: { syncId: "sync-1", commitMessage: "manual" },
+                payload: { runId: "sync-1" },
               },
             ],
           })
@@ -65,7 +73,7 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
           expect(job?.projectId).toBe("project-a")
           expect(job?.attempt).toBe(0)
           expect(job?.type).toBe("sync.run.requested")
-          expect(job?.payload.syncId).toBe("sync-1")
+          expect(job?.payload.runId).toBe("sync-1")
           expect(Date.parse(job!.createdAt)).toBeGreaterThanOrEqual(before)
           expect(job?.availableAt).toBe(job?.createdAt)
         })
@@ -76,7 +84,7 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
           const input = {
             id: "dispatch-run-1",
             type: "sync.run.requested" as const,
-            payload: { syncId: "sync-1" },
+            payload: { runId: "sync-1" },
           }
           const [[first], [second]] = await Promise.all([
             queues.syncRuns.enqueue({ projectId: "project-a", jobs: [input] }),
@@ -97,7 +105,7 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
           const input = {
             id,
             type: "sync.run.requested" as const,
-            payload: { syncId: "sync-1" },
+            payload: { runId: "sync-1" },
           }
 
           const [[first], [duplicate]] = await Promise.all([
@@ -147,7 +155,7 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
           await expect(
             queues.syncRuns.enqueue({
               projectId: "   ",
-              jobs: [{ type: "sync.run.requested", payload: { syncId: "sync-1" } }],
+              jobs: [{ type: "sync.run.requested", payload: { runId: "sync-1" } }],
             })
           ).rejects.toBeInstanceOf(QueueError)
         })
@@ -159,7 +167,7 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
         await withQueues(async (queues) => {
           await queues.pipelines.enqueue({
             projectId: "project-a",
-            jobs: [{ type: "pipeline.run.requested", payload: { pipelineId: "p-1" } }],
+            jobs: [{ type: "pipeline.run.requested", payload: { runId: "p-1" } }],
           })
 
           const [claimed] = await queues.pipelines.claim({
@@ -168,7 +176,7 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
           })
 
           expect(claimed?.job.attempt).toBe(1)
-          expect(claimed?.job.payload.pipelineId).toBe("p-1")
+          expect(claimed?.job.payload.runId).toBe("p-1")
           expect(claimed?.leaseId).toBeTruthy()
           expect(Date.parse(claimed!.leaseExpiresAt)).toBeGreaterThan(
             Date.parse(claimed!.claimedAt)
@@ -180,7 +188,7 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
         await withQueues(async (queues) => {
           await queues.syncRuns.enqueue({
             projectId: "project-a",
-            jobs: [{ type: "sync.run.requested", payload: { syncId: "s-1" } }],
+            jobs: [{ type: "sync.run.requested", payload: { runId: "s-1" } }],
           })
 
           const zero = await queues.syncRuns.claim({
@@ -203,7 +211,7 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
         await withQueues(async (queues) => {
           await queues.syncRuns.enqueue({
             projectId: "project-a",
-            jobs: [{ type: "sync.run.requested", payload: { syncId: "s-1" } }],
+            jobs: [{ type: "sync.run.requested", payload: { runId: "s-1" } }],
           })
 
           await expect(
@@ -220,7 +228,7 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
           const availableAt = new Date(Date.now() + shortLeaseMs + 20).toISOString()
           await queues.syncRuns.enqueue({
             projectId: "project-a",
-            jobs: [{ type: "sync.run.requested", payload: { syncId: "s-1" }, availableAt }],
+            jobs: [{ type: "sync.run.requested", payload: { runId: "s-1" }, availableAt }],
           })
 
           const before = await queues.syncRuns.claim({
@@ -243,11 +251,11 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
         await withQueues(async (queues) => {
           await queues.syncRuns.enqueue({
             projectId: "project-a",
-            jobs: [{ type: "sync.run.requested", payload: { syncId: "a-1" } }],
+            jobs: [{ type: "sync.run.requested", payload: { runId: "a-1" } }],
           })
           await queues.syncRuns.enqueue({
             projectId: "project-b",
-            jobs: [{ type: "sync.run.requested", payload: { syncId: "b-1" } }],
+            jobs: [{ type: "sync.run.requested", payload: { runId: "b-1" } }],
           })
 
           const claimedB = await queues.syncRuns.claim({
@@ -257,7 +265,7 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
           })
 
           expect(claimedB).toHaveLength(1)
-          expect(claimedB[0]?.job.payload.syncId).toBe("b-1")
+          expect(claimedB[0]?.job.payload.runId).toBe("b-1")
           expect(claimedB[0]?.job.projectId).toBe("project-b")
         })
       })
@@ -266,30 +274,18 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
         await withQueues(async (queues) => {
           await queues.syncRuns.enqueue({
             projectId: "project-a",
-            jobs: [{ type: "sync.run.requested", payload: { syncId: "s-1" } }],
+            jobs: [{ type: "sync.run.requested", payload: { runId: "s-1" } }],
           })
           await queues.pipelines.enqueue({
             projectId: "project-a",
-            jobs: [{ type: "pipeline.run.requested", payload: { pipelineId: "p-1" } }],
+            jobs: [{ type: "pipeline.run.requested", payload: { runId: "p-1" } }],
           })
           await queues.projections.enqueue({
             projectId: "project-a",
             jobs: [
               {
                 type: "projection.run.requested",
-                payload: {
-                  projectionId: "room-projection",
-                  projectionKind: "object",
-                  protocol: "replacement",
-                  datasetVersion: {
-                    datasetId: "canonical.rooms",
-                    versionId: "ver_1",
-                    createdAt: "2026-01-01T00:00:00.000Z",
-                  },
-                  ontologyRevision: "ontology-v1",
-                  projectionRevision: "projection-v1",
-                  ownershipHash: "ownership-v1",
-                },
+                payload: { runId: "projection-run-1" },
               },
             ],
           })
@@ -298,12 +294,7 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
             jobs: [
               {
                 type: "workflow.run.requested",
-                payload: {
-                  workflowId: "reconcile-transaction",
-                  input: {
-                    transaction: { objectTypeId: "Transaction", primaryId: "txn_123" },
-                  },
-                },
+                payload: { runId: "workflow-run-1" },
               },
             ],
           })
@@ -313,7 +304,6 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
               {
                 type: "action.run.requested",
                 payload: {
-                  actionId: "mark-paid",
                   runId: "act_1",
                 },
               },
@@ -347,13 +337,13 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
           })
 
           expect(crossLane).toHaveLength(1)
-          expect(crossLane[0]?.job.payload.pipelineId).toBe("p-1")
+          expect(crossLane[0]?.job.payload.runId).toBe("p-1")
           expect(projectionLane).toHaveLength(1)
-          expect(projectionLane[0]?.job.payload.projectionId).toBe("room-projection")
+          expect(projectionLane[0]?.job.payload.runId).toBe("projection-run-1")
           expect(workflowLane).toHaveLength(1)
-          expect(workflowLane[0]?.job.payload.workflowId).toBe("reconcile-transaction")
+          expect(workflowLane[0]?.job.payload.runId).toBe("workflow-run-1")
           expect(actionLane).toHaveLength(1)
-          expect(actionLane[0]?.job.payload.actionId).toBe("mark-paid")
+          expect(actionLane[0]?.job.payload.runId).toBe("act_1")
           expect(sameLane).toHaveLength(1)
         })
       })
@@ -364,7 +354,7 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
         await withQueues(async (queues) => {
           const [job] = await queues.syncRuns.enqueue({
             projectId: "project-a",
-            jobs: [{ type: "sync.run.requested", payload: { syncId: "s-1" } }],
+            jobs: [{ type: "sync.run.requested", payload: { runId: "s-1" } }],
           })
           const [claim] = await queues.syncRuns.claim({
             projectId: "project-a",
@@ -390,7 +380,7 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
         await withQueues(async (queues) => {
           const [job] = await queues.syncRuns.enqueue({
             projectId: "project-a",
-            jobs: [{ type: "sync.run.requested", payload: { syncId: "s-1" } }],
+            jobs: [{ type: "sync.run.requested", payload: { runId: "s-1" } }],
           })
           await queues.syncRuns.claim({
             projectId: "project-a",
@@ -414,7 +404,7 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
         await withQueues(async (queues) => {
           const [job] = await queues.syncRuns.enqueue({
             projectId: "project-a",
-            jobs: [{ type: "sync.run.requested", payload: { syncId: "s-1" } }],
+            jobs: [{ type: "sync.run.requested", payload: { runId: "s-1" } }],
           })
           const [firstClaim] = await queues.syncRuns.claim({
             projectId: "project-a",
@@ -428,7 +418,6 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
             jobId: job!.id,
             leaseId: firstClaim!.leaseId,
             availableAt: retryAt,
-            error: { message: "try again" },
           })
           await Bun.sleep(retryRedeliveryMs + 30)
           const [secondClaim] = await queues.syncRuns.claim({
@@ -446,7 +435,7 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
         await withQueues(async (queues) => {
           const [job] = await queues.syncRuns.enqueue({
             projectId: "project-a",
-            jobs: [{ type: "sync.run.requested", payload: { syncId: "s-1" } }],
+            jobs: [{ type: "sync.run.requested", payload: { runId: "s-1" } }],
           })
           const [claim] = await queues.syncRuns.claim({
             projectId: "project-a",
@@ -471,7 +460,7 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
         await withQueues(async (queues) => {
           const [job] = await queues.pipelines.enqueue({
             projectId: "project-a",
-            jobs: [{ type: "pipeline.run.requested", payload: { pipelineId: "p-1" } }],
+            jobs: [{ type: "pipeline.run.requested", payload: { runId: "p-1" } }],
           })
           const [claim] = await queues.pipelines.claim({
             projectId: "project-a",
@@ -482,7 +471,7 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
             projectId: "project-a",
             jobId: job!.id,
             leaseId: claim!.leaseId,
-            error: { message: "boom" },
+            failure: TERMINAL_FAILURE,
           })
 
           const later = await queues.pipelines.claim({
@@ -500,7 +489,7 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
         await withQueues(async (queues) => {
           const [job] = await queues.syncRuns.enqueue({
             projectId: "project-a",
-            jobs: [{ type: "sync.run.requested", payload: { syncId: "s-1" } }],
+            jobs: [{ type: "sync.run.requested", payload: { runId: "s-1" } }],
           })
           const [claim] = await queues.syncRuns.claim({
             projectId: "project-a",
@@ -540,7 +529,7 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
         await withQueues(async (queues) => {
           const [job] = await queues.syncRuns.enqueue({
             projectId: "project-a",
-            jobs: [{ type: "sync.run.requested", payload: { syncId: "s-1" } }],
+            jobs: [{ type: "sync.run.requested", payload: { runId: "s-1" } }],
           })
           await queues.syncRuns.claim({
             projectId: "project-a",
@@ -565,7 +554,7 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
         await withQueues(async (queues) => {
           const [job] = await queues.syncRuns.enqueue({
             projectId: "project-a",
-            jobs: [{ type: "sync.run.requested", payload: { syncId: "s-1" } }],
+            jobs: [{ type: "sync.run.requested", payload: { runId: "s-1" } }],
           })
           const [first] = await queues.syncRuns.claim({
             projectId: "project-a",
@@ -590,7 +579,7 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
         await withQueues(async (queues) => {
           const [job] = await queues.syncRuns.enqueue({
             projectId: "project-a",
-            jobs: [{ type: "sync.run.requested", payload: { syncId: "s-1" } }],
+            jobs: [{ type: "sync.run.requested", payload: { runId: "s-1" } }],
           })
           const [claim] = await queues.syncRuns.claim({
             projectId: "project-a",

package/src/testing/sync-execution.ts

@@ -0,0 +1,61 @@
+import type { TrustedPrimitiveRef } from "../execution"
+import type { QueueSyncRunInput, Storage, SyncRunRecord } from "../storage"
+import type { ExecutionStorage } from "../storage/executions"
+
+/** Create the durable execution required by a Sync-run storage fixture. */
+export async function createTestSyncExecution(
+  executions: ExecutionStorage,
+  input: {
+    readonly projectId: string
+    readonly syncId: string
+    readonly runId: string
+    readonly executionId?: string
+  }
+): Promise<string> {
+  const executionId = input.executionId ?? `test_sync_execution:${input.runId}`
+  const existing = await executions.getById({ projectId: input.projectId, id: executionId })
+  if (existing) return executionId
+
+  const primitive: TrustedPrimitiveRef = {
+    kind: "sync",
+    id: input.syncId,
+    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 Sync run with the valid durable execution fixture required by every provider. */
+export async function queueTestSyncRun(
+  storage: Pick<Storage, "syncRuns" | "executions">,
+  input: Omit<QueueSyncRunInput, "executionId">
+): Promise<SyncRunRecord> {
+  if (!storage.syncRuns) throw new Error("Sync run storage is not configured for this test.")
+  const executionId = await createTestSyncExecution(storage.executions, {
+    projectId: input.projectId,
+    syncId: input.syncId,
+    runId: input.id,
+  })
+  return storage.syncRuns.queue({ ...input, executionId })
+}
+
+/** Start a Sync run after creating its durable execution and queued state. */
+export async function startTestSyncRun(
+  storage: Pick<Storage, "syncRuns" | "executions">,
+  input: Omit<QueueSyncRunInput, "executionId" | "queuedAt"> & { readonly startedAt?: Date }
+): Promise<SyncRunRecord> {
+  const { startedAt, ...queuedRun } = input
+  await queueTestSyncRun(storage, { ...queuedRun, queuedAt: startedAt })
+  return storage.syncRuns!.start({
+    id: input.id,
+    projectId: input.projectId,
+    startedAt,
+  })
+}

package/src/testing/webhook-execution.ts

@@ -0,0 +1,47 @@
+import type { TrustedPrimitiveRef } from "../execution"
+import type { StartWebhookRunInput, Storage, WebhookRunRecord } from "../storage"
+import type { ExecutionStorage } from "../storage/executions"
+
+/** Create the durable execution required by a Webhook-run storage fixture. */
+export async function createTestWebhookExecution(
+  executions: ExecutionStorage,
+  input: {
+    readonly projectId: string
+    readonly route: string
+    readonly runId: string
+    readonly executionId?: string
+  }
+): Promise<string> {
+  const executionId = input.executionId ?? `test_webhook_execution:${input.runId}`
+  const existing = await executions.getById({ projectId: input.projectId, id: executionId })
+  if (existing) return executionId
+
+  const primitive: TrustedPrimitiveRef = {
+    kind: "webhook",
+    id: input.route,
+    runId: input.runId,
+  }
+  await executions.create({
+    id: executionId,
+    projectId: input.projectId,
+    executor: { type: "primitive", kind: primitive.kind, runId: primitive.runId },
+    source: { type: "webhook", deliveryId: input.runId },
+    correlationId: `test_correlation:${input.runId}`,
+    authorizationRef: { type: "trustedPrimitive", primitive },
+  })
+  return executionId
+}
+
+/** Start a Webhook run with the valid durable execution fixture required by every provider. */
+export async function startTestWebhookRun(
+  storage: Pick<Storage, "webhookRuns" | "executions">,
+  input: Omit<StartWebhookRunInput, "executionId">
+): Promise<WebhookRunRecord> {
+  if (!storage.webhookRuns) throw new Error("Webhook run storage is not configured for this test.")
+  const executionId = await createTestWebhookExecution(storage.executions, {
+    projectId: input.projectId,
+    route: input.route,
+    runId: input.id,
+  })
+  return storage.webhookRuns.start({ ...input, executionId })
+}

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

@@ -0,0 +1,240 @@
+import { describe, expect, test } from "bun:test"
+import type { SixbFailure } from "../errors/types"
+import type { CreateExecutionInput, Storage } from "../storage"
+import type { WebhookRunFailureCode } from "../storage/webhook-runs"
+import { startTestWebhookRun } from "./webhook-execution"
+
+export type WebhookRunStorageContractStorage = Storage & {
+  readonly webhookRuns: NonNullable<Storage["webhookRuns"]>
+}
+
+export interface WebhookRunStorageContractSuiteOptions<
+  TStorage extends WebhookRunStorageContractStorage = WebhookRunStorageContractStorage,
+> {
+  readonly createStorage: () => TStorage | Promise<TStorage>
+  readonly cleanup?: (storage: TStorage) => void | Promise<void>
+}
+
+const projectId = "webhook-contract"
+const route = "/api/webhooks/github/events"
+const bodySha256 = "0".repeat(64)
+const finishedAt = new Date("2026-06-01T12:01:00.000Z")
+const retryableFailure = {
+  code: "webhook.delivery_failed",
+  message: "Webhook delivery failed.",
+  retryable: true,
+  at: finishedAt.toISOString(),
+  details: { connectorId: "github", webhookId: "events", runId: "delivery-retry" },
+} as const satisfies SixbFailure<WebhookRunFailureCode>
+const rejectedFailure = {
+  code: "webhook.delivery_rejected",
+  message: "Webhook delivery was rejected.",
+  retryable: false,
+  at: finishedAt.toISOString(),
+} as const satisfies SixbFailure<WebhookRunFailureCode>
+
+/** Runs the durable Webhook delivery contract against one complete storage provider. */
+export function runWebhookRunStorageContractSuite<
+  TStorage extends WebhookRunStorageContractStorage,
+>(label: string, options: WebhookRunStorageContractSuiteOptions<TStorage>): void {
+  const withStorage = async (body: (storage: TStorage) => Promise<void>): Promise<void> => {
+    const storage = await options.createStorage()
+    try {
+      await body(storage)
+    } finally {
+      await options.cleanup?.(storage)
+    }
+  }
+
+  describe(label, () => {
+    test("round-trips the immutable execution and delivery identity", async () => {
+      await withStorage(async (storage) => {
+        const run = await startTestWebhookRun(storage, runInput("delivery-1", "provider-1"))
+        expect(run).toMatchObject({
+          id: "delivery-1",
+          projectId,
+          executionId: "test_webhook_execution:delivery-1",
+          connectorId: "github",
+          webhookId: "events",
+          status: "running",
+          route,
+          requestBodyBytes: 12,
+          requestBodySha256: bodySha256,
+          idempotencyKey: "provider-1",
+        })
+        await expect(
+          storage.webhookRuns.getByDelivery({
+            projectId,
+            connectorId: "github",
+            webhookId: "events",
+            idempotencyKey: "provider-1",
+          })
+        ).resolves.toEqual(run)
+      })
+    })
+
+    test("rejects missing or mismatched execution authority", async () => {
+      await withStorage(async (storage) => {
+        const missing = runInput("missing-execution")
+        await expect(
+          storage.webhookRuns.start({ ...missing, executionId: "missing" })
+        ).rejects.toMatchObject({ code: "invalid_execution" })
+
+        await storage.executions.create(disabledRequestExecution("wrong-execution"))
+        await expect(
+          storage.webhookRuns.start({ ...missing, executionId: "wrong-execution" })
+        ).rejects.toMatchObject({ code: "invalid_execution" })
+      })
+    })
+
+    test("enforces one run per provider delivery key", async () => {
+      await withStorage(async (storage) => {
+        await startTestWebhookRun(storage, runInput("delivery-first", "provider-shared"))
+        await expect(
+          startTestWebhookRun(storage, runInput("delivery-second", "provider-shared"))
+        ).rejects.toMatchObject({ code: "duplicate_run" })
+      })
+    })
+
+    test("restarts only retryable failures without changing execution identity", async () => {
+      await withStorage(async (storage) => {
+        const started = await startTestWebhookRun(
+          storage,
+          runInput("delivery-retry", "provider-retry")
+        )
+        await storage.webhookRuns.finish({
+          projectId,
+          id: started.id,
+          status: "failed",
+          finishedAt,
+          responseStatus: 503,
+          error: retryableFailure,
+        })
+        const restarted = await storage.webhookRuns.restart({ projectId, id: started.id })
+        expect(restarted).toMatchObject({
+          id: started.id,
+          executionId: started.executionId,
+          status: "running",
+        })
+        expect(restarted.finishedAt).toBeUndefined()
+        expect(restarted.responseStatus).toBeUndefined()
+        expect(restarted.error).toBeUndefined()
+
+        await storage.webhookRuns.finish({
+          projectId,
+          id: started.id,
+          status: "succeeded",
+          responseStatus: 202,
+        })
+        await expect(
+          storage.webhookRuns.restart({ projectId, id: started.id })
+        ).rejects.toMatchObject({ code: "invalid_transition" })
+      })
+    })
+
+    test("does not reopen a terminal client rejection", async () => {
+      await withStorage(async (storage) => {
+        const run = await startTestWebhookRun(storage, runInput("delivery-rejected"))
+        await storage.webhookRuns.finish({
+          projectId,
+          id: run.id,
+          status: "failed",
+          finishedAt,
+          responseStatus: 422,
+          error: rejectedFailure,
+        })
+        await expect(storage.webhookRuns.restart({ projectId, id: run.id })).rejects.toMatchObject({
+          code: "invalid_transition",
+        })
+      })
+    })
+
+    test("persists a validated, detached failure through get and list", async () => {
+      await withStorage(async (storage) => {
+        const run = await startTestWebhookRun(storage, runInput("failed-run", "failed-key"))
+        const failedRunFailure = {
+          ...retryableFailure,
+          details: { ...retryableFailure.details, runId: run.id },
+        }
+        const mutableFailure = {
+          code: "webhook.delivery_failed" as const,
+          message: String(failedRunFailure.message),
+          retryable: true as const,
+          at: failedRunFailure.at,
+          details: {
+            connectorId: String(failedRunFailure.details.connectorId),
+            webhookId: String(failedRunFailure.details.webhookId),
+            runId: String(failedRunFailure.details.runId),
+          },
+        }
+        const finished = await storage.webhookRuns.finish({
+          projectId,
+          id: run.id,
+          status: "failed",
+          finishedAt,
+          responseStatus: 503,
+          error: mutableFailure,
+        })
+
+        mutableFailure.details.runId = "mutated-after-write"
+        expect(finished.error).toEqual(failedRunFailure)
+        await expect(storage.webhookRuns.getById({ projectId, id: run.id })).resolves.toMatchObject(
+          {
+            error: failedRunFailure,
+          }
+        )
+        await expect(
+          storage.webhookRuns.list({
+            projectId,
+            statuses: ["failed"],
+            idempotencyKey: "failed-key",
+          })
+        ).resolves.toMatchObject({ runs: [{ id: run.id, error: failedRunFailure }], total: 1 })
+      })
+    })
+
+    test("rejects failures outside the Webhook run contract without finishing", async () => {
+      await withStorage(async (storage) => {
+        const run = await startTestWebhookRun(storage, runInput("invalid-failure"))
+        await expect(
+          storage.webhookRuns.finish({
+            projectId,
+            id: run.id,
+            status: "failed",
+            finishedAt,
+            error: { ...retryableFailure, code: "runtime.cancelled" } as never,
+          })
+        ).rejects.toThrow("code is not allowed by this failure contract")
+        const unchanged = await storage.webhookRuns.getById({ projectId, id: run.id })
+        expect(unchanged?.status).toBe("running")
+        expect(unchanged?.error).toBeUndefined()
+      })
+    })
+  })
+}
+
+function runInput(id: string, idempotencyKey?: string) {
+  return {
+    id,
+    projectId,
+    connectorId: "github",
+    webhookId: "events",
+    method: "POST",
+    route,
+    requestBodyBytes: 12,
+    requestBodySha256: bodySha256,
+    ...(idempotencyKey === undefined ? {} : { idempotencyKey }),
+    startedAt: new Date("2026-06-01T12:00:00.000Z"),
+  }
+}
+
+function disabledRequestExecution(id: string): CreateExecutionInput {
+  return {
+    id,
+    projectId,
+    executor: { type: "request", requestId: id },
+    source: { type: "http", requestId: id },
+    correlationId: `correlation:${id}`,
+    authorizationRef: { type: "disabled" },
+  }
+}