homegraph 1.2.0 → 1.5.0

package/dist/db/wal-valve.js

@@ -0,0 +1,290 @@
+"use strict";
+/**
+ * WAL checkpoint valve — bounds WAL growth while auto-checkpointing is
+ * deferred during a bulk index (#1231).
+ *
+ * Why deferral: SQLite's default `wal_autocheckpoint` (1000 pages) re-writes
+ * hot B-tree/FTS pages into the main DB file over and over during a bulk
+ * index — measured at ~95% of ALL disk I/O, and the difference between 45s
+ * and 19+ minutes on HDD-class storage (150 random IOPS). Deferring
+ * checkpoints turns the store into pure sequential WAL appends; each backfill
+ * pass writes distinct pages once, in page order (≈ sequential).
+ *
+ * Why a valve: unbounded deferral is its own failure mode, both measured in
+ * the #1231 repro. The WAL duplicates hot pages per COMMIT, so it grows far
+ * faster than the DB (5.9GB WAL for a ~340MB DB on a 3.3k-file index) —
+ * filling the disk, and poisoning every subsequent read that must page
+ * through it (the first resolution-phase read blocked the main thread >60s
+ * and the #850 liveness watchdog killed the healthy index). The valve
+ * watches WAL growth on a timer and, past a soft threshold, backfills with
+ * `PRAGMA wal_checkpoint(PASSIVE)` on a worker-thread connection — PASSIVE
+ * never blocks the writer, and off-thread means the main thread (and the
+ * watchdog heartbeat) keep turning regardless of how long a backfill takes.
+ *
+ * The load-bearing subtlety: a WAL file's SIZE never shrinks. After a full
+ * backfill, the writer's next commit RESTARTS the WAL from the top and the
+ * frames recycle inside the same file — so raw size says nothing about the
+ * un-backfilled backlog, and a size-triggered valve degenerates into firing
+ * (and pausing the writer) forever once the file passes its threshold
+ * (measured: guava crawled at ~9min per 160 files). Instead the valve
+ * tracks `sizeAtLastFullBackfill` — refreshed whenever a checkpoint reports
+ * `log === checkpointed` (everything backfilled) — and triggers on GROWTH
+ * beyond that baseline, which only happens when genuinely un-backfilled
+ * frames push past the file's high-water mark.
+ *
+ * Backpressure: if the writer outruns the checkpointer past a hard cap of
+ * growth (2× soft), {@link backpressure} pauses the writer (at a safe,
+ * between-transactions boundary) until a FULL backfill lands. One in-flight
+ * pass is not enough: on a disk saturated by the writer, every concurrent
+ * PASSIVE pass is already stale by the time it finishes (the writer appended
+ * past its snapshot), so neither SQLite's WAL wrap nor the baseline ever
+ * trigger and the WAL grows without bound (measured: 5.9GB on guava at 150
+ * IOPS, then a >60s read stall and a watchdog kill). With the writer parked,
+ * the next pass covers everything, the WAL wraps on the following commit,
+ * and the pause is the disk's honest catch-up cost — the correct terminal
+ * mode when hardware genuinely can't keep up with the append rate.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WalCheckpointValve = void 0;
+exports.resolveWalValveMb = resolveWalValveMb;
+/** Soft WAL-growth threshold (MB) that triggers an off-thread passive checkpoint. */
+const DEFAULT_WAL_VALVE_MB = 256;
+/** Hard cap = this × soft threshold; past it the writer pauses for a full backfill. */
+const HARD_CAP_MULTIPLIER = 2;
+/** File cap = this × soft threshold; past it the barrier also TRUNCATEs the file. */
+const FILE_CAP_MULTIPLIER = 4;
+/** Passes attempted per writer pause before giving up (a pinned reader could stall forever). */
+const MAX_PAUSED_BACKFILL_PASSES = 20;
+/** How often the timer looks at the WAL file size. */
+const CHECK_INTERVAL_MS = 2000;
+/**
+ * Resolve the valve's soft threshold from the `HOMEGRAPH_WAL_VALVE_MB`
+ * override; non-numeric / non-positive values fall back to the default.
+ */
+function resolveWalValveMb(envVal, dbSizeBytes) {
+    if (envVal !== undefined && envVal !== '') {
+        const n = Number(envVal);
+        if (Number.isFinite(n) && n > 0)
+            return Math.floor(n);
+    }
+    // Scale with the project when the caller knows the DB size: every fold
+    // re-writes hot B-tree pages into the main file (the #1231 pathology in
+    // bounded form — 111s of a kernel-scale batch loop at the flat 256MB cap,
+    // §7a.2), so a big project affords a proportionally bigger transient WAL
+    // (~dbSize/4 soft ⇒ file cap ≈ dbSize) in exchange for ~4× fewer folds.
+    if (dbSizeBytes !== undefined && dbSizeBytes > 0) {
+        return Math.min(2048, Math.max(DEFAULT_WAL_VALVE_MB, Math.floor(dbSizeBytes / 4 / (1024 * 1024))));
+    }
+    return DEFAULT_WAL_VALVE_MB;
+}
+class WalCheckpointValve {
+    db;
+    intervalMs;
+    timer = null;
+    inflight = null;
+    /** Writer pause in progress (hard cap breached): passes loop until a full backfill. */
+    pause = null;
+    /**
+     * WAL file size observed when a checkpoint last reported the ENTIRE WAL
+     * backfilled. Growth is measured against this baseline — see the header
+     * comment for why absolute size cannot be used.
+     */
+    sizeAtLastFullBackfill = 0;
+    softBytes;
+    hardBytes;
+    fileCapBytes;
+    /**
+     * Futility latch: consecutive backfill give-ups (a reader pinning the WAL)
+     * disable further writer pauses for a cooldown, so a pinned phase degrades
+     * to the pre-valve behavior (unbounded WAL, folded when the pinner exits)
+     * instead of burning a 20-pass checkpoint attempt — each pass a worker
+     * thread + fresh connection — at EVERY over-cap boundary. That churn is
+     * what turned a pinned kernel-scale resolution from slow into OOM-killed
+     * (§7a.1 run 1: 22GB WAL, exit 137 at an envelope the pre-fix build
+     * survived).
+     */
+    consecutiveGiveUps = 0;
+    futileUntil = 0;
+    constructor(db, softMb = resolveWalValveMb(process.env.HOMEGRAPH_WAL_VALVE_MB), intervalMs = CHECK_INTERVAL_MS, log = () => { }) {
+        this.db = db;
+        this.intervalMs = intervalMs;
+        this.softBytes = softMb * 1024 * 1024;
+        this.hardBytes = this.softBytes * HARD_CAP_MULTIPLIER;
+        this.fileCapBytes = this.softBytes * FILE_CAP_MULTIPLIER;
+        // HOMEGRAPH_WAL_VALVE_DEBUG=1 surfaces valve decisions to stderr without
+        // needing the caller's verbose plumbing — the observability gap that let
+        // §7a.1 run 1 fail silently (give-ups were verbose-gated and invisible).
+        this.log = process.env.HOMEGRAPH_WAL_VALVE_DEBUG
+            ? (m) => console.error(`[wal-valve] ${m}`)
+            : log;
+    }
+    log;
+    mb(n) {
+        return `${Math.round(n / 1024 / 1024)}MB`;
+    }
+    /** Un-backfilled growth estimate: bytes the WAL has grown past the last full backfill. */
+    growthBytes() {
+        return this.db.getWalSizeBytes() - this.sizeAtLastFullBackfill;
+    }
+    /** Begin watching the WAL. Idempotent; the timer never holds the loop open. */
+    start() {
+        if (this.timer)
+            return;
+        // One armed line per run under either diagnostics env: §7a.1's failed
+        // kernel-scale runs burned three 25-minute cycles before "is the valve
+        // even alive?" could be answered.
+        if (process.env.HOMEGRAPH_SYNTH_TIMINGS || process.env.HOMEGRAPH_WAL_VALVE_DEBUG) {
+            console.error(`[wal-valve] armed soft=${this.mb(this.softBytes)} hard=${this.mb(this.hardBytes)} wal=${this.mb(this.db.getWalSizeBytes())}`);
+        }
+        let ticks = 0;
+        this.timer = setInterval(() => {
+            if ((++ticks % 15) === 0) {
+                this.log(`alive: wal=${this.mb(this.db.getWalSizeBytes())} baseline=${this.mb(this.sizeAtLastFullBackfill)} inflight=${this.inflight ? 'y' : 'n'} paused=${this.pause ? 'y' : 'n'}`);
+            }
+            this.check();
+        }, this.intervalMs);
+        this.timer.unref?.();
+    }
+    /** Stop watching. Any in-flight checkpoint keeps running — await drain(). */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /** One poll: fire an off-thread passive checkpoint when growth passes the soft threshold. */
+    check() {
+        if (!this.pause && !this.inflight && this.growthBytes() > this.softBytes)
+            this.fire();
+    }
+    /**
+     * Writer-side backstop, called at a between-transactions boundary. Returns
+     * null (no wait) while growth is under the hard cap; past it, returns a
+     * promise that resolves only once a FULL backfill has landed — see the
+     * header comment for why a single pass is not enough on a saturated disk.
+     */
+    backpressure() {
+        if (this.pause)
+            return this.pause;
+        if (Date.now() < this.futileUntil)
+            return null; // pinned reader — parking is churn, not progress
+        // Two independent triggers:
+        //  - growth: un-backfilled BACKLOG past the hard cap (the original valve).
+        //  - file size: a WAL can stay fully backfilled and still grow without
+        //    bound — the writer only restarts at frame 0 if a commit finds no
+        //    reader marks, which §7a.1's instrumented run showed never happens
+        //    in practice (file marched 361→721MB through two COMPLETE
+        //    backfills). Past the file cap, park and TRUNCATE at the barrier —
+        //    the backfill part is instant when the backlog is already folded.
+        if (this.growthBytes() <= this.hardBytes && this.db.getWalSizeBytes() <= this.fileCapBytes)
+            return null;
+        this.log(`backpressure: wal=${this.mb(this.db.getWalSizeBytes())} baseline=${this.mb(this.sizeAtLastFullBackfill)} — pausing writer for full backfill`);
+        const t0 = Date.now();
+        this.pause = this.backfillFully().finally(() => {
+            this.pause = null;
+            this.log(`backpressure released after ${Date.now() - t0}ms: wal=${this.mb(this.db.getWalSizeBytes())} baseline=${this.mb(this.sizeAtLastFullBackfill)}`);
+        });
+        return this.pause;
+    }
+    /** Await any in-flight checkpoint and writer pause. */
+    async drain() {
+        while (this.pause || this.inflight) {
+            if (this.pause)
+                await this.pause;
+            if (this.inflight)
+                await this.inflight;
+        }
+    }
+    /**
+     * Phase-boundary fold: backfill the ENTIRE WAL now (off-thread, awaited).
+     * Called between bulk phases — e.g. after parsing, before resolution's
+     * first reads — so the next phase never pages a bulk-write-sized WAL on
+     * the main thread (the post-parse read against a multi-GB WAL is what
+     * blew the #850 watchdog's 60s window in the #1231 repro). The await
+     * keeps the event loop (and the watchdog heartbeat) turning.
+     */
+    async foldNow() {
+        await this.drain();
+        if (this.growthBytes() <= 0)
+            return;
+        this.log(`foldNow: wal=${this.mb(this.db.getWalSizeBytes())} baseline=${this.mb(this.sizeAtLastFullBackfill)}`);
+        this.pause = this.backfillFully().finally(() => { this.pause = null; });
+        await this.pause;
+    }
+    /**
+     * With the writer parked on the returned promise, loop passive passes until
+     * one reports the entire WAL backfilled (typically the second: the first
+     * drains the pass that was already running against a stale snapshot). Gives
+     * up after a bounded number of passes — e.g. a reader pinning the WAL —
+     * because unbounded WAL growth degrades; a wedged writer never recovers.
+     */
+    async backfillFully() {
+        for (let i = 0; i < MAX_PAUSED_BACKFILL_PASSES; i++) {
+            if (this.inflight)
+                await this.inflight; // fold in the stale in-flight pass first
+            const res = await this.db.checkpointWalPassive();
+            if (!res)
+                return; // checkpoint machinery unavailable — don't spin
+            this.log(`backfill pass ${i + 1}: busy=${res.busy} log=${res.log} checkpointed=${res.checkpointed} wal=${this.mb(this.db.getWalSizeBytes())}`);
+            if (res.busy === 0 && res.log === res.checkpointed) {
+                // Backfill complete AND we are at a parked barrier (backfillFully only
+                // runs under a writer pause): the no-reader window is guaranteed, so
+                // chop the FILE too — a fully-backfilled WAL otherwise keeps growing
+                // whenever commits land while pool readers hold marks (§7a.1: 22GB
+                // on-disk at kernel scale despite backfills). A racing reader turns
+                // this into a no-op (busy=1); the passive result above still stands.
+                const trunc = await this.db.checkpointWalTruncate();
+                if (trunc)
+                    this.log(`truncate: busy=${trunc.busy} wal=${this.mb(this.db.getWalSizeBytes())}`);
+                this.sizeAtLastFullBackfill = this.db.getWalSizeBytes();
+                this.consecutiveGiveUps = 0;
+                this.futileUntil = 0;
+                return;
+            }
+        }
+        this.consecutiveGiveUps++;
+        if (this.consecutiveGiveUps >= 2) {
+            this.futileUntil = Date.now() + 60_000;
+        }
+        const msg = `backfill gave up after ${MAX_PAUSED_BACKFILL_PASSES} passes (streak ${this.consecutiveGiveUps}${this.futileUntil ? ', parking disabled 60s' : ''}) — a reader is pinning the WAL`;
+        this.log(msg);
+        // Give-ups are rare and load-bearing for §7a.1-class diagnosis — surface
+        // them on any timing-instrumented run, not just valve-debug ones.
+        if (process.env.HOMEGRAPH_SYNTH_TIMINGS && !process.env.HOMEGRAPH_WAL_VALVE_DEBUG) {
+            console.error(`[wal-valve] ${msg}`);
+        }
+    }
+    fire() {
+        this.log(`fire: wal=${this.mb(this.db.getWalSizeBytes())} baseline=${this.mb(this.sizeAtLastFullBackfill)}`);
+        const p = this.db
+            .checkpointWalPassive()
+            .then((res) => {
+            this.log(`timer pass: ${res ? `busy=${res.busy} log=${res.log} checkpointed=${res.checkpointed}` : 'null (machinery unavailable)'} wal=${this.mb(this.db.getWalSizeBytes())}`);
+            // Full backfill (busy 0, every log frame checkpointed) ⇒ the writer's
+            // next commit wraps the WAL; the file's current size becomes the new
+            // growth baseline. A partial pass (writer appended during it, or a
+            // read transaction pinned frames) leaves the baseline alone, so the
+            // next tick fires again and copies the remainder. In non-WAL mode
+            // SQLite reports log = checkpointed = -1, which is harmless here.
+            if (res && res.busy === 0 && res.log === res.checkpointed) {
+                this.sizeAtLastFullBackfill = this.db.getWalSizeBytes();
+                // NO truncate here. A truncate checkpoint that starts against an
+                // ACTIVE writer wins the lock race and then blocks that writer for
+                // its entire backfill — after a multi-GB single-transaction burst
+                // (edge-index recreate) that exceeds the writer's 5s busy_timeout
+                // and fails the index with "database is locked" (§7a.2 record run).
+                // The file chop happens exclusively at parked barriers
+                // (backpressure/foldNow), where the writer is awaiting us by
+                // construction and cannot collide.
+            }
+        })
+            .catch(() => { })
+            .finally(() => {
+            if (this.inflight === p)
+                this.inflight = null;
+        });
+        this.inflight = p;
+    }
+}
+exports.WalCheckpointValve = WalCheckpointValve;
+//# sourceMappingURL=wal-valve.js.map

