@weftlet/toolkit 0.2.1 → 0.3.0

package/README.md

@@ -67,6 +67,71 @@ the archive-byte, snapshot replacement and MCP startup regression suite also pas
 Windows CI. Full native Windows release preparation remains separately unvalidated.
 See the [validation record](docs/VALIDATION.md).
 
+## Preview hydration before model work
+
+`hydrate --plan` requires toolkit **0.3.0 or newer**. Releases through 0.2.1 do not support
+this flag. With a supporting version installed, inspect a project's committed inputs:
+
+```sh
+pnpm exec weftlet hydrate --plan --config /path/to/project/context-graph.config.json --ref HEAD
+pnpm exec weftlet hydrate --plan --json --config /path/to/project/context-graph.config.json --ref HEAD
+```
+
+The human summary and JSON identify the resolved commit, current local configuration, selected
+documents and inclusion reasons, UTF-8 byte sizes, source approval, expected cache reuse and
+extraction counts, budget violations, and working changes excluded from the committed input.
+Selection uses configured repository file/directory paths; `approvedIntentSources` uses its
+separate glob matcher. An explicit empty semantic source list selects no documents, fixing the
+earlier accidental expansion to the whole repository.
+
+Planning reads Git objects and existing artifacts without loading a model provider or repository
+adapter, indexing code, collecting runtime evidence, validating the graph or writing snapshots.
+It does not check credentials or estimate tokens or dollars. Cache hits depend on unchanged
+inputs; corrupt or unreadable entries are reported separately from misses. `--force-semantic`
+shows planned re-extraction without allocating or writing a forced revision.
+
+A plan exits 0 when its source/cache/budget checks are ready. It exits 1 with the full plan when
+errors block those checks or incomplete selection needs review. Missing/no-document selectors
+and existing agent-selection limits are warnings; they do not add a new hydration gate that
+would prevent removing the last document and invalidating its relationships. All selected
+documents remain visible when budgets are exceeded.
+
+Source approval does not approve model assertions. Validation-document labels reflect configured
+evidence roots; selected validation documents still undergo semantic extraction today. Recursive
+SOT traversal and default validation-document separation remain T07 work. See
+[ADR 016](docs/ADR-016-hydration-preview.md) and the [1.0 task list](docs/RELEASE-1.0-PLAN.md).
+
+## SHACL validation and performance
+
+Starting with 0.3.0, the toolkit indexes a temporary union to accelerate cold validation.
+The toolkit uses JavaScript `rdf-validate-shacl` and an in-memory
+N3 store. Each hydration validates the complete graph; semantic artifact reuse does not make
+validation incremental, and there is no validation-result cache, Rust engine or GraphDB service.
+Saved queries do not rerun SHACL.
+
+The current shapes use subject/predicate/object values independently of graph names. Validation
+now builds one temporary union graph so repeated property lookups avoid scanning every named
+assertion graph. The same shapes and validator run against that union. The original named dataset,
+assertion records and provenance remain the source for SPARQL, queries and serialization.
+
+In bounded, single-run public experiments, 2,000 facts with unique subject/object nodes took
+31.50 seconds in the original SHACL path, compared with 0.153 seconds to build the union and
+0.467 seconds for SHACL on that union. A 10,000-fact union case used about 1.3 GiB process RSS;
+the extra projection has a memory cost. These measurements do not reproduce the private consumer's
+full generation run or guarantee a production duration. See [ADR 017](docs/ADR-017-shacl-validation-union.md)
+for methodology, parity boundaries and remaining work. To run the bounded public benchmark from
+a development checkout:
+
+```sh
+pnpm build
+pnpm benchmark:shacl
+```
+
+Current hydration progress reports phase boundaries. The validator performs synchronous work,
+so an ordinary timer cannot provide an honest heartbeat while that work blocks Node's main
+thread. Worker-based progress, early identity checks, validation-result reuse and incremental
+validation remain separate T05 work; they do not delay the focused cold-validation release.
+
 ## Development
 
 The development source is organized by responsibility; see

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

