codegraph-java 0.1.0

package/dist/extraction/store-worker.js

@@ -0,0 +1,139 @@
+"use strict";
+/**
+ * Store worker — dedicated writer thread for the bulk-index store phase.
+ *
+ * During a fresh full index the main thread's biggest serial cost is executing
+ * the per-file INSERT batches. This worker owns that work on its own SQLite
+ * connection: the orchestrator posts one message per file (in file order) and
+ * the worker applies them in arrival order, which preserves the #1015
+ * insertion-order determinism exactly as if the main thread had run the same
+ * calls. The main thread performs NO database access while the writer is
+ * active (fresh-DB path only), so there is no cross-connection contention.
+ *
+ * Protocol (main → worker):
+ *   {type:'open', dbPath, fastInit}  → open connection, reply {type:'ready'}
+ *   {type:'bundle', bundle}          → apply one file's store bundle
+ *   {type:'drain', id}               → reply {type:'drained', id} (in-order ⇒ all prior bundles applied)
+ *   {type:'close'}                   → close DB and exit
+ * Worker → main: {type:'ready'} | {type:'drained', id} | {type:'error', message}
+ *
+ * A bundle failure does not kill the worker; the first error is reported and
+ * the client surfaces it at drain(), matching the main-thread path where a
+ * store exception propagates out of the ordered-flush chain.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+// Compile cache FIRST — same worker-boot rationale as parse-worker.ts.
+try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    require('node:module').enableCompileCache?.();
+}
+catch { /* cache is best-effort */ }
+const worker_threads_1 = require("worker_threads");
+const queries_1 = require("../db/queries");
+const sqlite_adapter_1 = require("../db/sqlite-adapter");
+const store_writer_1 = require("./store-writer");
+const decode_1 = require("./kernel/decode");
+if (!worker_threads_1.parentPort) {
+    throw new Error('store-worker must be run as a worker thread');
+}
+const port = worker_threads_1.parentPort;
+let db = null;
+let queries = null;
+// CODEGRAPH_SYNTH_TIMINGS: split the writer lane's busy time into its two
+// halves — kernel-buffer decode+finalize (JS-object materialization, the §4d
+// buffer→bind candidate) vs the SQL bundle store — printed once at close.
+const STORE_TIMINGS = !!process.env.CODEGRAPH_SYNTH_TIMINGS;
+let decodeNs = 0n;
+let storeNs = 0n;
+let bundleCount = 0;
+let kernelBundleCount = 0;
+/** Decode a kernel bundle's buffers into the standard pre-filtered StoreBundle. */
+function decodeKernelBundle(bundle) {
+    const asBuf = (u) => Buffer.from(u.buffer, u.byteOffset, u.byteLength);
+    const decoded = (0, decode_1.decodeExtractBuffers)({
+        meta: asBuf(bundle.buffers.meta),
+        nodes: asBuf(bundle.buffers.nodes),
+        edges: asBuf(bundle.buffers.edges),
+        refs: asBuf(bundle.buffers.refs),
+        arena: asBuf(bundle.buffers.arena),
+    }, bundle.filePath, bundle.language);
+    return (0, store_writer_1.finalizeStoreBundle)(decoded, bundle.filePath, bundle.language, bundle.file);
+}
+port.on('message', (msg) => {
+    try {
+        switch (msg.type) {
+            case 'open': {
+                const created = (0, sqlite_adapter_1.createDatabase)(msg.dbPath);
+                db = created.db;
+                // Mirrors db/index.ts configureConnection, with the same fast-init
+                // durability trade the main connection applies for fresh builds.
+                db.pragma('busy_timeout = 5000');
+                db.pragma('foreign_keys = ON');
+                if (msg.fastInit) {
+                    db.pragma('journal_mode = MEMORY');
+                    db.pragma('synchronous = OFF');
+                }
+                else {
+                    db.pragma('synchronous = NORMAL');
+                }
+                db.pragma('cache_size = -64000');
+                db.pragma('temp_store = MEMORY');
+                queries = new queries_1.QueryBuilder(db);
+                port.postMessage({ type: 'ready' });
+                break;
+            }
+            case 'bundle': {
+                if (!queries)
+                    throw new Error('store-worker: bundle before open');
+                if (STORE_TIMINGS) {
+                    bundleCount++;
+                    const t0 = process.hrtime.bigint();
+                    let bundle;
+                    if ('kernel' in msg.bundle) {
+                        kernelBundleCount++;
+                        bundle = decodeKernelBundle(msg.bundle);
+                    }
+                    else {
+                        bundle = msg.bundle;
+                    }
+                    const t1 = process.hrtime.bigint();
+                    queries.storeFileBundle(bundle);
+                    decodeNs += t1 - t0;
+                    storeNs += process.hrtime.bigint() - t1;
+                    port.postMessage({ type: 'ack' });
+                    break;
+                }
+                const bundle = 'kernel' in msg.bundle ? decodeKernelBundle(msg.bundle) : msg.bundle;
+                queries.storeFileBundle(bundle);
+                port.postMessage({ type: 'ack' });
+                break;
+            }
+            case 'drain': {
+                port.postMessage({ type: 'drained', id: msg.id });
+                break;
+            }
+            case 'close': {
+                if (STORE_TIMINGS && bundleCount > 0) {
+                    console.error(`[store-timing] bundles=${bundleCount} (kernel=${kernelBundleCount}) decode=${(Number(decodeNs / 1000000n) / 1000).toFixed(2)}s store=${(Number(storeNs / 1000000n) / 1000).toFixed(2)}s`);
+                }
+                try {
+                    db?.close();
+                }
+                catch {
+                    /* already closed */
+                }
+                process.exit(0);
+                break;
+            }
+        }
+    }
+    catch (err) {
+        // The error reply doubles as the bundle's ack so the client's outstanding
+        // counter still drains after a failure.
+        port.postMessage({
+            type: 'error',
+            message: err instanceof Error ? err.message : String(err),
+        });
+    }
+});
+//# sourceMappingURL=store-worker.js.map

