@hasna/loops 0.4.13 → 0.4.22

package/dist/lib/storage/pg-executor.d.ts

@@ -0,0 +1,27 @@
+import type { PoolQueryClient } from "../../generated/storage-kit/query.js";
+import type { PostgresQueryExecutor } from "./postgres.js";
+export interface PgExecutorOptions {
+    connectionString: string;
+    max?: number;
+    applicationName?: string;
+    connectionTimeoutMillis?: number;
+    idleTimeoutMillis?: number;
+}
+/**
+ * `PostgresQueryExecutor` backed by a live `pg.Pool` via the vendored kit.
+ *
+ * Transaction support is intentionally omitted: `PostgresStorage.migrate`
+ * treats DDL as idempotent (`CREATE ... IF NOT EXISTS` + a checksum ledger), so
+ * a pooled sequential apply is correct and avoids binding every inner
+ * `execute` to a single dedicated client.
+ */
+export declare class PgPoolExecutor implements PostgresQueryExecutor {
+    private readonly client;
+    constructor(client: PoolQueryClient);
+    static fromConnectionString(options: PgExecutorOptions): PgPoolExecutor;
+    /** The underlying typed query client, for callers that need `get`/`one`/`transaction`. */
+    get queryClient(): PoolQueryClient;
+    query<T extends Record<string, unknown>>(sql: string, params?: readonly unknown[]): Promise<T[]>;
+    execute(sql: string, params?: readonly unknown[]): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/lib/storage/pg-runner-claim.d.ts

@@ -0,0 +1,40 @@
+import type { PoolQueryClient } from "../../generated/storage-kit/query.js";
+export interface ClaimedRunRow extends Record<string, unknown> {
+    id: string;
+    loop_id: string;
+    loop_name: string;
+    scheduled_for: string | Date;
+    attempt: number;
+    status: string;
+    claimed_by: string | null;
+    claim_token: string | null;
+    lease_expires_at: string | Date | null;
+}
+export interface ClaimNextRunOptions {
+    runnerId: string;
+    leaseMs: number;
+    claimToken: string;
+    /** Statuses a run may be in to be claimable. Defaults to queued + lease-expired running. */
+    now?: Date;
+}
+/**
+ * Atomically claim the next claimable run for `runnerId`.
+ *
+ * A run is claimable when it is `queued`, or `running` with an expired lease
+ * (crash recovery). Returns the claimed row, or `null` when nothing was
+ * available. Two concurrent callers are guaranteed to receive distinct rows
+ * (or one receives `null`) thanks to `FOR UPDATE SKIP LOCKED`.
+ */
+export declare function claimNextRun(client: PoolQueryClient, options: ClaimNextRunOptions): Promise<ClaimedRunRow | null>;
+/**
+ * Heartbeat a claimed run's lease. Returns true when the lease was extended
+ * (the caller still owns the run), false when ownership was lost (claim token
+ * mismatch, run finalized, or lease already stolen).
+ */
+export declare function heartbeatRunLease(client: PoolQueryClient, input: {
+    runId: string;
+    runnerId: string;
+    claimToken: string;
+    leaseMs: number;
+    now?: Date;
+}): Promise<boolean>;

package/dist/lib/storage/postgres-loop-storage.d.ts

@@ -0,0 +1,120 @@
+import type { RecoverExpiredRunLeasesResult } from "../store.js";
+import { Store } from "../store.js";
+import type { PoolQueryClient } from "../../generated/storage-kit/query.js";
+import type { LoopStorageContract, LoopStorageMethodName } from "./contract.js";
+/** Thrown by store methods that are not yet ported to the Postgres backend. */
+export declare class NotImplementedError extends Error {
+    readonly code = "not_implemented";
+    constructor(method: string);
+}
+type M<K extends LoopStorageMethodName> = Store[K] extends (...a: infer A) => infer R ? {
+    args: A;
+    result: R;
+} : never;
+export declare class PostgresLoopStorage implements LoopStorageContract {
+    private readonly client;
+    readonly backend = "postgres";
+    readonly supportsRemoteRunners = true;
+    constructor(client: PoolQueryClient);
+    close(): Promise<void>;
+    private assertDaemonLeaseFence;
+    private loadLoop;
+    private loadRun;
+    private loadRunBySlot;
+    private loadDaemonLease;
+    private setWorkItemsForLoop;
+    private setWorkItemsForWorkflowRun;
+    private cascadeWorkItemsForLoopRun;
+    createLoop(...args: M<"createLoop">["args"]): Promise<M<"createLoop">["result"]>;
+    getLoop(...args: M<"getLoop">["args"]): Promise<M<"getLoop">["result"]>;
+    findLoopByName(...args: M<"findLoopByName">["args"]): Promise<M<"findLoopByName">["result"]>;
+    requireLoop(...args: M<"requireLoop">["args"]): Promise<M<"requireLoop">["result"]>;
+    listLoops(...args: M<"listLoops">["args"]): Promise<M<"listLoops">["result"]>;
+    dueLoops(...args: M<"dueLoops">["args"]): Promise<M<"dueLoops">["result"]>;
+    updateLoop(...args: M<"updateLoop">["args"]): Promise<M<"updateLoop">["result"]>;
+    renameLoop(...args: M<"renameLoop">["args"]): Promise<M<"renameLoop">["result"]>;
+    archiveLoop(...args: M<"archiveLoop">["args"]): Promise<M<"archiveLoop">["result"]>;
+    unarchiveLoop(...args: M<"unarchiveLoop">["args"]): Promise<M<"unarchiveLoop">["result"]>;
+    deleteLoop(...args: M<"deleteLoop">["args"]): Promise<M<"deleteLoop">["result"]>;
+    private requireLoopIn;
+    countLoops(...args: M<"countLoops">["args"]): Promise<M<"countLoops">["result"]>;
+    upsertMigrationWorkflow(...args: M<"upsertMigrationWorkflow">["args"]): Promise<M<"upsertMigrationWorkflow">["result"]>;
+    upsertMigrationLoop(...args: M<"upsertMigrationLoop">["args"]): Promise<M<"upsertMigrationLoop">["result"]>;
+    upsertMigrationRun(...args: M<"upsertMigrationRun">["args"]): Promise<M<"upsertMigrationRun">["result"]>;
+    createSkippedRun(...args: M<"createSkippedRun">["args"]): Promise<M<"createSkippedRun">["result"]>;
+    getRun(...args: M<"getRun">["args"]): Promise<M<"getRun">["result"]>;
+    getRunBySlot(...args: M<"getRunBySlot">["args"]): Promise<M<"getRunBySlot">["result"]>;
+    /**
+     * Claim a specific loop slot for a runner.
+     *
+     * Divergence from the sqlite Store (documented, not accidental): the sqlite
+     * path also consults LOCAL process liveness (`isRecordedProcessAlive`,
+     * `hasLiveWorkflowStepProcesses`) before stealing an expired-lease run,
+     * because the daemon and the run's child process share a host. On the
+     * Postgres/remote backend the claiming runner may be a different machine than
+     * the one that holds the (possibly still-live) process, so local pid checks
+     * are meaningless. Ownership here is governed purely by lease expiry: an
+     * expired lease is reclaimable, a live lease is not. The lease/heartbeat
+     * contract (plus `FOR UPDATE` row locks) is the remote correctness boundary.
+     */
+    claimRun(...args: M<"claimRun">["args"]): Promise<M<"claimRun">["result"]>;
+    finalizeRun(...args: M<"finalizeRun">["args"]): Promise<M<"finalizeRun">["result"]>;
+    heartbeatRunLease(...args: M<"heartbeatRunLease">["args"]): Promise<M<"heartbeatRunLease">["result"]>;
+    recordRunProcess(...args: M<"recordRunProcess">["args"]): Promise<M<"recordRunProcess">["result"]>;
+    listRuns(...args: M<"listRuns">["args"]): Promise<M<"listRuns">["result"]>;
+    writeRunReceipt(...args: M<"writeRunReceipt">["args"]): Promise<M<"writeRunReceipt">["result"]>;
+    getRunReceipt(...args: M<"getRunReceipt">["args"]): Promise<M<"getRunReceipt">["result"]>;
+    listRunReceipts(...args: M<"listRunReceipts">["args"]): Promise<M<"listRunReceipts">["result"]>;
+    countRuns(...args: M<"countRuns">["args"]): Promise<M<"countRuns">["result"]>;
+    recoverExpiredRunLeases(...args: M<"recoverExpiredRunLeases">["args"]): Promise<M<"recoverExpiredRunLeases">["result"]>;
+    /**
+     * Recover expired run leases. Divergence from sqlite (documented): the remote
+     * backend cannot inspect local process liveness, so an expired lease is always
+     * abandoned (never "deferred because the local process is still alive"). The
+     * `deferred` array is therefore always empty here. The generated-route
+     * workflow archival side effect is not ported (route automation is a TIER 2
+     * path); the core guarantee — no run stays `running` past its lease — holds.
+     */
+    recoverExpiredRunLeasesDetailed(...args: M<"recoverExpiredRunLeasesDetailed">["args"]): Promise<RecoverExpiredRunLeasesResult>;
+    pruneHistory(...args: M<"pruneHistory">["args"]): Promise<M<"pruneHistory">["result"]>;
+    acquireDaemonLease(...args: M<"acquireDaemonLease">["args"]): Promise<M<"acquireDaemonLease">["result"]>;
+    heartbeatDaemonLease(...args: M<"heartbeatDaemonLease">["args"]): Promise<M<"heartbeatDaemonLease">["result"]>;
+    releaseDaemonLease(...args: M<"releaseDaemonLease">["args"]): Promise<M<"releaseDaemonLease">["result"]>;
+    getDaemonLease(...args: M<"getDaemonLease">["args"]): Promise<M<"getDaemonLease">["result"]>;
+    private loadWorkflow;
+    getWorkflow(...args: M<"getWorkflow">["args"]): Promise<M<"getWorkflow">["result"]>;
+    listWorkflows(...args: M<"listWorkflows">["args"]): Promise<M<"listWorkflows">["result"]>;
+    countWorkflows(...args: M<"countWorkflows">["args"]): Promise<M<"countWorkflows">["result"]>;
+    getWorkflowInvocation(...args: M<"getWorkflowInvocation">["args"]): Promise<M<"getWorkflowInvocation">["result"]>;
+    listWorkflowInvocations(...args: M<"listWorkflowInvocations">["args"]): Promise<M<"listWorkflowInvocations">["result"]>;
+    getWorkflowWorkItem(...args: M<"getWorkflowWorkItem">["args"]): Promise<M<"getWorkflowWorkItem">["result"]>;
+    listWorkflowWorkItems(...args: M<"listWorkflowWorkItems">["args"]): Promise<M<"listWorkflowWorkItems">["result"]>;
+    countActiveWorkflowWorkItems(...args: M<"countActiveWorkflowWorkItems">["args"]): Promise<M<"countActiveWorkflowWorkItems">["result"]>;
+    getWorkflowRun(...args: M<"getWorkflowRun">["args"]): Promise<M<"getWorkflowRun">["result"]>;
+    listWorkflowRuns(...args: M<"listWorkflowRuns">["args"]): Promise<M<"listWorkflowRuns">["result"]>;
+    listWorkflowStepRuns(...args: M<"listWorkflowStepRuns">["args"]): Promise<M<"listWorkflowStepRuns">["result"]>;
+    getWorkflowStepRun(...args: M<"getWorkflowStepRun">["args"]): Promise<M<"getWorkflowStepRun">["result"]>;
+    listWorkflowEvents(...args: M<"listWorkflowEvents">["args"]): Promise<M<"listWorkflowEvents">["result"]>;
+    getGoal(...args: M<"getGoal">["args"]): Promise<M<"getGoal">["result"]>;
+    listGoals(...args: M<"listGoals">["args"]): Promise<M<"listGoals">["result"]>;
+    listGoalPlanNodes(...args: M<"listGoalPlanNodes">["args"]): Promise<M<"listGoalPlanNodes">["result"]>;
+    listGoalRuns(...args: M<"listGoalRuns">["args"]): Promise<M<"listGoalRuns">["result"]>;
+    createWorkflow(): never;
+    archiveWorkflow(): never;
+    createWorkflowInvocation(): never;
+    upsertWorkflowWorkItem(): never;
+    admitWorkflowWorkItem(): never;
+    createGoal(): never;
+    createGoalPlanNodes(): never;
+    updateGoalStatus(): never;
+    updateGoalPlanNode(): never;
+    recordGoalEvent(): never;
+    createWorkflowRun(): never;
+    startWorkflowStepRun(): never;
+    recoverWorkflowRun(): never;
+    finalizeWorkflowStepRun(): never;
+    finalizeWorkflowRun(): never;
+    appendWorkflowEvent(): never;
+}
+export declare function createPostgresLoopStorage(client: PoolQueryClient): PostgresLoopStorage;
+export {};

package/dist/lib/storage/postgres-schema.js

@@ -323,6 +323,35 @@ CREATE INDEX IF NOT EXISTS idx_audit_events_action ON audit_events(action, creat
   migration("0004_work_item_route_scope", `
 ALTER TABLE workflow_work_items ADD COLUMN IF NOT EXISTS route_scope TEXT;
 CREATE INDEX IF NOT EXISTS idx_workflow_work_items_scope ON workflow_work_items(route_scope, status);
+    `),
+  migration("0005_run_receipts", `
+CREATE TABLE IF NOT EXISTS run_receipts (
+  run_id TEXT PRIMARY KEY,
+  loop_id TEXT NOT NULL,
+  machine_json JSONB NOT NULL,
+  repo TEXT NOT NULL,
+  task_ids_json JSONB NOT NULL,
+  knowledge_ids_json JSONB NOT NULL,
+  digest_id TEXT NOT NULL,
+  started_at TIMESTAMPTZ,
+  finished_at TIMESTAMPTZ,
+  status TEXT NOT NULL,
+  exit_code INTEGER,
+  summary_json JSONB NOT NULL,
+  evidence_paths_json JSONB NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL,
+  updated_at TIMESTAMPTZ NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_run_receipts_loop ON run_receipts(loop_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_run_receipts_repo ON run_receipts(repo, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_run_receipts_digest ON run_receipts(digest_id);
+CREATE INDEX IF NOT EXISTS idx_run_receipts_status ON run_receipts(status, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_run_receipts_task_ids ON run_receipts USING GIN (task_ids_json);
+CREATE INDEX IF NOT EXISTS idx_run_receipts_knowledge_ids ON run_receipts USING GIN (knowledge_ids_json);
+    `),
+  migration("0006_work_item_machine_id", `
+ALTER TABLE workflow_work_items ADD COLUMN IF NOT EXISTS machine_id TEXT;
+CREATE INDEX IF NOT EXISTS idx_workflow_work_items_machine ON workflow_work_items(machine_id, status);
     `)
 ]);
 export {

package/dist/lib/storage/postgres.js

@@ -323,6 +323,35 @@ CREATE INDEX IF NOT EXISTS idx_audit_events_action ON audit_events(action, creat
   migration("0004_work_item_route_scope", `
 ALTER TABLE workflow_work_items ADD COLUMN IF NOT EXISTS route_scope TEXT;
 CREATE INDEX IF NOT EXISTS idx_workflow_work_items_scope ON workflow_work_items(route_scope, status);
+    `),
+  migration("0005_run_receipts", `
+CREATE TABLE IF NOT EXISTS run_receipts (
+  run_id TEXT PRIMARY KEY,
+  loop_id TEXT NOT NULL,
+  machine_json JSONB NOT NULL,
+  repo TEXT NOT NULL,
+  task_ids_json JSONB NOT NULL,
+  knowledge_ids_json JSONB NOT NULL,
+  digest_id TEXT NOT NULL,
+  started_at TIMESTAMPTZ,
+  finished_at TIMESTAMPTZ,
+  status TEXT NOT NULL,
+  exit_code INTEGER,
+  summary_json JSONB NOT NULL,
+  evidence_paths_json JSONB NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL,
+  updated_at TIMESTAMPTZ NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_run_receipts_loop ON run_receipts(loop_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_run_receipts_repo ON run_receipts(repo, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_run_receipts_digest ON run_receipts(digest_id);
+CREATE INDEX IF NOT EXISTS idx_run_receipts_status ON run_receipts(status, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_run_receipts_task_ids ON run_receipts USING GIN (task_ids_json);
+CREATE INDEX IF NOT EXISTS idx_run_receipts_knowledge_ids ON run_receipts USING GIN (knowledge_ids_json);
+    `),
+  migration("0006_work_item_machine_id", `
+ALTER TABLE workflow_work_items ADD COLUMN IF NOT EXISTS machine_id TEXT;
+CREATE INDEX IF NOT EXISTS idx_workflow_work_items_machine ON workflow_work_items(machine_id, status);
     `)
 ]);
 