@@ -7,12 +7,14 @@ export interface AgentSemanticScope {
     readonly semanticSources: readonly string[];
     readonly headName: string;
     readonly snapshotSuffix: string;
+    readonly omittedDocuments?: readonly string[];
+    readonly ignoredSearchTerms?: number;
 }
 export declare class AgentSemanticScopeResolver {
     private readonly config;
     private readonly repository;
     constructor(config: ContextGraphConfig, repository: GitRepository);
-    resolve(request: ImpactScanRequest): Promise<AgentSemanticScope>;
+    resolve(request: ImpactScanRequest, ref?: string): Promise<AgentSemanticScope>;
 }
 export declare class PreparedImpactQueryService implements ImpactQueryService {
     private readonly store;

package/dist/application/agent-context.js

@@ -16,13 +16,15 @@ export class AgentSemanticScopeResolver {
         this.config = config;
         this.repository = repository;
     }
-    async resolve(request) {
+    async resolve(request, ref = 'HEAD') {
         const agent = this.config.agentContext;
         if (!agent)
             throw new Error('Agent context preparation is not configured');
-        const commitSha = await this.repository.resolveRef('HEAD');
+        const commitSha = await this.repository.resolveRef(ref);
         const available = new Set((await this.repository.listFilesAt(commitSha, this.config.semanticSources)).filter((path) => /\.(?:md|mdx|txt)$/i.test(path)));
         const selected = new Set();
+        const omitted = new Set();
+        let ignoredSearchTerms = 0;
         for (const path of await this.repository.listFilesAt(commitSha, agent.alwaysSemanticSources)) {
             if (available.has(path))
                 selected.add(path);
@@ -42,6 +44,8 @@ export class AgentSemanticScopeResolver {
                     .filter((path) => available.has(path));
                 for (const path of references.slice(0, agent.maxReferencedDocuments))
                     selected.add(path);
+                for (const path of references.slice(agent.maxReferencedDocuments))
+                    omitted.add(path);
             }
             if (agent.includeMatchingEvidence) {
                 const ownerSlug = basename(ownerDocument).replace(/\.md$/i, '');
@@ -51,16 +55,19 @@ export class AgentSemanticScopeResolver {
             }
         }
         else {
-            const terms = [
+            const requestedTerms = [
                 request.task,
                 ...(request.checklistItems ?? []),
                 ...(request.capabilities ?? []),
             ]
-                .filter((term) => Boolean(term))
-                .slice(0, 8);
-            const matches = await this.repository.findTextAt(commitSha, terms, this.config.semanticSources);
+                .filter((term) => Boolean(term));
+            const terms = requestedTerms.slice(0, 8);
+            ignoredSearchTerms = requestedTerms.length - terms.length;
+            const matches = (await this.repository.findTextAt(commitSha, terms, this.config.semanticSources)).filter((match) => available.has(match.path));
             for (const match of matches.slice(0, agent.maxReferencedDocuments))
                 selected.add(match.path);
+            for (const match of matches.slice(agent.maxReferencedDocuments))
+                omitted.add(match.path);
         }
         const semanticSources = [...selected].sort();
         if (semanticSources.length === 0) {
@@ -72,6 +79,8 @@ export class AgentSemanticScopeResolver {
             semanticSources,
             headName: `agent-${scopeDigest}`,
             snapshotSuffix: `agent-${scopeDigest}`,
+            omittedDocuments: [...omitted].filter((path) => !selected.has(path)).sort(),
+            ignoredSearchTerms,
         };
     }
 }

package/dist/application/hydration-plan.d.ts

@@ -0,0 +1,57 @@
+import type { ImpactScanRequest } from '@weftlet/core';
+import { type SemanticCacheInspection } from '../extraction/semantic-cache.js';
+import { type SemanticInputIssue, type SemanticSelection } from '../extraction/semantic-sources.js';
+export interface HydrationPlanOptions {
+    readonly ref?: string;
+    readonly forceSemantic?: boolean;
+    readonly request?: ImpactScanRequest;
+}
+export interface HydrationPlanDocument {
+    readonly path: string;
+    readonly stableSemanticId: string;
+    readonly sourceDigest: string;
+    readonly bytes: number;
+    readonly lines: number;
+    readonly selectedBy: readonly string[];
+    readonly role: 'semantic-document' | 'validation-evidence';
+    readonly sourceAuthority: 'declared' | 'inferred';
+    readonly approvedBy: readonly string[];
+    readonly extractionReview: 'unreviewed';
+    readonly cache: Omit<SemanticCacheInspection, 'artifact'>;
+}
+export interface HydrationPlan {
+    readonly schemaVersion: 1;
+    readonly kind: 'hydration-plan';
+    readonly repositoryId: string;
+    readonly ref: string;
+    readonly commitSha: string;
+    readonly configurationDigest: string;
+    readonly ready: boolean;
+    readonly scope: {
+        readonly mode: 'configured' | 'agent';
+        readonly selectors: readonly string[];
+        readonly digest: string;
+        readonly headName: string;
+        readonly complete: boolean;
+        readonly omittedDocuments: readonly string[];
+        readonly ignoredSearchTerms: number;
+    };
+    readonly documents: readonly HydrationPlanDocument[];
+    readonly selections: readonly SemanticSelection[];
+    readonly budgets: {
+        readonly maxDocuments: number;
+        readonly maxSourceBytes: number;
+        readonly selectedDocuments: number;
+        readonly totalSourceBytes: number;
+    };
+    readonly estimates: {
+        readonly reusableArtifacts: number;
+        readonly extractions: number;
+        readonly unknownArtifacts: number;
+    };
+    readonly issues: readonly SemanticInputIssue[];
+    readonly excludedWorkingChanges: readonly string[];
+    readonly assumptions: readonly string[];
+}
+/** Inspect only committed source objects, config and existing artifacts; never initialize a provider or adapter. */
+export declare function planHydration(configPath: string, options?: HydrationPlanOptions): Promise<HydrationPlan>;

package/dist/application/hydration-plan.js

@@ -0,0 +1,79 @@
+import { loadConfig } from '../configuration/config.js';
+import { resolveStorageRoot } from '../configuration/cache.js';
+import { GitRepository } from '../repository/git.js';
+import { matchesRepositoryGlob } from '../repository/glob.js';
+import { SemanticArtifactStore } from '../storage/storage.js';
+import { inspectSemanticCache } from '../extraction/semantic-cache.js';
+import { semanticProviderIdentity } from '../extraction/semantic-identity.js';
+import { selectSemanticInputs } from '../extraction/semantic-sources.js';
+import { sha256, stableJson } from '../infrastructure/util.js';
+import { AgentSemanticScopeResolver } from './agent-context.js';
+async function describeDocument(source, selections, config, evidencePaths, store, forceSemantic = false) {
+    const inspection = forceSemantic
+        ? { status: 'forced', reason: 'Explicit force bypasses existing artifacts; a new revision is allocated only during hydration.' }
+        : await inspectSemanticCache(store, config.semantic, source, semanticProviderIdentity(config.semantic));
+    const { artifact: _artifact, ...cache } = inspection;
+    const approvedBy = (config.approvedIntentSources ?? []).filter((pattern) => matchesRepositoryGlob(source.path, pattern));
+    return { path: source.path, stableSemanticId: source.stableSemanticId, sourceDigest: source.digest,
+        bytes: Buffer.byteLength(source.content), lines: source.content.split('\n').length,
+        selectedBy: selections.filter((item) => item.paths.includes(source.path)).map((item) => item.selector),
+        role: evidencePaths.has(source.path) ? 'validation-evidence' : 'semantic-document',
+        sourceAuthority: approvedBy.length ? 'declared' : 'inferred', approvedBy,
+        extractionReview: 'unreviewed', cache };
+}
+async function resolvePlanningScope(config, repository, commitSha, request = {}) {
+    const agent = config.agentContext
+        ? await new AgentSemanticScopeResolver(config, repository).resolve(request, commitSha)
+        : undefined;
+    const selectors = agent?.semanticSources ?? config.semanticSources;
+    return { mode: agent ? 'agent' : 'configured', selectors, digest: sha256(stableJson(selectors)),
+        headName: agent?.headName ?? 'default', omittedDocuments: agent?.omittedDocuments ?? [],
+        ignoredSearchTerms: agent?.ignoredSearchTerms ?? 0 };
+}
+/** Inspect only committed source objects, config and existing artifacts; never initialize a provider or adapter. */
+export async function planHydration(configPath, options = {}) {
+    const { config, repositoryRoot } = await loadConfig(configPath);
+    const repository = new GitRepository(repositoryRoot);
+    const ref = options.ref ?? 'HEAD';
+    const commitSha = await repository.resolveRef(ref);
+    const scope = await resolvePlanningScope(config, repository, commitSha, options.request);
+    const selection = await selectSemanticInputs(repository, commitSha, scope.selectors, config.semantic);
+    const issues = [...selection.issues];
+    const { omittedDocuments, ignoredSearchTerms } = scope;
+    const limited = omittedDocuments.length > 0 || ignoredSearchTerms > 0;
+    const complete = !limited && selection.selections.every((item) => item.status === 'matched');
+    if (limited)
+        issues.push({ code: 'selection-limited', severity: 'warning',
+            message: `Existing agent selection limits omitted ${omittedDocuments.length} documents and ${ignoredSearchTerms} search terms; this plan describes only the selected scope.`,
+            paths: omittedDocuments });
+    const store = new SemanticArtifactStore(resolveStorageRoot(repositoryRoot, config));
+    const evidencePaths = new Set(await repository.listFilesAt(commitSha, config.evidenceRoots));
+    const documents = [];
+    for (const source of selection.sources) {
+        const document = await describeDocument(source, selection.selections, config, evidencePaths, store, options.forceSemantic);
+        const { cache } = document;
+        if (cache.status === 'corrupt' || cache.status === 'unavailable')
+            issues.push({
+                code: `cache-${cache.status}`, severity: 'error', message: cache.reason, paths: [source.path],
+            });
+        documents.push(document);
+    }
+    const count = (...states) => documents.filter((doc) => states.includes(doc.cache.status)).length;
+    return {
+        schemaVersion: 1, kind: 'hydration-plan', repositoryId: config.repositoryId, ref, commitSha,
+        configurationDigest: sha256(stableJson(config)), ready: complete && !issues.some((item) => item.severity === 'error'),
+        scope: { ...scope, complete },
+        documents, selections: selection.selections, budgets: selection.budgets,
+        estimates: { reusableArtifacts: count('hit'), extractions: count('miss', 'forced'), unknownArtifacts: count('corrupt', 'unavailable') },
+        issues, excludedWorkingChanges: await repository.workingChanges(),
+        assumptions: [
+            'Sources come from the resolved commit; configuration and cache are read from the current local environment.',
+            'Estimates require unchanged source, configuration, provider contract and readable artifacts; concurrent changes can invalidate them.',
+            'Document and per-document UTF-8 byte limits apply to all selected documents, including cache hits; no token or monetary estimate is made.',
+            'Ready describes semantic inputs and readable cache only. Providers, credentials, adapters, storage writes, indexing, runtime evidence, routing, ontology and graph validation have not been checked.',
+            'Roles reflect configured evidence roots, not inferred prose meaning. Selected validation documents still undergo semantic extraction today; source approval never approves extracted assertions.',
+            'Selection is the configured scope, optionally narrowed by existing bounded agent selection; recursive SOT traversal and complete product coverage are not claimed.',
+            'Unmatched selectors and bounded scope omissions need review. They do not introduce new hydration gates: removing the last document can still publish a graph with its relationships removed.',
+        ],
+    };
+}

package/dist/application/hydrator.js

@@ -4,6 +4,7 @@ import { repositoryFileExtractorIdentity } from '../extraction/static.js';
 import { sha256, stableJson } from "../infrastructure/util.js";
 import { documentLinkerIdentity, linkSemanticDocuments } from "../extraction/document.js";
 import { repositoryNodeIdentityVersion } from '../extraction/repository-nodes.js';
+import { selectSemanticInputs } from '../extraction/semantic-sources.js';
 import { runtimeEvidenceFacts } from "../extraction/runtime-evidence.js";
 import { matchesRepositoryGlob } from "../repository/glob.js";
 import { RdfEvidenceGraph } from "../graph/rdf.js";
@@ -62,12 +63,17 @@ export class ContextGraphHydrator {
         const commitSha = await repository.resolveRef(options.ref);
         if (options.requireClean === true)
             await repository.requireExactCleanCommit(commitSha);
+        const selectedSemanticSources = options.semanticSources ?? config.semanticSources;
+        const selection = await selectSemanticInputs(repository, commitSha, selectedSemanticSources, config.semantic);
+        if (selection.issues.some((issue) => issue.severity === 'error')) {
+            throw new Error(selection.issues.map((issue) => issue.message).join('\n'));
+        }
+        const { sources } = selection;
         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,
@@ -93,7 +99,7 @@ export class ContextGraphHydrator {
             : undefined;
         const configurationDigest = sha256(stableJson(config));
         const scopeDigest = sha256(stableJson(selectedSemanticSources)).slice(0, 12);
-        const effectiveSuffix = ['graph-v5', `links-${documentLinkerIdentity.version}`, `files-${repositoryFileExtractorIdentity.version}`,
+        const effectiveSuffix = ['graph-v6', `links-${documentLinkerIdentity.version}`, `files-${repositoryFileExtractorIdentity.version}`,
             ...(config.routingSources?.length ? [`routes-${routingExtractorIdentity.version}`] : []),
             configurationDigest.slice(0, 16), scopeDigest, baseSuffix, runtimeSuffix].filter(Boolean).join('-');
         const snapshotId = effectiveSuffix ? `${commitSha}-${effectiveSuffix}` : commitSha;
@@ -111,18 +117,6 @@ export class ContextGraphHydrator {
         };
         // Validate committed routing inputs before invoking any provider or indexer.
         const routing = await extractRoutingDeclarations(repository, context, config.routingSources ?? []);
-        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();
@@ -236,7 +230,7 @@ export class ContextGraphHydrator {
                 scope: selectedSemanticSources,
                 ontologyVersion: config.semantic.ontologyVersion,
                 extractorVersions: {
-                    assembly: 'standalone-graph-v5',
+                    assembly: 'standalone-graph-v6',
                     'repository-node-identity': String(repositoryNodeIdentityVersion),
                     [documentLinkerIdentity.id]: documentLinkerIdentity.version,
                     ...(config.routingSources?.length ? { [routingExtractorIdentity.id]: routingExtractorIdentity.version } : {}),

package/dist/extraction/providers.js

@@ -1,12 +1,12 @@
 import { CodexCliSemanticExtractor, SemanticProviderError } from "./semantic.js";
-import { sha256, stableJson } from "../infrastructure/util.js";
+import { semanticProviderIdentity } from './semantic-identity.js';
 import { resolveConsumerModule } from "../infrastructure/module-resolution.js";
 /** Lazy loading ensures a missing provider cannot disable saved-evidence queries. */
 export function createSemanticExtractor(config, repositoryRoot) {
     if (config.provider === 'codex-cli')
         return new CodexCliSemanticExtractor(config);
     const modulePath = config.providerModule;
-    const identity = `${config.providerIdentity}:${sha256(stableJson(config))}:contract-v2`;
+    const identity = semanticProviderIdentity(config);
     let extractor;
     return {
         identity,

package/dist/extraction/semantic-cache.d.ts

@@ -0,0 +1,12 @@
+import type { SemanticArtifact, SemanticSource } from '@weftlet/core';
+import type { ContextGraphConfig } from '../configuration/config.js';
+import type { SemanticArtifactStore } from '../storage/storage.js';
+export type SemanticCacheStatus = 'hit' | 'miss' | 'forced' | 'corrupt' | 'unavailable';
+export interface SemanticCacheInspection {
+    readonly status: SemanticCacheStatus;
+    readonly key?: string;
+    readonly reason: string;
+    readonly artifact?: SemanticArtifact;
+}
+/** Read-only; a broken artifact is not an extraction miss or permission to overwrite evidence. */
+export declare function inspectSemanticCache(store: SemanticArtifactStore, config: ContextGraphConfig['semantic'], source: SemanticSource, modelIdentity: string, forceRevision?: string): Promise<SemanticCacheInspection>;

package/dist/extraction/semantic-cache.js

@@ -0,0 +1,59 @@
+import { semanticArtifactKey, semanticArtifactOutputDigest } from './semantic-identity.js';
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function strings(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+function matchesIdentity(value, key, source, config, modelIdentity) {
+    return value.key === key && value.stableSemanticId === source.stableSemanticId &&
+        value.sourceDigest === source.digest && value.modelIdentity === modelIdentity &&
+        ['promptVersion', 'extractorVersion', 'adapterVersion', 'ontologyVersion'].every((field) => value[field] === config[field]);
+}
+function reusableArtifact(value, key, source, config, modelIdentity) {
+    if (!record(value) || !matchesIdentity(value, key, source, config, modelIdentity) ||
+        !record(value.source) || value.source.digest !== source.digest ||
+        typeof value.source.path !== 'string' || typeof value.source.commitSha !== 'string' ||
+        !Array.isArray(value.facts) || !Array.isArray(value.diagnostics) || !strings(value.unresolvedMappings) ||
+        typeof value.oml !== 'string' || typeof value.rawModelOutput !== 'string' ||
+        typeof value.outputDigest !== 'string')
+        return false;
+    const lineCount = source.content.split('\n').length;
+    const span = (item) => record(item) && typeof item.path === 'string' &&
+        item.digest === source.digest && typeof item.commitSha === 'string' &&
+        Number.isInteger(item.startLine) && Number.isInteger(item.endLine) &&
+        Number(item.startLine) >= 1 && Number(item.endLine) >= Number(item.startLine) && Number(item.endLine) <= lineCount;
+    const node = (item) => record(item) && typeof item.id === 'string' && item.id.length > 0 &&
+        typeof item.kind === 'string' && typeof item.label === 'string';
+    if (!span(value.source) || !value.facts.every((fact) => record(fact) && typeof fact.id === 'string' &&
+        node(fact.subject) && node(fact.object) && typeof fact.predicate === 'string' && span(fact.provenance) &&
+        record(fact.extractor) && fact.extractor.id === modelIdentity && fact.extractor.version === config.extractorVersion &&
+        typeof fact.confidence === 'number' && fact.confidence >= config.minimumConfidence && fact.confidence <= 1))
+        return false;
+    if (!value.diagnostics.every((item) => record(item) && typeof item.id === 'string' &&
+        typeof item.kind === 'string' && typeof item.reason === 'string' && strings(item.relatedNodeIds) &&
+        Array.isArray(item.provenance) && item.provenance.length > 0 && item.provenance.every(span)))
+        return false;
+    if (config.failOnUnresolved && (value.unresolvedMappings.length || value.diagnostics.length))
+        return false;
+    return semanticArtifactOutputDigest(value) === value.outputDigest;
+}
+/** Read-only; a broken artifact is not an extraction miss or permission to overwrite evidence. */
+export async function inspectSemanticCache(store, config, source, modelIdentity, forceRevision) {
+    const key = semanticArtifactKey(config, source, modelIdentity, forceRevision);
+    let value;
+    try {
+        value = await store.read(key);
+    }
+    catch (error) {
+        return error instanceof SyntaxError
+            ? { status: 'corrupt', key, reason: 'Cached artifact is not valid JSON; retain it for diagnosis or use an explicit forced refresh.' }
+            : { status: 'unavailable', key, reason: 'Cached artifact could not be read; check local storage access before hydrating.' };
+    }
+    if (value === undefined)
+        return { status: 'miss', key, reason: 'No artifact exists for the current source and extraction contract.' };
+    if (!reusableArtifact(value, key, source, config, modelIdentity)) {
+        return { status: 'corrupt', key, reason: 'Cached artifact identity, structure or content digest is invalid; retain it for diagnosis or use an explicit forced refresh.' };
+    }
+    return { status: 'hit', key, reason: 'Readable artifact matches the source and extraction contract; reuse remains subject to unchanged inputs.', artifact: value };
+}

package/dist/extraction/semantic-identity.d.ts

@@ -0,0 +1,7 @@
+import type { SemanticArtifact, SemanticSource } from '@weftlet/core';
+import type { ContextGraphConfig } from '../configuration/config.js';
+/** Pure identity: inspecting planned work must not load providers or probe credentials. */
+export declare function semanticProviderIdentity(config: ContextGraphConfig['semantic']): string;
+/** Preserve the 0.2.1 artifact contract, including identity-policy invalidation. */
+export declare function semanticArtifactKey(config: ContextGraphConfig['semantic'], source: SemanticSource, modelIdentity: string, forceRevision?: string): string;
+export declare function semanticArtifactOutputDigest(artifact: Pick<SemanticArtifact, 'facts' | 'diagnostics' | 'oml' | 'rawModelOutput'>): string;

package/dist/extraction/semantic-identity.js

@@ -0,0 +1,29 @@
+import { sha256, stableJson } from '../infrastructure/util.js';
+import { repositoryNodeIdentityVersion } from './repository-nodes.js';
+/** Pure identity: inspecting planned work must not load providers or probe credentials. */
+export function semanticProviderIdentity(config) {
+    return config.provider === 'codex-cli'
+        ? `codex-cli:${config.model}:${config.reasoningEffort}:${config.promptVersion}:contract-v3`
+        : `${config.providerIdentity}:${sha256(stableJson(config))}:contract-v2`;
+}
+/** Preserve the 0.2.1 artifact contract, including identity-policy invalidation. */
+export function semanticArtifactKey(config, source, modelIdentity, forceRevision) {
+    return sha256(stableJson({
+        stableSemanticId: source.stableSemanticId,
+        sourceDigest: source.digest,
+        promptVersion: config.promptVersion,
+        extractorVersion: config.extractorVersion,
+        modelIdentity,
+        adapterVersion: config.adapterVersion,
+        ontologyVersion: config.ontologyVersion,
+        minimumConfidence: config.minimumConfidence,
+        failOnUnresolved: config.failOnUnresolved,
+        forceRevision,
+        diagnosticContractVersion: 3,
+        repositoryNodeIdentityVersion,
+    }));
+}
+export function semanticArtifactOutputDigest(artifact) {
+    return sha256(stableJson({ facts: artifact.facts, diagnostics: artifact.diagnostics ?? [],
+        compiledOml: artifact.oml, rawModelOutput: artifact.rawModelOutput }));
+}

package/dist/extraction/semantic-sources.d.ts

@@ -0,0 +1,27 @@
+import type { SemanticSource } from '@weftlet/core';
+import type { ContextGraphConfig } from '../configuration/config.js';
+import type { GitRepository } from '../repository/git.js';
+export interface SemanticSelection {
+    readonly selector: string;
+    readonly paths: readonly string[];
+    readonly excludedPaths: readonly string[];
+    readonly status: 'matched' | 'no-documents' | 'missing';
+}
+export interface SemanticInputIssue {
+    readonly code: string;
+    readonly severity: 'error' | 'warning';
+    readonly message: string;
+    readonly paths: readonly string[];
+}
+/** Git path selection, source bytes and limits are shared by preview and execution. */
+export declare function selectSemanticInputs(repository: GitRepository, commitSha: string, selectors: readonly string[], config: ContextGraphConfig['semantic']): Promise<{
+    sources: readonly SemanticSource[];
+    selections: SemanticSelection[];
+    budgets: {
+        maxDocuments: number;
+        maxSourceBytes: number;
+        selectedDocuments: number;
+        totalSourceBytes: number;
+    };
+    issues: SemanticInputIssue[];
+}>;

package/dist/extraction/semantic-sources.js

@@ -0,0 +1,35 @@
+/** Git path selection, source bytes and limits are shared by preview and execution. */
+export async function selectSemanticInputs(repository, commitSha, selectors, config) {
+    const selections = [];
+    for (const selector of [...new Set(selectors)]) {
+        const files = await repository.listFilesAt(commitSha, [selector]);
+        const paths = files.filter((path) => /\.(?:md|mdx|txt)$/i.test(path));
+        selections.push({ selector, paths, excludedPaths: files.filter((path) => !paths.includes(path)),
+            status: paths.length ? 'matched' : files.length ? 'no-documents' : 'missing' });
+    }
+    const sources = await repository.semanticSources({ commitSha }, selectors);
+    const budgets = { maxDocuments: config.maxDocuments ?? 8, maxSourceBytes: config.maxSourceBytes ?? 65_536,
+        selectedDocuments: sources.length, totalSourceBytes: sources.reduce((sum, source) => sum + Buffer.byteLength(source.content), 0) };
+    const issues = selections.filter((item) => item.status !== 'matched').map((item) => ({
+        code: item.status === 'missing' ? 'missing-source' : 'unsupported-source', severity: 'warning',
+        message: item.status === 'missing' ? `Semantic selector ${item.selector} matches no committed files.`
+            : `Semantic selector ${item.selector} matches no supported Markdown/text documents.`, paths: [item.selector],
+    }));
+    if (sources.length > budgets.maxDocuments)
+        issues.push({ code: 'document-budget', severity: 'error',
+            message: `Semantic source budget exceeded: ${sources.length} documents exceed maxDocuments ${budgets.maxDocuments}.`,
+            paths: sources.map((source) => source.path) });
+    const oversized = sources.filter((source) => Buffer.byteLength(source.content) > budgets.maxSourceBytes);
+    if (oversized.length)
+        issues.push({ code: 'source-byte-budget', severity: 'error',
+            message: `Semantic source budget exceeded: ${oversized.length} documents exceed the per-document maxSourceBytes ${budgets.maxSourceBytes}.`,
+            paths: oversized.map((source) => source.path) });
+    const byId = new Map();
+    for (const source of sources)
+        byId.set(source.stableSemanticId, [...(byId.get(source.stableSemanticId) ?? []), source.path]);
+    for (const [id, paths] of byId)
+        if (paths.length > 1)
+            issues.push({ code: 'duplicate-semantic-id', severity: 'error',
+                message: `Duplicate stable semantic ID: ${id}`, paths });
+    return { sources, selections, budgets, issues };
+}

package/dist/extraction/semantic.js

@@ -8,7 +8,9 @@ import { resolveCodexInvocation } from './codex-command.js';
 import { runSemanticProcess, SemanticProviderError } from "./semantic-process.js";
 export { SemanticProviderError } from "./semantic-process.js";
 import { sha256, stableJson } from "../infrastructure/util.js";
-import { canonicalizeRepositoryDocumentNode, repositoryNodeIdentityVersion } from './repository-nodes.js';
+import { canonicalizeRepositoryDocumentNode } from './repository-nodes.js';
+import { semanticArtifactKey, semanticArtifactOutputDigest, semanticProviderIdentity } from './semantic-identity.js';
+import { inspectSemanticCache } from './semantic-cache.js';
 import { assertSemanticCitation, numberedSemanticSource, semanticCitationSchema, } from "./semantic-citations.js";
 function canonicalizeRepositoryDocuments(output) {
     const ids = new Map();
@@ -228,7 +230,7 @@ export class CodexCliSemanticExtractor {
         this.config = config;
         this.runner = runner;
         this.loginProbe = loginProbe;
-        this.identity = `codex-cli:${config.model}:${config.reasoningEffort}:${config.promptVersion}:contract-v3`;
+        this.identity = semanticProviderIdentity(config);
     }
     async extract(source, context, options = {}) {
         options.signal?.throwIfAborted();
@@ -333,24 +335,12 @@ export class SemanticHydrator {
     }
     async hydrate(source, context, forceRevision, options = {}) {
         options.signal?.throwIfAborted();
-        const keyInput = {
-            stableSemanticId: source.stableSemanticId,
-            sourceDigest: source.digest,
-            promptVersion: this.config.promptVersion,
-            extractorVersion: this.config.extractorVersion,
-            modelIdentity: this.extractor.identity,
-            adapterVersion: this.config.adapterVersion,
-            ontologyVersion: this.config.ontologyVersion,
-            minimumConfidence: this.config.minimumConfidence,
-            failOnUnresolved: this.config.failOnUnresolved,
-            forceRevision,
-            diagnosticContractVersion: 3,
-            repositoryNodeIdentityVersion,
-        };
-        const key = sha256(stableJson(keyInput));
-        const existing = await this.store.read(key);
-        if (existing)
-            return { artifact: existing, reused: true };
+        const key = semanticArtifactKey(this.config, source, this.extractor.identity, forceRevision);
+        const cached = await inspectSemanticCache(this.store, this.config, source, this.extractor.identity, forceRevision);
+        if (cached.status === 'hit')
+            return { artifact: cached.artifact, reused: true };
+        if (cached.status !== 'miss')
+            throw new Error(cached.reason);
         const extraction = await this.extractor.extract(source, context, options);
         assertSemanticOutput(extraction.parsed, source);
         if (typeof extraction.rawModelOutput !== 'string' || Buffer.byteLength(extraction.rawModelOutput) > 2 * 1024 * 1024) {
@@ -411,7 +401,7 @@ export class SemanticHydrator {
             throw new Error(`Unresolved semantic mappings for ${source.path}: ${[...unresolvedMappings, ...diagnostics.map((item) => item.reason)].join('; ')}`);
         }
         const compiledOml = renderOml(key, output.assertions);
-        const outputDigest = sha256(stableJson({ facts, diagnostics, compiledOml, rawModelOutput: extraction.rawModelOutput }));
+        const outputDigest = semanticArtifactOutputDigest({ facts, diagnostics, oml: compiledOml, rawModelOutput: extraction.rawModelOutput });
         const artifact = {
             key,
             stableSemanticId: source.stableSemanticId,

package/dist/graph/rdf.d.ts

@@ -1,5 +1,5 @@
 import type { GraphFact, GraphSnapshot } from "@weftlet/core";
-export declare const CG = "https://context-graph.dev/record#";
+export { CG } from './shacl-shapes.js';
 export declare const nodeIri: (id: string) => string;
 export declare const factIri: (id: string) => string;
 /** Lossless RDF dataset: one named graph per cited assertion, with provenance in the default graph. */