@sixb/core 0.1.18 → 0.1.19

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
+}

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

@@ -2,32 +2,26 @@ import type { ActionSubject } from "../../actions"
 import type { SixbErrorCode, SixbFailure } from "../../errors/types"
 import type { JsonValue } from "../../json"
 
-export type ActionRunStatus = "queued" | "running" | "succeeded" | "failed" | "cancelled"
-
-export const ACTION_RUN_PHASES = [
-  "request",
-  "enqueue",
-  "validation",
-  "writeback",
-  "edits",
-  "commit",
-  "effects",
-  "cancelled",
-] as const
+/**
+ * How a run ended. A run is recorded once, when it ends: while it executes, the request that runs
+ * it is its only state.
+ */
+export type ActionRunStatus = "succeeded" | "failed"
+
+/** The phases of a run, in the order it reaches them. */
+export const ACTION_RUN_PHASES = ["validation", "writeback", "edits", "commit", "effects"] as const
 
 export type ActionRunPhase = (typeof ACTION_RUN_PHASES)[number]
 
 export type ActionRunParams = Readonly<Record<string, JsonValue>>
 
-export type ActionRunPhaseStatus = "succeeded" | "failed"
-
 /** Error codes an action run or phase record can persist and expose. */
 export const ACTION_RUN_FAILURE_CODES = [
   "internal.unexpected",
   "runtime.cancelled",
-  "queue.enqueue_failed",
   "action.phase_failed",
   "action.read_conflict",
+  "action.timeout",
 ] as const satisfies readonly [SixbErrorCode, ...SixbErrorCode[]]
 
 export type ActionRunFailureCode = (typeof ACTION_RUN_FAILURE_CODES)[number]
@@ -70,67 +64,34 @@ export type ActionRunEffectsRecord =
       readonly error: ActionRunFailure<"effects">
     }
 
