cairnq 0.1.0 → 0.3.0

package/dist/_protocol/sql/sqlite/fail.sql

@@ -1,16 +1,40 @@
--- Fail a task. Ownership-checked. Single CASE-based statement handles both
--- branches atomically: retryable && attempt < max_attempts -> requeue with
--- backoff (run_at = now + delay_ms); otherwise -> terminal 'failed'.
+-- Fail a task. Ownership-checked. One CASE-based statement decides all three
+-- outcomes atomically:
+--   1. a cancel was requested while it ran -> terminal 'canceled'. Cancel wins,
+--      exactly as in complete.sql: a task the user cancelled must never be
+--      redelivered, whether the attempt ended in a return or in an exception.
+--   2. retryable && attempt < max_attempts -> requeue with backoff
+--      (run_at = now + delay_ms).
+--   3. otherwise -> terminal 'failed'.
+-- The error envelope is recorded on every branch, so a canceled-while-failing
+-- task still carries why its last attempt failed. progress/message describe the
+-- attempt in flight, so only the requeue branch clears them: a terminal record
+-- keeps how far the last attempt got, a re-queued one must not advertise a dead
+-- attempt's progress bar until the next attempt overwrites it.
 -- :retryable is 0/1. :error is a JSON envelope text.
 -- params: id, worker_id, now_ms, error, retryable, delay_ms
 update cairnq_tasks
 set
-    status = case when :retryable = 1 and attempt < max_attempts then 'queued' else 'failed' end,
+    status = case
+        when cancel_requested_at_ms is not null then 'canceled'
+        when :retryable = 1 and attempt < max_attempts then 'queued'
+        else 'failed'
+    end,
     error = :error,
-    worker_id = case when :retryable = 1 and attempt < max_attempts then null else worker_id end,
-    lease_until_ms = case when :retryable = 1 and attempt < max_attempts then null else lease_until_ms end,
-    run_at_ms = case when :retryable = 1 and attempt < max_attempts then :now_ms + :delay_ms else run_at_ms end,
-    completed_at_ms = case when :retryable = 1 and attempt < max_attempts then null else :now_ms end,
+    worker_id = case when cancel_requested_at_ms is null and :retryable = 1 and attempt < max_attempts
+                     then null else worker_id end,
+    -- Unconditional, unlike worker_id above: all three branches end the attempt
+    -- that held the lease — two terminally, one to wait for redelivery — and none
+    -- of them leaves anyone owning it (see succeed.sql).
+    lease_until_ms = null,
+    run_at_ms = case when cancel_requested_at_ms is null and :retryable = 1 and attempt < max_attempts
+                     then :now_ms + :delay_ms else run_at_ms end,
+    completed_at_ms = case when cancel_requested_at_ms is null and :retryable = 1 and attempt < max_attempts
+                           then null else :now_ms end,
+    progress = case when cancel_requested_at_ms is null and :retryable = 1 and attempt < max_attempts
+                    then null else progress end,
+    message = case when cancel_requested_at_ms is null and :retryable = 1 and attempt < max_attempts
+                   then null else message end,
     updated_at_ms = :now_ms
 where id = :id
   and status = 'running'

package/dist/_protocol/sql/sqlite/list.sql

@@ -7,5 +7,7 @@ where (:status is null or status = :status)
   and (:name is null or name = :name)
   and (:root_id is null or root_id = :root_id)
   and (:correlation_id is null or correlation_id = :correlation_id)
-order by created_at_ms desc
+-- id breaks created_at_ms ties, as in claim.sql: without it, paginating with
+-- offset across same-millisecond rows could repeat or skip a task.
+order by created_at_ms desc, id desc
 limit :limit offset :offset;

package/dist/_protocol/sql/sqlite/lock_key.sql