package/dist/extraction/store-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-worker.js","sourceRoot":"","sources":["../../src/extraction/store-worker.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;AAEH,uEAAuE;AACvE,IAAI,CAAC;IACH,iEAAiE;IAChE,OAAO,CAAC,aAAa,CAAyC,CAAC,kBAAkB,EAAE,EAAE,CAAC;AACzF,CAAC;AAAC,MAAM,CAAC,CAAC,0BAA0B,CAAC,CAAC;AAEtC,mDAA4C;AAC5C,2CAA6C;AAC7C,yDAAsE;AACtE,iDAA+F;AAC/F,4CAAuD;AAEvD,IAAI,CAAC,2BAAU,EAAE,CAAC;IAChB,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;AACjE,CAAC;AACD,MAAM,IAAI,GAAG,2BAAU,CAAC;AAExB,IAAI,EAAE,GAA0B,IAAI,CAAC;AACrC,IAAI,OAAO,GAAwB,IAAI,CAAC;AAExC,0EAA0E;AAC1E,6EAA6E;AAC7E,0EAA0E;AAC1E,MAAM,aAAa,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC;AAC5D,IAAI,QAAQ,GAAG,EAAE,CAAC;AAClB,IAAI,OAAO,GAAG,EAAE,CAAC;AACjB,IAAI,WAAW,GAAG,CAAC,CAAC;AACpB,IAAI,iBAAiB,GAAG,CAAC,CAAC;AAQ1B,mFAAmF;AACnF,SAAS,kBAAkB,CAAC,MAAyB;IACnD,MAAM,KAAK,GAAG,CAAC,CAAa,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC;IACnF,MAAM,OAAO,GAAG,IAAA,6BAAoB,EAClC;QACE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;QAChC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;QAClC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;QAClC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;QAChC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;KACnC,EACD,MAAM,CAAC,QAAQ,EACf,MAAM,CAAC,QAAQ,CAChB,CAAC;IACF,OAAO,IAAA,kCAAmB,EAAC,OAAO,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;AACrF,CAAC;AAED,IAAI,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,GAAc,EAAE,EAAE;IACpC,IAAI,CAAC;QACH,QAAQ,GAAG,CAAC,IAAI,EAAE,CAAC;YACjB,KAAK,MAAM,CAAC,CAAC,CAAC;gBACZ,MAAM,OAAO,GAAG,IAAA,+BAAc,EAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBAC3C,EAAE,GAAG,OAAO,CAAC,EAAE,CAAC;gBAChB,mEAAmE;gBACnE,iEAAiE;gBACjE,EAAE,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC;gBACjC,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;gBAC/B,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;oBACjB,EAAE,CAAC,MAAM,CAAC,uBAAuB,CAAC,CAAC;oBACnC,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;gBACjC,CAAC;qBAAM,CAAC;oBACN,EAAE,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC;gBACpC,CAAC;gBACD,EAAE,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC;gBACjC,EAAE,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC;gBACjC,OAAO,GAAG,IAAI,sBAAY,CAAC,EAAE,CAAC,CAAC;gBAC/B,IAAI,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;gBACpC,MAAM;YACR,CAAC;YACD,KAAK,QAAQ,CAAC,CAAC,CAAC;gBACd,IAAI,CAAC,OAAO;oBAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;gBAClE,IAAI,aAAa,EAAE,CAAC;oBAClB,WAAW,EAAE,CAAC;oBACd,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;oBACnC,IAAI,MAAmB,CAAC;oBACxB,IAAI,QAAQ,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;wBAC3B,iBAAiB,EAAE,CAAC;wBACpB,MAAM,GAAG,kBAAkB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;oBAC1C,CAAC;yBAAM,CAAC;wBACN,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;oBACtB,CAAC;oBACD,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;oBACnC,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;oBAChC,QAAQ,IAAI,EAAE,GAAG,EAAE,CAAC;oBACpB,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC;oBACxC,IAAI,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;oBAClC,MAAM;gBACR,CAAC;gBACD,MAAM,MAAM,GAAG,QAAQ,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,kBAAkB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;gBACpF,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;gBAChC,IAAI,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;gBAClC,MAAM;YACR,CAAC;YACD,KAAK,OAAO,CAAC,CAAC,CAAC;gBACb,IAAI,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;gBAClD,MAAM;YACR,CAAC;YACD,KAAK,OAAO,CAAC,CAAC,CAAC;gBACb,IAAI,aAAa,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;oBACrC,OAAO,CAAC,KAAK,CACX,0BAA0B,WAAW,YAAY,iBAAiB,YAAY,CAAC,MAAM,CAAC,QAAQ,GAAG,QAAU,CAAC,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,GAAG,QAAU,CAAC,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAC9L,CAAC;gBACJ,CAAC;gBACD,IAAI,CAAC;oBACH,EAAE,EAAE,KAAK,EAAE,CAAC;gBACd,CAAC;gBAAC,MAAM,CAAC;oBACP,oBAAoB;gBACtB,CAAC;gBACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBAChB,MAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,0EAA0E;QAC1E,wCAAwC;QACxC,IAAI,CAAC,WAAW,CAAC;YACf,IAAI,EAAE,OAAO;YACb,OAAO,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SAC1D,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC,CAAC"}