package/dist/db/wal-valve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wal-valve.js","sourceRoot":"","sources":["../../src/db/wal-valve.ts"],"names":[],"mappings":"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"}

package/dist/directory.d.ts

@@ -77,10 +77,14 @@ export declare function findIndexedSubprojectRoots(root: string, opts?: {
     max?: number;
 }): string[];
 /**
- * Does `prompt` contain an explicit structural keyword (English or CJK)? A
- * keyword is a strong, self-contained signal, so the front-load hook fires on it
- * directly — no graph check needed. (A *code-token* match, by contrast, is only
- * a candidate the hook verifies against the graph first; see {@link extractCodeTokens}.)
+ * Does `prompt` contain an explicit structural keyword? A keyword is a strong,
+ * self-contained signal, so the front-load hook fires on it directly — no graph
+ * check needed. (A *code-token* match, by contrast, is only a candidate the
+ * hook verifies against the graph first; see {@link extractCodeTokens}.)
+ * Coverage is multilingual (#994, #1126): the ~29 languages with the largest
+ * developer populations, across Latin, Cyrillic, Greek, CJK, Hangul, Arabic,
+ * Hebrew, Thai, and Devanagari scripts. Languages beyond the keyword table
+ * still fire through the language-agnostic code-token path.
  */
 export declare function hasStructuralKeyword(prompt: string): boolean;
 /**
@@ -101,7 +105,7 @@ export declare function extractCodeTokens(prompt: string): string[];
 /**
  * Cheap, graph-free candidate gate for the front-load hook: could `prompt` be a
  * structural / flow / impact / "where-how" question worth front-loading context
- * for? True on an explicit keyword (English or CJK, issue #994) OR an
+ * for? True on an explicit keyword in any covered language (#994, #1126) OR an
  * identifier-shaped token. A keyword is sufficient to fire on its own; a
  * token-only match is only a candidate the hook then verifies against the graph
  * (a brand name like `JavaScript` is token-shaped but isn't a symbol). Every

package/dist/directory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"directory.d.ts","sourceRoot":"","sources":["../src/directory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAqBzC;AAED,qFAAqF;AACrF,eAAO,MAAM,aAAa,eAAwB,CAAC;AAEnD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOxD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAQ1D;AAED;;;;;;;;GAQG;AACH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA8BxE;AAED,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAmBzE;AA2BD;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7C,MAAM,EAAE,CAmBV;AAyBD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAkB1D;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;yEAEqE;IACrE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;;6EAEyE;IACzE,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB;;+DAE2D;IAC3D,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,CAwCxE;AAyDD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAgBzD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAuBzD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CA8BnE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CA+B5D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAYlF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG;IACtD,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CA6BA"}
+{"version":3,"file":"directory.d.ts","sourceRoot":"","sources":["../src/directory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAqBzC;AAED,qFAAqF;AACrF,eAAO,MAAM,aAAa,eAAwB,CAAC;AAEnD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOxD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAQ1D;AAED;;;;;;;;GAQG;AACH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA8BxE;AAED,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAmBzE;AA2BD;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7C,MAAM,EAAE,CAmBV;AAsND;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAK5D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAkB1D;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;yEAEqE;IACrE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;;6EAEyE;IACzE,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB;;+DAE2D;IAC3D,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,CAwCxE;AAyDD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAgBzD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAuBzD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CA8BnE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CA+B5D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAYlF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG;IACtD,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CA6BA"}

package/dist/directory.js

@@ -263,33 +263,224 @@ function findIndexedSubprojectRoots(root, opts = {}) {
     return out;
 }
 /**
- * English structural keywords, matched with `\b` word boundaries so a keyword
- * inside a longer word doesn't false-positive ("flow" in "flower").
+ * Unicode-aware word-boundary emulation for the keyword lists below. JS's `\b`
+ * is ASCII-only — it fires only at `[A-Za-z0-9_]` edges — so it can never bound
+ * a keyword whose first or last character is accented or non-Latin: `/\boù\b/`
+ * NEVER matches "où est …" (ù isn't an ASCII word char, so no boundary exists
+ * next to it). That is the #994 CJK mechanism resurfaced for Latin scripts and
+ * Cyrillic (#1126). A lookaround — "not flanked by a letter, digit, or
+ * underscore" — is the script-independent equivalent.
  */
