@fungi.computer/watchdog 0.1.0 → 0.1.1

package/README.md

@@ -7,8 +7,8 @@ asks your liveness probe what happened and recovers the work.
 
 Watchdog never looks inside a job. The payload, queue name and lane are opaque
 values you choose. Your code decides what a job means and how to run it.
-Watchdog owns the lifecycle: queued, running, settled. Claims, claim tokens and
-the SQL that moves rows between states stay private to the package.
+Watchdog owns the lifecycle: queued, running, completing, settled. Claims, claim
+tokens and the SQL that moves rows between states stay private to the package.
 
 Use it when you need work to survive a restart, run once per claim, and settle
 with an honest outcome, without writing your own state machine. It runs on any
@@ -23,8 +23,8 @@ npm install @fungi.computer/watchdog
 
 Watchdog is ESM-only. The SQLite entrypoint runs anywhere you have a synchronous
 SQLite handle, such as Cloudflare Durable Object storage or `node:sqlite` in
-Node 24. It depends on `effect`, `pg` and `@cloudflare/workers-types`, which npm
-installs for you.
+Node 24. Its runtime dependencies include Cairn, `effect`, `pg`, `@types/pg` and
+`@cloudflare/workers-types`, which npm installs for you.
 
 Entrypoints:
 
@@ -95,13 +95,15 @@ In a Durable Object, `ctx.storage` is already the SQLite owner.
 ## Core concepts
 
 **Jobs.** A job has a `jobId`, a `queue`, a `lane`, an integer `priority`, an
-opaque JSON `payload` and an optional `recovery: { maxRecoveries }`. IDs and
-queue names are 1 to 256 characters; lanes are 1 to 512 characters. Owner-local
-construction can reserve one lane for concurrent delivery; otherwise the lane is
-stored without a scheduling policy. A job moves through three states:
+opaque JSON `payload` and an optional `recovery: { maxRecoveries, windowMs? }`.
+IDs and queue names are 1 to 256 characters; lanes are 1 to 512 characters.
+Owner-local construction can reserve one lane for concurrent delivery; otherwise
+the lane is stored without a scheduling policy. A job moves through four states:
 
 - `queued`: accepted and waiting.
 - `running`: claimed by one tick and handed to your executor.
+- `completing`: execution decided its outcome; settlement and its projection are
+  pending.
 - `settled`: finished, with an `outcome` of `completed`, `failed`, `cancelled`,
   `outcome_unknown` or `interrupted`, and an optional `failureReason`.
 
@@ -125,25 +127,50 @@ as `execution_failed` or `execution_interrupted`.
 - `isAlive(job)`: answers whether a running job's execution still exists.
 - `wake.recompute()`: arms your next timer or alarm after durable state changes.
 
-**Disappearance recovery.** Each tick first checks the oldest running claim. If
-`isAlive` returns `false`, the execution is gone. A job with recovery budget
-left goes back to `queued`. Otherwise it settles as `interrupted`. If `isAlive`
-throws, Watchdog does not guess. The claim stays as it is, and an otherwise idle
-tick reports `{ status: "liveness_unknown", jobId, reason }`.
+**Completion recovery.** An exact claim first records its outcome as
+`completing`. A separate transaction settles that decision and invokes the owner
+projection. If this transaction fails, the decision remains durable. Each tick
+retries one pending completion before taking new work. Failure surfaces
+immediately; the host owns bounded wake backoff. A restart never executes
+completing work again, probes its liveness or charges its recovery budget. Queue
+heads report it as `running` until settlement commits; `read(jobId)` reports
+`completing`.
+
+**Disappearance recovery.** After pending completion, a tick checks the oldest
+running claim. If `isAlive` returns `false`, the execution is gone. A job with
+recovery budget left goes back to `queued`. Otherwise it settles as
+`interrupted`. If `isAlive` throws, Watchdog does not guess. The claim stays as
+it is, and an otherwise idle tick reports
+`{ status: "liveness_unknown", jobId, reason }`.
+
+An optional positive `windowMs` resets the count when that much time has elapsed
+since the first charged recovery in the current window. Clock rollback does not
+reset it. Without a window, the count remains a lifetime budget for that job.
+
+**Effect owner shutdown.** The Effect runtime's `close` stops dispatch and
+interrupts its owned execution. After the executor scope ends, `isDrained(job)`
+must prove that foreign cleanup completed. Only then does Watchdog requeue its
+exact claim without charging recovery. An absent or false drain answer leaves
+the claim running and fails with `drain_failed`; reopening treats it as an
+unexpected disappearance. Durable cancellation wins over the handoff. An
+already-decided completion continues settlement. Further ticks return `stopped`.
+The production caller is Shiitake, whose run scope supplies bounded model/tool
+cleanup evidence. Promise runtimes do not expose this lifecycle operation.
 
 **Cancellation.** `cancel({ jobId, cancellationId })` records a durable
 cancellation. A queued job settles as `cancelled` on its next tick. A job the
 current runtime is executing is interrupted and settles as `cancelled`.
 Replaying the same `cancellationId` returns `replayed`. A different one returns
