nexus-prime 7.2.0 → 7.3.1

package/dist/architects/config.js

@@ -7,9 +7,14 @@ function parseInteger(value, fallback) {
     const parsed = Number.parseInt(value ?? '', 10);
     return Number.isFinite(parsed) ? parsed : fallback;
 }
+function clampInteger(value, min, max) {
+    if (!Number.isFinite(value))
+        return min;
+    return Math.max(min, Math.min(max, Math.floor(value)));
+}
 export const ArchitectsConfig = {
     enabled: parseBoolean(process.env.ARCHITECTS_ENABLED, true),
-    maxConcurrent: parseInteger(process.env.ARCHITECTS_MAX_CONCURRENT, -1),
+    maxConcurrent: clampInteger(parseInteger(process.env.ARCHITECTS_MAX_CONCURRENT, 2), 1, 4),
     sentinelPatrolMs: parseInteger(process.env.ARCHITECTS_SENTINEL_PATROL_MS, 120_000),
     wardPatrolMs: parseInteger(process.env.ARCHITECTS_WARD_PATROL_MS, 180_000),
     convergenceStrategy: (process.env.ARCHITECTS_CONVERGENCE_STRATEGY || 'bisecting'),

package/dist/cli/doctor-storage.d.ts

@@ -1,4 +1,15 @@
 import type { StateScope } from '../install/state-locator.js';
+import type { LicenseStatus } from '../licensing/types.js';
+export interface NgramFootprint {
+    dbPath: string;
+    dbBytes: number;
+    walBytes: number;
+    shmBytes: number;
+    totalBytes: number;
+    walLimitBytes: number;
+    footprintLimitBytes: number;
+    archives: number;
+}
 export interface DoctorReport {
     stateDir: string;
     totals: Record<StateScope, number>;
@@ -15,5 +26,13 @@ export interface DoctorReport {
         limit: number;
     }>;
     suggestCleanup: boolean;
+    /** Install manifest's recorded architecture generation, if present. */
+    installArchGeneration?: string;
+    /** Architecture generation built into this binary. */
+    currentArchGeneration: string;
+    /** ngram-index footprint snapshot for the canonical state-dir DB. */
+    ngram: NgramFootprint;
+    /** Active license status. */
+    license: Pick<LicenseStatus, 'tier' | 'valid' | 'expiresAt' | 'trial' | 'degradedReason'>;
 }
 export declare function runDoctorStorage(): DoctorReport;

package/dist/cli/doctor-storage.js

@@ -2,13 +2,29 @@
  * nexus doctor storage — read-only disk usage report.
  *
  * Shows scope-by-scope bytes under the state dir + tmp prefixes, flags any
- * scope that exceeds the corresponding cleanup budget, and prints a single
- * remediation hint (`nexus cleanup --fix`) when needed.
+ * scope that exceeds the corresponding cleanup budget, surfaces the install
+ * architecture generation + ngram WAL footprint + license status, and prints
+ * a single remediation hint (`nexus cleanup --fix`) when needed.
  */
 import * as fs from 'fs';
+import * as path from 'path';
 import { resolveRunsBudget, resolveWorktreeBudget } from './cleanup.js';
 import { dirBytes, formatBytes } from '../install/fs-purge.js';
-import { enumerateStatePaths, getNexusStateDir, getRuntimeTmpRoots, getWorktreeRoots, } from '../install/state-locator.js';
+import { enumerateNgramArchives, enumerateStatePaths, getNexusStateDir, getRuntimeTmpRoots, getWorktreeRoots, } from '../install/state-locator.js';
+import { INSTALL_ARCH_GENERATION, loadManifest, } from '../install/manifest.js';
+import { getNgramFootprintBytes } from '../engines/ngram-index.js';
+import { getSharedLicenseManager } from '../licensing/license-manager.js';
+const NGRAM_DEFAULT_WAL_LIMIT_BYTES = 64 * 1024 * 1024;
+const NGRAM_DEFAULT_FOOTPRINT_BYTES = 512 * 1024 * 1024;
+function readEnvBytesPositive(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return fallback;
+    return Math.floor(parsed);
+}
 export function runDoctorStorage() {
     const stateDir = getNexusStateDir();
     const entries = [];
@@ -47,14 +63,67 @@ export function runDoctorStorage() {
     if (totals.runtime > runsBudget.maxBytes) {
         flags.push({ scope: 'runtime', reason: 'bytes-over-limit', actual: totals.runtime, limit: runsBudget.maxBytes });
     }
+    const ngramDbPath = path.join(stateDir, 'ngram-index.db');
+    const walLimitBytes = readEnvBytesPositive('NEXUS_NGRAM_WAL_LIMIT_BYTES', NGRAM_DEFAULT_WAL_LIMIT_BYTES);
+    const footprintLimitBytes = readEnvBytesPositive('NEXUS_NGRAM_MAX_FOOTPRINT_BYTES', NGRAM_DEFAULT_FOOTPRINT_BYTES);
+    const safeStat = (p) => {
+        try {
+            return fs.existsSync(p) ? fs.statSync(p).size : 0;
+        }
+        catch {
+            return 0;
+        }
+    };
+    const ngram = {
+        dbPath: ngramDbPath,
+        dbBytes: safeStat(ngramDbPath),
+        walBytes: safeStat(`${ngramDbPath}-wal`),
+        shmBytes: safeStat(`${ngramDbPath}-shm`),
+        totalBytes: getNgramFootprintBytes(ngramDbPath),
+        walLimitBytes,
+        footprintLimitBytes,
+        archives: enumerateNgramArchives(stateDir).length,
+    };
+    if (ngram.walBytes > walLimitBytes) {
+        flags.push({ scope: 'db', reason: 'ngram-wal-over-limit', actual: ngram.walBytes, limit: walLimitBytes });
+    }
+    if (ngram.totalBytes > footprintLimitBytes) {
+        flags.push({ scope: 'db', reason: 'ngram-footprint-over-limit', actual: ngram.totalBytes, limit: footprintLimitBytes });
+    }
+    const manifest = loadManifest();
+    const license = (() => {
+        try {
+            const status = getSharedLicenseManager().getStatus();
+            return {
+                tier: status.tier,
+                valid: status.valid,
+                expiresAt: status.expiresAt,
+                trial: status.trial,
+                degradedReason: status.degradedReason,
+            };
+        }
+        catch {
+            return { tier: 'free', valid: false, expiresAt: null, trial: false, degradedReason: 'malformed' };
+        }
+    })();
     const report = {
         stateDir,
         totals,
         entries,
         flags,
         suggestCleanup: flags.length > 0,
+        installArchGeneration: manifest.architectureGeneration,
+        currentArchGeneration: INSTALL_ARCH_GENERATION,
+        ngram,
+        license,
     };
     console.log(`\n[doctor:storage] state dir: ${stateDir}`);
+    console.log(`  install arch  ${report.installArchGeneration ?? '(unstamped)'} → current ${report.currentArchGeneration}`);
+    const trialNote = license.trial && license.expiresAt
+        ? ` (trial, ${Math.max(0, Math.ceil((license.expiresAt - Date.now()) / (24 * 60 * 60 * 1000)))}d left)`
+        : '';
+    console.log(`  license       tier=${license.tier} valid=${license.valid}${trialNote}${license.degradedReason ? ` reason=${license.degradedReason}` : ''}`);
+    console.log(`  ngram db      db=${formatBytes(ngram.dbBytes)} wal=${formatBytes(ngram.walBytes)} shm=${formatBytes(ngram.shmBytes)} total=${formatBytes(ngram.totalBytes)} (cap=${formatBytes(footprintLimitBytes)})  archives=${ngram.archives}`);
     for (const [scope, bytes] of Object.entries(totals)) {
         console.log(`  ${scope.padEnd(10)} ${formatBytes(bytes)}`);
     }

package/dist/cli/install-wizard.d.ts

@@ -4,6 +4,7 @@
  * Invoked via: nexus-prime setup
  */
 import { type IDEId } from '../agents/adapters/ide-compat.js';
+import { INSTALL_ARCH_GENERATION } from '../install/manifest.js';
 export interface WizardOptions {
     /** Target workspace root (defaults to cwd) */
     workspaceRoot?: string;
@@ -36,6 +37,20 @@ export declare function configureIDE(ide: IDEId, opts?: WizardOptions): Promise<
     configPath: string | null;
     writtenHash: string | null;
 }>;
+/** Architecture-generation migration step. Idempotent and best-effort: when
+ *  the install manifest predates INSTALL_ARCH_GENERATION (or carries an older
+ *  one), we drop stale generated artefacts that the current generation no
+ *  longer owns. The manifest's path/registration entries are preserved so
+ *  uninstall can still reverse them. */
+export interface ArchUpgradeResult {
+    previousGeneration?: string;
+    currentGeneration: typeof INSTALL_ARCH_GENERATION;
+    migrated: boolean;
+    ngramArchivesPruned: number;
+}
+export declare function runArchitectureUpgrade(opts?: {
+    dryRun?: boolean;
+}): ArchUpgradeResult;
 /** Run the install wizard: detect IDEs and write MCP configs. */
 export declare function runInstallWizard(opts?: WizardOptions): Promise<WizardResult>;
 /** Print how to add nexus-prime manually to an MCP client. */

package/dist/cli/install-wizard.js

@@ -4,7 +4,7 @@
  * Invoked via: nexus-prime setup
  */
 import { createHash } from 'crypto';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 import { dirname, join, resolve } from 'path';
@@ -15,7 +15,9 @@ import { resolveNexusStateDir } from '../engines/runtime-registry.js';
 import { resolveWorkspaceContext } from '../engines/workspace-resolver.js';
 import { runPostinstallCleanup } from '../postinstall/cleanup.js';
 import { openBrowser, printHandoffBanner, withSpinner } from './interactive-setup.js';
-import { appendToManifest, recordPath, recordRegistration, recordSetupMarker } from '../install/manifest.js';
+import { appendToManifest, detectArchitectureUpgrade, loadManifest, recordArchitectureGeneration, recordPath, recordRegistration, recordSetupMarker, INSTALL_ARCH_GENERATION, } from '../install/manifest.js';
+import { enumerateNgramArchives } from '../install/state-locator.js';
+import { NEXUS_HOOK_COMMAND_MARKER, writeNexusClaudeCodeHooks } from '../install/claude-code-hooks.js';
 /** Compute sha256 of a file's content. Returns null if the file cannot be read. */
 export function computeFileHash(filePath) {
     try {
@@ -147,35 +149,8 @@ function _nexusMcpEntry(workspaceRoot) {
  */
 function _writeClaudeCodeHooks(workspaceRoot) {
     const settingsPath = join(workspaceRoot, '.claude', 'settings.json');
-    let existing = {};
-    if (existsSync(settingsPath)) {
-        try {
-            existing = JSON.parse(readFileSync(settingsPath, 'utf8'));
-        }
-        catch { /* start fresh if unreadable */ }
-    }
-    const NEXUS_CMD_MARKER = 'nexus-prime hook';
-    const nexusHooks = {
-        UserPromptSubmit: [{ matcher: '', hooks: [{ type: 'command', command: 'nexus-prime hook bootstrap' }] }],
-        PreToolUse: [{ matcher: 'Edit|Write|MultiEdit', hooks: [{ type: 'command', command: 'nexus-prime hook mindkit' }] }],
-        PostToolUse: [{ matcher: 'Edit|Write|MultiEdit|Bash', hooks: [{ type: 'command', command: 'nexus-prime hook memory' }] }],
-        Stop: [{ matcher: '', hooks: [{ type: 'command', command: 'nexus-prime hook session-dna' }] }],
-    };
-    const existingHooks = (existing.hooks && typeof existing.hooks === 'object' && !Array.isArray(existing.hooks))
-        ? existing.hooks
-        : {};
-    for (const [event, entries] of Object.entries(nexusHooks)) {
-        const current = Array.isArray(existingHooks[event]) ? existingHooks[event] : [];
-        // Strip stale nexus-prime hook entries then append fresh ones
-        const filtered = current.filter((e) => typeof e === 'object' && e !== null &&
-            !(Array.isArray(e.hooks) &&
-                e.hooks.some((h) => typeof h === 'object' && h !== null && typeof h.command === 'string' &&
-                    h.command.includes(NEXUS_CMD_MARKER))));
-        existingHooks[event] = [...filtered, ...entries];
-    }
-    existing.hooks = existingHooks;
-    mkdirSync(dirname(settingsPath), { recursive: true });
-    writeFileSync(settingsPath, JSON.stringify(existing, null, 2), 'utf8');
+    // Single source of truth: hook spec + dedup logic live in install/claude-code-hooks.ts.
+    writeNexusClaudeCodeHooks(settingsPath);
     const isHome = workspaceRoot === homedir();
     appendToManifest((m) => {
         const withPath = recordPath(m, { path: settingsPath, kind: 'file', scope: 'state' });
@@ -183,7 +158,7 @@ function _writeClaudeCodeHooks(workspaceRoot) {
             target: isHome ? 'claude-home' : 'claude-workspace',
             filePath: settingsPath,
             jsonPath: ['hooks'],
-            entryMarker: NEXUS_CMD_MARKER,
+            entryMarker: NEXUS_HOOK_COMMAND_MARKER,
         });
     });
 }
@@ -255,6 +230,45 @@ function _writeWorkspaceLocalConfigs(callerIde, workspaceRoot) {
         }
     }
 }
+export function runArchitectureUpgrade(opts = {}) {
+    const manifest = loadManifest();
+    const detection = detectArchitectureUpgrade(manifest);
+    if (!detection.requiresMigration) {
+        if (manifest.architectureGeneration !== INSTALL_ARCH_GENERATION && !opts.dryRun) {
+            // Fresh install or no recorded entries — just stamp the marker.
+            appendToManifest((m) => recordArchitectureGeneration(m));
+        }
+        return {
+            previousGeneration: detection.previousGeneration,
+            currentGeneration: detection.currentGeneration,
+            migrated: false,
+            ngramArchivesPruned: 0,
+        };
+    }
+    let ngramArchivesPruned = 0;
+    if (!opts.dryRun) {
+        // Stale ngram archives from prior generations: keep nothing — the new
+        // rotation path archives at most one and uses footprint accounting.
+        try {
+            const archives = enumerateNgramArchives();
+            for (const archive of archives) {
+                try {
+                    rmSync(archive.path, { force: true });
+                    ngramArchivesPruned += 1;
+                }
+                catch { /* best-effort */ }
+            }
+        }
+        catch { /* best-effort */ }
+        appendToManifest((m) => recordArchitectureGeneration(m));
+    }
+    return {
+        previousGeneration: detection.previousGeneration,
+        currentGeneration: detection.currentGeneration,
+        migrated: true,
+        ngramArchivesPruned,
+    };
+}
 /** Run the install wizard: detect IDEs and write MCP configs. */
 export async function runInstallWizard(opts = {}) {
     const workspaceRoot = resolve(opts.workspaceRoot ?? process.cwd());
@@ -263,6 +277,10 @@ export async function runInstallWizard(opts = {}) {
     const setupMarker = readSetupMarker();
     const log = (msg) => { if (verbose)
         process.stdout.write(msg + '\n'); };
+    const upgrade = runArchitectureUpgrade({ dryRun });
+    if (upgrade.migrated && verbose) {
+        log(`  [arch] migrated install ${upgrade.previousGeneration ?? 'legacy'} → ${upgrade.currentGeneration} (ngram archives pruned: ${upgrade.ngramArchivesPruned})`);
+    }
     const detected = detectInstalledIDEs(workspaceRoot);
     if (detected.length === 0) {
         log('  No supported IDEs detected in this workspace. Skipping MCP config setup.');

package/dist/cli.js

@@ -38,67 +38,24 @@ import { runUninstall } from './cli/uninstall.js';
 import { runCleanup } from './cli/cleanup.js';
 import { runDoctorStorage } from './cli/doctor-storage.js';
 const tokenEngine = new TokenSupremacyEngine();
+import { getNexusHookSpec, writeNexusClaudeCodeHooks, } from './install/claude-code-hooks.js';
 /**
  * Write (or merge) nexus-prime Claude Code hook entries into ~/.claude/settings.json.
- * Idempotent: removes any pre-existing `nexus-prime hook *` entries before adding fresh ones.
+ * Idempotent — delegates to the shared writer in install/claude-code-hooks.ts
+ * so cli.ts and install-wizard.ts cannot drift on the hook spec or dedup logic.
  */
 function writeClaudeCodeHooks(settingsPath, dryRun) {
-    let settings = {};
-    if (existsSync(settingsPath)) {
-        try {
-            settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
-        }
-        catch {
-            settings = {};
-        }
-    }
-    const hooks = (settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks))
-        ? { ...settings.hooks }
-        : {};
-    const nexusHooks = {
-        UserPromptSubmit: [
-            { hooks: [{ type: 'command', command: 'nexus-prime hook bootstrap', timeout: 30 }] },
-        ],
-        PreToolUse: [
-            {
-                matcher: 'Edit|Write|MultiEdit',
-                hooks: [{ type: 'command', command: 'nexus-prime hook mindkit', timeout: 10 }],
-            },
-        ],
-        PostToolUse: [
-            {
-                matcher: 'Edit|Write|MultiEdit|Bash',
-                hooks: [{ type: 'command', command: 'nexus-prime hook memory', timeout: 10 }],
-            },
-        ],
-        Stop: [
-            { hooks: [{ type: 'command', command: 'nexus-prime hook session-dna', timeout: 60 }] },
-        ],
-    };
-    for (const [event, entries] of Object.entries(nexusHooks)) {
-        const existing = Array.isArray(hooks[event]) ? hooks[event] : [];
-        // Remove stale nexus-prime hook entries before re-adding
-        const filtered = existing.filter((entry) => {
-            if (!entry || typeof entry !== 'object')
-                return true;
-            const hooksList = entry.hooks;
-            if (!Array.isArray(hooksList))
-                return true;
-            return !hooksList.some((h) => h && typeof h.command === 'string' &&
-                h.command.startsWith('nexus-prime hook'));
-        });
-        hooks[event] = [...filtered, ...entries];
-    }
-    settings.hooks = hooks;
+    const result = writeNexusClaudeCodeHooks(settingsPath, { dryRun });
     if (dryRun) {
         console.log('Hooks preview (would write to ~/.claude/settings.json):');
-        console.log(JSON.stringify(nexusHooks, null, 2));
+        console.log(JSON.stringify(getNexusHookSpec(), null, 2));
         return;
     }
-    mkdirSync(dirname(settingsPath), { recursive: true });
-    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
-    console.log(`   Hooks: ${settingsPath}`);
-    Object.keys(nexusHooks).forEach(ev => console.log(`     ${ev} → nexus-prime hook ${ev.toLowerCase().replace('tooluse', '').trim() || ev}`));
+    console.log(`   Hooks: ${settingsPath}${result.changed ? '' : ' (no change)'}`);
+    result.events.forEach((ev) => {
+        const tail = ev.toLowerCase().replace('tooluse', '').trim() || ev;
+        console.log(`     ${ev} → nexus-prime hook ${tail}`);
+    });
 }
 const program = new Command();
 let nexus = null;

package/dist/dashboard/routes/health.js

@@ -1,5 +1,25 @@
+import { DASHBOARD_API_VERSION } from '../contract.js';
+import { INSTALL_ARCH_GENERATION, loadManifest } from '../../install/manifest.js';
 import { getToolHealthSummary } from '../../agents/adapters/mcp/tool-health.js';
 export const handleHealthRoutes = async (ctx, req, res, url) => {
+    if (req.method === 'GET'
+        && (url.pathname === '/api/version' || url.pathname === '/api/dashboard/version')) {
+        // Stable version endpoint so external probes (CI smoke, foreign installs
+        // sharing port 3377) can identify the running dashboard generation.
+        const manifest = (() => { try {
+            return loadManifest();
+        }
+        catch {
+            return null;
+        } })();
+        ctx.respondJson(res, {
+            dashboardApiVersion: DASHBOARD_API_VERSION,
+            architectureGeneration: INSTALL_ARCH_GENERATION,
+            installArchGeneration: manifest?.architectureGeneration ?? null,
+            product: 'nexus-prime',
+        });
+        return true;
+    }
     if (req.method === 'GET' && url.pathname === '/api/license') {
         const { getSharedLicenseManager } = await import('../../licensing/index.js');
         ctx.respondJson(res, getSharedLicenseManager().getStatus());

package/dist/dashboard/server.js

@@ -21,6 +21,7 @@ import { handleAuthoringRoutes } from './routes/authoring.js';
 import { handleArchitectsRoutes } from './routes/architects.js';
 import { handleWorkforceRoutes } from './routes/workforce.js';
 import { handleGraphRoutes } from './routes/graph.js';
+import { DASHBOARD_API_VERSION } from './contract.js';
 import { SseBroker } from './stream/sse-broker.js';
 import { nexusEventBus } from '../engines/event-bus.js';
 const __filename = fileURLToPath(import.meta.url);
@@ -30,7 +31,6 @@ const DEFAULT_PORT = parseInt(process.env.NEXUS_DASHBOARD_PORT || '3377', 10);
 const MAX_PORT_SCAN = 24;
 const DASHBOARD_PROBE_TIMEOUT_MS = 3000;
 const DASHBOARD_PROBE_ATTEMPTS = 2;
-const DASHBOARD_API_VERSION = '4';
 const DASHBOARD_SCHEMA_VERSION = 1;
 const DASHBOARD_PRETTY_JSON = process.env.NEXUS_DASHBOARD_PRETTY_JSON === '1';
 const CORE_CAPABILITIES = {

package/dist/engines/ngram-index.d.ts

@@ -11,6 +11,9 @@
  *
  * Persistence: SQLite (same pattern as memory.db / graph.db)
  */
+export declare function getNgramWalPath(dbPath: string): string;
+export declare function getNgramShmPath(dbPath: string): string;
+export declare function getNgramFootprintBytes(dbPath: string): number;
 export interface Posting {
     docId: string;
     locMask: number;
@@ -54,6 +57,9 @@ export declare class NgramIndex {
     private deleteStmt;
     private lookupStmt;
     private docExistsStmt;
+    private writesSinceCheckpoint;
+    private lastCheckpointAt;
+    private quotaSkipNoticeShown;
     private _searchStats;
     constructor(dbPath?: string, options?: NgramIndexOptions);
     private rotateOversizeDbIfNeeded;
@@ -64,14 +70,35 @@ export declare class NgramIndex {
     private warmHashSet;
     /** Warm the hash set after a deferred init. No-op if already warm. */
     warmHashSetDeferred(): void;
+    /** Run an opportunistic WAL checkpoint. PASSIVE first, escalate to TRUNCATE
+     *  if the WAL is still over its configured limit. Returns the WAL byte size
+     *  observed after the attempt so callers can report progress. */
+    private checkpointIfNeeded;
+    /** Footprint quota check before a write. Returns true if the write should
+     *  proceed; false if it should be skipped. Throws when NEXUS_NGRAM_STRICT_QUOTA=1
+     *  so callers can surface hard quota failures during tests/CI. */
+    private allowWrite;
     /** Index a document's text content */
     addDocument(docId: string, text: string): void;
+    /** Trigger a passive checkpoint when either the doc or time interval threshold
+     *  is hit. Cheap on a healthy DB, prevents WAL growth on bulk indexing. */
+    private maybePeriodicCheckpoint;
     /** Remove a document from the index */
     removeDocument(docId: string): void;
     /** Check if a document is already indexed */
     isIndexed(docId: string): boolean;
     /** Get count of indexed documents */
     getDocCount(): number;
+    /** Path to the underlying SQLite database file. */
+    getDbPath(): string;
+    /** Bytes occupied by the .db file alone. */
+    getDbBytes(): number;
+    /** Bytes occupied by the .db-wal file. */
+    getWalBytes(): number;
+    /** Bytes occupied by the .db-shm file. */
+    getShmBytes(): number;
+    /** Total SQLite footprint = db + wal + shm. Use this for quota checks. */
+    getSqliteFootprintBytes(): number;
     /**
      * Search for documents matching a text query.
      * Returns candidate document IDs ranked by trigram match count.
@@ -120,8 +147,9 @@ export declare class NgramIndex {
     optimizeStorage(force?: boolean): void;
     /**
      * Operator-focused maintenance for the on-disk ngram DB.
-     * - Bounds runaway DB growth via rotation (default >= 1GB)
-     * - Vacuums only when safe (<= vacuumMaxBytes) and either forced or dirty
+     * - Bounds runaway DB growth via rotation (default >= 1GB), counting the
+     *   full SQLite footprint (db + wal + shm) so a runaway WAL triggers it.
+     * - Vacuums only when safe (<= vacuumMaxBytes) and either forced or dirty.
      */
     maintainBounded(options?: {
         force?: boolean;
@@ -132,7 +160,13 @@ export declare class NgramIndex {
         uniqueTrigramCount: number;
         dbSizeBytes: number;
     };
-    /** Close the database connection */
+    /** Close the database connection.
+     *
+     *  Always truncates the WAL so the .db-wal sibling can never outgrow the
+     *  configured cap on shutdown — the failure mode that produced the 84GB
+     *  WAL on a user machine. VACUUM is only run when the operator has both a
+     *  small DB and explicitly opts in via NEXUS_NGRAM_VACUUM_ON_CLOSE=1, since
+     *  blind VACUUM on multi-GB DBs blocks shutdown indefinitely. */
     close(): void;
 }
 /** Get or create the shared NgramIndex instance */