@@ -0,0 +1,5 @@
+-- No-op on SQLite: BEGIN IMMEDIATE already serializes every keyed transaction
+-- on the database's single write lock, so there is nothing further to lock.
+-- Exists so the shared TaskStore logic can take the key lock unconditionally;
+-- see the postgres dialect for the real one.
+select 1 as locked;

package/dist/_protocol/sql/sqlite/progress.sql

@@ -1,8 +1,12 @@
 -- Update progress/message. Ownership-checked. Does not change status.
 -- params: id, worker_id, now_ms, progress, message
--- message is coalesced so progress(value) without a message keeps the prior one.
+-- Both fields are coalesced, symmetrically: progress(value) keeps the prior
+-- message, progress(null, message) keeps the prior fraction. Passing null means
+-- "leave this alone", never "clear it".
 update cairnq_tasks
-set progress = :progress, message = coalesce(:message, message), updated_at_ms = :now_ms
+set progress = coalesce(:progress, progress),
+    message = coalesce(:message, message),
+    updated_at_ms = :now_ms
 where id = :id
   and status = 'running'
   and worker_id = :worker_id

package/dist/_protocol/sql/sqlite/protocol_version.sql

@@ -0,0 +1,4 @@
+-- The storage's protocol major, from cairnq_meta (written by the migrations).
+-- Returns no row on a database from before the first migration.
+-- params: (none)
+select value from cairnq_meta where key = 'protocol_version';

package/dist/_protocol/sql/sqlite/purge.sql

@@ -0,0 +1,18 @@
+-- Retention: delete terminal tasks that completed before a cutoff. Nothing else
+-- ever removes rows, so without this a long-lived database only grows.
+-- Bounded by :limit so a large backlog is drained in short transactions instead
+-- of one long write that blocks every other writer. The key pointer of a purged
+-- task goes with it via cairnq_task_keys' ON DELETE CASCADE.
+-- The LIMIT lives in a subquery: plain `delete ... limit` needs a non-default
+-- SQLite build option.
+-- params: before_ms, limit
+delete from cairnq_tasks
+where id in (
+    select id from cairnq_tasks
+    where status in ('succeeded', 'failed', 'canceled')
+      and completed_at_ms is not null
+      and completed_at_ms < :before_ms
+    order by completed_at_ms asc
+    limit :limit
+)
+returning id;

package/dist/_protocol/sql/sqlite/recover_leases.sql

@@ -1,15 +1,33 @@
 -- Reclaim tasks whose lease expired. Run inside the same write transaction as
--- claim, just before it. attempt < max_attempts -> back to 'queued' for redelivery;
--- otherwise -> 'failed' with a lease-expired error envelope.
+-- claim, just before it. Three outcomes, mirroring fail.sql:
+--   1. a cancel was requested before the worker died -> terminal 'canceled'
+--      (a cancelled task must never be redelivered by the crash path either);
+--   2. attempt < max_attempts -> back to 'queued' for redelivery;
+--   3. otherwise -> terminal 'failed' with a lease-expired error envelope.
 -- params: now_ms, lease_expired_error (JSON envelope text)
 update cairnq_tasks
 set
-    status = case when attempt < max_attempts then 'queued' else 'failed' end,
-    worker_id = case when attempt < max_attempts then null else worker_id end,
+    status = case
+        when cancel_requested_at_ms is not null then 'canceled'
+        when attempt < max_attempts then 'queued'
+        else 'failed'
+    end,
+    worker_id = case when cancel_requested_at_ms is null and attempt < max_attempts
+                     then null else worker_id end,
     lease_until_ms = null,
