@weftlet/toolkit 0.6.0 → 0.7.0

package/dist/application/mapping-proposals.js

@@ -0,0 +1,142 @@
+import { sha256, stableJson } from '../infrastructure/util.js';
+import { jsonDigest } from '../infrastructure/json-digest.js';
+import { prepareMappingProposal } from '../extraction/mapping-plan.js';
+import { parseMappingRequest, mappingVersion } from '../extraction/mapping-request.js';
+import { validateMappingOutput } from '../extraction/mapping-output.js';
+import { SemanticProviderError } from '../extraction/semantic-process.js';
+import { inspectSavedEvidence } from './saved-evidence.js';
+import { snapshotContext } from '../graph/snapshot-context.js';
+import { RdfEvidenceGraph } from '../graph/rdf.js';
+export class MappingProposalService {
+    repository;
+    snapshots;
+    artifacts;
+    settings;
+    constructor(repository, snapshots, artifacts, settings) {
+        this.repository = repository;
+        this.snapshots = snapshots;
+        this.artifacts = artifacts;
+        this.settings = settings;
+        if (!Number.isSafeInteger(settings.timeoutMs) || settings.timeoutMs < 1 || settings.timeoutMs > 600_000)
+            throw Error('Mapping timeout must be between 1 and 600000 ms');
+    }
+    async snapshot(snapshotId) {
+        const snapshot = await this.snapshots.read(snapshotId);
+        if (!snapshot || snapshot.manifest.snapshotId !== snapshotId || snapshot.manifest.repositoryId !== this.settings.repositoryId)
+            throw Error('Mapping snapshot is missing or has mismatched identity');
+        const facts = await new RdfEvidenceGraph(snapshot).facts();
+        if (new Set(facts.map(f => f.id)).size !== facts.length)
+            throw Error('Duplicate mapping evidence identities');
+        return { ...snapshot, facts };
+    }
+    evidence(snapshot) {
+        return inspectSavedEvidence(snapshotContext(snapshot.manifest), this.repository, this.settings.configurationDigest, this.settings.expectedExtractors);
+    }
+    key(plan) {
+        // Checkout dirtiness and operational timeout never change an immutable evidence request's identity.
+        const { evidenceState: _state, ...saved } = plan;
+        return jsonDigest({ version: mappingVersion, provider: this.settings.providerIdentity, plan: saved });
+    }
+    validate(artifact, snapshot, key) {
+        if (artifact.key !== key || artifact.version !== mappingVersion || artifact.plan.version !== mappingVersion || !artifact.plan.ready ||
+            artifact.plan.snapshotDigest !== jsonDigest(snapshot) || artifact.plan.snapshot.snapshotId !== snapshot.manifest.snapshotId ||
+            artifact.authority !== 'inferred' || artifact.extractionReview !== 'unreviewed' || artifact.establishesCompliance !== false ||
+            artifact.outputDigest !== jsonDigest({ plan: artifact.plan, providerIdentity: artifact.providerIdentity, output: artifact.output })) {
+            throw Error('Mapping artifact integrity or snapshot binding mismatch');
+        }
+        if (jsonDigest({ version: mappingVersion, provider: artifact.providerIdentity, plan: artifact.plan }) !== key)
+            throw Error('Mapping artifact key mismatch');
+        validateMappingOutput(artifact.output, artifact.plan);
+        return artifact;
+    }
+    async plan(value) {
+        const request = parseMappingRequest(value), snapshot = await this.snapshot(request.snapshotId);
+        const prepared = await prepareMappingProposal(this.repository, snapshot, request);
+        const evidenceState = await this.evidence(snapshot);
+        const issues = [...prepared.plan.issues];
+        if (!evidenceState.extractionCompatible)
+            issues.push({ code: 'incompatible-snapshot-extraction' });
+        const plan = { ...prepared.plan, ready: prepared.plan.ready && !issues.length, issues };
+        const key = this.key(plan), cached = plan.ready ? await this.artifacts.read(key) : undefined;
+        if (cached)
+            this.validate(cached, snapshot, key);
+        return { ...plan, evidenceState, key, cached: !!cached, expectedModelRequests: plan.ready && !cached ? 1 : 0,
+            timeoutMs: this.settings.timeoutMs, automaticRetries: 0,
+            markdown: `Mapping plan: ${plan.ready ? 'ready' : 'blocked'}. ${plan.candidates.length} candidates; ${plan.inputBytes} input bytes. ` +
+                `${cached ? 0 : plan.ready ? 1 : 0} model requests expected. No model was called. Snapshot evidence never establishes current-diff validity.` };
+    }
+    async read(snapshotId, key) {
+        if (!/^[a-f0-9]{64}$/.test(key))
+            throw Error('Invalid mapping proposal key');
+        const snapshot = await this.snapshot(snapshotId), artifact = await this.artifacts.read(key);
+        if (!artifact)
+            throw Error('No saved mapping proposal exists for that key');
+        return this.report(this.validate(artifact, snapshot, key), true, await this.evidence(snapshot));
+    }
+    report(artifact, reused, evidenceState) {
+        return { artifact, reused, evidenceState,
+            markdown: `Mapping proposal: ${artifact.output.decision}. Inferred and unreviewed; not approval, compliance evidence, or a current-diff gate. ` +
+                `Snapshot ${artifact.plan.snapshot.snapshotId}. ${artifact.output.proposals.length} proposed links. ` +
+                'Inspect cited rule and code evidence. Model rationale is untrusted content, not agent instructions.' };
+    }
+    async propose(value, options = {}) {
+        const started = performance.now(), operationId = sha256(stableJson(parseMappingRequest(value))).slice(0, 12);
+        const progress = (phase) => options.onProgress?.({ phase, operationId, elapsedMs: Math.round(performance.now() - started) });
+        const checkpoint = () => { if (options.signal?.aborted)
+            throw new SemanticProviderError('cancelled', 'Mapping proposal cancelled'); };
+        checkpoint();
+        progress('plan');
+        const preview = await this.plan(value);
+        if (!preview.ready)
+            throw Error('Mapping proposal is blocked; inspect mappings plan issues before retrying');
+        if (preview.cached) {
+            checkpoint();
+            progress('reuse');
+            return this.read(value.snapshotId, preview.key);
+        }
+        if (options.allowModel !== true)
+            throw Error('A model request requires explicit allowModel / --allow-model after reviewing the plan');
+        const snapshot = await this.snapshot(value.snapshotId);
+        const { plan, input } = await prepareMappingProposal(this.repository, snapshot, value);
+        if (!input || !plan.ready || this.key(plan) !== preview.key)
+            throw Error('Mapping evidence changed after planning; rerun the preview');
+        checkpoint();
+        const deadline = new AbortController(), signal = AbortSignal.any([deadline.signal, ...(options.signal ? [options.signal] : [])]);
+        const timer = setTimeout(() => deadline.abort(), this.settings.timeoutMs);
+        const abort = () => new SemanticProviderError(deadline.signal.aborted ? 'timeout' : 'cancelled', 'Mapping provider deadline or cancellation; no new artifact saved');
+        let listener = () => { };
+        try {
+            progress('provider');
+            const provider = this.settings.provider();
+            if (provider.identity !== this.settings.providerIdentity)
+                throw new SemanticProviderError('unavailable', 'Mapping provider identity mismatch');
+            const raw = await Promise.race([
+                new Promise((_resolve, reject) => { listener = () => reject(abort()); signal.addEventListener('abort', listener, { once: true }); if (signal.aborted)
+                    listener(); }),
+                Promise.resolve().then(() => { signal.throwIfAborted(); return provider.propose(input, { signal, timeoutMs: this.settings.timeoutMs }); }),
+            ]);
+            if (signal.aborted)
+                throw abort();
+            progress('validate');
+            const output = validateMappingOutput(raw, plan);
+            const artifact = { key: preview.key, version: mappingVersion, providerIdentity: provider.identity,
+                plan, output, outputDigest: jsonDigest({ plan, providerIdentity: provider.identity, output }),
+                authority: 'inferred', extractionReview: 'unreviewed', establishesCompliance: false };
+            if (signal.aborted)
+                throw abort();
+            await this.artifacts.write(artifact);
+            progress('saved');
+            return this.report(artifact, false, await this.evidence(snapshot));
+        }
+        catch (error) {
+            if (error instanceof SemanticProviderError && ['timeout', 'cancelled', 'invalid-output', 'unavailable', 'exit'].includes(error.code)) {
+                throw new SemanticProviderError(error.code, `Mapping proposal ${error.code}; inspect the plan and retry explicitly. Existing evidence is retained.`);
+            }
+            throw new Error('Mapping proposal failed; existing evidence is retained. Provider details are withheld.');
+        }
+        finally {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', listener);
+        }
+    }
+}

