hoi4-agent-tools 3.0.8 → 3.1.0

package/dist/hoi4_agent_tools/core/dependency-walk.js

@@ -0,0 +1,266 @@
+import { z } from 'zod/v4';
+import { hashCanonical } from './canonical.js';
+import { currentAnalysisCheckpoints } from './analysis-checkpoints.js';
+import { ServiceError } from './result.js';
+const ordinal = z.number().int().nonnegative();
+const pathSchema = z.object({ edge: ordinal, parent: ordinal.nullable() }).strict();
+const recordSchema = z
+    .object({
+    kind: z.enum(['visit', 'terminal', 'cycle', 'depth']),
+    root: ordinal,
+    path: ordinal,
+})
+    .strict();
+const stateSchema = z
+    .object({
+    version: z.literal(1),
+    key: z.string(),
+    root: ordinal,
+    steps: ordinal,
+    paths: z.array(pathSchema),
+    records: z.array(recordSchema),
+    stack: z.array(ordinal),
+    visited: z.array(z.string()),
+    current: z.object({ path: ordinal, edge: ordinal }).strict().nullable(),
+    started: z.boolean(),
+    complete: z.boolean(),
+})
+    .strict();
+/** A bounded, serializable DFS frontier; paths share prefixes instead of copying source data. */
+export class DependencyWalk {
+    input;
+    state;
+    key;
+    edges;
+    outgoing = new Map();
+    branches;
+    visited;
+    constructor(input, restored) {
+        this.input = input;
+        this.key = hashCanonical({ algorithm: 'dependency-walk.v1', ...input });
+        this.edges = new Map(input.edges.map(({ id }, index) => [id, index]));
+        if (this.edges.size !== input.edges.length || input.roots.some((id) => !this.edges.has(id)))
+            throw new ServiceError('DEPENDENCY_WALK_INPUT_INVALID', 'Dependency edge identities must be unique and roots must exist');
+        if (!Number.isSafeInteger(input.maximumDepth) ||
+            input.maximumDepth < 1 ||
+            !Number.isSafeInteger(input.maximumSteps) ||
+            input.maximumSteps < 1)
+            throw new ServiceError('DEPENDENCY_WALK_INPUT_INVALID', 'Dependency traversal requires finite positive bounds');
+        this.branches = new Set(input.branches);
+        for (const [index, edge] of input.edges.entries()) {
+            const values = this.outgoing.get(edge.from) ?? [];
+            values.push(index);
+            this.outgoing.set(edge.from, values);
+        }
+        if (input.reverseEdges)
+            for (const values of this.outgoing.values())
+                values.reverse();
+        const decoded = restored === undefined ? undefined : stateSchema.safeParse(restored);
+        if (decoded !== undefined && !decoded.success)
+            throw new ServiceError('DEPENDENCY_CHECKPOINT_INVALID', 'Dependency checkpoint has an invalid state schema');
+        this.state = decoded?.data ?? {
+            version: 1,
+            key: this.key,
+            root: 0,
+            steps: 0,
+            paths: [],
+            records: [],
+            stack: [],
+            visited: [],
+            current: null,
+            started: false,
+            complete: input.roots.length === 0,
+        };
+        if (this.state.key !== this.key ||
+            this.state.root > input.roots.length ||
+            this.state.steps > input.maximumSteps)
+            throw new ServiceError('DEPENDENCY_CHECKPOINT_STALE', 'Dependency checkpoint does not match this exact source graph and traversal contract');
+        this.validateState();
+        this.visited = new Set(this.state.visited);
+    }
+    validateState() {
+        const invalid = (message) => {
+            throw new ServiceError('DEPENDENCY_CHECKPOINT_INVALID', message);
+        };
+        if (this.state.complete !== (this.state.root === this.input.roots.length) ||
+            (!this.state.started && (this.state.current !== null || this.state.stack.length !== 0)) ||
+            (this.state.complete && this.state.started) ||
+            this.state.paths.length > this.state.steps ||
+            this.state.records.length > this.state.steps ||
+            new Set(this.state.stack).size !== this.state.stack.length ||
+            new Set(this.state.visited).size !== this.state.visited.length)
+            invalid('Dependency checkpoint has inconsistent lifecycle or retained work');
+        const roots = [];
+        const rootEdges = new Set(this.input.roots.map((id) => this.edges.get(id)));
+        for (const [index, path] of this.state.paths.entries()) {
+            if (path.edge >= this.input.edges.length || (path.parent !== null && path.parent >= index))
+                throw new ServiceError('DEPENDENCY_CHECKPOINT_INVALID', 'Dependency checkpoint contains an invalid path');
+            if (path.parent === null) {
+                if (!rootEdges.has(path.edge))
+                    invalid('Dependency path starts outside the requested roots');
+                roots.push(path.edge);
+            }
+            else {
+                const previous = this.input.edges[this.state.paths[path.parent].edge];
+                if (previous.to !== this.input.edges[path.edge].from)
+                    invalid('Dependency checkpoint path is disconnected from its parent edge');
+                roots.push(roots[path.parent]);
+            }
+        }
+        for (const index of [
+            ...this.state.stack,
+            ...(this.state.current === null ? [] : [this.state.current.path]),
+        ])
+            if (index >= this.state.paths.length ||
+                this.input.edges[roots[index]].id !== this.input.roots[this.state.root])
+                throw new ServiceError('DEPENDENCY_CHECKPOINT_INVALID', 'Dependency frontier points outside its retained paths');
+        if (this.state.current !== null) {
+            const { path, edge } = this.state.current;
+            const node = this.input.edges[this.state.paths[path].edge].to;
+            if (edge > (this.outgoing.get(node)?.length ?? 0) || this.state.stack.includes(path))
+                invalid('Dependency adjacency cursor is outside its current node or duplicates the frontier');
+        }
+        for (const record of this.state.records)
+            if (record.root >= this.input.roots.length ||
+                record.path >= this.state.paths.length ||
+                this.input.edges[roots[record.path]].id !== this.input.roots[record.root])
+                throw new ServiceError('DEPENDENCY_CHECKPOINT_INVALID', 'Dependency evidence points outside its retained graph');
+    }
+    path(index) {
+        if (!Number.isSafeInteger(index) || index < 0 || index >= this.state.paths.length)
+            throw new ServiceError('DEPENDENCY_PATH_INVALID', 'Dependency path ordinal is outside the retained frontier');
+        const values = [];
+        let cursor = index;
+        while (cursor !== null) {
+            const path = this.state.paths[cursor];
+            values.push(this.input.edges[path.edge]);
+            cursor = path.parent;
+        }
+        return values.reverse();
+    }
+    addPath(edge, parent) {
+        this.state.paths.push({ edge, parent });
+        return this.state.paths.length - 1;
+    }
+    record(kind, path) {
+        this.state.records.push({ kind, path, root: this.state.root });
+    }
+    /** Advance at most this many elementary transitions, including wide adjacency lists. */
+    advance(maximumSteps, signal) {
+        if (!Number.isSafeInteger(maximumSteps) || maximumSteps < 1)
+            throw new ServiceError('DEPENDENCY_BATCH_INVALID', 'Dependency batch size must be positive');
+        const end = this.state.steps + maximumSteps;
+        while (!this.state.complete && this.state.steps < end) {
+            signal?.throwIfAborted();
+            if (this.state.steps >= this.input.maximumSteps)
+                throw new ServiceError('DEPENDENCY_WORK_LIMIT', 'Dependency expansion reached its explicit work ceiling', {
+                    maximum: this.input.maximumSteps,
+                    completedRoots: this.state.root,
+                    totalRoots: this.input.roots.length,
+                });
+            this.state.steps++;
+            if (!this.state.started) {
+                const edge = this.edges.get(this.input.roots[this.state.root]);
+                const rootPath = this.addPath(edge, null);
+                this.state.stack.push(rootPath);
+                this.visited.clear();
+                if (this.input.visitPolicy === 'node')
+                    this.visited.add(this.input.edges[edge].to);
+                this.state.started = true;
+                continue;
+            }
+            if (this.state.current === null) {
+                const path = this.state.stack.pop();
+                if (path === undefined) {
+                    this.state.root++;
+                    this.state.started = false;
+                    this.state.complete = this.state.root === this.input.roots.length;
+                    continue;
+                }
+                if (this.input.visitPolicy === 'path') {
+                    const key = this.path(path)
+                        .map(({ to }) => to)
+                        .join('\0');
+                    if (this.visited.has(key))
+                        continue;
+                    this.visited.add(key);
+                }
+                this.record('visit', path);
+                this.state.current = { path, edge: 0 };
+                continue;
+            }
+            const current = this.state.current;
+            const node = this.input.edges[this.state.paths[current.path].edge].to;
+            const candidates = this.outgoing.get(node) ?? [];
+            const edgeIndex = candidates[current.edge++];
+            if (edgeIndex === undefined) {
+                this.state.current = null;
+                continue;
+            }
+            const edge = this.input.edges[edgeIndex];
+            if (!this.branches.has(edge.to)) {
+                this.record('terminal', this.addPath(edgeIndex, current.path));
+                continue;
+            }
+            const ancestors = this.path(current.path).map(({ to }) => to);
+            if (ancestors.includes(edge.to)) {
+                this.record('cycle', this.addPath(edgeIndex, current.path));
+                continue;
+            }
+            if (ancestors.length >= this.input.maximumDepth) {
+                this.record('depth', this.addPath(edgeIndex, current.path));
+                continue;
+            }
+            const visitKey = this.input.visitPolicy === 'node' ? edge.to : [...ancestors, edge.to].join('\0');
+            if (this.input.visitPolicy === 'node') {
+                if (this.visited.has(visitKey))
+                    continue;
+                this.visited.add(visitKey);
+            }
+            this.state.stack.push(this.addPath(edgeIndex, current.path));
+        }
+        return this.state.complete;
+    }
+    checkpoint() {
+        this.state.visited = [...this.visited];
+        return this.state;
+    }
+}
+export function walkDependencies(input, signal) {
+    const walk = new DependencyWalk(input);
+    while (!walk.state.complete)
+        walk.advance(256, signal);
+    return walk;
+}
+export async function walkDependenciesAsync(input, signal, checkpointSteps = 2_048) {
+    signal?.throwIfAborted();
+    if (!Number.isSafeInteger(checkpointSteps) || checkpointSteps < 1)
+        throw new ServiceError('DEPENDENCY_BATCH_INVALID', 'Checkpoint interval must be positive');
+    const checkpoints = currentAnalysisCheckpoints();
+    const key = hashCanonical({ algorithm: 'dependency-walk.v1', ...input });
+    const restored = await checkpoints?.load(key, input.sourceRevision, stateSchema);
+    const walk = new DependencyWalk(input, restored);
+    let savedAt = walk.state.steps;
+    while (!walk.state.complete) {
+        const complete = walk.advance(256, signal);
+        if ((complete && savedAt > 0) || walk.state.steps - savedAt >= checkpointSteps) {
+            await checkpoints?.save(key, input.sourceRevision, walk.checkpoint(), walk.state.root, input.roots.length);
+            savedAt = walk.state.steps;
+        }
+        await new Promise((resolve) => setImmediate(resolve));
+        signal?.throwIfAborted();
+    }
+    return walk;
+}
+export function runDependencyAnalysis(analysis, signal) {
+    let next = analysis.next();
+    while (!next.done)
+        next = analysis.next(walkDependencies(next.value, signal));
+    return next.value;
+}
+export async function runDependencyAnalysisAsync(analysis, signal) {
+    let next = analysis.next();
+    while (!next.done)
+        next = analysis.next(await walkDependenciesAsync(next.value, signal));
+    return next.value;
+}

