@weftlet/toolkit 0.4.0 → 0.6.0

package/dist/graph/coverage.js

@@ -0,0 +1,96 @@
+import { repositoryFileNode } from '@weftlet/core';
+import { contextPackEvidenceAuthority } from './authority.js';
+export const contextPackLanes = [
+    'productIntent',
+    'contractsAndInvariants',
+    'implementationAndConsumers',
+    'validationEvidence',
+];
+function isValidationFact(fact) {
+    if (fact.sourceRole !== undefined) {
+        return fact.sourceRole === 'validation' || fact.subject.kind === 'Evidence' ||
+            fact.object.kind === 'Evidence' || fact.predicate === 'verifiedBy';
+    }
+    const path = fact.provenance.path.toLowerCase();
+    return (fact.subject.kind === 'Evidence' ||
+        fact.object.kind === 'Evidence' ||
+        fact.predicate === 'verifiedBy' ||
+        /(?:^|\/)(?:test|tests|testing|validation|evidence)(?:\/|$)/.test(path) ||
+        /\.(?:spec|test)\.[cm]?[jt]sx?$/.test(path));
+}
+export function isDeclaredFact(fact) {
+    if (fact.sourceRole !== undefined && fact.sourceRole !== 'intent')
+        return false;
+    if (fact.authority)
+        return fact.authority === 'declared' && !isValidationFact(fact);
+    return false;
+}
+export function contextPackLaneForFact(fact) {
+    if (fact.sourceRole === 'validation')
+        return 'validationEvidence';
+    if (fact.extractor.id === 'otlp-runtime-evidence')
+        return undefined;
+    const kinds = new Set([fact.subject.kind, fact.object.kind]);
+    if (isValidationFact(fact)) {
+        return 'validationEvidence';
+    }
+    if (kinds.has('Contract') ||
+        kinds.has('Invariant') ||
+        kinds.has('PersistenceModel') ||
+        ['governedBy', 'definedBy', 'persistsTo', 'authorizedBy'].includes(fact.predicate)) {
+        return 'contractsAndInvariants';
+    }
+    if ((fact.sourceRole === undefined || fact.sourceRole === 'intent') &&
+        (isDeclaredFact(fact) || fact.sourceAuthority === 'declared') &&
+        (kinds.has('Document') ||
+            kinds.has('Capability') ||
+            kinds.has('Workflow') ||
+            ['decisionAuthority', 'operationallyOwnedBy', 'references'].includes(fact.predicate))) {
+        return 'productIntent';
+    }
+    return 'implementationAndConsumers';
+}
+export function coverageDescription(coverage) {
+    return coverage.scope === 'returned-page' && coverage.countsAreNonExclusive
+        ? 'Counts describe evidence on this returned page and may overlap; a code relationship can also describe a contract. They are not a percentage, a count of display groups, or proof that behavior is correct.'
+        : 'Coverage scope and overlap metadata are unavailable for this Context Pack; re-query saved evidence for an explicit report.';
+}
+/** Reporting only: never changes a fact's authority, identity, primary lane or stored bytes. */
+export function isImplementationEvidence(fact) {
+    if (fact.sourceRole !== undefined || isValidationFact(fact) || fact.extractor.id === 'otlp-runtime-evidence' ||
+        fact.extractionReview === 'unreviewed' || contextPackEvidenceAuthority(fact) !== 'implemented')
+        return false;
+    const path = fact.provenance.path;
+    if (!path || /(?:^|\/)(?:test|tests|testing|validation|evidence|__tests__|__mocks__)(?:\/|$)/i.test(path.replaceAll('\\', '/')))
+        return false;
+    const file = repositoryFileNode(path);
+    if (file.kind !== 'Component')
+        return false;
+    const nodes = [fact.subject, fact.object];
+    // Explicit adapter authority also supports logical component/provider identities.
+    if (fact.authority === 'implemented')
+        return nodes.some(node => ['Component', 'Provider'].includes(node.kind));
+    // Legacy deterministic adapters omitted authority. Require their cited physical file,
+    // rather than treating every fact in the implementation display group as code evidence.
+    return nodes.some(node => node.kind === 'Component' && node.id === file.id);
+}
+export function coverageForFacts(facts) {
+    const counts = {
+        productIntent: 0, contractsAndInvariants: 0, implementationAndConsumers: 0, validationEvidence: 0,
+    };
+    for (const fact of facts) {
+        const lane = contextPackLaneForFact(fact);
+        if (lane && lane !== 'implementationAndConsumers')
+            counts[lane]++;
+        if (isImplementationEvidence(fact))
+            counts.implementationAndConsumers++;
+    }
+    return { scope: 'returned-page', countsAreNonExclusive: true, counts,
+        gaps: [
+            ...contextPackLanes.filter(lane => counts[lane] === 0)
+                .map(lane => `No ${lane} evidence appears on this returned page.`),
+            ...(facts.some(fact => fact.sourceAuthority === 'declared' && fact.extractionReview === 'unreviewed')
+                ? ['Approved-source extraction remains unreviewed; verify cited intent before using it as a rule or gate.'] : []),
+        ],
+    };
+}