package/dist/application/mapping-service.d.ts

@@ -0,0 +1,2 @@
+/** Public configured service; provider construction stays lazy until an explicitly allowed run. */
+export declare function createMappingProposalService(configPath: string): Promise<import("./mapping-proposals.js").MappingProposalService>;

package/dist/application/mapping-service.js

@@ -0,0 +1,5 @@
+import { createContextGraphApplication } from './application.js';
+/** Public configured service; provider construction stays lazy until an explicitly allowed run. */
+export async function createMappingProposalService(configPath) {
+    return (await createContextGraphApplication(configPath)).mappingProposalService;
+}

package/dist/application/overlay.js

@@ -3,6 +3,7 @@ import { mkdir, rm, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { promisify } from 'node:util';
 import { scipSourcePatterns } from '../configuration/scip-project.js';
+import { buildCodeInventory } from '../extraction/code-inventory.js';
 import { GitRepository } from "../repository/git.js";
 import { withCommittedTree } from "../repository/committed-tree.js";
 import { RepositoryContractExtractor, RepositoryFileExtractor, ScipSymbolExtractor, ScipTypeScriptIndexer, repositoryFileExtractorIdentity, repositoryContractExtractorIdentity, scipSymbolExtractorIdentity } from "../extraction/static.js";
@@ -15,11 +16,18 @@ import { graphAssemblyIdentity, documentExtractionVersions } from './extraction-
 import { assertGraphIdentities } from '../graph/identity-preflight.js';
 import { selectHydrationInputs, documentSelectionIdentity } from './hydration-inputs.js';
 import { retainOverlayDocumentFact, overlayDocumentRoots, overlayDocumentManifest, overlayDocumentNotes } from './document-overlay.js';
+import { assembleDocumentCodeBindings } from './document-code-bindings.js';
+import { documentCodeBindingIdentity } from '../extraction/document-code-bindings.js';
+import { documentObligationIdentity } from '../extraction/document-obligations.js';
+import { assembleDocumentObligations } from './document-obligations.js';
+import { draftFacts } from './draft-facts.js';
+import { staticCallIdentity } from '../extraction/static-calls.js';
+import { extractEvidence } from './extractor-results.js';
 import { documentEvidenceExtractorIdentity } from '../extraction/document-evidence.js';
 const execute = promisify(execFile);
 const implementationExtractors = new Set([
     'repository-file-extractor', 'repository-contract-extractor', 'scip-symbol-extractor',
-    routingExtractorIdentity.id,
+    routingExtractorIdentity.id, documentCodeBindingIdentity.id, staticCallIdentity.id, documentObligationIdentity.id,
 ]);
 /** Conservative code overlay: reindex implementation; invalidate changed prose, never synthesize intent. */
 export async function buildWorkingOverlay(repository, config, store, storageRoot, baseSnapshotId, agent = 'default', options = {}) {
@@ -44,7 +52,8 @@ export async function buildWorkingOverlay(repository, config, store, storageRoot
     const roots = [...config.codeRoots, ...config.semanticSources, ...config.evidenceRoots,
         ...overlayDocumentRoots(config),
         ...config.contractPatterns, ...scipSourcePatterns(config.scip.sourceProject),
-        ...routingSources, ...baseRouting.referencedPaths];
+        ...routingSources, ...baseRouting.referencedPaths,
+        ...base.facts.flatMap(fact => fact.contractObligation ? [fact.contractObligation.declaration.endpoint] : [])];
     const excluded = [];
     for (const path of changed) {
         if (!inWorkingScope(path, roots)) {
@@ -96,14 +105,18 @@ export async function buildWorkingOverlay(repository, config, store, storageRoot
             deletedPaths: captured.filter((f) => f.content === null).map((f) => f.path),
             renamedPaths: {},
         };
-        const documents = config.documentTraversal
-            ? await selectHydrationInputs(draftRepository, context.commitSha, config) : undefined;
+        const documents = await selectHydrationInputs(draftRepository, context.commitSha, config);
+        const obligations = await assembleDocumentObligations(draftRepository, context, documents, config);
+        if (obligations.facts.some(fact => !inWorkingScope(fact.contractObligation.declaration.endpoint, roots))) {
+            throw new Error('Draft obligation endpoints are outside captured source scope; configure their scope before rebuilding');
+        }
         const documentSelection = documents?.documentSelection ? {
             ...documents.documentSelection,
             // Temporary Git commit timestamps are not evidence identity. Bind drafts to captured bytes.
             digest: sha256(stableJson({ ...documents.documentSelection, digest: undefined, baseSha: head, overlayDigest })),
         } : undefined;
         const scip = await new ScipTypeScriptIndexer(config.scip, storageRoot).index(context);
+        const codeInventory = buildCodeInventory(await draftRepository.listEntriesAt(context.commitSha), await draftRepository.listFilesAt(context.commitSha, config.codeRoots), config.codeRoots, config.scip.sourceProject, scip);
         const routing = await extractRoutingDeclarations(draftRepository, context, routingSources, { allowMissingSources: true });
         const uncapturedEndpoints = routing.referencedPaths.filter((path) => !inWorkingScope(path, roots));
         if (uncapturedEndpoints.length) {
@@ -114,42 +127,43 @@ export async function buildWorkingOverlay(repository, config, store, storageRoot
             new RepositoryContractExtractor(draftRepository, config.contractPatterns, config.contractConsumerRoots ?? config.codeRoots, config.contractAliases),
             new ScipSymbolExtractor(draftRepository, scip),
         ];
-        const facts = [...(await Promise.all(extractors.map((e) => e.extract(context)))).flat(),
-            ...routing.facts, ...(documents?.documentEvidence?.facts ?? [])].map(({ id: _id, ...fact }) => {
-            const draft = { ...fact, snapshotId, authority: 'draft',
-                ...(fact.extractor.id === routingExtractorIdentity.id || fact.sourceRole !== undefined ? { sourceAuthority: 'draft' } : {}),
-                provenance: { ...fact.provenance, commitSha: head } };
-            return { ...draft, id: sha256(stableJson(draft)) };
-        });
-        const diagnostics = [...routing.diagnostics, ...(documents?.documentEvidence?.diagnostics ?? [])].map(({ id: _id, ...item }) => {
+        const extraction = await extractEvidence(extractors, context);
+        const codeFacts = extraction.facts;
+        const retainedSubjects = base.facts.filter(fact => retainOverlayDocumentFact(fact, documents, affected) &&
+            !implementationExtractors.has(fact.extractor.id) &&
+            contextPackEvidenceAuthority(fact) !== 'implemented' &&
+            fact.extractor.id !== 'otlp-runtime-evidence' && !affected.has(fact.provenance.path) &&
+            ![fact.subject, fact.object].some(node => [...affected].some(path => node.id === `component:file:${path}` || node.id === `document:${path}` || node.label === path)));
+        const bindings = await assembleDocumentCodeBindings(draftRepository, context, documents, config, codeFacts, [...retainedSubjects, ...codeFacts, ...routing.facts, ...obligations.facts]);
+        const facts = draftFacts([...codeFacts, ...routing.facts, ...obligations.facts, ...(documents.documentEvidence?.facts ?? []), ...bindings.facts], snapshotId, head);
+        const diagnostics = [...extraction.diagnostics, ...bindings.diagnostics, ...obligations.diagnostics, ...routing.diagnostics, ...(documents?.documentEvidence?.diagnostics ?? [])].map(({ id: _id, ...item }) => {
             const draft = { ...item, provenance: item.provenance.map((span) => ({ ...span, commitSha: head })) };
             return { ...draft, id: sha256(stableJson(draft)) };
         }).sort((a, b) => a.id.localeCompare(b.id));
-        return { facts, diagnostics, documents, documentSelection };
+        return { facts, diagnostics, documents, documentSelection, retainedSubjects, codeInventory };
     });
-    const retained = base.facts.filter((fact) => retainOverlayDocumentFact(fact, extracted.documents, affected) &&
-        !implementationExtractors.has(fact.extractor.id) &&
-        contextPackEvidenceAuthority(fact) !== 'implemented' &&
-        fact.extractor.id !== 'otlp-runtime-evidence' &&
-        !affected.has(fact.provenance.path) &&
-        ![fact.subject, fact.object].some((node) => [...affected].some((path) => node.id === `component:file:${path}` || node.id === `document:${path}` || node.label === path))).map((fact) => ({ ...fact, snapshotId }));
+    const retained = extracted.retainedSubjects.map(fact => ({ ...fact, snapshotId }));
     const allFacts = [...retained, ...extracted.facts].sort((a, b) => a.id.localeCompare(b.id));
     assertGraphIdentities(allFacts, { repositoryId: config.repositoryId, includeDetails: options.validationDetails });
     const overlay = {
         ...base,
         manifest: {
             ...base.manifest, snapshotId, baseSha: head, overlayDigest, overlayCapture,
+            codeInventory: extracted.codeInventory, scipIndexDigest: extracted.codeInventory.scipIndexDigest,
             ...overlayDocumentManifest(extracted.documentSelection),
             extractorVersions: { ...base.manifest.extractorVersions,
                 assembly: graphAssemblyIdentity,
+                [documentCodeBindingIdentity.id]: documentCodeBindingIdentity.version,
+                [documentObligationIdentity.id]: documentObligationIdentity.version,
                 ...documentExtractionVersions(config),
                 [repositoryFileExtractorIdentity.id]: repositoryFileExtractorIdentity.version,
                 [repositoryContractExtractorIdentity.id]: repositoryContractExtractorIdentity.version,
                 [scipSymbolExtractorIdentity.id]: scipSymbolExtractorIdentity.version,
+                [staticCallIdentity.id]: staticCallIdentity.version,
                 ...(routingSources.length ? { [routingExtractorIdentity.id]: routingExtractorIdentity.version } : {}) },
-            generatedAt: new Date().toISOString(), contentDigest: sha256(stableJson(routingSources.length || config.documentTraversal
-                ? { facts: allFacts, diagnostics: extracted.diagnostics,
-                    ...(extracted.documentSelection ? { documentSelection: extracted.documentSelection } : {}) } : allFacts)),
+            generatedAt: new Date().toISOString(), contentDigest: sha256(stableJson({ facts: allFacts, diagnostics: extracted.diagnostics,
+                codeInventory: extracted.codeInventory,
+                ...(extracted.documentSelection ? { documentSelection: extracted.documentSelection } : {}) })),
         },
         facts: allFacts,
         invariants: base.invariants.map((rule) => ({

package/dist/application/saved-code-coverage.d.ts

@@ -0,0 +1,40 @@
+import type { CodeCoverageRequest, CodeCoverageService } from '@weftlet/core';
+import type { GitRepository } from '../repository/git.js';
+export declare class SavedCodeCoverageService implements CodeCoverageService {
+    private readonly queries;
+    private readonly repository;
+    private readonly configurationDigest;
+    private readonly expectedExtractors?;
+    constructor(queries: CodeCoverageService, repository: GitRepository, configurationDigest: string, expectedExtractors?: Readonly<Record<string, string>> | undefined);
+    coverage(request: CodeCoverageRequest): Promise<{
+        markdown: string;
+        evidenceState: {
+            readonly currentCommit?: string;
+            readonly excludedWorkingChanges: readonly string[];
+            readonly capturedWorkingChanges?: readonly string[];
+            readonly changedSinceCapture?: readonly string[];
+            readonly overlayFreshness?: "current" | "stale" | "unknown";
+            readonly stale: boolean;
+            readonly configurationMatches: boolean;
+            readonly extractionCompatible?: boolean;
+            readonly incompatibleExtractors?: readonly string[];
+            readonly eligibleForCurrentDiffValidation: false;
+        };
+        snapshot: import("@weftlet/core").ContextPack["snapshot"];
+        overview: import("@weftlet/core").CodeCoverageOverview;
+        view: "projects" | "files";
+        project?: import("@weftlet/core").CodeProjectCoverage;
+        projectStatus?: "present" | "absent" | "unknown";
+        projects: readonly import("@weftlet/core").CodeProjectCoverage[];
+        files: readonly import("@weftlet/core").CodeFileCoverage[];
+        selection: {
+            readonly projectRoot?: string;
+            readonly maxItems: number;
+            readonly offset: number;
+            readonly total: number;
+            readonly remaining: number;
+            readonly truncated: boolean;
+            readonly continuation?: string;
+        };
+    }>;
+}

package/dist/application/saved-code-coverage.js

@@ -0,0 +1,20 @@
+import { renderCodeCoverage } from '../graph/code-coverage-renderer.js';
+import { inspectSavedEvidence } from './saved-evidence.js';
+export class SavedCodeCoverageService {
+    queries;
+    repository;
+    configurationDigest;
+    expectedExtractors;
+    constructor(queries, repository, configurationDigest, expectedExtractors) {
+        this.queries = queries;
+        this.repository = repository;
+        this.configurationDigest = configurationDigest;
+        this.expectedExtractors = expectedExtractors;
+    }
+    async coverage(request) {
+        const report = await this.queries.coverage(request);
+        const evidenceState = await inspectSavedEvidence(report.snapshot, this.repository, this.configurationDigest, this.expectedExtractors);
+        const result = { ...report, evidenceState };
+        return { ...result, markdown: renderCodeCoverage(result) };
+    }
+}

package/dist/application/saved-compatibility.d.ts

@@ -0,0 +1,38 @@
+import type { ContractCompatibilityRequest, ContractCompatibilityService } from '@weftlet/core';
+import type { GitRepository } from '../repository/git.js';
+export declare class SavedContractCompatibilityService implements ContractCompatibilityService {
+    private readonly queries;
+    private readonly repository;
+    private readonly configurationDigest;
+    private readonly expectedExtractors?;
+    constructor(queries: ContractCompatibilityService, repository: GitRepository, configurationDigest: string, expectedExtractors?: Readonly<Record<string, string>> | undefined);
+    assess(request: ContractCompatibilityRequest): Promise<{
+        markdown: string;
+        evidenceState: {
+            readonly currentCommit?: string;
+            readonly excludedWorkingChanges: readonly string[];
+            readonly capturedWorkingChanges?: readonly string[];
+            readonly changedSinceCapture?: readonly string[];
+            readonly overlayFreshness?: "current" | "stale" | "unknown";
+            readonly stale: boolean;
+            readonly configurationMatches: boolean;
+            readonly extractionCompatible?: boolean;
+            readonly incompatibleExtractors?: readonly string[];
+            readonly eligibleForCurrentDiffValidation: false;
+        };
+        snapshot: import("@weftlet/core").ContextPack["snapshot"];
+        selection: ContractCompatibilityRequest;
+        facts: readonly import("@weftlet/core").GraphFact[];
+        coverage: import("@weftlet/core").ContextPack["coverage"];
+        assessment: import("@weftlet/core").ContractCompatibilityAssessment;
+        context: {
+            readonly contractNodeIds: readonly string[];
+            readonly endpointNodeIds: readonly string[];
+            readonly otherIncidentFacts: number;
+            readonly competingFactIds: readonly string[];
+            readonly competingFacts: number;
+            readonly omittedCompetingFacts: number;
+        };
+        diagnostics: import("@weftlet/core").DiagnosticReport;
+    }>;
+}

package/dist/application/saved-compatibility.js

@@ -0,0 +1,20 @@
+import { renderContractCompatibility } from '../graph/compatibility-renderer.js';
+import { inspectSavedEvidence } from './saved-evidence.js';
+export class SavedContractCompatibilityService {
+    queries;
+    repository;
+    configurationDigest;
+    expectedExtractors;
+    constructor(queries, repository, configurationDigest, expectedExtractors) {
+        this.queries = queries;
+        this.repository = repository;
+        this.configurationDigest = configurationDigest;
+        this.expectedExtractors = expectedExtractors;
+    }
+    async assess(request) {
+        const report = await this.queries.assess(request);
+        const evidenceState = await inspectSavedEvidence(report.snapshot, this.repository, this.configurationDigest, this.expectedExtractors);
+        const result = { ...report, evidenceState };
+        return { ...result, markdown: renderContractCompatibility(result) };
+    }
+}

package/dist/application/saved-evidence.d.ts

@@ -1,4 +1,4 @@
-import type { ImpactQueryService, ImpactScanRequest } from "@weftlet/core";
+import type { ContextPack, ImpactQueryService, ImpactScanRequest } from "@weftlet/core";
 import type { GitRepository } from "../repository/git.js";
 /** Read-side metadata; never calls an indexer, model, compiler, or refresh operation. */
 export declare class SavedEvidenceQueryService implements ImpactQueryService {
@@ -10,16 +10,16 @@ export declare class SavedEvidenceQueryService implements ImpactQueryService {
     scan(request: ImpactScanRequest): Promise<{
         markdown: string;
         evidenceState: {
-            eligibleForCurrentDiffValidation: false;
-            extractionCompatible?: boolean | undefined;
-            incompatibleExtractors?: readonly string[] | undefined;
-            stale: boolean;
-            configurationMatches: boolean;
-            overlayFreshness?: "unknown" | "current" | "stale" | undefined;
-            capturedWorkingChanges?: string[] | undefined;
-            changedSinceCapture?: string[] | undefined;
-            currentCommit: string | undefined;
-            excludedWorkingChanges: string[];
+            readonly currentCommit?: string;
+            readonly excludedWorkingChanges: readonly string[];
+            readonly capturedWorkingChanges?: readonly string[];
+            readonly changedSinceCapture?: readonly string[];
+            readonly overlayFreshness?: "current" | "stale" | "unknown";
+            readonly stale: boolean;
+            readonly configurationMatches: boolean;
+            readonly extractionCompatible?: boolean;
+            readonly incompatibleExtractors?: readonly string[];
+            readonly eligibleForCurrentDiffValidation: false;
         };
         snapshot: Pick<import("@weftlet/core").SnapshotManifest, "snapshotId" | "commitSha" | "contentDigest" | "configurationDigest" | "scope" | "baseSha" | "overlayDigest" | "overlayCapture"> & Partial<Pick<import("@weftlet/core").SnapshotManifest, "extractorVersions" | "documentSelection">>;
         capabilities: readonly import("@weftlet/core").GraphNode[];
@@ -31,6 +31,10 @@ export declare class SavedEvidenceQueryService implements ImpactQueryService {
         diagnostics: import("@weftlet/core").DiagnosticReport;
         exploration?: {
             readonly rankingVersion?: string;
+            readonly codeTraversalVersion?: string;
+            readonly unexpandedCodeTargets?: readonly string[];
+            readonly unexpandedCodeTargetCount?: number;
+            readonly unexpandedCodeTargetsTruncated?: boolean;
             readonly returned: number;
             readonly reachableFacts: number;
             readonly maxDepth: number;
@@ -40,3 +44,5 @@ export declare class SavedEvidenceQueryService implements ImpactQueryService {
         };
     }>;
 }
+/** Shared read-side state for impact scans and exact-node exploration. */
+export declare function inspectSavedEvidence(snapshot: ContextPack['snapshot'], repository: GitRepository, configurationDigest: string, expectedExtractors?: Readonly<Record<string, string>>): Promise<NonNullable<ContextPack['evidenceState']>>;

package/dist/application/saved-evidence.js

@@ -16,50 +16,54 @@ export class SavedEvidenceQueryService {
     }
     async scan(request) {
         const pack = await this.queries.scan(request);
-        const currentCommit = await this.repository.resolveRef('HEAD').catch(() => undefined);
-        const workingChanges = await this.repository.workingChanges();
-        const capturedWorkingChanges = [];
-        const changedSinceCapture = new Set();
-        let overlayFreshness;
-        if (pack.snapshot.overlayDigest) {
-            overlayFreshness = 'unknown';
-            const capture = pack.snapshot.overlayCapture;
-            if (capture) {
-                overlayFreshness = 'current';
-                for (const file of capture.files) {
-                    try {
-                        const content = await readWorkingContent(this.repository.root, file.path);
-                        if ((content === null ? null : sha256(content)) === file.digest)
-                            capturedWorkingChanges.push(file.path);
-                        else
-                            changedSinceCapture.add(file.path);
-                    }
-                    catch {
-                        overlayFreshness = 'unknown';
+        const evidenceState = await inspectSavedEvidence(pack.snapshot, this.repository, this.configurationDigest, this.expectedExtractors);
+        const result = { ...pack, evidenceState };
+        return { ...result, markdown: new MarkdownContextPackRenderer().render(result) };
+    }
+}
+/** Shared read-side state for impact scans and exact-node exploration. */
+export async function inspectSavedEvidence(snapshot, repository, configurationDigest, expectedExtractors) {
+    const currentCommit = await repository.resolveRef('HEAD').catch(() => undefined);
+    const workingChanges = await repository.workingChanges();
+    const capturedWorkingChanges = [];
+    const changedSinceCapture = new Set();
+    let overlayFreshness;
+    if (snapshot.overlayDigest) {
+        overlayFreshness = 'unknown';
+        const capture = snapshot.overlayCapture;
+        if (capture) {
+            overlayFreshness = 'current';
+            for (const file of capture.files) {
+                try {
+                    const content = await readWorkingContent(repository.root, file.path);
+                    if ((content === null ? null : sha256(content)) === file.digest)
+                        capturedWorkingChanges.push(file.path);
+                    else
                         changedSinceCapture.add(file.path);
-                    }
                 }
-                for (const path of workingChanges) {
-                    if (!capturedWorkingChanges.includes(path) && inWorkingScope(path, capture.sourcePatterns))
-                        changedSinceCapture.add(path);
+                catch {
+                    overlayFreshness = 'unknown';
+                    changedSinceCapture.add(file.path);
                 }
-                if (changedSinceCapture.size && overlayFreshness !== 'unknown')
-                    overlayFreshness = 'stale';
             }
+            for (const path of workingChanges) {
+                if (!capturedWorkingChanges.includes(path) && inWorkingScope(path, capture.sourcePatterns))
+                    changedSinceCapture.add(path);
+            }
+            if (changedSinceCapture.size && overlayFreshness !== 'unknown')
+                overlayFreshness = 'stale';
         }
-        const excludedWorkingChanges = workingChanges.filter((path) => !capturedWorkingChanges.includes(path));
-        const incompatibleExtractors = this.expectedExtractors
-            ? incompatibleSnapshotExtractors(pack.snapshot.extractorVersions, this.expectedExtractors) : undefined;
-        const evidenceState = {
-            currentCommit,
-            excludedWorkingChanges,
-            ...(overlayFreshness ? { overlayFreshness, capturedWorkingChanges, changedSinceCapture: [...changedSinceCapture].sort() } : {}),
-            stale: currentCommit !== pack.snapshot.commitSha || (overlayFreshness !== undefined && overlayFreshness !== 'current'),
-            configurationMatches: pack.snapshot.configurationDigest === this.configurationDigest,
-            ...(incompatibleExtractors ? { extractionCompatible: incompatibleExtractors.length === 0, incompatibleExtractors } : {}),
-            eligibleForCurrentDiffValidation: false,
-        };
-        const result = { ...pack, evidenceState };
-        return { ...result, markdown: new MarkdownContextPackRenderer().render(result) };
     }
+    const excludedWorkingChanges = workingChanges.filter((path) => !capturedWorkingChanges.includes(path));
+    const incompatibleExtractors = expectedExtractors
+        ? incompatibleSnapshotExtractors(snapshot.extractorVersions, expectedExtractors) : undefined;
+    return {
+        currentCommit,
+        excludedWorkingChanges,
+        ...(overlayFreshness ? { overlayFreshness, capturedWorkingChanges, changedSinceCapture: [...changedSinceCapture].sort() } : {}),
+        stale: currentCommit !== snapshot.commitSha || (overlayFreshness !== undefined && overlayFreshness !== 'current'),
+        configurationMatches: snapshot.configurationDigest === configurationDigest,
+        ...(incompatibleExtractors ? { extractionCompatible: incompatibleExtractors.length === 0, incompatibleExtractors } : {}),
+        eligibleForCurrentDiffValidation: false,
+    };
 }

package/dist/application/saved-exploration.d.ts

@@ -0,0 +1,57 @@
+import type { GraphExplorationService, GraphNeighborsRequest } from '@weftlet/core';
+import type { GitRepository } from '../repository/git.js';
+/** Adds checkout/overlay state without extracting, refreshing or changing a saved graph. */
+export declare class SavedGraphExplorationService implements GraphExplorationService {
+    private readonly queries;
+    private readonly repository;
+    private readonly configurationDigest;
+    private readonly expectedExtractors?;
+    constructor(queries: GraphExplorationService, repository: GitRepository, configurationDigest: string, expectedExtractors?: Readonly<Record<string, string>> | undefined);
+    neighbors(request: GraphNeighborsRequest): Promise<{
+        markdown: string;
+        evidenceState: {
+            readonly currentCommit?: string;
+            readonly excludedWorkingChanges: readonly string[];
+            readonly capturedWorkingChanges?: readonly string[];
+            readonly changedSinceCapture?: readonly string[];
+            readonly overlayFreshness?: "current" | "stale" | "unknown";
+            readonly stale: boolean;
+            readonly configurationMatches: boolean;
+            readonly extractionCompatible?: boolean;
+            readonly incompatibleExtractors?: readonly string[];
+            readonly eligibleForCurrentDiffValidation: false;
+        };
+        snapshot: import("@weftlet/core").ContextPack["snapshot"];
+        focus: {
+            readonly nodeId: string;
+            readonly status: "present" | "absent-from-snapshot";
+        };
+        facts: readonly import("@weftlet/core").GraphFact[];
+        coverage: import("@weftlet/core").ContextPack["coverage"];
+        diagnostics: import("@weftlet/core").ContextPack["diagnostics"];
+        selection: {
+            readonly version: string;
+            readonly direction: import("@weftlet/core").GraphDirection;
+            readonly predicates: readonly import("@weftlet/core").GraphPredicate[];
+            readonly maxFacts: number;
+            readonly incidentFacts: number;
+            readonly matchingFacts: number;
+            readonly filteredFacts: number;
+            readonly offset: number;
+            readonly returnedFacts: number;
+            readonly remainingFacts: number;
+            readonly truncated: boolean;
+            readonly continuation?: string;
+        };
+        frontier: {
+            readonly scope: "selected-one-hop-neighborhood";
+            readonly totalNeighbors: number;
+            readonly remainingNeighbors: number;
+            readonly neighbors: readonly {
+                readonly nodeId: string;
+                readonly factIds: readonly string[];
+                readonly otherIncidentFacts: number;
+            }[];
+        };
+    }>;
+}

package/dist/application/saved-exploration.js

@@ -0,0 +1,21 @@
+import { renderGraphNeighborhood } from '../graph/neighborhood-renderer.js';
+import { inspectSavedEvidence } from './saved-evidence.js';
+/** Adds checkout/overlay state without extracting, refreshing or changing a saved graph. */
+export class SavedGraphExplorationService {
+    queries;
+    repository;
+    configurationDigest;
+    expectedExtractors;
+    constructor(queries, repository, configurationDigest, expectedExtractors) {
+        this.queries = queries;
+        this.repository = repository;
+        this.configurationDigest = configurationDigest;
+        this.expectedExtractors = expectedExtractors;
+    }
+    async neighbors(request) {
+        const result = await this.queries.neighbors(request);
+        const evidenceState = await inspectSavedEvidence(result.snapshot, this.repository, this.configurationDigest, this.expectedExtractors);
+        const withState = { ...result, evidenceState };
+        return { ...withState, markdown: renderGraphNeighborhood(withState) };
+    }
+}