@sixb/core 0.1.14 → 0.1.15

package/src/storage/projection-runs/lifecycle.ts

@@ -442,6 +442,15 @@ export function failProjectionRunEnqueue(
   }
 }
 
+/** Validates the failure of an attempt that leaves its run running, before it is stored. */
+export function parseProjectionAttemptFailure(
+  record: Pick<ProjectionRunRecord, "id" | "projectId" | "status">,
+  error: SixbFailure<ProjectionRunFailureCode>
+): SixbFailure<ProjectionRunFailureCode> {
+  assertProjectionRunRunning(record)
+  return parseSixbFailure(error, PROJECTION_RUN_FAILURE_CODES)
+}
+
 export function canRequeueProjectionRunAfterEnqueueFailure(
   record: ProjectionRunRecord,
   input: QueueProjectionRunInput
@@ -457,6 +466,34 @@ export function canRequeueProjectionRunAfterEnqueueFailure(
   )
 }
 
+/**
+ * Statuses of a run that still stands to replace its projection's source. A later run in one of
+ * them makes an earlier run stale; a failed or cancelled one replaces nothing.
+ */
+export const SUPERSEDING_PROJECTION_RUN_STATUSES = [
+  "queued",
+  "running",
+  "succeeded",
+] as const satisfies readonly ProjectionRunStatus[]
+
+/**
+ * Whether `newer` makes `run` stale. Dataset version timestamps are canonical UTC ISO strings, so
+ * they order as text; SQL adapters compare them under a binary collation for the same reason.
+ */
+export function projectionRunSupersedes(
+  newer: ProjectionRunRecord,
+  run: ProjectionRunRecord
+): boolean {
+  return (
+    run.identity.protocol === "replacement" &&
+    newer.identity.protocol === "replacement" &&
+    newer.projectId === run.projectId &&
+    newer.identity.projectionId === run.identity.projectionId &&
+    newer.identity.datasetVersion.createdAt > run.identity.datasetVersion.createdAt &&
+    (SUPERSEDING_PROJECTION_RUN_STATUSES as readonly ProjectionRunStatus[]).includes(newer.status)
+  )
+}
+
 // ── Persistence mapping ─────────────────────────────────────
 
 export function restoreProjectionRun(row: PersistedProjectionRunRecord): StoredProjectionRunRecord {
@@ -616,8 +653,7 @@ function assertPersistedLifecycle(row: PersistedProjectionRunRecord): void {
       row.attempt < 1 ||
       row.startedAt === undefined ||
       row.finishedAt !== undefined ||
-      row.executionToken === undefined ||
-      hasError
+      row.executionToken === undefined
     ) {
       throw incompleteProjectionRun(row.id)
     }
@@ -641,7 +677,12 @@ function assertPersistedLifecycle(row: PersistedProjectionRunRecord): void {
       return
     }
   }
-  if (row.attempt < 1 || row.startedAt === undefined || (row.status === "succeeded" && hasError)) {
+  if (
+    row.attempt < 1 ||
+    row.startedAt === undefined ||
+    ((row.status === "succeeded" || row.status === "superseded") && hasError) ||
+    (row.status === "superseded" && row.protocol !== "replacement")
+  ) {
     throw incompleteProjectionRun(row.id)
   }
 }
@@ -652,6 +693,17 @@ function assertProjectionRunDate(value: Date, fieldName: string): void {
   }
 }
 
+function isProjectionRunTerminalStatus(
+  status: unknown
+): status is ProjectionRunFinishPlan["status"] {
+  return (
+    status === "succeeded" ||
+    status === "failed" ||
+    status === "cancelled" ||
+    status === "superseded"
+  )
+}
+
 function isProjectionKind(value: unknown): value is ProjectionKind {
   return value === "object" || value === "link" || value === "telemetry"
 }
