@osolmaz/pi-workflows 0.12.0 → 0.13.0

package/dist/workflows/store.d.ts

@@ -1,105 +1,30 @@
-import type { WorkflowDefinition, WorkflowDefinitionSnapshot, WorkflowRunManifest, WorkflowRunState, WorkflowSessionBinding, WorkflowSessionCapture, WorkflowSessionEntryRecord, WorkflowSessionEventRecord, WorkflowTraceEvent, WorkflowTraceEventDraft, WorkflowUpdateInput, WorkflowUpdateRecord } from "./types.js";
-export declare const RUN_BUNDLE_SCHEMA: "pi-workflows.run-bundle.v1";
+import { StateDatabase } from "../state/database.js";
+import { type MutationActor, type OwnerType } from "../state/mutation.js";
+import type { WorkflowDefinition, WorkflowDefinitionSnapshot, WorkflowRunState, WorkflowSessionBinding, WorkflowSessionCapture, WorkflowSessionEntryRecord, WorkflowSessionEventRecord, WorkflowTraceEvent, WorkflowTraceEventDraft, WorkflowUpdateInput, WorkflowUpdateRecord } from "./types.js";
 export declare const RUN_STATE_SCHEMA: "pi-workflows.run-state.v1";
-export declare const TRACE_EVENT_SCHEMA: "pi-workflows.trace-event.v1";
 export declare const DEFINITION_SNAPSHOT_SCHEMA: "pi-workflows.definition-snapshot.v1";
 export declare const SESSION_BINDING_SCHEMA: "pi-workflows.session-binding.v1";
 export declare const SESSION_EVENT_SCHEMA: "pi-workflows.session-event.v1";
 export declare const SESSION_CAPTURE_SCHEMA: "pi-workflows.session-capture.v1";
 export declare const SESSION_EVENT_MAX_BYTES: number;
-/** Runs directory: `$PI_WORKFLOWS_RUNS_DIR` or `~/.pi/agent/workflows/runs`. */
-export declare function workflowRunsBaseDir(homeDir?: string): string;
+export declare function workflowStateDatabasePath(homeDir?: string): string;
 export declare function createRunId(workflowName: string, now?: Date): string;
-/**
- * Persists run bundles (see docs/run-bundles.md). `trace.ndjson` is the
- * append-only source of truth; every transition appends the trace event
- * first, then atomically replaces `state.json` (carrying `traceSeq`) and
- * `manifest.json`. Large string leaves in persisted values are externalized
- * into content-addressed `artifacts/`. Bundles are private: directories are
- * 0700 and files 0600.
- */
-/**
- * A fence proves the writer still owns the run. It is checked before every
- * locked write; it throws (ClaimLostError) when the queue claim was lost, so
- * a stalled runner can never interleave writes with the new claim holder.
- */
-export type RunFence = () => void;
+export type RunWriteAuthority = {
+    actor: MutationActor;
+    ownerType: OwnerType;
+    ownerId: string;
+    token: string;
+    generation: number;
+};
 export type WorkflowRunStoreOptions = {
-    fenceProvider?: (runDir: string) => RunFence | undefined;
+    authorityProvider?: (runId: string) => RunWriteAuthority | undefined;
+    state?: StateDatabase;
+    readOnly?: boolean;
 };