-const STRUCTURAL_EN = /\b(how|where|trace|flow|path|reach(?:es|ed)?|call(?:s|ed|er|ers|ee)?|depend|impact|affect|wired?|connect|implement|architect|structure|breaks?|what calls|why does)\b/i;
+const NOT_WORD_BEFORE = /(?<![\p{L}\p{N}_])/u.source;
+const NOT_WORD_AFTER = /(?![\p{L}\p{N}_])/u.source;
 /**
- * Non-English (CJK) structural keywords, matched WITHOUT `\b`. JS's `\b` is
- * ASCII-only — it only fires at `[A-Za-z0-9_]` boundaries, never between Han
- * characters — so a Chinese keyword wrapped in `\b…\b` could never match. That
- * was issue #994: the English-only gate silently no-op'd every Chinese prompt,
- * so non-English users got no front-load nudge and no error to explain why. The
- * set mirrors the English intent (如何=how, 在哪/哪里=where, 流程/流向=flow,
- * 路径=path, 调用=call, 依赖=depend, 影响=impact/affect, 实现=implement,
- * 架构=architect, 结构=structure, 追踪/跟踪=trace) plus structural-overview words
- * with no single clean English equivalent (介绍/解析/分析/原理/机制).
+ * Structural keywords matched as EXACT words (boundary on both sides): short
+ * or ambiguous tokens where prefix matching would false-positive ("flow" in
+ * "flower", "path" in "pathological"). Grouped by language; a term appears once
+ * even when several languages share it ("como" is Portuguese for how AND
+ * unaccented-typed Spanish "cómo").
  */
