@weftlet/toolkit 0.0.0-stage → 0.1.0

package/dist/application/agent-context.d.ts

@@ -0,0 +1,23 @@
+import type { ContextGraphConfig } from "../configuration/config.js";
+import type { ImpactQueryService, ImpactScanRequest, SnapshotStore } from "@weftlet/core";
+import type { GitRepository } from "../repository/git.js";
+import type { ContextGraphHydrator } from "./hydrator.js";
+export interface AgentSemanticScope {
+    readonly commitSha: string;
+    readonly semanticSources: readonly string[];
+    readonly headName: string;
+    readonly snapshotSuffix: string;
+}
+export declare class AgentSemanticScopeResolver {
+    private readonly config;
+    private readonly repository;
+    constructor(config: ContextGraphConfig, repository: GitRepository);
+    resolve(request: ImpactScanRequest): Promise<AgentSemanticScope>;
+}
+export declare class PreparedImpactQueryService implements ImpactQueryService {
+    private readonly store;
+    private readonly hydrator;
+    private readonly scopeResolver;
+    constructor(store: SnapshotStore, hydrator: ContextGraphHydrator, scopeResolver: AgentSemanticScopeResolver);
+    scan(request: ImpactScanRequest): Promise<import("@weftlet/core").ContextPack>;
+}

package/dist/application/agent-context.js

