@sixb/core 0.1.17 → 0.1.19

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

@@ -1,30 +1,15 @@
 import type { ExecutionStorage } from "../executions"
 import { ActionRunError } from "./errors"
-import { parseActionRunFailure } from "./failure"
-import {
-  actionRunPhaseRecordsEqual,
-  actionSubjectsEqual,
-  canRequeueActionRunAfterEnqueueFailure,
-  isTerminalActionRun,
-} from "./idempotency"
+import { actionSubjectsEqual } from "./idempotency"
 import { assertActionRunExecution } from "./provider"
+import { normalizeRecordActionRunInput, resolveActionRunEffects } from "./record"
 import type {
-  ActionRunEffectsRecord,
-  ActionRunFailure,
-  ActionRunParams,
-  ActionRunPhase,
   ActionRunRecord,
   ActionRunStorage,
-  ActionRunWritebackRecord,
-  EnterActionRunPhaseInput,
-  FinishActionRunInput,
   ListActionRunsInput,
   ListActionRunsResult,
-  LockActionMaterializationRunInput,
-  QueueActionRunInput,
   RecordActionEffectsInput,
-  RecordActionWritebackInput,
-  StartActionRunInput,
+  RecordActionRunInput,
 } from "./types"
 
 type RunRootOperation = <T>(run: () => Promise<T> | T) => Promise<T>
@@ -35,74 +20,12 @@ function actionRunKey(projectId: string, id: string): string {
   return JSON.stringify([projectId, id])
 }
 
-function assertNonBlank(value: string, fieldName: string): void {
-  if (typeof value !== "string" || value.trim().length === 0) {
-    throw new ActionRunError(`[Sixb] Action materialization ${fieldName} must be nonblank.`)
-  }
-}
-
 function cloneActionRunRecord(record: ActionRunRecord): ActionRunRecord {
   return structuredClone(record)
 }
 
-function normalizeParams(params: ActionRunParams): ActionRunParams {
-  return structuredClone(params)
-}
-
-function normalizeSubject(subject: QueueActionRunInput["subject"]): QueueActionRunInput["subject"] {
-  return structuredClone(subject)
-}
-
-function normalizeError<TPhase extends ActionRunPhase>(
-  error: ActionRunFailure<TPhase>,
-  expectedPhase?: TPhase
-): ActionRunFailure<TPhase> {
-  return expectedPhase === undefined
-    ? (parseActionRunFailure(error) as ActionRunFailure<TPhase>)
-    : parseActionRunFailure(error, expectedPhase)
-}
-
-function normalizeWriteback(
-  input: RecordActionWritebackInput,
-  completedAt: Date
-): ActionRunWritebackRecord {
-  if (input.status === "succeeded") {
-    return {
-      status: "succeeded",
-      completedAt,
-      result: structuredClone(input.result),
-    }
-  }
-
-  return {
-    status: "failed",
-    completedAt,
-    error: normalizeError(input.error, "writeback"),
-  }
-}
-
-function normalizeEffects(
-  input: RecordActionEffectsInput,
-  completedAt: Date
-): ActionRunEffectsRecord {
-  if (input.status === "succeeded") {
-    return {
-      status: "succeeded",
-      completedAt,
-    }
-  }
-
-  return {
-    status: "failed",
-    completedAt,
-    error: normalizeError(input.error, "effects"),
-  }
-}
-
 function compareRuns(a: ActionRunRecord, b: ActionRunRecord, order: "asc" | "desc"): number {
-  const leftAt = a.startedAt ?? a.queuedAt
-  const rightAt = b.startedAt ?? b.queuedAt
-  const delta = leftAt.getTime() - rightAt.getTime()
+  const delta = a.startedAt.getTime() - b.startedAt.getTime()
   if (delta !== 0) {
     return order === "asc" ? delta : -delta
   }
@@ -136,235 +59,49 @@ export class InMemoryActionRunStorage implements ActionRunStorage {
     }
   }
 
