intentdna 1.8.6 → 1.8.7

package/dist/runtime/run-store.d.ts

@@ -0,0 +1,96 @@
+import type { AttemptRecord, CommittedStepResult, JsonValue, RunId, RuntimeEvent, TaskClaim, TaskRecord } from "./run-contracts.js";
+export declare const RUN_STORE_SCHEMA_VERSION: 1;
+export declare const RUN_STATUS_VALUES: readonly ["active", "cancelling", "succeeded", "failed", "cancelled"];
+export type RunStatus = typeof RUN_STATUS_VALUES[number];
+export type TerminalRunStatus = Extract<RunStatus, "succeeded" | "failed" | "cancelled">;
+export interface RunCancellationIntent {
+    readonly requested_at: string;
+    readonly reason: string | null;
+}
+export interface RunTerminalRecord {
+    readonly status: TerminalRunStatus;
+    readonly reason: string | null;
+    readonly completed_at: string;
+}
+export interface RunRecord {
+    readonly run_id: RunId;
+    readonly workflow_id: string;
+    readonly workflow_version: string | null;
+    readonly plan_digest: string;
+    readonly status: RunStatus;
+    readonly cancellation: RunCancellationIntent | null;
+    readonly terminal: RunTerminalRecord | null;
+    readonly metadata: JsonValue;
+    readonly created_at: string;
+    readonly updated_at: string;
+}
+/**
+ * Claims are retained as history. The task and attempt records determine which
+ * claim is current; renewing a lease updates the matching claim token in place.
+ */
+export type StoredTaskClaim = TaskClaim;
+export interface RunStoreSnapshot {
+    readonly schema_version: typeof RUN_STORE_SCHEMA_VERSION;
+    readonly record_version: number;
+    readonly run: RunRecord;
+    readonly tasks: readonly TaskRecord[];
+    readonly attempts: readonly AttemptRecord[];
+    readonly claims: readonly StoredTaskClaim[];
+    readonly events: readonly RuntimeEvent[];
+    readonly results: readonly CommittedStepResult[];
+    readonly created_at: string;
+    readonly updated_at: string;
+}
+export interface CreateRunStoreRecord {
+    readonly run: RunRecord;
+    readonly tasks?: readonly TaskRecord[];
+}
+/**
+ * Collections are upserted by their durable identity. Events and results are
+ * append-only: an exact/idempotent replay is ignored and a conflict is rejected.
+ */
+export interface RunStoreUpdate {
+    readonly run_id: RunId;
+    readonly expected_record_version: number;
+    readonly run?: RunRecord;
+    readonly tasks?: readonly TaskRecord[];
+    readonly attempts?: readonly AttemptRecord[];
+    readonly claims?: readonly StoredTaskClaim[];
+    readonly events?: readonly RuntimeEvent[];
+    readonly results?: readonly CommittedStepResult[];
+}
+export interface RunStoreUpdateResult {
+    readonly snapshot: RunStoreSnapshot;
+    readonly applied: boolean;
+    readonly duplicate_event_ids: readonly string[];
+    readonly duplicate_result_ids: readonly string[];
+}
+export interface DurableRunStoreOptions {
+    readonly root_directory: string;
+    readonly lock_wait_ms?: number;
+    readonly lock_stale_ms?: number;
+    readonly lock_retry_ms?: number;
+    readonly lock_heartbeat_ms?: number;
+}
+export type RunStoreErrorCode = "invalid_options" | "invalid_record" | "unsupported_schema" | "run_exists" | "run_not_found" | "version_conflict" | "immutable_record" | "identity_conflict" | "event_conflict" | "result_conflict" | "lock_timeout" | "lock_lost";
+export declare class RunStoreError extends Error {
+    readonly code: RunStoreErrorCode;
+    constructor(code: RunStoreErrorCode, message: string);
+}
+export declare class DurableRunStore {
+    private readonly options;
+    constructor(options: DurableRunStoreOptions);
+    private runDirectory;
+    private ledgerPath;
+    private lockDirectory;
+    private readSnapshot;
+    createRun(input: CreateRunStoreRecord): Promise<RunStoreSnapshot>;
+    loadRun(runId: RunId): Promise<RunStoreSnapshot | null>;
+    requireRun(runId: RunId): Promise<RunStoreSnapshot>;
+    updateRun(update: RunStoreUpdate): Promise<RunStoreUpdateResult>;
+    /**
+     * Reads every valid run ledger after restart. No worker-session directory is
+     * consulted, and this store intentionally exposes no worker cleanup operation.
+     */
+    loadAllRuns(): Promise<readonly RunStoreSnapshot[]>;
+}