@davesheffer/hunch 1.8.2 → 1.9.2

package/dist/store/jsonStore.js

@@ -3,10 +3,10 @@
  * in PRs, diffable, mergeable). This layer never touches SQLite — it is the
  * authoritative read/write surface; SQLite is rebuilt from it.
  */
-import { mkdirSync, readdirSync, readFileSync, existsSync, rmSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, opendirSync, readSync, realpathSync, rmSync, } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { ENTITY_KINDS, SCHEMAS } from "../core/types.js";
-import { migrateRaw, readManifest, writeManifest, SCHEMA_VERSION } from "../core/migrate.js";
+import { BASELINE_VERSION, migrateRaw, SCHEMA_VERSION } from "../core/migrate.js";
 import { writeFileAtomic } from "../core/io.js";
 /** High-cardinality collections (symbols, edges) are stored as a single
  *  index.json array — there can be thousands, and one file per edge would create
@@ -14,6 +14,22 @@ import { writeFileAtomic } from "../core/io.js";
  *  constraints) are one file per record so they're cleanly reviewable in PRs. */
 const SINGLE_FILE = { symbols: "index.json", edges: "index.json" };
 const encode = (v) => JSON.stringify(v, null, 2) + "\n";
+/** Curated entities are intentionally small, human-reviewable records. Symbols
+ * and edges are dense indexes, so they get a much larger but still finite cap. */
+export const MAX_JSON_RECORD_BYTES = 8 * 1024 * 1024;
+export const MAX_JSON_INDEX_BYTES = 256 * 1024 * 1024;
+export const MAX_JSON_MANIFEST_BYTES = 64 * 1024;
+export const MAX_JSON_DIRECTORY_ENTRIES_PER_KIND = 100_000;
+function missing(error) {
+    return error.code === "ENOENT";
+}
+function pathIsWithin(path, parent) {
+    const rel = relative(parent, path);
+    return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+function unsafePath(path, reason) {
+    return new Error(`[hunch] refusing unsafe JSON store path ${path}: ${reason}`);
+}
 export class JsonStore {
     paths;
     _warnedForward = false;
@@ -25,8 +41,212 @@ export class JsonStore {
      *  process self-invalidates on the next read. In-process writes also invalidate
      *  explicitly (exact, independent of mtime granularity). */
     cache = new Map();
+    lexicalRoot;
+    canonicalRoot;
+    lexicalHunch;
     constructor(paths) {
         this.paths = paths;
+        this.lexicalRoot = resolve(paths.root);
+        this.canonicalRoot = realpathSync(this.lexicalRoot);
+        this.lexicalHunch = resolve(paths.hunch);
+        const hunchRelative = relative(this.lexicalRoot, this.lexicalHunch);
+        if (!hunchRelative || !pathIsWithin(this.lexicalHunch, this.lexicalRoot)) {
+            throw unsafePath(paths.hunch, "the Hunch directory is not a child of its declared store root");
+        }
+    }
+    lstatOrMissing(path) {
+        try {
+            return lstatSync(path);
+        }
+        catch (error) {
+            if (missing(error))
+                return null;
+            throw error;
+        }
+    }
+    expectedCanonical(path) {
+        const lexical = resolve(path);
+        if (!pathIsWithin(lexical, this.lexicalRoot)) {
+            throw unsafePath(path, "path escapes the declared store root");
+        }
+        return resolve(this.canonicalRoot, relative(this.lexicalRoot, lexical));
+    }
+    /** Require an ordinary, canonically-contained directory. Creation is one
+     * component at a time after its parent has been validated; recursive mkdir
+     * would otherwise traverse a malicious pre-existing symlink. */
+    safeDirectory(path, create) {
+        const lexical = resolve(path);
+        const expected = this.expectedCanonical(lexical);
+        let stat = this.lstatOrMissing(lexical);
+        if (!stat) {
+            if (!create)
+                return null;
+            mkdirSync(lexical);
+            stat = lstatSync(lexical);
+        }
+        if (stat.isSymbolicLink() || !stat.isDirectory()) {
+            throw unsafePath(lexical, "expected an ordinary directory (symlinks are not followed)");
+        }
+        const canonical = realpathSync(lexical);
+        if (canonical !== expected || !pathIsWithin(canonical, this.canonicalRoot)) {
+            throw unsafePath(lexical, "canonical directory escapes its declared store root");
+        }
+        return { lexical, canonical, stat };
+    }
+    safeHunchDirectory(create) {
+        const current = this.safeDirectory(this.lexicalHunch, false);
+        if (current || !create)
+            return current;
+        // The declared root was canonicalized in the constructor and the Hunch dir
+        // is its direct child for both public and private-overlay path builders.
+        const parent = resolve(this.lexicalHunch, "..");
+        if (parent !== this.lexicalRoot) {
+            throw unsafePath(this.lexicalHunch, "the Hunch directory is not directly beneath its store root");
+        }
+        return this.safeDirectory(this.lexicalHunch, true);
+    }
+    assertKind(kind) {
+        if (!ENTITY_KINDS.includes(kind)) {
+            throw new Error(`[hunch] unknown JSON entity kind: ${String(kind)}`);
+        }
+    }
+    safeKindDirectory(kind, create) {
+        this.assertKind(kind);
+        const hunch = this.safeHunchDirectory(create);
+        if (!hunch)
+            return null;
+        const lexical = resolve(this.paths.dir(kind));
+        if (resolve(lexical, "..") !== this.lexicalHunch || lexical !== resolve(this.lexicalHunch, kind)) {
+            throw unsafePath(lexical, `kind directory ${kind} is not directly beneath the Hunch directory`);
+        }
+        return this.safeDirectory(lexical, create);
+    }
+    maxBytes(kind) {
+        return SINGLE_FILE[kind] ? MAX_JSON_INDEX_BYTES : MAX_JSON_RECORD_BYTES;
+    }
+    assertSafeRecordId(id) {
+        // Entity schemas intentionally accept free-form IDs for backwards
+        // compatibility. The storage boundary must still reject path syntax.
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id) || id === "." || id === "..") {
+            throw new Error(`[hunch] refusing unsafe JSON record id: ${JSON.stringify(id)}`);
+        }
+    }
+    assertFileBelongsTo(directory, file) {
+        const lexical = resolve(file);
+        const rel = relative(directory.lexical, lexical);
+        if (!rel || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel) || rel.includes(sep)) {
+            throw unsafePath(file, "record path is not a direct child of its kind directory");
+        }
+        return lexical;
+    }
+    validateExistingFile(directory, file, maxBytes) {
+        const lexical = this.assertFileBelongsTo(directory, file);
+        const stat = this.lstatOrMissing(lexical);
+        if (!stat)
+            return null;
+        if (stat.isSymbolicLink() || !stat.isFile()) {
+            throw unsafePath(lexical, "expected an ordinary file (symlinks and special files are not followed)");
+        }
+        if (stat.nlink !== 1) {
+            throw unsafePath(lexical, "hard-linked records are not accepted");
+        }
+        if (stat.size > maxBytes) {
+            throw new Error(`[hunch] refusing oversized JSON file ${lexical}: ${stat.size} bytes exceeds ${maxBytes}`);
+        }
+        const canonical = realpathSync(lexical);
+        if (canonical !== resolve(directory.canonical, relative(directory.lexical, lexical))) {
+            throw unsafePath(lexical, "canonical record path escapes its kind directory");
+        }
+        return stat;
+    }
+    /** Read through the exact descriptor whose type, identity, containment, and
+     * finite size were checked. Returning null means the file is absent. */
+    readContainedFile(directory, file, maxBytes) {
+        const lexical = this.assertFileBelongsTo(directory, file);
+        const before = this.validateExistingFile(directory, lexical, maxBytes);
+        if (!before)
+            return null;
+        let descriptor;
+        try {
+            descriptor = openSync(lexical, constants.O_RDONLY | constants.O_NOFOLLOW);
+            const opened = fstatSync(descriptor);
+            const after = lstatSync(lexical);
+            if (!opened.isFile() || !after.isFile() || after.isSymbolicLink()
+                || opened.nlink !== 1 || after.nlink !== 1
+                || opened.size > maxBytes
+                || opened.dev !== before.dev || opened.ino !== before.ino
+                || after.dev !== opened.dev || after.ino !== opened.ino
+                || realpathSync(lexical) !== resolve(directory.canonical, relative(directory.lexical, lexical))) {
+                throw unsafePath(lexical, "record changed identity or containment while it was opened");
+            }
+            // Read only the byte count that passed fstat. Reading the descriptor to
+            // EOF would let an in-place grow race turn a bounded check into an
+            // unbounded allocation.
+            const bytes = Buffer.allocUnsafe(opened.size);
+            let offset = 0;
+            while (offset < bytes.length) {
+                const read = readSync(descriptor, bytes, offset, bytes.length - offset, offset);
+                if (read === 0)
+                    break;
+                offset += read;
+            }
+            return bytes.subarray(0, offset).toString("utf8");
+        }
+        finally {
+            if (descriptor !== undefined)
+                closeSync(descriptor);
+        }
+    }
+    writeContainedFile(directory, file, data, maxBytes) {
+        const lexical = this.assertFileBelongsTo(directory, file);
+        const bytes = Buffer.byteLength(data);
+        if (bytes > maxBytes) {
+            throw new Error(`[hunch] refusing oversized JSON write ${lexical}: ${bytes} bytes exceeds ${maxBytes}`);
+        }
+        // Refuse an existing symlink/hardlink/special file rather than relying on
+        // rename semantics that differ across platforms.
+        this.validateExistingFile(directory, lexical, maxBytes);
+        writeFileAtomic(lexical, data);
+        this.validateExistingFile(directory, lexical, maxBytes);
+        // Detect a kind-dir replacement around the atomic rename before reporting
+        // success. (Node has no portable openat/renameat API; this closes the static
+        // committed-symlink attack and detects the common concurrent replacement.)
+        this.safeDirectory(directory.lexical, false);
+    }
+    removeContainedFile(directory, file, maxBytes) {
+        const lexical = this.assertFileBelongsTo(directory, file);
+        if (!this.validateExistingFile(directory, lexical, maxBytes))
+            return false;
+        rmSync(lexical);
+        this.safeDirectory(directory.lexical, false);
+        return true;
+    }
+    jsonFileNames(kind) {
+        const directory = this.safeKindDirectory(kind, false);
+        if (!directory)
+            return [];
+        const names = [];
+        let entries = 0;
+        const handle = opendirSync(directory.lexical);
+        try {
+            for (;;) {
+                const entry = handle.readSync();
+                if (!entry)
+                    break;
+                entries++;
+                if (entries > MAX_JSON_DIRECTORY_ENTRIES_PER_KIND) {
+                    throw new Error(`[hunch] refusing JSON kind ${kind}: more than ${MAX_JSON_DIRECTORY_ENTRIES_PER_KIND} directory entries`);
+                }
+                if (!entry.name.endsWith(".json"))
+                    continue;
+                names.push(entry.name);
+            }
+        }
+        finally {
+            handle.closeSync();
+        }
+        this.safeDirectory(directory.lexical, false);
+        return names.sort();
     }
     /** Drop memoized loadAll results. Writes through this store invalidate the
      *  affected kind automatically; call this for OUT-OF-BAND changes to .hunch/
@@ -35,6 +255,30 @@ export class JsonStore {
     clearCache() {
         this.cache.clear();
     }
+    /** Cheap revision marker for the JSON source tree. Hunch writes records with
+     *  temp-file + rename, so every supported add/update/delete bumps the containing
+     *  kind directory's metadata. Include the manifest separately because a schema
+     *  migration can change how otherwise-identical record bytes are interpreted.
+     *  This lets long-lived readers notice another process without hashing or
+     *  reparsing the complete graph on every request. */
+    changeStamp() {
+        const hunch = this.safeHunchDirectory(false);
+        const manifestStamp = () => {
+            if (!hunch)
+                return "missing";
+            const stat = this.validateExistingFile(hunch, this.paths.manifest, MAX_JSON_MANIFEST_BYTES);
+            if (!stat)
+                return "missing";
+            return `${stat.mtimeMs}:${stat.ctimeMs}:${stat.size}`;
+        };
+        return [
+            `manifest:${manifestStamp()}`,
+            ...ENTITY_KINDS.map((kind) => {
+                const directory = this.safeKindDirectory(kind, false);
+                return `${kind}:${directory ? `${directory.stat.mtimeMs}:${directory.stat.ctimeMs}:${directory.stat.size}` : "missing"}`;
+            }),
+        ].join("|");
+    }
     invalidate(kind) {
         this.cache.delete(kind);
     }