-  async lockForMaterialization(input: LockActionMaterializationRunInput): Promise<ActionRunRecord> {
-    return this.runRootOperation(() => cloneActionRunRecord(this.requireMaterializationRun(input)))
-  }
-
-  async queue(input: QueueActionRunInput): Promise<ActionRunRecord> {
+  async record(input: RecordActionRunInput): Promise<ActionRunRecord> {
     return this.runRootOperation(async () => {
-      const key = actionRunKey(input.projectId, input.id)
-      const existing = this.rows.get(key)
-      if (existing && !canRequeueActionRunAfterEnqueueFailure(existing, input)) {
+      const record = normalizeRecordActionRunInput(input)
+      const key = actionRunKey(record.projectId, record.id)
+      if (this.rows.has(key)) {
         throw new ActionRunError(
-          `[Sixb] Action run '${input.id}' already exists for project '${input.projectId}'.`
+          `[Sixb] Action run '${record.id}' is already recorded for project '${record.projectId}'.`
         )
       }
       if (
         [...this.rows.values()].some(
-          (run) =>
-            run.projectId === input.projectId &&
-            run.id !== input.id &&
-            run.executionId === input.executionId
+          (run) => run.projectId === record.projectId && run.executionId === record.executionId
         )
       ) {
         throw new ActionRunError(
-          `[Sixb] Execution '${input.executionId}' already belongs to another Action run.`
+          `[Sixb] Execution '${record.executionId}' already belongs to another Action run.`
         )
       }
       await assertActionRunExecution({
         executions: this.executions,
-        projectId: input.projectId,
-        executionId: input.executionId,
-        runId: input.id,
-        actionId: input.actionId,
+        projectId: record.projectId,
+        executionId: record.executionId,
+        runId: record.id,
+        actionId: record.actionId,
       })
 
-      const record: ActionRunRecord = {
-        id: input.id,
-        projectId: input.projectId,
-        executionId: input.executionId,
-        actionId: input.actionId,
-        subject: normalizeSubject(input.subject),
-        status: "queued",
-        phase: "request",
-        queuedAt: new Date(input.queuedAt ?? new Date()),
-        params: normalizeParams(input.params),
-        idempotencyKey: input.idempotencyKey,
-      }
-
-      if (existing) {
-        const next: ActionRunRecord = {
-          ...existing,
-          status: "queued",
-          phase: "request",
-          queuedAt: record.queuedAt,
-          startedAt: undefined,
-          finishedAt: undefined,
-          error: undefined,
-          writeback: undefined,
-          effects: undefined,
-        }
-        this.rows.set(key, structuredClone(next))
-        return cloneActionRunRecord(next)
-      }
-
       this.rows.set(key, structuredClone(record))
       return cloneActionRunRecord(record)
     })
   }
 
-  async start(input: StartActionRunInput): Promise<ActionRunRecord> {
-    return this.runRootOperation(() => {
-      const key = actionRunKey(input.projectId, input.id)
-      const existing = this.rows.get(key)
-
-      if (!existing) {
-        throw new ActionRunError(
-          `[Sixb] Action run '${input.id}' not found for project '${input.projectId}'.`
-        )
-      }
-
-      if (existing.status !== "queued") {
-        throw new ActionRunError(
-          `[Sixb] Action run '${input.id}' cannot start from status '${existing.status}'.`
-        )
-      }
-
-      const next: ActionRunRecord = {
-        ...existing,
-        status: "running",
-        phase: input.phase ?? "validation",
-        startedAt: new Date(input.startedAt ?? new Date()),
-        error: undefined,
-      }
-
-      this.rows.set(key, structuredClone(next))
-      return cloneActionRunRecord(next)
-    })
-  }
-
-  async enterPhase(input: EnterActionRunPhaseInput): Promise<ActionRunRecord> {
-    return this.runRootOperation(() => {
-      const key = actionRunKey(input.projectId, input.id)
-      const existing = this.requireRunningRun(key, input.projectId, input.id, "enter phase")
-      const next: ActionRunRecord = {
-        ...existing,
-        phase: input.phase,
-      }
-
-      this.rows.set(key, structuredClone(next))
-      return cloneActionRunRecord(next)
-    })
-  }
-
-  async recordWriteback(input: RecordActionWritebackInput): Promise<ActionRunRecord> {
-    return this.runRootOperation(() => {
-      const key = actionRunKey(input.projectId, input.id)
-      const existing = this.requireRunningRun(key, input.projectId, input.id, "record writeback")
-      const writeback = normalizeWriteback(input, new Date(input.completedAt ?? new Date()))
-
-      if (existing.writeback) {
-        if (actionRunPhaseRecordsEqual(existing.writeback, writeback)) {
-          return cloneActionRunRecord(existing)
-        }
-
-        throw new ActionRunError(
-          `[Sixb] Action run '${input.id}' already has a different writeback record.`
-        )
-      }
-
-      const next: ActionRunRecord = {
-        ...existing,
-        phase: "writeback",
-        writeback,
-      }
-
-      this.rows.set(key, structuredClone(next))
-      return cloneActionRunRecord(next)
-    })
-  }
-
   async recordEffects(input: RecordActionEffectsInput): Promise<ActionRunRecord> {
     return this.runRootOperation(() => {
       const key = actionRunKey(input.projectId, input.id)
-      const existing = this.requireRunningRun(key, input.projectId, input.id, "record effects")
-      const effects = normalizeEffects(input, new Date(input.completedAt ?? new Date()))
-
-      if (existing.effects) {
-        if (actionRunPhaseRecordsEqual(existing.effects, effects)) {
-          return cloneActionRunRecord(existing)
-        }
-
-        throw new ActionRunError(
-          `[Sixb] Action run '${input.id}' already has a different effects record.`
-        )
-      }
-
-      const next: ActionRunRecord = {
-        ...existing,
-        phase: "effects",
-        effects,
-      }
+      const { run, effects } = resolveActionRunEffects(this.rows.get(key) ?? null, input)
+      if (!effects) return cloneActionRunRecord(run)
 
+      const next: ActionRunRecord = { ...run, phase: "effects", effects }
       this.rows.set(key, structuredClone(next))
       return cloneActionRunRecord(next)
     })
   }
 
-  async finish(input: FinishActionRunInput): Promise<ActionRunRecord> {
-    return this.runRootOperation(() => {
-      const key = actionRunKey(input.projectId, input.id)
-      const existing = this.rows.get(key)
-
-      if (!existing) {
-        throw new ActionRunError(
-          `[Sixb] Action run '${input.id}' not found for project '${input.projectId}'.`
-        )
-      }
-
-      if (isTerminalActionRun(existing)) {
-        throw new ActionRunError(
-          `[Sixb] Action run '${input.id}' cannot finish from terminal status '${existing.status}'.`
-        )
-      }
-
-      const phase =
-        input.status === "succeeded" ? (input.phase ?? existing.phase) : input.error.details.phase
-
-      const base: ActionRunRecord = {
-        ...existing,
-        status: input.status,
-        phase,
-        finishedAt: new Date(input.finishedAt ?? new Date()),
-      }
-
-      const next: ActionRunRecord =
-        input.status === "succeeded"
-          ? {
-              ...base,
-              error: undefined,
-            }
-          : {
-              ...base,
-              error: normalizeError(input.error),
-            }
-
-      this.rows.set(key, structuredClone(next))
-      return cloneActionRunRecord(next)
-    })
-  }
-
-  private requireRunningRun(
-    key: string,
-    projectId: string,
-    id: string,
-    operation: string
-  ): ActionRunRecord {
-    const existing = this.rows.get(key)
-
-    if (!existing) {
-      throw new ActionRunError(`[Sixb] Action run '${id}' not found for project '${projectId}'.`)
-    }
-
-    if (existing.status !== "running") {
-      throw new ActionRunError(
-        `[Sixb] Action run '${id}' cannot ${operation} from status '${existing.status}'.`
-      )
-    }
-
-    return existing
-  }
-
   async getById(params: { projectId: string; id: string }): Promise<ActionRunRecord | null> {
     return this.runRootOperation(() => {
       const record = this.rows.get(actionRunKey(params.projectId, params.id))
@@ -408,12 +145,8 @@ export class InMemoryActionRunStorage implements ActionRunStorage {
             : true
         )
         .filter((record) => (statuses ? statuses.has(record.status) : true))
-        .filter((record) =>
-          input.startedAfter ? (record.startedAt ?? record.queuedAt) >= input.startedAfter : true
-        )
-        .filter((record) =>
-          input.startedBefore ? (record.startedAt ?? record.queuedAt) <= input.startedBefore : true
-        )
+        .filter((record) => (input.startedAfter ? record.startedAt >= input.startedAfter : true))
+        .filter((record) => (input.startedBefore ? record.startedAt <= input.startedBefore : true))
         .sort((a, b) => compareRuns(a, b, order))
 
       const total = filtered.length
@@ -421,30 +154,6 @@ export class InMemoryActionRunStorage implements ActionRunStorage {
       return { runs, hasMore: offset + runs.length < total, total }
     })
   }
-
-  private requireMaterializationRun(input: LockActionMaterializationRunInput): ActionRunRecord {
-    assertNonBlank(input.projectId, "projectId")
-    assertNonBlank(input.runId, "runId")
-    assertNonBlank(input.actionId, "actionId")
-
-    const existing = this.rows.get(actionRunKey(input.projectId, input.runId))
-    if (!existing) {
-      throw new ActionRunError(
-        `[Sixb] Action run '${input.runId}' not found for project '${input.projectId}'.`
-      )
-    }
-    if (existing.actionId !== input.actionId) {
-      throw new ActionRunError(
-        `[Sixb] Action run '${input.runId}' does not belong to action '${input.actionId}'.`
-      )
-    }
-    if (existing.status !== "running") {
-      throw new ActionRunError(
-        `[Sixb] Action run '${input.runId}' cannot materialize from status '${existing.status}'.`
-      )
-    }
-    return existing
-  }
 }
 
 export type InMemoryActionRunStorageSnapshot = Map<string, ActionRunRecord>

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

@@ -1,13 +1,4 @@
 export { ActionRunError } from "./errors"
-export type { ActionRunPhaseRecord } from "./idempotency"
-export {
-  actionRunParamsEqual,
-  actionRunPhaseRecordsEqual,
-  actionSubjectsEqual,
-  canRequeueActionRunAfterEnqueueFailure,
-  finishActionRunPhase,
-  isTerminalActionRun,
-} from "./idempotency"
 export { InMemoryActionRunStorage } from "./in-memory"
 export type {
   ActionRunEffectsRecord,
@@ -16,19 +7,13 @@ export type {
   ActionRunFailureDetails,
   ActionRunParams,
   ActionRunPhase,
-  ActionRunPhaseStatus,
   ActionRunRecord,
   ActionRunStatus,
   ActionRunStorage,
   ActionRunWritebackRecord,
-  EnterActionRunPhaseInput,
-  FinishActionRunInput,
   ListActionRunsInput,
   ListActionRunsResult,
-  LockActionMaterializationRunInput,
-  QueueActionRunInput,
   RecordActionEffectsInput,
-  RecordActionWritebackInput,
-  StartActionRunInput,
+  RecordActionRunInput,
 } from "./types"
 export { ACTION_RUN_FAILURE_CODES, ACTION_RUN_PHASES } from "./types"

package/src/storage/action-runs/record.ts

@@ -0,0 +1,130 @@
+import { assertJsonValue, cloneJsonValue } from "../../json"
+import { ActionRunError } from "./errors"
+import { parseActionRunFailure } from "./failure"
+import { actionRunPhaseRecordsEqual } from "./idempotency"
+import type {
+  ActionRunEffectsRecord,
+  ActionRunRecord,
+  ActionRunWritebackRecord,
+  RecordActionEffectsInput,
+  RecordActionRunInput,
+} from "./types"
+import { ACTION_RUN_PHASES } from "./types"
+
+/**
+ * Validate a terminal run record before a provider inserts it, and detach it from the caller.
+ *
+ * Every provider records through this, so a stored run always reads back as the record that was
+ * written: a failed run carries the failure of the phase it ended in, and a succeeded one none. A
+ * run is recorded before its effects run, so no record starts in the `effects` phase.
+ */
+export function normalizeRecordActionRunInput(input: RecordActionRunInput): RecordActionRunInput {
+  const label = `[Sixb] Action run '${input.id}'`
+  for (const field of ["id", "projectId", "executionId", "actionId", "idempotencyKey"] as const) {
+    if (typeof input[field] !== "string" || input[field].trim().length === 0) {
+      throw new ActionRunError(`${label} must have a nonblank ${field}.`)
+    }
+  }
+  const status: string = input.status
+  if (status !== "succeeded" && status !== "failed") {
+    throw new ActionRunError(`${label} has unknown status '${status}'.`)
+  }
+  if (!(ACTION_RUN_PHASES as readonly string[]).includes(input.phase)) {
+    throw new ActionRunError(`${label} has unknown phase '${input.phase}'.`)
+  }
+  if (input.phase === "effects") {
+    throw new ActionRunError(`${label} is recorded before its effects run.`)
+  }
+  const startedAt = requireDate(input.startedAt, `${label} startedAt`)
+  const finishedAt = requireDate(input.finishedAt, `${label} finishedAt`)
+  if (finishedAt < startedAt) {
+    throw new ActionRunError(`${label} cannot finish before it started.`)
+  }
+  assertJsonValue(input.params, `${label} params`)
+
+  const fields = {
+    id: input.id,
+    projectId: input.projectId,
+    executionId: input.executionId,
+    actionId: input.actionId,
+    subject: structuredClone(input.subject),
+    phase: input.phase,
+    startedAt,
+    finishedAt,
+    params: structuredClone(input.params),
+    idempotencyKey: input.idempotencyKey,
+    ...(input.writeback === undefined
+      ? {}
+      : { writeback: normalizeWriteback(input.writeback, label) }),
+  }
+
+  if (input.status === "succeeded") {
+    if (input.error !== undefined) {
+      throw new ActionRunError(`${label} succeeded, so it cannot record a failure.`)
+    }
+    return { ...fields, status: "succeeded" }
+  }
+  const error = parseActionRunFailure(input.error, input.phase)
+  if (error.details.runId !== input.id || error.details.actionId !== input.actionId) {
+    throw new ActionRunError(`${label} records the failure of another run.`)
+  }
+  return { ...fields, status: "failed", error }
+}
+
+/**
+ * Resolve what recording effects does to the stored run: write `effects`, or nothing (`null`) when
+ * an equal outcome is already recorded.
+ *
+ * Effects run only after a succeeded run committed its edits, and their outcome is recorded once.
+ */
+export function resolveActionRunEffects(
+  existing: ActionRunRecord | null,
+  input: RecordActionEffectsInput
+): { readonly run: ActionRunRecord; readonly effects: ActionRunEffectsRecord | null } {
+  const label = `[Sixb] Action run '${input.id}'`
+  if (!existing) {
+    throw new ActionRunError(`${label} not found for project '${input.projectId}'.`)
+  }
+  const completedAt = requireDate(input.completedAt ?? new Date(), `${label} effects`)
+  const effects: ActionRunEffectsRecord =
+    input.status === "succeeded"
+      ? { status: "succeeded", completedAt }
+      : { status: "failed", completedAt, error: parseActionRunFailure(input.error, "effects") }
+
+  if (existing.effects) {
+    if (actionRunPhaseRecordsEqual(existing.effects, effects))
+      return { run: existing, effects: null }
+    throw new ActionRunError(`${label} already has a different effects record.`)
+  }
+  if (existing.status !== "succeeded" || existing.phase !== "commit") {
+    throw new ActionRunError(
+      `${label} cannot record effects: it ended '${existing.status}' in phase '${existing.phase}'.`
+    )
+  }
+  return { run: existing, effects }
+}
+
+function normalizeWriteback(
+  writeback: ActionRunWritebackRecord,
+  label: string
+): ActionRunWritebackRecord {
+  const completedAt = requireDate(writeback.completedAt, `${label} writeback`)
+  if (writeback.status === "succeeded") {
+    assertJsonValue(writeback.result, `${label} writeback result`)
+    return { status: "succeeded", completedAt, result: cloneJsonValue(writeback.result) }
+  }
+  return {
+    status: "failed",
+    completedAt,
+    error: parseActionRunFailure(writeback.error, "writeback"),
+  }
+}
+
+/** A detached copy of `value`, which must be a valid date. */
+function requireDate(value: Date, label: string): Date {
+  const date = value instanceof Date ? new Date(value) : new Date(Number.NaN)
+  if (!Number.isFinite(date.getTime())) {
+    throw new ActionRunError(`${label} must be a valid date.`)
+  }
+  return date
+}