@fungi.computer/watchdog 0.0.0-stage → 0.0.1

package/dist/internal/sqlite-store.d.ts

@@ -0,0 +1,107 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import type { WatchdogLaneFailure, WatchdogCancellationIntent, WatchdogCancellationResult, WatchdogExecutionDecision, WatchdogIngestResult, WatchdogQueuedJob, WatchdogQueueHead, WatchdogQueueProjector, WatchdogReadResult, WatchdogRunningJob, WatchdogSettledJob, WatchdogSettledRecord, WatchdogSqliteOwner, WatchdogSqliteRow, WatchdogStoredJob, WatchdogTransactionalProjection } from "../effect.js";
+import { WatchdogError } from "./watchdog-error.js";
+export type { WatchdogSqliteRow } from "../effect.js";
+export declare const laneFailureBatchSize = 256;
+/** One strict owner input grammar shared by the storage implementations. */
+export declare function parseLaneFailure(input: WatchdogLaneFailure): WatchdogLaneFailure;
+declare const JobRowSchema: Schema.Struct<{
+    readonly sequence: Schema.Int;
+    readonly job_id: Schema.String;
+    readonly queue_name: Schema.String;
+    readonly lane: Schema.String;
+    readonly priority: Schema.Int;
+    readonly payload_json: Schema.String;
+    readonly recovery_max: Schema.NullOr<Schema.Int>;
+    readonly state: Schema.Literals<readonly ["queued", "running", "settled"]>;
+    readonly outcome: Schema.NullOr<Schema.Literals<readonly ["completed", "failed", "cancelled", "outcome_unknown", "interrupted"]>>;
+    readonly claim_token: Schema.NullOr<Schema.String>;
+    readonly recovery_count: Schema.Int;
+    readonly cancellation_id: Schema.NullOr<Schema.String>;
+    readonly failure_reason: Schema.NullOr<Schema.String>;
+}>;
+/** Decoded relational row used inside the SQLite adapter family. */
+export type WatchdogSqliteJobRow = Schema.Schema.Type<typeof JobRowSchema>;
+/** Decoded row and domain job shared with the async SQLite adapter. */
+export type ParsedWatchdogSqliteJob = Readonly<{
+    row: WatchdogSqliteJobRow;
+    job: WatchdogStoredJob;
+}>;
+/** Package-private result of selecting or claiming one durable row. */
+export type WatchdogSelection = Readonly<{
+    status: "no_ready";
+}> | Readonly<{
+    status: "claim_unavailable";
+}> | Readonly<{
+    status: "cancelled";
+    job: WatchdogSettledJob;
+}> | Readonly<{
+    status: "claimed";
+    job: WatchdogRunningJob;
+    claimToken: string;
+}>;
+/** One private execution partition; no payload or product meaning. */
+export type LanePartition = Readonly<{
+    lane: string;
+    include: boolean;
+}>;
+/** Package-private storage operations consumed by Watchdog's Effect engine. */
+export type WatchdogStore = Readonly<{
+    hasPendingWork: Effect.Effect<boolean, WatchdogError>;
+    ingest: (job: WatchdogQueuedJob) => Effect.Effect<WatchdogIngestResult, WatchdogError>;
+    read: (jobId: string) => Effect.Effect<(Extract<WatchdogReadResult, {
+        status: "found";
+    }> & Readonly<{
+        claimToken: string | null;
+        recoveryCount: number;
+    }>) | Extract<WatchdogReadResult, {
+        status: "missing";
+    }>, WatchdogError>;
+    readQueueHead: (queue: string) => Effect.Effect<WatchdogQueueHead, WatchdogError>;
+    readSettled: (limit: number, afterSequence?: number) => Effect.Effect<readonly WatchdogSettledRecord[], WatchdogError>;
+    selectAndClaim: (claimToken: string) => Effect.Effect<WatchdogSelection, WatchdogError>;
+    settleExactClaim: (input: Readonly<{
+        jobId: string;
+        claimToken: string;
+        decision: WatchdogExecutionDecision;
+    }>) => Effect.Effect<Readonly<{
+        status: "settled" | "replayed";
+        job: WatchdogSettledJob;
+    }> | Readonly<{
+        status: "conflict" | "missing";
+    }>, WatchdogError>;
+    recordCancellation: (input: WatchdogCancellationIntent) => Effect.Effect<WatchdogCancellationResult, WatchdogError>;
+    failLane: (input: WatchdogLaneFailure) => Effect.Effect<Readonly<{
+        jobs: readonly WatchdogSettledJob[];
+        more: boolean;
+    }>, WatchdogError>;
+    purgeQueued: (queue: string) => Effect.Effect<void, WatchdogError>;
+    nextRunningClaim: () => Effect.Effect<Readonly<{
+        job: WatchdogRunningJob;
+        claimToken: string;
+        recoveryCount: number;
+    }> | undefined, WatchdogError>;
+    reconcileDisappearedClaim: (input: Readonly<{
+        job: WatchdogRunningJob;
+        claimToken: string;
+        recoveryCount: number;
+        disposition: "requeue" | "interrupted";
+    }>) => Effect.Effect<Readonly<{
+        status: "requeued";
+    }> | Readonly<{
+        status: "settled";
+        job: WatchdogSettledJob;
+    }> | Readonly<{
+        status: "conflict" | "missing";
+    }>, WatchdogError>;
+}>;
+/** Package-private SQLite state plus the one owner-transaction projection. */
+export type WatchdogSqliteState = Readonly<{
+    store: WatchdogStore;
+    partition: (partition: LanePartition) => WatchdogStore;
+    transactional: WatchdogTransactionalProjection;
+}>;
+export declare function parseJobRow(raw: WatchdogSqliteRow): ParsedWatchdogSqliteJob;
+/** Construct Watchdog's private owner-local SQLite state. */
+export declare function openSqliteState(owner: WatchdogSqliteOwner, project?: WatchdogQueueProjector, partition?: LanePartition): WatchdogSqliteState;