package/dist/extraction/store-writer.d.ts

@@ -0,0 +1,63 @@
+/**
+ * StoreWriter — main-thread client for the store worker (see store-worker.ts).
+ *
+ * Used ONLY on the fresh-DB bulk path: bundles are posted in file order and the
+ * worker applies them in arrival order, so rowid assignment (and therefore
+ * resolution's insertion-order disambiguation) is byte-identical to the
+ * main-thread store. Kill switch: CODEGRAPH_NO_STORE_WORKER=1.
+ */
+import { ExtractionResult, Language, Node, Edge, UnresolvedReference, FileRecord } from '../types';
+/** One file's complete store payload (pre-filtered — see storeFileBundle). */
+export interface StoreBundle {
+    nodes: Node[];
+    edges: Edge[];
+    refs: UnresolvedReference[];
+    file: FileRecord;
+}
+/**
+ * A kernel deferred-decode payload: the file's raw table buffers plus the
+ * FileRecord the main thread built from meta counts. The store WORKER decodes
+ * and finalizes (same filters as the object path), so per-node objects never
+ * exist on the main thread.
+ */
+export interface KernelStoreBundle {
+    kernel: true;
+    filePath: string;
+    language: Language;
+    buffers: NonNullable<ExtractionResult['kernelBuffers']>;
+    file: FileRecord;
+}
+/**
+ * The validation/denormalization every bundle gets before storeFileBundle —
+ * shared by the orchestrator's object path and the store worker's kernel
+ * decode path so the two can never drift:
+ *   - nodes missing identity fields are dropped (#42-class safety),
+ *   - edges must connect inserted nodes (FK integrity),
+ *   - refs must originate from inserted nodes and carry the denormalized
+ *     filePath/language the resolver reads.
+ */
+export declare function finalizeStoreBundle(result: Pick<ExtractionResult, 'nodes' | 'edges' | 'unresolvedReferences'>, filePath: string, language: Language, file: FileRecord): StoreBundle;
+export declare class StoreWriter {
+    private worker;
+    private readyPromise;
+    private firstError;
+    private drainWaiters;
+    private nextDrainId;
+    private exited;
+    /** Bundles posted but not yet acked — the queue-depth backpressure signal. */
+    private outstanding;
+    private belowWaiters;
+    constructor(workerScriptPath: string, dbPath: string, fastInit: boolean);
+    private failAll;
+    private settleOne;
+    ready(): Promise<void>;
+    /** Post one file's bundle. Throws immediately if the writer already failed. */
+    send(bundle: StoreBundle | KernelStoreBundle): void;
+    /** Backpressure: resolves once fewer than `limit` bundles are un-acked. */
+    waitBelow(limit: number): Promise<void>;
+    /** Resolves when every bundle posted before this call has been applied. */
+    drain(): Promise<void>;
+    /** Close the worker's DB connection and join the thread. */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=store-writer.d.ts.map

package/dist/extraction/store-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-writer.d.ts","sourceRoot":"","sources":["../../src/extraction/store-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEnG,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,IAAI,EAAE,mBAAmB,EAAE,CAAC;IAC5B,IAAI,EAAE,UAAU,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,IAAI,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,WAAW,CAAC,gBAAgB,CAAC,eAAe,CAAC,CAAC,CAAC;IACxD,IAAI,EAAE,UAAU,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,OAAO,GAAG,OAAO,GAAG,sBAAsB,CAAC,EAC1E,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,UAAU,GACf,WAAW,CAcb;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,UAAU,CAAsB;IACxC,OAAO,CAAC,YAAY,CAA0E;IAC9F,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,8EAA8E;IAC9E,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,YAAY,CAAqD;gBAE7D,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO;IA+CvE,OAAO,CAAC,OAAO;IAUf,OAAO,CAAC,SAAS;IAWjB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,+EAA+E;IAC/E,IAAI,CAAC,MAAM,EAAE,WAAW,GAAG,iBAAiB,GAAG,IAAI;IAOnD,2EAA2E;IAC3E,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOvC,2EAA2E;IAC3E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAWtB,4DAA4D;IACtD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAa7B"}

package/dist/extraction/store-writer.js

@@ -0,0 +1,174 @@
+"use strict";
+/**
+ * StoreWriter — main-thread client for the store worker (see store-worker.ts).
+ *
+ * Used ONLY on the fresh-DB bulk path: bundles are posted in file order and the
+ * worker applies them in arrival order, so rowid assignment (and therefore
+ * resolution's insertion-order disambiguation) is byte-identical to the
+ * main-thread store. Kill switch: CODEGRAPH_NO_STORE_WORKER=1.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StoreWriter = void 0;
+exports.finalizeStoreBundle = finalizeStoreBundle;
+const worker_threads_1 = require("worker_threads");
+/**
+ * The validation/denormalization every bundle gets before storeFileBundle —
+ * shared by the orchestrator's object path and the store worker's kernel
+ * decode path so the two can never drift:
+ *   - nodes missing identity fields are dropped (#42-class safety),
+ *   - edges must connect inserted nodes (FK integrity),
+ *   - refs must originate from inserted nodes and carry the denormalized
+ *     filePath/language the resolver reads.
+ */
+function finalizeStoreBundle(result, filePath, language, file) {
+    const validNodes = result.nodes.filter((n) => n.id && n.kind && n.name && n.filePath && n.language);
+    const insertedIds = new Set(validNodes.map((n) => n.id));
+    const validEdges = result.edges.filter((e) => insertedIds.has(e.source) && insertedIds.has(e.target));
+    const validRefs = result.unresolvedReferences
+        .filter((ref) => insertedIds.has(ref.fromNodeId))
+        .map((ref) => ({
+        ...ref,
+        filePath: ref.filePath ?? filePath,
+        language: ref.language ?? language,
+    }));
+    return { nodes: validNodes, edges: validEdges, refs: validRefs, file };
+}
+class StoreWriter {
+    worker;
+    readyPromise;
+    firstError = null;
+    drainWaiters = new Map();
+    nextDrainId = 0;
+    exited = false;
+    /** Bundles posted but not yet acked — the queue-depth backpressure signal. */
+    outstanding = 0;
+    belowWaiters = [];
+    constructor(workerScriptPath, dbPath, fastInit) {
+        this.worker = new worker_threads_1.Worker(workerScriptPath);
+        let readyResolve;
+        let readyReject;
+        this.readyPromise = new Promise((resolve, reject) => {
+            readyResolve = resolve;
+            readyReject = reject;
+        });
+        this.worker.on('message', (msg) => {
+            if (msg.type === 'ready') {
+                readyResolve();
+            }
+            else if (msg.type === 'ack') {
+                this.settleOne();
+            }
+            else if (msg.type === 'drained' && msg.id !== undefined) {
+                const waiter = this.drainWaiters.get(msg.id);
+                this.drainWaiters.delete(msg.id);
+                if (!waiter)
+                    return;
+                if (this.firstError)
+                    waiter.reject(this.firstError);
+                else
+                    waiter.resolve();
+            }
+            else if (msg.type === 'error') {
+                if (!this.firstError)
+                    this.firstError = new Error(`store worker: ${msg.message}`);
+                this.settleOne(); // the error reply is also the failed bundle's ack
+            }
+        });
+        this.worker.on('error', (err) => {
+            this.failAll(err instanceof Error ? err : new Error(String(err)));
+            readyReject(this.firstError);
+        });
+        this.worker.on('exit', (code) => {
+            this.exited = true;
+            if (code !== 0) {
+                this.failAll(new Error(`store worker exited with code ${code}`));
+                readyReject(this.firstError);
+            }
+            else if (this.drainWaiters.size > 0 || this.belowWaiters.length > 0) {
+                // A clean exit with waiters pending is a protocol violation (only
+                // close() should end the worker) — settle the waiters instead of
+                // hanging the index forever.
+                this.failAll(new Error('store worker exited before drain completed'));
+            }
+        });
+        this.worker.postMessage({ type: 'open', dbPath, fastInit });
+        // The worker holds the event loop open only until close(); don't unref —
+        // bundles must never be dropped because main ran out of work.
+    }
+    failAll(err) {
+        if (!this.firstError)
+            this.firstError = err;
+        for (const [, waiter] of this.drainWaiters)
+            waiter.reject(this.firstError);
+        this.drainWaiters.clear();
+        this.outstanding = 0;
+        const waiters = this.belowWaiters;
+        this.belowWaiters = [];
+        for (const w of waiters)
+            w.resolve(); // send() will surface firstError
+    }
+    settleOne() {
+        if (this.outstanding > 0)
+            this.outstanding--;
+        if (this.belowWaiters.length === 0)
+            return;
+        const still = [];
+        for (const w of this.belowWaiters) {
+            if (this.outstanding < w.limit)
+                w.resolve();
+            else
+                still.push(w);
+        }
+        this.belowWaiters = still;
+    }
+    ready() {
+        return this.readyPromise;
+    }
+    /** Post one file's bundle. Throws immediately if the writer already failed. */
+    send(bundle) {
+        if (this.firstError)
+            throw this.firstError;
+        if (this.exited)
+            throw new Error('store worker already exited');
+        this.outstanding++;
+        this.worker.postMessage({ type: 'bundle', bundle });
+    }
+    /** Backpressure: resolves once fewer than `limit` bundles are un-acked. */
+    waitBelow(limit) {
+        if (this.firstError || this.exited || this.outstanding < limit)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            this.belowWaiters.push({ limit, resolve });
+        });
+    }
+    /** Resolves when every bundle posted before this call has been applied. */
+    drain() {
+        if (this.firstError)
+            return Promise.reject(this.firstError);
+        if (this.exited)
+            return Promise.reject(new Error('store worker already exited'));
+        const id = this.nextDrainId++;
+        const p = new Promise((resolve, reject) => {
+            this.drainWaiters.set(id, { resolve, reject });
+        });
+        this.worker.postMessage({ type: 'drain', id });
+        return p;
+    }
+    /** Close the worker's DB connection and join the thread. */
+    async close() {
+        if (this.exited)
+            return;
+        this.worker.postMessage({ type: 'close' });
+        await new Promise((resolve) => {
+            const t = setTimeout(() => {
+                void this.worker.terminate().then(() => resolve());
+            }, 5000);
+            this.worker.once('exit', () => {
+                clearTimeout(t);
+                resolve();
+            });
+        });
+    }
+}
+exports.StoreWriter = StoreWriter;
+//# sourceMappingURL=store-writer.js.map

