@osolmaz/pi-workflows 0.2.0 → 0.4.0

package/dist/workflows/store.d.ts

@@ -18,12 +18,24 @@ export declare function createRunId(workflowName: string, now?: Date): string;
  * 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 WorkflowRunStoreOptions = {
+    fenceProvider?: (runDir: string) => RunFence | undefined;
+};
 export declare class WorkflowRunStore {
     readonly outputRoot: string;
+    private readonly fenceProvider;
     private readonly contexts;
-    constructor(outputRoot?: string);
+    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.
@@ -31,6 +43,20 @@ export declare class WorkflowRunStore {
     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>;
     /**
      * Persist one transition: append the trace event, then rewrite the
      * projections reflecting it.
@@ -41,26 +67,40 @@ export declare class WorkflowRunStore {
      * append a `session_bound` trace event. Projections catch up on the next
      * snapshot.
      */
-    writeSessionBinding(runDir: string, binding: WorkflowSessionBinding): Promise<void>;
+    /** 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>): Promise<number>;
+    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[]): Promise<void>;
+    appendSessionEventBatch(runDir: string, records: WorkflowSessionEventRecord[], attemptId?: string): Promise<void>;
     /** Atomically replace the temporal capture integrity projection. */
-    writeSessionCapture(runDir: string, capture: WorkflowSessionCapture): Promise<void>;
+    writeSessionCapture(runDir: string, capture: WorkflowSessionCapture, attemptId?: string): Promise<void>;
     /** Count complete durable session records after both writers have drained. */
-    sessionCounts(runDir: string): Promise<{
+    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;
+    entries: WorkflowSessionEntryRecord[];
+    events: WorkflowSessionEventRecord[];
+    capture: WorkflowSessionCapture | null;
+    integrity: SessionCaptureIntegrity;
+};
 export type LoadedRunBundle = {
     runDir: string;
     manifest: WorkflowRunManifest;
@@ -71,7 +111,11 @@ export type LoadedRunBundle = {
     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>;
 /** Read a run bundle from disk. Returns null when the bundle is unreadable. */
 export declare function readRunBundle(runDir: string): Promise<LoadedRunBundle | null>;
 /** List run bundles under `outputRoot`, most recently started first. */