package/dist/internal/sqlite-store.js

@@ -0,0 +1,478 @@
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { WatchdogError } from "./watchdog-error.js";
+import { laneSchema } from "./lane.js";
+const Identifier = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(256));
+const Priority = Schema.Int.check(Schema.isGreaterThanOrEqualTo(Number.MIN_SAFE_INTEGER), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER));
+const Count = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER));
+const FailureReason = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(200));
+const LaneFailureSchema = Schema.Struct({
+    lane: laneSchema,
+    reason: FailureReason,
+});
+// A transition batch, not a lifetime limit on lane work; matches terminal reads.
+export const laneFailureBatchSize = 256;
+/** One strict owner input grammar shared by the storage implementations. */
+export function parseLaneFailure(input) {
+    try {
+        return Schema.decodeUnknownSync(LaneFailureSchema, {
+            onExcessProperty: "error",
+        })(input);
+    }
+    catch (cause) {
+        throw new WatchdogError("store_invalid", cause);
+    }
+}
+const JobRowSchema = Schema.Struct({
+    sequence: Schema.Int,
+    job_id: Identifier,
+    queue_name: Identifier,
+    lane: laneSchema,
+    priority: Priority,
+    payload_json: Schema.String,
+    recovery_max: Schema.NullOr(Count),
+    state: Schema.Literals(["queued", "running", "settled"]),
+    outcome: Schema.NullOr(Schema.Literals([
+        "completed",
+        "failed",
+        "cancelled",
+        "outcome_unknown",
+        "interrupted",
+    ])),
+    claim_token: Schema.NullOr(Identifier),
+    recovery_count: Count,
+    cancellation_id: Schema.NullOr(Identifier),
+    failure_reason: Schema.NullOr(FailureReason),
+});
+const PayloadTextSchema = Schema.fromJsonString(Schema.Unknown);
+const decodeJobRow = Schema.decodeUnknownExit(JobRowSchema, {
+    onExcessProperty: "error",
+});
+const decodePayload = Schema.decodeUnknownExit(PayloadTextSchema);
+const encodePayload = Schema.encodeUnknownExit(PayloadTextSchema);
+function laneQuery(partition) {
+    return partition === undefined
+        ? { predicate: "1 = 1", values: [] }
+        : {
+            predicate: partition.include ? "lane = ?" : "lane <> ?",
+            values: [partition.lane],
+        };
+}
+const columns = `sequence, job_id, queue_name, lane, priority, payload_json,
+                 recovery_max, state, outcome, claim_token, recovery_count,
+                 cancellation_id, failure_reason`;
+function unavailable(cause) {
+    return new WatchdogError("store_unavailable", cause);
+}
+function storeEffect(operation) {
+    return Effect.try({
+        try: operation,
+        // The SQL error stays on the failure; a Watchdog failure raised inside
+        // (an invariant or a decode) already carries its own.
+        catch: (error) => error instanceof WatchdogError ? error : unavailable(error),
+    });
+}
+function encodeOpaquePayload(payload) {
+    const encoded = encodePayload(payload);
+    if (encoded._tag === "Failure")
+        throw unavailable(Cause.squash(encoded.cause));
+    return encoded.value;
+}
+export function parseJobRow(raw) {
+    const decoded = decodeJobRow(raw);
+    if (decoded._tag === "Failure")
+        throw unavailable(Cause.squash(decoded.cause));
+    const row = decoded.value;
+    const payload = decodePayload(row.payload_json);
+    if (payload._tag === "Failure")
+        throw unavailable(Cause.squash(payload.cause));
+    const common = row.recovery_max === null
+        ? {
+            jobId: row.job_id,
+            queue: row.queue_name,
+            lane: row.lane,
+            priority: row.priority,
+            payload: payload.value,
+        }
+        : {
+            jobId: row.job_id,
+            queue: row.queue_name,
+            lane: row.lane,
+            priority: row.priority,
+            payload: payload.value,
+            recovery: { maxRecoveries: row.recovery_max },
+        };
+    if (row.state === "queued")
+        return { row, job: { ...common, state: "queued" } };
+    if (row.state === "running") {
+        if (row.claim_token === null)
+            throw unavailable();
+        return { row, job: { ...common, state: "running" } };
+    }
+    if (row.outcome === null)
+        throw unavailable();
+    const settled = {
+        ...common,
+        state: "settled",
+        outcome: row.outcome,
+    };
+    return {
+        row,
+        job: (row.outcome === "failed" || row.outcome === "interrupted") &&
+            row.failure_reason !== null
+            ? { ...settled, failureReason: row.failure_reason }
+            : settled,
+    };
+}
+function readJob(owner, jobId) {
+    const raw = owner.sql
+        .exec(`SELECT ${columns}
+         FROM watchdog_jobs
+        WHERE job_id = ?`, jobId)
+        .toArray()[0];
+    return raw === undefined ? undefined : parseJobRow(raw);
+}
+function readSettled(owner, limit, afterSequence, partition) {
+    const lane = laneQuery(partition);
+    const rows = owner.sql
+        .exec(`SELECT ${columns} FROM watchdog_jobs NOT INDEXED WHERE state = 'settled' AND ${lane.predicate} AND sequence > ?
+       AND sequence < COALESCE(
+        (SELECT MIN(sequence) FROM watchdog_jobs INDEXED BY idx_watchdog_ready
+         WHERE state IN ('queued', 'running') AND ${lane.predicate}),
+        9223372036854775807)
+       ORDER BY sequence ASC LIMIT ?`, ...lane.values, afterSequence ?? 0, ...lane.values, limit)
+        .toArray();
+    return rows.map((raw) => {
+        const parsed = parseJobRow(raw);
+        if (parsed.job.state !== "settled")
+            throw unavailable();
+        return { sequence: parsed.row.sequence, job: parsed.job };
+    });
+}
+function readQueueHead(owner, queue) {
+    const raw = owner.sql
+        .exec(`SELECT ${columns}
+         FROM watchdog_jobs
+        WHERE queue_name = ? AND state IN ('running', 'queued')
+        ORDER BY CASE state WHEN 'running' THEN 0 ELSE 1 END,
+                 priority DESC, sequence ASC
+        LIMIT 1`, queue)
+        .toArray()[0];
+    if (raw === undefined)
+        return { state: "idle" };
+    const parsed = parseJobRow(raw);
+    if (parsed.job.state === "settled")
+        throw unavailable();
+    return {
+        state: parsed.job.state,
+        jobId: parsed.job.jobId,
+        cancellationRequested: parsed.row.cancellation_id !== null,
+    };
+}
+function readLatestSettledJob(owner, queue) {
+    const raw = owner.sql
+        .exec(`SELECT ${columns}
+         FROM watchdog_jobs
+        WHERE queue_name = ? AND state = 'settled'
+        ORDER BY sequence DESC
+        LIMIT 1`, queue)
+        .toArray()[0];
+    if (raw === undefined)
+        return undefined;
+    const parsed = parseJobRow(raw);
+    if (parsed.job.state !== "settled")
+        throw unavailable();
+    return parsed.job;
+}
+/** Tell the owner projection one queue changed, inside the same transaction. */
+function projectQueue(owner, project, queue, settled) {
+    if (project === undefined)
+        return;
+    const head = readQueueHead(owner, queue);
+    project(settled === undefined ? { queue, head } : { queue, head, settled });
+}
+function prepare(owner) {
+    owner.transactionSync(() => {
+        owner.sql.exec(`
+      CREATE TABLE IF NOT EXISTS watchdog_jobs (
+        sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+        job_id TEXT UNIQUE NOT NULL,
+        queue_name TEXT NOT NULL,
+        lane TEXT NOT NULL,
+        priority INTEGER NOT NULL,
+        payload_json TEXT NOT NULL,
+        recovery_max INTEGER,
+        state TEXT NOT NULL CHECK (state IN ('queued', 'running', 'settled')),
+        outcome TEXT CHECK (
+          outcome IS NULL OR outcome IN (
+            'completed', 'failed', 'cancelled', 'outcome_unknown', 'interrupted'
+          )
+        ),
+        claim_token TEXT,
+        recovery_count INTEGER NOT NULL DEFAULT 0,
+        cancellation_id TEXT UNIQUE,
+        failure_reason TEXT,
+        CHECK (recovery_max IS NULL OR recovery_max >= 0),
+        CHECK (
+          (state = 'queued' AND outcome IS NULL AND claim_token IS NULL) OR
+          (state = 'running' AND outcome IS NULL AND claim_token IS NOT NULL) OR
+          (state = 'settled' AND outcome IS NOT NULL)
+        )
+      )
+    `);
+        owner.sql.exec(`CREATE INDEX IF NOT EXISTS idx_watchdog_lane_failure
+         ON watchdog_jobs(lane, state DESC, sequence ASC)`);
+        owner.sql.exec(`CREATE INDEX IF NOT EXISTS idx_watchdog_ready
+         ON watchdog_jobs(state, priority DESC, sequence ASC)`);
+        owner.sql.exec(`CREATE INDEX IF NOT EXISTS idx_watchdog_queue_head
+         ON watchdog_jobs(queue_name, state, priority DESC, sequence ASC)`);
+    });
+}
+function enqueue(owner, project, job) {
+    const payloadJson = encodeOpaquePayload(job.payload);
+    const prior = readJob(owner, job.jobId);
+    if (prior !== undefined) {
+        const priorRecovery = prior.job.recovery?.maxRecoveries;
+        const nextRecovery = job.recovery?.maxRecoveries;
+        if (prior.job.queue !== job.queue ||
+            prior.job.lane !== job.lane ||
+            prior.job.priority !== job.priority ||
+            prior.row.payload_json !== payloadJson ||
+            priorRecovery !== nextRecovery)
+            throw unavailable();
+        return false;
+    }
+    owner.sql.exec(`INSERT INTO watchdog_jobs
+       (job_id, queue_name, lane, priority, payload_json, recovery_max,
+        state, outcome, claim_token, recovery_count, cancellation_id)
+     VALUES (?, ?, ?, ?, ?, ?, 'queued', NULL, NULL, 0, NULL)`, job.jobId, job.queue, job.lane, job.priority, payloadJson, job.recovery?.maxRecoveries ?? null);
+    projectQueue(owner, project, job.queue);
+    return true;
+}
+function recordCancellationIntent(owner, project, intent) {
+    const prior = readJob(owner, intent.jobId);
+    if (prior === undefined)
+        return { status: "missing" };
+    if (prior.row.cancellation_id !== null)
+        return prior.row.cancellation_id === intent.cancellationId
+            ? { status: "replayed", intent }
+            : { status: "conflict" };
+    if (intent.onlyIfQueued === true && prior.job.state !== "queued")
+        return { status: "conflict" };
+    owner.sql.exec(`UPDATE watchdog_jobs
+        SET cancellation_id = ?
+      WHERE job_id = ? AND cancellation_id IS NULL`, intent.cancellationId, intent.jobId);
+    projectQueue(owner, project, prior.job.queue);
+    return { status: "recorded", intent };
+}
+function selectAndClaim(owner, project, claimToken, partition) {
+    const lane = laneQuery(partition);
+    return owner.transactionSync(() => {
+        const raw = owner.sql
+            .exec(`SELECT ${columns}
+           FROM watchdog_jobs
+          WHERE state = 'queued' AND ${lane.predicate}
+            AND (cancellation_id IS NOT NULL OR NOT EXISTS (
+              SELECT 1 FROM watchdog_jobs predecessor INDEXED BY idx_watchdog_queue_head
+              WHERE predecessor.queue_name = watchdog_jobs.queue_name
+                AND predecessor.state IN ('queued', 'running')
+                AND (predecessor.state = 'running' OR
+                  (predecessor.state = 'queued' AND
+                    (predecessor.priority > watchdog_jobs.priority OR
+                      (predecessor.priority = watchdog_jobs.priority AND
+                        predecessor.sequence < watchdog_jobs.sequence))))))
+          ORDER BY priority DESC, sequence ASC
+          LIMIT 1`, ...lane.values)
+            .toArray()[0];
+        if (raw === undefined)
+            return { status: "no_ready" };
+        const selected = parseJobRow(raw);
+        if (selected.job.state !== "queued")
+            return { status: "claim_unavailable" };
+        if (selected.row.cancellation_id !== null) {
+            owner.sql.exec(`UPDATE watchdog_jobs
+            SET state = 'settled', outcome = 'cancelled'
+          WHERE job_id = ? AND state = 'queued' AND cancellation_id = ?`, selected.job.jobId, selected.row.cancellation_id);
+            const settled = readJob(owner, selected.job.jobId)?.job;
+            if (settled?.state !== "settled" || settled.outcome !== "cancelled")
+                return { status: "claim_unavailable" };
+            projectQueue(owner, project, settled.queue, settled);
+            return { status: "cancelled", job: settled };
+        }
+        owner.sql.exec(`UPDATE watchdog_jobs
+          SET state = 'running', claim_token = ?
+        WHERE job_id = ? AND state = 'queued'`, claimToken, selected.job.jobId);
+        const claimed = readJob(owner, selected.job.jobId)?.job;
+        if (claimed?.state !== "running")
+            return { status: "claim_unavailable" };
+        projectQueue(owner, project, claimed.queue);
+        return { status: "claimed", job: claimed, claimToken };
+    });
+}
+function settleExactClaim(owner, project, input) {
+    return owner.transactionSync(() => {
+        const prior = readJob(owner, input.jobId);
+        if (prior === undefined)
+            return { status: "missing" };
+        const outcome = prior.row.cancellation_id === null ? input.decision.kind : "cancelled";
+        if (prior.job.state === "settled")
+            return prior.row.claim_token === input.claimToken &&
+                prior.job.outcome === outcome
+                ? { status: "replayed", job: prior.job }
+                : { status: "conflict" };
+        if (prior.job.state !== "running" ||
+            prior.row.claim_token !== input.claimToken)
+            return { status: "conflict" };
+        owner.sql.exec(`UPDATE watchdog_jobs
+          SET state = 'settled', outcome = ?, failure_reason = ?
+        WHERE job_id = ? AND state = 'running' AND claim_token = ?`, outcome, outcome === "failed" && input.decision.kind === "failed"
+            ? (input.decision.reason ?? null)
+            : null, input.jobId, input.claimToken);
+        const settled = readJob(owner, input.jobId)?.job;
+        if (settled?.state !== "settled")
+            return { status: "conflict" };
+        projectQueue(owner, project, settled.queue, settled);
+        return { status: "settled", job: settled };
+    });
+}
+/** Construct Watchdog's private owner-local SQLite state. */
+export function openSqliteState(owner, project, partition) {
+    prepare(owner);
+    const transactional = Object.freeze({
+        readQueueHead: (queue) => readQueueHead(owner, queue),
+        readLatestSettledJob: (queue) => readLatestSettledJob(owner, queue),
+        enqueueAcceptedJob: (job) => {
+            enqueue(owner, project, job);
+        },
+        recordCancellationIntent: (intent) => recordCancellationIntent(owner, project, intent),
+    });
+    const createStore = (partition) => {
+        const lane = laneQuery(partition);
+        return Object.freeze({
+            hasPendingWork: storeEffect(() => owner.sql
+                .exec("SELECT 1 FROM watchdog_jobs WHERE state IN ('queued', 'running') LIMIT 1")
+                .toArray().length !== 0),
+            ingest: (job) => storeEffect(() => owner.transactionSync(() => ({
+                status: enqueue(owner, project, job) ? "queued" : "duplicate",
+            }))),
+            read: (jobId) => storeEffect(() => {
+                const parsed = readJob(owner, jobId);
+                if (parsed === undefined)
+                    return { status: "missing" };
+                return {
+                    status: "found",
+                    job: parsed.job,
+                    claimToken: parsed.row.claim_token,
+                    recoveryCount: parsed.row.recovery_count,
+                    cancellation: parsed.row.cancellation_id === null
+                        ? { status: "absent" }
+                        : {
+                            status: "present",
+                            cancellation: {
+                                jobId,
+                                cancellationId: parsed.row.cancellation_id,
+                            },
+                        },
+                };
+            }),
+            readQueueHead: (queue) => storeEffect(() => readQueueHead(owner, queue)),
+            readSettled: (limit, afterSequence) => storeEffect(() => readSettled(owner, limit, afterSequence, partition)),
+            selectAndClaim: (claimToken) => storeEffect(() => selectAndClaim(owner, project, claimToken, partition)),
+            settleExactClaim: (input) => storeEffect(() => settleExactClaim(owner, project, input)),
+            recordCancellation: (intent) => storeEffect(() => owner.transactionSync(() => {
+                const result = recordCancellationIntent(owner, project, intent);
+                return { status: result.status };
+            })),
+            failLane: (raw) => storeEffect(() => {
+                const input = parseLaneFailure(raw);
+                return owner.transactionSync(() => {
+                    // Under the declared state grammar, DESC puts running before queued.
+                    const rows = owner.sql
+                        .exec(`SELECT ${columns} FROM watchdog_jobs
+             WHERE lane = ? AND state IN ('queued', 'running')
+             ORDER BY state DESC, sequence ASC LIMIT ?`, input.lane, laneFailureBatchSize)
+                        .toArray();
+                    const jobs = [];
+                    for (const row of rows) {
+                        const prior = parseJobRow(row);
+                        owner.sql.exec(`UPDATE watchdog_jobs SET state = 'settled', outcome = 'failed', failure_reason = ?, claim_token = NULL
+               WHERE job_id = ? AND state IN ('queued', 'running')`, input.reason, prior.job.jobId);
+                        const settled = readJob(owner, prior.job.jobId)?.job;
+                        if (settled?.state !== "settled" || settled.outcome !== "failed")
+                            throw unavailable();
+                        projectQueue(owner, project, settled.queue, settled);
+                        jobs.push(settled);
+                    }
+                    const more = owner.sql
+                        .exec("SELECT 1 FROM watchdog_jobs WHERE lane = ? AND state IN ('queued', 'running') LIMIT 1", input.lane)
+                        .toArray().length !== 0;
+                    return { jobs, more };
+                });
+            }),
+            purgeQueued: (queue) => storeEffect(() => {
+                owner.transactionSync(() => {
+                    owner.sql.exec(`DELETE FROM watchdog_jobs
+              WHERE queue_name = ? AND state = 'queued'`, queue);
+                    projectQueue(owner, project, queue);
+                });
+            }),
+            nextRunningClaim: () => storeEffect(() => {
+                const raw = owner.sql
+                    .exec(`SELECT ${columns}
+               FROM watchdog_jobs
+              WHERE state = 'running' AND ${lane.predicate}
+              ORDER BY sequence ASC
+              LIMIT 1`, ...lane.values)
+                    .toArray()[0];
+                if (raw === undefined)
+                    return undefined;
+                const parsed = parseJobRow(raw);
+                if (parsed.job.state !== "running" || parsed.row.claim_token === null)
+                    throw unavailable();
+                return {
+                    job: parsed.job,
+                    claimToken: parsed.row.claim_token,
+                    recoveryCount: parsed.row.recovery_count,
+                };
+            }),
+            reconcileDisappearedClaim: (input) => storeEffect(() => owner.transactionSync(() => {
+                const prior = readJob(owner, input.job.jobId);
+                if (prior === undefined)
+                    return { status: "missing" };
+                if (prior.job.state !== "running" ||
+                    prior.row.claim_token !== input.claimToken ||
+                    prior.row.recovery_count !== input.recoveryCount)
+                    return { status: "conflict" };
+                if (input.disposition === "requeue" &&
+                    prior.row.cancellation_id === null) {
+                    owner.sql.exec(`UPDATE watchdog_jobs
+                  SET state = 'queued', claim_token = NULL,
+                      recovery_count = recovery_count + 1
+                WHERE job_id = ? AND state = 'running' AND claim_token = ?`, input.job.jobId, input.claimToken);
+                    projectQueue(owner, project, input.job.queue);
+                    return { status: "requeued" };
+                }
+                const cancelled = prior.row.cancellation_id !== null;
+                const reason = cancelled
+                    ? null
+                    : prior.job.recovery === undefined
+                        ? "Execution disappeared without a recovery policy"
+                        : `Restart recovery budget exhausted (${String(prior.job.recovery.maxRecoveries)} recoveries)`;
+                owner.sql.exec(`UPDATE watchdog_jobs
+                SET state = 'settled', outcome = ?, failure_reason = ?
+              WHERE job_id = ? AND state = 'running' AND claim_token = ?`, cancelled ? "cancelled" : "interrupted", reason, input.job.jobId, input.claimToken);
+                const settled = readJob(owner, input.job.jobId)?.job;
+                if (settled?.state !== "settled")
+                    return { status: "conflict" };
+                projectQueue(owner, project, settled.queue, settled);
+                return { status: "settled", job: settled };
+            })),
+        });
+    };
+    return Object.freeze({
+        store: createStore(partition),
+        partition: createStore,
+        transactional,
+    });
+}

