@osolmaz/pi-workflows 0.2.0 → 0.4.0

package/dist/controllers/sqlite.d.ts

@@ -0,0 +1,235 @@
+import { type ControllerStore, type EffectReservation, type QueueItem, type QueueRequeueOptions, type WorkflowRecordUpdate, type WorkflowReservation } from "./store.js";
+import type { ChildWorkflowRecord, ControllerEvent, ControllerQueueClaim, ControllerResource, ControllerResourceRef, ControllerResourceStatus, EffectRecord, JsonObject } from "./types.js";
+/** A user-started workflow run tracked by the durable run queue. */
+export type WorkflowRunQueueRecord = {
+    runId: string;
+    /** Human-readable workflow name used in status and event output. */
+    workflowName: string;
+    /** Canonical source reference used to reopen the run. */
+    workflowSourceRef: string;
+    input: unknown;
+    status: "claimed" | "parked" | "done";
+    runnerId: string | null;
+    claimToken: string | null;
+    claimExpiresAt: string | null;
+    affinityRunnerId: string | null;
+    parentRunId: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+/** One run lifecycle transition in the cross-session event feed. */
+export type RunEventRecord = {
+    seq: number;
+    recordedAt: string;
+    runId: string;
+    workflowRef: string;
+    type: string;
+    runnerId: string | null;
+    payload: JsonObject;
+};
+export declare class SqliteControllerStore implements ControllerStore {
+    readonly filePath: string;
+    private readonly database;
+    private closed;
+    constructor(filePath?: string, options?: {
+        readOnly?: boolean;
+    });
+    close(): void;
+    putResource<TSpec, TStatus>(options: {
+        controller: string;
+        key: string;
+        spec: TSpec;
+        initialStatus: TStatus;
+        now?: string;
+    }): ControllerResource<TSpec, TStatus>;
+    getResource<TSpec = unknown, TStatus = unknown>(ref: ControllerResourceRef): ControllerResource<TSpec, TStatus> | undefined;
+    getResourceByUid(uid: string): ControllerResource | undefined;
+    listResources<TSpec = unknown, TStatus = unknown>(options?: {
+        controller?: string;
+    }): ControllerResource<TSpec, TStatus>[];
+    updateStatus<TStatus>(options: {
+        ref: ControllerResourceRef;
+        expectedResourceVersion: number;
+        status: ControllerResourceStatus<TStatus>;
+        finalizers?: string[];
+        now?: string;
+    }): ControllerResource<unknown, TStatus>;
+    requestDeletion(ref: ControllerResourceRef, now?: string): ControllerResource;
+    updateFinalizers(options: {
+        ref: ControllerResourceRef;
+        expectedResourceVersion: number;
+        finalizers: string[];
+        now?: string;
+    }): ControllerResource;
+    deleteResource(ref: ControllerResourceRef, expectedResourceVersion: number): boolean;
+    enqueue(ref: ControllerResourceRef, availableAt?: string): void;
+    claimNext(options: {
+        controllers: string[];
+        leaseMs: number;
+        now?: string;
+    }): ControllerQueueClaim | undefined;
+    renewClaim(claim: ControllerQueueClaim, leaseMs: number, now?: string): boolean;
+    settleClaim(claim: ControllerQueueClaim, now?: string): boolean;
+    requeueClaim(claim: ControllerQueueClaim, options: QueueRequeueOptions, _now?: string): boolean;
+    listQueue(): QueueItem[];
+    reserveEffect(options: {
+        key: string;
+        resourceUid: string;
+        generation: number;
+        kind: string;
+        requestFingerprint: string;
+        now?: string;
+    }): EffectReservation;
+    getEffect(resourceUid: string, key: string): EffectRecord | undefined;
+    updateEffect(options: {
+        resourceUid: string;
+        key: string;
+        state: EffectRecord["state"];
+        externalRef?: string;
+        error?: string;
+        now?: string;
+    }): EffectRecord;
+    listEffects(resourceUid: string): EffectRecord[];
+    reserveWorkflow(options: {
+        resourceUid: string;
+        requestKey: string;
+        workflow: string;
+        inputFingerprint: string;
+    }): WorkflowReservation;
+    getWorkflow(resourceUid: string, requestKey: string): ChildWorkflowRecord | undefined;
+    getWorkflowByRequestId(requestId: string): ChildWorkflowRecord | undefined;
+    updateWorkflow(requestId: string, update: WorkflowRecordUpdate): ChildWorkflowRecord;
+    listWorkflows(resourceUid: string): ChildWorkflowRecord[];
+    recordEvent(options: {
+        controller: string;
+        key: string;
+        type: string;
+        payload?: JsonObject;
+        now?: string;
+    }): ControllerEvent;
+    listEvents(options?: {
+        controller?: string;
+        key?: string;
+        limit?: number;
+    }): ControllerEvent[];
+    private configure;
+    private initializeSchema;
+    private transaction;
+    private resourceRow;
+    private requireResource;
+    private throwMissingOrConflict;
+    private enqueueRow;
+    private claimedRow;
+    private effectRow;
+    private requireEffect;
+    private workflowRow;
+    private requireWorkflow;
+    /**
+     * Insert a user-started run and claim it in one statement, so the
+     * originating runner owns the run from birth (origin affinity).
+     */
+    enqueueWorkflowRun(options: {
+        runId: string;
+        workflowName: string;
+        workflowSourceRef: string;
+        input: unknown;
+        runnerId: string;
+        claimToken: string;
+        leaseMs: number;
+        affinityRunnerId?: string;
+        parentRunId?: string;
+        now?: string;
+    }): WorkflowRunQueueRecord;
+    getWorkflowRun(runId: string): WorkflowRunQueueRecord | undefined;
+    listWorkflowRuns(options?: {
+        status?: WorkflowRunQueueRecord["status"];
+    }): WorkflowRunQueueRecord[];
+    /**
+     * Claim the oldest claimable run, preferring runs with affinity to this
+     * runner. Parked rows are claimable immediately; claimed rows become
+     * claimable once their lease expires, so a dead or stalled runner never
+     * strands a run. Returns undefined when nothing is claimable.
+     */
+    claimNextWorkflowRun(options: {
+        runnerId: string;
+        claimToken: string;
+        leaseMs: number;
+        excludeRunIds?: string[];
+        now?: string;
+    }): WorkflowRunQueueRecord | undefined;
+    /** Extend a live claim. Rejects expired or foreign claims. */
+    renewWorkflowRunClaim(options: {
+        runId: string;
+        claimToken: string;
+        leaseMs: number;
+        now?: string;
+    }): boolean;
+    /** The fence check: true only while this exact claim is live. */
+    verifyWorkflowRunClaim(options: {
+        runId: string;
+        claimToken: string;
+        now?: string;
+    }): boolean;
+    /** Release a claim and park the run so another runner can resume it. */
+    parkWorkflowRun(options: {
+        runId: string;
+        claimToken: string;
+        now?: string;
+    }): boolean;
+    /**
+     * Delete a claimed row. Used when a continuation fails before its bundle
+     * exists, so the parent's one-continuation slot is not consumed by a run
+     * that never happened.
+     */
+    deleteWorkflowRun(options: {
+        runId: string;
+        claimToken: string;
+    }): boolean;
+    /** Release a claim and mark the run terminal in the queue. */
+    completeWorkflowRun(options: {
+        runId: string;
+        claimToken: string;
+        now?: string;
+    }): boolean;
+    /** Repair a canonical bundle's queue source and claim it only when needed. */
+    repairCanonicalWorkflowSourceRun(options: {
+        runId: string;
+        workflowName: string;
+        workflowSourceRef: string;
+        runnerId: string;
+        claimToken: string;
+        leaseMs: number;
+        now?: string;
+    }): "unchanged" | "claimed" | false;
+    /** Claim and rewrite one proved legacy workflow source queue row atomically. */
+    claimLegacyWorkflowSourceRun(options: {
+        runId: string;
+        workflowName: string;
+        oldWorkflowPath: string;
+        workflowSourceRef: string;
+        runnerId: string;
+        claimToken: string;
+        leaseMs: number;
+        now?: string;
+    }): boolean;
+    /** Append a run lifecycle transition to the event feed. */
+    recordRunEvent(options: {
+        runId: string;
+        workflowRef: string;
+        type: string;
+        runnerId?: string;
+        payload?: JsonObject;
+        now?: string;
+    }): number;
+    /** List run events after a watermark, oldest first. */
+    listRunEventsAfter(seq: number, options?: {
+        limit?: number;
+    }): RunEventRecord[];
+    /** The highest run event seq in the feed; 0 when empty. */
+    latestRunEventSeq(): number;
+    /** The last run event this session was told about; 0 before any sync. */
+    getSessionWatermark(sessionId: string): number;
+    setSessionWatermark(sessionId: string, seq: number, now?: string): void;
+    private requireWorkflowRun;
+    private requireEvent;
+}