@weftlet/toolkit 0.3.0 → 0.5.0

package/dist/extraction/repository-nodes.js

@@ -1,20 +1,14 @@
+import { repositoryFileNode } from '@weftlet/core';
+export { repositoryFileNode } from '@weftlet/core';
 /** Internal cache contract: changing this policy must also change snapshot assembly identity. */
 export const repositoryNodeIdentityVersion = 1;
-function isDocumentPath(path) {
-    return /\.(?:md|mdx|txt)$/i.test(path);
-}
-/** Physical file identity; this does not establish existence, intent, ownership or approval. */
-export function repositoryFileNode(path) {
-    if (isDocumentPath(path))
-        return { id: `document:${path}`, kind: 'Document', label: path };
-    return { id: `component:file:${path}`, label: path,
-        kind: /\.(spec|test)\.[^.]+$/i.test(path) ? 'Evidence' : 'Component' };
-}
 /** Normalize only reserved document/file identities, never inferred business concept IDs. */
 export function canonicalizeRepositoryDocumentNode(node) {
     const match = /^(?:component:file:|document:)(.+)$/.exec(node.id);
-    if (!match || !isDocumentPath(match[1]))
+    if (!match)
         return node;
     const canonical = repositoryFileNode(match[1]);
+    if (canonical.kind !== 'Document')
+        return node;
     return { ...node, id: canonical.id, kind: canonical.kind };
 }

package/dist/extraction/routing.d.ts

@@ -2,7 +2,7 @@ import type { ExtractionContext, GraphDiagnostic, GraphFact } from '@weftlet/cor
 import type { GitRepository } from '../repository/git.js';
 export declare const routingExtractorIdentity: {
     readonly id: "routing-declaration-extractor";
-    readonly version: "1.0.0";
+    readonly version: "1.1.0";
 };
 /** Reads explicit mapping declarations, never infers routing from matching topic text. */
 export declare function extractRoutingDeclarations(repository: GitRepository, context: ExtractionContext, paths: readonly string[], options?: {

package/dist/extraction/routing.js

@@ -1,6 +1,7 @@
 import { posix } from 'node:path';
+import { repositoryFileNode as fileNode } from '@weftlet/core';
 import { sha256, stableJson } from '../infrastructure/util.js';
-export const routingExtractorIdentity = { id: 'routing-declaration-extractor', version: '1.0.0' };
+export const routingExtractorIdentity = { id: 'routing-declaration-extractor', version: '1.1.0' };
 function record(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -61,10 +62,6 @@ function parseRoutes(content, path) {
             producer: route.producer, consumer: route.consumer };
     });
 }