package/dist/internal/watchdog-error.d.ts

@@ -0,0 +1,12 @@
+/** Typed failures owned by the generic Watchdog engine. */
+export declare class WatchdogError extends Error {
+    readonly _tag: "WatchdogError";
+    readonly cause: "store_unavailable" | "store_invalid" | "claim_unavailable" | "execution_failed" | "settlement_rejected" | "wake_unavailable" | "liveness_unavailable";
+    readonly underlying?: unknown;
+    constructor(failureKind: "store_unavailable" | "store_invalid" | "claim_unavailable" | "execution_failed" | "settlement_rejected" | "wake_unavailable" | "liveness_unavailable", 
+    /**
+     * The original thrown value, kept for server-side diagnosis only. `cause`
+     * is already the closed category above, so this is a separate field.
+     */
+    cause?: unknown);
+}

package/dist/internal/watchdog-error.js

@@ -0,0 +1,17 @@
+/** Typed failures owned by the generic Watchdog engine. */
+export class WatchdogError extends Error {
+    _tag = "WatchdogError";
+    cause;
+    underlying;
+    constructor(failureKind, 
+    /**
+     * The original thrown value, kept for server-side diagnosis only. `cause`
+     * is already the closed category above, so this is a separate field.
+     */
+    cause) {
+        super(`Watchdog ${failureKind.replaceAll("_", " ")}`);
+        this.name = this._tag;
+        this.cause = failureKind;
+        this.underlying = cause;
+    }
+}

package/dist/node-sqlite.d.ts

@@ -0,0 +1,17 @@
+import type { DatabaseSync } from "node:sqlite";
+import type { WatchdogSqliteOwner, WatchdogSqliteCursor, WatchdogSqliteRow, WatchdogSqliteValue } from "./effect.js";
+/** Materialized Node SQLite rows, including the exact-one native operation. */
+export type NodeSqliteCursor = WatchdogSqliteCursor & Readonly<{
+    /** Return the sole decoded row; throw for zero or multiple rows. */
+    one: () => WatchdogSqliteRow;
+}>;
+/** Concrete Node adapter; generic Watchdog owners need only toArray(). */
+export type NodeSqliteOwner = Omit<WatchdogSqliteOwner, "sql"> & Readonly<{
+    /** Statements execute synchronously against the caller-owned database. */
+    sql: Readonly<{
+        /** Decode materialized scalar rows without choosing the query owner’s schema. */
+        exec: (statement: string, ...bindings: WatchdogSqliteValue[]) => NodeSqliteCursor;
+    }>;
+}>;
+/** Adapt a caller-owned Node SQLite database; the caller retains its lifetime. */
+export declare function fromNodeSqlite(database: DatabaseSync): NodeSqliteOwner;