package/dist/graph/document-role-description.d.ts

@@ -0,0 +1,5 @@
+import type { DocumentSelectionRecord, GraphFact } from '@weftlet/core';
+/** Plain text for evidence details; the rendering context must escape it. */
+export declare function sourceDocumentDescription(fact: GraphFact): string | undefined;
+/** Completeness is scoped to the configured canonical links, not all product knowledge. */
+export declare function documentSelectionDescription(selection?: DocumentSelectionRecord): string;

package/dist/graph/document-role-description.js

@@ -0,0 +1,18 @@
+/** Plain text for evidence details; the rendering context must escape it. */
+export function sourceDocumentDescription(fact) {
+    const parts = [];
+    if (fact.sourceRole !== undefined)
+        parts.push(`source role ${fact.sourceRole}`);
+    if (fact.sourceOwnership) {
+        parts.push(`ownership ${fact.sourceOwnership.status}`, `owner documents ${fact.sourceOwnership.ownerDocuments.join(', ') || '(none)'}`);
+    }
+    return parts.length ? parts.join('; ') : undefined;
+}
+/** Completeness is scoped to the configured canonical links, not all product knowledge. */
+export function documentSelectionDescription(selection) {
+    if (!selection)
+        return '';
+    return `Document traversal: ${selection.complete ? 'complete within configured links' : 'INCOMPLETE'}; ` +
+        `${selection.documentPaths.length} discovered documents; ${selection.semanticPaths.length} semantic candidates; ` +
+        `${selection.excluded.length} excluded from semantic extraction. Ownership and assertion approval are separate.`;
+}

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.d.ts

@@ -1,7 +1,7 @@
-import type { ContextPack, ContextPackLane, ContextPackRenderer, GraphFact, ImpactQueryService, ImpactScanRequest, SnapshotStore } from "@weftlet/core";
+import type { ContextPack, ContextPackRenderer, ImpactQueryService, ImpactScanRequest, SnapshotStore } from "@weftlet/core";
+export { contextPackLaneForFact } from './coverage.js';
 export declare const DEFAULT_CONTEXT_PACK_FACTS = 60;
 export declare const MAX_CONTEXT_PACK_FACTS = 200;
