@weftlet/toolkit 0.5.0 → 0.6.1

package/dist/extraction/static.js

@@ -1,7 +1,6 @@
 // Modified for standalone extraction; see docs/extraction-manifest.json.
-import { randomUUID } from 'node:crypto';
 import { withCommittedTree } from "../repository/committed-tree.js";
-import { copyFile, mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
+import { copyFile, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -13,6 +12,7 @@ import { moduleRequestNode } from './module-request.js';
 import { matchesRepositoryGlob } from "../repository/glob.js";
 import { runProcess } from "../infrastructure/process.js";
 import { sha256, stableJson } from "../infrastructure/util.js";
+import { physicalArtifactKey, temporaryArtifactPath } from '../infrastructure/artifact-paths.js';
 export class ScipTypeScriptIndexer {
     config;
     storageRoot;
@@ -26,9 +26,9 @@ export class ScipTypeScriptIndexer {
             assertSourceProjectInvocation(this.config.command, this.config.args);
         }
         const require = createRequire(import.meta.url);
-        const destination = join(this.storageRoot, 'scip', `${context.snapshotId}.scip`);
+        const destination = join(this.storageRoot, 'scip', `${physicalArtifactKey(context.snapshotId)}.scip`);
         await mkdir(join(this.storageRoot, 'scip'), { recursive: true });
-        const temporary = `${destination}.${randomUUID()}.tmp`;
+        const temporary = temporaryArtifactPath(destination);
         const command = this.config.command === 'bundled-scip-typescript' ? process.execPath : this.config.command;
         const args = this.config.command === 'bundled-scip-typescript'
             ? [
@@ -38,23 +38,28 @@ export class ScipTypeScriptIndexer {
                 temporary,
             ]
             : this.config.args;
-        await withCommittedTree(context.repositoryRoot, context.commitSha, async (worktreeRoot) => {
-            const project = this.config.sourceProject ? await prepareScipSourceProject(worktreeRoot, this.config.sourceProject, await new GitRepository(context.repositoryRoot).listAllFilesAt(context.commitSha)) : undefined;
-            await runProcess(command, project ? [...args, project] : args, worktreeRoot, {
-                ...process.env,
-                NODE_OPTIONS: process.env.NODE_OPTIONS ?? '--max-old-space-size=8192',
+        try {
+            await withCommittedTree(context.repositoryRoot, context.commitSha, async (worktreeRoot) => {
+                const project = this.config.sourceProject ? await prepareScipSourceProject(worktreeRoot, this.config.sourceProject, await new GitRepository(context.repositoryRoot).listAllFilesAt(context.commitSha)) : undefined;
+                await runProcess(command, project ? [...args, project] : args, worktreeRoot, {
+                    ...process.env,
+                    NODE_OPTIONS: process.env.NODE_OPTIONS ?? '--max-old-space-size=8192',
+                });
+                const source = this.config.command === 'bundled-scip-typescript'
+                    ? temporary
+                    : join(worktreeRoot, 'index.scip');
+                await stat(source);
+                if (source !== temporary)
+                    await copyFile(source, temporary);
+                // SCIP embeds this disposable checkout in metadata and inferred-type hover text.
+                // Store the normalized artifact itself so its digest still authenticates its bytes.
+                await writeFile(temporary, normalizeScipCheckout(await readFile(temporary), worktreeRoot));
             });
-            const source = this.config.command === 'bundled-scip-typescript'
-                ? temporary
-                : join(worktreeRoot, 'index.scip');
-            await stat(source);
-            if (source !== temporary)
-                await copyFile(source, temporary);
-            // SCIP embeds this disposable checkout in metadata and inferred-type hover text.
-            // Store the normalized artifact itself so its digest still authenticates its bytes.
-            await writeFile(temporary, normalizeScipCheckout(await readFile(temporary), worktreeRoot));
-        });
-        await rename(temporary, destination);
+            await rename(temporary, destination);
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
         return {
             path: destination,
             digest: sha256(await readFile(destination)),

package/dist/graph/authority.js

@@ -1,6 +1,9 @@
 export function contextPackEvidenceAuthority(fact) {
     if (fact.authority)
         return fact.authority;
+    // A document's role describes its source, not whether its claims were checked.
+    if (fact.sourceRole !== undefined)
+        return 'inferred';
     if (fact.extractor.id === 'otlp-runtime-evidence')
         return 'observed';
     if (fact.extractor.id.startsWith('codex-cli:'))

package/dist/graph/coverage.d.ts

@@ -0,0 +1,8 @@
+import { type ContextPackCoverage, type ContextPackLane, type GraphFact } from '@weftlet/core';
+export declare const contextPackLanes: readonly ContextPackLane[];
+export declare function isDeclaredFact(fact: GraphFact): boolean;
+export declare function contextPackLaneForFact(fact: GraphFact): ContextPackLane | undefined;
+export declare function coverageDescription(coverage: ContextPackCoverage): string;
+/** Reporting only: never changes a fact's authority, identity, primary lane or stored bytes. */
+export declare function isImplementationEvidence(fact: GraphFact): boolean;
+export declare function coverageForFacts(facts: readonly GraphFact[]): ContextPackCoverage;

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/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.js

@@ -36,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')));
             }

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

@@ -15,3 +15,8 @@ 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

@@ -16,3 +16,7 @@ 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';

package/dist/infrastructure/artifact-paths.d.ts

@@ -0,0 +1,4 @@
+/** Physical names only. Logical identities and evidence must retain the original value. */
+export declare function physicalArtifactKey(identity: string): string;
+/** Same-directory staging preserves atomic rename/link without repeating a long basename. */
+export declare function temporaryArtifactPath(destination: string): string;

package/dist/infrastructure/artifact-paths.js

@@ -0,0 +1,14 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+/** Physical names only. Logical identities and evidence must retain the original value. */
+export function physicalArtifactKey(identity) {
+    if (/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(identity) &&
+        !/^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(identity))
+        return identity;
+    // '~' is excluded from literal logical storage keys, so a digest cannot alias one.
+    return `~${createHash('sha256').update(identity).digest('hex')}`;
+}
+/** Same-directory staging preserves atomic rename/link without repeating a long basename. */
+export function temporaryArtifactPath(destination) {
+    return join(dirname(destination), `.${randomUUID()}.tmp`);
+}

package/dist/interfaces/cli.js

@@ -19,6 +19,7 @@ import { planHydration } from '../application/hydration-plan.js';
 import { adoptSemanticCache } from '../application/cache-adoption.js';
 import { SemanticHydrationError } from '../application/hydration-failure.js';
 import { GraphIdentityConflictError } from '../graph/identity-preflight.js';
+import { runDocumentCoverage } from './document-coverage.js';
 function valueAfter(args, name) {
     const index = args.indexOf(name);
     return index >= 0 ? args[index + 1] : undefined;
@@ -61,9 +62,23 @@ function formatHydrationPlan(plan) {
         `Expected cache reuse: ${plan.estimates.reusableArtifacts}; extractions: ${plan.estimates.extractions}; unknown cache entries: ${plan.estimates.unknownArtifacts}`,
         `Source/cache/budget checks: ${readiness}`,
     ];
+    if (plan.documentSelection) {
+        const selection = plan.documentSelection;
+        lines.push(`Document traversal: ${selection.complete ? 'complete' : 'blocked'}; identity ${selection.digest}; policy ${selection.policyDigest}`);
+        lines.push(`Discovered: ${selection.documentPaths.length}; semantic candidates: ${selection.semanticPaths.length}`);
+        for (const excluded of selection.excluded)
+            lines.push(`Excluded from model extraction: ${JSON.stringify(excluded.path)} (${excluded.reason}); retained traversal/evidence reporting.`);
+    }
+    if (plan.documentCoverage) {
+        const { limits, counters } = plan.documentCoverage.traversal;
+        lines.push(`Traversal reads: ${counters.readDocuments}/${limits.maxReadDocuments} documents; ${counters.readBytes}/${limits.maxReadBytes} bytes; ${limits.maxDocumentBytes} bytes maximum per document`);
+    }
     for (const document of plan.documents) {
         lines.push(`- ${JSON.stringify(document.path)} [${document.sourceId}]: ${document.bytes} bytes, ${document.lines} lines; ${document.role}; source ${document.sourceAuthority}, extraction ${document.extractionReview}; cache ${document.cache.status}; selected by ${document.selectedBy.map((selector) => JSON.stringify(selector)).join(', ')}`);
     }
+    for (const document of plan.documentCoverage?.classification.documents ?? []) {
+        lines.push(`Classification ${JSON.stringify(document.path)}: ${document.sourceRole}; owner ${document.ownership.status}; ${document.ownership.ownerDocuments.map(path => JSON.stringify(path)).join(', ')}`);
+    }
     for (const selection of plan.selections.filter((item) => item.status !== 'matched')) {
         lines.push(`Selection ${JSON.stringify(selection.selector)}: ${selection.status}`);
     }
@@ -83,9 +98,11 @@ function formatHydrationPlan(plan) {
 async function main() {
     const args = process.argv.slice(2);
     if (args.includes('--help') || !args.length) {
-        process.stdout.write('weftlet init|config show|config validate|doctor|hydrate|cache adopt|overlay|impact scan|sparql|validate|govern|visualize|diagnostics show|invariant check|clean-compare|ontology compile\nUse --config <file>; queries accept --snapshot <id>. impact scan accepts --changed-file, --capability, --max-facts, --max-depth, --continuation.\nhydrate --plan [--json] [--ref <commit>] [--force-semantic] previews scope, cache and budgets without model calls or graph writes. Preview readiness is advisory and does not add a hydration gate.\nhydrate --json --quiet emits structured semantic failures on stderr with no progress lines; failure stdout stays empty. hydrate --plan maps opaque source IDs to local document paths.\nhydrate|overlay --validation-details explicitly includes local node/fact identities, extractor names and source citations in identity-conflict errors; default reports use opaque references. This flag writes no diagnostic file. Use --json --quiet for structured identity-conflict stderr and empty failure stdout. Validation timings report phase boundaries, not a live heartbeat or percentage.\ncache adopt --from-config <previous.json> [--config <current.json>] [--ref <commit>] [--dry-run] returns JSON and copies only validated compatible artifacts, without model calls or snapshot writes. --dry-run performs no cache writes. Agent configurations accept the same --owner-doc, --task and --capability selection as hydrate.\ninit [--yes] [--directory <project>] [--config <file>] [--repository-id <id>] [--code-root <path>] [--semantic-source <path>] [--evidence-root <path>] [--model <name>] [--no-gitignore]\nSource flags may be repeated. init never overwrites an existing config. See README.md for examples.\n');
+        process.stdout.write('weftlet documents plan|init|config show|config validate|doctor|hydrate|cache adopt|overlay|impact scan|sparql|validate|govern|visualize|diagnostics show|invariant check|clean-compare|ontology compile\nUse --config <file>; queries accept --snapshot <id>. impact scan accepts --changed-file, --capability, --max-facts, --max-depth, --continuation.\ndocuments plan --entry <document> [--entry <document>] [--root <path>] [--document-policy <json-file>] [--ref <commit>] [--json] previews prospective committed link coverage; it does not change hydration inputs or estimate model/cache work. Source classification/ownership completeness is separate from traversal readiness. The preview policy is an operation input. Set documentTraversal in configuration to activate traversal hydration; hydrate --plan describes its execution inputs. Safety limits: --max-read-documents, --max-read-bytes, --max-document-bytes.\nhydrate --plan [--json] [--ref <commit>] [--force-semantic] previews scope, cache and budgets without model calls or graph writes. Traversal coverage and role ambiguity block new model work; direct-source selection retains its existing behavior.\nhydrate --json --quiet emits structured semantic failures on stderr with no progress lines; failure stdout stays empty. hydrate --plan maps opaque source IDs to local document paths.\nhydrate|overlay --validation-details explicitly includes local node/fact identities, extractor names and source citations in identity-conflict errors; default reports use opaque references. This flag writes no diagnostic file. Use --json --quiet for structured identity-conflict stderr and empty failure stdout. Validation timings report phase boundaries, not a live heartbeat or percentage.\ncache adopt --from-config <previous.json> [--config <current.json>] [--ref <commit>] [--dry-run] returns JSON and copies only validated compatible artifacts, without model calls or snapshot writes. --dry-run performs no cache writes. Agent configurations accept the same --owner-doc, --task and --capability selection as hydrate.\ninit [--yes] [--directory <project>] [--config <file>] [--repository-id <id>] [--code-root <path>] [--semantic-source <path>] [--evidence-root <path>] [--model <name>] [--no-gitignore]\nSource flags may be repeated. init never overwrites an existing config. See README.md for examples.\n');
         return;
     }
+    if (await runDocumentCoverage(args, defaultConfigPath))
+        return;
     if (args[0] === 'init') {
         await runInit(args.slice(1));
         return;

package/dist/interfaces/document-coverage.d.ts

@@ -0,0 +1,9 @@
+import { type DocumentCoverageOptions, type DocumentCoveragePlan } from '../application/document-coverage.js';
+export declare function parseDocumentCoverageArgs(args: readonly string[]): {
+    configPath?: string;
+    policyPath?: string;
+    json: boolean;
+    options: DocumentCoverageOptions;
+} | undefined;
+export declare function formatDocumentCoverage(plan: DocumentCoveragePlan): string;
+export declare function runDocumentCoverage(args: readonly string[], defaultConfig: () => string): Promise<boolean>;