-const STRUCTURAL_CJK = /如何|怎么|在哪|哪里|追踪|跟踪|流程|流向|路径|调用|依赖|影响|实现|架构|结构|介绍|解析|分析|原理|机制/;
+const STRUCTURAL_WORDS = [
+    // English — the pre-#1126 list minus what moved to STRUCTURAL_STEMS: the
+    // bare-stem entries never matched their own derived forms (`\barchitect\b`
+    // can't match "architecture"), and "what calls" is subsumed by the "call" stem.
+    'how', 'where', 'tracing', 'flows?', 'paths?', 'reach(?:es|ed)?', 'wired?', 'breaks?', 'why does',
+    // French (où=where, flux=flow, chemin=path, casse=breaks)
+    'comment', 'où', 'flux', 'chemins?', 'casse',
+    // Spanish (cómo/como=how, dónde/donde=where, flujo=flow, ruta/camino=path,
+    // rompe=breaks, llaman / quién llama = call(s) — bare "llama" is excluded:
+    // it's also the animal/model name in English prompts)
+    'cómo', 'dónde', 'donde', 'flujos?', 'rutas?', 'caminos?', 'rompe', 'llaman', 'quién llama', 'quien llama',
+    // Portuguese (como=how — also covers unaccented Spanish; onde=where,
+    // fluxo=flow, caminho=path)
+    'como', 'onde', 'fluxos?', 'caminhos?',
+    // German (wie=how, wo/woher/wohin=where, Pfad=path, Fluss/Ablauf=flow,
+    // bricht/kaputt=breaks, ruft=calls, hängt=depends — "hängt … von X ab"
+    // splits the separable verb "abhängen", so the "abhäng" stem can't catch it)
+    'wie', 'wo', 'woher', 'wohin', 'pfade?', 'fluss', 'ablauf', 'bricht', 'kaputt', 'ruft', 'hängt',
+    // Italian (dove=where, flusso=flow, percorso/i=path)
+    'dove', 'flusso', 'percors[oi]',
+    // Russian (как=how, где=where, путь/пути=path, работает=works)
+    'как', 'где', 'путь', 'пути', 'работает',
+    // Ukrainian (як=how, де=where, потік=flow — обліque cases reuse the RU
+    // "поток" stem; працює=works)
+    'як', 'де', 'потік', 'працює',
+    // Dutch (hoe=how, waar=where, roept=calls, werkt=works, aangeroepen=called —
+    // the ge- participle escapes the "aanroep" stem)
+    'hoe', 'waar', 'roept', 'werkt', 'aangeroepen',
+    // Polish + Czech (jak=how — shared; gdzie/kde=where, cesta=path)
+    'jak', 'gdzie', 'kde', 'cesta',
+    // Romanian (cum=how, unde=where; flux is shared with French)
+    'cum', 'unde',
+    // Hungarian (hogyan=how, hol=where)
+    'hogyan', 'hol',
+    // Turkish (nasıl=how, mimari=architecture, takip=trace/follow)
+    'nasıl', 'mimari', 'takip',
+    // Indonesian/Malay (bagaimana=how, di mana/dimana=where, alur=flow, jalur=path)
+    'bagaimana', 'di mana', 'dimana', 'alur', 'jalur',
+    // Vietnamese — spaced Latin with heavy diacritics, the exact class ASCII `\b`
+    // breaks (làm sao/thế nào=how, ở đâu=where, gọi=call, phụ thuộc=depend,
+    // ảnh hưởng=affect, kiến trúc=architecture, cấu trúc=structure, luồng=flow,
+    // đường dẫn=path, hoạt động=works, giải thích=explain, theo dõi=trace)
+    'làm sao', 'thế nào', 'ở đâu', 'gọi', 'phụ thuộc', 'ảnh hưởng', 'kiến trúc',
+    'cấu trúc', 'luồng', 'đường dẫn', 'hoạt động', 'giải thích', 'theo dõi',
+    // Swedish / Danish / Norwegian (hur/hvordan=how, hvor=where, beror=depends,
+    // flöde=flow)
+    'hur', 'hvordan', 'hvor', 'beror', 'flöde',
+    // Finnish (miten=how, missä=where, toimii=works)
+    'miten', 'missä', 'toimii',
+    // Greek (πώς=how, πού=where — accented forms only: unaccented πως/που are
+    // ubiquitous conjunctions; καλεί=calls, δομή=structure, ροή=flow)
+    'πώς', 'πού', 'καλεί', 'δομή', 'ροή',
+    // Hindi (कैसे=how, कहाँ/कहां=where, कॉल=call, निर्भर=depends,
+    // संरचना=structure, प्रवाह=flow)
+    'कैसे', 'कहाँ', 'कहां', 'कॉल', 'निर्भर', 'संरचना', 'प्रवाह',
+];
+/**
+ * Structural keyword STEMS matched as word PREFIXES (boundary on the left
+ * only), so derived forms match without enumerating each: "architect" fires on
+ * architecture/architectural, "depend" on depends/dependency/dependencies,
+ * "вызыва" on вызывает/вызывается. Mid-word occurrences stay excluded —
+ * "restructure"/"independent" don't fire — so precision stays close to the
+ * exact-word class. Add a stem only when every plausible completion is still a
+ * structural word; a stem with ordinary-English completions must instead
+ * enumerate its structural suffixes and re-assert the right boundary (see the
+ * four bounded English entries below, #1138).
+ */
+const STRUCTURAL_STEMS = [
+    // English + the Latin-script languages that share the spelling (French
+    // architecture/structure/trace/impact, Spanish depende/implementa/impacto, …).
+    // call/trace/affect/connect are NOT safe as open prefixes — callus,
+    // calligraphy, Connecticut, connective, affectionate, Tracey are ordinary
+    // words that would false-fire the full-explore tier (#1138) — so they carry
+    // an enumerated suffix set + right boundary. "tracing" lives in
+    // STRUCTURAL_WORDS (the e is dropped, so no trace-prefix form matches it).
+    'architect', 'structur', 'depend', 'implement', 'impact', 'explain',
+    `call(?:s|ing|ed|ers?|backs?|able|sites?)?${NOT_WORD_AFTER}`,
+    `trace(?:s|d|rs?)?${NOT_WORD_AFTER}`,
+    `affect(?:s|ed|ing)?${NOT_WORD_AFTER}`,
+    `connect(?:s|ed|ing|ions?|ors?|ivity)?${NOT_WORD_AFTER}`,
+    // French (appel(le)=call, dépend=depends, implément(e)=implement,
+    // connex(ion)=connection, expliqu(e)=explain, fonctionn(e/ement)=works)
+    'appel', 'dépend', 'implément', 'connex', 'expliqu', 'fonctionn',
+    // Spanish (llamad(a)=call, afect(a)=affect, conect(a)/conexi(ón)=connect,
+    // arquitec(tura)=architecture, estructur(a)=structure, funcion(a)=works,
+    // traza(r)=trace, explica=explain)
+    'llamad', 'afect', 'conect', 'conexi', 'arquitec', 'estructur', 'funcion', 'traza', 'explica',
+    // Portuguese (chama(da)=call, afeta=affect, arquitet(ura)=architecture,
+    // estrutur(a)=structure, quebra(do)=breaks)
+    'chama', 'afeta', 'arquitet', 'estrutur', 'quebra',
+    // German (abhäng(t)=depend, Auswirkung=impact, beeinfluss(t)=affect,
+    // verbind(et)=connect, Architektur, Struktur, funktionier(t)=works,
+    // Aufruf/aufgerufen=call, erklär(t)=explain, verfolg(en)=trace)
+    'abhäng', 'auswirkung', 'beeinfluss', 'verbind', 'architekt', 'struktur', 'funktionier', 'aufruf', 'aufgerufen', 'erklär', 'verfolg',
+    // Italian (chiam(a/ata)=call, dipend(e/enza)=depend, impatt(o)=impact,
+    // connett(e)/conness(ione)=connect, architett(ura), struttur(a),
+    // funzion(a/amento)=works, tracci(a)=trace, spiega(mi)=explain)
+    'chiam', 'dipend', 'impatt', 'connett', 'conness', 'architett', 'struttur', 'funzion', 'tracci', 'spiega',
+    // Russian (вызыва(ет)=calls, завис(ит)=depends, влия(ет)=affects,
+    // реализ(ация)=implementation, структур(а), архитектур(а),
+    // трассир(овка)=trace, лома(ет)=breaks, объясн(и)=explain, поток=flow)
+    'вызыва', 'завис', 'влия', 'реализ', 'структур', 'архитектур', 'трассир', 'лома', 'объясн', 'поток',
+    // Ukrainian — і/и spellings diverge from Russian (виклика(є)=calls,
+    // залеж(ить)=depends, вплива(є)=affects, архітектур(а), реаліз(ація),
+    // поясн(и)=explain, шлях(у)=path; структур(а) is shared with Russian)
+    'виклика', 'залеж', 'вплива', 'архітектур', 'реаліз', 'поясн', 'шлях',
+    // Dutch (aanroep(en)=call, afhankelijk(heid)=depends, beïnvloed(t)=affects,
+    // structuur — "structur" can't reach the uu; uitleg(gen)=explain)
+    'aanroep', 'afhankelijk', 'beïnvloed', 'structuur', 'uitleg',
+    // Polish (wywoł(uje)=calls, zależ(y)=depends, wpływ(a)=affects/impact,
+    // przepływ=flow, ścieżk(a)=path, działa(nie)=works, wyjaśni(j)=explain,
+    // śledz(enie)=trace; architektura/struktura fire via the German stems)
+    'wywoł', 'zależ', 'wpływ', 'przepływ', 'ścieżk', 'działa', 'wyjaśni', 'śledz',
+    // Czech (volá(ní)=calls, závis(í)=depends, ovlivň(uje)=affects,
+    // funguj(e)=works, vysvětl(i)=explain)
+    'volá', 'závis', 'ovlivň', 'funguj', 'vysvětl',
+    // Romanian (apel(ează)=calls, depind(e)=depends — i not e, so "depend" misses
+    // it; arhitectur(a) — no c; funcțion(ează)=works, explică=explain)
+    'apel', 'depind', 'arhitectur', 'funcțion', 'explică',
+    // Hungarian (hív(ja)=calls, függ(őség)=depends, működ(ik)=works,
+    // struktúr(a) — ú escapes "struktur"; magyaráz(d)=explain;
+    // architektúra fires via the German stem)
+    'hív', 'függ', 'működ', 'struktúr', 'magyaráz',
+    // Turkish — agglutinative, so stems beat exact words (nere(de/ye/den)=where,
+    // çağır/çağrı=call, bağıml(ı)=depends, bağlant(ı)=connection, akış(ı)=flow,
+    // etkile(r)/etkisi=affects/impact)
+    'nere', 'çağır', 'çağrı', 'bağıml', 'bağlant', 'akış', 'etkile', 'etkisi',
+    // Indonesian/Malay — me-/di-/ber- prefixes block a bare stem, so affixed
+    // forms are listed too (panggil(an)/memanggil/dipanggil=call,
+    // bergantung/tergantung=depends, pengaruh/mempengaruhi/memengaruhi=affect,
+    // arsitektur=architecture, fungsi/berfungsi=works,
+    // jelaskan/menjelaskan=explain)
+    'panggil', 'memanggil', 'dipanggil', 'bergantung', 'tergantung', 'pengaruh',
+    'mempengaruhi', 'memengaruhi', 'arsitektur', 'fungsi', 'berfungsi', 'jelaskan', 'menjelaskan',
+    // Swedish / Danish / Norwegian (anrop(ar)=calls, påverk(ar)/påvirk(er)=affects,
+    // afhæng(er)/avheng(er)=depends, förklar(a)/forklar=explain,
+    // arkitektur — k not ch; funger(ar/er)=works)
+    'anrop', 'påverk', 'påvirk', 'afhæng', 'avheng', 'förklar', 'forklar', 'arkitektur', 'funger',
+    // Finnish (kutsu(u)=calls, riippu(u)=depends, arkkitehtuur(i),
+    // rakente(en)=structure, selit(ä)=explain)
+    'kutsu', 'riippu', 'arkkitehtuur', 'rakente', 'selit',
+    // Greek — accented and unaccented stem spellings both occur
+    // (εξαρτ(άται)=depends, επηρε(άζει)=affects, αρχιτεκτονικ(ή),
+    // διαδρομ(ή)=path, εξηγ/εξήγ(ησε)=explain)
+    'εξαρτ', 'επηρε', 'αρχιτεκτονικ', 'διαδρομ', 'εξηγ', 'εξήγ',
+    // Hindi (समझा(ओ/इए)=explain, आर्किटेक्चर=architecture)
+    'समझा', 'आर्किटेक्चर',
+];
+const STRUCTURAL_WORDS_RE = new RegExp(`${NOT_WORD_BEFORE}(?:${STRUCTURAL_WORDS.join('|')})${NOT_WORD_AFTER}`, 'iu');
+const STRUCTURAL_STEMS_RE = new RegExp(`${NOT_WORD_BEFORE}(?:${STRUCTURAL_STEMS.join('|')})`, 'iu');
+/**
+ * Structural keywords matched as bare SUBSTRINGS, for languages where a
+ * boundary can't be relied on: scripts with no word separators (Chinese —
+ * simplified AND traditional; the original #994 set was simplified-only —
+ * Japanese, Thai), Korean (spaced, but particles attach directly to the noun:
+ * 구조가/구조를), and Arabic / Farsi / Hebrew (spaced, but proclitics attach to
+ * the word: وكيف "and-how", והמבנה "and-the-structure"). JS's `\b` can never
+ * fire between Han characters, which was issue #994: the English-only gate
+ * silently no-op'd every Chinese prompt, so non-English users got no front-load
+ * nudge and no error to explain why. The sets mirror the English intent
+ * (如何/怎么/怎麼/どうやって/どのように/어떻게/كيف/چگونه/چطور/איך/อย่างไร/ยังไง=how,
+ * 在哪/哪里/哪裡/어디/أين/كجا/איפה/ที่ไหน=where, 流程/流向/流れ/흐름/تدفق/זרימה=flow,
+ * 路径/路徑/経路/경로/مسار/مسیر/נתיב/เส้นทาง=path,
+ * 调用/調用/呼び出/호출/يستدعي/استدعاء/فراخوان/קורא/เรียกใช้=call,
+ * 依赖/依賴/依存/의존/يعتمد/تعتمد/وابسته/תלוי/ขึ้นอยู่กับ=depend,
+ * 影响/影響/영향/يؤثر/تأثير/تأثیر/משפיע/ผลกระทบ=impact/affect,
+ * 实现/實現/実装/구현=implement,
+ * 架构/架構/アーキテクチャ/아키텍처/معماري/معماری/ארכיטקטור/สถาปัตยกรรม=architecture,
+ * 结构/結構/構造/구조/بنية/هيكل/ساختار/מבנה/โครงสร้าง=structure,
+ * 追踪/跟踪/追蹤/追跡/トレース/추적/تتبع/ติดตาม=trace,
+ * يعمل/تعمل/ทำงาน=works) plus structural-overview words with no single clean
+ * English equivalent (介绍/介紹/解析/分析/原理/机制/機制/仕組み/説明/설명/動作/동작/작동/
+ * اشرح/شرح/توضیح/הסבר/อธิบาย=explain).
+ *
+ * KNOWN, ACCEPTED false-positive class (#1140): substring matching cannot see
+ * homograph compounds — Korean 구조 (structure) also fires inside 구조대
+ * (rescue squad). Verified unfixable at this layer: ICU word segmentation
+ * (Intl.Segmenter) returns 구조대 and the particle form 구조가 (which the gate
+ * MUST keep matching) as equally opaque single segments, and a 구조대 denylist
+ * would break 구조대로 ("according to the structure" — 구조 + the 대로
+ * particle), a legitimate structural prompt. The miss rate this design avoids
+ * (silently no-op'ing every prompt in these languages, #994) outweighs the
+ * occasional off-domain fire.
+ */
+const STRUCTURAL_UNSEGMENTED = /如何|怎么|怎麼|在哪|哪里|哪裡|追踪|跟踪|追蹤|追跡|トレース|流程|流向|流れ|路径|路徑|経路|调用|調用|呼び出|依赖|依賴|依存|影响|影響|实现|實現|実装|架构|架構|アーキテクチャ|结构|結構|構造|介绍|介紹|解析|分析|原理|机制|機制|仕組み|説明|動作|どうやって|どのように|어떻게|어디|호출|흐름|경로|의존|영향|구현|구조|아키텍처|추적|동작|작동|설명|كيف|أين|اين|يستدعي|استدعاء|يعتمد|تعتمد|يؤثر|تأثير|معماري|بنية|هيكل|تدفق|مسار|تتبع|يعمل|تعمل|اشرح|شرح|چگونه|چطور|کجا|فراخوان|وابسته|تأثیر|معماری|ساختار|مسیر|توضیح|איך|איפה|קורא|תלוי|משפיע|ארכיטקטור|מבנה|זרימה|נתיב|הסבר|อย่างไร|ยังไง|ที่ไหน|เรียกใช้|ขึ้นอยู่กับ|ผลกระทบ|สถาปัตยกรรม|โครงสร้าง|เส้นทาง|ติดตาม|ทำงาน|อธิบาย/;
 /** Doc/data/asset file extensions — a `name.ext` of this kind is a file
  *  reference, not a code symbol, so it must not trip the member-access signal. */
 const DOC_DATA_EXT = /\.(md|markdown|txt|rst|json|ya?ml|toml|lock|csv|tsv|log|ini|cfg|conf|env|xml|html?|png|jpe?g|gif|svg|pdf)$/i;
 /**
- * Does `prompt` contain an explicit structural keyword (English or CJK)? A
- * keyword is a strong, self-contained signal, so the front-load hook fires on it
- * directly — no graph check needed. (A *code-token* match, by contrast, is only
- * a candidate the hook verifies against the graph first; see {@link extractCodeTokens}.)
+ * Does `prompt` contain an explicit structural keyword? A keyword is a strong,
+ * self-contained signal, so the front-load hook fires on it directly — no graph
+ * check needed. (A *code-token* match, by contrast, is only a candidate the
+ * hook verifies against the graph first; see {@link extractCodeTokens}.)
+ * Coverage is multilingual (#994, #1126): the ~29 languages with the largest
+ * developer populations, across Latin, Cyrillic, Greek, CJK, Hangul, Arabic,
+ * Hebrew, Thai, and Devanagari scripts. Languages beyond the keyword table
+ * still fire through the language-agnostic code-token path.
  */
 function hasStructuralKeyword(prompt) {
-    return !!prompt && (STRUCTURAL_EN.test(prompt) || STRUCTURAL_CJK.test(prompt));
+    return (!!prompt &&
+        (STRUCTURAL_WORDS_RE.test(prompt) || STRUCTURAL_STEMS_RE.test(prompt) || STRUCTURAL_UNSEGMENTED.test(prompt)));
 }
 /**
  * Identifier-shaped tokens in `prompt` — camelCase / PascalCase-with-inner-cap,
@@ -333,7 +524,7 @@ function extractCodeTokens(prompt) {
 /**
  * Cheap, graph-free candidate gate for the front-load hook: could `prompt` be a
  * structural / flow / impact / "where-how" question worth front-loading context
- * for? True on an explicit keyword (English or CJK, issue #994) OR an
+ * for? True on an explicit keyword in any covered language (#994, #1126) OR an
  * identifier-shaped token. A keyword is sufficient to fire on its own; a
  * token-only match is only a candidate the hook then verifies against the graph
  * (a brand name like `JavaScript` is token-shaped but isn't a symbol). Every