@weftlet/toolkit 0.5.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/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/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>;

package/dist/interfaces/document-coverage.js

@@ -0,0 +1,117 @@
+import { planDocumentCoverage } from '../application/document-coverage.js';
+import { open } from 'node:fs/promises';
+import { parseDocumentClassificationPolicy } from '../extraction/document-classification.js';
+const traversalFlags = ['--entry', '--root', '--document-policy', '--max-read-documents', '--max-read-bytes', '--max-document-bytes'];
+const usage = 'Usage: weftlet documents plan --entry <document> [--entry <document>] [--root <path>] [--document-policy <json-file>] [--config <file>] [--ref <commit>] [--json] [--max-read-documents <count>] [--max-read-bytes <bytes>] [--max-document-bytes <bytes>]';
+export function parseDocumentCoverageArgs(args) {
+    if (args[0] !== 'documents') {
+        if (args.some(arg => traversalFlags.some(flag => arg === flag || arg.startsWith(`${flag}=`)))) {
+            throw new Error('Document traversal options are supported only by documents plan; they do not change hydration selection.');
+        }
+        return undefined;
+    }
+    if (args[1] !== 'plan')
+        throw new Error(usage);
+    const values = new Map();
+    let json = false;
+    for (let index = 2; index < args.length; index++) {
+        const flag = args[index];
+        if (flag === '--json') {
+            if (json)
+                throw new Error(usage);
+            json = true;
+            continue;
+        }
+        if (![...traversalFlags, '--config', '--ref'].includes(flag))
+            throw new Error(usage);
+        const value = args[++index];
+        if (!value || value.startsWith('--'))
+            throw new Error(usage);
+        if (values.has(flag) && flag !== '--entry' && flag !== '--root')
+            throw new Error(usage);
+        values.set(flag, [...(values.get(flag) ?? []), value]);
+    }
+    if (!values.has('--entry'))
+        throw new Error(usage);
+    const number = (flag) => {
+        const value = values.get(flag)?.[0];
+        if (value === undefined)
+            return undefined;
+        if (!/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(Number(value)))
+            throw new Error(`${flag} must be a positive integer`);
+        return Number(value);
+    };
+    return { configPath: values.get('--config')?.[0], policyPath: values.get('--document-policy')?.[0], json, options: {
+            entryPoints: values.get('--entry'), roots: values.get('--root'), ref: values.get('--ref')?.[0],
+            maxReadDocuments: number('--max-read-documents'), maxReadBytes: number('--max-read-bytes'),
+            maxDocumentBytes: number('--max-document-bytes'),
+        } };
+}
+export function formatDocumentCoverage(plan) {
+    const lines = [
+        `Prospective document coverage: ${plan.repositoryId}`,
+        `Commit: ${plan.commitSha} (requested ${JSON.stringify(plan.ref)})`,
+        `Configuration: ${plan.configurationDigest}; coverage: ${plan.coverageDigest}`,
+        'Hydration selection unchanged; no extraction/cache estimate.',
+        `Entry points: ${plan.entryPoints.map(path => JSON.stringify(path)).join(', ')}`,
+        `Roots: ${plan.roots.map(path => JSON.stringify(path)).join(', ')}`,
+        `Coverage: ${plan.coverage.complete ? 'complete within supported local scope' : 'incomplete'}; budget comparison: ${plan.budgets.withinLimits ? 'within limits' : 'blocked'}`,
+        `Source classification: ${plan.classification.complete ? 'complete' : 'gaps'}; policy: ${plan.classification.policyDigest}. This is separate from traversal/budget readiness.`,
+        `Discovered documents: ${plan.budgets.documents}/${plan.budgets.maxDocuments}; bytes: ${plan.budgets.bytes}; maximum per extraction source: ${plan.budgets.maxSourceBytes}`,
+        `Read limits: ${plan.limits.maxReadDocuments} documents, ${plan.limits.maxReadBytes} total bytes, ${plan.limits.maxDocumentBytes} bytes per document`,
+    ];
+    for (const document of plan.documents)
+        lines.push(`- ${JSON.stringify(document.path)}: ${document.status}, ${document.bytes} bytes; ${document.role}; role ${document.sourceRole} (${document.roleStatus}); source ${document.sourceAuthority}, extraction ${document.extractionReview}; owner ${document.ownership.status} ${document.ownership.ownerDocuments.map(path => JSON.stringify(path)).join(', ')}; ${document.entryPoint ? 'entry point' : 'linked document'}`);
+    for (const link of plan.links)
+        lines.push(`Link ${JSON.stringify(link.sourcePath)}:${link.startLine}-${link.endLine}: ${link.status}${link.path ? ` ${JSON.stringify(link.path)}` : ''}`);
+    for (const issue of plan.issues)
+        lines.push(`${issue.severity.toUpperCase()} [${issue.code}]: ${issue.message}`);
+    for (const issue of plan.classification.issues)
+        lines.push(`CLASSIFICATION ${issue.severity.toUpperCase()} [${issue.code}]: ${issue.message} ${issue.paths.map(path => JSON.stringify(path)).join(', ')}`);
+    if (plan.coverage.unvisited.length)
+        lines.push(`Unread frontier: ${plan.coverage.unvisited.map(path => JSON.stringify(path)).join(', ')}`);
+    if (plan.excludedWorkingChanges.length)
+        lines.push(`Working changes excluded: ${plan.excludedWorkingChanges.map(path => JSON.stringify(path)).join(', ')}`);
+    lines.push(...plan.assumptions.map(note => `Note: ${note}`));
+    return `${lines.join('\n')}\n`;
+}
+async function readDocumentPolicy(path) {
+    const handle = await open(path, 'r');
+    try {
+        const metadata = await handle.stat();
+        if (!metadata.isFile() || metadata.size > 65_536)
+            throw new Error('Document policy must be a JSON file of at most 65536 bytes');
+        const buffer = Buffer.alloc(65_537);
+        let length = 0;
+        while (length < buffer.length) {
+            const { bytesRead } = await handle.read(buffer, length, buffer.length - length, length);
+            if (!bytesRead)
+                break;
+            length += bytesRead;
+        }
+        if (length > 65_536)
+            throw new Error('Document policy exceeds 65536 bytes');
+        let parsed;
+        try {
+            parsed = JSON.parse(buffer.subarray(0, length).toString('utf8'));
+        }
+        catch {
+            throw new Error('Document policy must contain valid JSON');
+        }
+        return parseDocumentClassificationPolicy(parsed);
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function runDocumentCoverage(args, defaultConfig) {
+    const parsed = parseDocumentCoverageArgs(args);
+    if (!parsed)
+        return false;
+    const options = parsed.policyPath ? { ...parsed.options, documentPolicy: await readDocumentPolicy(parsed.policyPath) } : parsed.options;
+    const plan = await planDocumentCoverage(parsed.configPath ?? defaultConfig(), options);
+    process.stdout.write(parsed.json ? `${JSON.stringify(plan, null, 2)}\n` : formatDocumentCoverage(plan));
+    if (!plan.ready)
+        process.exitCode = 1;
+    return true;
+}

package/dist/repository/git.d.ts

@@ -8,6 +8,15 @@ export interface GitTextMatch {
     readonly path: string;
     readonly line: number;
 }
+/** Exact committed entries, relative to the configured repository root. */
+export interface GitTreeEntry {
+    readonly path: string;
+    readonly mode: string;
+    readonly type: 'blob' | 'tree' | 'commit';
+    readonly objectId: string;
+    /** Git blob size in bytes; directories and gitlinks have no size. */
+    readonly size?: number;
+}
 export declare class GitRepository {
     readonly root: string;
     constructor(root: string);
@@ -19,6 +28,8 @@ export declare class GitRepository {
     requireExactCleanCommit(commitSha: string): Promise<void>;
     listFilesAt(commitSha: string, roots: readonly string[]): Promise<readonly string[]>;
     listAllFilesAt(commitSha: string): Promise<readonly string[]>;
+    /** Read tree metadata without Git's quoted/newline path formatting or checkout access. */
+    listEntriesAt(commitSha: string): Promise<readonly GitTreeEntry[]>;
     readFileAt(commitSha: string, path: string): Promise<string>;
     findTextAt(commitSha: string, needles: readonly string[], roots: readonly string[]): Promise<readonly GitTextMatch[]>;
     delta(baseSha: string | undefined, headSha: string, roots: readonly string[]): Promise<GitDelta>;

package/dist/repository/git.js

@@ -2,6 +2,7 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { posix } from 'node:path';
+import { isUtf8 } from 'node:buffer';
 import { sha256, slug } from "../infrastructure/util.js";
 const execFileAsync = promisify(execFile);
 export class GitRepository {
@@ -73,6 +74,43 @@ export class GitRepository {
     listAllFilesAt(commitSha) {
         return this.listFilesAt(commitSha, ['.']);
     }
+    /** Read tree metadata without Git's quoted/newline path formatting or checkout access. */
+    async listEntriesAt(commitSha) {
+        const commit = await this.resolveRef(commitSha);
+        // :./ selects the committed subtree at cwd; --full-tree makes output relative to
+        // that subtree rather than applying cwd's prefix a second time in a nested project.
+        const { stdout } = await execFileAsync('git', ['ls-tree', '-r', '-t', '-l', '-z', '--full-tree', `${commit}:./`], {
+            cwd: this.root, encoding: 'buffer', maxBuffer: 64 * 1024 * 1024, windowsHide: true,
+        });
+        if (!isUtf8(stdout))
+            throw new Error('Git tree entry paths are not valid UTF-8');
+        const output = stdout.toString('utf8');
+        if (!output)
+            return [];
+        if (!output.endsWith('\0'))
+            throw new Error('Malformed NUL-delimited Git tree listing');
+        const seen = new Set();
+        const entries = output.slice(0, -1).split('\0').map((record) => {
+            const match = /^([0-7]{6}) (blob|tree|commit) ([a-f0-9]{40}|[a-f0-9]{64}) +([0-9]+|-)\t([\s\S]+)$/.exec(record);
+            if (!match)
+                throw new Error('Malformed Git tree entry metadata');
+            const mode = match[1];
+            const type = match[2];
+            const objectId = match[3];
+            const rawSize = match[4];
+            const path = match[5];
+            const size = rawSize === '-' ? undefined : Number(rawSize);
+            const validMode = type === 'blob' ? ['100644', '100755', '120000'].includes(mode)
+                : mode === (type === 'tree' ? '040000' : '160000');
+            if (!validMode || (type === 'blob' ? size === undefined || !Number.isSafeInteger(size) || size < 0 : size !== undefined) ||
+                path.startsWith('/') || path.split('/').some(part => !part || part === '.' || part === '..') || seen.has(path)) {
+                throw new Error('Malformed Git tree entry mode, size or path');
+            }
+            seen.add(path);
+            return { path, mode, type, objectId, ...(size === undefined ? {} : { size }) };
+        });
+        return entries.sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+    }
     readFileAt(commitSha, path) {
         // Git object paths are top-level-relative unless explicitly prefixed with ./.
         return this.execute(['show', `${commitSha}:./${path}`], false);