-`conflict`. Pass `onlyIfQueued: true` to refuse cancellation once a job has
-started.
-
-**Lane refusal.** `failLane({ lane, reason })` terminally settles queued and
-running work in that lane as `failed`, retaining each job and its bounded owner
-reason code. It handles at most 256 jobs per call, running jobs first, and
-returns `{ settled, more }`. Repeat only while `more` is true; 256 is a
-transition batch, not a cap on accepted work. Already settled history and other
-lanes stay intact. Once exhausted, another call returns
+`conflict`. Once execution has durably decided, cancellation is a no-op and
+returns `{ status: "decided", outcome }`, including after settlement. Pass
+`onlyIfQueued: true` to refuse cancellation once a job has started.
+
+**Lane refusal.** `failLane({ lane, reason })` terminally settles queued,
+running and completing work in that lane as `failed`, retaining each job and its
+bounded owner reason code. It handles at most 256 jobs per call, running jobs
+first, and returns `{ settled, more }`. Repeat only while `more` is true; 256 is
+a transition batch, not a cap on accepted work. Already settled history and
+other lanes stay intact. Once exhausted, another call returns
 `{ settled: 0, more: false }` and fires no projector. A later enqueue is new
 work, not a permanent refusal marker.
 
@@ -171,8 +198,25 @@ ingest, claim, cancellation, settlement, lane refusal, recovery and purge. Use
 it to keep a per-queue status row in step with Watchdog. A throw from `project`
 fails the transition.
 
-**Purge.** `purge(queue)` deletes every queued job in one queue. Running and
-settled jobs stay.
+**Purge.** `purge(queue)` deletes every queued job in one queue. Running,
+completing and settled jobs stay.
+
+## Scheduled work and delivery attempts
+
+A queued job may carry `notBefore`, an absolute millisecond deadline. Watchdog
+retains it as `not_before`; future queue heads hold their successors while
+independent queues proceed. `wakeState(now)` returns `{ pending, nextWakeAt }`
+from the same rows, including shared leases. Cancellation bypasses a future due
+time. Hosts schedule now when `pending` is true, otherwise at `nextWakeAt`.
+
+An executor may supply a code-owned `retryPolicy` with bounded backoff and
+either an attempt ceiling or absolute deadline. Watchdog increments
+`attempt_count` and records the fallback due time before execution. The executor
+receives the reserved attempt, returns `retry` to retain the same work, and
+receives an exhausted context without another receiver attempt when the budget
+ends. Delivery disappearance retains that charge and does not borrow Agent
+recovery quotas. The native Effect executor's `replaySafe` predicate is for work
+whose entire effect is one owner transaction, such as extension timers.
 
 ## Concurrent owner-local delivery
 
@@ -185,34 +229,40 @@ partition. Both slots require the queue head across lanes, ordered by running
 first, then priority descending and enqueue sequence ascending. Cancelled queued
 jobs can settle past a busy queue without executing.
 
-The Effect runtime's `readSettled(limit, afterSequence)` exposes the serial
-partition in enqueue order. A prefix fence withholds later settlements until all
-earlier serial jobs settle or are purged. Concurrent receipts never consume a
-page slot; they remain readable by job ID. `hasPendingWork` still covers both
-partitions. These owner-local operations require no stored schema change and do
-not change the D1 or PostgreSQL adapters.
+The Effect runtime's `readSettled(limit, afterSequence, lane?)` exposes the
+serial partition in enqueue order. A prefix fence withholds later settlements
+until all earlier jobs in the selected partition and optional lane settle or are
+purged. Concurrent receipts never consume a page slot; they remain readable by
+job ID. `wakeState(now)` still covers both partitions. These owner-local
+operations require no stored schema change and do not change the D1 or
+PostgreSQL adapters.
 
 ## Shared D1 and PostgreSQL storage
 
 `@fungi.computer/watchdog/d1` exports `createD1Watchdog` and `watchdogD1Schema`.
 `@fungi.computer/watchdog/postgres` exports `createPostgresWatchdog` and
 `watchdogPostgresSchema`. Apply the package-owned schema through your migration