-function fileNode(path) {
-    return { id: `component:file:${path}`, label: path,
-        kind: /\.(spec|test)\.[^.]+$/i.test(path) ? 'Evidence' : 'Component' };
-}
 /** Reads explicit mapping declarations, never infers routing from matching topic text. */
 export async function extractRoutingDeclarations(repository, context, paths, options = {}) {
     if (paths.length > 16 || new Set(paths).size !== paths.length ||
@@ -96,7 +93,7 @@ export async function extractRoutingDeclarations(repository, context, paths, opt
         if (!tracked.has(path)) {
             if (!options.allowMissingSources)
                 throw new Error(`Routing source ${path} is not a committed file at ${context.commitSha}`);
-            addDiagnostic(`Routing source ${path} is absent from this draft; no bindings from that source were retained.`, [], [`document:${path}`]);
+            addDiagnostic(`Routing source ${path} is absent from this draft; no bindings from that source were retained.`, [], [fileNode(path).id]);
             continue;
         }
         if (!regular.has(path))

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

@@ -7,6 +7,7 @@ export interface SemanticCacheInspection {
     readonly key?: string;
     readonly reason: string;
     readonly artifact?: SemanticArtifact;
+    readonly origin?: 'primary' | 'legacy';
 }
 /** 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

@@ -42,8 +42,11 @@ function reusableArtifact(value, key, source, config, modelIdentity) {
 export async function inspectSemanticCache(store, config, source, modelIdentity, forceRevision) {
     const key = semanticArtifactKey(config, source, modelIdentity, forceRevision);
     let value;
+    let origin;
     try {
-        value = await store.read(key);
+        const entry = await store.readEntry(key);
+        value = entry?.artifact;
+        origin = entry?.origin;
     }
     catch (error) {
         return error instanceof SyntaxError
@@ -55,5 +58,9 @@ export async function inspectSemanticCache(store, config, source, modelIdentity,
     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 };
+    return { status: 'hit', key, origin,
+        reason: origin === 'legacy'
+            ? 'Validated artifact is available in the exact legacy configuration profile; hydration can retain a copy in the operationally stable cache.'
+            : 'Readable artifact matches the source and extraction contract; reuse remains subject to unchanged inputs.',
+        artifact: value };
 }

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

@@ -0,0 +1,9 @@
+import type { SemanticSource } from '@weftlet/core';
+export type SemanticHydrationPhase = 'semantic-cache-read' | 'semantic-extract' | 'semantic-validate' | 'semantic-cache-write';
+/** Preserve policy distinctions without copying source-specific messages into run reports. */
+export declare class SemanticPolicyError extends Error {
+    readonly code: 'unresolved' | 'low-confidence';
+    constructor(code: 'unresolved' | 'low-confidence', message: string);
+}
+/** Correlation only: never used as an artifact key or an authorization boundary. */
+export declare function semanticSourceId(repositoryId: string, source: Pick<SemanticSource, 'stableSemanticId'>): string;

package/dist/extraction/semantic-diagnostics.js

@@ -0,0 +1,15 @@
+import { sha256, stableJson } from '../infrastructure/util.js';
+/** Preserve policy distinctions without copying source-specific messages into run reports. */
+export class SemanticPolicyError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'SemanticPolicyError';
+    }
+}
+/** Correlation only: never used as an artifact key or an authorization boundary. */
+export function semanticSourceId(repositoryId, source) {
+    return `source-${sha256(stableJson({ kind: 'weftlet-semantic-source-v1', repositoryId,
+        stableSemanticId: source.stableSemanticId }))}`;
+}

package/dist/extraction/semantic.d.ts

@@ -7,6 +7,7 @@ export type { SemanticRunOptions } from "./semantic-process.js";
 import type { ExtractionContext, GraphNodeKind, GraphPredicate, SemanticArtifact, SemanticSource, DiagnosticKind } from "@weftlet/core";
 import type { ContextGraphConfig } from "../configuration/config.js";
 import type { SemanticArtifactStore } from "../storage/storage.js";
+import { type SemanticHydrationPhase } from './semantic-diagnostics.js';
 export interface ExtractedAssertion {
     readonly subject: {
         readonly id: string;
@@ -66,8 +67,11 @@ export declare class SemanticHydrator {
     private readonly store;
     private readonly extractor;
     constructor(config: ContextGraphConfig['semantic'], store: SemanticArtifactStore, extractor: SemanticExtractor);
-    hydrate(source: SemanticSource, context: ExtractionContext, forceRevision?: string, options?: SemanticRunOptions): Promise<{
+    hydrate(source: SemanticSource, context: ExtractionContext, forceRevision?: string, options?: SemanticRunOptions & {
+        readonly onPhase?: (phase: SemanticHydrationPhase) => void;
+    }): Promise<{
         artifact: SemanticArtifact;
         reused: boolean;
     }>;
+    private promoteLegacy;
 }

package/dist/extraction/semantic.js

@@ -11,6 +11,7 @@ import { sha256, stableJson } from "../infrastructure/util.js";
 import { canonicalizeRepositoryDocumentNode } from './repository-nodes.js';
 import { semanticArtifactKey, semanticArtifactOutputDigest, semanticProviderIdentity } from './semantic-identity.js';
 import { inspectSemanticCache } from './semantic-cache.js';
+import { SemanticPolicyError } from './semantic-diagnostics.js';
 import { assertSemanticCitation, numberedSemanticSource, semanticCitationSchema, } from "./semantic-citations.js";
 function canonicalizeRepositoryDocuments(output) {
     const ids = new Map();
@@ -334,14 +335,32 @@ export class SemanticHydrator {
         this.extractor = extractor;
     }
     async hydrate(source, context, forceRevision, options = {}) {
-        options.signal?.throwIfAborted();
+        const checkpoint = () => {
+            if (options.signal?.aborted)
+                throw new SemanticProviderError('cancelled', 'Semantic extraction cancelled');
+        };
+        checkpoint();
+        options.onPhase?.('semantic-cache-read');
         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 === 'hit') {
+            // Planning remains read-only. Execution can copy an inspected legacy hit
+            // atomically without rewriting its original artifact or extraction identity.
+            checkpoint();
+            if (cached.origin === 'legacy')
+                options.onPhase?.('semantic-cache-write');
+            const artifact = cached.origin === 'legacy'
+                ? await this.promoteLegacy(source, cached.artifact, forceRevision) : cached.artifact;
+            return { artifact, reused: true };
+        }
         if (cached.status !== 'miss')
             throw new Error(cached.reason);
-        const extraction = await this.extractor.extract(source, context, options);
+        checkpoint();
+        options.onPhase?.('semantic-extract');
+        // Phase observation belongs to hydration, not the provider extension contract.
+        const extraction = await this.extractor.extract(source, context, { signal: options.signal, timeoutMs: options.timeoutMs });
+        checkpoint();
+        options.onPhase?.('semantic-validate');
         assertSemanticOutput(extraction.parsed, source);
         if (typeof extraction.rawModelOutput !== 'string' || Buffer.byteLength(extraction.rawModelOutput) > 2 * 1024 * 1024) {
             throw new SemanticProviderError('invalid-output', 'Invalid or oversized raw semantic output');
@@ -351,7 +370,7 @@ export class SemanticHydrator {
         const facts = output.assertions.map((assertion, index) => {
             assertSemanticCitation(assertion.citation, source.path, lineCount, `assertion[${index}]`);
             if (assertion.confidence < this.config.minimumConfidence) {
-                throw new Error(`Low-confidence semantic assertion for ${source.path}`);
+                throw new SemanticPolicyError('low-confidence', `Low-confidence semantic assertion for ${source.path}`);
             }
             const provenance = {
                 path: source.path,
@@ -398,7 +417,7 @@ export class SemanticHydrator {
         });
         const unresolvedMappings = output.unresolvedMappings ?? [];
         if (this.config.failOnUnresolved && (unresolvedMappings.length > 0 || diagnostics.length > 0)) {
-            throw new Error(`Unresolved semantic mappings for ${source.path}: ${[...unresolvedMappings, ...diagnostics.map((item) => item.reason)].join('; ')}`);
+            throw new SemanticPolicyError('unresolved', `Unresolved semantic mappings for ${source.path}: ${[...unresolvedMappings, ...diagnostics.map((item) => item.reason)].join('; ')}`);
         }
         const compiledOml = renderOml(key, output.assertions);
         const outputDigest = semanticArtifactOutputDigest({ facts, diagnostics, oml: compiledOml, rawModelOutput: extraction.rawModelOutput });
@@ -425,7 +444,21 @@ export class SemanticHydrator {
             rawModelOutput: extraction.rawModelOutput,
             outputDigest,
         };
+        checkpoint();
+        options.onPhase?.('semantic-cache-write');
         await this.store.write(artifact);
         return { artifact, reused: false };
     }
+    async promoteLegacy(source, artifact, forceRevision) {
+        await this.store.write(artifact);
+        // A concurrent winner must satisfy the full contract, not merely expose the
+        // same outputDigest field. Never publish using an invalid retained artifact.
+        const retained = await inspectSemanticCache(this.store, this.config, source, this.extractor.identity, forceRevision);
+        if (retained.status !== 'hit')
+            throw new Error(retained.reason);
+        if (retained.origin !== 'primary' || retained.artifact.outputDigest !== artifact.outputDigest) {
+            throw new Error('Concurrent semantic artifact changed during legacy promotion; inspect cache integrity before retrying.');
+        }
+        return retained.artifact;
+    }
 }

package/dist/extraction/static.d.ts

@@ -1,5 +1,5 @@
 import type { ContextGraphConfig } from "../configuration/config.js";
-import type { ExtractionContext, FactExtractor, GraphFact } from "@weftlet/core";
+import { type ExtractionContext, type FactExtractor, type GraphFact } from "@weftlet/core";
 import { GitRepository } from "../repository/git.js";
 export interface ScipIndexResult {
     readonly path: string;
@@ -17,12 +17,16 @@ export declare class ScipTypeScriptIndexer implements StaticIndexer {
     index(context: ExtractionContext): Promise<ScipIndexResult>;
 }
 export declare function normalizeScipCheckout(bytes: Uint8Array, checkoutRoot: string): Uint8Array;
+export declare const scipSymbolExtractorIdentity: {
+    readonly id: "scip-symbol-extractor";
+    readonly version: "1.1.0";
+};
 export declare class ScipSymbolExtractor implements FactExtractor {
     private readonly repository;
     private readonly index;
     readonly identity: {
-        id: string;
-        version: string;
+        readonly id: "scip-symbol-extractor";
+        readonly version: "1.1.0";
     };
     constructor(repository: GitRepository, index: ScipIndexResult);
     extract(context: ExtractionContext): Promise<readonly GraphFact[]>;
@@ -42,14 +46,18 @@ export declare class RepositoryFileExtractor implements FactExtractor {
     constructor(repository: GitRepository, roots: readonly string[], scipDigest: string);
     extract(context: ExtractionContext): Promise<readonly GraphFact[]>;
 }
+export declare const repositoryContractExtractorIdentity: {
+    readonly id: "repository-contract-extractor";
+    readonly version: "1.2.0";
+};
 export declare class RepositoryContractExtractor implements FactExtractor {
     private readonly repository;
     private readonly patterns;
     private readonly consumerRoots;
     private readonly aliases;
     readonly identity: {
-        id: string;
-        version: string;
+        readonly id: "repository-contract-extractor";
+        readonly version: "1.2.0";
     };
     constructor(repository: GitRepository, patterns: readonly string[], consumerRoots: readonly string[], aliases?: Readonly<Record<string, readonly string[]>>);
     extract(context: ExtractionContext): Promise<readonly GraphFact[]>;

package/dist/extraction/static.js

@@ -5,6 +5,7 @@ import { copyFile, mkdir, readFile, rename, stat, writeFile } from 'node:fs/prom
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { repositoryFileNode } from "@weftlet/core";
 import { GitRepository } from "../repository/git.js";
 import { assertScipSourceProject, assertSourceProjectInvocation } from '../configuration/scip-project.js';
 import { prepareScipSourceProject } from './scip-project.js';
@@ -90,10 +91,11 @@ export function normalizeScipCheckout(bytes, checkoutRoot) {
     }
     return index.serializeBinary();
 }
+export const scipSymbolExtractorIdentity = { id: 'scip-symbol-extractor', version: '1.1.0' };
 export class ScipSymbolExtractor {
     repository;
     index;
-    identity = { id: 'scip-symbol-extractor', version: '1.0.0' };
+    identity = scipSymbolExtractorIdentity;
     constructor(repository, index) {
         this.repository = repository;
         this.index = index;
@@ -105,11 +107,7 @@ export class ScipSymbolExtractor {
             const path = document.relative_path.replace(/\\/g, '/');
             const content = await this.repository.readFileAt(context.commitSha, path);
             const digest = sha256(content);
-            const component = {
-                id: `component:file:${path}`,
-                kind: (/\.(spec|test)\.[^.]+$/i.test(path) ? 'Evidence' : 'Component'),
-                label: path,
-            };
+            const component = repositoryFileNode(path);
             for (const occurrence of document.occurrences) {
                 if (!occurrence.symbol || occurrence.symbol.startsWith('local '))
                     continue;
@@ -195,9 +193,7 @@ export class RepositoryFileExtractor {
             const content = await this.repository.readFileAt(context.commitSha, path);
             const digest = sha256(content);
             const component = {
-                id: `component:file:${path}`,
-                kind: (/\.(spec|test)\.[^.]+$/i.test(path) ? 'Evidence' : 'Component'),
-                label: path,
+                ...repositoryFileNode(path),
                 attributes: { scipIndexDigest: this.scipDigest },
             };
             const provenance = {
@@ -239,12 +235,13 @@ export class RepositoryFileExtractor {
         return facts;
     }
 }
+export const repositoryContractExtractorIdentity = { id: 'repository-contract-extractor', version: '1.2.0' };
 export class RepositoryContractExtractor {
     repository;
     patterns;
     consumerRoots;
     aliases;
-    identity = { id: 'repository-contract-extractor', version: '1.1.0' };
+    identity = repositoryContractExtractorIdentity;
     constructor(repository, patterns, consumerRoots, aliases = {}) {
         this.repository = repository;
         this.patterns = patterns;
@@ -306,11 +303,7 @@ export class RepositoryContractExtractor {
                     digest: sha256(consumerContent),
                     commitSha: context.commitSha,
                 };
-                const consumer = {
-                    id: `component:file:${match.path}`,
-                    kind: 'Component',
-                    label: match.path,
-                };
+                const consumer = repositoryFileNode(match.path);
                 facts.push({
                     id: sha256(stableJson({ consumer, contract, consumerProvenance })),
                     subject: consumer,

package/dist/governance/governance.js

@@ -2,10 +2,12 @@ import { readFile, mkdtemp, realpath, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { isAbsolute, join, relative, resolve } from 'node:path';
 import { createRequire } from 'node:module';
+import { repositoryFileNode } from '@weftlet/core';
 import { GitRepository } from "../repository/git.js";
 import { RdfEvidenceGraph, CG, nodeIri } from "../graph/rdf.js";
 import { sha256, stableJson } from "../infrastructure/util.js";
 import { runProcess } from "../infrastructure/process.js";
+const architectureAnalyzerVersion = '3';
 export async function analyzeArchitecture(root, policy, policyPath = 'architecture.policy.json') {
     const findings = [];
     const add = (category, ruleId, from, to, message) => {
@@ -86,11 +88,11 @@ export async function analyzeArchitecture(root, policy, policyPath = 'architectu
                 const lines = content.split('\n');
                 facts.push({
                     id: sha256(stableJson({ from: module.source, to: dependency.resolved, digest: inputs[module.source] })),
-                    subject: { id: `component:file:${module.source}`, kind: 'Component', label: module.source,
+                    subject: { ...repositoryFileNode(module.source),
                         attributes: membership[0] ? { domain: membership[0].domain, layer: membership[0].layer,
                             module: membership[0].id, adapter: Boolean(membership[0].adapter) } : {} },
                     predicate: 'consumes',
-                    object: { id: `component:file:${dependency.resolved}`, kind: 'Component', label: dependency.resolved },
+                    object: repositoryFileNode(dependency.resolved),
                     provenance: { path: module.source, startLine: 1, endLine: lines.length, digest: inputs[module.source], commitSha },
                     extractor: { id: 'dependency-cruiser', version: '18.7.0' }, confidence: 1,
                     authority: dirtyPaths.has(module.source) ? 'draft' : 'implemented', snapshotId: 'pending',
@@ -128,7 +130,7 @@ export async function analyzeArchitecture(root, policy, policyPath = 'architectu
             attributes: { domain: module.domain, layer: module.layer, adapter: Boolean(module.adapter) } };
         addPolicyFact(node, 'governedBy', { id: `layer:${module.layer}`, kind: 'Scope', label: module.layer });
         for (const path of Object.keys(inputs).filter((path) => new RegExp(module.path).test(path))) {
-            addPolicyFact(node, 'contains', { id: `component:file:${path}`, kind: 'Component', label: path });
+            addPolicyFact(node, 'contains', repositoryFileNode(path));
         }
     }
     for (const contract of policy.contracts ?? []) {
@@ -137,14 +139,16 @@ export async function analyzeArchitecture(root, policy, policyPath = 'architectu
     if (!Object.keys(inputs).length)
         add('extraction-gap', 'source-coverage', '', '', 'No source files were analyzed');
     const contentDigest = sha256(stableJson({ inputs, policyDigest, commitSha, dirtyPaths: [...dirtyPaths].sort(),
-        tools: { dependencyCruiser: '18.7.0', eslint: '10.13.0', jscpd: '5.4.1', analyzer: '2' } }));
+        tools: { dependencyCruiser: '18.7.0', eslint: '10.13.0', jscpd: '5.4.1', analyzer: architectureAnalyzerVersion } }));
     const snapshotId = `architecture-${contentDigest}`;
     const snapshot = {
         manifest: {
             schemaVersion: 1, repositoryId: 'architecture-analysis', ref: 'HEAD', commitSha, snapshotId,
             configurationDigest: policyDigest, scope: policy.roots, contentDigest,
             ...(dirtyPaths.size ? { baseSha: commitSha, overlayDigest: contentDigest } : {}),
-            ontologyVersion: 'architecture-v1', extractorVersions: { 'dependency-cruiser': '18.7.0' },
+            ontologyVersion: 'architecture-v1', extractorVersions: {
+                'dependency-cruiser': '18.7.0', 'architecture-analyzer': architectureAnalyzerVersion,
+            },
             semanticModel: 'none', semanticPromptVersion: 'none', generatedAt: new Date().toISOString(),
             semanticArtifactKeys: [], scipIndexDigest: '', rdfDigest: '',
         },
@@ -158,8 +162,8 @@ export async function analyzeArchitecture(root, policy, policyPath = 'architectu
         if (result.truncated)
             add('extraction-gap', rule.id, '', '', 'Transitive dependency query truncated');
         for (const row of result.rows) {
-            const from = modules.find((m) => nodeIri(`component:file:${m.source}`) === row.from)?.source;
-            const to = modules.find((m) => nodeIri(`component:file:${m.source}`) === row.to)?.source;
+            const from = modules.find((m) => nodeIri(repositoryFileNode(m.source).id) === row.from)?.source;
+            const to = modules.find((m) => nodeIri(repositoryFileNode(m.source).id) === row.to)?.source;
             if (from && to && new RegExp(rule.from).test(from) && new RegExp(rule.to).test(to)) {
                 add(rule.approved ? 'rule-violation' : 'advisory', rule.id, from, to, 'Transitive dependency inferred by SPARQL property path from source import evidence');
             }

package/dist/graph/identity-preflight.d.ts

@@ -0,0 +1,57 @@
+import { type ExtractorIdentity, type GraphFact, type GraphNodeKind, type SourceSpan } from '@weftlet/core';
+/** Diagnostic detail is an invocation option, not extraction policy or a cache identity input. */
+export interface GraphIdentityPreflightOptions {
+    readonly repositoryId: string;
+    readonly includeDetails?: boolean;
+}
+export type ReportedIdentityKind = GraphNodeKind | `unknown-kind-${string}`;
+export interface GraphIdentityOccurrenceDetails {
+    readonly nodeId: string;
+    readonly nodeKind: GraphNodeKind;
+    readonly factId: string;
+    readonly extractor: ExtractorIdentity;
+    readonly provenance: SourceSpan;
+    readonly confidence: number;
+    readonly authority?: GraphFact['authority'];
+    readonly sourceAuthority?: GraphFact['sourceAuthority'];
+    readonly extractionReview?: GraphFact['extractionReview'];
+}
+export interface GraphIdentityOccurrence {
+    readonly factIndex: number;
+    readonly side: 'subject' | 'object';
+    readonly kind: ReportedIdentityKind;
+    readonly factRef: string;
+    readonly sourceRef: string;
+    readonly extractorRef: string;
+    readonly details?: GraphIdentityOccurrenceDetails;
+}
+export interface GraphIdentityConflict {
+    readonly nodeRef: string;
+    readonly kinds: readonly ReportedIdentityKind[];
+    readonly occurrences: readonly GraphIdentityOccurrence[];
+    readonly details?: {
+        readonly nodeId: string;
+    };
+}
+export interface GraphIdentityPreflightReport {
+    readonly schemaVersion: 1;
+    readonly kind: 'graph-identity-preflight';
+    readonly category: 'extraction-gap';
+    readonly phase: 'validate-identities';
+    readonly passed: boolean;
+    /** A passing identity preflight never establishes full graph conformance. */
+    readonly shaclValidated: false;
+    readonly factCount: number;
+    readonly nodeCount: number;
+    readonly conflictCount: number;
+    readonly conflicts: readonly GraphIdentityConflict[];
+}
+/** Find the single-kind constraint's conflicts without constructing RDF or changing any fact. */
+export declare function inspectGraphIdentities(facts: readonly GraphFact[], options: GraphIdentityPreflightOptions): GraphIdentityPreflightReport;
+/** The message is safe even when the caller explicitly requested local report details. */
+export declare class GraphIdentityConflictError extends Error {
+    readonly report: GraphIdentityPreflightReport;
+    readonly code = "node-kind-conflict";
+    constructor(report: GraphIdentityPreflightReport);
+}
+export declare function assertGraphIdentities(facts: readonly GraphFact[], options: GraphIdentityPreflightOptions): GraphIdentityPreflightReport;

package/dist/graph/identity-preflight.js

@@ -0,0 +1,71 @@
+import { sha256, stableJson } from '@weftlet/core';
+const publicKinds = new Set([
+    'Project', 'Document', 'Capability', 'Workflow', 'Component', 'Contract', 'Evidence',
+    'Invariant', 'Snapshot', 'Provider', 'PersistenceModel', 'Scope',
+]);
+/** Find the single-kind constraint's conflicts without constructing RDF or changing any fact. */
+export function inspectGraphIdentities(facts, options) {
+    const identities = new Map();
+    for (const fact of facts)
+        for (const node of [fact.subject, fact.object]) {
+            let kinds = identities.get(node.id);
+            if (!kinds)
+                identities.set(node.id, kinds = new Set());
+            kinds.add(node.kind);
+        }
+    const ref = (domain, ...values) => `identity-${domain}-${sha256(stableJson(['graph-identity-preflight-v1', options.repositoryId, domain, ...values]))}`;
+    const reportedKind = (kind) => publicKinds.has(kind)
+        ? kind : `unknown-kind-${sha256(stableJson(['graph-identity-kind-v1', options.repositoryId, kind]))}`;
+    const conflicts = new Map();
+    for (const [id, kinds] of identities)
+        if (kinds.size > 1) {
+            conflicts.set(id, { nodeRef: ref('node', id), kinds: [...kinds].map(reportedKind), occurrences: [],
+                ...(options.includeDetails ? { details: { nodeId: id } } : {}) });
+        }
+    // The common conflict-free path allocates no evidence reports. Preserve every conflicting
+    // occurrence, including duplicate fact IDs and the two ends of a self-reference.
+    if (conflicts.size)
+        for (const [factIndex, fact] of facts.entries()) {
+            const sides = ['subject', 'object'].filter(side => conflicts.has(fact[side].id));
+            if (!sides.length)
+                continue;
+            const references = { factRef: ref('fact', fact.id), sourceRef: ref('source', fact.provenance.path),
+                extractorRef: ref('extractor', fact.extractor.id, fact.extractor.version) };
+            for (const side of sides) {
+                const node = fact[side];
+                conflicts.get(node.id).occurrences.push({ factIndex, side, kind: reportedKind(node.kind), ...references,
+                    ...(options.includeDetails ? { details: {
+                            nodeId: node.id, nodeKind: node.kind, factId: fact.id,
+                            extractor: { id: fact.extractor.id, version: fact.extractor.version },
+                            provenance: { path: fact.provenance.path, startLine: fact.provenance.startLine,
+                                endLine: fact.provenance.endLine, digest: fact.provenance.digest, commitSha: fact.provenance.commitSha },
+                            confidence: fact.confidence,
+                            ...(fact.authority === undefined ? {} : { authority: fact.authority }),
+                            ...(fact.sourceAuthority === undefined ? {} : { sourceAuthority: fact.sourceAuthority }),
+                            ...(fact.extractionReview === undefined ? {} : { extractionReview: fact.extractionReview }),
+                        } } : {}) });
+            }
+        }
+    return { schemaVersion: 1, kind: 'graph-identity-preflight', category: 'extraction-gap',
+        phase: 'validate-identities', passed: conflicts.size === 0, shaclValidated: false,
+        factCount: facts.length, nodeCount: identities.size, conflictCount: conflicts.size,
+        conflicts: [...conflicts.values()] };
+}
+/** The message is safe even when the caller explicitly requested local report details. */
+export class GraphIdentityConflictError extends Error {
+    report;
+    code = 'node-kind-conflict';
+    constructor(report) {
+        super(`Graph identity preflight found ${report.conflictCount} node kind conflict(s) across ${report.factCount} facts. ` +
+            'Full SHACL validation was not run. Use --validation-details for local node and cited evidence details. ' +
+            'Correct the extractor or assertion identity disagreement, then retry; no graph facts were rewritten by this check.');
+        this.report = report;
+        this.name = 'GraphIdentityConflictError';
+    }
+}
+export function assertGraphIdentities(facts, options) {
+    const report = inspectGraphIdentities(facts, options);
+    if (!report.passed)
+        throw new GraphIdentityConflictError(report);
+    return report;
+}

package/dist/graph/query.js

@@ -113,6 +113,7 @@ export class MarkdownContextPackRenderer {
             ] : []),
             ...(pack.evidenceState ? [
                 `Stale relative to checkout: ${pack.evidenceState.stale}; configuration matches: ${pack.evidenceState.configurationMatches}`,
+                `Extraction compatibility: ${pack.evidenceState.extractionCompatible === undefined ? 'not assessed' : pack.evidenceState.extractionCompatible ? 'current' : `refresh required (${pack.evidenceState.incompatibleExtractors?.join(', ') || 'unknown versions'})`}`,
                 `Excluded working changes: ${pack.evidenceState.excludedWorkingChanges.join(', ') || '(none)'}`,
                 ...(pack.evidenceState.overlayFreshness ? [
                     `Overlay freshness: ${pack.evidenceState.overlayFreshness}`,
@@ -327,6 +328,7 @@ export class SnapshotImpactQueryService {
                 baseSha: snapshot.manifest.baseSha,
                 overlayDigest: snapshot.manifest.overlayDigest,
                 overlayCapture: snapshot.manifest.overlayCapture,
+                extractorVersions: snapshot.manifest.extractorVersions,
             },
             capabilities,
             facts,

package/dist/graph/rdf.d.ts

@@ -1,4 +1,5 @@
 import type { GraphFact, GraphSnapshot } from "@weftlet/core";
+import { type GraphValidationProgress } from './validation-progress.js';
 export { CG } from './shacl-shapes.js';
 export declare const nodeIri: (id: string) => string;
 export declare const factIri: (id: string) => string;
@@ -7,7 +8,9 @@ export declare class RdfEvidenceGraph {
     readonly snapshot: GraphSnapshot;
     private readonly dataset;
     constructor(snapshot: GraphSnapshot);
-    validate(): Promise<{
+    validate(options?: {
+        readonly onProgress?: (event: GraphValidationProgress) => void;
+    }): Promise<{
         conforms: boolean;
         issues: {
             category: "extraction-gap";

package/dist/graph/rdf.js

@@ -5,6 +5,7 @@ import { contextPackEvidenceAuthority } from "./authority.js";
 import { stableJson } from "../infrastructure/util.js";
 import { createRequire } from 'node:module';
 import { CG, RDF, XSD, evidenceShapes } from './shacl-shapes.js';
+import { measureValidationPhase } from './validation-progress.js';
 const { namedNode: iri, literal } = DataFactory;
 export { CG } from './shacl-shapes.js';
 export const nodeIri = (id) => `urn:context-graph:node:${encodeURIComponent(id)}`;
@@ -61,16 +62,19 @@ export class RdfEvidenceGraph {
             this.dataset.addQuad(iri('urn:context-graph:snapshot'), iri(CG + 'configurationDigest'), literal(snapshot.manifest.configurationDigest));
         }
     }
-    async validate() {
+    async validate(options = {}) {
         // These graph-independent shapes already read the dataset as a union. Index
         // that union once so every property lookup avoids scanning one graph per fact.
         // Keep every triple; the original named dataset retains assertion provenance
         // and remains the source for queries and serialization.
-        const validationGraph = new Store();
-        for (const { subject, predicate, object } of this.dataset) {
-            validationGraph.addQuad(subject, predicate, object);
-        }
-        const report = await new SHACLValidator(new Store(evidenceShapes)).validate(validationGraph);
+        const counts = { factCount: this.snapshot.facts.length };
+        const validationGraph = await measureValidationPhase('build-validation-union', counts, options.onProgress, () => {
+            const union = new Store();
+            for (const { subject, predicate, object } of this.dataset)
+                union.addQuad(subject, predicate, object);
+            return union;
+        });
+        const report = await measureValidationPhase('validate-shacl', counts, options.onProgress, () => new SHACLValidator(new Store(evidenceShapes)).validate(validationGraph));
         const issues = report.results.map((result) => ({
             category: 'extraction-gap',
             focus: result.focusNode?.value,

package/dist/graph/validation-progress.d.ts

@@ -0,0 +1,14 @@
+export type GraphValidationPhase = 'validate-identities' | 'build-rdf-evidence' | 'build-validation-union' | 'validate-shacl';
+export interface GraphValidationProgress {
+    readonly phase: GraphValidationPhase;
+    readonly status: 'started' | 'completed' | 'failed';
+    /** Wall time for this phase, not a completion estimate or in-phase heartbeat. */
+    readonly elapsedMs: number;
+    readonly factCount: number;
+    readonly nodeCount?: number;
+}
+/** Phase boundaries remain observable even when an operation blocks same-thread timers. */
+export declare function measureValidationPhase<T>(phase: GraphValidationPhase, counts: {
+    readonly factCount: number;
+    readonly nodeCount?: number;
+}, onProgress: ((event: GraphValidationProgress) => void) | undefined, operation: () => T | Promise<T>): Promise<T>;