-export interface ActionRunRecord {
+interface ActionRunRecordFields {
   readonly id: string
   readonly projectId: string
   readonly executionId: string
   readonly actionId: string
   readonly subject: ActionSubject
-  readonly status: ActionRunStatus
-  readonly phase?: ActionRunPhase
-  readonly queuedAt: Date
-  readonly startedAt?: Date
-  readonly finishedAt?: Date
+  /** The last phase the run reached. */
+  readonly phase: ActionRunPhase
+  readonly startedAt: Date
+  readonly finishedAt: Date
   readonly params: ActionRunParams
   readonly idempotencyKey: string
   readonly writeback?: ActionRunWritebackRecord
-  readonly effects?: ActionRunEffectsRecord
-  readonly error?: ActionRunFailure
-}
-
-export interface QueueActionRunInput {
-  readonly id: string
-  readonly projectId: string
-  readonly executionId: string
-  readonly actionId: string
-  readonly subject: ActionSubject
-  readonly params: ActionRunParams
-  readonly idempotencyKey: string
-  readonly queuedAt?: Date
 }
 
-export interface StartActionRunInput {
-  readonly id: string
-  readonly projectId: string
-  readonly startedAt?: Date
-  readonly phase?: Extract<ActionRunPhase, "validation">
-}
+/** A run's terminal record, as it is written once when the run ends. */
+export type RecordActionRunInput =
+  | (ActionRunRecordFields & { readonly status: "succeeded"; readonly error?: never })
+  | (ActionRunRecordFields & { readonly status: "failed"; readonly error: ActionRunFailure })
 
-export interface EnterActionRunPhaseInput {
-  readonly id: string
-  readonly projectId: string
-  readonly phase: Extract<
-    ActionRunPhase,
-    "validation" | "writeback" | "edits" | "commit" | "effects"
-  >
+/**
+ * A recorded run. Its effects run after its record is written, so their outcome is the one part
+ * recorded later, on a succeeded run that committed edits.
+ */
+export type ActionRunRecord = RecordActionRunInput & {
+  readonly effects?: ActionRunEffectsRecord
 }
 
-export type RecordActionWritebackInput =
-  | {
-      readonly id: string
-      readonly projectId: string
-      readonly status: "succeeded"
-      readonly completedAt?: Date
-      readonly result: JsonValue
-    }
-  | {
-      readonly id: string
-      readonly projectId: string
-      readonly status: "failed"
-      readonly completedAt?: Date
-      readonly error: ActionRunFailure<"writeback">
-    }
-
 export type RecordActionEffectsInput =
   | {
       readonly id: string
@@ -146,22 +107,6 @@ export type RecordActionEffectsInput =
       readonly error: ActionRunFailure<"effects">
     }
 
-export type FinishActionRunInput =
-  | {
-      readonly id: string
-      readonly projectId: string
-      readonly status: "succeeded"
-      readonly finishedAt?: Date
-      readonly phase?: ActionRunPhase
-    }
-  | {
-      readonly id: string
-      readonly projectId: string
-      readonly status: "failed" | "cancelled"
-      readonly finishedAt?: Date
-      readonly error: ActionRunFailure
-    }
-
 export interface ListActionRunsInput {
   readonly projectId: string
   readonly actionId?: string
@@ -184,21 +129,21 @@ export interface ListActionRunsResult {
   readonly total: number
 }
 
-export interface LockActionMaterializationRunInput {
-  readonly projectId: string
-  readonly actionId: string
-  readonly runId: string
-}
-
 export interface ActionRunStorage {
-  /** Transactional fence for Action identity and running state before a new ontology commit. */
-  lockForMaterialization(input: LockActionMaterializationRunInput): Promise<ActionRunRecord>
-  queue(input: QueueActionRunInput): Promise<ActionRunRecord>
-  start(input: StartActionRunInput): Promise<ActionRunRecord>
-  enterPhase(input: EnterActionRunPhaseInput): Promise<ActionRunRecord>
-  recordWriteback(input: RecordActionWritebackInput): Promise<ActionRunRecord>
+  /**
+   * Insert a run's terminal record.
+   *
+   * A run is recorded once: a run id that already has a record is refused with an
+   * `ActionRunError`, and so is an execution that already recorded another run. The execution must
+   * be the trusted primitive execution created for this run.
+   */
+  record(input: RecordActionRunInput): Promise<ActionRunRecord>
+  /**
+   * Record the outcome of the effects of a succeeded run that committed edits, once. Recording an
+   * equal outcome again returns the run unchanged.
+   */
   recordEffects(input: RecordActionEffectsInput): Promise<ActionRunRecord>
-  finish(input: FinishActionRunInput): Promise<ActionRunRecord>
   getById(params: { projectId: string; id: string }): Promise<ActionRunRecord | null>
+  /** Runs ordered by `startedAt`, then id. */
   list(input: ListActionRunsInput): Promise<ListActionRunsResult>
 }

package/src/storage/index.ts

@@ -35,28 +35,20 @@ export type {
   ActionRunFailureDetails,
   ActionRunParams,
   ActionRunPhase,
-  ActionRunPhaseRecord,
-  ActionRunPhaseStatus,
   ActionRunRecord,
   ActionRunStatus,
   ActionRunStorage,
   ActionRunWritebackRecord,
-  EnterActionRunPhaseInput,
-  FinishActionRunInput,
   ListActionRunsInput,
   ListActionRunsResult,
-  LockActionMaterializationRunInput,
-  QueueActionRunInput,
   RecordActionEffectsInput,
-  RecordActionWritebackInput,
-  StartActionRunInput,
+  RecordActionRunInput,
 } from "./action-runs"
 export {
   ACTION_RUN_FAILURE_CODES,
   ACTION_RUN_PHASES,
   ActionRunError,
   InMemoryActionRunStorage,
-  isTerminalActionRun,
 } from "./action-runs"
 export type {
   AgentContextCheckpointReason,

package/src/storage/internal.ts

@@ -1,12 +1,6 @@
 /** Implementation exports for Sixb packages only. */
 
-export {
-  actionRunParamsEqual,
-  actionRunPhaseRecordsEqual,
-  actionSubjectsEqual,
-  canRequeueActionRunAfterEnqueueFailure,
-  finishActionRunPhase,
-} from "./action-runs/idempotency"
+export { normalizeRecordActionRunInput, resolveActionRunEffects } from "./action-runs/record"
 export { assertAiUsageExecutionId, normalizeAiModelCallRecord } from "./ai-usage/record"
 export { normalizeAiModelCallUsage } from "./ai-usage/usage"
 export { parseFileDownloadGrantRow } from "./file-download-grants/record"

package/src/storage/objects/execution-limits.ts

@@ -20,9 +20,10 @@ export class ObjectReadLimitExceededError extends Error {
 
   constructor(
     readonly metric: ObjectReadLimitMetric,
-    readonly limit: number
+    readonly limit: number,
+    message = `[Sixb] Object read exceeded its ${metric} limit (${limit}).`
   ) {
-    super(`[Sixb] Object read exceeded its ${metric} limit (${limit}).`)
+    super(message)
   }
 }
 

package/src/storage/types.ts

@@ -35,12 +35,10 @@ export type {
   ActionRunRecord,
   ActionRunStatus,
   ActionRunStorage,
-  FinishActionRunInput,
   ListActionRunsInput,
   ListActionRunsResult,
-  LockActionMaterializationRunInput,
-  QueueActionRunInput,
-  StartActionRunInput,
+  RecordActionEffectsInput,
+  RecordActionRunInput,
 } from "./action-runs"
 export { ACTION_RUN_FAILURE_CODES, ACTION_RUN_PHASES, ActionRunError } from "./action-runs"
 export type {

package/src/testing/action-execution.ts

@@ -1,5 +1,14 @@
+import type { ActionSubject } from "../actions"
 import type { AuthorizablePrincipal, TrustedPrimitiveRef } from "../execution"
-import type { ActionRunRecord, QueueActionRunInput, Storage } from "../storage"
+import type {
+  ActionRunFailure,
+  ActionRunParams,
+  ActionRunPhase,
+  ActionRunRecord,
+  ActionRunWritebackRecord,
+  RecordActionRunInput,
+  Storage,
+} from "../storage"
 import type { ExecutionStorage } from "../storage/executions"
 
 /** Create the durable execution chain required by an Action-run storage fixture. */
@@ -57,22 +66,73 @@ export async function createTestActionExecution(
   return executionId
 }
 
-/** Queue an Action run with the valid durable execution fixture required by every provider. */
-export async function queueTestActionRun(
-  storage: Pick<Storage, "actionRuns" | "executions">,
-  input: Omit<QueueActionRunInput, "executionId"> & {
-    readonly requesterGroupIds?: readonly string[]
-    readonly requestedBy?: AuthorizablePrincipal
-  }
-): Promise<ActionRunRecord> {
-  if (!storage.actionRuns) throw new Error("Action run storage is not configured for this test.")
-  const executionId = await createTestActionExecution(storage.executions, {
+type TestActionRunOutcome =
+  | { readonly status?: "succeeded"; readonly error?: never }
+  | { readonly status: "failed"; readonly error: ActionRunFailure }
+
+/** A test Action run that ended. It succeeds in its commit phase unless told otherwise. */
+export type TestActionRunInput = TestActionRunOutcome & {
+  readonly id: string
+  readonly projectId: string
+  readonly actionId: string
+  readonly subject: ActionSubject
+  readonly params: ActionRunParams
+  readonly idempotencyKey: string
+  /** Defaults to `commit` for a succeeded run, and to its failure's phase for a failed one. */
+  readonly phase?: ActionRunPhase
+  /** Defaults to now. */
+  readonly startedAt?: Date
+  /** Defaults to `startedAt`. */
+  readonly finishedAt?: Date
+  readonly writeback?: ActionRunWritebackRecord
+  readonly requesterGroupIds?: readonly string[]
+  /** Must name an existing auth principal. The parent request then carries its authority. */
+  readonly requestedBy?: AuthorizablePrincipal
+}
+
+/**
+ * Create a test run's durable execution, and return the run's terminal record without writing it:
+ * an Action commit carries the record it inserts.
+ */
+export async function createTestActionRunRecord(
+  executions: ExecutionStorage,
+  input: TestActionRunInput
+): Promise<RecordActionRunInput> {
+  const executionId = await createTestActionExecution(executions, {
     projectId: input.projectId,
     actionId: input.actionId,
     runId: input.id,
     requesterGroupIds: input.requesterGroupIds,
     ...(input.requestedBy === undefined ? {} : { requestedBy: input.requestedBy }),
   })
-  const { requesterGroupIds: _groups, requestedBy: _requestedBy, ...run } = input
-  return storage.actionRuns.queue({ ...run, executionId })
+  const startedAt = input.startedAt ?? new Date()
+  const fields = {
+    id: input.id,
+    projectId: input.projectId,
+    executionId,
+    actionId: input.actionId,
+    subject: input.subject,
+    params: input.params,
+    idempotencyKey: input.idempotencyKey,
+    startedAt,
+    finishedAt: input.finishedAt ?? startedAt,
+    ...(input.writeback === undefined ? {} : { writeback: input.writeback }),
+  }
+  return input.status === "failed"
+    ? {
+        ...fields,
+        status: "failed",
+        phase: input.phase ?? input.error.details.phase,
+        error: input.error,
+      }
+    : { ...fields, status: "succeeded", phase: input.phase ?? "commit" }
+}
+
+/** Record a test Action run with the valid durable execution every provider requires. */
+export async function recordTestActionRun(
+  storage: Pick<Storage, "actionRuns" | "executions">,
+  input: TestActionRunInput
+): Promise<ActionRunRecord> {
+  if (!storage.actionRuns) throw new Error("Action run storage is not configured for this test.")
+  return storage.actionRuns.record(await createTestActionRunRecord(storage.executions, input))
 }