-tool before you open a runtime. Opening a runtime never migrates a database.
+tool before you open a runtime. Opening a runtime never migrates a database. The
+named `watchdog_execution_state` constraint identifies the current lifecycle
+grammar. An obsolete grammar is refused before execution. Native prepared
+admission remains part of the caller's migrated transaction; it performs no
+schema repair. Owner-local SQLite applies the same refusal when opening.
 
 These runtimes have the same `ingest`, `read`, `readQueueHead`, `tick`,
-`cancel`, `failLane`, `purge` and `hasPendingWork` operations. They take
+`cancel`, `failLane`, `purge` and `wakeState(now)` operations. They take
 `execute`, `wake` and an optional `now` clock instead of an owner and liveness
 probe. Watchdog answers liveness itself from the claim's lease.
 
 D1 `enqueue(job)` returns a prepared statement for the producer's native batch.
 `enqueueFromSelect({ text, values })` accepts a trusted native SQLite
 `?NNN`-bound SELECT of `job_id`, `queue_name`, `lane`, `priority`,
-`payload_json` and nullable `recovery_max`. Watchdog supplies its INSERT and
-conflict checks. This lets a job depend on facts conditionally inserted earlier
-in the same batch, without a JavaScript read in between. PostgreSQL
-`enqueue(client, job)` uses the caller's checked-out transaction client. The
-caller owns BEGIN, COMMIT and ROLLBACK. An identical replay does nothing. A
-conflicting identity or cargo fails the whole native transaction.
+`payload_json`, nullable `recovery_max` and nullable `recovery_window_ms`.
+Watchdog supplies its INSERT and conflict checks. This lets a job depend on
+facts conditionally inserted earlier in the same batch, without a JavaScript
+read in between. PostgreSQL `enqueue(client, job)` uses the caller's checked-out
+transaction client. The caller owns BEGIN, COMMIT and ROLLBACK. An identical
+replay does nothing. A conflicting identity or cargo fails the whole native
+transaction.
 
 Both adapters use the same lifecycle engine as the SQLite entrypoint. Claims
 stay private, with two-minute leases, ten-second renewal and bounded renewal
@@ -241,7 +291,7 @@ modules:
   with their Effect schemas.
 - `@fungi.computer/watchdog/effect`: `makeRuntime`, `WatchdogRuntimeEffect` and
   `EffectWatchdogOptions`. The Effect runtime also has
-  `readSettled(limit, afterSequence?)` for paging through settled jobs.
+  `readSettled(limit, afterSequence?, lane?)` for paging through settled jobs.
 - `@fungi.computer/watchdog/node-sqlite`: `fromNodeSqlite(database)` for a
   caller-owned Node SQLite database. It returns `NodeSqliteOwner`; its
   `NodeSqliteCursor` provides `toArray()` and `one()`, which returns exactly one
@@ -301,9 +351,12 @@ Every failure is a `WatchdogError` with a closed `cause`:
 
 - `store_unavailable`: the store threw, or an ingest replay conflicted with the
   stored job.
-- `store_invalid`: the lane-refusal input failed its strict lane/reason decoder.
-  Other store faults remain `store_unavailable`.
+- `store_invalid`: the lifecycle schema is obsolete, or lane-refusal input
+  failed its strict lane/reason decoder. Other store faults remain
+  `store_unavailable`.
 - `claim_unavailable`: a claim could not be taken or renewed.
+- `drain_failed`: interrupted execution did not prove that foreign cleanup
+  finished.
 - `execution_failed`: your Promise executor threw. `tick()` does not reject. The
   job settles as `failed` with this code as its `failureReason`.
 - `settlement_rejected`: the claim was replaced or expired before settlement.

package/dist/d1.js