package/dist/hoi4_agent_tools/core/domain-validation.js

@@ -0,0 +1,188 @@
+import { boundedSourceHashEvidence, publicArtifactLink } from './artifacts.js';
+import { canonicalJson } from './canonical.js';
+import { exactChangedFilePatterns, focusDomainScanPatterns } from './domain-scan-patterns.js';
+import { parseClausewitz } from './source/index.js';
+import { TRANSACTION_MAX_DIAGNOSTICS } from './transaction-limits.js';
+import { importContinuousFocusPalettes, importFocusTrees, layoutFocusTreeAsync, lintContinuousFocusPalette, lintFocusTree, } from '../focus/index.js';
+import { ScriptedGuiStudio } from '../gui/index.js';
+import { AgentNudger, attributeMapValidationDiagnostics } from '../map/index.js';
+import { PACKAGE_VERSION } from '../version.js';
+function sourcePathComparisonKey(value) {
+    const normalized = value.replaceAll('\\', '/');
+    return process.platform === 'win32' ? normalized.toLocaleLowerCase('en-US') : normalized;
+}
+function focusReferences(engineSnapshot) {
+    const active = (kind) => engineSnapshot.index
+        .findAll(kind)
+        .filter(({ overridden }) => !overridden)
+        .map(({ id }) => id);
+    return {
+        decision: active('decision'),
+        decision_category: active('decision_category'),
+        event: active('event'),
+        idea: active('idea'),
+        leader: active('leader'),
+        formable: active('formable'),
+        helper: active('scripted_effect'),
+    };
+}
+export async function postValidateTransaction(engine, transaction, principal, signal) {
+    engine.invalidate(transaction.workspaceId);
+    const workspace = engine.resolver.get(transaction.workspaceId, principal);
+    const focusTransaction = transaction.operationKind === 'focus-plan-changes' ||
+        transaction.operationKind === 'continuous-focus-plan-changes';
+    const snapshot = await engine.scan(transaction.workspaceId, {
+        patterns: focusTransaction
+            ? focusDomainScanPatterns(workspace)
+            : exactChangedFilePatterns(transaction.files.map(({ relativePath }) => relativePath)),
+    }, principal, signal);
+    const changed = new Set(transaction.files.map(({ relativePath }) => sourcePathComparisonKey(relativePath)));
+    const diagnostics = snapshot.diagnostics.filter(({ location }) => {
+        if (location === undefined)
+            return false;
+        const sourcePath = sourcePathComparisonKey(location.path);
+        return [...changed].some((relativePath) => sourcePath.endsWith(`:${relativePath}`));
+    });
+    const checks = [];
+    if (transaction.operationKind === 'focus-plan-changes') {
+        const catalog = focusReferences(snapshot);
+        for (const file of snapshot.files.filter(({ shadowedBy, relativePath }) => shadowedBy === undefined &&
+            relativePath.toLowerCase().endsWith('.txt') &&
+            changed.has(sourcePathComparisonKey(relativePath)))) {
+            const document = parseClausewitz(file.bytes, file.displayPath);
+            const imported = importFocusTrees(document, { references: catalog });
+            diagnostics.push(...imported.diagnostics);
+            for (const plan of imported.plans) {
+                const layout = await layoutFocusTreeAsync(plan, signal === undefined ? {} : { signal });
+                diagnostics.push(...lintFocusTree(plan, {
+                    index: snapshot.index,
+                    references: catalog,
+                    layout,
+                }));
+            }
+        }
+        const passed = !diagnostics.some(({ severity }) => severity === 'error' || severity === 'blocker');
+        checks.push({
+            id: 'post-write-focus',
+            passed,
+            message: passed
+                ? 'The focus result re-imported, laid out, and linted successfully'
+                : 'The focus result failed post-write import or lint',
+        });
+    }
+    else if (transaction.operationKind === 'continuous-focus-plan-changes') {
+        for (const file of snapshot.files.filter(({ shadowedBy, relativePath }) => shadowedBy === undefined &&
+            relativePath.toLowerCase().endsWith('.txt') &&
+            changed.has(sourcePathComparisonKey(relativePath)))) {
+            const imported = importContinuousFocusPalettes(parseClausewitz(file.bytes, file.displayPath));
+            diagnostics.push(...imported.diagnostics);
+            for (const plan of imported.continuousFocusPalettes) {
+                diagnostics.push(...lintContinuousFocusPalette(plan));
+            }
+        }
+        const passed = !diagnostics.some(({ severity }) => severity === 'error' || severity === 'blocker');
+        checks.push({
+            id: 'post-write-continuous-focus',
+            passed,
+            message: passed
+                ? 'The continuous focus result re-imported and linted successfully'
+                : 'The continuous focus result failed post-write import or lint',
+        });
+    }
+    else if (transaction.operationKind === 'gui-source-change' ||
+        transaction.operationKind === 'gui-helper-compilation') {
+        const studio = new ScriptedGuiStudio(engine);
+        const scanned = await studio.scan(transaction.workspaceId, principal, signal);
+        diagnostics.push(...scanned.graph.diagnostics);
+        const passed = !scanned.graph.diagnostics.some(({ severity }) => severity === 'error' || severity === 'blocker');
+        checks.push({
+            id: 'post-write-gui-graph',
+            passed,
+            message: passed
+                ? 'The GUI graph rebuilt successfully'
+                : 'The GUI graph has blocking diagnostics',
+        });
+    }
+    else if (transaction.operationKind === 'agent-nudger-map-changes') {
+        const nudger = new AgentNudger(engine);
+        const validated = await nudger.validate(transaction.workspaceId, principal, signal);
+        const mapDiagnostics = attributeMapValidationDiagnostics({
+            diagnostics: [...diagnostics, ...validated.validation.diagnostics],
+            operations: transaction.operations,
+            changes: transaction.files,
+        });
+        diagnostics.length = 0;
+        diagnostics.push(...mapDiagnostics);
+        checks.push(...validated.validation.checks);
+        checks.push({
+            id: 'post-write-map',
+            passed: validated.validation.passed,
+            message: validated.validation.passed
+                ? 'The map result rescanned and validated successfully'
+                : 'The map result failed post-write validation',
+        });
+    }
+    const passed = !diagnostics.some(({ severity }) => severity === 'error' || severity === 'blocker');
+    checks.unshift({
+        id: 'post-write-shared-index',
+        passed,
+        message: passed
+            ? 'Changed files reparsed and reindexed successfully'
+            : 'Changed files have blocking post-write diagnostics',
+    });
+    const availableDiagnostics = Math.max(0, TRANSACTION_MAX_DIAGNOSTICS - transaction.diagnostics.length);
+    if (diagnostics.length > availableDiagnostics) {
+        const workspace = engine.resolver.get(transaction.workspaceId, principal);
+        const sourceEvidence = boundedSourceHashEvidence(Object.fromEntries(transaction.files.flatMap(({ relativePath, afterSha256 }) => afterSha256 === null ? [] : [[relativePath, afterSha256]])));
+        const artifact = await engine.artifacts.putChunked(workspace, `${transaction.operationKind}.post-validation.json`, 'application/json', `${canonicalJson({
+            schemaVersion: 1,
+            operationKind: transaction.operationKind,
+            diagnosticCount: diagnostics.length,
+            checks,
+            diagnostics,
+        })}\n`, {
+            kind: 'rewrite-post-validation',
+            toolVersion: PACKAGE_VERSION,
+            schemaVersion: 'rewrite-post-validation.v1',
+            sourceHashes: sourceEvidence.sourceHashes,
+            metadata: { sourceHashInventory: sourceEvidence.inventory },
+        }, 'Complete diagnostics from post-write validation', signal);
+        const retainedLimit = Math.max(0, availableDiagnostics - 1);
+        const hard = diagnostics.filter(({ severity }) => severity === 'error' || severity === 'blocker');
+        const retainedHard = hard.slice(0, retainedLimit);
+        const retainedSoft = diagnostics
+            .filter(({ severity }) => severity !== 'error' && severity !== 'blocker')
+            .slice(0, retainedLimit - retainedHard.length);
+        const omittedHard = hard.length - retainedHard.length;
+        const artifactLink = publicArtifactLink(artifact);
+        checks.push({
+            id: 'post-write-diagnostics-artifact',
+            passed: omittedHard === 0,
+            message: `Complete post-write diagnostics are stored at ${artifactLink.uri}`,
+        });
+        return {
+            diagnostics: availableDiagnostics === 0
+                ? []
+                : [
+                    ...retainedHard,
+                    ...retainedSoft,
+                    {
+                        code: 'POST_VALIDATION_DIAGNOSTICS_IN_ARTIFACT',
+                        severity: omittedHard > 0 ? 'blocker' : 'warning',
+                        category: 'validation',
+                        message: `Complete post-write validation contains ${diagnostics.length} diagnostics and is stored as an artifact`,
+                        details: {
+                            total: diagnostics.length,
+                            returned: availableDiagnostics,
+                            omitted: diagnostics.length - retainedLimit,
+                            omittedHard,
+                            artifact: artifactLink,
+                        },
+                    },
+                ],
+            checks,
+            artifacts: [artifactLink],
+        };
+    }
+    return { diagnostics, checks, artifacts: [] };
+}

