@hasna/loops 0.4.28 → 0.4.29

package/dist/lib/run-completion.d.ts

@@ -0,0 +1,18 @@
+export interface RunCompletionInput {
+    startedAt: string;
+    requestedFinishedAt?: string;
+    requestedDurationMs?: number;
+    serverNow: Date;
+}
+export interface NormalizedRunCompletion {
+    finishedAt: string;
+    durationMs: number | undefined;
+    updatedAt: string;
+}
+/**
+ * Treat the control-plane clock as authoritative while retaining a bounded
+ * runner timestamp as evidence. In the normal case, where startedAt is not
+ * ahead of the server clock, finishedAt is clamped into [startedAt, serverNow].
+ * A backwards server-clock jump fails safe at serverNow and yields duration 0.
+ */
+export declare function normalizeRunCompletion(input: RunCompletionInput): NormalizedRunCompletion;

package/dist/lib/scheduler.d.ts

@@ -1,5 +1,7 @@
 import type { ExecutorResult, Loop, LoopRun } from "../types.js";
+import { type CircuitBreakerThreshold } from "./advancement.js";
 import type { Store } from "./store.js";
+export { CIRCUIT_BREAKER_REASON_PREFIX, DEFAULT_CIRCUIT_BREAKER_THRESHOLD, MAX_RETRY_DELAY_MS, retryBackoffDelayMs, } from "./advancement.js";
 export interface SchedulerDeps {
     store: Store;
     runnerId: string;
@@ -25,6 +27,7 @@ export interface TickResult {
 export interface ClaimedLoopRun {
     loop: Loop;
     run: LoopRun;
+    claimToken: string;
 }
 export interface ClaimDueRunsResult extends TickResult {
     claims: ClaimedLoopRun[];
@@ -90,21 +93,11 @@ export declare function runLoopNow(deps: RunLoopNowDeps & {
 export declare function runLoopNow(deps: RunLoopNowDeps & {
     mode?: "inline";
 }): Promise<RunLoopNowExecuted>;
-export declare const MAX_RETRY_DELAY_MS: number;
-export declare const DEFAULT_CIRCUIT_BREAKER_THRESHOLD = 5;
-export declare const CIRCUIT_BREAKER_REASON_PREFIX = "circuit breaker open";
 export declare const MAX_SKIPS_PER_LOOP_PER_TICK = 10;
-/**
- * Exponential retry backoff with jitter:
- * delay = retryDelayMs * 2^(attempt-1) * (0.5 + random), capped at 6h.
- * Failures classified as provider-gated back off 4x harder, since hammering
- * a throttled, misconfigured, or unavailable provider only makes things worse.
- */
-export declare function retryBackoffDelayMs(loop: Loop, run: LoopRun, random?: () => number): number;
 export interface AdvanceLoopOptions {
     daemonLeaseId?: string;
     random?: () => number;
-    circuitBreakerThreshold?: number | ((loop: Loop) => number | undefined);
+    circuitBreakerThreshold?: CircuitBreakerThreshold;
     onRun?: (run: LoopRun) => void;
 }
 /**
@@ -123,6 +116,7 @@ export declare function advanceLoop(store: Store, loop: Loop, run: LoopRun, fini
 export declare function executeClaimedRun(deps: {
     store: Store;
     runnerId: string;
+    claimToken: string;
     loop: Loop;
     run: LoopRun;
     now?: () => Date;

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

@@ -1,6 +1,6 @@
 import type { Store } from "../store.js";
 export type LoopStorageBackend = "sqlite" | "postgres";
-export type LoopStorageMethodName = "createLoop" | "getLoop" | "findLoopByName" | "requireLoop" | "listLoops" | "dueLoops" | "updateLoop" | "renameLoop" | "archiveLoop" | "unarchiveLoop" | "deleteLoop" | "upsertMigrationLoop" | "upsertMigrationRun" | "upsertMigrationWorkflow" | "createWorkflow" | "getWorkflow" | "listWorkflows" | "countWorkflows" | "archiveWorkflow" | "createWorkflowInvocation" | "getWorkflowInvocation" | "listWorkflowInvocations" | "upsertWorkflowWorkItem" | "getWorkflowWorkItem" | "listWorkflowWorkItems" | "countActiveWorkflowWorkItems" | "admitWorkflowWorkItem" | "createGoal" | "getGoal" | "listGoals" | "createGoalPlanNodes" | "listGoalPlanNodes" | "updateGoalStatus" | "updateGoalPlanNode" | "recordGoalEvent" | "listGoalRuns" | "createWorkflowRun" | "getWorkflowRun" | "listWorkflowRuns" | "listWorkflowStepRuns" | "getWorkflowStepRun" | "startWorkflowStepRun" | "recoverWorkflowRun" | "finalizeWorkflowStepRun" | "finalizeWorkflowRun" | "appendWorkflowEvent" | "listWorkflowEvents" | "recordRunProcess" | "createSkippedRun" | "getRun" | "getRunBySlot" | "claimRun" | "finalizeRun" | "heartbeatRunLease" | "listRuns" | "writeRunReceipt" | "getRunReceipt" | "listRunReceipts" | "recoverExpiredRunLeases" | "recoverExpiredRunLeasesDetailed" | "countLoops" | "countRuns" | "pruneHistory" | "acquireDaemonLease" | "heartbeatDaemonLease" | "releaseDaemonLease" | "getDaemonLease";
+export type LoopStorageMethodName = "createLoop" | "getLoop" | "findLoopByName" | "requireLoop" | "requireUniqueLoop" | "listLoops" | "dueLoops" | "updateLoop" | "advanceLoopIfCurrent" | "tripCircuitBreakerIfCurrent" | "renameLoop" | "archiveLoop" | "unarchiveLoop" | "deleteLoop" | "upsertMigrationLoop" | "upsertMigrationRun" | "upsertMigrationWorkflow" | "createWorkflow" | "getWorkflow" | "requireWorkflow" | "listWorkflows" | "countWorkflows" | "archiveWorkflow" | "createWorkflowInvocation" | "getWorkflowInvocation" | "listWorkflowInvocations" | "upsertWorkflowWorkItem" | "getWorkflowWorkItem" | "listWorkflowWorkItems" | "countActiveWorkflowWorkItems" | "admitWorkflowWorkItem" | "createGoal" | "getGoal" | "requireGoal" | "findGoalByContext" | "listGoals" | "createGoalPlanNodes" | "listGoalPlanNodes" | "updateGoalStatus" | "updateGoalPlanNode" | "recordGoalEvent" | "listGoalRuns" | "createWorkflowRun" | "getWorkflowRun" | "requireWorkflowRun" | "listWorkflowRuns" | "listWorkflowStepRuns" | "getWorkflowStepRun" | "isWorkflowRunTerminal" | "startWorkflowStepRun" | "markWorkflowStepPid" | "recordWorkflowStepProgress" | "recoverWorkflowRun" | "finalizeWorkflowStepRun" | "skipWorkflowStepRun" | "finalizeWorkflowRun" | "appendWorkflowEvent" | "listWorkflowEvents" | "recordRunProcess" | "createSkippedRun" | "getRun" | "getRunBySlot" | "nextRetryableRun" | "claimRun" | "finalizeRun" | "heartbeatRunLease" | "listRuns" | "listRecoveredLeaseRunsPage" | "writeRunReceipt" | "getRunReceipt" | "listRunReceipts" | "recoverExpiredRunLeases" | "recoverExpiredRunLeasesDetailed" | "countLoops" | "countRuns" | "pruneHistory" | "acquireDaemonLease" | "heartbeatDaemonLease" | "releaseDaemonLease" | "getDaemonLease";
 type AsyncStoreMethod<K extends LoopStorageMethodName> = Store[K] extends (...args: infer Args) => infer Result ? (...args: Args) => Promise<Result> : never;
 export interface LoopStorageContract extends Record<LoopStorageMethodName, (...args: never[]) => Promise<unknown>> {
     readonly backend: LoopStorageBackend;
@@ -10,9 +10,12 @@ export interface LoopStorageContract extends Record<LoopStorageMethodName, (...a
     getLoop: AsyncStoreMethod<"getLoop">;
     findLoopByName: AsyncStoreMethod<"findLoopByName">;
     requireLoop: AsyncStoreMethod<"requireLoop">;
+    requireUniqueLoop: AsyncStoreMethod<"requireUniqueLoop">;
     listLoops: AsyncStoreMethod<"listLoops">;
     dueLoops: AsyncStoreMethod<"dueLoops">;
     updateLoop: AsyncStoreMethod<"updateLoop">;
+    advanceLoopIfCurrent: AsyncStoreMethod<"advanceLoopIfCurrent">;
+    tripCircuitBreakerIfCurrent: AsyncStoreMethod<"tripCircuitBreakerIfCurrent">;
     renameLoop: AsyncStoreMethod<"renameLoop">;
     archiveLoop: AsyncStoreMethod<"archiveLoop">;
     unarchiveLoop: AsyncStoreMethod<"unarchiveLoop">;
@@ -22,6 +25,7 @@ export interface LoopStorageContract extends Record<LoopStorageMethodName, (...a
     upsertMigrationWorkflow: AsyncStoreMethod<"upsertMigrationWorkflow">;
     createWorkflow: AsyncStoreMethod<"createWorkflow">;
     getWorkflow: AsyncStoreMethod<"getWorkflow">;
+    requireWorkflow: AsyncStoreMethod<"requireWorkflow">;
     listWorkflows: AsyncStoreMethod<"listWorkflows">;
     countWorkflows: AsyncStoreMethod<"countWorkflows">;
     archiveWorkflow: AsyncStoreMethod<"archiveWorkflow">;
@@ -35,6 +39,8 @@ export interface LoopStorageContract extends Record<LoopStorageMethodName, (...a
     admitWorkflowWorkItem: AsyncStoreMethod<"admitWorkflowWorkItem">;
     createGoal: AsyncStoreMethod<"createGoal">;
     getGoal: AsyncStoreMethod<"getGoal">;
+    requireGoal: AsyncStoreMethod<"requireGoal">;
+    findGoalByContext: AsyncStoreMethod<"findGoalByContext">;
     listGoals: AsyncStoreMethod<"listGoals">;
     createGoalPlanNodes: AsyncStoreMethod<"createGoalPlanNodes">;
     listGoalPlanNodes: AsyncStoreMethod<"listGoalPlanNodes">;
@@ -44,12 +50,17 @@ export interface LoopStorageContract extends Record<LoopStorageMethodName, (...a
     listGoalRuns: AsyncStoreMethod<"listGoalRuns">;
     createWorkflowRun: AsyncStoreMethod<"createWorkflowRun">;
     getWorkflowRun: AsyncStoreMethod<"getWorkflowRun">;
+    requireWorkflowRun: AsyncStoreMethod<"requireWorkflowRun">;
     listWorkflowRuns: AsyncStoreMethod<"listWorkflowRuns">;
     listWorkflowStepRuns: AsyncStoreMethod<"listWorkflowStepRuns">;
     getWorkflowStepRun: AsyncStoreMethod<"getWorkflowStepRun">;
+    isWorkflowRunTerminal: AsyncStoreMethod<"isWorkflowRunTerminal">;
     startWorkflowStepRun: AsyncStoreMethod<"startWorkflowStepRun">;
+    markWorkflowStepPid: AsyncStoreMethod<"markWorkflowStepPid">;
+    recordWorkflowStepProgress: AsyncStoreMethod<"recordWorkflowStepProgress">;
     recoverWorkflowRun: AsyncStoreMethod<"recoverWorkflowRun">;
     finalizeWorkflowStepRun: AsyncStoreMethod<"finalizeWorkflowStepRun">;
+    skipWorkflowStepRun: AsyncStoreMethod<"skipWorkflowStepRun">;
     finalizeWorkflowRun: AsyncStoreMethod<"finalizeWorkflowRun">;
     appendWorkflowEvent: AsyncStoreMethod<"appendWorkflowEvent">;
     listWorkflowEvents: AsyncStoreMethod<"listWorkflowEvents">;
@@ -57,10 +68,12 @@ export interface LoopStorageContract extends Record<LoopStorageMethodName, (...a
     createSkippedRun: AsyncStoreMethod<"createSkippedRun">;
     getRun: AsyncStoreMethod<"getRun">;
     getRunBySlot: AsyncStoreMethod<"getRunBySlot">;
+    nextRetryableRun: AsyncStoreMethod<"nextRetryableRun">;
     claimRun: AsyncStoreMethod<"claimRun">;
     finalizeRun: AsyncStoreMethod<"finalizeRun">;
     heartbeatRunLease: AsyncStoreMethod<"heartbeatRunLease">;
     listRuns: AsyncStoreMethod<"listRuns">;
+    listRecoveredLeaseRunsPage: AsyncStoreMethod<"listRecoveredLeaseRunsPage">;
     writeRunReceipt: AsyncStoreMethod<"writeRunReceipt">;
     getRunReceipt: AsyncStoreMethod<"getRunReceipt">;
     listRunReceipts: AsyncStoreMethod<"listRunReceipts">;
@@ -100,6 +113,7 @@ export interface SchemaMigrationStorage {
     listAppliedMigrations(): Promise<AppliedStorageMigration[]>;
     migrate(opts?: {
         dryRun?: boolean;
+        through?: string;
     }): Promise<StorageMigrationResult>;
     close(): Promise<void>;
 }

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

@@ -2,6 +2,6 @@ export type { AppliedStorageMigration, AuditEventRecord, LoopStorageBackend, Loo
 export { SqliteLoopStorage, createSqliteLoopStorage } from "./sqlite.js";
 export { PostgresStorage, createPostgresStorage } from "./postgres.js";
 export type { PostgresQueryExecutor } from "./postgres.js";
-export { PostgresLoopStorage, createPostgresLoopStorage, NotImplementedError, } from "./postgres-loop-storage.js";
+export { PostgresLoopStorage, createPostgresLoopStorage, } from "./postgres-loop-storage.js";
 export { POSTGRES_MIGRATION_LEDGER_TABLE, POSTGRES_STORAGE_MIGRATIONS, checksumStorageSql, } from "./postgres-schema.js";
 export { Store } from "../store.js";