@weftlet/toolkit 0.5.0 → 0.6.1

package/README.md

@@ -13,6 +13,10 @@ Proposed future capabilities are recorded in the [Weftlet 2.0 product plan](docs
 
 ## Set up a project
 
+<!-- weftlet:release:start -->
+Package versions in this checkout/archive: `@weftlet/toolkit@0.6.1` and `@weftlet/core@0.6.1`.
+<!-- weftlet:release:end -->
+
 Weftlet uses `@weftlet/toolkit`; its neutral `@weftlet/core` dependency is installed
 automatically. Both packages are available on npm.
 See [release status](docs/RELEASING.md). Existing Tently users should follow
@@ -80,7 +84,7 @@ pnpm exec weftlet hydrate --plan --json --config /path/to/project/context-graph.
 The human summary and JSON identify the resolved commit, current local configuration, selected
 documents and inclusion reasons, UTF-8 byte sizes, source approval, expected cache reuse and
 extraction counts, budget violations, and working changes excluded from the committed input.
-Selection uses configured repository file/directory paths; `approvedIntentSources` uses its
+Direct-mode selection uses configured repository file/directory paths; `approvedIntentSources` uses its
 separate glob matcher. An explicit empty semantic source list selects no documents, fixing the
 earlier accidental expansion to the whole repository.
 
@@ -96,9 +100,9 @@ and existing agent-selection limits are warnings; they do not add a new hydratio
 would prevent removing the last document and invalidating its relationships. All selected
 documents remain visible when budgets are exceeded.
 
-Source approval does not approve model assertions. Validation-document labels reflect configured
-evidence roots; selected validation documents still undergo semantic extraction today. Recursive
-SOT traversal and default validation-document separation remain T07 work. See
+Source approval does not approve model assertions. In direct mode, validation-document labels
+reflect configured evidence roots and selected validation documents still undergo semantic
+extraction. The opt-in traversal mode below excludes them by default. See
 [ADR 016](docs/ADR-016-hydration-preview.md) and the [1.0 task list](docs/RELEASE-1.0-PLAN.md).
 
 Starting with **0.4.0**, preview also maps opaque diagnostic source IDs to local paths. Semantic
@@ -107,6 +111,119 @@ their structured report on stderr. Built-in Codex can reuse completed artifacts
 operational changes such as increasing a timeout. See [provider recovery](docs/PROVIDERS.md#limits-and-reuse)
 for preview, retry and explicit legacy-cache adoption instructions.
 
+## Preview linked document coverage
+
+This checkout/archive includes a separate prospective preview. npm 0.5.0 does not include this command:
+
+```sh
+pnpm exec weftlet documents plan --entry docs/sot.md --entry docs/roadmap.md --root docs --ref HEAD
+pnpm exec weftlet documents plan --entry docs/sot.md --root docs --ref HEAD --json
+```
+
+Use your repository's exact committed entry paths. `--root` may repeat and defaults to the
+repository root. The operation follows supported Markdown links with cycle protection and
+deduplication, records citations and exclusions, and reports missing/ambiguous targets. Paths,
+approval matches and validation-evidence labels remain explicit; following a link never approves
+its contents. Git objects supply the input even while the checkout is dirty.
+
+This reports prospective coverage and **does not change hydration inputs or estimate cache/model
+work**. Continue using `hydrate --plan` for the current execution plan. This command does not modify configuration.
+Existing semantic document/byte budgets are compared after traversal, including validation
+documents. Independent read limits (`--max-read-documents`, `--max-read-bytes`,
+`--max-document-bytes`) leave an explicit unread frontier if reached. Incomplete coverage or
+exceeded extraction budgets return a report with exit status 1, without model calls or graph writes.
+The preview follows only supported local links; complete coverage is not a claim of complete
+product knowledge. See [ADR 023](docs/ADR-023-document-coverage-preview.md) for limits and the
+prospective-operation boundaries.
+
+The preview also accepts an optional JSON source policy:
+
+```sh
+pnpm exec weftlet documents plan --entry docs/sot.md --root docs --document-policy document-policy.json --json
+```
+
+```json
+{
+  "schemaVersion": 1,
+  "roles": [
+    { "id": "intent", "pattern": "docs/sot.md", "role": "intent" },
+    { "id": "plans", "pattern": "docs/plans/**", "role": "plan" },
+    { "id": "checks", "pattern": "docs/validation/**", "role": "validation" }
+  ],
+  "owners": [
+    { "id": "sot-owner", "pattern": "docs/**", "ownerDocument": "docs/sot.md" }
+  ]
+}
+```
+
+Roles are `intent`, `plan`, `validation` or `reference`; unmatched sources are `unclassified`
+unless configured evidence roots or approved intent sources provide a default. The owner must
+be read within the selected coverage, match `approvedIntentSources`, and have an unambiguous
+intent role. Owner mappings and links never transfer approval to another source or approve an
+assertion. Conflicting mappings remain explicit gaps.
+
+This file is an operation input, separate from `context-graph.config.json`. `ready` and the
+exit status still describe traversal and budget checks; inspect `classification.complete` and
+its issues for role/ownership gaps. The policy does not change current hydration or cache inputs.
+The public `extractDocumentEvidence` API separately emits cited document-presence and reference
+facts, including empty validation documents, without interpreting prose or treating a written
+“PASS” as proof that a test ran. Queries, RDF/SHACL and the viewer preserve its source metadata.
+See [ADR 025](docs/ADR-025-document-classification.md) for the contract and limits.
+
+## Hydrate linked SOT and roadmap documents
+
+This checkout/archive adds opt-in traversal hydration; npm 0.5.0 does not support it. Merge this
+fragment into your normal configuration, using real committed entry paths and reviewed owner
+mappings. Keep the existing `semanticSources` array for direct-mode compatibility; traversal
+replaces its selection when enabled.
+
+```json
+{
+  "documentTraversal": {
+    "entryPoints": ["docs/sot.md", "docs/roadmap.md"],
+    "roots": ["docs"],
+    "maxReadDocuments": 1000,
+    "maxReadBytes": 16777216,
+    "maxDocumentBytes": 1048576,
+    "policy": {
+      "schemaVersion": 1,
+      "roles": [
+        { "id": "intent", "pattern": "docs/sot.md", "role": "intent" },
+        { "id": "plans", "pattern": "docs/roadmap.md", "role": "plan" },
+        { "id": "checks", "pattern": "docs/validation/**", "role": "validation" }
+      ],
+      "owners": [
+        { "id": "product-owner", "pattern": "docs/**", "ownerDocument": "docs/sot.md" }
+      ]
+    }
+  }
+}
+```
+
+Review `approvedIntentSources` separately: an owner must already be explicitly approved. Preview
+with `weftlet hydrate --plan --json`, then run `weftlet hydrate --ref HEAD` after reviewing scope
+and cost. The plan reports all discovered documents, roles, ownership, exclusions, read limits,
+semantic budgets and expected artifact reuse. Validation documents receive presence/reference
+facts without model calls. `semantic.maxDocuments` and `maxSourceBytes` apply to semantic candidates;
+traversal read limits apply to every read document. Broken/ambiguous links, incomplete reads, role
+ambiguity or exceeded budgets stop new model work rather than silently trimming coverage.
+
+Ownership gaps remain diagnostics. Reaching an owner, choosing an intent role or reading an
+approved source never approves a model assertion. Plans/unclassified sources remain explicitly
+labeled, and model facts remain inferred/unreviewed. Complete coverage means the configured
+canonical links were followed, not that every product rule was found.
+
+Built-in Codex can reuse unchanged artifacts when enabling traversal or editing its policy/read
+limits. Role/owner metadata is assembled without rewriting those artifacts. Custom module
+providers use a separate full-config cache. Snapshots bind the configuration and selection, while
+old snapshots remain queryable. Draft overlays recompute reachability, invalidate changed sources
+and owners, and label incomplete coverage without making model calls.
+
+Traversal cannot be combined with `agentContext` or a direct programmatic source override; saved
+impact queries still accept owner/task filters. `documents plan` remains a prospective operation;
+its sidecar policy is not automatically adopted by hydration. See
+[ADR 026](docs/ADR-026-traversal-hydration.md) for identity, compatibility and limits.
+
 ## SHACL validation and performance
 
 Starting with **0.5.0**, identity preflight runs before ontology/RDF work.
@@ -143,10 +260,14 @@ pnpm build
 pnpm benchmark:shacl
 ```
 
-Current hydration progress reports phase boundaries. The validator performs synchronous work,
-so an ordinary timer cannot provide an honest heartbeat while that work blocks Node's main
-thread. Worker-based progress, validation-result reuse and incremental
-validation remain separate T05 work; they do not delay the focused cold-validation release.
+The [T05 closeout](docs/ADR-027-validation-closeout.md) measures cold, repeated and changed inputs,
+plus worker, exact-result-key and Rust prototypes. Direct full validation remains the 1.0 choice:
+the 10,000-fact public cases measured about 2.9–5.7 seconds, with material memory use. These are
+fixture measurements, not a private consumer capacity guarantee. The prototypes are development
+tools, not runtime options; every hydration still performs full validation. Current progress reports
+phase boundaries because synchronous work blocks same-thread timers. Reproduce the lifecycle study
+from a development checkout with `pnpm benchmark:validation`; raw results and commands are linked
+from the ADR.
 
 ## Development
 
@@ -214,12 +335,9 @@ Each committed JSON record names a scoped binding and exact producer/consumer fi
 are cited candidate dependencies; they do not assert an approved policy or observed delivery.
 
 Install the locally packed core and toolkit tarballs together. The installed commands are
-`weftlet`, `weftlet-mcp`, and the compatible `context-graph` / `context-graph-mcp` aliases. For example, after preparing a release, replace `<version>` with the version in `.release/manifest.json`:
-
-```sh
-npm install --save-dev "/path/to/weftlet/.release/weftlet-core-<version>.tgz" "/path/to/weftlet/.release/weftlet-toolkit-<version>.tgz"
-npx weftlet init
-```
+`weftlet`, `weftlet-mcp`, and the compatible `context-graph` / `context-graph-mcp` aliases.
+Use the [versioned installation examples](docs/RELEASING.md#inspecting-and-consuming-releases)
+generated for this checkout/archive; then run `npx weftlet init`.
 
 Pass `--config /absolute/path/context-graph.config.json`
 to the CLI or set `CONTEXT_GRAPH_CONFIG` for MCP. No launcher rebuild is required for installed
@@ -248,6 +366,13 @@ ahead of repeated detail and shared-import context. Ranking changes ordering, no
 the reachable scope. Responses identify the ranking version; after a ranking upgrade, restart
 scans whose old continuation tokens are rejected. No snapshot refresh is needed for new ordering.
 
+This source includes a [coverage reporting correction](docs/ADR-024-implementation-coverage.md)
+for the next release: code relationships displayed under contracts also count as implementation
+evidence. New reports identify `coverage.scope: "returned-page"` and `countsAreNonExclusive: true`.
+Counts can overlap and describe returned evidence; they are not completeness percentages or proof
+that behavior is correct. Document/model claims and test-only evidence do not establish production
+implementation. The reporting fix works with saved snapshots without another hydration.
+
 [Relative import evidence](docs/ADR-013-relative-module-requests.md) now scopes module requests
 to the importing directory. An explicit refresh applies this extraction fix; saved snapshots
 keep their original facts. These requests remain unresolved evidence, while SCIP supplies

package/dist/application/cache-adoption.d.ts

@@ -1,4 +1,4 @@
-import type { ImpactScanRequest } from '@weftlet/core';
+import type { DocumentSelectionRecord, ImpactScanRequest } from '@weftlet/core';
 import { type SemanticInputIssue, type SemanticSelection } from '../extraction/semantic-sources.js';
 import { type SemanticScope } from './semantic-scope.js';
 export interface SemanticCacheAdoptionOptions {
@@ -28,6 +28,7 @@ export interface SemanticCacheAdoption {
         readonly complete: boolean;
     };
     readonly records: readonly SemanticCacheAdoptionRecord[];
+    readonly documentSelection?: DocumentSelectionRecord;
     readonly counts: Readonly<Record<SemanticCacheAdoptionStatus, number>>;
     readonly selections: readonly SemanticSelection[];
     readonly budgets: {

package/dist/application/cache-adoption.js

@@ -2,10 +2,10 @@ import { loadConfig } from '../configuration/config.js';
 import { resolveSemanticStorageRoots, resolveStorageRoot, semanticCachePartition } from '../configuration/cache.js';
 import { inspectSemanticCache } from '../extraction/semantic-cache.js';
 import { semanticProviderIdentity } from '../extraction/semantic-identity.js';
-import { selectSemanticInputs } from '../extraction/semantic-sources.js';
 import { sha256, stableJson } from '../infrastructure/util.js';
 import { GitRepository } from '../repository/git.js';
 import { SemanticArtifactStore } from '../storage/storage.js';
+import { selectHydrationInputs } from './hydration-inputs.js';
 import { resolveSemanticScope } from './semantic-scope.js';
 const problemStatuses = new Set(['corrupt', 'unavailable', 'conflict']);
 function problem(inspection, source, location) {
@@ -67,6 +67,11 @@ async function publishCandidate(candidate, config, identity, current) {
     return { ...candidate.record, status: 'adopted',
         reason: 'Validated artifact is available in the current cache; the previous artifact is unchanged.' };
 }
+function previousArtifactRoot(repositoryRoot, config) {
+    // Traverse only the explicitly named module namespace; direct/Codex recovery retains legacy conflict checks.
+    return config.documentTraversal && config.semantic.provider === 'module'
+        ? resolveSemanticStorageRoots(repositoryRoot, config).primary : resolveStorageRoot(repositoryRoot, config);
+}
 /** Explicitly adopts only committed-source artifacts from a compatible, named legacy profile. */
 export async function adoptSemanticCache(configPath, options) {
     const [loaded, previous] = await Promise.all([loadConfig(configPath), loadConfig(options.fromConfigPath)]);
@@ -81,10 +86,11 @@ export async function adoptSemanticCache(configPath, options) {
     const ref = options.ref ?? 'HEAD';
     const commitSha = await repository.resolveRef(ref);
     const scope = await resolveSemanticScope(config, repository, commitSha, options.request);
-    const selection = await selectSemanticInputs(repository, commitSha, scope.selectors, config.semantic);
+    const selection = await selectHydrationInputs(repository, commitSha, config, scope.selectors);
     const issues = [...selection.issues];
     const limited = scope.omittedDocuments.length > 0 || scope.ignoredSearchTerms > 0;
-    const complete = !limited && selection.selections.every((item) => item.status === 'matched');
+    const complete = !limited && selection.selections.every((item) => item.status === 'matched') &&
+        (selection.documentSelection?.complete ?? true);
     if (limited)
         issues.push({ code: 'selection-limited', severity: 'warning',
             message: `Existing agent selection limits omitted ${scope.omittedDocuments.length} documents and ${scope.ignoredSearchTerms} search terms; adoption describes only the selected scope.`,
@@ -95,7 +101,7 @@ export async function adoptSemanticCache(configPath, options) {
         const current = new SemanticArtifactStore(resolveSemanticStorageRoots(repositoryRoot, config).primary);
         // Do not scan sibling profiles or infer ownership from an artifact key. The
         // supplied old configuration proves the exact legacy location to inspect.
-        const old = new SemanticArtifactStore(resolveStorageRoot(repositoryRoot, previous.config));
+        const old = new SemanticArtifactStore(previousArtifactRoot(repositoryRoot, previous.config));
         const identity = semanticProviderIdentity(config.semantic);
         for (const source of selection.sources) {
             const candidate = await inspectCandidate(source, config.semantic, identity, old, current);
@@ -117,9 +123,10 @@ export async function adoptSemanticCache(configPath, options) {
         ref, commitSha, configurationDigest: sha256(stableJson(config)),
         previousConfigurationDigest: sha256(stableJson(previous.config)), dryRun,
         ready: complete && !issues.some((issue) => issue.severity === 'error'), scope: { ...scope, complete },
+        ...(selection.documentSelection ? { documentSelection: selection.documentSelection } : {}),
         records, counts, selections: selection.selections, budgets: selection.budgets, issues,
         assumptions: [
-            'Selection uses the same configured or bounded agent scope as hydration planning at the resolved commit; only expected keys in the explicitly named previous profile are inspected.',
+            'Selection uses the same configured, traversal or bounded agent scope as hydration planning at the resolved commit; only expected keys in the explicitly named previous profile are inspected.',
             'Missing or incomplete previous artifacts need later extraction. Corrupt or conflicting complete artifacts are retained for diagnosis.',
             'Adoption preserves original artifact identity and provenance; it does not validate or publish a current snapshot.',
             'Artifacts are adopted independently; earlier valid copies remain available if a later artifact or storage operation fails.',

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

@@ -0,0 +1,28 @@
+import { type DocumentTraversalOptions, type DocumentTraversalReport } from '../extraction/document-traversal.js';
+import { type DocumentClassification, type DocumentClassificationPolicy, type DocumentClassificationReport } from '../extraction/document-classification.js';
+export interface DocumentCoverageOptions extends Omit<DocumentTraversalOptions, 'maxDocuments' | 'maxSourceBytes'> {
+    readonly ref?: string;
+    readonly documentPolicy?: DocumentClassificationPolicy;
+}
+export interface DocumentCoveragePlan extends Omit<DocumentTraversalReport, 'documents'> {
+    readonly schemaVersion: 1;
+    readonly kind: 'document-coverage-plan';
+    readonly mode: 'prospective';
+    readonly changesHydrationSelection: false;
+    readonly repositoryId: string;
+    readonly ref: string;
+    readonly commitSha: string;
+    readonly configurationDigest: string;
+    readonly coverageDigest: string;
+    /** Traversal and budget readiness only; classification is reported independently. */
+    readonly ready: boolean;
+    readonly classification: DocumentClassificationReport;
+    readonly documents: readonly (DocumentTraversalReport['documents'][number] & DocumentClassification & {
+        readonly role: 'semantic-document' | 'validation-evidence';
+        readonly extractionReview: 'unreviewed';
+    })[];
+    readonly excludedWorkingChanges: readonly string[];
+    readonly assumptions: readonly string[];
+}
+/** Read committed links only. This does not initialize execution, inspect caches or change selection. */
+export declare function planDocumentCoverage(configPath: string, options: DocumentCoverageOptions): Promise<DocumentCoveragePlan>;

package/dist/application/document-coverage.js

@@ -0,0 +1,58 @@
+import { loadConfig } from '../configuration/config.js';
+import { GitRepository } from '../repository/git.js';
+import { sha256, stableJson } from '../infrastructure/util.js';
+import { traverseDocuments } from '../extraction/document-traversal.js';
+import { classifyDocumentSources, parseDocumentClassificationPolicy } from '../extraction/document-classification.js';
+function classifyKnownDocuments(paths, context, policy) {
+    // Traversal bounds reads, not its discovered frontier. Preserve every known path while each
+    // classifier call stays bounded; all batches see the same complete set of read owners.
+    const ordered = [...paths].sort();
+    const batchSize = 1000;
+    const first = classifyDocumentSources(ordered.slice(0, batchSize), context, policy);
+    const documents = [...first.documents];
+    const issues = [...first.issues];
+    for (let offset = batchSize; offset < ordered.length; offset += batchSize) {
+        const batch = classifyDocumentSources(ordered.slice(offset, offset + batchSize), context, policy);
+        documents.push(...batch.documents);
+        issues.push(...batch.issues);
+    }
+    return { policyDigest: first.policyDigest, documents, issues, complete: !issues.length };
+}
+/** Read committed links only. This does not initialize execution, inspect caches or change selection. */
+export async function planDocumentCoverage(configPath, options) {
+    const { config, repositoryRoot } = await loadConfig(configPath);
+    const documentPolicy = parseDocumentClassificationPolicy(options.documentPolicy ?? { schemaVersion: 1 });
+    const repository = new GitRepository(repositoryRoot);
+    const ref = options.ref ?? 'HEAD';
+    const commitSha = await repository.resolveRef(ref);
+    const traversal = await traverseDocuments(repository, commitSha, {
+        entryPoints: options.entryPoints, roots: options.roots,
+        maxReadDocuments: options.maxReadDocuments, maxReadBytes: options.maxReadBytes,
+        maxDocumentBytes: options.maxDocumentBytes,
+        maxDocuments: config.semantic.maxDocuments ?? 8, maxSourceBytes: config.semantic.maxSourceBytes ?? 65_536,
+    });
+    const classification = classifyKnownDocuments(traversal.documents.map(document => document.path), {
+        approvedIntentSources: config.approvedIntentSources ?? [], evidenceRoots: config.evidenceRoots,
+        availableDocuments: traversal.documents.filter(document => document.status === 'read').map(document => document.path),
+    }, documentPolicy);
+    const classified = new Map(classification.documents.map(document => [document.path, document]));
+    const documents = traversal.documents.map(document => ({ ...document, ...classified.get(document.path),
+        role: classified.get(document.path).sourceRole === 'validation' ? 'validation-evidence' : 'semantic-document',
+        extractionReview: 'unreviewed' }));
+    return { ...traversal, documents, schemaVersion: 1, kind: 'document-coverage-plan', mode: 'prospective',
+        changesHydrationSelection: false, repositoryId: config.repositoryId, ref, commitSha,
+        configurationDigest: sha256(stableJson(config)), classification,
+        coverageDigest: sha256(stableJson({ commitSha, traversal, documents, classification })),
+        ready: traversal.coverage.complete && traversal.budgets.withinLimits,
+        excludedWorkingChanges: await repository.workingChanges(),
+        assumptions: [
+            'This is prospective document coverage, not the hydration execution plan. It changes no configuration or hydration inputs and estimates no cache reuse, model calls, tokens or cost.',
+            'Documents and link citations come from the resolved commit; configuration, document policy and excluded working changes describe current operation inputs.',
+            'Complete covers supported local document links inside the requested scope. External links, fragments and resolved non-document files are reported but not traversed; this does not prove complete product coverage.',
+            'Extraction budgets compare all discovered documents, including validation evidence. Safety limits can leave an explicit unread frontier; undiscovered descendants then remain unknown.',
+            'Ready describes traversal and budget checks only. Classification completeness is separate; unresolved roles or ownership are evidence gaps, not proven business-rule violations or approved intent.',
+            'Roles use explicit document policy and configured defaults. Ownership maps require a read, approved intent owner. Neither approval nor ownership transfers through links or approves individual assertions.',
+            'No provider, adapter, indexer, runtime source or graph validator was initialized. No cache, snapshot or source document was written.',
+            'Use hydrate --plan for current extraction inputs and cache estimates. The standalone document-evidence API is available; connecting classification and validation separation to hydration remains T07c.',
+        ] };
+}

package/dist/application/document-overlay.d.ts

@@ -0,0 +1,14 @@
+import type { ContextGraphConfig } from '../configuration/config.js';
+import type { DocumentSelectionRecord, GraphFact } from '@weftlet/core';
+import type { HydrationInputs } from './hydration-inputs.js';
+/** Retain only unchanged, still-reachable assertions with unchanged source ownership. */
+export declare function retainOverlayDocumentFact(fact: GraphFact, inputs: HydrationInputs | undefined, affected: ReadonlySet<string>): boolean;
+export declare function overlayDocumentRoots(config: Pick<ContextGraphConfig, 'documentTraversal'>): readonly string[];
+export declare function overlayDocumentManifest(selection?: DocumentSelectionRecord): {
+    documentSelection: DocumentSelectionRecord;
+    scope: readonly string[];
+} | {
+    documentSelection?: undefined;
+    scope?: undefined;
+};
+export declare function overlayDocumentNotes(config: Pick<ContextGraphConfig, 'documentTraversal'>): readonly string[];

package/dist/application/document-overlay.js

@@ -0,0 +1,31 @@
+import { documentEvidenceExtractorIdentity } from '../extraction/document-evidence.js';
+import { stableJson } from '../infrastructure/util.js';
+/** Retain only unchanged, still-reachable assertions with unchanged source ownership. */
+export function retainOverlayDocumentFact(fact, inputs, affected) {
+    if (!inputs?.documentSelection)
+        return true;
+    if (fact.extractor.id === documentEvidenceExtractorIdentity.id)
+        return false;
+    if (!/\.(?:md|mdx|txt)$/i.test(fact.provenance.path))
+        return true;
+    if (!inputs.documentSelection.complete)
+        return false;
+    const source = inputs.sources.find(source => source.path === fact.provenance.path);
+    const classification = inputs.documentEvidence?.classification.documents.find(document => document.path === fact.provenance.path);
+    return Boolean(source && classification && source.digest === fact.provenance.digest &&
+        fact.sourceRole === classification.sourceRole &&
+        fact.sourcePolicyDigest === inputs.documentSelection.policyDigest &&
+        stableJson(fact.sourceOwnership) === stableJson(classification.ownership) &&
+        !classification.ownership.ownerDocuments.some(path => affected.has(path)));
+}
+export function overlayDocumentRoots(config) {
+    return config.documentTraversal ? config.documentTraversal.roots ?? ['.'] : [];
+}
+export function overlayDocumentManifest(selection) {
+    return selection ? { documentSelection: selection, scope: selection.documentPaths } : {};
+}
+export function overlayDocumentNotes(config) {
+    return config.documentTraversal ? [
+        'Document traversal was recomputed from captured drafts. Changed/unreachable sources and changed owners invalidate prior semantic assertions; incomplete coverage invalidates all retained document assertions.',
+    ] : [];
+}

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

@@ -1,6 +1,7 @@
 import type { ContextGraphConfig } from '../configuration/config.js';
 export declare const graphAssemblyVersion = 7;
 export declare const graphAssemblyIdentity = "standalone-graph-v7";
+export declare function documentExtractionVersions(config?: Pick<ContextGraphConfig, 'documentTraversal'>): Readonly<Record<string, string>>;
 /** Runtime expectations are separate from source/configuration identity and artifact reuse. */
-export declare function requiredSnapshotExtractorVersions(config?: Pick<ContextGraphConfig, 'routingSources'>): Readonly<Record<string, string>>;
+export declare function requiredSnapshotExtractorVersions(config?: Pick<ContextGraphConfig, 'routingSources' | 'documentTraversal'>): Readonly<Record<string, string>>;
 export declare function incompatibleSnapshotExtractors(actual: Readonly<Record<string, string>> | undefined, expected: Readonly<Record<string, string>>): readonly string[];

package/dist/application/extraction-identity.js

@@ -1,10 +1,17 @@
 import { repositoryContractExtractorIdentity, scipSymbolExtractorIdentity } from '../extraction/static.js';
 import { routingExtractorIdentity } from '../extraction/routing.js';
+import { documentEvidenceExtractorIdentity } from '../extraction/document-evidence.js';
+import { documentSelectionIdentity } from './hydration-inputs.js';
 export const graphAssemblyVersion = 7;
 export const graphAssemblyIdentity = `standalone-graph-v${graphAssemblyVersion}`;
+export function documentExtractionVersions(config) {
+    return config?.documentTraversal ? { 'document-selection': documentSelectionIdentity,
+        [documentEvidenceExtractorIdentity.id]: documentEvidenceExtractorIdentity.version } : {};
+}
 /** Runtime expectations are separate from source/configuration identity and artifact reuse. */
 export function requiredSnapshotExtractorVersions(config) {
     return { assembly: graphAssemblyIdentity,
+        ...documentExtractionVersions(config),
         [repositoryContractExtractorIdentity.id]: repositoryContractExtractorIdentity.version,
         [scipSymbolExtractorIdentity.id]: scipSymbolExtractorIdentity.version,
         ...(config?.routingSources?.length ? { [routingExtractorIdentity.id]: routingExtractorIdentity.version } : {}),

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

@@ -0,0 +1,15 @@
+import type { DocumentSelectionRecord, GraphFact } from '@weftlet/core';
+import type { ContextGraphConfig } from '../configuration/config.js';
+import type { GitRepository } from '../repository/git.js';
+import { selectSemanticInputs } from '../extraction/semantic-sources.js';
+import { extractDocumentEvidence } from '../extraction/document-evidence.js';
+export declare const documentSelectionIdentity = "document-selection-v1";
+export type DocumentEvidence = Awaited<ReturnType<typeof extractDocumentEvidence>>;
+export type HydrationInputs = Awaited<ReturnType<typeof selectSemanticInputs>> & {
+    readonly documentEvidence?: DocumentEvidence;
+    readonly documentSelection?: DocumentSelectionRecord;
+};
+/** One committed selection for preview, hydration and explicit cache adoption. No execution dependencies. */
+export declare function selectHydrationInputs(repository: GitRepository, commitSha: string, config: ContextGraphConfig, selectors?: readonly string[]): Promise<HydrationInputs>;
+/** Assembly metadata is deliberately outside immutable provider artifacts. */
+export declare function classifyHydratedFacts(facts: readonly GraphFact[], evidence?: DocumentEvidence): readonly GraphFact[];

package/dist/application/hydration-inputs.js

@@ -0,0 +1,55 @@
+import { selectSemanticInputs } from '../extraction/semantic-sources.js';
+import { extractDocumentEvidence } from '../extraction/document-evidence.js';
+import { sha256, stableJson } from '../infrastructure/util.js';
+export const documentSelectionIdentity = 'document-selection-v1';
+/** One committed selection for preview, hydration and explicit cache adoption. No execution dependencies. */
+export async function selectHydrationInputs(repository, commitSha, config, selectors = config.semanticSources) {
+    if (!config.documentTraversal)
+        return selectSemanticInputs(repository, commitSha, selectors, config.semantic);
+    const context = { repositoryRoot: repository.root, repositoryId: config.repositoryId,
+        ref: commitSha, commitSha, snapshotId: commitSha, changedPaths: [], deletedPaths: [], renamedPaths: {} };
+    const evidence = await extractDocumentEvidence(repository, context, {
+        ...config.documentTraversal, documentPolicy: config.documentTraversal.policy,
+        // Traversal reads have their own limits; semantic budgets are applied after role exclusion below.
+        maxDocuments: 10_000, maxSourceBytes: 4 * 1024 * 1024,
+        approvedIntentSources: config.approvedIntentSources, evidenceRoots: config.evidenceRoots,
+    });
+    const classified = new Map(evidence.classification.documents.map(document => [document.path, document]));
+    const excluded = [];
+    const semanticPaths = [];
+    for (const document of evidence.traversal.documents) {
+        const classification = classified.get(document.path);
+        if (document.status !== 'read')
+            excluded.push({ path: document.path, reason: 'unread' });
+        else if (classification?.roleStatus === 'ambiguous')
+            excluded.push({ path: document.path, reason: 'ambiguous-role' });
+        else if (classification?.sourceRole === 'validation')
+            excluded.push({ path: document.path, reason: 'validation' });
+        else
+            semanticPaths.push(document.path);
+    }
+    const selection = await selectSemanticInputs(repository, commitSha, semanticPaths, config.semantic);
+    // Prospective traversal budgets count every document. Execution budgets count only semantic inputs.
+    const issues = [...selection.issues, ...evidence.traversal.issues.filter(issue => !['document-budget', 'source-byte-budget'].includes(issue.code)), ...evidence.classification.issues.map(issue => ({ ...issue, severity: issue.code === 'role-ambiguous' ? 'error' : issue.severity }))];
+    const record = { version: 1, policyDigest: evidence.classification.policyDigest,
+        complete: evidence.traversal.coverage.complete && !issues.some(issue => issue.severity === 'error'),
+        entryPoints: evidence.traversal.entryPoints, roots: evidence.traversal.roots,
+        documentPaths: evidence.traversal.documents.map(document => document.path), semanticPaths, excluded };
+    const digest = sha256(stableJson({ identity: documentSelectionIdentity, commitSha, record,
+        traversal: evidence.traversal, classification: evidence.classification }));
+    return { ...selection, issues, documentEvidence: evidence, documentSelection: { ...record, digest } };
+}
+/** Assembly metadata is deliberately outside immutable provider artifacts. */
+export function classifyHydratedFacts(facts, evidence) {
+    if (!evidence)
+        return facts;
+    const classified = new Map(evidence.classification.documents.map(document => [document.path, document]));
+    return facts.map(fact => {
+        const document = classified.get(fact.provenance.path);
+        if (!document)
+            throw new Error('Document assembly fact has no classified source');
+        const metadata = { sourceRole: document.sourceRole, sourceOwnership: document.ownership,
+            sourcePolicyDigest: evidence.classification.policyDigest, sourceAuthority: document.sourceAuthority };
+        return { ...fact, ...metadata, id: sha256(stableJson({ fact: fact.id, metadata, identity: documentSelectionIdentity })) };
+    });
+}

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

@@ -2,6 +2,8 @@ import type { ImpactScanRequest } from '@weftlet/core';
 import { type SemanticCacheInspection } from '../extraction/semantic-cache.js';
 import { type SemanticInputIssue, type SemanticSelection } from '../extraction/semantic-sources.js';
 import { type SemanticScope } from './semantic-scope.js';
+import { type DocumentEvidence } from './hydration-inputs.js';
+import type { DocumentSelectionRecord, SourceDocumentRole, SourceOwnership } from '@weftlet/core';
 export interface HydrationPlanOptions {
     readonly ref?: string;
     readonly forceSemantic?: boolean;
@@ -21,6 +23,9 @@ export interface HydrationPlanDocument {
     readonly approvedBy: readonly string[];
     readonly extractionReview: 'unreviewed';
     readonly cache: Omit<SemanticCacheInspection, 'artifact'>;
+    readonly sourceRole?: SourceDocumentRole;
+    readonly sourceOwnership?: SourceOwnership;
+    readonly sourcePolicyDigest?: string;
 }
 export interface HydrationPlan {
     readonly schemaVersion: 1;
@@ -34,6 +39,8 @@ export interface HydrationPlan {
         readonly complete: boolean;
     };
     readonly documents: readonly HydrationPlanDocument[];
+    readonly documentSelection?: DocumentSelectionRecord;
+    readonly documentCoverage?: Pick<DocumentEvidence, 'traversal' | 'classification'>;
     readonly selections: readonly SemanticSelection[];
     readonly budgets: {
         readonly maxDocuments: number;

package/dist/application/hydration-plan.js

@@ -4,9 +4,9 @@ import { matchesRepositoryGlob } from '../repository/glob.js';
 import { createSemanticArtifactStore } from './semantic-artifact-store.js';
 import { inspectSemanticCache } from '../extraction/semantic-cache.js';
 import { semanticProviderIdentity } from '../extraction/semantic-identity.js';
-import { selectSemanticInputs } from '../extraction/semantic-sources.js';
 import { sha256, stableJson } from '../infrastructure/util.js';
 import { resolveSemanticScope } from './semantic-scope.js';
+import { selectHydrationInputs } from './hydration-inputs.js';
 import { semanticSourceId } from '../extraction/semantic-diagnostics.js';
 async function describeDocument(source, selections, config, evidencePaths, store, forceSemantic = false) {
     const inspection = forceSemantic
@@ -29,11 +29,12 @@ export async function planHydration(configPath, options = {}) {
     const ref = options.ref ?? 'HEAD';
     const commitSha = await repository.resolveRef(ref);
     const scope = await resolveSemanticScope(config, repository, commitSha, options.request);
-    const selection = await selectSemanticInputs(repository, commitSha, scope.selectors, config.semantic);
+    const selection = await selectHydrationInputs(repository, commitSha, config, scope.selectors);
     const issues = [...selection.issues];
     const { omittedDocuments, ignoredSearchTerms } = scope;
     const limited = omittedDocuments.length > 0 || ignoredSearchTerms > 0;
-    const complete = !limited && selection.selections.every((item) => item.status === 'matched');
+    const complete = !limited && selection.selections.every((item) => item.status === 'matched') &&
+        (selection.documentSelection?.complete ?? true);
     if (limited)
         issues.push({ code: 'selection-limited', severity: 'warning',
             message: `Existing agent selection limits omitted ${omittedDocuments.length} documents and ${ignoredSearchTerms} search terms; this plan describes only the selected scope.`,
@@ -42,7 +43,11 @@ export async function planHydration(configPath, options = {}) {
     const evidencePaths = new Set(await repository.listFilesAt(commitSha, config.evidenceRoots));
     const documents = [];
     for (const source of selection.sources) {
-        const document = await describeDocument(source, selection.selections, config, evidencePaths, store, options.forceSemantic);
+        const described = await describeDocument(source, selection.selections, config, evidencePaths, store, options.forceSemantic);
+        const classification = selection.documentEvidence?.classification.documents.find(item => item.path === source.path);
+        const document = classification ? { ...described, role: 'semantic-document',
+            sourceAuthority: classification.sourceAuthority, sourceRole: classification.sourceRole,
+            sourceOwnership: classification.ownership, sourcePolicyDigest: selection.documentEvidence.classification.policyDigest } : described;
         const { cache } = document;
         if (cache.status === 'corrupt' || cache.status === 'unavailable')
             issues.push({
@@ -56,9 +61,17 @@ export async function planHydration(configPath, options = {}) {
         configurationDigest: sha256(stableJson(config)), ready: complete && !issues.some((item) => item.severity === 'error'),
         scope: { ...scope, complete },
         documents, selections: selection.selections, budgets: selection.budgets,
+        ...(selection.documentSelection ? { documentSelection: selection.documentSelection,
+            documentCoverage: { traversal: selection.documentEvidence.traversal, classification: selection.documentEvidence.classification } } : {}),
         estimates: { reusableArtifacts: count('hit'), extractions: count('miss', 'forced'), unknownArtifacts: count('corrupt', 'unavailable') },
         issues, excludedWorkingChanges: await repository.workingChanges(),
-        assumptions: [
+        assumptions: selection.documentSelection ? [
+            'Traversal uses committed entry points and canonical local links. All discovered documents and exclusions are reported; only semantic candidates count against extraction budgets.',
+            'Validation documents retain deterministic presence/references without model extraction. Role ambiguity and incomplete coverage block model work; ownership gaps remain explicit diagnostics.',
+            'Classification and owner mappings never approve assertions. Model facts remain inferred/unreviewed, including from approved sources.',
+            'Readiness checks selection, budgets and readable caches. It does not initialize providers, adapters, credentials, indexing, runtime sources or graph validation.',
+            'Built-in Codex artifacts retain their extraction identity. Traversal module providers use a separate conservative cache; no cache or snapshot was written.',
+        ] : [
             'Sources come from the resolved commit; configuration and cache are read from the current local environment.',
             'Estimates require unchanged source, configuration, provider contract and readable artifacts; concurrent changes can invalidate them.',
             'Document and per-document UTF-8 byte limits apply to all selected documents, including cache hits; no token or monetary estimate is made.',