-    run_at_ms = case when attempt < max_attempts then :now_ms else run_at_ms end,
-    error = case when attempt >= max_attempts then :lease_expired_error else error end,
-    completed_at_ms = case when attempt >= max_attempts then :now_ms else completed_at_ms end,
+    run_at_ms = case when cancel_requested_at_ms is null and attempt < max_attempts
+                     then :now_ms else run_at_ms end,
+    -- Only the failed branch records lease expiry: a canceled task did not fail.
+    error = case when cancel_requested_at_ms is null and attempt >= max_attempts
+                 then :lease_expired_error else error end,
+    completed_at_ms = case when cancel_requested_at_ms is null and attempt < max_attempts
+                           then completed_at_ms else :now_ms end,
+    -- Only the requeue branch clears them: they describe the dead attempt, and a
+    -- task waiting to be redelivered must not report its progress bar.
+    progress = case when cancel_requested_at_ms is null and attempt < max_attempts
+                    then null else progress end,
+    message = case when cancel_requested_at_ms is null and attempt < max_attempts
+                   then null else message end,
     updated_at_ms = :now_ms
 where status = 'running'
   and lease_until_ms is not null

package/dist/_protocol/sql/sqlite/retry.sql

@@ -10,6 +10,9 @@ set
     run_at_ms = :now_ms,
     cancel_requested_at_ms = null,
     completed_at_ms = null,
+    -- The previous attempt's progress bar dies with the attempt.
+    progress = null,
+    message = null,
     attempt = case when :reset_attempt = 1 then 0 else attempt end,
     updated_at_ms = :now_ms
 where id = :id and status in ('failed', 'canceled')

package/dist/_protocol/sql/sqlite/stats.sql

@@ -0,0 +1,8 @@
+-- Queue depth at a glance: task counts grouped by queue and status. Read-only.
+-- A queue appears only while it has rows — terminal tasks count until purge
+-- removes them. The SDK zero-fills the statuses a queue has no rows in.
+-- params: (none)
+select queue, status, count(*) as count
+from cairnq_tasks
+group by queue, status
+order by queue asc, status asc;

package/dist/_protocol/sql/sqlite/succeed.sql

@@ -6,6 +6,10 @@ set
     result = :result,
     progress = 1.0,
     message = coalesce(:message, message),
+    -- A lease describes an attempt in flight; this one just ended. worker_id is
+    -- what carries the audit trail (who ran it), so nothing is lost by clearing
+    -- it, and the terminal-lease invariant holds — see PROTOCOL.md §Lease model.
+    lease_until_ms = null,
     completed_at_ms = :now_ms,
     updated_at_ms = :now_ms
 where id = :id

package/dist/client.d.ts

