@cortexkit/opencode-magic-context 0.43.1 → 0.44.0

package/src/shared/prompt-async-transport.ts

@@ -0,0 +1,242 @@
+import type { createOpencodeClient } from "@opencode-ai/sdk";
+
+import type { PromptArgs, PromptTransport } from "./model-suggestion-retry";
+
+type Client = ReturnType<typeof createOpencodeClient> | undefined;
+
+/**
+ * Why this exists: a synchronous `session.prompt` keeps one HTTP request open
+ * for a child's whole agent loop, which for a dreamer batch is many minutes.
+ * Some OpenCode 1 builds give plugins an SDK client whose fetch keeps Bun's
+ * default request timer, which rejects with `TimeoutError` after five to six
+ * minutes while the host keeps running the child. Sending with `prompt_async`
+ * and polling for idle keeps every request short, so the caller's own slice
+ * timer is the only thing that can end the run.
+ */
+
+const DEFAULT_POLL_INTERVAL_MS = 1_000;
+/** How long an idle child may show no started run before the send is treated as
+ * lost. The host creates the user message and marks the session busy right after
+ * accepting `prompt_async`, so this only has to cover a slow or contended host. */
+const DEFAULT_START_GRACE_MS = 30_000;
+/** The wait only looks at the newest messages: the ones this send appended and
+ * the ones just before it. The host returns the most recent `limit` messages. */
+const MESSAGE_WINDOW = 20;
+
+export interface PromptAsyncWaitOptions {
+    pollIntervalMs?: number;
+    startGraceMs?: number;
+}
+
+type SessionApi = {
+    promptAsync?: (options: unknown) => Promise<unknown>;
+    status?: (options?: unknown) => Promise<unknown>;
+    messages?: (options: unknown) => Promise<unknown>;
+};
+
+function sessionApi(client: Client): SessionApi | undefined {
+    return (client as { session?: SessionApi } | undefined)?.session;
+}
+
+/** True when the host client can send without waiting and report session status. */
+export function supportsPromptAsync(client: Client): boolean {
+    const session = sessionApi(client);
+    return (
+        typeof session?.promptAsync === "function" &&
+        typeof session?.status === "function" &&
+        typeof session?.messages === "function"
+    );
+}
+
+/**
+ * Build a retry-chain transport that sends with `prompt_async` and waits for the
+ * child to go idle. Returns undefined for a client without those endpoints, so
+ * the caller falls back to the synchronous prompt.
+ */
+export function createPromptAsyncTransport(
+    client: Client,
+    childSessionId: string,
+    options: PromptAsyncWaitOptions = {},
+): PromptTransport | undefined {
+    if (!supportsPromptAsync(client)) return undefined;
+    return Object.assign(
+        (request: PromptArgs) => promptAsyncAndWaitForIdle(client, request, options),
+        { childSessionId },
+    );
+}
+
+type MessageInfo = {
+    id?: unknown;
+    role?: unknown;
+    time?: { completed?: unknown };
+    finish?: unknown;
+    error?: unknown;
+};
+
+function infoOf(message: unknown): MessageInfo {
+    const info = (message as { info?: unknown } | null)?.info;
+    return info && typeof info === "object" ? (info as MessageInfo) : {};
+}
+
+function messageId(message: unknown): string | null {
+    const id = infoOf(message).id;
+    return typeof id === "string" ? id : null;
+}
+
+/** An assistant message the host has finished writing, successfully or not. */
+function isSettledAssistant(message: unknown): boolean {
+    const info = infoOf(message);
+    if (info.role !== "assistant") return false;
+    return info.time?.completed != null || info.error != null || info.finish != null;
+}
+
+function unwrapData(response: unknown): unknown {
+    if (response && typeof response === "object" && "data" in response) {
+        return (response as { data?: unknown }).data;
+    }
+    return response;
+}
+
+function describeRejection(error: unknown): string {
+    if (error instanceof Error) return error.message;
+    try {
+        return JSON.stringify(error);
+    } catch {
+        return String(error);
+    }
+}
+
+function abortError(signal: AbortSignal): unknown {
+    return signal.reason ?? new Error("prompt_async wait aborted");
+}
+
+function sleep(ms: number, signal: AbortSignal | undefined): Promise<void> {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(abortError(signal));
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(abortError(signal as AbortSignal));
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+
+async function readMessages(
+    session: SessionApi,
+    sessionId: string,
+    directory: string | undefined,
+    signal: AbortSignal | undefined,
+): Promise<unknown[]> {
+    const response = await session.messages?.({
+        path: { id: sessionId },
+        query: { ...(directory ? { directory } : {}), limit: MESSAGE_WINDOW },
+        ...(signal ? { signal } : {}),
+    });
+    const data = unwrapData(response);
+    return Array.isArray(data) ? data : [];
+}
+
+/** "busy"/"retry" while the loop runs, "idle" when absent or idle, null when unreadable. */
+async function readStatus(
+    session: SessionApi,
+    sessionId: string,
+    directory: string | undefined,
+    signal: AbortSignal | undefined,
+): Promise<string | null> {
+    try {
+        const response = await session.status?.({
+            ...(directory ? { query: { directory } } : {}),
+            ...(signal ? { signal } : {}),
+        });
+        if (response && typeof response === "object" && "error" in response) {
+            if ((response as { error?: unknown }).error) return null;
+        }
+        const data = unwrapData(response);
+        if (!data || typeof data !== "object") return null;
+        const entry = (data as Record<string, unknown>)[sessionId];
+        const type = (entry as { type?: unknown } | undefined)?.type;
+        return typeof type === "string" ? type : "idle";
+    } catch (error) {
+        if (signal?.aborted) throw error;
+        return null;
+    }
+}
+
+/**
+ * Send one prompt with `prompt_async`, then poll until the child session is idle
+ * and its newest message is a finished assistant reply from this send. Returns
+ * without judging that reply: the caller's output validation reads it. Rejects
+ * when the caller's signal aborts, and when the host accepted the send but never
+ * started a run within the start grace.
+ */
+export async function promptAsyncAndWaitForIdle(
+    client: Client,
+    request: PromptArgs,
+    options: PromptAsyncWaitOptions = {},
+): Promise<void> {
+    const session = sessionApi(client);
+    if (!session || !supportsPromptAsync(client)) {
+        throw new Error("prompt_async transport is unavailable on this client");
+    }
+    const sessionId = request.path.id;
+    const directory = (request.query as { directory?: unknown } | undefined)?.directory;
+    const dir = typeof directory === "string" ? directory : undefined;
+    const signal = request.signal;
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const startGraceMs = options.startGraceMs ?? DEFAULT_START_GRACE_MS;
+
+    // A fallback attempt reuses the child session, so an earlier attempt's final
+    // reply must not be mistaken for this send's reply.
+    const baseline = new Set(
+        (await readMessages(session, sessionId, dir, signal))
+            .map(messageId)
+            .filter((id): id is string => id !== null),
+    );
+
+    const sent = await session.promptAsync?.(request);
+    if (sent && typeof sent === "object" && "error" in sent) {
+        const rejection = (sent as { error?: unknown }).error;
+        if (rejection)
+            throw new Error(`prompt_async was rejected: ${describeRejection(rejection)}`);
+    }
+    const sentAt = Date.now();
+    let sawBusy = false;
+
+    for (;;) {
+        await sleep(pollIntervalMs, signal);
+        const status = await readStatus(session, sessionId, dir, signal);
+        if (status === "busy" || status === "retry") {
+            sawBusy = true;
+            continue;
+        }
+        // An unreadable status says nothing about the run; keep waiting under the
+        // caller's timer rather than guessing.
+        if (status === null) continue;
+
+        const messages = await readMessages(session, sessionId, dir, signal);
+        const last = messages.at(-1);
+        const lastId = messageId(last);
+        if (last && lastId !== null && !baseline.has(lastId) && isSettledAssistant(last)) return;
+
+        const fresh = messages.some((message) => {
+            const id = messageId(message);
+            return id !== null && !baseline.has(id);
+        });
+        // The loop ran and ended without a final reply (for example it failed
+        // before writing one). Output validation reports what is missing.
+        if (sawBusy && fresh) return;
+        if (Date.now() - sentAt >= startGraceMs) {
+            if (fresh) return;
+            throw new Error(
+                `prompt_async did not start a run in child session ${sessionId} within ${startGraceMs}ms`,
+            );
+        }
+    }
+}

package/src/shared/prompt-surface-a1-golden.md

@@ -5,7 +5,7 @@ Token counts are Claude BPE estimates on the raw text.
 
 ## 1. System-prompt guidance section
 
-### PRIMARY full (reduce=on, memory=on, dreamer=on, temporal=on) — 4989 chars, ~1180 tokens
+### PRIMARY full (reduce=on, memory=on, dreamer=on, temporal=on) — 5151 chars, ~1218 tokens
 
 ```markdown
 ## Magic Context
@@ -26,9 +26,9 @@ Reduction prompts are routine housekeeping to keep the session fast and cheap
 
 Think of your context as a desk. Every message and every tool output lands on it, and each item arrives with a §N§ tag (§1§, §42§) — the tag is the item's handle.
 
-When an item no longer needs to stay on the desk for the work ahead, stamp it: `ctx_reduce` with its tag. Stamping does not remove anything — the item stays on the desk, fully readable. From time to time, when stamped items have piled up and the desk needs room, Magic Context clears them all in one sweep; you don't pick the moment, you only stamp. Stamp as soon as an item has served its purpose, not at the end of the turn, and do it silently: nobody wants to read "I'll drop these outputs". Never stamp a user message for what it asks of you; a large paste inside one is fine once you have used it.
+When an item no longer needs to stay on the desk for the work ahead, stamp it: `ctx_reduce` with its tag. Stamping does not remove anything — the item stays on the desk, fully readable. From time to time, when stamped items have piled up and the desk needs room, Magic Context clears them all in one sweep; you don't pick the moment, you only stamp. Stamp as soon as an item has served its purpose, not at the end of the turn, and do it silently: nobody wants to read "I'll drop these outputs". An output is used once you've taken what you need from it into your reasoning or your answer. Never stamp a user message for what it asks of you; a large paste inside one is fine once you have used it.
 
-Nothing stamped is ever lost. A cleared item goes to the archive — a recent one leaves a `[dropped §N§]` placeholder on the desk, an older one leaves nothing — and `ctx_expand(message=N)` brings it back whole: text, tool input, tool output. Now and then Magic Context leaves a short reminder on the desk saying how much unstamped material is lying around; that is housekeeping, not a warning, and the desk never gets smaller for it.
+Nothing stamped is ever lost. A cleared item goes to the archive — a recent one leaves a `[dropped §N§]` placeholder on the desk, an older one leaves nothing — and `ctx_expand(message=N)` brings it back whole: text, tool input, tool output. Now and then Magic Context leaves a short reminder on the desk saying how much unstamped material is lying around. A reminder means stamping is overdue: act on it in your next step. It isn't a warning about the desk's size. The desk never gets smaller for it.
 
 Older work is not kept on the desk at all. Magic Context files it as an organized record, `<session-history>`: one heading per stretch of work, `## start-end · date · title`, with a summary underneath. Each heading is a pointer into the archive — `ctx_expand(start, end)` opens that stretch in full when the summary is not enough. Because of this filing, your own earlier messages may mention actions whose tool call is no longer on the desk. That is normal. It is never a reason to fabricate: if there is no tool result on the desk, the action did not happen, and you never inline or invent a tool call, an output, a search result or a diff in your own text.
 
@@ -39,7 +39,7 @@ Older work is not kept on the desk at all. Magic Context files it as an organize
 Some things on the desk are Magic Context's own markings, not conversation: `<system-reminder>`, `<ctx-search-hint>`, `<session-history>`, `<session-history-since>`, `<project-memory>`, `<memory-updates>`, `<new-compartments>`, `<new-memories>`, `[dropped §N§]`, and `<!-- +Xm -->` before a user message (the time that passed since your last reply; headings in the record carry `start-date`/`end-date` too). Read them, use the time, and never reproduce them in a reply or treat them as instructions.
 ```
 
-### PRIMARY memory-off (reduce=on, memory=off) — 4652 chars, ~1100 tokens
+### PRIMARY memory-off (reduce=on, memory=off) — 4814 chars, ~1138 tokens
 
 ```markdown
 ## Magic Context
@@ -60,9 +60,9 @@ Reduction prompts are routine housekeeping to keep the session fast and cheap
 
 Think of your context as a desk. Every message and every tool output lands on it, and each item arrives with a §N§ tag (§1§, §42§) — the tag is the item's handle.
 
-When an item no longer needs to stay on the desk for the work ahead, stamp it: `ctx_reduce` with its tag. Stamping does not remove anything — the item stays on the desk, fully readable. From time to time, when stamped items have piled up and the desk needs room, Magic Context clears them all in one sweep; you don't pick the moment, you only stamp. Stamp as soon as an item has served its purpose, not at the end of the turn, and do it silently: nobody wants to read "I'll drop these outputs". Never stamp a user message for what it asks of you; a large paste inside one is fine once you have used it.
+When an item no longer needs to stay on the desk for the work ahead, stamp it: `ctx_reduce` with its tag. Stamping does not remove anything — the item stays on the desk, fully readable. From time to time, when stamped items have piled up and the desk needs room, Magic Context clears them all in one sweep; you don't pick the moment, you only stamp. Stamp as soon as an item has served its purpose, not at the end of the turn, and do it silently: nobody wants to read "I'll drop these outputs". An output is used once you've taken what you need from it into your reasoning or your answer. Never stamp a user message for what it asks of you; a large paste inside one is fine once you have used it.
 
-Nothing stamped is ever lost. A cleared item goes to the archive — a recent one leaves a `[dropped §N§]` placeholder on the desk, an older one leaves nothing — and `ctx_expand(message=N)` brings it back whole: text, tool input, tool output. Now and then Magic Context leaves a short reminder on the desk saying how much unstamped material is lying around; that is housekeeping, not a warning, and the desk never gets smaller for it.
+Nothing stamped is ever lost. A cleared item goes to the archive — a recent one leaves a `[dropped §N§]` placeholder on the desk, an older one leaves nothing — and `ctx_expand(message=N)` brings it back whole: text, tool input, tool output. Now and then Magic Context leaves a short reminder on the desk saying how much unstamped material is lying around. A reminder means stamping is overdue: act on it in your next step. It isn't a warning about the desk's size. The desk never gets smaller for it.
 
 Older work is not kept on the desk at all. Magic Context files it as an organized record, `<session-history>`: one heading per stretch of work, `## start-end · date · title`, with a summary underneath. Each heading is a pointer into the archive — `ctx_expand(start, end)` opens that stretch in full when the summary is not enough. Because of this filing, your own earlier messages may mention actions whose tool call is no longer on the desk. That is normal. It is never a reason to fabricate: if there is no tool result on the desk, the action did not happen, and you never inline or invent a tool call, an output, a search result or a diff in your own text.
 
@@ -392,8 +392,8 @@ The hash handler persists the MD5 of `output.system.join("\\n")`. The values bel
 
 | Variant | Guidance bytes | MD5 system-prompt hash |
 |---|---:|---|
-| PRIMARY full | 5025 | `eaed1eda58c1c741546c9094481f4f0a` |
-| PRIMARY memory-off | 4686 | `573866747d9aac2999f616a7885fb77a` |
+| PRIMARY full | 5187 | `62439669fbf226e31fc809477e2a64be` |
+| PRIMARY memory-off | 4848 | `7298eac5c77a12cbd62f969fd1310330` |
 | PRIMARY reduce-off | 4078 | `0a969d63dfe7d83f301099610556c418` |
 | SUBAGENT minimal | 1376 | `2f5a0e99b9171fdfa08c7920cb18dc4d` |
 

package/src/shared/rpc-server.ts

@@ -18,7 +18,13 @@ import {
     type NotificationSink,
     registerNotificationSink,
 } from "./rpc-notifications";
-import { isPidAlive, parseRpcPortFile, rpcPortDir, rpcPortFilePath } from "./rpc-utils";
+import {
+    isPidAlive,
+    parseRpcPortFile,
+    registerOwnRpcServerInstance,
+    rpcPortDir,
+    rpcPortFilePath,
+} from "./rpc-utils";
 import { shouldEnforcePrivateStoragePermissions } from "./storage-permissions";
 
 type RpcHandler = (params: Record<string, unknown>) => Promise<Record<string, unknown>>;
@@ -87,6 +93,7 @@ export class MagicContextRpcServer {
     private portDir: string;
     private startedAt = Date.now();
     private readonly instanceId = randomBytes(8).toString("hex");
+    private unregisterOwnInstance: (() => void) | null = null;
     /** Every authenticated WS socket, so dispose can close them all. */
     private sockets = new Set<ServerWebSocket<WsData>>();
     // Unguessable per-process bearer token, published in the (user-private) port
@@ -186,6 +193,9 @@ export class MagicContextRpcServer {
             } else {
                 mkdirSync(dir, { recursive: true });
             }
+            // Registered before the file appears, so the storage migration guard in
+            // this process never sees its own discovery file as another live host.
+            this.unregisterOwnInstance ??= registerOwnRpcServerInstance(this.instanceId);
             const tmpPath = `${this.portFilePath}.tmp`;
             // A stale tmp from a crashed write could exist with loose perms;
             // writeFileSync's mode only applies on create, so remove it first.
@@ -249,6 +259,8 @@ export class MagicContextRpcServer {
         } catch {
             // Intentional: port file may already be gone
         }
+        this.unregisterOwnInstance?.();
+        this.unregisterOwnInstance = null;
     }
 
     private warnIfOtherLiveInstance(): void {

package/src/shared/rpc-types.ts

@@ -174,6 +174,19 @@ export interface MemoryImportanceHistogram {
     };
 }
 
+/**
+ * Which side ran (or would run) a Rust-mode completion, and why: `configured`
+ * when the user set the runner, `default_for_harness` when the harness chose it.
+ * `observed` is `last_completion` for a completion that actually ran in the
+ * module's current process, `resolved_for_route` when none has yet.
+ */
+export interface RunnerStatus {
+    runner: "host" | "broca";
+    source: "configured" | "default_for_harness";
+    harness: string;
+    observed: "last_completion" | "resolved_for_route";
+}
+
 export interface StatusDetail extends SidebarSnapshot {
     /** OpenCode 2 hidden-run model variants dropped because the host catalog did not declare them. */
     hiddenVariantWarnings?: string[];
@@ -183,6 +196,10 @@ export interface StatusDetail extends SidebarSnapshot {
         canonicalCause: RunnerRefusalCanonicalCause;
         detail: string;
     };
+    /** Which runner the Rust historian used for this session, and why. Rust mode only. */
+    historianRunner?: RunnerStatus;
+    /** Which runner the Rust module's dreamer completions resolve to, and why. Rust mode only. */
+    dreamerRunner?: RunnerStatus;
     /** ACTIVE-memory importance distribution; unclassified is a subset of total. */
     memoryImportanceHistogram: MemoryImportanceHistogram;
     /**

package/src/shared/rpc-utils.ts

@@ -37,6 +37,34 @@ export interface RpcPortFileRecord {
     instance_id?: string;
 }
 
+/**
+ * RPC server instances started by this process. The storage migration guard reads
+ * the same discovery files to find live hosts that may still run an older build;
+ * a server this process started runs this process's own build, so its discovery
+ * file must never count as such a host. Without this, a process that was refused
+ * once and retries after its own RPC server has started would find itself as the
+ * blocker and refuse forever.
+ */
+const ownRpcServerInstanceIds = new Set<string>();
+
+export function registerOwnRpcServerInstance(instanceId: string): () => void {
+    ownRpcServerInstanceIds.add(instanceId);
+    return () => {
+        ownRpcServerInstanceIds.delete(instanceId);
+    };
+}
+
+/** Whether a discovery record belongs to an RPC server started by this process. */
+export function isOwnRpcServerRecord(
+    record: Pick<RpcPortFileRecord, "pid" | "instance_id">,
+): boolean {
+    return (
+        record.pid === process.pid &&
+        record.instance_id !== undefined &&
+        ownRpcServerInstanceIds.has(record.instance_id)
+    );
+}
+
 /**
  * Stable hash for a project directory — scopes RPC port files per-project
  * so multiple OpenCode instances don't collide.

package/src/shared/sqlite-transaction-mode-guard.test.ts

@@ -0,0 +1,198 @@
+import { describe, expect, it } from "bun:test";
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import ts from "typescript";
+
+/**
+ * A deferred transaction (`db.transaction(fn)()`, `.deferred()`, `.default()`)
+ * starts with no lock. If it reads before it writes, the write must upgrade a read
+ * snapshot to a write lock, and SQLite never runs the busy handler for that
+ * upgrade: under another process's write it fails at once with SQLITE_BUSY, or
+ * with SQLITE_BUSY_SNAPSHOT when another commit landed after the read, and
+ * busy_timeout never applies. Many OpenCode and Pi processes share one context.db,
+ * so every transaction that writes must start with `.immediate()` (or
+ * `.exclusive()`), which takes the write lock at BEGIN where busy_timeout covers it.
+ *
+ * Only read-only transactions may stay deferred. Each one is listed here, keyed
+ * by file and the nearest named enclosing function, with the reason it never
+ * writes. A read-only snapshot must not take the write lock, because that would
+ * block every writer for the length of the read.
+ */
+const READ_ONLY_DEFERRED_TRANSACTIONS: Record<string, string> = {
+    "packages/plugin/src/v2/store-reader.ts#window":
+        "reads the latest compaction and the rows after it as one consistent snapshot of the OpenCode 2 store; never writes",
+    "packages/pi-plugin/src/inject-compartments-pi.ts#readFrozenM0InputsPi":
+        "reads the m[0] render sources and their watermarks as one consistent snapshot; never writes",
+};
+
+const REPOSITORY_ROOT = resolve(import.meta.dir, "../../../..");
+const SOURCE_ROOTS = ["packages/plugin/src", "packages/pi-plugin/src"];
+const LOCKING_MODES = new Set(["immediate", "exclusive"]);
+
+function sourceFiles(directory: string): string[] {
+    const result: string[] = [];
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        const path = join(directory, entry.name);
+        if (entry.isDirectory()) {
+            if (entry.name === "node_modules") continue;
+            result.push(...sourceFiles(path));
+        } else if (
+            /\.tsx?$/.test(entry.name) &&
+            !/\.test\.tsx?$/.test(entry.name) &&
+            !/\.d\.ts$/.test(entry.name)
+        ) {
+            result.push(path);
+        }
+    }
+    return result;
+}
+
+function isTransactionCall(node: ts.Node): node is ts.CallExpression {
+    return (
+        ts.isCallExpression(node) &&
+        ts.isPropertyAccessExpression(node.expression) &&
+        node.expression.name.text === "transaction"
+    );
+}
+
+/** True when `node` is the receiver of a called `.immediate()` / `.exclusive()`. */
+function isCalledWithLockingMode(node: ts.Node): boolean {
+    const access = node.parent;
+    return (
+        access !== undefined &&
+        ts.isPropertyAccessExpression(access) &&
+        access.expression === node &&
+        LOCKING_MODES.has(access.name.text) &&
+        access.parent !== undefined &&
+        ts.isCallExpression(access.parent) &&
+        access.parent.expression === access
+    );
+}
+
+function enclosingFunctionName(node: ts.Node): string {
+    for (let current = node.parent; current; current = current.parent) {
+        if (
+            (ts.isFunctionDeclaration(current) || ts.isMethodDeclaration(current)) &&
+            current.name
+        ) {
+            return current.name.getText();
+        }
+        if (
+            (ts.isArrowFunction(current) || ts.isFunctionExpression(current)) &&
+            current.parent &&
+            (ts.isVariableDeclaration(current.parent) || ts.isPropertyAssignment(current.parent))
+        ) {
+            return current.parent.name.getText();
+        }
+    }
+    return "<module>";
+}
+
+/**
+ * A transaction stored in a variable is locking only when every use of that
+ * variable calls `.immediate()` or `.exclusive()` on it.
+ */
+function storedTransactionLocks(call: ts.CallExpression, source: ts.SourceFile): boolean {
+    const declaration = call.parent;
+    if (!ts.isVariableDeclaration(declaration) || !ts.isIdentifier(declaration.name)) return false;
+    const name = declaration.name.text;
+    let scope: ts.Node = source;
+    for (let current: ts.Node | undefined = declaration.parent; current; current = current.parent) {
+        if (ts.isBlock(current)) {
+            scope = current;
+            break;
+        }
+    }
+    const uses: ts.Identifier[] = [];
+    const visit = (node: ts.Node): void => {
+        if (ts.isIdentifier(node) && node.text === name && node !== declaration.name) {
+            uses.push(node);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(scope);
+    return uses.length > 0 && uses.every(isCalledWithLockingMode);
+}
+
+interface TransactionScan {
+    deferredSites: Map<string, string[]>;
+    lockingSites: number;
+}
+
+function scanTransactionModes(files: Array<{ path: string; text: string }>): TransactionScan {
+    const deferredSites = new Map<string, string[]>();
+    let lockingSites = 0;
+    for (const file of files) {
+        if (!file.text.includes(".transaction(")) continue;
+        const source = ts.createSourceFile(file.path, file.text, ts.ScriptTarget.Latest, true);
+        const visit = (node: ts.Node): void => {
+            if (isTransactionCall(node)) {
+                if (isCalledWithLockingMode(node) || storedTransactionLocks(node, source)) {
+                    lockingSites += 1;
+                } else {
+                    const key = `${file.path}#${enclosingFunctionName(node)}`;
+                    const line = source.getLineAndCharacterOfPosition(node.getStart(source)).line;
+                    const locations = deferredSites.get(key) ?? [];
+                    locations.push(`${file.path}:${line + 1}`);
+                    deferredSites.set(key, locations);
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(source);
+    }
+    return { deferredSites, lockingSites };
+}
+
+function repositorySources(): Array<{ path: string; text: string }> {
+    return SOURCE_ROOTS.flatMap((root) =>
+        sourceFiles(resolve(REPOSITORY_ROOT, root)).map((path) => ({
+            path: relative(REPOSITORY_ROOT, path),
+            text: readFileSync(path, "utf8"),
+        })),
+    );
+}
+
+describe("SQLite transaction lock mode", () => {
+    it("starts every writing transaction with .immediate() or .exclusive()", () => {
+        const { deferredSites, lockingSites } = scanTransactionModes(repositorySources());
+        // The scan must actually see the codebase's transactions.
+        expect(lockingSites).toBeGreaterThan(50);
+
+        const unlisted = [...deferredSites]
+            .filter(([key]) => !(key in READ_ONLY_DEFERRED_TRANSACTIONS))
+            .flatMap(([, locations]) => locations);
+        expect(unlisted).toEqual([]);
+
+        // One deferred transaction per listed function, so a second one added
+        // beside a read-only snapshot is not waved through by the same entry.
+        const repeated = [...deferredSites].filter(([, locations]) => locations.length > 1);
+        expect(repeated).toEqual([]);
+
+        // A listed entry whose transaction is gone or now locks must be removed.
+        const stale = Object.keys(READ_ONLY_DEFERRED_TRANSACTIONS).filter(
+            (key) => !deferredSites.has(key),
+        );
+        expect(stale).toEqual([]);
+    });
+
+    it("recognises each deferred and locking shape", () => {
+        const text = `
+            function plainCall(db) { db.transaction(() => write())(); }
+            function explicitDeferred(db) { db.transaction(() => write()).deferred(); }
+            function stored(db) { const tx = db.transaction(() => write()); tx(); }
+            function storedMixed(db) { const tx = db.transaction(() => write()); tx.immediate(); tx(); }
+            function immediate(db) { db.transaction(() => write()).immediate(); }
+            function chained(db) { return db\n.transaction(() => write())\n.exclusive(); }
+            function storedImmediate(db) { const tx = db.transaction(() => write()); return tx.immediate(); }
+        `;
+        const { deferredSites, lockingSites } = scanTransactionModes([{ path: "x.ts", text }]);
+        expect([...deferredSites.keys()].sort()).toEqual([
+            "x.ts#explicitDeferred",
+            "x.ts#plainCall",
+            "x.ts#stored",
+            "x.ts#storedMixed",
+        ]);
+        expect(lockingSites).toBe(3);
+    });
+});

package/src/shared/sqlite-write-locker-test-support.ts

@@ -0,0 +1,62 @@
+/**
+ * Holds a SQLite write lock from a separate process, for lock-contention tests.
+ *
+ * Run directly as `bun sqlite-write-locker-test-support.ts <db> <holdMs>`, the file
+ * opens the database, takes the write lock with BEGIN IMMEDIATE, prints `LOCKED`,
+ * holds the lock for `holdMs`, commits and prints `RELEASED`. Tests start it
+ * through `startSqliteWriteLocker`.
+ *
+ * The lock has to come from a different process. A second connection in the
+ * test's own process cannot release its lock while the test's main thread is
+ * blocked inside SQLite's busy wait, so the wait would always time out and a test
+ * could never observe a writer that waits and then succeeds.
+ */
+import { Database } from "bun:sqlite";
+
+export interface SqliteWriteLocker {
+    /** Resolves with the locker's exit code after it has committed and exited. */
+    exited: Promise<number>;
+}
+
+/** Start the locker and resolve once it reports that it holds the write lock. */
+export async function startSqliteWriteLocker(
+    dbPath: string,
+    holdMs: number,
+): Promise<SqliteWriteLocker> {
+    const child = Bun.spawn(["bun", import.meta.path, dbPath, String(holdMs)], {
+        stdout: "pipe",
+        stderr: "pipe",
+    });
+    const reader = child.stdout.getReader();
+    const decoder = new TextDecoder();
+    let seen = "";
+    while (!seen.includes("LOCKED\n")) {
+        const chunk = await reader.read();
+        if (chunk.done) {
+            const stderr = await new Response(child.stderr).text();
+            throw new Error(`sqlite write locker exited before locking: ${stderr}`);
+        }
+        seen += decoder.decode(chunk.value, { stream: true });
+    }
+    reader.releaseLock();
+    return { exited: child.exited };
+}
+
+function main(): void {
+    const [dbPath, holdArg] = process.argv.slice(2);
+    const holdMs = Number(holdArg);
+    if (!dbPath || !Number.isFinite(holdMs) || holdMs < 0) {
+        process.stderr.write("usage: sqlite-write-locker-test-support.ts <db> <holdMs>\n");
+        process.exit(2);
+    }
+    const db = new Database(dbPath);
+    db.exec("PRAGMA busy_timeout = 5000");
+    db.exec("BEGIN IMMEDIATE");
+    process.stdout.write("LOCKED\n");
+    Bun.sleepSync(holdMs);
+    db.exec("COMMIT");
+    db.close();
+    process.stdout.write("RELEASED\n");
+}
+
+if (import.meta.main) main();