@@ -44,17 +288,36 @@ export class JsonStore {
      *  a manifest is LEGACY — left unstamped so it defaults to the baseline and
      *  `hunch migrate` upgrades it. */
     ensureDirs() {
-        const fresh = !existsSync(this.paths.hunch);
-        mkdirSync(this.paths.hunch, { recursive: true });
+        const fresh = !this.safeHunchDirectory(false);
+        const hunch = this.safeHunchDirectory(true);
+        // Preflight every existing kind before creating anything else. An unsafe
+        // committed kind symlink therefore fails init without partially scaffolding.
+        for (const kind of ENTITY_KINDS)
+            this.safeKindDirectory(kind, false);
         for (const kind of ENTITY_KINDS)
-            mkdirSync(this.paths.dir(kind), { recursive: true });
-        if (fresh && !existsSync(this.paths.manifest))
-            writeManifest(this.paths, SCHEMA_VERSION);
+            this.safeKindDirectory(kind, true);
+        const manifest = this.validateExistingFile(hunch, this.paths.manifest, MAX_JSON_MANIFEST_BYTES);
+        if (fresh && !manifest) {
+            this.writeContainedFile(hunch, this.paths.manifest, JSON.stringify({ schema_version: SCHEMA_VERSION }, null, 2) + "\n", MAX_JSON_MANIFEST_BYTES);
+        }
     }
     /** The on-disk schema version (from the manifest), read FRESH each call so a
      *  long-lived process (the MCP server) reflects an out-of-band `hunch migrate`. */
     schemaVersion() {
-        const v = readManifest(this.paths).schema_version;
+        const hunch = this.safeHunchDirectory(false);
+        let v = BASELINE_VERSION;
+        if (hunch) {
+            const text = this.readContainedFile(hunch, this.paths.manifest, MAX_JSON_MANIFEST_BYTES);
+            if (text !== null) {
+                try {
+                    const manifest = JSON.parse(text);
+                    if (typeof manifest.schema_version === "number" && Number.isInteger(manifest.schema_version)) {
+                        v = manifest.schema_version;
+                    }
+                }
+                catch { /* corrupt manifests intentionally retain baseline semantics */ }
+            }
+        }
         if (v > SCHEMA_VERSION && !this._warnedForward) {
             this._warnedForward = true;
             console.warn(`[hunch] .hunch/ was written by a newer schema (v${v} > v${SCHEMA_VERSION}); ` +
@@ -72,14 +335,15 @@ export class JsonStore {
         const single = SINGLE_FILE[kind];
         if (single)
             return join(this.paths.dir(kind), single);
+        this.assertSafeRecordId(id);
         return join(this.paths.dir(kind), `${id}.json`);
     }
     /** Load every record of a kind, validated against its schema. Memoized — the
      *  returned array is shared and MUST be treated read-only (every caller already
      *  derives via filter/map/sort, which copy). Invalidated on write. */
     loadAll(kind) {
-        const dir = this.paths.dir(kind);
-        const mtimeMs = existsSync(dir) ? statSync(dir).mtimeMs : 0;
+        const directory = this.safeKindDirectory(kind, false);
+        const mtimeMs = directory?.stat.mtimeMs ?? 0;
         const hit = this.cache.get(kind);
         if (hit && hit.mtimeMs === mtimeMs)
             return hit.data;
@@ -90,20 +354,21 @@ export class JsonStore {
     /** Uncached disk read + validate. Invalid records are skipped with a warning
      *  rather than crashing the whole load. */
     readAllFromDisk(kind) {
-        const dir = this.paths.dir(kind);
-        if (!existsSync(dir))
+        const directory = this.safeKindDirectory(kind, false);
+        if (!directory)
             return [];
         const schema = SCHEMAS[kind];
         const out = [];
         const version = this.schemaVersion(); // read the manifest ONCE per load, not per record
         const single = SINGLE_FILE[kind];
         if (single) {
-            const f = join(dir, single);
-            if (!existsSync(f))
-                return [];
+            const f = join(directory.lexical, single);
             let arr;
             try {
-                arr = JSON.parse(readFileSync(f, "utf8"));
+                const text = this.readContainedFile(directory, f, this.maxBytes(kind));
+                if (text === null)
+                    return [];
+                arr = JSON.parse(text);
             }
             catch (e) {
                 console.warn(`[hunch] skipping corrupt ${kind}/${single}: ${e.message}`);
@@ -118,12 +383,13 @@ export class JsonStore {
             }
             return out;
         }
-        for (const name of readdirSync(dir)) {
-            if (!name.endsWith(".json"))
-                continue;
+        for (const name of this.jsonFileNames(kind)) {
             let raw;
             try {
-                raw = JSON.parse(readFileSync(join(dir, name), "utf8"));
+                const text = this.readContainedFile(directory, join(directory.lexical, name), this.maxBytes(kind));
+                if (text === null)
+                    continue;
+                raw = JSON.parse(text);
             }
             catch (e) {
                 console.warn(`[hunch] skipping corrupt ${kind}/${name}: ${e.message}`);
@@ -141,21 +407,23 @@ export class JsonStore {
     put(kind, record) {
         const schema = SCHEMAS[kind];
         const validated = schema.parse(record);
-        mkdirSync(this.paths.dir(kind), { recursive: true });
         const single = SINGLE_FILE[kind];
+        if (!single)
+            this.assertSafeRecordId(validated.id);
+        const directory = this.safeKindDirectory(kind, true);
         if (single) {
             // Operate on the RAW array (NOT the validating loadAll) so updating one
             // record can't silently drop schema-invalid / future-schema siblings — the
             // same reason delete() reads raw. Keep the index sorted by id (stable diff,
             // and agrees with the merge driver so a re-index after a merge is a no-op).
             const f = this.fileFor(kind, validated.id);
-            const arr = this.readRawArray(f).filter((r) => r?.id !== validated.id);
+            const arr = this.readRawArray(kind, directory, f).filter((r) => r?.id !== validated.id);
             arr.push(validated);
             arr.sort((a, b) => String(a?.id).localeCompare(String(b?.id)));
-            writeFileAtomic(f, encode(arr));
+            this.writeContainedFile(directory, f, encode(arr), this.maxBytes(kind));
         }
         else {
-            writeFileAtomic(this.fileFor(kind, validated.id), encode(validated));
+            this.writeContainedFile(directory, this.fileFor(kind, validated.id), encode(validated), this.maxBytes(kind));
         }
         this.invalidate(kind);
         return validated;
@@ -164,33 +432,42 @@ export class JsonStore {
     replaceAll(kind, records) {
         const schema = SCHEMAS[kind];
         const validated = records.map((r) => schema.parse(r));
-        this.invalidate(kind);
-        mkdirSync(this.paths.dir(kind), { recursive: true });
         const single = SINGLE_FILE[kind];
+        if (!single) {
+            for (const record of validated)
+                this.assertSafeRecordId(String(record.id));
+        }
+        this.invalidate(kind);
+        const directory = this.safeKindDirectory(kind, true);
         if (single) {
             // Sorted by id so the index has ONE canonical order — re-indexing after a
             // git merge (which the driver also id-sorts) doesn't churn the whole file.
             validated.sort((a, b) => String(a.id).localeCompare(String(b.id)));
-            writeFileAtomic(this.fileFor(kind, "index"), encode(validated));
+            this.writeContainedFile(directory, this.fileFor(kind, "index"), encode(validated), this.maxBytes(kind));
             return;
         }
-        // one file per record: clear stale files, then write
-        for (const name of existsSync(this.paths.dir(kind)) ? readdirSync(this.paths.dir(kind)) : []) {
-            if (name.endsWith(".json"))
-                rmSync(join(this.paths.dir(kind), name));
+        // One file per record: preflight EVERY existing JSON file before deleting
+        // any, so one malicious symlink cannot cause a partially-cleared store.
+        const existing = this.jsonFileNames(kind);
+        for (const name of existing) {
+            this.validateExistingFile(directory, join(directory.lexical, name), this.maxBytes(kind));
+        }
+        for (const name of existing) {
+            this.removeContainedFile(directory, join(directory.lexical, name), this.maxBytes(kind));
         }
         for (const r of validated) {
-            writeFileAtomic(this.fileFor(kind, r.id), encode(r));
+            const id = r.id;
+            this.writeContainedFile(directory, this.fileFor(kind, id), encode(r), this.maxBytes(kind));
         }
     }
     /** Read a single-file index as a raw array (no validation). Missing/empty → [].
      *  A non-empty file that fails to parse THROWS — we must never silently treat a
      *  corrupt index as empty and then rewrite it, which would flatten every existing
      *  record. (`hunch index` rebuilds from scratch via replaceAll to recover.) */
-    readRawArray(f) {
-        if (!existsSync(f))
+    readRawArray(kind, directory, f) {
+        const text = this.readContainedFile(directory, f, this.maxBytes(kind));
+        if (text === null)
             return [];
-        const text = readFileSync(f, "utf8");
         if (!text.trim())
             return [];
         let v;
@@ -211,21 +488,27 @@ export class JsonStore {
     delete(kind, id) {
         const single = SINGLE_FILE[kind];
         if (single) {
+            const directory = this.safeKindDirectory(kind, false);
+            if (!directory)
+                return false;
             const f = this.fileFor(kind, "index");
-            if (!existsSync(f))
+            const arr = this.readRawArray(kind, directory, f);
+            if (!this.validateExistingFile(directory, f, this.maxBytes(kind)))
                 return false;
-            const arr = this.readRawArray(f);
             const next = arr.filter((r) => r?.id !== id);
             if (next.length === arr.length)
                 return false;
-            writeFileAtomic(f, encode(next));
+            this.writeContainedFile(directory, f, encode(next), this.maxBytes(kind));
             this.invalidate(kind);
             return true;
         }
+        this.assertSafeRecordId(id);
+        const directory = this.safeKindDirectory(kind, false);
+        if (!directory)
+            return false;
         const f = this.fileFor(kind, id);
-        if (!existsSync(f))
+        if (!this.removeContainedFile(directory, f, this.maxBytes(kind)))
             return false;
-        rmSync(f);
         this.invalidate(kind);
         return true;
     }
@@ -234,18 +517,20 @@ export class JsonStore {
      *  to empty the PUBLIC store after its records have been moved into the private
      *  overlay. Returns the number of files removed. Invalidates the memoized load. */
     dropAll(kind) {
-        const dir = this.paths.dir(kind);
-        if (!existsSync(dir))
+        const directory = this.safeKindDirectory(kind, false);
+        if (!directory)
             return 0;
-        let n = 0;
-        for (const name of readdirSync(dir)) {
-            if (name.endsWith(".json")) {
-                rmSync(join(dir, name));
-                n++;
-            }
+        const names = this.jsonFileNames(kind);
+        // Preflight first: never partially delete a kind because a later entry is a
+        // symlink, device, oversized file, or hard link.
+        for (const name of names) {
+            this.validateExistingFile(directory, join(directory.lexical, name), this.maxBytes(kind));
+        }
+        for (const name of names) {
+            this.removeContainedFile(directory, join(directory.lexical, name), this.maxBytes(kind));
         }
         this.invalidate(kind);
-        return n;
+        return names.length;
     }
     /** Persist a schema migration: rewrite every LOADABLE record in its current shape.
      *  A record that still fails validation after migration is kept untouched (never
@@ -257,18 +542,19 @@ export class JsonStore {
         this.cache.clear(); // every record is rewritten; drop all memoized loads
         const version = this.schemaVersion(); // read once; we're migrating FROM this
         for (const kind of ENTITY_KINDS) {
-            const dir = this.paths.dir(kind);
-            if (!existsSync(dir))
+            const directory = this.safeKindDirectory(kind, false);
+            if (!directory)
                 continue;
             const schema = SCHEMAS[kind];
             const single = SINGLE_FILE[kind];
             if (single) {
-                const f = join(dir, single);
-                if (!existsSync(f))
-                    continue;
+                const f = join(directory.lexical, single);
                 let arr;
                 try {
-                    arr = JSON.parse(readFileSync(f, "utf8"));
+                    const text = this.readContainedFile(directory, f, this.maxBytes(kind));
+                    if (text === null)
+                        continue;
+                    arr = JSON.parse(text);
                 }
                 catch {
                     skipped++;
@@ -290,16 +576,17 @@ export class JsonStore {
                         skipped++;
                     }
                 }
-                writeFileAtomic(f, encode(kept));
+                this.writeContainedFile(directory, f, encode(kept), this.maxBytes(kind));
             }
             else {
-                for (const name of readdirSync(dir)) {
-                    if (!name.endsWith(".json"))
-                        continue;
-                    const p = join(dir, name);
+                for (const name of this.jsonFileNames(kind)) {
+                    const p = join(directory.lexical, name);
                     let raw;
                     try {
-                        raw = JSON.parse(readFileSync(p, "utf8"));
+                        const text = this.readContainedFile(directory, p, this.maxBytes(kind));
+                        if (text === null)
+                            continue;
+                        raw = JSON.parse(text);
                     }
                     catch {
                         skipped++;
@@ -307,7 +594,7 @@ export class JsonStore {
                     }
                     const r = schema.safeParse(this.migrate(kind, raw, version));
                     if (r.success) {
-                        writeFileAtomic(p, encode(r.data));
+                        this.writeContainedFile(directory, p, encode(r.data), this.maxBytes(kind));
                         migrated++;
                     }
                     else {

package/dist/store/schema.js

@@ -3,8 +3,9 @@
  *
  * The JSON files under .hunch/ are the source of truth; this database is rebuilt
  * from them by `hunch index`. JSON-array/object fields are stored as TEXT (JSON)
- * — we only need them indexed where we query them. Search is a single unified
- * FTS5 table; the graph is plain tables walked with recursive CTEs.
+ * — we only need them indexed where we query them. Search prefers one unified
+ * FTS5 table, but db.ts substitutes a plain table when the host Node binary was
+ * built without FTS5; the graph is plain tables walked with recursive CTEs.
  */
 import { shortHash } from "../core/ids.js";
 /** Canonical content hash of the exact title+body that fed both FTS and the
@@ -71,15 +72,6 @@ CREATE TABLE IF NOT EXISTS constraints (
   prov_source TEXT, prov_confidence REAL, prov_evidence TEXT
 );
 
--- Unified full-text search across every entity. Rebuilt on index; bm25-ranked.
-CREATE VIRTUAL TABLE IF NOT EXISTS search USING fts5(
-  ref UNINDEXED,   -- entity id
-  kind UNINDEXED,  -- components | edges | symbols | decisions | bugs | constraints
-  title,
-  body,
-  tokenize = 'porter unicode61'
-);
-
 -- Local semantic-search vectors (opt-in; written by \`hunch embed\`). One row per
 -- (ref, model); vec is a Float32 BLOB. DELIBERATELY NOT in RESET_SQL: reindex()
 -- runs RESET on nearly every path (MCP startup, every query/context), so resetting
@@ -91,6 +83,30 @@ CREATE TABLE IF NOT EXISTS embeddings (
   PRIMARY KEY (ref, model)
 );
 `;
+/** Preferred search table when the host SQLite build includes FTS5. Kept
+ * separate from SCHEMA_SQL so a missing optional SQLite module cannot prevent
+ * deterministic graph/constraint operations from opening the derived index. */
+export const FTS_SEARCH_SCHEMA_SQL = /* sql */ `
+CREATE VIRTUAL TABLE IF NOT EXISTS search USING fts5(
+  ref UNINDEXED,   -- entity id
+  kind UNINDEXED,  -- components | edges | symbols | decisions | bugs | constraints
+  title,
+  body,
+  tokenize = 'porter unicode61'
+);
+`;
+/** Portable keyword-search fallback. HunchStore detects that MATCH/bm25 are
+ * unavailable and performs a bounded LIKE scan over the same four columns. */
+export const PLAIN_SEARCH_SCHEMA_SQL = /* sql */ `
+CREATE TABLE IF NOT EXISTS search (
+  ref TEXT,
+  kind TEXT,
+  title TEXT,
+  body TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_search_ref ON search(ref);
+CREATE INDEX IF NOT EXISTS idx_search_kind ON search(kind);
+`;
 /** Drop derived data (used before a full reindex). NOTE: embeddings is omitted on
  *  purpose — see the embeddings table comment above. */
 export const RESET_SQL = /* sql */ `