@sixb/core 0.1.13 → 0.1.15

package/src/storage/ontology/sources.ts

@@ -128,7 +128,7 @@ interface BaseAbandonSourceMaterializationInput {
   readonly abandonedAt: string
 }
 
-/** Abandon the current execution's exact candidate after ingress or semantic failure. */
+/** Abandon the current execution's exact candidate, e.g. an adopted one whose delta base moved. */
 export interface AbandonSourceMaterializationCandidateInput
   extends BaseAbandonSourceMaterializationInput {
   readonly kind: "candidate"
@@ -136,20 +136,38 @@ export interface AbandonSourceMaterializationCandidateInput
 }
 
 /**
- * Reclaim a logical run after redelivery. The current execution may abandon the prior execution's
- * staging/ready candidate, but never one already owned by its own token.
+ * Release whatever candidate a run still holds, whichever execution staged it. Called in the same
+ * transaction as the run's terminal transition, so no candidate outlives its run.
  */
-export interface ReclaimSourceMaterializationInput extends BaseAbandonSourceMaterializationInput {
-  readonly kind: "reclaim"
+export interface AbandonRunSourceMaterializationInput
+  extends BaseAbandonSourceMaterializationInput {
+  readonly kind: "run"
 }
 
 export type AbandonSourceMaterializationInput =
   | AbandonSourceMaterializationCandidateInput
-  | ReclaimSourceMaterializationInput
+  | AbandonRunSourceMaterializationInput
+
+export interface AdoptSourceMaterializationInput {
+  readonly projectId: string
+  readonly source: ProjectionSourceRef
+  readonly execution: ProjectionExecution
+  readonly adoptedAt: string
+}
+
+export interface AdoptedSourceMaterialization {
+  readonly record: OntologySourceRecord
+  /**
+   * Where staging resumes. Every root before this ordinal is complete; the root at it may be
+   * partial and is staged again, which staging accepts for identical rows. Equals the root count
+   * once the candidate is ready.
+   */
+  readonly resumeStagingOrdinal: number
+}
 
 export interface CleanupTerminalSourceMaterializationsInput {
   readonly projectId: string
-  /** Exclusive cutoff for retired roots in terminal manifests, and for empty terminal manifests. */
+  /** Exclusive cutoff for retired roots in superseded manifests, and for empty ones. */
   readonly terminalBefore: string
   /** Maximum total assertion, root-reference, and manifest deletions performed by one call. */
   readonly limit: number
@@ -161,6 +179,12 @@ export interface CleanupTerminalSourceMaterializationsResult {
   readonly materializationsDeleted: number
 }
 
+export interface PurgeAbandonedSourceMaterializationsInput {
+  readonly projectId: string
+  /** Maximum total assertion, root-reference, and manifest deletions performed by one call. */
+  readonly limit: number
+}
+
 export interface SummarizeTerminalSourceMaterializationsInput {
   readonly projectId: string
 }
@@ -195,11 +219,21 @@ export interface OntologySourceStorage {
   stageRows(input: StageSourceRowsInput): Promise<StageSourceRowsResult>
   markReady(input: MarkSourceMaterializationReadyInput): Promise<OntologySourceRecord>
   getActive(input: GetActiveOntologySourceInput): Promise<OntologySourceRecord | null>
+  /** Hands a redelivered run's candidate to its current execution; null when it has none. */
+  adopt(input: AdoptSourceMaterializationInput): Promise<AdoptedSourceMaterialization | null>
   abandon(input: AbandonSourceMaterializationCandidateInput): Promise<OntologySourceRecord>
-  abandon(input: ReclaimSourceMaterializationInput): Promise<OntologySourceRecord | null>
+  abandon(input: AbandonRunSourceMaterializationInput): Promise<OntologySourceRecord | null>
+  /** Retired roots of superseded manifests, after their retention. */
   cleanupTerminal(
     input: CleanupTerminalSourceMaterializationsInput
   ): Promise<CleanupTerminalSourceMaterializationsResult>
+  /**
+   * Abandoned candidates, whole and oldest first. Nothing reads an abandoned candidate, so it has
+   * no retention; deleting one manifest at a time keeps each delete on the source-version index.
+   */
+  purgeAbandoned(
+    input: PurgeAbandonedSourceMaterializationsInput
+  ): Promise<CleanupTerminalSourceMaterializationsResult>
   summarizeTerminal(
     input: SummarizeTerminalSourceMaterializationsInput
   ): Promise<TerminalSourceMaterializationSummary>

package/src/storage/projection-runs/in-memory.ts

@@ -26,8 +26,10 @@ import {
   finishProjectionRunRecord,
   immutableDatasetVersionConflict,
   mergeProjectionRunProgress,
+  parseProjectionAttemptFailure,
   planProjectionRunReclaim,
   projectionRunNotFound,
+  projectionRunSupersedes,
   publicProjectionRunRecord,
   requireTelemetryProjectionRun,
   type StoredProjectionRunRecord,
@@ -36,6 +38,7 @@ import {
 import {
   type AdvanceProjectionTelemetryCheckpointInput,
   type FailProjectionRunEnqueueInput,
+  type FindSupersedingProjectionRunInput,
   type FinishProjectionRunInput,
   type ListLatestProjectionRunsInput,
   type ListLatestProjectionRunsResult,
@@ -47,6 +50,7 @@ import {
   type ProjectionRunStorage,
   projectionRunObjectTypesVisible,
   type QueueProjectionRunInput,
+  type RecordProjectionAttemptFailureInput,
   type RecordProjectionMissingTargetInput,
   type StartOrReclaimProjectionRunInput,
   type TelemetryProjectionRunRecord,
@@ -60,6 +64,10 @@ function projectionRunKey(projectId: string, id: string): string {
   return JSON.stringify([projectId, id])
 }
 
+function compareText(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0
+}
+
 function compareRuns(a: ProjectionRunRecord, b: ProjectionRunRecord, order: "asc" | "desc") {
   return compareStartedAt(a, b, order)
 }
@@ -152,7 +160,6 @@ export class InMemoryProjectionRunStorage implements ProjectionRunStorage {
         executionToken,
         startedAt: existing.startedAt ?? new Date(input.startedAt ?? new Date()),
         finishedAt: undefined,
-        error: undefined,
       }
 
       this.rows.set(key, structuredClone(record))
@@ -246,6 +253,17 @@ export class InMemoryProjectionRunStorage implements ProjectionRunStorage {
     })
   }
 
+  async recordAttemptFailure(
+    input: RecordProjectionAttemptFailureInput
+  ): Promise<ProjectionRunRecord> {
+    return this.runRootOperation(() => {
+      const existing = this.requireExecution(input)
+      const next = { ...existing, error: parseProjectionAttemptFailure(existing, input.error) }
+      this.rows.set(projectionRunKey(input.projectId, input.id), structuredClone(next))
+      return publicProjectionRunRecord(next)
+    })
+  }
+
   async finish(input: FinishProjectionRunInput): Promise<ProjectionRunRecord> {
     return this.runRootOperation(() => {
       const existing = this.requireExecution(input)
@@ -311,12 +329,33 @@ export class InMemoryProjectionRunStorage implements ProjectionRunStorage {
     })
   }
 
+  async findSupersedingRun(
+    input: FindSupersedingProjectionRunInput
+  ): Promise<ProjectionRunRecord | null> {
+    return this.runRootOperation(() => {
+      const run = this.rows.get(projectionRunKey(input.projectId, input.id))
+      if (!run) throw projectionRunNotFound(input.projectId, input.id)
+      const newest = [...this.rows.values()]
+        .filter((candidate) => projectionRunSupersedes(candidate, run))
+        .sort(
+          (left, right) =>
+            compareText(
+              right.identity.datasetVersion.createdAt,
+              left.identity.datasetVersion.createdAt
+            ) || compareText(right.id, left.id)
+        )[0]
+      return newest ? publicProjectionRunRecord(newest) : null
+    })
+  }
+
   async listLatestByProjectionIds(
     input: ListLatestProjectionRunsInput
   ): Promise<ListLatestProjectionRunsResult> {
     return this.runRootOperation(() => {
       const runs = latestStartedAtByOwnerId(
-        [...this.rows.values()].filter((record) => record.projectId === input.projectId),
+        [...this.rows.values()].filter(
+          (record) => record.projectId === input.projectId && record.status !== "superseded"
+        ),
         input.projectionIds,
         (record) => record.identity.projectionId
       )

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

@@ -3,6 +3,7 @@ export { InMemoryProjectionRunStorage } from "./in-memory"
 export type {
   AdvanceProjectionTelemetryCheckpointInput,
   FailProjectionRunEnqueueInput,
+  FindSupersedingProjectionRunInput,
   FinishProjectionRunInput,
   LinkProjectionRunRecord,
   LinkProjectionTarget,
@@ -27,6 +28,7 @@ export type {
   ProjectionTarget,
   ProjectionTelemetryCheckpoint,
   QueueProjectionRunInput,
+  RecordProjectionAttemptFailureInput,
   RecordProjectionMissingTargetInput,
   StartOrReclaimProjectionRunInput,
   TelemetryProjectionRunRecord,

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>