-export declare class WorkflowRunStore {
-    readonly outputRoot: string;
-    private readonly fenceProvider;
-    private readonly contexts;
-    constructor(outputRoot?: string, options?: WorkflowRunStoreOptions);
-    runDirFor(runId: string): string;
-    quarantineIncompleteRun(runId: string): Promise<string | undefined>;
-    private contextFor;
-    private streamFor;
-    /**
-     * Run `task` exclusively for this bundle. Sequence numbers are assigned
-     * inside the lock, so physical file order always matches logical order.
-     */
-    private withRunLock;
-    private withSessionEventLock;
-    initializeRunBundle(workflow: WorkflowDefinition, state: WorkflowRunState): Promise<string>;
-    /**
-     * Prepare an interrupted bundle for resume. Repairs a torn trace tail,
-     * drops trace events the state projection never recorded, and seeds the
-     * in-process context so new events continue the sequence. The caller must
-     * hold the run's queue claim; the fence is verified before any write.
-     */
-    prepareRunResume(runId: string): Promise<LoadedRunBundle>;
-    /**
-     * Finalize captures left "recording" by a session that is gone, so they
-     * report failed with the reason instead of dangling forever.
-     */
-    private finalizeRecordingCaptures;
-    /** Mark a nonterminal bundle failed and append an interruption event. */
-    markRunInterrupted(runId: string, reason?: string): Promise<LoadedRunBundle | null>;
-    /** Publish one durable update under the run's serialized claim-fenced writer. */
-    publishUpdate(runDir: string, state: WorkflowRunState, nodeId: string, attemptId: string, update: WorkflowUpdateInput, options?: {
-        signal?: AbortSignal;
-    }): Promise<{
-        event: WorkflowTraceEvent;
-        record: WorkflowUpdateRecord;
-    }>;
-    /**
-     * Persist one transition: append the trace event, then rewrite the
-     * projections reflecting it.
-     */
-    writeSnapshot(runDir: string, state: WorkflowRunState, event: WorkflowTraceEventDraft): Promise<WorkflowTraceEvent>;
-    /**
-     * Bind the run to a Pi conversation: write `session/binding.json` once and
-     * append a `session_bound` trace event. Projections catch up on the next
-     * snapshot.
-     */
-    /** True when a session binding already exists for this bundle. */
-    hasSessionBinding(runDir: string): Promise<boolean>;
-    /** List capture segment attempt ids under `session/segments/`. */
-    listSessionSegments(runDir: string): Promise<string[]>;
-    writeSessionBinding(runDir: string, binding: WorkflowSessionBinding, attemptId?: string): Promise<void>;
-    /** Append one verbatim Pi session entry to `session/entries.ndjson`. */
-    appendSessionEntry(runDir: string, entry: Record<string, unknown>, attemptId?: string): Promise<number>;
-    /** Append a fully stamped ordered batch to `session/events.ndjson`. */
-    appendSessionEventBatch(runDir: string, records: WorkflowSessionEventRecord[], attemptId?: string): Promise<void>;
-    /** Atomically replace the temporal capture integrity projection. */
-    writeSessionCapture(runDir: string, capture: WorkflowSessionCapture, attemptId?: string): Promise<void>;
-    /** Count complete durable session records after both writers have drained. */
-    sessionCounts(runDir: string, attemptId?: string): Promise<{
-        eventCount: number;
-        entryCount: number;
-        lastEventSeq: number;
-    }>;
-    private appendTraceEvent;
-    private writeProjections;
-    private writeLoadedProjections;
-}
 export type SessionCaptureIntegrity = {
     status: "unavailable" | "recording" | "complete" | "failed" | "invalid";
     diagnostics: string[];
 };