@@ -9,6 +9,7 @@ export function createD1Watchdog(options) {
         .prepare(statement.text.replace(/\$(\d+)/gu, "?$1"))
         .bind(...statement.values);
     const runtime = createAsyncRuntime({
+        dialect: "sqlite",
         clock: options.now === undefined ? "unixepoch('subsec')*1000" : undefined,
         query: async (statement) => (await prepare(statement).all()).results,
     }, options);

package/dist/effect.d.ts

@@ -1,6 +1,27 @@
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 import { WatchdogError } from "./internal/watchdog-error.js";
+/** Immediate reconciliation and the earliest future durable deadline. */
+export type WatchdogWakeState = Readonly<{
+    pending: boolean;
+    nextWakeAt: number | null;
+}>;
+/** Bounded receiver policy selected by the executor's existing delivery owner. */
+export type WatchdogRetryPolicy = Readonly<{
+    baseMs: number;
+    maxMs: number;
+    limit: Readonly<{
+        maxAttempts: number;
+    }> | Readonly<{
+        deadlineAt: number;
+    }>;
+}>;
+/** Reservation committed before receiver I/O; exhausted work may only finish its receipt. */
+export type WatchdogAttempt = Readonly<{
+    count: number;
+    status: "admitted" | "exhausted";
+    final: boolean;
+}>;
 /** The public queued-job grammar. Payload is deliberately uninterpreted. */
 export declare const WatchdogQueuedJobSchema: Schema.Struct<{
     readonly state: Schema.Literal<"queued">;
@@ -9,25 +30,46 @@ export declare const WatchdogQueuedJobSchema: Schema.Struct<{
     readonly lane: Schema.String;
     readonly priority: Schema.Int;
     readonly payload: Schema.Unknown;
+    readonly notBefore: Schema.optionalKey<Schema.Int>;
     readonly recovery: Schema.optional<Schema.Struct<{
         readonly maxRecoveries: Schema.Int;
+        readonly windowMs: Schema.optionalKey<Schema.Int>;
     }>>;
 }>;
 /** Generic durable work waiting for execution. */
 export type WatchdogQueuedJob = Schema.Schema.Type<typeof WatchdogQueuedJobSchema>;
+/** Execution has decided; its atomic owner projection has not committed yet. */
+export declare const WatchdogCompletingJobSchema: Schema.Struct<{
+    readonly state: Schema.Literal<"completing">;
+    readonly outcome: Schema.Literals<readonly ["completed", "failed", "cancelled", "outcome_unknown", "interrupted"]>;
+    readonly failureReason: Schema.optionalKey<Schema.String>;
+    readonly jobId: Schema.String;
+    readonly queue: Schema.String;
+    readonly lane: Schema.String;
+    readonly priority: Schema.Int;
+    readonly payload: Schema.Unknown;
+    readonly notBefore: Schema.optionalKey<Schema.Int>;
+    readonly recovery: Schema.optional<Schema.Struct<{
+        readonly maxRecoveries: Schema.Int;
+        readonly windowMs: Schema.optionalKey<Schema.Int>;
+    }>>;
+}>;
+/** Durable decision awaiting its owner projection, never executor replay. */
+export type WatchdogCompletingJob = Schema.Schema.Type<typeof WatchdogCompletingJobSchema>;
 /** The public terminal-job grammar. */
 export declare const WatchdogSettledJobSchema: Schema.Struct<{
     readonly state: Schema.Literal<"settled">;
     readonly outcome: Schema.Literals<readonly ["completed", "failed", "cancelled", "outcome_unknown", "interrupted"]>;
-    /** Why a job failed or exhausted disappearance recovery, when known. */
     readonly failureReason: Schema.optionalKey<Schema.String>;
     readonly jobId: Schema.String;
     readonly queue: Schema.String;
     readonly lane: Schema.String;
     readonly priority: Schema.Int;
     readonly payload: Schema.Unknown;
+    readonly notBefore: Schema.optionalKey<Schema.Int>;
     readonly recovery: Schema.optional<Schema.Struct<{
         readonly maxRecoveries: Schema.Int;
+        readonly windowMs: Schema.optionalKey<Schema.Int>;
     }>>;
 }>;
 /** Generic durable work with a terminal outcome. */
@@ -45,8 +87,10 @@ export declare const WatchdogRunningJobSchema: Schema.Struct<{
     readonly lane: Schema.String;
     readonly priority: Schema.Int;
     readonly payload: Schema.Unknown;
+    readonly notBefore: Schema.optionalKey<Schema.Int>;
     readonly recovery: Schema.optional<Schema.Struct<{
         readonly maxRecoveries: Schema.Int;
+        readonly windowMs: Schema.optionalKey<Schema.Int>;
     }>>;
 }>;
 /** Generic durable work held by Watchdog's private claim. */
@@ -59,8 +103,10 @@ export declare const WatchdogStoredJobSchema: Schema.Union<readonly [Schema.Stru
     readonly lane: Schema.String;
     readonly priority: Schema.Int;
     readonly payload: Schema.Unknown;
+    readonly notBefore: Schema.optionalKey<Schema.Int>;
     readonly recovery: Schema.optional<Schema.Struct<{
         readonly maxRecoveries: Schema.Int;
+        readonly windowMs: Schema.optionalKey<Schema.Int>;
     }>>;
 }>, Schema.Struct<{
     readonly state: Schema.Literal<"running">;
@@ -69,27 +115,46 @@ export declare const WatchdogStoredJobSchema: Schema.Union<readonly [Schema.Stru
     readonly lane: Schema.String;
     readonly priority: Schema.Int;
     readonly payload: Schema.Unknown;
+    readonly notBefore: Schema.optionalKey<Schema.Int>;
+    readonly recovery: Schema.optional<Schema.Struct<{
+        readonly maxRecoveries: Schema.Int;
+        readonly windowMs: Schema.optionalKey<Schema.Int>;
+    }>>;
+}>, Schema.Struct<{
+    readonly state: Schema.Literal<"completing">;
+    readonly outcome: Schema.Literals<readonly ["completed", "failed", "cancelled", "outcome_unknown", "interrupted"]>;
+    readonly failureReason: Schema.optionalKey<Schema.String>;
+    readonly jobId: Schema.String;
+    readonly queue: Schema.String;
+    readonly lane: Schema.String;
+    readonly priority: Schema.Int;
+    readonly payload: Schema.Unknown;
+    readonly notBefore: Schema.optionalKey<Schema.Int>;
     readonly recovery: Schema.optional<Schema.Struct<{
         readonly maxRecoveries: Schema.Int;
+        readonly windowMs: Schema.optionalKey<Schema.Int>;
     }>>;
 }>, Schema.Struct<{
     readonly state: Schema.Literal<"settled">;
     readonly outcome: Schema.Literals<readonly ["completed", "failed", "cancelled", "outcome_unknown", "interrupted"]>;
-    /** Why a job failed or exhausted disappearance recovery, when known. */
     readonly failureReason: Schema.optionalKey<Schema.String>;
     readonly jobId: Schema.String;
     readonly queue: Schema.String;
     readonly lane: Schema.String;
     readonly priority: Schema.Int;
     readonly payload: Schema.Unknown;
+    readonly notBefore: Schema.optionalKey<Schema.Int>;
     readonly recovery: Schema.optional<Schema.Struct<{
         readonly maxRecoveries: Schema.Int;
+        readonly windowMs: Schema.optionalKey<Schema.Int>;
     }>>;
 }>]>;
 /** Any publicly readable lifecycle state for a generic job. */
 export type WatchdogStoredJob = Schema.Schema.Type<typeof WatchdogStoredJobSchema>;
 /** Terminal decisions returned by the execution adapter. */
 export declare const WatchdogExecutionDecisionSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"retry">;
+}>, Schema.Struct<{
     readonly kind: Schema.Literal<"completed">;
 }>, Schema.Struct<{
     readonly kind: Schema.Literal<"failed">;
@@ -113,17 +178,29 @@ export type WatchdogCancellationIntent = Schema.Schema.Type<typeof WatchdogCance
 export type WatchdogCancellationDecision = Readonly<{
     status: "recorded" | "replayed";
     intent: WatchdogCancellationIntent;
+}> | Readonly<{
+    status: "decided";
+    outcome: WatchdogSettledJob["outcome"];
 }> | Readonly<{
     status: "conflict" | "missing";
 }>;
 /** Narrow synchronous seam for owner-atomic queue inspection, ingest, and cancellation. */
 export type WatchdogTransactionalProjection = Readonly<{
+    /** Read the same durable readiness for synchronous native host wake composition. */
+    wakeState: (now: number) => WatchdogWakeState;
+    /** Reads a job's exact lifecycle state and durable deadline in the owner transaction. */
+    readJob: (jobId: string) => Readonly<{
+        state: WatchdogStoredJob["state"];
+        notBefore: number;
+    }> | undefined;
     /** Reads the bounded current queue head inside an enclosing owner transaction. */
     readQueueHead: (queue: string) => WatchdogQueueHead;
     /** Reads the most recently settled job of one queue, if any. */
     readLatestSettledJob: (queue: string) => WatchdogSettledJob | undefined;
     /** Applies the same durable queued-row mutation as store.ingest. */
     enqueueAcceptedJob: (job: WatchdogQueuedJob) => void;
+    /** Expedite existing queued work without changing its charged attempt count. */
+    expediteQueuedJob: (jobId: string, now: number) => boolean;
     /** Records or replays cancellation without interpreting the payload. */
     recordCancellationIntent: (intent: WatchdogCancellationIntent) => WatchdogCancellationDecision;
 }>;
@@ -137,8 +214,10 @@ export declare const WatchdogReadResultSchema: Schema.Union<readonly [Schema.Str
         readonly lane: Schema.String;
         readonly priority: Schema.Int;
         readonly payload: Schema.Unknown;
+        readonly notBefore: Schema.optionalKey<Schema.Int>;
         readonly recovery: Schema.optional<Schema.Struct<{
             readonly maxRecoveries: Schema.Int;
+            readonly windowMs: Schema.optionalKey<Schema.Int>;
         }>>;
     }>, Schema.Struct<{
         readonly state: Schema.Literal<"running">;
@@ -147,21 +226,38 @@ export declare const WatchdogReadResultSchema: Schema.Union<readonly [Schema.Str
         readonly lane: Schema.String;
         readonly priority: Schema.Int;
         readonly payload: Schema.Unknown;
+        readonly notBefore: Schema.optionalKey<Schema.Int>;
+        readonly recovery: Schema.optional<Schema.Struct<{
+            readonly maxRecoveries: Schema.Int;
+            readonly windowMs: Schema.optionalKey<Schema.Int>;
+        }>>;
+    }>, Schema.Struct<{
+        readonly state: Schema.Literal<"completing">;
+        readonly outcome: Schema.Literals<readonly ["completed", "failed", "cancelled", "outcome_unknown", "interrupted"]>;
+        readonly failureReason: Schema.optionalKey<Schema.String>;
+        readonly jobId: Schema.String;
+        readonly queue: Schema.String;
+        readonly lane: Schema.String;
+        readonly priority: Schema.Int;
+        readonly payload: Schema.Unknown;
+        readonly notBefore: Schema.optionalKey<Schema.Int>;
         readonly recovery: Schema.optional<Schema.Struct<{
             readonly maxRecoveries: Schema.Int;
+            readonly windowMs: Schema.optionalKey<Schema.Int>;
         }>>;
     }>, Schema.Struct<{
         readonly state: Schema.Literal<"settled">;
         readonly outcome: Schema.Literals<readonly ["completed", "failed", "cancelled", "outcome_unknown", "interrupted"]>;
-        /** Why a job failed or exhausted disappearance recovery, when known. */
         readonly failureReason: Schema.optionalKey<Schema.String>;
         readonly jobId: Schema.String;
         readonly queue: Schema.String;
         readonly lane: Schema.String;
         readonly priority: Schema.Int;
         readonly payload: Schema.Unknown;
+        readonly notBefore: Schema.optionalKey<Schema.Int>;
         readonly recovery: Schema.optional<Schema.Struct<{
             readonly maxRecoveries: Schema.Int;
+            readonly windowMs: Schema.optionalKey<Schema.Int>;
         }>>;
     }>]>;
     readonly cancellation: Schema.Union<readonly [Schema.Struct<{
@@ -187,7 +283,7 @@ export declare const WatchdogQueueHeadSchema: Schema.Union<readonly [Schema.Stru
     readonly jobId: Schema.String;
     readonly cancellationRequested: Schema.Boolean;
 }>]>;
-/** Current queued or running job for one queue, excluding terminal history. */
+/** Queue occupancy: completing work remains running here until its projection commits. Read the job for its exact lifecycle state. */
 export type WatchdogQueueHead = Schema.Schema.Type<typeof WatchdogQueueHeadSchema>;
 /** One queue's state after a durable transition. */
 export type WatchdogQueueTransition = Readonly<{
@@ -214,6 +310,9 @@ export declare const WatchdogIngestResultSchema: Schema.Union<readonly [Schema.S
 export type WatchdogIngestResult = Schema.Schema.Type<typeof WatchdogIngestResultSchema>;
 /** Results returned by durable cancellation recording. */
 export declare const WatchdogCancellationResultSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly status: Schema.Literal<"decided">;
+    readonly outcome: Schema.Literals<readonly ["completed", "failed", "cancelled", "outcome_unknown", "interrupted"]>;
+}>, Schema.Struct<{
     readonly status: Schema.Literals<readonly ["recorded", "replayed"]>;
 }>, Schema.Struct<{
     readonly status: Schema.Literals<readonly ["conflict", "missing"]>;
@@ -222,8 +321,14 @@ export declare const WatchdogCancellationResultSchema: Schema.Union<readonly [Sc
 export type WatchdogCancellationResult = Schema.Schema.Type<typeof WatchdogCancellationResultSchema>;
 /** Effect-native host executor for one generic running job. */
 export type EffectWatchdogExecutor = Readonly<{
+    /** Code-owned proof that consumption and every effect commit in one owner transaction. */
+    replaySafe?: (job: WatchdogRunningJob) => boolean;
+    /** Resolve the current delivery policy from the existing owner, outside a storage transaction. */
+    retryPolicy?: (job: WatchdogRunningJob) => Effect.Effect<WatchdogRetryPolicy | undefined, WatchdogError>;
     /** Runs one generic claimed job until a terminal decision. */
-    execute: (job: WatchdogRunningJob) => Effect.Effect<WatchdogExecutionDecision, WatchdogError>;
+    execute: (job: WatchdogRunningJob, attempt: WatchdogAttempt | undefined) => Effect.Effect<WatchdogExecutionDecision, WatchdogError>;
+    /** After interruption and scope release, prove foreign resources finished cleanup. */
+    isDrained?: (job: WatchdogRunningJob) => Effect.Effect<boolean, WatchdogError>;
 }>;
 /** Scalar grammar shared by native SQLite adapters and their storage owners. */
 export declare const watchdogSqliteValueSchema: Schema.Union<readonly [Schema.instanceOf<ArrayBuffer, unknown>, Schema.String, Schema.Number, Schema.Null]>;
@@ -277,7 +382,12 @@ export type WatchdogLivenessUnknown = Readonly<{
 }>;
 /** Result of one bounded deep tick. */
 export type WatchdogTickResult = Readonly<{
+    status: "requeued";
+    jobId: string;
+}> | Readonly<{
     status: "busy";
+}> | Readonly<{
+    status: "stopped";
 }> | Readonly<{
     status: "no_ready";
 }> | WatchdogLivenessUnknown | Readonly<{
@@ -300,8 +410,8 @@ export type WatchdogLaneFailureResult = Readonly<{
 }>;
 /** Effect-native Watchdog runtime surface. */
 export type WatchdogRuntimeEffect = Readonly<{
-    /** Whether any queued or running job still needs owner reconciliation. */
-    hasPendingWork: Effect.Effect<boolean, WatchdogError>;
+    /** Read readiness and the next deadline from the same durable work rows. */
+    wakeState: (now: number) => Effect.Effect<WatchdogWakeState, WatchdogError>;
     /** Persists one queued job. */
     ingest: (job: WatchdogQueuedJob) => Effect.Effect<WatchdogIngestResult, WatchdogError>;
     /** Reads one durable job. */
@@ -309,7 +419,7 @@ export type WatchdogRuntimeEffect = Readonly<{
     /** Reads the bounded current head of one generic queue. */
     readQueueHead: (queue: string) => Effect.Effect<WatchdogQueueHead, WatchdogError>;
     /** Reads a bounded terminal prefix of the serial partition for owner recovery. */
-    readSettled: (limit: number, afterSequence?: number) => Effect.Effect<readonly WatchdogSettledRecord[], WatchdogError>;
+    readSettled: (limit: number, afterSequence?: number, lane?: string) => Effect.Effect<readonly WatchdogSettledRecord[], WatchdogError>;
     /** Runs one bounded generic lifecycle tick. */
     tick: () => Effect.Effect<WatchdogTickResult, WatchdogError>;
     /** Records cancellation and signals live execution. */
@@ -318,6 +428,8 @@ export type WatchdogRuntimeEffect = Readonly<{
      * Refused claims are invalidated; both late success and failure reports are rejected.
      */
     failLane: (input: WatchdogLaneFailure) => Effect.Effect<WatchdogLaneFailureResult, WatchdogError>;
+    /** Stop dispatch, interrupt owned execution, and hand off only a proven drained claim. */
+    close: Effect.Effect<void, WatchdogError>;
     /** Removes queued jobs in one queue. */
     purge: (queue: string) => Effect.Effect<void, WatchdogError>;
     /** Joins accepted enqueue and cancellation to an existing owner transaction. */

package/dist/effect.js

@@ -1,4 +1,5 @@
 import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
 import * as Schema from "effect/Schema";
 import { bindWatchdogEngine } from "./internal/runtime.js";
 import { openSqliteState } from "./internal/sqlite-store.js";
@@ -11,6 +12,7 @@ const Priority = Schema.Int.check(Schema.isGreaterThanOrEqualTo(Number.MIN_SAFE_
 const RecoveryCount = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER));
 const RecoveryPolicy = Schema.Struct({
     maxRecoveries: RecoveryCount,
+    windowMs: Schema.optionalKey(Schema.Int.check(Schema.isGreaterThan(0), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER))),
 });
 const PublicJobFields = {
     jobId: BoundedString,
@@ -18,6 +20,8 @@ const PublicJobFields = {
     lane: laneSchema,
     priority: Priority,
     payload: Schema.Unknown,
+    /** Earliest initial dispatch; replay never changes a retained deadline. */
+    notBefore: Schema.optionalKey(RecoveryCount),
     recovery: Schema.optional(RecoveryPolicy),
 };
 /** The public queued-job grammar. Payload is deliberately uninterpreted. */
@@ -25,19 +29,27 @@ export const WatchdogQueuedJobSchema = Schema.Struct({
     ...PublicJobFields,
     state: Schema.Literal("queued"),
 });
+const Outcome = Schema.Literals([
+    "completed",
+    "failed",
+    "cancelled",
+    "outcome_unknown",
+    "interrupted",
+]);
+const DecidedJobFields = {
+    ...PublicJobFields,
+    outcome: Outcome,
+    failureReason: Schema.optionalKey(FailureReason),
+};
+/** Execution has decided; its atomic owner projection has not committed yet. */
+export const WatchdogCompletingJobSchema = Schema.Struct({
+    ...DecidedJobFields,
+    state: Schema.Literal("completing"),
+});
 /** The public terminal-job grammar. */
 export const WatchdogSettledJobSchema = Schema.Struct({
-    ...PublicJobFields,
+    ...DecidedJobFields,
     state: Schema.Literal("settled"),
-    outcome: Schema.Literals([
-        "completed",
-        "failed",
-        "cancelled",
-        "outcome_unknown",
-        "interrupted",
-    ]),
-    /** Why a job failed or exhausted disappearance recovery, when known. */
-    failureReason: Schema.optionalKey(FailureReason),
 });
 /** The public running-job grammar. Private claim data is deliberately absent. */
 export const WatchdogRunningJobSchema = Schema.Struct({
@@ -48,10 +60,12 @@ export const WatchdogRunningJobSchema = Schema.Struct({
 export const WatchdogStoredJobSchema = Schema.Union([
     WatchdogQueuedJobSchema,
     WatchdogRunningJobSchema,
+    WatchdogCompletingJobSchema,
     WatchdogSettledJobSchema,
 ]);
 /** Terminal decisions returned by the execution adapter. */
 export const WatchdogExecutionDecisionSchema = Schema.Union([
+    Schema.Struct({ kind: Schema.Literal("retry") }),
     Schema.Struct({ kind: Schema.Literal("completed") }),
     Schema.Struct({
         kind: Schema.Literal("failed"),
@@ -98,6 +112,7 @@ export const WatchdogIngestResultSchema = Schema.Union([
 ]);
 /** Results returned by durable cancellation recording. */
 export const WatchdogCancellationResultSchema = Schema.Union([
+    Schema.Struct({ status: Schema.Literal("decided"), outcome: Outcome }),
     Schema.Struct({ status: Schema.Literals(["recorded", "replayed"]) }),
     Schema.Struct({ status: Schema.Literals(["conflict", "missing"]) }),
 ]);
@@ -125,6 +140,12 @@ export function makeRuntime(options) {
             return Object.freeze({
                 ...base,
                 tickConcurrent: concurrent.tick,
+                close: Effect.all([Effect.exit(serial.close), Effect.exit(concurrent.close)], { concurrency: 2 }).pipe(Effect.flatMap((exits) => {
+                    const failed = exits.find(Exit.isFailure);
+                    return failed === undefined
+                        ? Effect.void
+                        : Effect.failCause(failed.cause);
+                })),
                 failLane: (input) => input.lane === lane
                     ? concurrent.failLane(input)
                     : serial.failLane(input),
@@ -135,6 +156,8 @@ export function makeRuntime(options) {
                     : serial.cancel(intent))),
             });
         },
-        catch: (error) => new WatchdogError("store_unavailable", error),
+        catch: (error) => error instanceof WatchdogError
+            ? error
+            : new WatchdogError("store_unavailable", error),
     });
 }