@sixb/core 0.1.0 → 0.1.2

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

@@ -1,11 +1,19 @@
+import { parseSixbFailure } from "../../errors/internal"
+import type { SixbFailure } from "../../errors/types"
 import type {
   ProjectionMaterializationIdentity,
   ProjectionRunTerminalDecision,
 } from "../../materialization/model"
-import type { ProjectionKind, ProjectionTarget } from "../../projections/types"
+import type {
+  ProjectionKind,
+  ProjectionRunFailureCode,
+  ProjectionTarget,
+} from "../../projections/types"
+import { PROJECTION_RUN_FAILURE_CODES } from "../../projections/types"
 import { ProjectionRunError } from "./errors"
 import type {
   AdvanceProjectionTelemetryCheckpointInput,
+  FailProjectionRunEnqueueInput,
   FinishProjectionRunInput,
   ProjectionMissingTarget,
   ProjectionRunClaim,
@@ -13,6 +21,7 @@ import type {
   ProjectionRunRecord,
   ProjectionRunStatus,
   ProjectionTelemetryCheckpoint,
+  QueueProjectionRunInput,
   StartOrReclaimProjectionRunInput,
   TelemetryProjectionRunRecord,
 } from "./types"
@@ -25,6 +34,7 @@ export type StoredProjectionRunRecord = ProjectionRunRecord & {
 export interface PersistedProjectionRunRecord {
   readonly id: string
   readonly projectId: string
+  readonly executionId: string
   readonly projectionId: string
   readonly projectionKind: ProjectionKind
   readonly protocol?: "replacement" | "telemetry"
@@ -38,7 +48,8 @@ export interface PersistedProjectionRunRecord {
   readonly sourceObjectTypeId?: string
   readonly targetObjectTypeId?: string
   readonly status: ProjectionRunStatus
-  readonly startedAt: Date
+  readonly queuedAt: Date
+  readonly startedAt?: Date
   readonly finishedAt?: Date
   readonly attempt: number
   readonly executionToken?: string
@@ -51,7 +62,7 @@ export interface PersistedProjectionRunRecord {
   readonly missingTargetBatchOrdinal?: number
   readonly missingTargetFirstSeenAt?: Date
   readonly progress: ProjectionRunProgress
-  readonly errorMessage?: string
+  readonly error?: unknown
 }
 
 export interface ProjectionTelemetryAdvance {
@@ -60,11 +71,11 @@ export interface ProjectionTelemetryAdvance {
 }
 
 export interface ProjectionRunFinishPlan {
-  readonly status: Exclude<ProjectionRunStatus, "running">
+  readonly status: Exclude<ProjectionRunStatus, "queued" | "running">
   readonly finishedAt: Date
   readonly progress: ProjectionRunProgress
   readonly inputExhausted?: true
-  readonly errorMessage?: string
+  readonly error?: SixbFailure<ProjectionRunFailureCode>
 }
 
 // ── Scalar and identity validation ──────────────────────────
@@ -145,11 +156,25 @@ export function assertProjectionRunTargetMatches(
 export function assertProjectionRunStartInput(input: StartOrReclaimProjectionRunInput): void {
   assertProjectionRunNonEmpty(input.id, "id")
   assertProjectionRunNonEmpty(input.projectId, "projectId")
+  assertProjectionRunIdentityAndTarget(input)
+  if (input.startedAt) assertProjectionRunDate(input.startedAt, "startedAt")
+}
+
+export function assertProjectionRunQueueInput(input: QueueProjectionRunInput): void {
+  assertProjectionRunNonEmpty(input.id, "id")
+  assertProjectionRunNonEmpty(input.projectId, "projectId")
+  assertProjectionRunNonEmpty(input.executionId, "executionId")
+  assertProjectionRunIdentityAndTarget(input)
+  if (input.queuedAt) assertProjectionRunDate(input.queuedAt, "queuedAt")
+}
+
+function assertProjectionRunIdentityAndTarget(
+  input: QueueProjectionRunInput | StartOrReclaimProjectionRunInput
+): void {
   assertProjectionRunIdentity(input.identity)
   assertProjectionTarget(input.identity.projectionKind, input.target)
-  if (input.startedAt) assertProjectionRunDate(input.startedAt, "startedAt")
   if (input.identity.projectionKind === "telemetry") {
-    const telemetry = input as ProjectionRunStart<"telemetry">
+    const telemetry = input as ProjectionRunIdentityInput<"telemetry">
     assertPositiveCounter(telemetry.fixedBatchSize, "fixedBatchSize")
   } else if (input.fixedBatchSize !== undefined) {
     throw new ProjectionRunError(
@@ -162,7 +187,11 @@ export function planProjectionRunReclaim(
   record: StoredProjectionRunRecord,
   input: StartOrReclaimProjectionRunInput
 ): { readonly attempt: number } {
-  assertProjectionRunRunning(record)
+  if (record.status !== "queued" && record.status !== "running") {
+    throw new ProjectionRunError(
+      `[Sixb] Projection run '${record.id}' cannot start from status '${record.status}'.`
+    )
+  }
   assertProjectionRunIdentityMatches(record, input.identity)
   assertProjectionRunTargetMatches(record, input.target)
   if (record.telemetryCheckpoint?.fixedBatchSize !== input.fixedBatchSize) {
@@ -170,35 +199,36 @@ export function planProjectionRunReclaim(
       `[Sixb] Projection run '${input.id}' fixed batch size does not match.`
     )
   }
-  return { attempt: nextProjectionRunAttempt(record.attempt) }
+  return { attempt: record.status === "queued" ? 1 : nextProjectionRunAttempt(record.attempt) }
 }
 
 // ── Lifecycle transitions ───────────────────────────────────
 
 export function createProjectionRunRecord(
-  input: StartOrReclaimProjectionRunInput,
+  input: QueueProjectionRunInput,
   now: Date = new Date()
 ): ProjectionRunRecord {
-  assertProjectionRunStartInput(input)
+  assertProjectionRunQueueInput(input)
   const base = {
     id: input.id,
     projectId: input.projectId,
-    status: "running" as const,
-    attempt: 1,
+    executionId: input.executionId,
+    status: "queued" as const,
+    attempt: 0,
     progress: zeroProjectionRunProgress(),
-    startedAt: new Date(input.startedAt ?? now),
+    queuedAt: new Date(input.queuedAt ?? now),
   }
   switch (input.identity.projectionKind) {
     case "object": {
-      const object = input as ProjectionRunStart<"object">
+      const object = input as ProjectionRunAdmission<"object">
       return { ...base, identity: object.identity, target: object.target }
     }
     case "link": {
-      const link = input as ProjectionRunStart<"link">
+      const link = input as ProjectionRunAdmission<"link">
       return { ...base, identity: link.identity, target: link.target }
     }
     case "telemetry": {
-      const telemetry = input as ProjectionRunStart<"telemetry">
+      const telemetry = input as ProjectionRunAdmission<"telemetry">
       return {
         ...base,
         identity: telemetry.identity,
@@ -218,12 +248,15 @@ export function assertProjectionRunRunning(
   record: Pick<ProjectionRunRecord, "id" | "projectId" | "status">
 ): void {
   if (record.status === "running") return
+  if (record.status !== "queued") {
+    throw new ProjectionRunError(`[Sixb] Projection run '${record.id}' is already terminal.`)
+  }
   throw new ProjectionRunError(
-    `[Sixb] Projection run '${record.id}' for project '${record.projectId}' is already terminal.`
+    `[Sixb] Projection run '${record.id}' for project '${record.projectId}' is not running.`
   )
 }
 
-export function assertProjectionRunExecution(
+export function assertProjectionRunAttempt(
   record: StoredProjectionRunRecord,
   input: {
     readonly id: string
@@ -353,9 +386,9 @@ export function planProjectionRunFinish(
     ...(input.status === "succeeded" && input.protocol === "telemetry"
       ? { inputExhausted: true as const }
       : {}),
-    ...(input.status === "succeeded" || input.errorMessage === undefined
+    ...(input.status === "succeeded" || input.error === undefined
       ? {}
-      : { errorMessage: input.errorMessage }),
+      : { error: parseSixbFailure(input.error, PROJECTION_RUN_FAILURE_CODES) }),
   }
 }
 
@@ -370,7 +403,7 @@ export function finishProjectionRunRecord(
     status: plan.status,
     finishedAt: plan.finishedAt,
     progress: plan.progress,
-    errorMessage: plan.errorMessage,
+    error: plan.error,
   }
   if (plan.inputExhausted) {
     const telemetry = requireTelemetryProjectionRun(record)
@@ -383,36 +416,76 @@ export function finishProjectionRunRecord(
   return { ...record, ...terminal }
 }
 
+export function failProjectionRunEnqueue(
+  record: StoredProjectionRunRecord,
+  input: FailProjectionRunEnqueueInput,
+  now: Date = new Date()
+): StoredProjectionRunRecord {
+  if (record.status !== "queued") {
+    throw new ProjectionRunError(
+      `[Sixb] Projection run '${record.id}' cannot fail enqueue from status '${record.status}'.`
+    )
+  }
+  const error = parseSixbFailure(input.error, PROJECTION_RUN_FAILURE_CODES)
+  if (error.code !== "queue.enqueue_failed") {
+    throw new ProjectionRunError(
+      `[Sixb] Projection run '${record.id}' enqueue failure must use code 'queue.enqueue_failed'.`
+    )
+  }
+  const finishedAt = new Date(input.finishedAt ?? now)
+  assertProjectionRunDate(finishedAt, "finishedAt")
+  return {
+    ...record,
+    status: "failed",
+    finishedAt,
+    error,
+  }
+}
+
+export function canRequeueProjectionRunAfterEnqueueFailure(
+  record: ProjectionRunRecord,
+  input: QueueProjectionRunInput
+): boolean {
+  return (
+    record.status === "failed" &&
+    record.error?.code === "queue.enqueue_failed" &&
+    record.error.retryable &&
+    record.executionId === input.executionId &&
+    projectionRunIdentitiesEqual(record.identity, input.identity) &&
+    projectionTargetsEqual(record.target, input.target) &&
+    record.telemetryCheckpoint?.fixedBatchSize === input.fixedBatchSize
+  )
+}
+
 // ── Persistence mapping ─────────────────────────────────────
 
 export function restoreProjectionRun(row: PersistedProjectionRunRecord): StoredProjectionRunRecord {
   assertProjectionRunNonEmpty(row.id, "id")
   assertProjectionRunNonEmpty(row.projectId, "projectId")
+  assertProjectionRunNonEmpty(row.executionId, "executionId")
   assertProjectionRunCounter(row.attempt, "attempt")
-  if (row.attempt < 1) {
-    throw new ProjectionRunError(`[Sixb] Projection run '${row.id}' attempt must be positive.`)
-  }
   assertProjectionRunProgress(row.progress)
-  assertValidDate(row.startedAt, "startedAt")
+  assertValidDate(row.queuedAt, "queuedAt")
+  if (row.startedAt) assertValidDate(row.startedAt, "startedAt")
   if (row.finishedAt) assertValidDate(row.finishedAt, "finishedAt")
-  if ((row.status === "running") !== (row.finishedAt === undefined)) {
-    throw incompleteProjectionRun(row.id)
-  }
-  if ((row.status === "running") !== (row.executionToken !== undefined)) {
-    throw incompleteProjectionRun(row.id)
-  }
+  assertPersistedLifecycle(row)
 
   const identity = restoreIdentity(row)
   const base = {
     id: row.id,
     projectId: row.projectId,
+    executionId: row.executionId,
     identity,
     status: row.status,
-    startedAt: new Date(row.startedAt),
+    queuedAt: new Date(row.queuedAt),
+    startedAt: row.startedAt ? new Date(row.startedAt) : undefined,
     finishedAt: row.finishedAt ? new Date(row.finishedAt) : undefined,
     attempt: row.attempt,
     progress: { ...row.progress },
-    errorMessage: row.errorMessage,
+    error:
+      row.error === undefined
+        ? undefined
+        : parseSixbFailure(row.error, PROJECTION_RUN_FAILURE_CODES),
     executionToken: row.executionToken,
   }
 
@@ -522,6 +595,57 @@ function assertValidDate(value: Date, fieldName: string): void {
   }
 }
 
+function assertPersistedLifecycle(row: PersistedProjectionRunRecord): void {
+  const hasError = row.error !== undefined
+
+  if (row.status === "queued") {
+    if (
+      row.attempt !== 0 ||
+      row.startedAt !== undefined ||
+      row.finishedAt !== undefined ||
+      row.executionToken !== undefined ||
+      hasError
+    ) {
+      throw incompleteProjectionRun(row.id)
+    }
+    return
+  }
+
+  if (row.status === "running") {
+    if (
+      row.attempt < 1 ||
+      row.startedAt === undefined ||
+      row.finishedAt !== undefined ||
+      row.executionToken === undefined ||
+      hasError
+    ) {
+      throw incompleteProjectionRun(row.id)
+    }
+    return
+  }
+
+  if (row.finishedAt === undefined || row.executionToken !== undefined) {
+    throw incompleteProjectionRun(row.id)
+  }
+  if (row.error !== undefined) {
+    const failure = parseSixbFailure(row.error, PROJECTION_RUN_FAILURE_CODES)
+    if (failure.code === "queue.enqueue_failed") {
+      if (
+        !failure.retryable ||
+        row.status !== "failed" ||
+        row.attempt !== 0 ||
+        row.startedAt !== undefined
+      ) {
+        throw incompleteProjectionRun(row.id)
+      }
+      return
+    }
+  }
+  if (row.attempt < 1 || row.startedAt === undefined || (row.status === "succeeded" && hasError)) {
+    throw incompleteProjectionRun(row.id)
+  }
+}
+
 function assertProjectionRunDate(value: Date, fieldName: string): void {
   if (!Number.isFinite(value.getTime())) {
     throw new ProjectionRunError(`[Sixb] Projection run ${fieldName} is invalid.`)
@@ -781,8 +905,13 @@ export function requireTelemetryProjectionRun<TRecord extends ProjectionRunRecor
   )
 }
 
-type ProjectionRunStart<TKind extends ProjectionKind> = Extract<
-  StartOrReclaimProjectionRunInput,
+type ProjectionRunIdentityInput<TKind extends ProjectionKind> = Extract<
+  QueueProjectionRunInput | StartOrReclaimProjectionRunInput,
+  { readonly identity: { readonly projectionKind: TKind } }
+>
+
+type ProjectionRunAdmission<TKind extends ProjectionKind> = Extract<
+  QueueProjectionRunInput,
   { readonly identity: { readonly projectionKind: TKind } }
 >
 

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

@@ -0,0 +1,34 @@
+import type { ExecutionStorage } from "../executions"
+import { findPrimitiveRunExecution } from "../executions/run-link"
+import { ProjectionRunError } from "./errors"
+
+export * from "./lifecycle"
+
+/** Validate the semantic link between a durable Projection run and its immutable execution. */
+export async function assertProjectionRunDurableExecution(input: {
+  readonly executions: ExecutionStorage
+  readonly projectId: string
+  readonly executionId: string
+  readonly runId: string
+  readonly projectionId: string
+  readonly datasetId: string
+  readonly datasetVersionId: string
+}): Promise<void> {
+  const execution = await findPrimitiveRunExecution({
+    executions: input.executions,
+    projectId: input.projectId,
+    executionId: input.executionId,
+    primitive: { kind: "projection", id: input.projectionId, runId: input.runId },
+    sourceTypes: ["datasetVersion"],
+  })
+  if (
+    !execution ||
+    execution.source.type !== "datasetVersion" ||
+    execution.source.datasetId !== input.datasetId ||
+    execution.source.versionId !== input.datasetVersionId
+  ) {
+    throw new ProjectionRunError(
+      `[Sixb] Execution '${input.executionId}' does not authorize Projection run '${input.runId}'.`
+    )
+  }
+}

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

@@ -1,3 +1,4 @@
+import type { SixbFailure } from "../../errors/types"
 import type {
   PinnedDatasetVersion,
   ProjectionExecution,
@@ -8,10 +9,14 @@ import type {
   LinkProjectionTarget,
   ObjectProjectionTarget,
   ProjectionKind,
+  ProjectionRunFailureCode,
   ProjectionTarget,
 } from "../../projections/types"
 
-export type ProjectionRunStatus = "running" | "succeeded" | "failed" | "cancelled"
+export type { ProjectionRunFailureCode } from "../../projections/types"
+export { PROJECTION_RUN_FAILURE_CODES } from "../../projections/types"
+
+export type ProjectionRunStatus = "queued" | "running" | "succeeded" | "failed" | "cancelled"
 
 export interface ProjectionRunProgress {
   /** Physical immutable-version rows consumed, before normalization or semantic materialization. */
@@ -63,12 +68,14 @@ export interface ProjectionMissingTarget {
 interface ProjectionRunRecordBase {
   readonly id: string
   readonly projectId: string
+  readonly executionId: string
   readonly status: ProjectionRunStatus
   readonly attempt: number
   readonly progress: ProjectionRunProgress
-  readonly startedAt: Date
+  readonly queuedAt: Date
+  readonly startedAt?: Date
   readonly finishedAt?: Date
-  readonly errorMessage?: string
+  readonly error?: SixbFailure<ProjectionRunFailureCode>
 }
 
 type ProjectionIdentity<TKind extends ProjectionKind> = Extract<
@@ -118,29 +125,43 @@ export function projectionRunObjectTypesVisible(
   return canView(target.objectTypeId)
 }
 
-interface StartOrReclaimProjectionRunBase {
+interface ProjectionRunAdmissionBase {
   readonly id: string
   readonly projectId: string
-  readonly startedAt?: Date
+  readonly executionId: string
+  readonly queuedAt?: Date
 }
 
-export type StartOrReclaimProjectionRunInput =
-  | (StartOrReclaimProjectionRunBase & {
+export type QueueProjectionRunInput =
+  | (ProjectionRunAdmissionBase & {
       readonly identity: ProjectionIdentity<"object">
       readonly target: ObjectProjectionRunRecord["target"]
       readonly fixedBatchSize?: never
     })
-  | (StartOrReclaimProjectionRunBase & {
+  | (ProjectionRunAdmissionBase & {
       readonly identity: ProjectionIdentity<"link">
       readonly target: LinkProjectionRunRecord["target"]
       readonly fixedBatchSize?: never
     })
-  | (StartOrReclaimProjectionRunBase & {
+  | (ProjectionRunAdmissionBase & {
       readonly identity: ProjectionIdentity<"telemetry">
       readonly target: TelemetryProjectionRunRecord["target"]
       readonly fixedBatchSize: number
     })
 
+export type StartOrReclaimProjectionRunInput = QueueProjectionRunInput extends infer TInput
+  ? TInput extends QueueProjectionRunInput
+    ? Omit<TInput, "executionId" | "queuedAt"> & { readonly startedAt?: Date }
+    : never
+  : never
+
+export interface FailProjectionRunEnqueueInput {
+  readonly id: string
+  readonly projectId: string
+  readonly finishedAt?: Date
+  readonly error: SixbFailure<ProjectionRunFailureCode>
+}
+
 export interface ProjectionRunClaim {
   readonly run: ProjectionRunRecord
   readonly execution: ProjectionExecution
@@ -187,8 +208,8 @@ export interface ListProjectionRunsInput {
   readonly datasetId?: string
   readonly datasetVersionId?: string
   /**
-   * Viewable object type ids. A run is included only if every target type is present. Omit for a
-   * privileged caller; an empty set matches no runs.
+   * Viewable object type ids. A run is included only if every target type is present. Omit for an
+   * unrestricted internal execution; an empty set matches no runs.
    */
   readonly objectTypeIds?: readonly string[]
   readonly statuses?: readonly ProjectionRunStatus[]
@@ -215,7 +236,9 @@ export interface ListLatestProjectionRunsResult {
 }
 
 export interface ProjectionRunStorage {
+  queue(input: QueueProjectionRunInput): Promise<ProjectionRunRecord>
   startOrReclaim(input: StartOrReclaimProjectionRunInput): Promise<ProjectionRunClaim>
+  failEnqueue(input: FailProjectionRunEnqueueInput): Promise<ProjectionRunRecord>
   /** Transactionally fences the current execution before ontology materialization writes. */
   lockForMaterialization(
     input: LockProjectionRunForMaterializationInput

package/src/storage/run-listing.ts

@@ -6,13 +6,8 @@ export { paginate } from "./pagination"
 export interface StartedAtRunRecord<TStatus extends string = string> {
   readonly id: string
   readonly status: TStatus
-  readonly startedAt: Date
-}
-
-export interface RunListDateFilters<TStatus extends string = string> {
-  readonly statuses?: readonly TStatus[]
-  readonly startedAfter?: Date
-  readonly startedBefore?: Date
+  readonly startedAt?: Date
+  readonly queuedAt?: Date
 }
 
 export function storageKey(projectId: string, id: string): string {
@@ -45,11 +40,13 @@ export function matchesRunListDateFilters<TStatus extends string>(
     return false
   }
 
-  if (filters.startedAfter && record.startedAt < filters.startedAfter) {
+  const startedAt = effectiveStartedAt(record)
+
+  if (filters.startedAfter && startedAt < filters.startedAfter) {
     return false
   }
 
-  if (filters.startedBefore && record.startedAt > filters.startedBefore) {
+  if (filters.startedBefore && startedAt > filters.startedBefore) {
     return false
   }
 
@@ -57,11 +54,11 @@ export function matchesRunListDateFilters<TStatus extends string>(
 }
 
 export function compareStartedAt(
-  left: { readonly id: string; readonly startedAt: Date },
-  right: { readonly id: string; readonly startedAt: Date },
+  left: { readonly id: string; readonly startedAt?: Date; readonly queuedAt?: Date },
+  right: { readonly id: string; readonly startedAt?: Date; readonly queuedAt?: Date },
   order: RunListOrder
 ): number {
-  const delta = left.startedAt.getTime() - right.startedAt.getTime()
+  const delta = effectiveStartedAt(left).getTime() - effectiveStartedAt(right).getTime()
   if (delta !== 0) {
     return order === "asc" ? delta : -delta
   }
@@ -74,7 +71,7 @@ export function compareStartedAt(
 }
 
 export function latestStartedAtByOwnerId<
-  TRecord extends { readonly id: string; readonly startedAt: Date },
+  TRecord extends { readonly id: string; readonly startedAt?: Date; readonly queuedAt?: Date },
 >(
   records: readonly TRecord[],
   ownerIds: readonly string[],
@@ -105,3 +102,15 @@ export function latestStartedAtByOwnerId<
     return record ? [record] : []
   })
 }
+
+function effectiveStartedAt(record: {
+  readonly id: string
+  readonly startedAt?: Date
+  readonly queuedAt?: Date
+}): Date {
+  const value = record.startedAt ?? record.queuedAt
+  if (!value) {
+    throw new Error(`[Sixb] Run '${record.id}' has neither startedAt nor queuedAt.`)
+  }
+  return value
+}

package/src/storage/sync-runs/idempotency.ts

@@ -0,0 +1,18 @@
+import type { QueueSyncRunInput, SyncRunRecord } from "./types"
+
+export function canRequeueSyncRunAfterEnqueueFailure(
+  existing: SyncRunRecord,
+  input: QueueSyncRunInput
+): boolean {
+  return (
+    existing.status === "failed" &&
+    existing.error?.code === "queue.enqueue_failed" &&
+    existing.error.retryable &&
+    existing.executionId === input.executionId &&
+    existing.syncId === input.syncId &&
+    existing.datasetId === input.datasetId &&
+    existing.mode === input.mode &&
+    existing.expectedLatestVersionId === input.expectedLatestVersionId &&
+    existing.commitMessage === input.commitMessage
+  )
+}