@sixb/core 0.1.17 → 0.1.19

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/agents/provider.ts

@@ -150,6 +150,17 @@ export function assertConversationAgentRunSpec(
       `[${prefix}] Conversational Agent reasoning must be one of: ${AGENT_REASONING_LEVELS.join(", ")}, or a nonnegative budgetTokens object.`
     )
   }
+  for (const [name, value] of [
+    ["timeZone", spec.timeZone],
+    ["locale", spec.locale],
+  ] as const) {
+    if (value !== undefined && (typeof value !== "string" || value.trim().length === 0)) {
+      throw new AgentStorageError(
+        "invalid_input",
+        `[${prefix}] Conversational Agent run '${name}' must be a non-empty string.`
+      )
+    }
+  }
 }
 
 function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {

package/src/storage/agents/types.ts

@@ -1,5 +1,5 @@
 import type { AgentMessage, AgentMessagePart, AgentMessageRole } from "../../agents/message"
-import type { AgentReasoningLevel } from "../../agents/types"
+import type { AgentReasoning } from "../../agents/types"
 import type { Principal } from "../../auth"
 import type { FileRef } from "../../blob-storage"
 import type { SixbErrorCode, SixbFailure } from "../../errors/types"
@@ -123,8 +123,9 @@ export type AgentRunFailureCode = (typeof AGENT_RUN_FAILURE_CODES)[number]
 
 /**
  * Why a run ended — Sixb's provider-independent vocabulary. It includes model-loop reasons plus
- * platform-level endings such as `timeout`, so reads remain typed and exhaustive. `other` and
- * `unknown` preserve terminal state when a provider adds a new reason.
+ * platform-level endings such as `timeout`, or `interrupted` for a turn whose worker died before
+ * finishing it, so reads remain typed and exhaustive. `other` and `unknown` preserve terminal state
+ * when a provider adds a new reason.
  */
 export const AGENT_RUN_FINISH_REASONS = [
   "stop",
@@ -132,6 +133,7 @@ export const AGENT_RUN_FINISH_REASONS = [
   "content-filter",
   "tool-calls",
   "timeout",
+  "interrupted",
   "error",
   "other",
   "unknown",
@@ -162,6 +164,7 @@ export const AGENT_RUN_DIAGNOSTIC_CODES = [
   "output_collection_failed",
   "output_file_changed",
   "output_storage_failed",
+  "step_limit_reached",
 ] as const
 
 /**
@@ -178,7 +181,8 @@ export type AgentRunDiagnosticSeverity = "warning" | "error"
 export interface AgentRunDiagnostic {
   readonly code: AgentRunDiagnosticCode
   readonly severity: AgentRunDiagnosticSeverity
-  readonly scope: "output"
+  /** `output` for published files, `run` for the turn as a whole. */
+  readonly scope: "output" | "run"
   /** Relative path inside the run's published output directory, when one file is involved. */
   readonly path?: string
   /** Sanitized, stable copy suitable for display to an end user. */
@@ -224,16 +228,20 @@ export interface ConversationAgentRunRecord extends AgentRunRecordBase {
   readonly spec?: ConversationAgentRunSpec
 }
 
-/** Immutable, serialisable model selection for one conversational turn. */
+/** Immutable, serialisable model selection and requester settings for one conversational turn. */
 export interface ConversationAgentRunSpec {
   readonly model: LanguageModelRef
-  readonly reasoning?: AgentReasoningLevel
+  readonly reasoning?: AgentReasoning
+  /** Canonical IANA time zone of the requester. Absent uses the project time zone. */
+  readonly timeZone?: string
+  /** Canonical BCP 47 language of the requester. Absent uses the project locale. */
+  readonly locale?: string
 }
 
 /** Immutable, serialisable child configuration captured before dispatch. */
 export interface SubagentRunSpec {
   readonly model: LanguageModelRef
-  readonly reasoning?: AgentReasoningLevel
+  readonly reasoning?: AgentReasoning
   /** Focused task supplied by the parent Agent. */
   readonly task: string
   /** Project tools available when the child was admitted. Runtime tools are injected separately. */

package/src/storage/index.ts

@@ -21,6 +21,7 @@ export type {
 } from "../materialization/model"
 export type { ModelProviderIds } from "../models/events"
 export type { ObjectRef } from "../ontology"
+export type { RedactionReason, Redactions } from "../security/types"
 export type {
   ShareAccessPlan,
   ShareScopedActionGrant,
@@ -34,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/objects/types.ts

@@ -6,6 +6,7 @@ import type {
   ObjectQuerySortField,
   QueryScalarKind,
 } from "../../objects/query"
+import type { Redactions } from "../../security/types"
 import type { ObjectReadExecutionLimits } from "./execution-limits"
 import type { LinkBatchKey, ObjectBatchKey } from "./keys"
 
@@ -33,6 +34,12 @@ export interface ObjectRow {
    * `.links` typing are layered on top of this runtime shape.
    */
   links?: ObjectRowLinks
+  /**
+   * Properties omitted because the reader lacks a clearance, keyed by property id.
+   *
+   * Populated by the authorized object reader; storage providers never read or write it.
+   */
+  redactions?: Redactions
 }
 
 /** Per-link expansion result keyed by link id (see {@link ObjectQueryExpand}). */

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