@@ -1,5 +1,5 @@
-import { type Task } from "./models.js";
-import type { ListInput, SubmitInput, TaskStore } from "./store/base.js";
+import { type Task, type TaskStatus } from "./models.js";
+import type { ListInput, PurgeInput, SubmitInput, TaskStore } from "./store/base.js";
 import { type TaskDef } from "./task.js";
 export type SubmitOptions = Omit<SubmitInput, "name" | "payload">;
 export interface CallOptions extends SubmitOptions {
@@ -34,6 +34,14 @@ export declare class CairnQ {
     retryByKey(key: string, opts?: {
         resetAttempt?: boolean;
     }): Promise<Task | null>;
+    /** Delete terminal tasks that finished more than `olderThanMs` ago and return
+     * their ids. Nothing else in CairnQ removes rows, so a long-lived database
+     * needs this on a schedule. Each call is bounded by `limit` to keep the write
+     * short; loop until it returns fewer than `limit`. */
+    purge(input?: PurgeInput): Promise<string[]>;
+    /** Task counts per queue, keyed by status and zero-filled across all statuses
+     * — `(await stats()).default.queued` is the backlog of a queue. */
+    stats(): Promise<Record<string, Record<TaskStatus, number>>>;
     wait(taskId: string, opts?: {
         timeoutMs?: number;
         pollMs?: number;

package/dist/client.js

@@ -51,6 +51,18 @@ export class CairnQ {
     retryByKey(key, opts) {
         return this._store.retryByKey(key, opts);
     }
+    /** Delete terminal tasks that finished more than `olderThanMs` ago and return
+     * their ids. Nothing else in CairnQ removes rows, so a long-lived database
+     * needs this on a schedule. Each call is bounded by `limit` to keep the write
+     * short; loop until it returns fewer than `limit`. */
+    purge(input) {
+        return this._store.purge(input);
+    }
+    /** Task counts per queue, keyed by status and zero-filled across all statuses
+     * — `(await stats()).default.queued` is the backlog of a queue. */
+    stats() {
+        return this._store.stats();
+    }
     wait(taskId, opts = {}) {
         return pollWait(this._store, taskId, {
             timeoutMs: opts.timeoutMs ?? 30_000,

package/dist/context.d.ts

@@ -8,6 +8,9 @@ export declare class TaskContext {
     private readonly task;
     readonly workerId: string;
     private readonly leaseMs;
+    private readonly abort;
+    private leaseLost;
+    private cancelSeen;
     constructor(store: TaskStore, task: Task, workerId: string, leaseMs: number);
     get taskId(): string;
     get name(): string;
@@ -17,9 +20,22 @@ export declare class TaskContext {
     get rootId(): string | null;
     get correlationId(): string | null;
     get payload(): any;
+    /**
+     * True once this worker has lost the task's lease — it expired and another
+     * worker reclaimed it. Nothing this handler writes will be recorded any more
+     * and the task is already running elsewhere, so a long handler should check
+     * this (or `signal`) and bail out instead of continuing to do side effects.
+     */
+    get lostLease(): boolean;
+    /** Aborts when the lease is lost. Pass it to fetch / any AbortSignal-aware API. */
+    get signal(): AbortSignal;
+    /** @internal Called by the worker when an owned write reports a lost lease. */
+    markLeaseLost(): void;
+    private observe;
+    private owned;
     progress(value: number | null, message?: string | null): Promise<Task>;
     heartbeat(): Promise<Task>;
-    /** Cooperative cancel check. */
+    /** Cooperative cancel check. Free once a heartbeat has already seen the flag. */
     canceled(): Promise<boolean>;
     /** Submit a child task; parent/root/correlation are wired automatically. */
     submit(name: string, payload?: unknown, opts?: SubmitOptions): Promise<Task>;

package/dist/context.js

@@ -1,3 +1,4 @@
+import { LostLease } from "./errors.js";
 import { cancelRequested } from "./models.js";
 import { taskName } from "./task.js";
 import { pollWait } from "./wait.js";
@@ -7,6 +8,11 @@ export class TaskContext {
     task;
     workerId;
     leaseMs;
+    abort = new AbortController();
+    leaseLost = false;
+    // Cancellation is monotonic: once the DB has told us a cancel was requested it
+    // can't be taken back, so canceled() can answer from this without a re-read.
+    cancelSeen = false;
     constructor(store, task, workerId, leaseMs) {
         this.store = store;
         this.task = task;
@@ -37,27 +43,75 @@ export class TaskContext {
     get payload() {
         return this.task.payload;
     }
+    /**
+     * True once this worker has lost the task's lease — it expired and another
+     * worker reclaimed it. Nothing this handler writes will be recorded any more
+     * and the task is already running elsewhere, so a long handler should check
+     * this (or `signal`) and bail out instead of continuing to do side effects.
+     */
+    get lostLease() {
+        return this.leaseLost;
+    }
+    /** Aborts when the lease is lost. Pass it to fetch / any AbortSignal-aware API. */
+    get signal() {
+        return this.abort.signal;
+    }
+    /** @internal Called by the worker when an owned write reports a lost lease. */
+    markLeaseLost() {
+        if (this.leaseLost)
+            return;
+        this.leaseLost = true;
+        this.abort.abort(new LostLease(this.task.id));
+    }
+    // Every owned write returns the current row, so cancellation and lease loss
+    // ride along on writes the handler was making anyway.
+    observe(task) {
+        if (cancelRequested(task))
+            this.cancelSeen = true;
+        return task;
+    }
+    async owned(write) {
+        // Short-circuit once the lease is known lost: nothing this context writes
+        // may be recorded any more. Locally, not just via the store's ownership
+        // check — after an abandoned (timed-out) attempt the same worker may
+        // re-claim this task under the same workerId, and a zombie handler's write
+        // would then pass ownership against the NEW attempt.
+        if (this.leaseLost)
+            throw new LostLease(this.task.id);
+        try {
+            return this.observe(await write());
+        }
+        catch (err) {
+            if (err instanceof LostLease)
+                this.markLeaseLost();
+            throw err;
+        }
+    }
     async progress(value, message = null) {
-        return this.store.progress({
+        return this.owned(() => this.store.progress({
             taskId: this.task.id,
             workerId: this.workerId,
             progress: value,
             message,
-        });
+        }));
     }
     async heartbeat() {
-        return this.store.heartbeat({
+        return this.owned(() => this.store.heartbeat({
             taskId: this.task.id,
             workerId: this.workerId,
             leaseMs: this.leaseMs,
-        });
+        }));
     }
-    /** Cooperative cancel check. */
+    /** Cooperative cancel check. Free once a heartbeat has already seen the flag. */
     async canceled() {
+        if (this.cancelSeen)
+            return true;
         const t = await this.store.get(this.task.id);
         if (!t)
             return true;
-        return cancelRequested(t) || t.status === "canceled";
+        if (cancelRequested(t))
+            this.cancelSeen = true;
+        return this.cancelSeen || t.status === "canceled";
     }
     async submit(task, payload, opts = {}) {
         return this.store.submit({

package/dist/errors.d.ts

@@ -1,3 +1,4 @@
+import { type Task } from "./models.js";
 /** The single shape of the JSON error envelope (see PROTOCOL.md). Everything that
  * records an error — a handler exception, a missing handler, lease expiry, a thrown
  * TaskError — builds it here, so the contract's fields live in one place. */
@@ -9,15 +10,23 @@ export declare function errorEnvelope(e: {
     details?: Record<string, unknown>;
 }): Record<string, unknown>;
 export declare class CairnQError extends Error {
+    constructor(message?: string);
 }
 export declare class AlreadyExists extends CairnQError {
     key: string;
     constructor(key: string);
 }
-/** wait/call did not reach a terminal status in time. The task keeps running. */
+/** wait/call did not reach a terminal status in time. The task keeps running.
+ * `task` is the last snapshot wait() observed (null if get() found nothing), and
+ * the message says what state it was stuck in — a queued-never-claimed task is
+ * the classic first-run failure (no worker, no handler, wrong queue or file). */
 export declare class TaskTimeout extends CairnQError {
     taskId: string;
-    constructor(taskId: string);
+    readonly task: Task | null;
+    constructor(taskId: string, opts?: {
+        timeoutMs?: number;
+        task?: Task | null;
+    });
 }
 /** A waited-on task ended in `failed`. The envelope's fields are unpacked onto the
  * error — read `e.code` / `e.message` / `e.retryable` / `e.details` instead of
@@ -42,6 +51,13 @@ export declare class LostLease extends CairnQError {
 export declare class ProtocolVersionMismatch extends CairnQError {
     constructor(message: string);
 }
+/** A value could not be encoded for a protocol JSON column (non-finite number,
+ * BigInt, circular structure, …). Raised at the boundary — submit rejects with
+ * it, and a worker records a handler result that triggers it as a permanent
+ * `unserializable_result` failure. The Python SDK raises the same named error. */
+export declare class SerializationError extends CairnQError {
+    constructor(message: string);
+}
 /** Throw inside a handler to control how the failure is recorded. Defaults to
  * non-retryable so deterministic errors fail fast instead of burning retries.
  * Any other thrown value is treated as retryable. */

package/dist/errors.js

@@ -1,3 +1,5 @@
+import { nowMs } from "./ids.js";
+import { cancelRequested, isQueued } from "./models.js";
 /** The single shape of the JSON error envelope (see PROTOCOL.md). Everything that
  * records an error — a handler exception, a missing handler, lease expiry, a thrown
  * TaskError — builds it here, so the contract's fields live in one place. */
@@ -11,6 +13,13 @@ export function errorEnvelope(e) {
     };
 }
 export class CairnQError extends Error {
+    constructor(message) {
+        super(message);
+        // Subclasses each set their own; without this a bare CairnQError reports
+        // "Error", and `err.name` is how callers (and the conformance runner) tell
+        // one apart from another.
+        this.name = "CairnQError";
+    }
 }
 export class AlreadyExists extends CairnQError {
     key;
@@ -20,13 +29,40 @@ export class AlreadyExists extends CairnQError {
         this.name = "AlreadyExists";
     }
 }
-/** wait/call did not reach a terminal status in time. The task keeps running. */
+/** One line of "why hasn't this finished" from the last snapshot wait()
+ * observed. No worker running, no handler for the name, wrong queue, and two
+ * processes on different database files all look identical from the API side —
+ * queued, never claimed — so that case names the likely causes. */
+function timeoutDetail(task) {
+    if (!task)
+        return "task not found — wrong database file, or already purged?";
+    if (isQueued(task)) {
+        const delayMs = task.run_at_ms - nowMs();
+        if (task.attempt === 0 && delayMs <= 0) {
+            return (`never claimed by a worker — is a worker running with a handler for ` +
+                `'${task.name}' on queue '${task.queue}', against this same database?`);
+        }
+        const next = delayMs > 0 ? `, next run in ~${delayMs}ms` : "";
+        return `still queued (attempt ${task.attempt}/${task.max_attempts})${next}`;
+    }
+    if (cancelRequested(task))
+        return "cancel requested, waiting for the handler to observe it";
+    return `still running (attempt ${task.attempt}/${task.max_attempts})`;
+}
+/** wait/call did not reach a terminal status in time. The task keeps running.
+ * `task` is the last snapshot wait() observed (null if get() found nothing), and
+ * the message says what state it was stuck in — a queued-never-claimed task is
+ * the classic first-run failure (no worker, no handler, wrong queue or file). */
 export class TaskTimeout extends CairnQError {
     taskId;
-    constructor(taskId) {
-        super(`task ${taskId} did not finish in time`);
+    task;
+    constructor(taskId, opts = {}) {
+        super(opts.timeoutMs == null
+            ? `task ${taskId} did not finish in time`
+            : `task ${taskId} did not finish within ${opts.timeoutMs}ms: ${timeoutDetail(opts.task ?? null)}`);
         this.taskId = taskId;
         this.name = "TaskTimeout";
+        this.task = opts.task ?? null;
     }
 }
 /** A waited-on task ended in `failed`. The envelope's fields are unpacked onto the
@@ -72,6 +108,16 @@ export class ProtocolVersionMismatch extends CairnQError {
         this.name = "ProtocolVersionMismatch";
     }
 }
+/** A value could not be encoded for a protocol JSON column (non-finite number,
+ * BigInt, circular structure, …). Raised at the boundary — submit rejects with
+ * it, and a worker records a handler result that triggers it as a permanent
+ * `unserializable_result` failure. The Python SDK raises the same named error. */
+export class SerializationError extends CairnQError {
+    constructor(message) {
+        super(message);
+        this.name = "SerializationError";
+    }
+}
 /** Throw inside a handler to control how the failure is recorded. Defaults to
  * non-retryable so deterministic errors fail fast instead of burning retries.
  * Any other thrown value is treated as retryable. */

package/dist/index.d.ts

@@ -7,7 +7,8 @@ export { defineTask } from "./task.js";
 export type { TaskDef } from "./task.js";
 export { SQLiteStore } from "./store/sqlite.js";
 export { PostgresStore } from "./store/postgres.js";
-export type { ListInput, SubmitInput, TaskStore, Conflict } from "./store/base.js";
+export { TaskStore } from "./store/base.js";
+export type { ListInput, PurgeInput, SubmitInput, Conflict } from "./store/base.js";
 export type { Task, TaskStatus } from "./models.js";
 export { STATUSES, isTerminal, cancelRequested, isQueued, isRunning, isSucceeded, isFailed, isCanceled, } from "./models.js";
-export { CairnQError, AlreadyExists, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, ProtocolVersionMismatch, } from "./errors.js";
+export { CairnQError, AlreadyExists, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, ProtocolVersionMismatch, SerializationError, } from "./errors.js";

package/dist/index.js

@@ -4,5 +4,6 @@ export { TaskContext } from "./context.js";
 export { defineTask } from "./task.js";
 export { SQLiteStore } from "./store/sqlite.js";
 export { PostgresStore } from "./store/postgres.js";
+export { TaskStore } from "./store/base.js";
 export { STATUSES, isTerminal, cancelRequested, isQueued, isRunning, isSucceeded, isFailed, isCanceled, } from "./models.js";
-export { CairnQError, AlreadyExists, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, ProtocolVersionMismatch, } from "./errors.js";
+export { CairnQError, AlreadyExists, TaskTimeout, TaskFailed, TaskCanceled, TaskError, LostLease, ProtocolVersionMismatch, SerializationError, } from "./errors.js";

package/dist/sql.js

@@ -1,19 +1,23 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-// Locate the shared cairnq-protocol dir. Resolution: $CAIRNQ_PROTOCOL_DIR ->
-// vendored `_protocol/` next to this module -> walk up to `cairnq-protocol/`
-// (monorepo dev). Both SDKs load the SAME .sql strings (zero-drift guarantee).
-// The dir is laid out per-dialect (sql/<dialect>/*.sql, migrations/<dialect>/*.sql)
-// so a second backend (Postgres) slots in beside sqlite; `dialect` picks the subtree.
+// Locate the shared cairnq-protocol dir. Resolution: $CAIRNQ_PROTOCOL_DIR -> walk
+// up to `cairnq-protocol/` (monorepo dev) -> vendored `_protocol/` next to this
+// module (written at publish time). Both SDKs load the SAME .sql strings
+// (zero-drift guarantee). The dir is laid out per-dialect (sql/<dialect>/*.sql,
+// migrations/<dialect>/*.sql) so a second backend (Postgres) slots in beside
+// sqlite; `dialect` picks the subtree.
+//
+// The source tree wins over the vendored copy on purpose: vendoring is a publish
+// step that also runs locally, and a stale `_protocol/` shadowing the canonical
+// SQL means edits to cairnq-protocol/ are silently not under test. An installed
+// package has no repo above it, so it falls through to the vendored copy.
 export function findProtocolRoot() {
     const env = process.env.CAIRNQ_PROTOCOL_DIR;
     if (env)
         return env;
-    let dir = dirname(fileURLToPath(import.meta.url));
-    const vendored = join(dir, "_protocol");
-    if (existsSync(join(vendored, "sql")))
-        return vendored;
+    const start = dirname(fileURLToPath(import.meta.url));
+    let dir = start;
     for (let i = 0; i < 10; i++) {
         const candidate = join(dir, "cairnq-protocol");
         if (existsSync(join(candidate, "sql")))
@@ -23,6 +27,9 @@ export function findProtocolRoot() {
             break;
         dir = parent;
     }
+    const vendored = join(start, "_protocol");
+    if (existsSync(join(vendored, "sql")))
+        return vendored;
     throw new Error("cannot locate cairnq-protocol; set CAIRNQ_PROTOCOL_DIR");
 }
 export function loadStatements(dialect = "sqlite", root = findProtocolRoot()) {