@@ -722,7 +774,7 @@ function assertFinishDecision(
   record: ProjectionRunRecord,
   input: ProjectionRunTerminalDecision
 ): void {
-  if (input.status !== "succeeded" && input.status !== "failed" && input.status !== "cancelled") {
+  if (!isProjectionRunTerminalStatus(input.status)) {
     throw new ProjectionRunError(
       `[Sixb] Projection run '${record.id}' finish status must be terminal.`
     )
@@ -735,6 +787,11 @@ function assertFinishDecision(
       `[Sixb] Projection run '${record.id}' finish protocol does not match its identity.`
     )
   }
+  if (input.status === "superseded" && input.protocol !== "replacement") {
+    throw new ProjectionRunError(
+      `[Sixb] Telemetry projection run '${record.id}' cannot be superseded.`
+    )
+  }
   const inputExhausted = "inputExhausted" in input ? input.inputExhausted : undefined
   if (input.status === "succeeded" && input.protocol === "telemetry") {
     if (inputExhausted === true) return

package/src/storage/projection-runs/types.ts

@@ -16,7 +16,18 @@ import type {
 export type { ProjectionRunFailureCode } from "../../projections/types"
 export { PROJECTION_RUN_FAILURE_CODES } from "../../projections/types"
 
-export type ProjectionRunStatus = "queued" | "running" | "succeeded" | "failed" | "cancelled"
+/**
+ * `superseded` ends a replacement run whose output would be stale on arrival: a run of the same
+ * projection pinned to a later dataset version exists and has not failed. Telemetry runs append
+ * readings rather than replace a source, so none is ever superseded.
+ */
+export type ProjectionRunStatus =
+  | "queued"
+  | "running"
+  | "succeeded"
+  | "failed"
+  | "cancelled"
+  | "superseded"
 
 export interface ProjectionRunProgress {
   /** Physical immutable-version rows consumed, before normalization or semantic materialization. */
@@ -76,6 +87,11 @@ interface ProjectionRunRecordBase {
   readonly queuedAt: Date
   readonly startedAt?: Date
   readonly finishedAt?: Date
+  /**
+   * The run's most recent failure, read with its status: on a `running` run, why its last attempt
+   * failed while the queue retries it; on a `failed` or `cancelled` run, why it ended. Cleared when
+   * the run succeeds or is superseded, so a present error always describes something current.
+   */
   readonly error?: SixbFailure<ProjectionRunFailureCode>
 }
 
@@ -202,6 +218,17 @@ export interface RecordProjectionMissingTargetInput
   readonly missingTarget: ProjectionMissingTarget
 }
 
+export interface RecordProjectionAttemptFailureInput
+  extends LockProjectionRunForMaterializationInput {
+  readonly error: SixbFailure<ProjectionRunFailureCode>
+}
+
+export interface FindSupersedingProjectionRunInput {
+  readonly projectId: string
+  /** The run that may be superseded. */
+  readonly id: string
+}
+
 export interface ListProjectionRunsInput {
   readonly projectId: string
   readonly projectionId?: string
@@ -258,10 +285,23 @@ export interface ProjectionRunStorage {
   recordMissingTarget(
     input: RecordProjectionMissingTargetInput
   ): Promise<TelemetryProjectionRunRecord>
+  /**
+   * Records the failure of the current attempt as the `error` of a run that stays `running` to be
+   * retried. Fenced like every other write: a delivery that lost the run cannot overwrite the
+   * failure of the one that holds it now. A reclaim keeps it until the run ends.
+   */
+  recordAttemptFailure(input: RecordProjectionAttemptFailureInput): Promise<ProjectionRunRecord>
   /** Telemetry success also records the worker's EOF observation atomically. */
   finish(input: FinishProjectionRunInput): Promise<ProjectionRunRecord>
+  /**
+   * The newest replacement run of the same projection that makes this one stale: pinned to a
+   * later dataset version, and queued, running, or succeeded. A failed or cancelled run replaces
+   * nothing, so it supersedes nothing either. Null for a telemetry run.
+   */
+  findSupersedingRun(input: FindSupersedingProjectionRunInput): Promise<ProjectionRunRecord | null>
   getById(params: { projectId: string; id: string }): Promise<ProjectionRunRecord | null>
   list(input: ListProjectionRunsInput): Promise<ListProjectionRunsResult>
+  /** Superseded runs are skipped: the run that superseded them is the one that matters. */
   listLatestByProjectionIds(
     input: ListLatestProjectionRunsInput
   ): Promise<ListLatestProjectionRunsResult>

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

@@ -410,38 +410,76 @@ export function runOntologyStorageContractSuite<TStorage extends OntologyStorage
             abandonedAt: "2026-01-01T00:03:00.000Z",
           })
         ).rejects.toMatchObject({ kind: "execution-lost" })
+        const adopted = await storage.ontology.sources.adopt({
+          projectId: "contract-project",
+          source,
+          execution: reclaimed.execution,
+          adoptedAt: "2026-01-01T00:01:30.000Z",
+        })
+        expect(adopted).toMatchObject({
+          record: {
+            materializationId: "staging-candidate",
+            status: "ready",
+            executionToken: reclaimed.execution.executionToken,
+            updatedAt: "2026-01-01T00:01:30.000Z",
+          },
+          resumeStagingOrdinal: 1,
+        })
+        // Adopting twice from the same execution is a no-op, not a second owner change.
+        expect(
+          await storage.ontology.sources.adopt({
+            projectId: "contract-project",
+            source,
+            execution: reclaimed.execution,
+            adoptedAt: "2026-01-01T00:01:40.000Z",
+          })
+        ).toMatchObject({ record: { executionToken: reclaimed.execution.executionToken } })
+
         const abandoned = await storage.ontology.sources.abandon({
-          kind: "reclaim",
+          kind: "run",
           projectId: "contract-project",
           source,
           execution: reclaimed.execution,
           abandonedAt: "2026-01-01T00:02:00.000Z",
         })
         expect(abandoned).toMatchObject({ status: "abandoned", executionToken: null })
+        expect(
+          await storage.ontology.sources.abandon({
+            kind: "run",
+            projectId: "contract-project",
+            source,
+            execution: reclaimed.execution,
+            abandonedAt: "2026-01-01T00:02:00.000Z",
+          })
+        ).toBeNull()
+        expect(
+          await storage.ontology.sources.adopt({
+            projectId: "contract-project",
+            source,
+            execution: reclaimed.execution,
+            adoptedAt: "2026-01-01T00:02:10.000Z",
+          })
+        ).toBeNull()
         expect(
           await storage.ontology.sources.summarizeTerminal({ projectId: "contract-project" })
         ).toEqual({ count: 1, oldestTerminalAt: "2026-01-01T00:02:00.000Z" })
 
+        // Superseded retention does not hold an abandoned candidate back.
         expect(
           await storage.ontology.sources.cleanupTerminal({
             projectId: "contract-project",
             terminalBefore: "2026-02-01T00:00:00.000Z",
-            limit: 1,
+            limit: 10,
           })
+        ).toEqual({ rowsDeleted: 0, materializationsDeleted: 0 })
+        expect(
+          await storage.ontology.sources.purgeAbandoned({ projectId: "contract-project", limit: 1 })
         ).toEqual({ rowsDeleted: 1, materializationsDeleted: 0 })
         expect(
-          await storage.ontology.sources.cleanupTerminal({
-            projectId: "contract-project",
-            terminalBefore: "2026-02-01T00:00:00.000Z",
-            limit: 1,
-          })
+          await storage.ontology.sources.purgeAbandoned({ projectId: "contract-project", limit: 1 })
         ).toEqual({ rowsDeleted: 1, materializationsDeleted: 0 })
         expect(
-          await storage.ontology.sources.cleanupTerminal({
-            projectId: "contract-project",
-            terminalBefore: "2026-02-01T00:00:00.000Z",
-            limit: 1,
-          })
+          await storage.ontology.sources.purgeAbandoned({ projectId: "contract-project", limit: 1 })
         ).toEqual({ rowsDeleted: 0, materializationsDeleted: 1 })
         expect(
           await storage.ontology.sources.summarizeTerminal({ projectId: "contract-project" })
@@ -449,6 +487,95 @@ export function runOntologyStorageContractSuite<TStorage extends OntologyStorage
       })
     })
 