package/dist/hoi4_agent_tools/core/engine.js

@@ -1,10 +1,14 @@
 import { compareCodeUnits, hashCanonical } from './canonical.js';
 import { SymbolIndex } from './index.js';
+import { IndexSegmentCache } from './index-segments.js';
+import { PersistentAnalysisCache, } from './persistent-analysis-cache.js';
+import { sourceDocuments } from './source/cache.js';
 import { WorkspaceScanner } from './scanner.js';
 import { ArtifactStore } from './artifacts.js';
-import { TransactionManager } from './transactions.js';
+import { TransactionManager, transactionRootFingerprint } from './transactions.js';
 import { RequestScheduler } from './request-scheduler.js';
 import { SharedRequestCapacity } from './shared-request-capacity.js';
+import { JobStore } from './job-store.js';
 const RECOVERY_TTL_SECONDS = 3_600;
 const RECOVERY_MAX_BYTES = 536_870_912;
 const RECOVERY_MAX_RECORDS = 128;
@@ -81,6 +85,8 @@ export class CoreEngine {
     scanner;
     artifacts;
     transactions;
+    indexSegments;
+    persistentAnalysisCache;
     #scanCache = new Map();
     #scanFlights = new Map();
     #scanGenerations = new Map();
@@ -88,14 +94,30 @@ export class CoreEngine {
     #activeScanAdmissions = new Set();
     constructor(resolver, services = {}) {
         this.resolver = resolver;
+        this.indexSegments = services.indexSegments ?? new IndexSegmentCache();
+        const state = resolver.serverState();
+        this.persistentAnalysisCache =
+            services.persistentAnalysisCache === null || state === undefined
+                ? undefined
+                : Promise.resolve(services.persistentAnalysisCache ?? PersistentAnalysisCache.create(state));
         this.requests = new RequestScheduler(resolver.config().maxConcurrentTools);
         this.sharedRequests = new SharedRequestCapacity(resolver.serverState()?.root, resolver.config().maxSharedTools);
         this.scanner =
             services.scanner ??
                 new WorkspaceScanner(resolver.config().scanMaxFiles, resolver.config().scanMaxBytes, resolver.config().scanMaxFileBytes);
+        let retentionJobs;
         this.artifacts =
             services.artifacts ??
-                new ArtifactStore(resolver.config().artifactMaxBytes, resolver.config().artifactMaxEntries, resolver.config().artifactMaxSingleBytes);
+                new ArtifactStore(resolver.config().artifactMaxBytes, resolver.config().artifactMaxEntries, resolver.config().artifactMaxSingleBytes, state === undefined
+                    ? undefined
+                    : async (workspace, signal) => {
+                        retentionJobs ??= JobStore.create(state);
+                        return (await retentionJobs).checkpointResources({
+                            workspaceId: workspace.id,
+                            workspaceIdentity: workspace.workspaceIdentity,
+                            rootFingerprint: transactionRootFingerprint(workspace),
+                        }, signal);
+                    });
         this.transactions =
             services.transactions ??
                 new TransactionManager(resolver, this.artifacts, RECOVERY_TTL_SECONDS, RECOVERY_MAX_BYTES, RECOVERY_MAX_RECORDS, resolver.serverState());
@@ -160,12 +182,28 @@ export class CoreEngine {
                         signal: controller.signal,
                     });
                     controller.signal.throwIfAborted();
-                    const revision = hashCanonical(files.map(({ displayPath, loadOrder, sha256 }) => ({ displayPath, loadOrder, sha256 })));
+                    const persistentAnalysisCache = await this.persistentAnalysisCache;
+                    const analysisScope = {
+                        workspaceIdentity: workspace.workspaceIdentity,
+                        rootFingerprint: transactionRootFingerprint(workspace),
+                        principal: principal ?? null,
+                    };
+                    await persistentAnalysisCache?.hydrate(analysisScope, files, sourceDocuments, this.indexSegments, controller.signal);
+                    const revision = hashCanonical(files.map(({ absolutePath, displayPath, relativePath, rootKind, loadOrder, shadowedBy, sha256, }) => ({
+                        absolutePath,
+                        displayPath,
+                        relativePath,
+                        rootKind,
+                        loadOrder,
+                        shadowedBy: shadowedBy ?? null,
+                        sha256,
+                    })));
                     const cacheKey = `${requestKey}:${revision}`;
                     const cached = this.#scanCache.get(cacheKey);
                     if (cached !== undefined)
                         return cached;
-                    const index = await SymbolIndex.buildAsync(files, controller.signal);
+                    const index = await SymbolIndex.buildAsync(files, controller.signal, this.indexSegments);
+                    await persistentAnalysisCache?.persist(analysisScope, files, sourceDocuments, this.indexSegments, controller.signal);
                     const snapshot = {
                         workspaceId,
                         revision,
@@ -219,12 +257,17 @@ export class CoreEngine {
     /** Drop completed scan buffers without invalidating revisions or interrupting active scans. */
     releaseScanCaches() {
         this.#scanCache.clear();
+        this.indexSegments.clear();
+        sourceDocuments.clear();
         this.scanner.clearCaches();
     }
     /** Monotonic cache generation used by domain services to invalidate derived snapshots. */
     generation(workspaceId) {
         return this.#scanGenerations.get(workspaceId) ?? 0;
     }
+    async persistentAnalysisCacheStatistics() {
+        return (await this.persistentAnalysisCache)?.statistics();
+    }
     awaitScanFlight(requestKey, flight, signal) {
         signal?.throwIfAborted();
         flight.waiters += 1;
@@ -342,6 +385,6 @@ export class CoreEngine {
         }
     }
     indexFiles(files) {
-        return SymbolIndex.build(files);
+        return SymbolIndex.build(files, this.indexSegments);
     }
 }