-/** One capture attempt: the session data a single recorder wrote. */
 export type SessionCaptureSegment = {
     attemptId: string;
     binding: WorkflowSessionBinding | null;
@@ -108,29 +33,84 @@ export type SessionCaptureSegment = {
     capture: WorkflowSessionCapture | null;
     integrity: SessionCaptureIntegrity;
 };
-export type LoadedRunBundle = {
-    runDir: string;
-    manifest: WorkflowRunManifest;
+export type LoadedWorkflowRun = {
+    runId: string;
     state: WorkflowRunState;
-    snapshot: WorkflowDefinitionSnapshot | null;
-    /** Full durable trace when loaded by the current reader. */
+    snapshot: WorkflowDefinitionSnapshot;
     traceEvents?: WorkflowTraceEvent[];
     sessionBinding: WorkflowSessionBinding | null;
     sessionEntries: WorkflowSessionEntryRecord[];
     sessionEvents: WorkflowSessionEventRecord[];
     sessionCapture: WorkflowSessionCapture | null;
     sessionIntegrity: SessionCaptureIntegrity;
-    /** Per-attempt captures written after a handoff or resume. */
     sessionSegments: SessionCaptureSegment[];
 };
-/** Read the final trace record without loading the rest of a run bundle. */
-export declare function readLastTraceEvent(runDir: string, tracePath?: string): Promise<WorkflowTraceEvent | null>;
-export type ReadRunBundleOptions = {
-    /** Load the full append-only trace. Detail views need it; run lists do not. */
+export type ReadWorkflowRunOptions = {
     includeTrace?: boolean;
 };
-/** Read a run bundle from disk. Returns null when the bundle is unreadable. */
-export declare function readRunBundle(runDir: string, options?: ReadRunBundleOptions): Promise<LoadedRunBundle | null>;
-/** List run bundles under `outputRoot`, most recently started first. */
-export declare function listRunBundles(outputRoot: string): Promise<LoadedRunBundle[]>;
+export declare class WorkflowRunStore {
+    readonly databasePath: string;
+    readonly state: StateDatabase;
+    private readonly authorityProvider;
+    private readonly contexts;
+    private readonly ownsState;
+    constructor(databasePath?: string, options?: WorkflowRunStoreOptions);
+    close(): void;
+    initializeRun(workflow: WorkflowDefinition, state: WorkflowRunState): Promise<string>;
+    prepareRunResume(runId: string): Promise<LoadedWorkflowRun>;
+    markRunInterrupted(runId: string, reason?: string): Promise<LoadedWorkflowRun | null>;
+    publishUpdate(runId: string, state: WorkflowRunState, nodeId: string, attemptId: string, update: WorkflowUpdateInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        event: WorkflowTraceEvent;
+        record: WorkflowUpdateRecord;
+    }>;
+    writeSnapshot(runId: string, state: WorkflowRunState, event: WorkflowTraceEventDraft): Promise<WorkflowTraceEvent>;
+    hasSessionBinding(runId: string): Promise<boolean>;
+    listSessionSegments(runId: string): Promise<string[]>;
+    writeSessionBinding(runId: string, binding: WorkflowSessionBinding, attemptId?: string): Promise<void>;
+    appendSessionEntry(runId: string, entry: Record<string, unknown>, attemptId?: string): Promise<number>;
+    appendSessionEventBatch(runId: string, records: WorkflowSessionEventRecord[], attemptId?: string): Promise<void>;
+    writeSessionCapture(runId: string, capture: WorkflowSessionCapture, attemptId?: string): Promise<void>;
+    sessionCounts(runId: string, attemptId?: string): Promise<{
+        eventCount: number;
+        entryCount: number;
+        lastEventSeq: number;
+    }>;
+    readRun(runId: string, options?: ReadWorkflowRunOptions): LoadedWorkflowRun | null;
+    listRuns(options?: ReadWorkflowRunOptions): LoadedWorkflowRun[];
+    readLastTraceEvent(runId: string): WorkflowTraceEvent | null;
+    private contextFor;
+    private withRunLock;
+    private assertSessionWriteAuthority;
+    private resourceRevision;
+    private requireResourceRevision;
+    private bumpResource;
+    private assertWriteAuthority;
+    private persistRunState;
+    private enqueueRunSettlementEffect;
+    private syncNodeAttempts;
+    private ensureAttempt;
+    private nextAttemptNumber;
+    private nextUpdateSequence;
+    private readRunRow;
+    private requireRunRow;
+    private readState;
+    private readDefinition;
+    private traceEvents;
+    private segmentRows;
+    private segmentRow;
+    private requireSegment;
+    private loadSegment;
+    private finalizeRecordingCaptures;
+}
+export declare function readWorkflowRun(runId: string, options?: ReadWorkflowRunOptions & {
+    databasePath?: string;
+}): LoadedWorkflowRun | null;
+export declare function listWorkflowRuns(options?: ReadWorkflowRunOptions & {
+    databasePath?: string;
+}): LoadedWorkflowRun[];
+export declare function readLastTraceEvent(runId: string, options?: {
+    databasePath?: string;
+}): WorkflowTraceEvent | null;
 export declare function createDefinitionSnapshot(workflow: WorkflowDefinition): WorkflowDefinitionSnapshot;