package/dist/lib/storage/sqlite.d.ts

@@ -22,6 +22,9 @@ export declare class SqliteLoopStorage implements LoopStorageContract {
     archiveLoop(...args: StoreMethod<"archiveLoop">["args"]): Promise<import("../../types.js").Loop>;
     unarchiveLoop(...args: StoreMethod<"unarchiveLoop">["args"]): Promise<import("../../types.js").Loop>;
     deleteLoop(...args: StoreMethod<"deleteLoop">["args"]): Promise<boolean>;
+    upsertMigrationLoop(...args: StoreMethod<"upsertMigrationLoop">["args"]): Promise<import("../../types.js").Loop>;
+    upsertMigrationRun(...args: StoreMethod<"upsertMigrationRun">["args"]): Promise<import("../../types.js").LoopRun>;
+    upsertMigrationWorkflow(...args: StoreMethod<"upsertMigrationWorkflow">["args"]): Promise<import("../../types.js").WorkflowSpec>;
     createWorkflow(...args: StoreMethod<"createWorkflow">["args"]): Promise<import("../../types.js").WorkflowSpec>;
     getWorkflow(...args: StoreMethod<"getWorkflow">["args"]): Promise<import("../../types.js").WorkflowSpec | undefined>;
     listWorkflows(...args: StoreMethod<"listWorkflows">["args"]): Promise<import("../../types.js").WorkflowSpec[]>;
@@ -70,6 +73,9 @@ export declare class SqliteLoopStorage implements LoopStorageContract {
     finalizeRun(...args: StoreMethod<"finalizeRun">["args"]): Promise<import("../../types.js").LoopRun>;
     heartbeatRunLease(...args: StoreMethod<"heartbeatRunLease">["args"]): Promise<import("../../types.js").LoopRun | undefined>;
     listRuns(...args: StoreMethod<"listRuns">["args"]): Promise<import("../../types.js").LoopRun[]>;
+    writeRunReceipt(...args: StoreMethod<"writeRunReceipt">["args"]): Promise<import("../../types.js").RunReceipt>;
+    getRunReceipt(...args: StoreMethod<"getRunReceipt">["args"]): Promise<import("../../types.js").RunReceipt | undefined>;
+    listRunReceipts(...args: StoreMethod<"listRunReceipts">["args"]): Promise<import("../../types.js").RunReceipt[]>;
     recoverExpiredRunLeases(...args: StoreMethod<"recoverExpiredRunLeases">["args"]): Promise<import("../../types.js").LoopRun[]>;
     recoverExpiredRunLeasesDetailed(...args: StoreMethod<"recoverExpiredRunLeasesDetailed">["args"]): Promise<import("../store.js").RecoverExpiredRunLeasesResult>;
     countLoops(...args: StoreMethod<"countLoops">["args"]): Promise<number>;