package/dist/extraction/store-writer.js.map

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

package/dist/extraction/syntax-tokens.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Syntax classification from the engine's own tree-sitter parse (CG-57).
+ *
+ * The viewer used to run a second highlighter (Shiki + 56 pruned TextMate
+ * grammars) over source the engine had already parsed with a real grammar. This
+ * takes the classification off the tree instead, which removes the second
+ * dependency, the second grammar set, and — the part that actually mattered —
+ * the second opinion: a `.ts` file is now read by exactly the grammar that
+ * decided what its symbols are.
+ *
+ * ## What comes out
+ *
+ * A flat, ordered, non-overlapping list of {@link SyntaxSpan}s over the source
+ * string. Gaps between spans are whitespace and are the caller's to fill. The
+ * classes are deliberately few, because the design's code colouring is
+ * near-monochrome: comments recede, strings and numbers recede one step less,
+ * keywords carry weight rather than hue, and the only colour in the body is a
+ * call site the graph resolved.
+ *
+ * ## How a node becomes a class
+ *
+ * The rules are language-agnostic on purpose — the engine indexes 40-odd
+ * languages and a per-grammar scope table would be 40 tables to keep true:
+ *
+ * * a node whose type mentions `comment` is a comment, whole, undescended;
+ * * inside a string node every leaf is string, *except* below an interpolation,
+ *   where the code starts again (so `${user.name()}` still links);
+ * * a numeric literal node is a number;
+ * * an **anonymous** leaf is a keyword when its text is a bare word and
+ *   punctuation otherwise — this is what makes `func`, `fn`, `def`, `END-IF`
+ *   and `Sub` all land as keywords without naming any of them;
+ * * a **named** leaf whose text is identifier-shaped is an identifier, unless
+ *   the grammar called it a type name, or the extractor's own definition tables
+ *   say it is the name of a definition.
+ *
+ * The last of those is the one place per-language knowledge is used, and it is
+ * reused rather than restated: {@link EXTRACTORS} already names every node type
+ * that declares something in each language, plus the field its name hangs on.
+ */
+import type { Node as SyntaxNode } from 'web-tree-sitter';
+import { Language } from '../types';
+/**
+ * Every class a token can carry, in wire order.
+ *
+ * `other` is punctuation and whitespace both. The design spec lists them apart
+ * (`punct` vs the gaps) but they paint identically — plain ink — and splitting
+ * them would roughly double the token count on a dense line to express a
+ * difference nothing draws.
+ */
+export declare const SYNTAX_TOKEN_CLASSES: readonly ["other", "ident", "comment", "string", "keyword", "number", "type", "def"];
+export type SyntaxTokenClass = (typeof SYNTAX_TOKEN_CLASSES)[number];
+/** A classified run of the source, by JS string index. Half-open. */
+export interface SyntaxSpan {
+    start: number;
+    end: number;
+    cls: SyntaxTokenClass;
+}
+/**
+ * Classify one parsed tree into spans.
+ *
+ * Exported for tests and for anything that already holds a tree; the usual
+ * entry point is {@link tokenizeSource}, which parses first.
+ */
+export declare function classifyTree(root: SyntaxNode, source: string, language: Language, offset?: number): SyntaxSpan[];
+/**
+ * A stretch of a file written in a different language from the file itself.
+ *
+ * Single-file components are the only case: a `.svelte`, `.vue` or `.astro`
+ * file has no tree-sitter grammar of its own here, but its `<script>` block —
+ * where every symbol the engine indexed in that file lives — is ordinary
+ * TypeScript or JavaScript. The extractors already delegate exactly this way,
+ * so the viewer reads a component's code with the same grammar the graph was
+ * built from. The surrounding markup stays unclassified, which under a
+ * near-monochrome theme costs the recession on tag names and attribute strings
+ * and nothing else.
+ */
+export interface SyntaxRegion {
+    start: number;
+    end: number;
+    language: Language;
+}
+/**
+ * The sub-language regions of a file, or null when the file is one language.
+ *
+ * Null and an empty array mean different things: null is "parse the whole file
+ * as `language`", empty is "this file has a grammar for none of it".
+ */
+export declare function syntaxRegionsFor(source: string, language: Language): SyntaxRegion[] | null;
+export interface TokenizeResult {
+    spans: SyntaxSpan[];
+    /** The grammar(s) that produced them, for the payload's `grammar` field. */
+    grammars: string[];
+}
+/**
+ * Parse `source` and classify it.
+ *
+ * Returns null when nothing in the file has a grammar — a plain answer, which
+ * every caller here already knows how to serve. Never throws: a grammar that
+ * fails to load or a parse that comes back empty is the same outcome as not
+ * having one.
+ */
+export declare function tokenizeSource(source: string, language: Language): Promise<TokenizeResult | null>;
+//# sourceMappingURL=syntax-tokens.d.ts.map

package/dist/extraction/syntax-tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"syntax-tokens.d.ts","sourceRoot":"","sources":["../../src/extraction/syntax-tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAE,IAAI,IAAI,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAOpC;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,sFASvB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAErE,qEAAqE;AACrE,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,gBAAgB,CAAC;CACvB;AAmKD;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,EAClB,MAAM,SAAI,GACT,UAAU,EAAE,CAYd;AAmFD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAOD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,YAAY,EAAE,GAAG,IAAI,CAyB1F;AAID,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAuBhC"}