+    test("adopts a staging candidate at its last staged root", async () => {
+      await withStorage(async (storage) => {
+        const identity = replacementIdentity("01")
+        const claimed = await startTestProjectionRun(storage, {
+          id: "resumed-run",
+          projectId: "contract-project",
+          identity,
+          target: { objectTypeId: "ContractDevice" },
+        })
+        const source = { projectionId: identity.projectionId }
+        await storage.ontology.sources.beginMaterialization({
+          projectId: "contract-project",
+          source,
+          materializationId: "resumed-candidate",
+          execution: claimed.execution,
+          projectionKind: "object",
+          protocol: "replacement",
+          datasetVersion: identity.datasetVersion,
+          projectionRevision: identity.projectionRevision,
+          ownershipHash: identity.ownershipHash,
+          ontologyRevision: identity.ontologyRevision,
+          createdAt: "2026-01-01T00:00:00.000Z",
+        })
+        const row = (primaryId: string, stagingOrdinal: number) => ({
+          root: { kind: "object" as const, ref: { objectTypeId: "ContractDevice", primaryId } },
+          assertion: {
+            kind: "object" as const,
+            ref: { objectTypeId: "ContractDevice", primaryId },
+            properties: { name: primaryId },
+          },
+          stagingOrdinal,
+        })
+        await storage.ontology.sources.stageRows({
+          projectId: "contract-project",
+          source,
+          materializationId: "resumed-candidate",
+          execution: claimed.execution,
+          rows: [row("zero", 0), row("one", 1)],
+        })
+
+        const reclaimed = await storage.projectionRuns.startOrReclaim({
+          id: claimed.run.id,
+          projectId: claimed.run.projectId,
+          identity,
+          target: { objectTypeId: "ContractDevice" },
+        })
+        const adopted = await storage.ontology.sources.adopt({
+          projectId: "contract-project",
+          source,
+          execution: reclaimed.execution,
+          adoptedAt: "2026-01-01T00:01:00.000Z",
+        })
+        expect(adopted).toMatchObject({
+          record: { status: "staging", executionToken: reclaimed.execution.executionToken },
+          resumeStagingOrdinal: 1,
+        })
+        // The previous execution lost the candidate with the run.
+        await expect(
+          storage.ontology.sources.stageRows({
+            projectId: "contract-project",
+            source,
+            materializationId: "resumed-candidate",
+            execution: claimed.execution,
+            rows: [row("two", 2)],
+          })
+        ).rejects.toMatchObject({ kind: "execution-lost" })
+        expect(
+          await storage.ontology.sources.stageRows({
+            projectId: "contract-project",
+            source,
+            materializationId: "resumed-candidate",
+            execution: reclaimed.execution,
+            rows: [row("one", 1), row("two", 2)],
+          })
+        ).toEqual({ inserted: 1, unchanged: 1 })
+        expect(
+          await storage.ontology.sources.markReady({
+            projectId: "contract-project",
+            source,
+            materializationId: "resumed-candidate",
+            execution: reclaimed.execution,
+            rootCount: 3,
+            assertionCount: 3,
+            readyAt: "2026-01-01T00:02:00.000Z",
+          })
+        ).toMatchObject({ status: "ready", rootCount: 3 })
+      })
+    })
+
     test("atomically activates explicit empty candidates and rejects competing stale heads", async () => {
       await withStorage(async (storage) => {
         const first = await createReadyEmptyCandidate(storage, "run-one", "candidate-one", "01")
@@ -532,16 +659,15 @@ export function runOntologyStorageContractSuite<TStorage extends OntologyStorage
           )
         ).rejects.toThrow("execution token is stale")
         await storage.ontology.sources.abandon({
-          kind: "reclaim",
+          kind: "run",
           projectId: "contract-project",
           source: stale.source,
           execution: reclaimed.execution,
           abandonedAt: "2026-01-06T00:01:00.000Z",
         })
 
-        const cleanup = await storage.ontology.sources.cleanupTerminal({
+        const cleanup = await storage.ontology.sources.purgeAbandoned({
           projectId: "contract-project",
-          terminalBefore: "2026-02-01T00:00:00.000Z",
           limit: 10,
         })
         expect(cleanup.materializationsDeleted).toBeGreaterThanOrEqual(1)

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

@@ -41,6 +41,13 @@ const failure = {
   details: { projectionId: "contract.devices", runId: "failed-run" },
 } as const satisfies SixbFailure<ProjectionRunFailureCode>
 
+const attemptFailure = {
+  code: "storage.unavailable",
+  message: "Storage is temporarily unavailable.",
+  retryable: true,
+  at: "2026-06-01T11:00:00.000Z",
+} as const satisfies SixbFailure<ProjectionRunFailureCode>
+
 const replacementIdentity = {
   projectionId: "contract.devices",
   projectionKind: "object",
@@ -149,11 +156,149 @@ export function runProjectionRunStorageContractSuite<TStorage extends Projection
           error: { code: "queue.enqueue_failed", message: "queue unavailable" },
         })
 
-        await expect(context.projectionRuns.queue(admission)).resolves.toMatchObject({
+        const requeued = await context.projectionRuns.queue(admission)
+        expect(requeued).toMatchObject({
           executionId: admission.executionId,
           status: "queued",
           attempt: 0,
         })
+        expect(requeued.error).toBeUndefined()
+      })
+    })
+
+    test("keeps the failure of a retried attempt until the run ends", async () => {
+      await withStorage(async (context) => {
+        const storage = context.projectionRuns
+        const input = replacementInput("retried-run")
+        await admitProjectionRun(context, input)
+        const first = await storage.startOrReclaim(input)
+
+        const failed = await storage.recordAttemptFailure({
+          ...executionInput(first),
+          error: attemptFailure,
+        })
+        expect(failed).toMatchObject({ status: "running", error: attemptFailure })
+
+        const second = await storage.startOrReclaim(input)
+        expect(second.run).toMatchObject({ attempt: 2, error: attemptFailure })
+        await expect(
+          storage.recordAttemptFailure({ ...executionInput(first), error: failure })
+        ).rejects.toThrow("execution token is stale")
+        await expect(
+          storage.recordAttemptFailure({
+            ...executionInput(second),
+            error: { ...failure, code: "dataset.not_found" } as never,
+          })
+        ).rejects.toThrow("code is not allowed by this failure contract")
+
+        const succeeded = await storage.finish({
+          ...executionInput(second),
+          protocol: "replacement",
+          status: "succeeded",
+        })
+        expect(succeeded).toMatchObject({ status: "succeeded" })
+        expect(succeeded.error).toBeUndefined()
+        await expect(
+          storage.recordAttemptFailure({ ...executionInput(second), error: failure })
+        ).rejects.toThrow("already terminal")
+      })
+    })
+
+    test("finds the newest later run that still stands to replace a source", async () => {
+      await withStorage(async (context) => {
+        const storage = context.projectionRuns
+        const current = replacementInput("current-run")
+        const earlier = versionedReplacementInput("earlier-run", "version-0", "2025-12-31")
+        const later = versionedReplacementInput("later-run", "version-2", "2026-01-02")
+        const latest = versionedReplacementInput("latest-run", "version-3", "2026-01-03")
+        const otherProjection = {
+          ...versionedReplacementInput("other-projection-run", "version-4", "2026-01-04"),
+          identity: {
+            ...versionedReplacementInput("other", "version-4", "2026-01-04").identity,
+            projectionId: "contract.rooms",
+          },
+        }
+        for (const input of [current, earlier, later, latest, otherProjection]) {
+          await admitProjectionRun(context, input)
+        }
+        const superseding = () => storage.findSupersedingRun({ projectId, id: current.id })
+
+        await expect(superseding()).resolves.toMatchObject({ id: latest.id, status: "queued" })
+        await expect(storage.findSupersedingRun({ projectId, id: latest.id })).resolves.toBeNull()
+
+        // A run that failed or was cancelled replaces nothing, so it supersedes nothing either.
+        await finishClaimed(context, latest, "failed")
+        await expect(superseding()).resolves.toMatchObject({ id: later.id })
+        await finishClaimed(context, later, "cancelled")
+        await expect(superseding()).resolves.toBeNull()
+
+        const telemetry = {
+          id: "telemetry-run",
+          projectId,
+          identity: telemetryIdentity,
+          target: objectTarget,
+          fixedBatchSize: 2,
+        } as const
+        await admitProjectionRun(context, telemetry)
+        await expect(
+          storage.findSupersedingRun({ projectId, id: telemetry.id })
+        ).resolves.toBeNull()
+        await expect(storage.findSupersedingRun({ projectId, id: "missing-run" })).rejects.toThrow(
+          "not found"
+        )
+      })
+    })
+
+    test("ends a superseded run without a failure and never reports it as the latest", async () => {
+      await withStorage(async (context) => {
+        const storage = context.projectionRuns
+        const stale = replacementInput("stale-run")
+        const newer = versionedReplacementInput("newer-run", "version-2", "2026-01-02")
+        await admitProjectionRun(context, stale)
+        await admitProjectionRun(context, newer)
+        // Started after the newer run was queued, so it is the most recent by activity.
+        // Removal proof: drop the superseded filter from listLatestByProjectionIds.
+        const claim = await storage.startOrReclaim({
+          ...stale,
+          startedAt: new Date("2026-01-01T00:00:05.000Z"),
+        })
+
+        const superseded = await storage.finish({
+          ...executionInput(claim),
+          protocol: "replacement",
+          status: "superseded",
+        })
+
+        expect(superseded).toMatchObject({ status: "superseded", attempt: 1 })
+        expect(superseded.error).toBeUndefined()
+        expect(superseded.finishedAt).toBeInstanceOf(Date)
+        await expect(
+          storage.listLatestByProjectionIds({
+            projectId,
+            projectionIds: [replacementIdentity.projectionId],
+          })
+        ).resolves.toMatchObject({ runs: [{ id: newer.id, status: "queued" }] })
+        await expect(storage.list({ projectId, statuses: ["superseded"] })).resolves.toMatchObject({
+          runs: [{ id: stale.id }],
+          total: 1,
+        })
+
+        const telemetry = {
+          id: "telemetry-run",
+          projectId,
+          identity: telemetryIdentity,
+          target: objectTarget,
+          fixedBatchSize: 2,
+        } as const
+        await admitProjectionRun(context, telemetry)
+        const telemetryClaim = await storage.startOrReclaim(telemetry)
+        await expect(
+          storage.finish({
+            ...executionInput(telemetryClaim),
+            protocol: "telemetry",
+            status: "superseded",
+          } as never)
+        ).rejects.toThrow("cannot be superseded")
       })
     })
 
@@ -582,6 +727,34 @@ function replacementInput(id: string) {
   return { id, projectId, identity: replacementIdentity, target: objectTarget } as const
 }
 
+/** A replacement run of the same projection, pinned to another version created on `day`. */
+function versionedReplacementInput(id: string, versionId: string, day: string) {
+  return {
+    ...replacementInput(id),
+    identity: {
+      ...replacementIdentity,
+      datasetVersion: {
+        ...replacementIdentity.datasetVersion,
+        versionId,
+        createdAt: `${day}T00:00:00.000Z`,
+      },
+    },
+  } as const
+}
+
+async function finishClaimed<TStorage extends ProjectionRunStorage>(
+  context: ProjectionRunStorageContractContext<TStorage>,
+  input: StartOrReclaimProjectionRunInput,
+  status: "failed" | "cancelled"
+): Promise<void> {
+  const claim = await context.projectionRuns.startOrReclaim(input)
+  await context.projectionRuns.finish({
+    ...executionInput(claim),
+    protocol: "replacement",
+    status,
+  })
+}
+
 function executionInput(claim: ProjectionRunClaim) {
   return {
     id: claim.run.id,

package/dist/chunk-3qpcrcj8.js.map

@@ -1,10 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../src/materialization/dataset-watermark.ts"],
-  "sourcesContent": [
-    "import { MaterializationConflictError } from \"./errors\"\nimport type { PinnedDatasetVersion } from \"./model\"\n\nexport type PinnedDatasetWatermarkConflict =\n  | \"dataset-mismatch\"\n  | \"version-metadata-mismatch\"\n  | \"older-version\"\n  | \"ambiguous-version\"\n\nexport function comparePinnedDatasetWatermarks(\n  active: PinnedDatasetVersion,\n  next: PinnedDatasetVersion\n): PinnedDatasetWatermarkConflict | null {\n  if (active.datasetId !== next.datasetId) return \"dataset-mismatch\"\n  if (active.versionId === next.versionId && active.createdAt !== next.createdAt) {\n    return \"version-metadata-mismatch\"\n  }\n\n  const activeAt = Date.parse(active.createdAt)\n  const nextAt = Date.parse(next.createdAt)\n  if (nextAt < activeAt) return \"older-version\"\n  if (nextAt === activeAt && next.versionId !== active.versionId) return \"ambiguous-version\"\n  return null\n}\n\nexport function assertPinnedDatasetWatermark(\n  active: PinnedDatasetVersion,\n  next: PinnedDatasetVersion,\n  subject: string\n): void {\n  const conflict = comparePinnedDatasetWatermarks(active, next)\n  if (!conflict) return\n\n  const message = pinnedDatasetWatermarkConflictMessage(conflict, subject)\n  throw new MaterializationConflictError(\"projection-fence\", message)\n}\n\nfunction pinnedDatasetWatermarkConflictMessage(\n  conflict: PinnedDatasetWatermarkConflict,\n  subject: string\n): string {\n  switch (conflict) {\n    case \"dataset-mismatch\":\n      return `${subject} dataset does not match the active source dataset.`\n    case \"version-metadata-mismatch\":\n      return `${subject} reused an immutable dataset version id with different metadata.`\n    case \"older-version\":\n      return `${subject} dataset version is older than the active watermark.`\n    case \"ambiguous-version\":\n      return `${subject} dataset watermark is ambiguous.`\n  }\n}\n"
-  ],
-  "mappings": ";;;;;;AASO,SAAS,+BAA8B,CAC5C,QACA,MACuC;AAAA,EACvC,IAAI,OAAO,cAAc,KAAK;AAAA,IAAW,OAAO;AAAA,EAChD,IAAI,OAAO,cAAc,KAAK,aAAa,OAAO,cAAc,KAAK,WAAW;AAAA,IAC9E,OAAO;AAAA,EACT;AAAA,EAEA,MAAM,WAAW,KAAK,MAAM,OAAO,SAAS;AAAA,EAC5C,MAAM,SAAS,KAAK,MAAM,KAAK,SAAS;AAAA,EACxC,IAAI,SAAS;AAAA,IAAU,OAAO;AAAA,EAC9B,IAAI,WAAW,YAAY,KAAK,cAAc,OAAO;AAAA,IAAW,OAAO;AAAA,EACvE,OAAO;AAAA;AAGF,SAAS,6BAA4B,CAC1C,QACA,MACA,SACM;AAAA,EACN,MAAM,WAAW,gCAA+B,QAAQ,IAAI;AAAA,EAC5D,IAAI,CAAC;AAAA,IAAU;AAAA,EAEf,MAAM,UAAU,sCAAsC,UAAU,OAAO;AAAA,EACvE,MAAM,IAAI,8BAA6B,oBAAoB,OAAO;AAAA;AAGpE,SAAS,qCAAqC,CAC5C,UACA,SACQ;AAAA,EACR,QAAQ;AAAA,SACD;AAAA,MACH,OAAO,GAAG;AAAA,SACP;AAAA,MACH,OAAO,GAAG;AAAA,SACP;AAAA,MACH,OAAO,GAAG;AAAA,SACP;AAAA,MACH,OAAO,GAAG;AAAA;AAAA;",
-  "debugId": "76FA48CB1D1BE09F64756E2164756E21",
-  "names": []
-}

package/dist/chunk-qma80ych.js.map

@@ -1,11 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../src/projections/types.ts", "../src/storage/projection-runs/types.ts"],
-  "sourcesContent": [
-    "import type { SixbErrorCode } from \"../errors/types\"\n\n/** Error codes a projection run can persist and expose through its public contract. */\nexport const PROJECTION_RUN_FAILURE_CODES = [\n  \"internal.unexpected\",\n  \"runtime.cancelled\",\n  \"queue.enqueue_failed\",\n  \"projection.execution_failed\",\n] as const satisfies readonly [SixbErrorCode, ...SixbErrorCode[]]\n\nexport type ProjectionRunFailureCode = (typeof PROJECTION_RUN_FAILURE_CODES)[number]\n\n/**\n * Lowered, serializable definition interfaces for projection DSL.\n *\n * These are the runtime-inspectable data structures that projection builders\n * lower into. They use plain string ids (no tokens, no methods) so they can\n * be stored, serialized, and introspected by tooling.\n */\n\n/**\n * Describes how a foreign key column in a dataset resolves to a link target.\n *\n * The source can be either a projected source property or a raw dataset field.\n * Its value equals the target object's primary property value, creating an\n * implicit link between source and target.\n *\n * `targetObjectTypeId` declares the concrete target type for this projection.\n * It must be the same type or a subtype (via `extends`) of the link's declared\n * target at the ontology level. Validation of the subtype relationship happens\n * at Sixb startup (Increment 7), not at DSL build time.\n */\nexport interface ForeignKeyDescriptor {\n  readonly linkId: string\n  /** Object property holding the target id. Mutually exclusive with sourceField. */\n  readonly sourcePropertyId?: string\n  /** Dataset column holding the target id. Mutually exclusive with sourcePropertyId. */\n  readonly sourceField?: string\n  readonly targetObjectTypeId: string\n}\n\n/** Resolves competing source-projection and managed-edit values for projected properties. */\nexport type SourceEditConflictResolution =\n  | { readonly strategy: \"editsWin\" }\n  | { readonly strategy: \"mostRecent\"; readonly sourceTimestamp: string }\n\n/**\n * Lowered, serializable definition for projecting a dataset into object instances.\n *\n * Each row contributes one complete object root to an authoritative replacement snapshot, with\n * properties mapped from dataset columns to object type properties. Duplicate roots are rejected.\n * FK links are resolved from source property or dataset field values to target object primary\n * values.\n */\nexport interface ObjectProjectionDefinition {\n  readonly _tag: \"ObjectProjectionDefinition\"\n  readonly id: string\n  readonly objectTypeId: string\n  readonly datasetId: string\n  /** Maps object type property id -> dataset column name. */\n  readonly properties: Readonly<Record<string, string>>\n  /** Maps link id -> FK descriptor. Empty `{}` when no FK links are projected. */\n  readonly links: Readonly<Record<string, ForeignKeyDescriptor>>\n  /** Defaults to `editsWin` when omitted by a legacy lowered definition. */\n  readonly conflictResolution?: SourceEditConflictResolution\n}\n\n/**\n * Lowered, serializable definition for projecting a join dataset into link instances.\n *\n * Each row in the join dataset contributes one complete link root to an authoritative replacement\n * snapshot, identified by its source, link id, and target. Duplicate roots are rejected.\n */\nexport interface LinkProjectionDefinition {\n  readonly _tag: \"LinkProjectionDefinition\"\n  readonly id: string\n  readonly linkId: string\n  readonly sourceObjectTypeId: string\n  readonly targetObjectTypeId: string\n  readonly datasetId: string\n  /** Dataset column holding the source object's primary property value. */\n  readonly sourceField: string\n  /** Dataset column holding the target object's primary property value. */\n  readonly targetField: string\n}\n\n/** Dataset columns that produce one telemetry property value. */\nexport interface TelemetryProjectionPropertyMapping {\n  /** Dataset column holding the telemetry value. */\n  readonly valueField: string\n  /** Dataset column holding the telemetry unit, when the property requires one. */\n  readonly unitField?: string\n}\n\n/**\n * Lowered, serializable definition for projecting dataset rows into telemetry history.\n *\n * Each row shares one target object id and observation timestamp, then contributes up to one\n * telemetry point for every mapped property. A property-token projection is lowered to the same\n * shape with one entry, so execution and ownership have one canonical contract.\n */\nexport interface TelemetryProjectionDefinition {\n  readonly _tag: \"TelemetryProjectionDefinition\"\n  readonly id: string\n  readonly objectTypeId: string\n  readonly datasetId: string\n  /** Dataset column holding the target object's primary id. */\n  readonly objectIdField: string\n  /** Dataset column holding the telemetry observation timestamp. */\n  readonly atField: string\n  /** Maps telemetry property id -> value and optional unit dataset columns. */\n  readonly properties: Readonly<Record<string, TelemetryProjectionPropertyMapping>>\n}\n\n/** Union of all projection definition types. */\nexport type ProjectionDefinition =\n  | ObjectProjectionDefinition\n  | LinkProjectionDefinition\n  | TelemetryProjectionDefinition\n\nexport interface ProjectionOwnership {\n  readonly objects: readonly {\n    readonly objectTypeId: string\n    readonly existence: boolean\n    readonly propertyIds: readonly string[]\n  }[]\n  readonly links: readonly {\n    readonly sourceObjectTypeId: string\n    readonly linkId: string\n  }[]\n  readonly telemetry: readonly {\n    readonly objectTypeId: string\n    readonly propertyId: string\n  }[]\n}\n\n/** Canonical correlation between a projection kind and its materialization protocol. */\nexport type ProjectionProtocolIdentity =\n  | { readonly projectionKind: \"object\"; readonly protocol: \"replacement\" }\n  | { readonly projectionKind: \"link\"; readonly protocol: \"replacement\" }\n  | { readonly projectionKind: \"telemetry\"; readonly protocol: \"telemetry\" }\n\nexport type ProjectionKind = ProjectionProtocolIdentity[\"projectionKind\"]\n\nexport interface ObjectProjectionTarget {\n  readonly objectTypeId: string\n}\n\nexport interface LinkProjectionTarget {\n  readonly sourceObjectTypeId: string\n  readonly targetObjectTypeId: string\n}\n\nexport interface ProjectionTargetByKind {\n  readonly object: ObjectProjectionTarget\n  readonly link: LinkProjectionTarget\n  readonly telemetry: ObjectProjectionTarget\n}\n\n/** Object types affected by one projection, correlated with its projection kind. */\nexport type ProjectionTarget<TKind extends ProjectionKind = ProjectionKind> =\n  ProjectionTargetByKind[TKind]\n\n/**\n * Frozen semantic identity used to dispatch one registered projection.\n *\n * Dataset version metadata is attached only when a committed dataset event is routed. Keeping the\n * registry-owned fields together prevents the orchestrator from recomputing ontology semantics.\n */\nexport type ProjectionDispatchDescriptor = ProjectionDispatchDescriptorBase &\n  ProjectionProtocolIdentity\n\ninterface ProjectionDispatchDescriptorBase {\n  readonly projectionId: string\n  readonly datasetId: string\n  readonly ontologyRevision: string\n  readonly projectionRevision: string\n  readonly ownershipHash: string\n}\n\nexport interface ResolvedProjection<TDefinition extends ProjectionDefinition> {\n  readonly projectionId: string\n  readonly datasetId: string\n  readonly projectionRevision: string\n  readonly ownershipHash: string\n  readonly ownership: ProjectionOwnership\n  readonly definition: TDefinition\n}\n",
-    "import type { SixbFailure } from \"../../errors/types\"\nimport type {\n  PinnedDatasetVersion,\n  ProjectionExecution,\n  ProjectionMaterializationIdentity,\n  ProjectionRunTerminalDecision,\n} from \"../../materialization/model\"\nimport type {\n  LinkProjectionTarget,\n  ObjectProjectionTarget,\n  ProjectionKind,\n  ProjectionRunFailureCode,\n  ProjectionTarget,\n} from \"../../projections/types\"\n\nexport type { ProjectionRunFailureCode } from \"../../projections/types\"\nexport { PROJECTION_RUN_FAILURE_CODES } from \"../../projections/types\"\n\nexport type ProjectionRunStatus = \"queued\" | \"running\" | \"succeeded\" | \"failed\" | \"cancelled\"\n\nexport interface ProjectionRunProgress {\n  /** Physical immutable-version rows consumed, before normalization or semantic materialization. */\n  readonly sourceRowsRead: number\n  /** Physical rows intentionally skipped because a required mapped value was blank. */\n  readonly sourceRowsSkipped: number\n  /** Maximum complete change records consumed by one incremental attempt; not a recovery cursor. */\n  readonly sourceChangesRead?: number\n}\n\nconst progressKeyFlags: Record<keyof ProjectionRunProgress, true> = {\n  sourceRowsRead: true,\n  sourceRowsSkipped: true,\n  sourceChangesRead: true,\n}\n\nexport const PROJECTION_RUN_PROGRESS_KEYS = Object.keys(\n  progressKeyFlags\n) as readonly (keyof ProjectionRunProgress)[]\n\nexport function zeroProjectionRunProgress(): ProjectionRunProgress {\n  return { sourceRowsRead: 0, sourceRowsSkipped: 0 }\n}\n\nexport interface ProjectionTelemetryCheckpoint {\n  readonly fixedBatchSize: number\n  readonly nextBatchOrdinal: number\n  readonly nextRowOffset: number\n  readonly inputExhausted: boolean\n}\n\n/**\n * The object a telemetry batch is waiting for, and when this run first found it missing.\n *\n * A projection's dataset can legitimately be materialized before the objects it references, so\n * the run waits instead of failing. The wait needs a start, and the run has no other durable one:\n * `startedAt` is when the run began, which on a batched projection is long before the batch that\n * cannot commit, and `attempt` counts every reclaim including the ones an unreachable queue caused.\n *\n * Cleared by any committed batch, so a run that is making progress never carries a stale wait.\n */\nexport interface ProjectionMissingTarget {\n  readonly objectTypeId: string\n  readonly objectId: string\n  /** The batch that could not commit because of it. */\n  readonly batchOrdinal: number\n  readonly firstSeenAt: Date\n}\n\ninterface ProjectionRunRecordBase {\n  readonly id: string\n  readonly projectId: string\n  readonly executionId: string\n  readonly status: ProjectionRunStatus\n  readonly attempt: number\n  readonly progress: ProjectionRunProgress\n  readonly queuedAt: Date\n  readonly startedAt?: Date\n  readonly finishedAt?: Date\n  readonly error?: SixbFailure<ProjectionRunFailureCode>\n}\n\ntype ProjectionIdentity<TKind extends ProjectionKind> = Extract<\n  ProjectionMaterializationIdentity,\n  { readonly projectionKind: TKind }\n>\n\nexport type ObjectProjectionRunRecord = ProjectionRunRecordBase & {\n  readonly identity: ProjectionIdentity<\"object\">\n  readonly target: ObjectProjectionTarget\n  readonly telemetryCheckpoint?: never\n  readonly missingTarget?: never\n}\n\nexport type LinkProjectionRunRecord = ProjectionRunRecordBase & {\n  readonly identity: ProjectionIdentity<\"link\">\n  readonly target: LinkProjectionTarget\n  readonly telemetryCheckpoint?: never\n  readonly missingTarget?: never\n}\n\nexport type TelemetryProjectionRunRecord = ProjectionRunRecordBase & {\n  readonly identity: ProjectionIdentity<\"telemetry\">\n  readonly target: ObjectProjectionTarget\n  readonly telemetryCheckpoint: ProjectionTelemetryCheckpoint\n  /**\n   * Only telemetry carries this: `MaterializationObjectNotFoundError` is raised by telemetry\n   * validation alone, and only a batched protocol has a checkpoint to anchor the wait to.\n   */\n  readonly missingTarget?: ProjectionMissingTarget\n}\n\n/** Durable projection lifecycle state. The execution token is deliberately returned separately. */\nexport type ProjectionRunRecord =\n  | ObjectProjectionRunRecord\n  | LinkProjectionRunRecord\n  | TelemetryProjectionRunRecord\n\nexport function projectionRunObjectTypesVisible(\n  run: ProjectionRunRecord,\n  canView: (objectTypeId: string) => boolean\n): boolean {\n  const target: ProjectionTarget = run.target\n  if (\"sourceObjectTypeId\" in target) {\n    return canView(target.sourceObjectTypeId) && canView(target.targetObjectTypeId)\n  }\n  return canView(target.objectTypeId)\n}\n\ninterface ProjectionRunAdmissionBase {\n  readonly id: string\n  readonly projectId: string\n  readonly executionId: string\n  readonly queuedAt?: Date\n}\n\nexport type QueueProjectionRunInput =\n  | (ProjectionRunAdmissionBase & {\n      readonly identity: ProjectionIdentity<\"object\">\n      readonly target: ObjectProjectionRunRecord[\"target\"]\n      readonly fixedBatchSize?: never\n    })\n  | (ProjectionRunAdmissionBase & {\n      readonly identity: ProjectionIdentity<\"link\">\n      readonly target: LinkProjectionRunRecord[\"target\"]\n      readonly fixedBatchSize?: never\n    })\n  | (ProjectionRunAdmissionBase & {\n      readonly identity: ProjectionIdentity<\"telemetry\">\n      readonly target: TelemetryProjectionRunRecord[\"target\"]\n      readonly fixedBatchSize: number\n    })\n\nexport type StartOrReclaimProjectionRunInput = QueueProjectionRunInput extends infer TInput\n  ? TInput extends QueueProjectionRunInput\n    ? Omit<TInput, \"executionId\" | \"queuedAt\"> & { readonly startedAt?: Date }\n    : never\n  : never\n\nexport interface FailProjectionRunEnqueueInput {\n  readonly id: string\n  readonly projectId: string\n  readonly finishedAt?: Date\n  readonly error: SixbFailure<ProjectionRunFailureCode>\n}\n\nexport interface ProjectionRunClaim {\n  readonly run: ProjectionRunRecord\n  readonly execution: ProjectionExecution\n}\n\nexport interface LockProjectionRunForMaterializationInput {\n  readonly id: string\n  readonly projectId: string\n  readonly executionToken: string\n  readonly identity: ProjectionMaterializationIdentity\n}\n\nexport interface UpdateProjectionRunInput extends LockProjectionRunForMaterializationInput {\n  readonly progress: Partial<ProjectionRunProgress>\n}\n\nexport type FinishProjectionRunInput = ProjectionRunTerminalDecision &\n  LockProjectionRunForMaterializationInput & {\n    readonly finishedAt?: Date\n    readonly progress?: Partial<ProjectionRunProgress>\n  }\n\nexport interface AdvanceProjectionTelemetryCheckpointInput\n  extends LockProjectionRunForMaterializationInput {\n  /** Must equal the run's current nextBatchOrdinal. */\n  readonly batchOrdinal: number\n  /** Physical dataset rows consumed by this batch, including skipped rows. */\n  readonly batchRowCount: number\n  /** Physical rows intentionally skipped inside this batch. */\n  readonly batchRowsSkipped: number\n  /** True when this batch consumed the final row of the immutable dataset version. */\n  readonly inputExhausted: boolean\n}\n\nexport interface RecordProjectionMissingTargetInput\n  extends LockProjectionRunForMaterializationInput {\n  readonly missingTarget: ProjectionMissingTarget\n}\n\nexport interface ListProjectionRunsInput {\n  readonly projectId: string\n  readonly projectionId?: string\n  readonly projectionKind?: ProjectionKind\n  readonly datasetId?: string\n  readonly datasetVersionId?: string\n  /**\n   * Viewable object type ids. A run is included only if every target type is present. Omit for an\n   * unrestricted internal execution; an empty set matches no runs.\n   */\n  readonly objectTypeIds?: readonly string[]\n  readonly statuses?: readonly ProjectionRunStatus[]\n  readonly startedAfter?: Date\n  readonly startedBefore?: Date\n  readonly limit?: number\n  readonly offset?: number\n  readonly order?: \"asc\" | \"desc\"\n}\n\nexport interface ListProjectionRunsResult {\n  readonly runs: readonly ProjectionRunRecord[]\n  readonly hasMore: boolean\n  readonly total: number\n}\n\nexport interface ListLatestProjectionRunsInput {\n  readonly projectId: string\n  readonly projectionIds: readonly string[]\n}\n\nexport interface ListLatestProjectionRunsResult {\n  readonly runs: readonly ProjectionRunRecord[]\n}\n\nexport interface ProjectionRunStorage {\n  queue(input: QueueProjectionRunInput): Promise<ProjectionRunRecord>\n  startOrReclaim(input: StartOrReclaimProjectionRunInput): Promise<ProjectionRunClaim>\n  failEnqueue(input: FailProjectionRunEnqueueInput): Promise<ProjectionRunRecord>\n  /** Transactionally fences the current execution before ontology materialization writes. */\n  lockForMaterialization(\n    input: LockProjectionRunForMaterializationInput\n  ): Promise<ProjectionRunRecord>\n  /** Updates physical source progress only. */\n  update(input: UpdateProjectionRunInput): Promise<ProjectionRunRecord>\n  /**\n   * Advances telemetry progress atomically with the corresponding ontology commit.\n   *\n   * Clears any recorded missing target: a batch that commits is a batch that was not waiting.\n   */\n  advanceTelemetryCheckpoint(\n    input: AdvanceProjectionTelemetryCheckpointInput\n  ): Promise<TelemetryProjectionRunRecord>\n  /** Records the object a telemetry batch is waiting for, so the wait has a durable start. */\n  recordMissingTarget(\n    input: RecordProjectionMissingTargetInput\n  ): Promise<TelemetryProjectionRunRecord>\n  /** Telemetry success also records the worker's EOF observation atomically. */\n  finish(input: FinishProjectionRunInput): Promise<ProjectionRunRecord>\n  getById(params: { projectId: string; id: string }): Promise<ProjectionRunRecord | null>\n  list(input: ListProjectionRunsInput): Promise<ListProjectionRunsResult>\n  listLatestByProjectionIds(\n    input: ListLatestProjectionRunsInput\n  ): Promise<ListLatestProjectionRunsResult>\n}\n\nexport type {\n  LinkProjectionTarget,\n  ObjectProjectionTarget,\n  PinnedDatasetVersion,\n  ProjectionExecution,\n  ProjectionKind,\n  ProjectionMaterializationIdentity,\n  ProjectionTarget,\n}\n"
-  ],
-  "mappings": ";;AAGO,IAAM,gCAA+B;AAAA,EAC1C;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;;;ACqBA,IAAM,mBAA8D;AAAA,EAClE,gBAAgB;AAAA,EAChB,mBAAmB;AAAA,EACnB,mBAAmB;AACrB;AAEO,IAAM,gCAA+B,OAAO,KACjD,gBACF;AAEO,SAAS,0BAAyB,GAA0B;AAAA,EACjE,OAAO,EAAE,gBAAgB,GAAG,mBAAmB,EAAE;AAAA;AA6E5C,SAAS,gCAA+B,CAC7C,KACA,SACS;AAAA,EACT,MAAM,SAA2B,IAAI;AAAA,EACrC,IAAI,wBAAwB,QAAQ;AAAA,IAClC,OAAO,QAAQ,OAAO,kBAAkB,KAAK,QAAQ,OAAO,kBAAkB;AAAA,EAChF;AAAA,EACA,OAAO,QAAQ,OAAO,YAAY;AAAA;",
-  "debugId": "20098923B6EB738064756E2164756E21",
-  "names": []
-}