-export declare function contextPackLaneForFact(fact: GraphFact): ContextPackLane | undefined;
 export { contextPackEvidenceAuthority } from "./authority.js";
 export declare class MarkdownContextPackRenderer implements ContextPackRenderer {
     render(pack: Omit<ContextPack, 'markdown'>): string;

package/dist/graph/query.js

@@ -4,49 +4,11 @@ import { RdfEvidenceGraph } from "./rdf.js";
 import { sha256, stableJson } from "../infrastructure/util.js";
 import { diagnosticSummary, selectDiagnostics } from "./diagnostics.js";
 import { factSearchText, IMPACT_RANKING_VERSION, rankImpactFacts } from './ranking.js';
+import { contextPackLanes, contextPackLaneForFact, isDeclaredFact, coverageForFacts, coverageDescription } from './coverage.js';
+import { documentSelectionDescription, sourceDocumentDescription } from './document-role-description.js';
+export { contextPackLaneForFact } from './coverage.js';
 export const DEFAULT_CONTEXT_PACK_FACTS = 60;
 export const MAX_CONTEXT_PACK_FACTS = 200;
-const contextPackLanes = [
-    'productIntent',
-    'contractsAndInvariants',
-    'implementationAndConsumers',
-    'validationEvidence',
-];
-function isValidationFact(fact) {
-    const path = fact.provenance.path.toLowerCase();
-    return (fact.subject.kind === 'Evidence' ||
-        fact.object.kind === 'Evidence' ||
-        fact.predicate === 'verifiedBy' ||
-        /(?:^|\/)(?:test|tests|testing|validation|evidence)(?:\/|$)/.test(path) ||
-        /\.(?:spec|test)\.[cm]?[jt]sx?$/.test(path));
-}
-function isDeclaredFact(fact) {
-    if (fact.authority)
-        return fact.authority === 'declared' && !isValidationFact(fact);
-    return false;
-}
-export function contextPackLaneForFact(fact) {
-    if (fact.extractor.id === 'otlp-runtime-evidence')
-        return undefined;
-    const kinds = new Set([fact.subject.kind, fact.object.kind]);
-    if (isValidationFact(fact)) {
-        return 'validationEvidence';
-    }
-    if (kinds.has('Contract') ||
-        kinds.has('Invariant') ||
-        kinds.has('PersistenceModel') ||
-        ['governedBy', 'definedBy', 'persistsTo', 'authorizedBy'].includes(fact.predicate)) {
-        return 'contractsAndInvariants';
-    }
-    if ((isDeclaredFact(fact) || fact.sourceAuthority === 'declared') &&
-        (kinds.has('Document') ||
-            kinds.has('Capability') ||
-            kinds.has('Workflow') ||
-            ['decisionAuthority', 'operationallyOwnedBy', 'references'].includes(fact.predicate))) {
-        return 'productIntent';
-    }
-    return 'implementationAndConsumers';
-}
 export { contextPackEvidenceAuthority } from "./authority.js";
 function selectBalancedFacts(ranked, maxFacts) {
     const queues = Object.fromEntries(contextPackLanes.map((lane) => [
@@ -63,11 +25,7 @@ function selectBalancedFacts(ranked, maxFacts) {
                 break;
         }
     }
-    const counts = Object.fromEntries(contextPackLanes.map((lane) => [
-        lane,
-        facts.filter((fact) => contextPackLaneForFact(fact) === lane).length,
-    ]));
-    return { facts, counts };
+    return facts;
 }
 const searchStopWords = new Set([
     'about',
@@ -99,6 +57,12 @@ function boundedFactLimit(value) {
     }
     return Math.min(value, MAX_CONTEXT_PACK_FACTS);
 }
+function markdownFactDetails(fact) {
+    const document = sourceDocumentDescription(fact)?.replace(/[\\`*_{}\[\]()<>!|]/g, '\\$&').replace(/[\r\n]/g, ' ');
+    return `confidence ${fact.confidence}` +
+        (fact.sourceAuthority ? `; source ${fact.sourceAuthority}; extraction ${fact.extractionReview ?? 'unknown'}` : '') +
+        (document ? `; ${document}` : '');
+}
 export class MarkdownContextPackRenderer {
     render(pack) {
         const lines = [
@@ -106,6 +70,7 @@ export class MarkdownContextPackRenderer {
             '',
             `Snapshot: \`${pack.snapshot.snapshotId}\` (${pack.snapshot.commitSha})`,
             `Configuration: ${pack.snapshot.configurationDigest ?? 'legacy/unknown'}; scope: ${pack.snapshot.scope?.join(', ') ?? 'legacy/unknown'}`,
+            ...[documentSelectionDescription(pack.snapshot.documentSelection)].filter(Boolean),
             ...(pack.exploration ? [
                 `Ranking: ${pack.exploration.rankingVersion ?? 'legacy/unknown'}`,
                 `Relationships returned: ${pack.exploration.returned}/${pack.exploration.reachableFacts}; truncated: ${pack.exploration.truncated}; depth limit reached: ${pack.exploration.depthLimitReached}`,
@@ -130,17 +95,18 @@ export class MarkdownContextPackRenderer {
             ...pack.invariants.map((item) => `- ${item.status}: ${item.message}`),
             '',
             '## Coverage',
+            coverageDescription(pack.coverage),
             ...contextPackLanes.map((lane) => `- ${lane}: ${pack.coverage.counts[lane]} relationships`),
             ...(pack.coverage.gaps.length
                 ? pack.coverage.gaps.map((gap) => `- GAP: ${gap}`)
-                : ['- No Context Pack lane gaps detected.']),
+                : ['- No coverage gaps detected on this returned page.']),
             ...contextPackLanes.flatMap((lane) => [
                 '',
                 `## ${lane}`,
                 ...pack.facts
                     .filter((fact) => contextPackLaneForFact(fact) === lane)
                     .map((fact) => `- [${contextPackEvidenceAuthority(fact)}] ${fact.subject.label} —${fact.predicate}→ ${fact.object.label} ` +
-                    `(\`${fact.provenance.path}:${fact.provenance.startLine}\`, confidence ${fact.confidence}${fact.sourceAuthority ? `; source ${fact.sourceAuthority}; extraction ${fact.extractionReview ?? 'unknown'}` : ''})`),
+                    `(\`${fact.provenance.path}:${fact.provenance.startLine}\`, ${markdownFactDetails(fact)})`),
             ]),
             '',
             '## Runtime evidence',
@@ -226,7 +192,7 @@ export class SnapshotImpactQueryService {
         }
         // Balance evidence lanes among similarly ranked facts, not across unrelated distance tiers.
         const allBalanced = [...tiers.values()].flatMap((tier) => [
-            ...selectBalancedFacts(tier, tier.length).facts,
+            ...selectBalancedFacts(tier, tier.length),
             ...tier.filter((fact) => contextPackLaneForFact(fact) === undefined),
         ]);
         const { continuation: _continuation, snapshotId: _snapshotId, ...query } = request;
@@ -249,7 +215,7 @@ export class SnapshotImpactQueryService {
             offset = token.offset;
         }
         const facts = allBalanced.slice(offset, offset + maxFacts);
-        const balanced = selectBalancedFacts(facts, facts.length);
+        const coverage = coverageForFacts(facts);
         const nextOffset = offset + facts.length;
         const continuation = nextOffset < allBalanced.length ? Buffer.from(JSON.stringify({
             snapshot: snapshot.manifest.snapshotId, digest: snapshot.manifest.contentDigest,
@@ -294,13 +260,13 @@ export class SnapshotImpactQueryService {
         for (const [kind, missing, reason] of [
             [
                 'missingIntent',
-                balanced.counts.productIntent === 0,
-                'No declared intent matched this query. Inspect the owner and philosophy sources before concluding a requirement is missing.',
+                coverage.counts.productIntent === 0,
+                'No product-intent relationships appear on this returned page. Inspect continuation, scope and owner sources before concluding a requirement is missing.',
             ],
             [
                 'implementationGaps',
-                balanced.counts.implementationAndConsumers === 0,
-                'No implementation relationships matched this query. Inspect code before concluding behavior is missing.',
+                coverage.counts.implementationAndConsumers === 0,
+                'No production implementation evidence appears on this returned page. Inspect continuation, scope and code before concluding behavior is missing.',
             ],
             [
                 'runtimeGaps',
@@ -329,20 +295,14 @@ export class SnapshotImpactQueryService {
                 overlayDigest: snapshot.manifest.overlayDigest,
                 overlayCapture: snapshot.manifest.overlayCapture,
                 extractorVersions: snapshot.manifest.extractorVersions,
+                ...(snapshot.manifest.documentSelection ? { documentSelection: snapshot.manifest.documentSelection } : {}),
             },
             capabilities,
             facts,
             invariants: snapshot.invariants.filter((item) => item.provenance.some((span) => suggestedFiles.includes(span.path))),
             runtimeEvidence,
             suggestedFiles,
-            coverage: {
-                counts: balanced.counts,
-                gaps: [...contextPackLanes
-                        .filter((lane) => balanced.counts[lane] === 0)
-                        .map((lane) => `No ${lane} evidence matched this request.`),
-                    ...(facts.some((fact) => fact.sourceAuthority === 'declared' && fact.extractionReview === 'unreviewed')
-                        ? ['Approved-source extraction remains unreviewed; verify cited intent before using it as a rule or gate.'] : [])],
-            },
+            coverage,
             diagnostics: selectDiagnostics(snapshot, request, facts, focus, queryDiagnostics),
             exploration: {
                 rankingVersion: IMPACT_RANKING_VERSION,

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)}`;
@@ -35,8 +36,19 @@ export class RdfEvidenceGraph {
                 snapshotId: fact.snapshotId, record: stableJson(fact),
                 ...(fact.sourceAuthority ? { sourceAuthority: fact.sourceAuthority } : {}),
                 ...(fact.extractionReview ? { extractionReview: fact.extractionReview } : {}),
+                ...(fact.sourceRole !== undefined ? { sourceRole: fact.sourceRole } : {}),
+                ...(fact.sourcePolicyDigest !== undefined ? { sourcePolicyDigest: fact.sourcePolicyDigest } : {}),
             }))
                 this.dataset.addQuad(record, iri(CG + p), literal(value));
+            if (fact.sourceOwnership !== undefined) {
+                this.dataset.addQuad(record, iri(CG + 'ownershipStatus'), literal(fact.sourceOwnership.status));
+                for (const ownerDocument of fact.sourceOwnership.ownerDocuments) {
+                    this.dataset.addQuad(record, iri(CG + 'ownerDocument'), literal(ownerDocument));
+                }
+                for (const mappingId of fact.sourceOwnership.mappingIds) {
+                    this.dataset.addQuad(record, iri(CG + 'ownershipMapping'), literal(mappingId));
+                }
+            }
             for (const [p, value] of [['startLine', fact.provenance.startLine], ['endLine', fact.provenance.endLine]]) {
                 this.dataset.addQuad(record, iri(CG + p), literal(String(value), iri(XSD + 'integer')));
             }
@@ -61,16 +73,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/shacl-shapes.js

@@ -24,4 +24,30 @@ cg:FactShape a sh:NodeShape; sh:targetClass rdf:Statement;
  sh:property [ sh:path cg:extractor; sh:minCount 1; sh:datatype xsd:string; sh:minLength 1 ].
 cg:NodeShape a sh:NodeShape; sh:targetClass cg:Node;
  sh:property [ sh:path cg:kind; sh:minCount 1; sh:maxCount 1 ].
+
+# Optional source metadata targets only assertions that carry those predicates.
+# Legacy facts do not acquire additional property or ownership consistency checks.
+cg:SourceRoleShape a sh:NodeShape; sh:targetSubjectsOf cg:sourceRole;
+ sh:property [ sh:path cg:sourceRole; sh:maxCount 1; sh:datatype xsd:string;
+   sh:in ("intent" "plan" "validation" "reference" "unclassified") ].
+cg:SourcePolicyShape a sh:NodeShape; sh:targetSubjectsOf cg:sourcePolicyDigest;
+ sh:property [ sh:path cg:sourcePolicyDigest; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ].
+cg:SourceOwnershipShape a sh:NodeShape;
+ sh:targetSubjectsOf cg:ownershipStatus, cg:ownerDocument, cg:ownershipMapping;
+ sh:property [ sh:path cg:ownershipStatus; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string;
+   sh:in ("resolved" "missing" "ambiguous" "unavailable" "unapproved" "ineligible" "not-required") ];
+ sh:property [ sh:path cg:ownerDocument; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:ownershipMapping; sh:datatype xsd:string; sh:minLength 1 ];
+ # Structural consistency does not prove approval, ownership correctness or source availability.
+ sh:or (
+   [ sh:property [ sh:path cg:ownershipStatus; sh:in ("resolved" "unavailable" "unapproved" "ineligible") ];
+     sh:property [ sh:path cg:ownerDocument; sh:minCount 1; sh:maxCount 1 ];
+     sh:property [ sh:path cg:ownershipMapping; sh:minCount 1 ] ]
+   [ sh:property [ sh:path cg:ownershipStatus; sh:hasValue "ambiguous" ];
+     sh:property [ sh:path cg:ownerDocument; sh:minCount 2 ];
+     sh:property [ sh:path cg:ownershipMapping; sh:minCount 1 ] ]
+   [ sh:property [ sh:path cg:ownershipStatus; sh:in ("missing" "not-required") ];
+     sh:property [ sh:path cg:ownerDocument; sh:maxCount 0 ];
+     sh:property [ sh:path cg:ownershipMapping; sh:maxCount 0 ] ]
+ ).
 `);

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>;

package/dist/graph/validation-progress.js

@@ -0,0 +1,18 @@
+/** Phase boundaries remain observable even when an operation blocks same-thread timers. */
+export async function measureValidationPhase(phase, counts, onProgress, operation) {
+    const started = performance.now();
+    const emit = (status) => onProgress?.({
+        phase, status, ...counts, elapsedMs: Math.max(0, Math.round(performance.now() - started)),
+    });
+    emit('started');
+    let result;
+    try {
+        result = await operation();
+    }
+    catch (error) {
+        emit('failed');
+        throw error;
+    }
+    emit('completed');
+    return result;
+}

package/dist/index.d.ts

@@ -13,3 +13,10 @@ export * from './application/hydration-plan.js';
 export * from './application/cache-adoption.js';
 export * from './application/hydration-failure.js';
 export * from './extraction/semantic-diagnostics.js';
+export * from './graph/identity-preflight.js';
+export * from './graph/validation-progress.js';
+export * from './application/document-coverage.js';
+export * from './extraction/document-traversal.js';
+export * from './extraction/document-classification.js';
+export * from './extraction/document-evidence.js';
+export type { DocumentTraversalConfig } from './configuration/document-traversal.js';

package/dist/index.js

@@ -14,3 +14,9 @@ export * from './application/hydration-plan.js';
 export * from './application/cache-adoption.js';
 export * from './application/hydration-failure.js';
 export * from './extraction/semantic-diagnostics.js';
+export * from './graph/identity-preflight.js';
+export * from './graph/validation-progress.js';
+export * from './application/document-coverage.js';
+export * from './extraction/document-traversal.js';
+export * from './extraction/document-classification.js';
+export * from './extraction/document-evidence.js';