gitnexus 1.6.9 → 1.6.10-aptos.0

package/dist/core/ingestion/utils/line-base.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Convert a 1-based source line number to the 0-based convention used by
+ * GraphNode `startLine`/`endLine`.
+ *
+ * The graph layer stores line numbers 0-based (tree-sitter `startPosition.row`),
+ * and this is load-bearing: the taint/PDG/CFG join and the MCP consumers all add
+ * `+ 1` to recover 1-based (see `summary-harvest-driver.ts` — "Function/Method
+ * node startLine is 0-based"). Most emitters get 0-based for free from
+ * tree-sitter. The exceptions are the regex-based COBOL/JCL processors (their
+ * parsers use `lineNum = i + 1`) and the scope-capture path (`Capture` ranges
+ * are 1-based per RFC §2.1). Those must convert to 0-based when they build a
+ * graph node, or the exact-content slice in `csv-generator.ts` drops the
+ * symbol's declaration line (#2379) and reported line numbers are off (#2377).
+ *
+ * Apply this ONLY at the graph-node `startLine:`/`endLine:` assignment. The
+ * parser-internal 1-based values (`.line`, `prog.startLine`) stay 1-based —
+ * they feed `L${line}` node/edge IDs and line-range containment checks that
+ * must not shift. The clamp guards degenerate inputs (line 0 / empty files).
+ */
+export declare const toZeroBasedLine: (oneBasedLine: number) => number;

package/dist/core/ingestion/utils/line-base.js

@@ -0,0 +1,20 @@
+/**
+ * Convert a 1-based source line number to the 0-based convention used by
+ * GraphNode `startLine`/`endLine`.
+ *
+ * The graph layer stores line numbers 0-based (tree-sitter `startPosition.row`),
+ * and this is load-bearing: the taint/PDG/CFG join and the MCP consumers all add
+ * `+ 1` to recover 1-based (see `summary-harvest-driver.ts` — "Function/Method
+ * node startLine is 0-based"). Most emitters get 0-based for free from
+ * tree-sitter. The exceptions are the regex-based COBOL/JCL processors (their
+ * parsers use `lineNum = i + 1`) and the scope-capture path (`Capture` ranges
+ * are 1-based per RFC §2.1). Those must convert to 0-based when they build a
+ * graph node, or the exact-content slice in `csv-generator.ts` drops the
+ * symbol's declaration line (#2379) and reported line numbers are off (#2377).
+ *
+ * Apply this ONLY at the graph-node `startLine:`/`endLine:` assignment. The
+ * parser-internal 1-based values (`.line`, `prog.startLine`) stay 1-based —
+ * they feed `L${line}` node/edge IDs and line-range containment checks that
+ * must not shift. The clamp guards degenerate inputs (line 0 / empty files).
+ */
+export const toZeroBasedLine = (oneBasedLine) => Math.max(0, oneBasedLine - 1);

package/dist/core/ingestion/utils/symbol-labels.d.ts

@@ -0,0 +1,21 @@
+import type { NodeLabel } from '../../../_shared/index.js';
+/**
+ * Graph-node labels that represent a resolvable code symbol — a definition with
+ * its own source span (function, type, member, module-like container).
+ *
+ * These get EXACT source-span content in the FTS index: `csv-generator.ts`
+ * slices exactly `[startLine, endLine]` for them (no ±2 padding), while every
+ * other label keeps the context window. That exactness depends on the 0-based
+ * `startLine`/`endLine` invariant enforced by `line-base.ts` — the slice is only
+ * correct because all emitters store 0-based lines. Keep the two together.
+ *
+ * Single source of truth so the set can't silently drift the way the inline copy
+ * did in #2379.
+ *
+ * NOTE: `group/extractors/manifest-extractor.ts`'s `CUSTOM_CONTRACT_RESOLVE_QUERY`
+ * carries a near-identical hand-list that is intentionally a SUBSET — it excludes
+ * `Namespace`, `Variable`, `Module`. Unifying the two needs a contract-resolution
+ * behavior check (would widen which nodes resolve as contract symbols), so it is
+ * deliberately left separate for now.
+ */
+export declare const SYMBOL_NODE_LABELS: ReadonlySet<NodeLabel>;

package/dist/core/ingestion/utils/symbol-labels.js

@@ -0,0 +1,45 @@
+/**
+ * Graph-node labels that represent a resolvable code symbol — a definition with
+ * its own source span (function, type, member, module-like container).
+ *
+ * These get EXACT source-span content in the FTS index: `csv-generator.ts`
+ * slices exactly `[startLine, endLine]` for them (no ±2 padding), while every
+ * other label keeps the context window. That exactness depends on the 0-based
+ * `startLine`/`endLine` invariant enforced by `line-base.ts` — the slice is only
+ * correct because all emitters store 0-based lines. Keep the two together.
+ *
+ * Single source of truth so the set can't silently drift the way the inline copy
+ * did in #2379.
+ *
+ * NOTE: `group/extractors/manifest-extractor.ts`'s `CUSTOM_CONTRACT_RESOLVE_QUERY`
+ * carries a near-identical hand-list that is intentionally a SUBSET — it excludes
+ * `Namespace`, `Variable`, `Module`. Unifying the two needs a contract-resolution
+ * behavior check (would widen which nodes resolve as contract symbols), so it is
+ * deliberately left separate for now.
+ */
+export const SYMBOL_NODE_LABELS = new Set([
+    'Function',
+    'Method',
+    'Class',
+    'Interface',
+    'CodeElement',
+    'Struct',
+    'Enum',
+    'Macro',
+    'Typedef',
+    'Union',
+    'Namespace',
+    'Trait',
+    'Impl',
+    'TypeAlias',
+    'Const',
+    'Static',
+    'Variable',
+    'Property',
+    'Record',
+    'Delegate',
+    'Annotation',
+    'Constructor',
+    'Template',
+    'Module',
+]);

package/dist/core/ingestion/workers/parse-worker.d.ts

@@ -113,6 +113,21 @@ export interface ExtractedDecoratorRoute {
      * participate in `include_router(prefix=...)` joining.
      */
     decoratorReceiver?: string;
+    /**
+     * Raw text of a non-literal decorator path argument (`#2391`), e.g.
+     * `API_V1_WIDGETS_GET` or `API_V1 + "/widgets"`. Present only when the
+     * decorator's first argument was NOT a string literal, in which case
+     * `routePath` is empty and parse-impl resolves the constant cross-file (or
+     * drops the route on failure). Absent for ordinary string-literal routes.
+     */
+    routePathExpr?: string;
+    /**
+     * Parsed operand list for {@link routePathExpr} — an identifier reference or a
+     * `+`-concatenation, in the {@link Operand} shape the constant resolver folds.
+     * `undefined` when the expression was not a foldable string form (e.g. an
+     * attribute access), in which case the route is dropped at resolution.
+     */
+    routePathOperands?: Operand[];
     /**
      * FastAPI `app.include_router(prefix='/x')` prefix that applies to
      * this route. Filled by parse-impl after cross-file aggregation; the
@@ -131,6 +146,17 @@ export interface ExtractedDecoratorRoute {
      */
     handlerName?: string;
 }
+/**
+ * One Python file's module-level string constants (#2391), used by parse-impl to
+ * resolve non-literal decorator route paths cross-file. `constants` is the
+ * `Map`-based {@link ModuleConstants} shape — it survives the worker
+ * `postMessage` boundary (structured clone) and the parse cache
+ * (`mapReplacer`/`mapReviver`) without conversion.
+ */
+export interface ExtractedModuleConstants {
+    filePath: string;
+    constants: ModuleConstants;
+}
 export interface ExtractedToolDef {
     filePath: string;
     toolName: string;
@@ -211,6 +237,13 @@ export interface ParseWorkerResult {
      * predate the field; consumers must guard with `if (… ?? [])`).
      */
     routerModuleAliases?: ExtractedRouterModuleAlias[];
+    /**
+     * Per-file Python module-level string constants (#2391). parse-impl aggregates
+     * these into a repo-wide, file-path-keyed map and resolves each decorator
+     * route's non-literal path expression against it. Optional for cache backward
+     * compatibility (older entries predate the field; consumers guard with `?? []`).
+     */
+    moduleConstants?: ExtractedModuleConstants[];
     toolDefs: ExtractedToolDef[];
     ormQueries: ExtractedORMQuery[];
     constructorBindings: FileConstructorBindings[];
@@ -256,3 +289,4 @@ export interface ParseWorkerInput {
  * Appends results to the provided array (avoids allocation when no matches).
  */
 export declare function extractORMQueries(filePath: string, content: string, out: ExtractedORMQuery[]): void;
+import { type ModuleConstants, type Operand } from '../route-extractors/python-const-resolver.js';

package/dist/core/ingestion/workers/parse-worker.js

@@ -751,6 +751,7 @@ export function extractORMQueries(filePath, content, out) {
 // per file; this module does not re-export it. Downstream consumers
 // import the function and its types directly from `route-extractors/`.
 import { extractFastAPIRouterBindings } from '../route-extractors/fastapi-router-bindings.js';
+import { extractPythonModuleConstants, parseConstOperands, } from '../route-extractors/python-const-resolver.js';
 /**
  * Report a non-fatal worker issue to the pool over IPC so a caught error is not
  * invisible to the operator (#2264). The pool logs it on the main thread AND
@@ -813,7 +814,7 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
         try {
             tree = parseSourceSafe(parser, parseContent, undefined, {
                 bufferSize: getTreeSitterBufferSize(parseContent),
-            });
+            }, file.path);
         }
         catch (err) {
             reportWarning(`Failed to parse file ${file.path}: ${err instanceof Error ? err.message : String(err)}`);
@@ -986,6 +987,12 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
             if (captureMap['decorator'] && captureMap['decorator.name']) {
                 const decoratorName = captureMap['decorator.name'].text;
                 const decoratorArg = captureMap['decorator.arg']?.text;
+                // #2391: the first positional arg captured as either a string node
+                // (`arg_str`, present even for the empty-string literal `""` which has no
+                // `string_content`) or a non-literal expression (`arg_expr`: an
+                // identifier or a `+`-concatenation).
+                const decoratorArgStr = captureMap['decorator.arg_str'];
+                const decoratorArgExpr = captureMap['decorator.arg_expr'];
                 const decoratorReceiver = captureMap['decorator.receiver']?.text;
                 const decoratorNode = captureMap['decorator'];
                 // Store by the decorator's end line — the definition follows immediately after
@@ -994,19 +1001,39 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
                     arg: decoratorArg,
                 });
                 if (ROUTE_DECORATOR_NAMES.has(decoratorName)) {
-                    const routePath = decoratorArg || '';
                     const method = decoratorName.replace('Mapping', '').toUpperCase();
                     const httpMethod = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'].includes(method)
                         ? method
                         : 'GET';
-                    result.decoratorRoutes.push({
+                    const base = {
                         filePath: file.path,
-                        routePath,
                         httpMethod,
                         decoratorName,
                         lineNumber: decoratorNode.startPosition.row + lineOffset,
                         ...(decoratorReceiver ? { decoratorReceiver } : {}),
-                    });
+                    };
+                    if (decoratorArgStr) {
+                        // String-literal path (the fast path, unchanged). Empty-string
+                        // literal `""` has no `string_content` → `decoratorArg` undefined →
+                        // routePath '' (a valid path under an APIRouter prefix).
+                        result.decoratorRoutes.push({ ...base, routePath: decoratorArg ?? '' });
+                    }
+                    else if (decoratorArgExpr) {
+                        // #2391 non-literal path (imported/composed constant). Emit the raw
+                        // expression + its operands for cross-file resolution in parse-impl;
+                        // `routePath` stays empty until resolved (or the route is dropped).
+                        const operands = decoratorArgExpr.type === 'identifier'
+                            ? [{ kind: 'ref', name: decoratorArgExpr.text }]
+                            : parseConstOperands(decoratorArgExpr);
+                        result.decoratorRoutes.push({
+                            ...base,
+                            routePath: '',
+                            routePathExpr: decoratorArgExpr.text,
+                            ...(operands ? { routePathOperands: operands } : {}),
+                        });
+                    }
+                    // Otherwise the first arg is absent or an unsupported shape
+                    // (attribute access, call, …) → skip; never a phantom `POST /`.
                 }
                 // MCP/RPC tool detection: @mcp.tool(), @app.tool(), @server.tool()
                 if (decoratorName === 'tool') {
@@ -1839,6 +1866,14 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
         // came from a `@router.<verb>` decorator. Python-only.
         if (language === SupportedLanguages.Python) {
             extractFastAPIRouterBindings(file.path, parseContent, result.routerIncludes, result.routerImports, (result.routerModuleAliases ??= []), (result.routerConstructorPrefixes ??= []));
+            // #2391: harvest module-level string constants + from-imports so parse-impl
+            // can resolve non-literal decorator route paths cross-file. Only emit for
+            // files that carry something resolvable (a constant definition or an import
+            // binding) to keep the aggregate bounded on large repos.
+            const constants = extractPythonModuleConstants(tree);
+            if (constants.literals.size > 0 || constants.exprs.size > 0 || constants.imports.size > 0) {
+                (result.moduleConstants ??= []).push({ filePath: file.path, constants });
+            }
         }
         // Language-specific decorator route extraction via provider hook.
         // The provider's extractDecoratorRoutes walks the AST for framework-specific

package/dist/core/ingestion/workers/result-merge.js

@@ -32,6 +32,10 @@ export const mergeResult = (target, src) => {
         target.routerModuleAliases ??= [];
         appendAll(target.routerModuleAliases, src.routerModuleAliases);
     }
+    if (src.moduleConstants) {
+        target.moduleConstants ??= [];
+        appendAll(target.moduleConstants, src.moduleConstants);
+    }
     if (src.springTypes) {
         target.springTypes ??= [];
         appendAll(target.springTypes, src.springTypes);

package/dist/core/ingestion/workers/worker-pool.d.ts

@@ -99,6 +99,19 @@ export interface WorkerPoolOptions {
      * created. Default `Math.max(3, poolSize)`.
      */
     consecutiveFailureThreshold?: number;
+    /**
+     * Startup budget in milliseconds for a replacement worker to emit the
+     * `{type:'ready'}` handshake before the pool treats it as a startup
+     * crash (see {@link waitForWorkerReady}). Default 5000; also overridable
+     * via `GITNEXUS_WORKER_READY_TIMEOUT_MS`, mirroring
+     * `GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS`. On a slow or heavily loaded
+     * host, a full pool of workers cold-starting concurrently can
+     * legitimately need more than 5s to load the native grammar bindings —
+     * without the override every slot times out and the pool misclassifies
+     * the slow start as a deterministic startup crash-loop, aborting the
+     * whole analyze.
+     */
+    workerReadyTimeoutMs?: number;
     /**
      * Test-only injection point for the Worker constructor. When provided,
      * the pool uses this factory instead of `new Worker(workerUrl)`. Production
@@ -135,6 +148,19 @@ export interface WorkerPoolOptions {
     pdg?: boolean;
     /** Per-function source-line cap for worker-side CFG construction (0 ⇒ no cap). */
     pdgMaxFunctionLines?: number;
+    /**
+     * Max wall time `terminate()` waits for a retired worker that has NOT yet
+     * reached a JS-visible safe point before giving up on terminating it
+     * (#2432). Terminating a worker thread that is inside an N-API call aborts
+     * the whole process (`Napi::Error` → `std::terminate` → SIGABRT) — and the
+     * same abort fires at plain process exit, so the drain is what makes
+     * shutdown safe. On expiry the worker is left running (unref'd, with its
+     * at-safe-point terminate listener still armed) and a diagnostic is logged.
+     * Default 30000ms — above the C++ capture budget
+     * (`GITNEXUS_CPP_CAPTURE_BUDGET_MS`, 20000ms) so the drain converges for
+     * the known pathological class. 0 ⇒ no wait (test hook).
+     */
+    shutdownDrainMs?: number;
 }
 export declare class WorkerPoolDispatchError extends Error {
     /**
@@ -193,6 +219,8 @@ interface ResolvedWorkerPoolOptions {
     maxRespawnsPerSlot: number;
     maxCumulativeTimeoutMs: number;
     consecutiveFailureThreshold: number;
+    shutdownDrainMs: number;
+    workerReadyTimeoutMs: number;
 }
 export declare function resolveWorkerPoolOptions(options?: WorkerPoolOptions, poolSize?: number): ResolvedWorkerPoolOptions;
 /**

package/dist/core/ingestion/workers/worker-pool.js

@@ -116,17 +116,7 @@ const DEFAULT_TIMEOUT_BACKOFF_FACTOR = 2;
 const DEFAULT_MAX_RESPAWNS_PER_SLOT = 3;
 const DEFAULT_MAX_CUMULATIVE_TIMEOUT_FACTOR = 5;
 const DEFAULT_CONSECUTIVE_FAILURE_THRESHOLD_FLOOR = 3;
-/**
- * Bounded wait for a replacement worker to emit the `{type:'ready'}`
- * handshake from `parse-worker.ts`. Trusting Node's `online` event alone
- * lets a worker that crashes during top-of-script init slip past pool
- * startup — the pool only notices on the first dispatch's idle timeout
- * (default 30s). 5 seconds is a generous budget for parser + grammar
- * imports; if the worker hasn't reported ready by then, it's almost
- * certainly stuck or crashed and the pool should surface the failure
- * fast rather than wait out the dispatch idle timeout.
- */
-const WORKER_READY_TIMEOUT_MS = 5_000;
+const DEFAULT_WORKER_READY_TIMEOUT_MS = 5_000;
 /**
  * Default upper bound on auto-resolved pool size. Past 16 workers the
  * dominant cost shifts from worker-side parsing to main-thread merge /
@@ -231,6 +221,8 @@ function nonNegativeInteger(value) {
         ? Math.floor(parsed)
         : undefined;
 }
+/** See {@link WorkerPoolOptions.shutdownDrainMs}. */
+const DEFAULT_SHUTDOWN_DRAIN_MS = 30_000;
 export function resolveWorkerPoolOptions(options = {}, poolSize) {
     const subBatchIdleTimeoutMs = positiveInteger(options.subBatchIdleTimeoutMs) ??
         positiveInteger(process.env.GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS) ??
@@ -252,6 +244,12 @@ export function resolveWorkerPoolOptions(options = {}, poolSize) {
         consecutiveFailureThreshold: positiveInteger(options.consecutiveFailureThreshold) ??
             positiveInteger(process.env.GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD) ??
             Math.max(DEFAULT_CONSECUTIVE_FAILURE_THRESHOLD_FLOOR, poolSize ?? 0),
+        shutdownDrainMs: nonNegativeInteger(options.shutdownDrainMs) ??
+            nonNegativeInteger(process.env.GITNEXUS_WORKER_SHUTDOWN_DRAIN_MS) ??
+            DEFAULT_SHUTDOWN_DRAIN_MS,
+        workerReadyTimeoutMs: positiveInteger(options.workerReadyTimeoutMs) ??
+            positiveInteger(process.env.GITNEXUS_WORKER_READY_TIMEOUT_MS) ??
+            DEFAULT_WORKER_READY_TIMEOUT_MS,
     };
 }
 /**
@@ -347,6 +345,27 @@ function captureWorkerStderr(worker) {
     // A stderr stream error must never crash the pool.
     stream.on('error', () => undefined);
 }
+/**
+ * Forward a worker's piped stdout to the parent process's stdout, so worker
+ * logs stay visible now that the production factory spawns with
+ * `{ stdout: true }`. Workers with INHERITED stdout have been observed to
+ * crash silently during top-of-script init (exit code 1, nothing on stderr,
+ * roughly half of a concurrently spawned pool) on macOS 26.5 under both
+ * Node 22 and 26; piping stdout eliminates the crash entirely. Piping also
+ * matches the existing stderr handling, so worker output no longer races the
+ * parent's raw fd. No-op when the worker has no `stdout` stream (test
+ * factories).
+ */
+function forwardWorkerStdout(worker) {
+    const stream = worker.stdout;
+    if (!stream)
+        return;
+    stream.on('data', (chunk) => {
+        process.stdout.write(chunk);
+    });
+    // A stdout stream error must never crash the pool.
+    stream.on('error', () => undefined);
+}
 /** Captured stderr tail for a worker, trimmed; '' when nothing was captured. */
 function workerStderrTail(worker) {
     return workerStderrTails.get(worker)?.text.trim() ?? '';
@@ -383,13 +402,14 @@ function workerErrorReason(workerIndex, message, stack) {
  * (parser/grammar import failure, missing native binding) slip past
  * pool startup. The pool then only noticed the dead replacement on the
  * first dispatch's idle timeout (default 30s) — a long stall masking
- * an actual crash. This handshake bounds the wait at
- * {@link WORKER_READY_TIMEOUT_MS} and surfaces init failures as
- * `error` / `exit` / `messageerror` events directly. `messageerror` is
- * wired the same way: a V8 deserialization failure during startup is
- * treated as worker death and rejects the readiness promise.
+ * an actual crash. This handshake bounds the wait at `readyTimeoutMs`
+ * (see {@link WorkerPoolOptions.workerReadyTimeoutMs}) and surfaces init
+ * failures as `error` / `exit` / `messageerror` events directly.
+ * `messageerror` is wired the same way: a V8 deserialization failure
+ * during startup is treated as worker death and rejects the readiness
+ * promise.
  */
-function waitForWorkerReady(worker) {
+function waitForWorkerReady(worker, readyTimeoutMs) {
     return new Promise((resolve, reject) => {
         const cleanup = () => {
             clearTimeout(timer);
@@ -427,8 +447,8 @@ function waitForWorkerReady(worker) {
         // access can fire from the listeners.
         const timer = setTimeout(() => {
             cleanup();
-            reject(new Error(withStderr(worker, `Replacement worker did not report ready within ${WORKER_READY_TIMEOUT_MS}ms — likely crashed during top-of-script init`)));
-        }, WORKER_READY_TIMEOUT_MS);
+            reject(new Error(withStderr(worker, `Replacement worker did not report ready within ${readyTimeoutMs}ms — likely crashed during top-of-script init (slow host? raise GITNEXUS_WORKER_READY_TIMEOUT_MS)`)));
+        }, readyTimeoutMs);
         worker.on('message', onMessage);
         worker.once('error', onError);
         worker.once('exit', onExit);
@@ -558,6 +578,10 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
         : undefined;
     const spawnWorker = options?.workerFactory ??
         ((url) => new Worker(url, {
+            // Piped (not inherited) stdio: stderr for crash capture (#1741),
+            // stdout because inherited stdout triggers silent startup crashes on
+            // some hosts (see forwardWorkerStdout).
+            stdout: true,
             stderr: true,
             workerData: workerStoreData,
             // The CFG visitors build per-function control-flow graphs by RECURSIVE
@@ -571,10 +595,11 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
             // try/catch) and only that function's PDG is skipped, never a crash.
             resourceLimits: { stackSizeMb: 16 },
         }));
-    /** Spawn + wire stderr capture in one step (used by all spawn sites). */
+    /** Spawn + wire stdio capture/forwarding in one step (used by all spawn sites). */
     const spawnAndCapture = (url) => {
         const worker = spawnWorker(url);
         captureWorkerStderr(worker);
+        forwardWorkerStdout(worker);
         return worker;
     };
     const workers = new Array(size);
@@ -608,13 +633,50 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
     // Set by `terminate()` (below). Also read by the self-healing startup loop so
     // a terminate during startup aborts pending backoff/retries (#1741).
     let terminated = false;
+    /** Resolves `true` when `promise` settles within `ms`, else `false`. The
+     *  timer is unref'd so an expiring drain never holds the process open. */
+    const settledWithin = (promise, ms) => {
+        if (ms <= 0)
+            return Promise.resolve(false);
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => resolve(false), ms);
+            timer.unref?.();
+            void promise.then(() => {
+                clearTimeout(timer);
+                resolve(true);
+            });
+        });
+    };
     const terminateTrackedWorkers = async (liveWorkers) => {
         const retired = Array.from(retiredWorkers);
         await Promise.all([
             ...liveWorkers.map((worker) => worker?.terminate().catch(() => undefined)),
-            ...retired.map((record) => record.terminate()),
+            ...retired.map(async (record) => {
+                // #2432: a retired worker that has not reached a JS-visible safe
+                // point may be inside an N-API call — terminating it aborts the
+                // WHOLE process (`Napi::Error` → std::terminate → SIGABRT). Drain:
+                // wait (bounded) for its safe point; on expiry leave it running —
+                // it is unref'd and its at-safe-point terminate listener stays
+                // armed — and log which file wedged it.
+                if (!record.safeToTerminate) {
+                    const drained = await settledWithin(record.safePoint, poolOptions.shutdownDrainMs);
+                    if (!drained) {
+                        logger.warn({
+                            workerIndex: record.workerIndex,
+                            reason: record.reason,
+                            drainMs: poolOptions.shutdownDrainMs,
+                        }, `Worker ${record.workerIndex} is still inside native code after the ` +
+                            `${poolOptions.shutdownDrainMs}ms shutdown drain; leaving it un-terminated ` +
+                            `to avoid a native abort (#2432). It will be terminated at its next safe point.`);
+                        return;
+                    }
+                }
+                await record.terminate();
+            }),
         ]);
-        retiredWorkers.clear();
+        // Undrained records stay tracked so a repeated shutdown call can retry
+        // their (now possibly safe) terminate; record.terminate() removes each
+        // drained record via its cleanup.
     };
     for (let i = 0; i < size; i++) {
         workers[i] = spawnAndCapture(workerUrl);
@@ -665,7 +727,7 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
             if (!worker)
                 return; // terminated mid-startup
             try {
-                await waitForWorkerReady(worker);
+                await waitForWorkerReady(worker, poolOptions.workerReadyTimeoutMs);
                 anyWorkerReachedReady = true;
                 return; // ready — slot stays in activeSlots
             }
@@ -709,7 +771,7 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
     const initialReadyGate = Promise.allSettled(workers.map((_, i) => bringSlotReady(i))).then(() => undefined);
     const dispatch = async (items, onProgress, chunkHash) => {
         // Await the initial-spawn readiness gate (F13). On first dispatch
-        // this blocks for up to WORKER_READY_TIMEOUT_MS while every initial
+        // this blocks for up to poolOptions.workerReadyTimeoutMs while every initial
         // worker's `{type:'ready'}` handshake is checked; on subsequent
         // dispatches the promise is already settled and resolves
         // synchronously. Slots whose initial worker crashed in top-of-
@@ -788,6 +850,18 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
             const retireWorkerAfterTimeout = (worker, workerIndex, reason) => {
                 let cleaned = false;
                 let terminateStarted = false;
+                let resolveSafePoint;
+                const safePoint = new Promise((resolve) => {
+                    resolveSafePoint = resolve;
+                });
+                // A message/messageerror proves the worker is executing JS again; an
+                // exit/error means the thread is gone. Either way `worker.terminate()`
+                // can no longer land mid-N-API call (#2432), so shutdown's drain may
+                // stop waiting.
+                function markSafeToTerminate() {
+                    record.safeToTerminate = true;
+                    resolveSafePoint();
+                }
                 function cleanupRetired() {
                     if (cleaned)
                         return;
@@ -806,6 +880,7 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
                     await worker.terminate().catch(() => undefined);
                 }
                 function terminateWhenBackInJs() {
+                    markSafeToTerminate();
                     void terminateRetired();
                 }
                 function onRetiredMessage(raw) {
@@ -816,8 +891,14 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
                         terminateWhenBackInJs();
                     }
                 }
-                const onRetiredError = () => cleanupRetired();
-                const onRetiredExit = () => cleanupRetired();
+                const onRetiredError = () => {
+                    markSafeToTerminate();
+                    cleanupRetired();
+                };
+                const onRetiredExit = () => {
+                    markSafeToTerminate();
+                    cleanupRetired();
+                };
                 const onRetiredMessageError = () => terminateWhenBackInJs();
                 const record = {
                     worker,
@@ -825,6 +906,8 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
                     reason,
                     cleanup: cleanupRetired,
                     terminate: terminateRetired,
+                    safeToTerminate: false,
+                    safePoint,
                 };
                 retiredWorkers.add(record);
                 worker.on('message', onRetiredMessage);
@@ -851,7 +934,7 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
                     return false;
                 const replacement = spawnAndCapture(workerUrl);
                 try {
-                    await waitForWorkerReady(replacement);
+                    await waitForWorkerReady(replacement, poolOptions.workerReadyTimeoutMs);
                 }
                 catch (err) {
                     await replacement.terminate().catch(() => undefined);
@@ -890,8 +973,25 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
                 const liveWorkers = workers.slice();
                 for (let i = 0; i < workers.length; i++)
                     workers[i] = undefined;
+                // #2432: a live worker with a job in flight may be inside an N-API
+                // call — direct terminate risks the same native abort as the retired
+                // case. Route busy workers through the retire path (terminate at
+                // their next JS-visible safe point); idle workers are parked in the
+                // JS event loop and terminate safely right away.
+                const idleWorkers = [];
+                for (let i = 0; i < liveWorkers.length; i++) {
+                    const worker = liveWorkers[i];
+                    if (worker === undefined)
+                        continue;
+                    if (busySlots.has(i)) {
+                        retireWorkerAfterTimeout(worker, i, 'circuit breaker tripped with job in flight');
+                    }
+                    else {
+                        idleWorkers.push(worker);
+                    }
+                }
                 activeSlots.clear();
-                void terminateTrackedWorkers(liveWorkers);
+                void terminateTrackedWorkers(idleWorkers);
             };
             const maybeDone = () => {
                 if (stopped)

package/dist/core/lbug/csv-generator.d.ts

@@ -14,6 +14,7 @@
 import type { GraphNode, GraphRelationship } from '../../_shared/index.js';
 import { KnowledgeGraph } from '../graph/types.js';
 import { NodeTableName } from './schema.js';
+import { type LayoutTableName } from './node-table-layout.js';
 /**
  * Flush buffered rows to disk once the buffered chunk reaches this many bytes.
  * Byte-bounded rather than row-count-bounded: row size ranges from a few dozen
@@ -49,6 +50,14 @@ export declare const shouldFlushCSVBuffer: (byteCount: number) => boolean;
 export declare const sanitizeUTF8: (str: string) => string;
 export declare const escapeCSVField: (value: string | number | undefined | null) => string;
 export declare const escapeCSVNumber: (value: number | undefined | null, defaultValue?: number) => string;
+/**
+ * LadybugDB STRING[] literal inside a quoted CSV field. Elements containing a
+ * list metacharacter (' , [ ]) are single-quoted so comma-bearing types like
+ * `Table<address, u64>` survive as one element. LadybugDB keeps the quotes on
+ * read, so user-facing columns must strip them (see moveResources fieldList).
+ */
+export declare const escapeCSVStringArray: (value: unknown) => string;
+export declare const escapeCSVBoolean: (value: unknown) => string;
 export declare const isBinaryContent: (content: string) => boolean;
 /**
  * Flatten newlines and tabs to single spaces for FTS-indexed text columns
@@ -77,6 +86,12 @@ export declare const isBinaryContent: (content: string) => boolean;
  * otherwise fail to match whitespace-normalized indexed content.
  */
 export declare const normalizeFtsText: (text: string) => string;
+/**
+ * Encode a row from the same ordered layout that owns its DDL, CSV header,
+ * and COPY column list. These tables are shared across languages, so missing
+ * optional properties deliberately serialize to typed defaults.
+ */
+export declare const buildLayoutNodeRow: (table: LayoutTableName, node: GraphNode, content: string) => string;
 /** Canonical relationship CSV header — shared by the emit pass and the
  * `splitRelCsvByLabelPair` differential oracle. */
 export declare const REL_CSV_HEADER = "from,to,type,confidence,reason,step";