@@ -0,0 +1,94 @@
+// Modified for standalone extraction; see docs/extraction-manifest.json.
+import { basename } from 'node:path';
+import { SnapshotImpactQueryService } from "../graph/query.js";
+import { sha256, stableJson } from "../infrastructure/util.js";
+function normalizeRepositoryPath(path) {
+    const normalized = path.replaceAll('\\', '/').replace(/^\.\//, '');
+    if (normalized.startsWith('/') || normalized.split('/').includes('..')) {
+        throw new Error(`ownerDocument must be a repository-relative path: ${path}`);
+    }
+    return normalized;
+}
+export class AgentSemanticScopeResolver {
+    config;
+    repository;
+    constructor(config, repository) {
+        this.config = config;
+        this.repository = repository;
+    }
+    async resolve(request) {
+        const agent = this.config.agentContext;
+        if (!agent)
+            throw new Error('Agent context preparation is not configured');
+        const commitSha = await this.repository.resolveRef('HEAD');
+        const available = new Set((await this.repository.listFilesAt(commitSha, this.config.semanticSources)).filter((path) => /\.(?:md|mdx|txt)$/i.test(path)));
+        const selected = new Set();
+        for (const path of await this.repository.listFilesAt(commitSha, agent.alwaysSemanticSources)) {
+            if (available.has(path))
+                selected.add(path);
+        }
+        const ownerDocument = request.ownerDocument
+            ? normalizeRepositoryPath(request.ownerDocument)
+            : undefined;
+        if (ownerDocument) {
+            if (!available.has(ownerDocument)) {
+                throw new Error(`Owner document is not a configured semantic source: ${ownerDocument}`);
+            }
+            selected.add(ownerDocument);
+            const content = await this.repository.readFileAt(commitSha, ownerDocument);
+            if (agent.followDocumentReferences) {
+                const references = [...content.matchAll(/\bdocs\/[A-Za-z0-9_./-]+\.md\b/g)]
+                    .map((match) => match[0])
+                    .filter((path) => available.has(path));
+                for (const path of references.slice(0, agent.maxReferencedDocuments))
+                    selected.add(path);
+            }
+            if (agent.includeMatchingEvidence) {
+                const ownerSlug = basename(ownerDocument).replace(/\.md$/i, '');
+                for (const path of [...available].filter((path) => this.config.evidenceRoots.some((root) => path === root || path.startsWith(`${root.replace(/\/$/, '')}/`)) && path.includes(ownerSlug))) {
+                    selected.add(path);
+                }
+            }
+        }
+        else {
+            const terms = [
+                request.task,
+                ...(request.checklistItems ?? []),
+                ...(request.capabilities ?? []),
+            ]
+                .filter((term) => Boolean(term))
+                .slice(0, 8);
+            const matches = await this.repository.findTextAt(commitSha, terms, this.config.semanticSources);
+            for (const match of matches.slice(0, agent.maxReferencedDocuments))
+                selected.add(match.path);
+        }
+        const semanticSources = [...selected].sort();
+        if (semanticSources.length === 0) {
+            throw new Error('Agent context scope did not resolve any semantic sources');
+        }
+        const scopeDigest = sha256(stableJson(semanticSources)).slice(0, 16);
+        return {
+            commitSha,
+            semanticSources,
+            headName: `agent-${scopeDigest}`,
+            snapshotSuffix: `agent-${scopeDigest}`,
+        };
+    }
+}
+export class PreparedImpactQueryService {
+    store;
+    hydrator;
+    scopeResolver;
+    constructor(store, hydrator, scopeResolver) {
+        this.store = store;
+        this.hydrator = hydrator;
+        this.scopeResolver = scopeResolver;
+    }
+    async scan(request) {
+        if (request.snapshotId) {
+            return new SnapshotImpactQueryService(this.store, 'default').scan(request);
+        }
+        const scope = await this.scopeResolver.resolve(request);
+        return new SnapshotImpactQueryService(this.store, scope.headName).scan(request);
+    }
+}

package/dist/application/application.d.ts

@@ -0,0 +1,23 @@
+import { SavedEvidenceQueryService } from "./saved-evidence.js";
+import { AgentSemanticScopeResolver } from "./agent-context.js";
+import type { ContextGraphAdapter, ContextGraphRepository } from "@weftlet/core";
+import { GitRepository } from "../repository/git.js";
+import { ContextGraphHydrator } from "./hydrator.js";
+import { OpenCaesarOntologyCompiler, DirectRdfOntologyCompiler } from "../extraction/ontology.js";
+import { FileSnapshotStore } from "../storage/storage.js";
+import { SnapshotChecks } from "./snapshot-checks.js";
+export declare function loadContextGraphAdapterModule(moduleSpecifier: string | undefined, repository: ContextGraphRepository, repositoryRoot?: string): Promise<ContextGraphAdapter>;
+export declare function createContextGraphApplication(configPath: string): Promise<{
+    storageRoot: string;
+    repository: GitRepository;
+    snapshotStore: FileSnapshotStore;
+    ontologyCompiler: OpenCaesarOntologyCompiler | DirectRdfOntologyCompiler;
+    hydrator: ContextGraphHydrator;
+    queryService: SavedEvidenceQueryService;
+    snapshotChecks: SnapshotChecks;
+    scopeResolver: AgentSemanticScopeResolver | undefined;
+    headName: string;
+    config: import("../configuration/config.js").ContextGraphConfig;
+    configPath: string;
+    repositoryRoot: string;
+}>;

package/dist/application/application.js

@@ -0,0 +1,91 @@
+// Modified for standalone extraction; see docs/extraction-manifest.json.
+import { SavedEvidenceQueryService } from "./saved-evidence.js";
+import { sha256, stableJson } from "../infrastructure/util.js";
+import { AgentSemanticScopeResolver, PreparedImpactQueryService } from "./agent-context.js";
+import { resolveStorageRoot } from "../configuration/cache.js";
+import { loadConfig } from "../configuration/config.js";
+import { GitRepository } from "../repository/git.js";
+import { ContextGraphHydrator } from "./hydrator.js";
+import { OpenCaesarOntologyCompiler, DirectRdfOntologyCompiler } from "../extraction/ontology.js";
+import { SnapshotImpactQueryService } from "../graph/query.js";
+import { SemanticHydrator } from "../extraction/semantic.js";
+import { createSemanticExtractor } from "../extraction/providers.js";
+import { SemanticArtifactStore, FileSnapshotStore } from "../storage/storage.js";
+import { RepositoryContractExtractor, RepositoryFileExtractor, ScipSymbolExtractor, ScipTypeScriptIndexer, } from "../extraction/static.js";
+import { OtlpJsonRuntimeEvidenceProvider } from "../extraction/telemetry.js";
+import { SnapshotChecks } from "./snapshot-checks.js";
+import { resolveConsumerModule } from "../infrastructure/module-resolution.js";
+const emptyAdapter = {
+    factExtractors: [],
+    invariantEvaluators: [],
+};
+export async function loadContextGraphAdapterModule(moduleSpecifier, repository, repositoryRoot = process.cwd()) {
+    if (!moduleSpecifier)
+        return emptyAdapter;
+    let candidate;
+    try {
+        candidate = (await import(resolveConsumerModule(moduleSpecifier, repositoryRoot)));
+    }
+    catch (error) {
+        throw new Error(`Unable to load context graph adapter ${moduleSpecifier}`, { cause: error });
+    }
+    if (typeof candidate.createContextGraphAdapter !== 'function') {
+        throw new Error(`Context graph adapter ${moduleSpecifier} must export createContextGraphAdapter(repository)`);
+    }
+    const adapter = candidate.createContextGraphAdapter(repository);
+    if (!Array.isArray(adapter.factExtractors) || !Array.isArray(adapter.invariantEvaluators)) {
+        throw new Error(`Context graph adapter ${moduleSpecifier} returned an invalid adapter`);
+    }
+    return adapter;
+}
+export async function createContextGraphApplication(configPath) {
+    const loaded = await loadConfig(configPath);
+    const { config, repositoryRoot } = loaded;
+    const storageRoot = resolveStorageRoot(repositoryRoot, config);
+    const repository = new GitRepository(repositoryRoot);
+    const adapter = await loadContextGraphAdapterModule(config.adapter, repository, repositoryRoot);
+    const snapshotStore = new FileSnapshotStore(storageRoot);
+    const artifactStore = new SemanticArtifactStore(storageRoot);
+    const semanticExtractor = createSemanticExtractor(config.semantic, repositoryRoot);
+    const semanticHydrator = new SemanticHydrator(config.semantic, artifactStore, semanticExtractor);
+    const staticIndexer = new ScipTypeScriptIndexer(config.scip, storageRoot);
+    const ontologyCompiler = config.ontology.backend === 'opencaesar' ? new OpenCaesarOntologyCompiler(config.ontology, repositoryRoot, storageRoot) : new DirectRdfOntologyCompiler(storageRoot);
+    const runtimeEvidenceProvider = new OtlpJsonRuntimeEvidenceProvider(config.runtimeEvidence, config.runtimeEvidencePolicy);
+    const extractorFactory = (scip) => [
+        new RepositoryFileExtractor(repository, config.codeRoots, scip.digest),
+        new RepositoryContractExtractor(repository, config.contractPatterns, config.contractConsumerRoots ?? config.codeRoots, config.contractAliases),
+        new ScipSymbolExtractor(repository, scip),
+        ...adapter.factExtractors,
+    ];
+    const hydrator = new ContextGraphHydrator({
+        config,
+        repository,
+        snapshotStore,
+        semanticHydrator,
+        staticIndexer,
+        ontologyCompiler,
+        runtimeEvidenceProvider,
+        extractorFactory,
+        invariantEvaluators: adapter.invariantEvaluators,
+    });
+    const headName = 'default';
+    const scopeResolver = config.agentContext
+        ? new AgentSemanticScopeResolver(config, repository)
+        : undefined;
+    const rawQueryService = scopeResolver
+        ? new PreparedImpactQueryService(snapshotStore, hydrator, scopeResolver)
+        : new SnapshotImpactQueryService(snapshotStore, headName);
+    const queryService = new SavedEvidenceQueryService(rawQueryService, repository, sha256(stableJson(config)));
+    return {
+        ...loaded,
+        storageRoot,
+        repository,
+        snapshotStore,
+        ontologyCompiler,
+        hydrator,
+        queryService,
+        snapshotChecks: new SnapshotChecks(snapshotStore, repository, hydrator, scopeResolver, sha256(stableJson(config))),
+        scopeResolver,
+        headName,
+    };
+}

package/dist/application/hydrator.d.ts

@@ -0,0 +1,49 @@
+import type { ContextGraphConfig } from "../configuration/config.js";
+import type { FactExtractor, GraphSnapshot, InvariantEvaluator, RuntimeTraceReference, RuntimeEvidenceProvider, SnapshotStore } from "@weftlet/core";
+import type { GitRepository } from "../repository/git.js";
+import type { OntologyCompiler } from "../extraction/ontology.js";
+import type { SemanticHydrator } from "../extraction/semantic.js";
+import type { ScipIndexResult, StaticIndexer } from "../extraction/static.js";
+export interface HydrationOptions {
+    readonly signal?: AbortSignal;
+    readonly onProgress?: (event: {
+        phase: string;
+        completed?: number;
+        total?: number;
+    }) => void;
+    readonly ref: string;
+    readonly headName: string;
+    readonly forceSemantic?: boolean;
+    readonly snapshotSuffix?: string;
+    readonly requireClean?: boolean;
+    readonly semanticSources?: readonly string[];
+    readonly runtimeEvidenceRevision?: RuntimeEvidenceRevision;
+}
+export interface RuntimeEvidenceRevision {
+    readonly commitSha: string;
+    readonly digest: string;
+    readonly references: readonly RuntimeTraceReference[];
+}
+export interface HydrationResult {
+    readonly snapshot: GraphSnapshot;
+    readonly semanticExtracted: number;
+    readonly semanticReused: number;
+}
+export interface HydratorDependencies {
+    readonly config: ContextGraphConfig;
+    readonly repository: GitRepository;
+    readonly snapshotStore: SnapshotStore;
+    readonly semanticHydrator: SemanticHydrator;
+    readonly staticIndexer: StaticIndexer;
+    readonly ontologyCompiler: OntologyCompiler;
+    readonly runtimeEvidenceProvider: RuntimeEvidenceProvider;
+    readonly extractorFactory: (scip: ScipIndexResult) => readonly FactExtractor[];
+    readonly invariantEvaluators: readonly InvariantEvaluator[];
+}
+export declare class ContextGraphHydrator {
+    private readonly dependencies;
+    constructor(dependencies: HydratorDependencies);
+    collectRuntimeEvidence(commitSha: string): Promise<RuntimeEvidenceRevision>;
+    hydrate(options: HydrationOptions): Promise<HydrationResult>;
+    compareClean(options: Omit<HydrationOptions, 'snapshotSuffix'>): Promise<HydrationResult>;
+}

package/dist/application/hydrator.js

@@ -0,0 +1,275 @@
+import { contractPatternRoots } from "../repository/glob.js";
+import { sha256, stableJson } from "../infrastructure/util.js";
+import { linkSemanticDocuments } from "../extraction/document.js";
+import { runtimeEvidenceFacts } from "../extraction/runtime-evidence.js";
+import { matchesRepositoryGlob } from "../repository/glob.js";
+import { RdfEvidenceGraph } from "../graph/rdf.js";
+async function concurrentMap(values, concurrency, worker) {
+    const results = new Array(values.length);
+    let cursor = 0;
+    let failure;
+    let failed = false;
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(concurrency, values.length)) }, async () => {
+        while (!failed && cursor < values.length) {
+            const index = cursor++;
+            try {
+                results[index] = await worker(values[index], index);
+            }
+            catch (error) {
+                failed = true;
+                failure ??= error;
+            }
+        }
+    }));
+    if (failed)
+        throw failure;
+    return results;
+}
+export class ContextGraphHydrator {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    async collectRuntimeEvidence(commitSha) {
+        const { config, repository } = this.dependencies;
+        const context = {
+            repositoryRoot: repository.root,
+            repositoryId: config.repositoryId,
+            ref: commitSha,
+            commitSha,
+            snapshotId: commitSha,
+            changedPaths: [],
+            deletedPaths: [],
+            renamedPaths: {},
+        };
+        const references = [...(await this.dependencies.runtimeEvidenceProvider.collect(context))]
+            .filter((evidence) => evidence.accepted)
+            .sort((left, right) => stableJson(left).localeCompare(stableJson(right)));
+        return {
+            commitSha,
+            digest: sha256(stableJson(references)),
+            references,
+        };
+    }
+    async hydrate(options) {
+        options.signal?.throwIfAborted();
+        options.onProgress?.({ phase: 'resolve-committed-sources' });
+        const { config, repository, snapshotStore } = this.dependencies;
+        const commitSha = await repository.resolveRef(options.ref);
+        if (options.requireClean === true)
+            await repository.requireExactCleanCommit(commitSha);
+        await this.dependencies.ontologyCompiler.checkReady?.();
+        const prior = await snapshotStore.readHead(options.headName);
+        const baseSha = prior?.manifest.commitSha === commitSha
+            ? prior.manifest.baseSha
+            : (prior?.manifest.commitSha ?? (await repository.firstParent(commitSha)));
+        const selectedSemanticSources = options.semanticSources ?? config.semanticSources;
+        const allRoots = [
+            ...new Set([
+                ...selectedSemanticSources,
+                ...config.codeRoots,
+                ...config.evidenceRoots,
+                ...contractPatternRoots(config.contractPatterns),
+            ]),
+        ];
+        const delta = await repository.delta(baseSha, commitSha, allRoots);
+        const forceRevision = options.forceSemantic
+            ? `${commitSha}:${new Date().toISOString()}:${process.pid}`
+            : undefined;
+        const baseSuffix = options.snapshotSuffix ??
+            (forceRevision ? `semantic-${sha256(forceRevision).slice(0, 12)}` : undefined);
+        const runtimeRevision = options.runtimeEvidenceRevision ?? (await this.collectRuntimeEvidence(commitSha));
+        if (runtimeRevision.commitSha !== commitSha) {
+            throw new Error('Runtime evidence revision does not match the hydration commit');
+        }
+        const runtimeSuffix = config.runtimeEvidence.length > 0
+            ? `runtime-${runtimeRevision.digest.slice(0, 12)}`
+            : undefined;
+        const configurationDigest = sha256(stableJson(config));
+        const scopeDigest = sha256(stableJson(selectedSemanticSources)).slice(0, 12);
+        const effectiveSuffix = ['graph-v2', configurationDigest.slice(0, 16), scopeDigest, baseSuffix, runtimeSuffix].filter(Boolean).join('-');
+        const snapshotId = effectiveSuffix ? `${commitSha}-${effectiveSuffix}` : commitSha;
+        const context = {
+            repositoryRoot: repository.root,
+            repositoryId: config.repositoryId,
+            ref: options.ref,
+            commitSha,
+            baseSha,
+            snapshotId,
+            changedPaths: delta.changedPaths,
+            deletedPaths: delta.deletedPaths,
+            renamedPaths: delta.renamedPaths,
+            semanticPaths: selectedSemanticSources,
+        };
+        const sources = await repository.semanticSources(context, selectedSemanticSources);
+        if (sources.length > (config.semantic.maxDocuments ?? 8) ||
+            sources.some((source) => Buffer.byteLength(source.content) > (config.semantic.maxSourceBytes ?? 65_536))) {
+            throw new Error('Semantic source budget exceeded before extraction; narrow scope or explicitly review configured limits');
+        }
+        const ids = new Set();
+        for (const source of sources) {
+            if (ids.has(source.stableSemanticId)) {
+                throw new Error(`Duplicate stable semantic ID: ${source.stableSemanticId}`);
+            }
+            ids.add(source.stableSemanticId);
+        }
+        let semanticExtracted = 0;
+        let semanticReused = 0;
+        const controller = new AbortController();
+        const signal = AbortSignal.any([controller.signal, ...(options.signal ? [options.signal] : [])]);
+        const hydrated = await concurrentMap(sources, config.semantic.concurrency, async (source) => {
+            let result;
+            try {
+                result = await this.dependencies.semanticHydrator.hydrate(source, context, forceRevision, { signal });
+            }
+            catch (error) {
+                controller.abort();
+                throw error;
+            }
+            if (result.reused)
+                semanticReused += 1;
+            else
+                semanticExtracted += 1;
+            options.onProgress?.({ phase: result.reused ? 'semantic-cache-hit' : 'semantic-extracted',
+                completed: semanticReused + semanticExtracted, total: sources.length });
+            return { source, ...result };
+        });
+        const artifacts = hydrated.map((result) => result.artifact);
+        const diagnostics = hydrated.flatMap(({ source, artifact }) => (artifact.diagnostics ?? []).map((item) => ({
+            ...item,
+            id: sha256(stableJson({ artifact: artifact.key, diagnostic: item.id, path: source.path })),
+            provenance: item.provenance.map((span) => ({
+                ...span,
+                path: source.path,
+                digest: source.digest,
+                commitSha,
+            })),
+        })));
+        const semanticFacts = hydrated.flatMap(({ source, artifact }) => artifact.facts.map((fact) => ({
+            ...fact,
+            id: sha256(stableJson({ artifact: artifact.key, fact: fact.id, path: source.path })),
+            provenance: {
+                ...fact.provenance,
+                path: source.path,
+                digest: source.digest,
+                commitSha,
+            },
+            snapshotId,
+            authority: 'inferred',
+            extractionReview: 'unreviewed',
+            sourceAuthority: (config.approvedIntentSources?.some((pattern) => matchesRepositoryGlob(source.path, pattern)) ? 'declared' : 'inferred'),
+        })));
+        options.signal?.throwIfAborted();
+        options.onProgress?.({ phase: 'index-typescript' });
+        const scip = await this.dependencies.staticIndexer.index(context);
+        const extractorFacts = (await Promise.all(this.dependencies.extractorFactory(scip).map((extractor) => extractor.extract(context)))).flat();
+        const trackedPaths = await repository.listAllFilesAt(commitSha);
+        const tracked = new Set(trackedPaths);
+        for (const fact of semanticFacts) {
+            for (const node of [fact.subject, fact.object]) {
+                const path = node.id.startsWith('component:file:') ? node.id.slice('component:file:'.length) : undefined;
+                if (path && !tracked.has(path))
+                    diagnostics.push({
+                        id: sha256(stableJson({ fact: fact.id, missing: path })),
+                        kind: 'implementationGaps',
+                        reason: `Cited implementation path ${path} is absent from the committed repository.`,
+                        relatedNodeIds: [node.id], provenance: [fact.provenance], evidenceScope: 'snapshot-query',
+                    });
+            }
+        }
+        const documentFacts = linkSemanticDocuments(context, hydrated, trackedPaths);
+        options.signal?.throwIfAborted();
+        options.onProgress?.({ phase: 'compile-semantic-rdf' });
+        const ontology = await this.dependencies.ontologyCompiler.compile(snapshotId, artifacts, context);
+        const runtimeEvidence = runtimeRevision.references;
+        const runtimeFacts = runtimeEvidenceFacts(context, runtimeEvidence);
+        const facts = [...semanticFacts, ...documentFacts, ...extractorFacts, ...runtimeFacts].sort((left, right) => left.id.localeCompare(right.id));
+        const invariants = (await Promise.all(this.dependencies.invariantEvaluators.map((evaluator) => evaluator.evaluate(snapshotId, facts)))).flat();
+        const failures = invariants.filter((invariant) => invariant.status === 'fail');
+        if (failures.length > 0) {
+            throw new Error(`Invariant validation failed: ${failures.map((failure) => failure.invariantId).join(', ')}`);
+        }
+        const unresolved = [
+            ...new Set([
+                ...artifacts.flatMap((artifact) => artifact.unresolvedMappings),
+                ...invariants
+                    .filter((invariant) => invariant.status === 'unknown')
+                    .map((invariant) => invariant.message),
+            ]),
+        ].sort();
+        const logical = {
+            repositoryId: config.repositoryId,
+            commitSha,
+            ontologyVersion: config.semantic.ontologyVersion,
+            semanticArtifactKeys: artifacts.map((artifact) => artifact.key).sort(),
+            scipIndexDigest: scip.digest,
+            rdfDigest: ontology.digest,
+            facts: facts.map(({ snapshotId: _snapshotId, ...fact }) => fact),
+            invariants,
+            runtimeEvidence,
+            unresolved,
+            diagnostics,
+            semanticSources: selectedSemanticSources,
+        };
+        const contentDigest = sha256(stableJson(logical));
+        const snapshot = {
+            manifest: {
+                schemaVersion: 1,
+                repositoryId: config.repositoryId,
+                ref: options.ref,
+                commitSha,
+                baseSha,
+                snapshotId,
+                configurationDigest,
+                scope: selectedSemanticSources,
+                ontologyVersion: config.semantic.ontologyVersion,
+                extractorVersions: {
+                    assembly: 'standalone-graph-v2',
+                    semantic: config.semantic.extractorVersion,
+                    scip: scip.version,
+                    ontology: config.ontology.toolVersion,
+                    ...Object.fromEntries(this.dependencies
+                        .extractorFactory(scip)
+                        .map((extractor) => [extractor.identity.id, extractor.identity.version])),
+                },
+                semanticModel: config.semantic.model,
+                semanticPromptVersion: config.semantic.promptVersion,
+                generatedAt: new Date().toISOString(),
+                contentDigest,
+                runtimeEvidenceDigest: runtimeRevision.digest,
+                semanticArtifactKeys: artifacts.map((artifact) => artifact.key).sort(),
+                scipIndexDigest: scip.digest,
+                rdfDigest: ontology.digest,
+            },
+            facts,
+            invariants,
+            runtimeEvidence,
+            unresolved,
+            diagnostics,
+        };
+        options.signal?.throwIfAborted();
+        options.onProgress?.({ phase: 'validate-shacl' });
+        const validation = await new RdfEvidenceGraph(snapshot).validate();
+        if (!validation.conforms) {
+            throw new Error(`Graph extraction failed SHACL validation: ${JSON.stringify(validation.issues)}`);
+        }
+        options.onProgress?.({ phase: 'publish-snapshot' });
+        await snapshotStore.write(snapshot);
+        await snapshotStore.updateHead(options.headName, snapshotId);
+        return { snapshot, semanticExtracted, semanticReused };
+    }
+    async compareClean(options) {
+        const current = await this.dependencies.snapshotStore.readHead(options.headName);
+        if (!current)
+            throw new Error('No incremental snapshot exists to compare');
+        const clean = await this.hydrate({
+            ...options,
+            headName: `${options.headName}-clean`,
+            snapshotSuffix: `clean-${Date.now()}`,
+        });
+        if (clean.snapshot.manifest.contentDigest !== current.manifest.contentDigest) {
+            throw new Error(`Clean hydration drift: ${current.manifest.contentDigest} != ${clean.snapshot.manifest.contentDigest}`);
+        }
+        return clean;
+    }
+}

package/dist/application/overlay.d.ts

@@ -0,0 +1,6 @@
+import type { ContextGraphConfig } from "../configuration/config.js";
+import type { GraphSnapshot } from "@weftlet/core";
+import { GitRepository } from "../repository/git.js";
+import { FileSnapshotStore } from "../storage/storage.js";
+/** Conservative code overlay: reindex implementation; invalidate changed prose, never synthesize intent. */
+export declare function buildWorkingOverlay(repository: GitRepository, config: ContextGraphConfig, store: FileSnapshotStore, storageRoot: string, baseSnapshotId: string, agent?: string): Promise<GraphSnapshot>;