@retaw106/mmc-oc 0.0.0-stage → 1.2.2

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

@@ -0,0 +1,234 @@
+import { describe, expect, it } from "bun:test";
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import ts from "typescript";
+
+/**
+ * An explicitly deferred transaction starts with no writer 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 writing transactions must acquire at BEGIN. The shared runtime defaults
+ * writable handles to IMMEDIATE; plugin/Pi call sites keep their explicit
+ * `.immediate()` / `.exclusive()` declarations as an additional intent fence.
+ *
+ * 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",
+    "packages/plugin/src/features/magic-context/message-fts-session-filter.ts#withMessageFtsSessionFilter":
+        "pins one read snapshot so the session's rowid coverage proof and the filtered message search see the same rows; never writes (read-only connections use it too)",
+    "packages/plugin/src/hooks/magic-context/lkg-persist.ts#loadPersistedLkgSlot":
+        "reads an LKG slot row and its prefix slices as one consistent snapshot even while another connection saves the slot; never writes (a failed verification clear opens its own transaction)",
+};
+
+const REPOSITORY_ROOT = resolve(import.meta.dir, "../../../..");
+const SOURCE_ROOTS = ["packages/plugin/src", "packages/pi-plugin/src"]; // fork trim: no packages/cli (T-003)
+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,
+    modes: ReadonlySet<string> = LOCKING_MODES,
+): boolean {
+    const access = node.parent;
+    return (
+        access !== undefined &&
+        ts.isPropertyAccessExpression(access) &&
+        access.expression === node &&
+        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,
+    modes: ReadonlySet<string> = LOCKING_MODES,
+): 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((use) => isCalledWithLockingMode(use, modes));
+}
+
+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("declares every audited read-only transaction explicitly deferred", () => {
+        const candidates: string[] = [];
+        for (const file of repositorySources()) {
+            const source = ts.createSourceFile(file.path, file.text, ts.ScriptTarget.Latest, true);
+            const visit = (node: ts.Node): void => {
+                if (isTransactionCall(node)) {
+                    const key = `${file.path}#${enclosingFunctionName(node)}`;
+                    if (key in READ_ONLY_DEFERRED_TRANSACTIONS) {
+                        const deferred = new Set(["deferred"]);
+                        if (
+                            !isCalledWithLockingMode(node, deferred) &&
+                            !storedTransactionLocks(node, source, deferred)
+                        )
+                            candidates.push(key);
+                    }
+                }
+                ts.forEachChild(node, visit);
+            };
+            visit(source);
+        }
+        expect(candidates.sort()).toEqual([]);
+    });
+
+    it("starts every writing transaction with .immediate() or .exclusive()", () => {
+        const { deferredSites, lockingSites } = scanTransactionModes(
+            repositorySources().filter((file) => !file.path.startsWith("packages/cli/")),
+        );
+        // 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,63 @@
+/**
+ * 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",
+        windowsHide: true,
+    });
+    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();

package/src/shared/sqlite.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "bun:test";
+import {
+    Database,
+    getSqliteMemoryStats,
+    loadSqliteModule,
+    SqliteRuntimeUnavailableError,
+} from "./sqlite";
+
+describe("SQLite runtime selector", () => {
+    it("reports live connection PRAGMAs and removes closed handles", () => {
+        const before = getSqliteMemoryStats().connectionCount;
+        const db = new Database(":memory:");
+        try {
+            db.exec("PRAGMA cache_size=-1024");
+            db.exec("CREATE VIRTUAL TABLE probe_fts USING fts5(content)");
+            const during = getSqliteMemoryStats();
+            expect(during.connectionCount).toBe(before + 1);
+            expect(during.connections.at(-1)).toMatchObject({
+                filename: ":memory:",
+                cacheSize: -1024,
+                cacheSizeUnit: "kib",
+                cacheUpperBoundBytes: 1024 * 1024,
+                fts5TableCount: 1,
+            });
+        } finally {
+            db.close();
+        }
+        expect(getSqliteMemoryStats().connectionCount).toBe(before);
+    });
+
+    it("wraps a missing node:sqlite module with the detected runtime and cause", async () => {
+        const cause = Object.assign(new Error("No such built-in module: node:sqlite"), {
+            code: "ERR_UNKNOWN_BUILTIN_MODULE",
+            name: "ResolveMessage",
+        });
+        let requestedSpecifier = "";
+        let thrown: unknown;
+
+        try {
+            await loadSqliteModule("Node.js", async (specifier) => {
+                requestedSpecifier = specifier;
+                throw cause;
+            });
+        } catch (error) {
+            thrown = error;
+        }
+
+        expect(requestedSpecifier).toBe("node:sqlite");
+        expect(thrown).toBeInstanceOf(SqliteRuntimeUnavailableError);
+        const compatibilityError = thrown as SqliteRuntimeUnavailableError;
+        expect(compatibilityError.runtime).toBe("Node.js");
+        expect(compatibilityError.specifier).toBe("node:sqlite");
+        expect(compatibilityError.message).toContain("Node.js >= 24");
+        expect(compatibilityError.message).toContain("Bun with bun:sqlite");
+        expect(compatibilityError.message).toContain("node:sqlite");
+        expect(compatibilityError.cause).toBe(cause);
+    });
+});