@weftlet/toolkit 0.4.0 → 0.6.0

package/dist/interfaces/cli.js

@@ -18,6 +18,8 @@ import { loadConfig } from "../configuration/config.js";
 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;
@@ -60,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}`);
     }
@@ -82,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.\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;
@@ -171,7 +189,7 @@ async function main() {
         const base = valueAfter(args, '--base-snapshot');
         if (!base)
             throw new Error('overlay requires --base-snapshot <committed snapshot ID>');
-        const result = await buildWorkingOverlay(application.repository, application.config, application.snapshotStore, application.storageRoot, base, valueAfter(args, '--agent'));
+        const result = await buildWorkingOverlay(application.repository, application.config, application.snapshotStore, application.storageRoot, base, valueAfter(args, '--agent'), { validationDetails: args.includes('--validation-details') });
         process.stdout.write(`${JSON.stringify(result.manifest, null, 2)}\n`);
         return;
     }
@@ -187,8 +205,11 @@ async function main() {
                 headName: scope?.headName ?? application.headName,
                 semanticSources: scope?.semanticSources,
                 forceSemantic: args.includes('--force-semantic'),
+                validationDetails: args.includes('--validation-details'),
                 signal: controller.signal,
                 onProgress: args.includes('--quiet') ? undefined : (event) => process.stderr.write(`[context-graph] ${event.phase}${event.total === undefined ? '' : ` ${event.completed}/${event.total}`}` +
+                    `${event.status === undefined ? '' : ` ${event.status}`}` +
+                    `${event.factCount === undefined ? '' : ` facts=${event.factCount}`}${event.nodeCount === undefined ? '' : ` nodes=${event.nodeCount}`}` +
                     `${event.sourceId === undefined ? '' : ` ${event.sourceId}`}${event.elapsedMs === undefined ? '' : ` ${event.elapsedMs} ms`}\n`),
             });
             process.stdout.write(`${JSON.stringify({
@@ -257,8 +278,11 @@ async function main() {
     throw new Error('Usage: weftlet hydrate|clean-compare|impact scan|diagnostics show --snapshot <id>|invariant check|ontology compile|visualize --output <file.html|file.dot|file.svg>');
 }
 main().catch((error) => {
-    process.stderr.write(`${error instanceof SemanticHydrationError
-        ? process.argv.includes('--json') ? JSON.stringify(error.report, null, 2) : error.message
-        : error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+    process.stderr.write(`${error instanceof GraphIdentityConflictError
+        ? process.argv.includes('--json') || process.argv.includes('--validation-details')
+            ? JSON.stringify(error.report, null, 2) : error.message
+        : error instanceof SemanticHydrationError
+            ? process.argv.includes('--json') ? JSON.stringify(error.report, null, 2) : error.message
+            : error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
     process.exitCode = 1;
 });

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

package/dist/visualization/visualization.js

@@ -1,7 +1,10 @@
 // Modified for standalone extraction; see docs/extraction-manifest.json.
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname, extname, resolve } from 'node:path';
+import { repositoryFileNode } from '@weftlet/core';
 import { contextPackEvidenceAuthority, contextPackLaneForFact } from "../graph/query.js";
+import { coverageDescription } from '../graph/coverage.js';
+import { documentSelectionDescription, sourceDocumentDescription } from '../graph/document-role-description.js';
 import { viewerScript } from "./viewer-interaction.js";
 import { diagnosticSummary } from "../graph/diagnostics.js";
 export const MAX_VISUALIZATION_FACTS = 200;
@@ -67,7 +70,7 @@ function visualColumn(kind, selectedLanes) {
     }
     return 'implementation';
 }
-function addNode(nodes, node, selectedLanes) {
+function addNode(nodes, node, selectedLanes, ownValidationSource = false) {
     if (nodes.has(node.id))
         return;
     nodes.set(node.id, {
@@ -75,7 +78,7 @@ function addNode(nodes, node, selectedLanes) {
         label: node.label,
         kind: node.kind,
         cluster: String(node.attributes?.module ?? node.attributes?.layer ?? node.kind),
-        column: visualColumn(node.kind, selectedLanes),
+        column: ownValidationSource && node.kind === 'Document' ? 'evidence' : visualColumn(node.kind, selectedLanes),
     });
 }
 function assertVisualizationBounds(pack) {
@@ -104,8 +107,16 @@ function visualModel(pack, sourceUrlTemplate) {
     assertVisualizationBounds(pack);
     const nodes = new Map();
     const selectedLanes = new Map();
+    const validationDocuments = new Set();
     const edges = [];
     for (const fact of pack.facts) {
+        if (fact.sourceRole === 'validation') {
+            const citedDocument = repositoryFileNode(fact.provenance.path);
+            if (citedDocument.kind === 'Document' &&
+                [fact.subject, fact.object].some(node => node.kind === 'Document' && node.id === citedDocument.id)) {
+                validationDocuments.add(citedDocument.id);
+            }
+        }
         const lane = contextPackLaneForFact(fact);
         if (!lane)
             continue;
@@ -116,8 +127,9 @@ function visualModel(pack, sourceUrlTemplate) {
         }
     }
     for (const fact of pack.facts) {
-        addNode(nodes, fact.subject, selectedLanes.get(fact.subject.id));
-        addNode(nodes, fact.object, selectedLanes.get(fact.object.id));
+        addNode(nodes, fact.subject, selectedLanes.get(fact.subject.id), validationDocuments.has(fact.subject.id));
+        addNode(nodes, fact.object, selectedLanes.get(fact.object.id), validationDocuments.has(fact.object.id));
+        const sourceDescription = sourceDocumentDescription(fact);
         edges.push({
             id: fact.id,
             from: fact.subject.id,
@@ -125,7 +137,8 @@ function visualModel(pack, sourceUrlTemplate) {
             label: fact.predicate,
             authority: contextPackEvidenceAuthority(fact),
             provenance: `${fact.provenance.path}:${fact.provenance.startLine}`,
-            detail: `confidence ${fact.confidence}; ${fact.extractor.id}@${fact.extractor.version}; source ${fact.sourceAuthority ?? 'see citation'}; extraction ${fact.extractionReview ?? 'unspecified'}`,
+            detail: `confidence ${fact.confidence}; ${fact.extractor.id}@${fact.extractor.version}; source ${fact.sourceAuthority ?? 'see citation'}; extraction ${fact.extractionReview ?? 'unspecified'}` +
+                (sourceDescription ? `; ${sourceDescription}` : ''),
             source: fact.provenance,
             sourceUrl: sourceLink(fact.provenance, sourceUrlTemplate),
         });
@@ -398,6 +411,7 @@ export function renderContextPackHtml(pack, sourceUrlTemplate) {
     Excluded working paths: ${pack.evidenceState?.excludedWorkingChanges.length ?? 'unknown'}.
     ${pack.snapshot.overlayDigest ? `Overlay freshness: ${escapeXml(pack.evidenceState?.overlayFreshness ?? 'unknown')}.` : ''}
     This view does not validate the current diff.</p>
+    <p>${escapeXml(documentSelectionDescription(pack.snapshot.documentSelection))}</p>
     <p>${pack.exploration ? `${pack.exploration.returned}/${pack.exploration.reachableFacts} reachable facts on this page; max depth ${pack.exploration.maxDepth}; ${pack.exploration.truncated ? 'TRUNCATED' : 'not truncated within this scope'}${pack.exploration.depthLimitReached ? '; depth limit reached — rerun with greater --max-depth' : ''}` : 'Query completeness metadata unavailable.'}</p>
     ${pack.exploration?.continuation ? `<details><summary>Continue agent/CLI query with this token</summary><code>${escapeXml(pack.exploration.continuation)}</code></details>` : ''}
     ${pack.evidenceState?.excludedWorkingChanges.length ? `<details><summary>Excluded working changes</summary>${detailList(pack.evidenceState.excludedWorkingChanges, '')}</details>` : ''}
@@ -410,10 +424,11 @@ export function renderContextPackHtml(pack, sourceUrlTemplate) {
       <section class="panel"><h2>Runtime references</h2>${detailList(pack.runtimeEvidence.map(reference => `${reference.serviceName}: ${reference.operation ?? 'observation'} · ${reference.sourcePath} · ${reference.observedAt ?? 'time unknown'}`), 'None in this page.')}<p>Edges are only the facts returned by the agent query. References do not create extra relationships.</p></section>
       <section class="panel">
         <h2>Coverage</h2>
+        <p>${escapeXml(coverageDescription(pack.coverage))}</p>
         ${Object.entries(pack.coverage.counts)
         .map(([lane, count]) => `<span class="metric">${escapeXml(lane)}: ${count}</span>`)
         .join('')}
-        ${detailList(pack.coverage.gaps, 'No Context Pack lane gaps detected.')}
+        ${detailList(pack.coverage.gaps, 'No coverage gaps detected on this returned page.')}
       </section>
       <section class="panel">
         <h2>Governing invariants</h2>

package/docs/ADR-017-shacl-validation-union.md

@@ -3,6 +3,10 @@
 Status: accepted and implemented in the focused 0.3.0 release; absent from 0.2.1.
 See [validation](VALIDATION.md) for checks and recorded publication evidence.
 
+Follow-up: [ADR 027](ADR-027-validation-closeout.md) records the completed T05 engineering
+evaluation and retains full direct validation. The measurements and remaining-work section below
+describe the original focused release; private consumer acceptance remains separate.
+
 ## Problem and measured mechanism
 
 The canonical RDF dataset has one named relationship graph per assertion, with assertion records,

package/docs/ADR-018-operational-semantic-cache.md

@@ -1,7 +1,7 @@
 # ADR-018: Preserve Codex artifacts across operational configuration changes
 
-Status: accepted and implemented in development source after 0.3.0; release evidence is recorded
-in [validation](VALIDATION.md). This increment does not claim a new npm publication.
+Status: accepted and shipped in 0.4.0; release and validation evidence is recorded in
+[validation](VALIDATION.md).
 
 ## Problem
 

package/docs/ADR-019-semantic-failure-diagnostics.md

@@ -1,7 +1,7 @@
 # ADR-019: Safe semantic failure diagnostics and settled progress
 
-Status: implemented in development source after 0.3.0; validation and publication are recorded
-separately in [validation](VALIDATION.md). This decision does not change extraction identity.
+Status: shipped in 0.4.0; validation and publication are recorded in [validation](VALIDATION.md).
+This decision does not change extraction identity.
 
 ## Problem
 

package/docs/ADR-020-canonical-physical-file-producers.md

@@ -1,7 +1,7 @@
 # ADR-020: One physical-file policy for deterministic producers and adapters
 
-Status: implemented in development source after 0.3.0; release/consumer acceptance is recorded
-separately in [validation](VALIDATION.md).
+Status: upstream fix shipped in 0.4.0; release evidence and pending consumer adapter/hydration
+acceptance are recorded separately in [validation](VALIDATION.md).
 
 ## Reported defect and ownership
 

package/docs/ADR-021-identity-preflight-and-validation-timing.md

@@ -0,0 +1,84 @@
+# ADR-021: Early identity conflicts and honest validation phase timing
+
+Status: shipped in 0.5.0 after local/hosted checks and independent archive review; release evidence
+is in [validation](VALIDATION.md). Consumer acceptance remains a separate checkpoint.
+This is the bounded T05a increment. Follow-up [ADR 027](ADR-027-validation-closeout.md) records
+the broader T05 engineering evaluation; the remaining-work section below describes this original
+increment. Private consumer performance acceptance remains separate.
+
+## Decision
+
+Before ontology compilation, invariant evaluation or RDF construction, scan every assembled
+fact's subject and object identity for multiple kinds. The scan covers semantic, document,
+static, adapter, routing and runtime facts, including conceptual identities. Working overlays
+run the same check over retained and newly extracted facts before RDF construction/publication.
+No fact, kind, ID, citation or authority is changed or discarded by the check.
+This runs after semantic/static extraction; it is separate from no-model `hydrate --plan`.
+
+`inspectGraphIdentities(facts, { repositoryId, includeDetails? })` returns a report;
+`assertGraphIdentities` throws `GraphIdentityConflictError` on conflicts. Both are public toolkit
+exports. A passing report has `passed: true` and **`shaclValidated: false`**. Consistent kinds
+alone do not establish canonical classification, correct intent, valid citations or conformance.
+The existing full RDF/SHACL path and shapes remain mandatory for successful publication. Direct
+`RdfEvidenceGraph.validate()` and the saved `validate` command still run all checks and return
+their existing verdict format. There is no validation cache, incremental validator or backend change.
+
+The two-pass scan is linear in fact occurrences. The common conflict-free path creates no
+per-evidence diagnostic records. On failure it reports every conflicting identity and occurrence,
+including both ends of a self-reference, repeated fact IDs and late conflicts. Counts are complete;
+there is no hidden document, hop or diagnostic cutoff. Reports retain input indices and side so
+duplicate assertion IDs cannot conceal a producer's occurrence.
+
+## Privacy and attribution
+
+There was no general configurable diagnostic privacy policy. This increment therefore makes
+local detail an explicit invocation option, without adding an extraction/configuration field.
+Default reports contain repository-scoped opaque node, fact, source and extractor references,
+counts and recognized kind names. Unknown kind strings are hashed as well. References correlate
+records; they are not encryption or proof that a low-entropy identifier cannot be guessed.
+
+`hydrate --json --quiet` emits a typed identity-failure report on stderr with empty stdout.
+Use `--validation-details` on `hydrate` or `overlay` only when local identities and citations
+may be displayed. That option includes exact node/fact IDs, extractor identity/version, citation
+path/lines/digest/commit, confidence and the original optional authority/review fields. It does
+not include labels, node attributes, source text, prompts or raw provider output. Absent authority
+fields stay absent; source approval is never promoted into assertion approval.
+
+The programmatic equivalent is `HydrationOptions.validationDetails` or the overlay's final
+options argument. Detail changes do not enter snapshot, provider or semantic-cache identities.
+The error message stays safe even when its report includes explicitly requested local details.
+No diagnostic file is written automatically. Existing non-identity SHACL errors retain their
+existing detailed behavior; this is not a claim that every command/error has been redacted.
+
+## Timing and failure preservation
+
+Hydration reports started/completed/failed boundaries and elapsed wall time for identity
+preflight, RDF construction, union construction and full SHACL. Counts describe graph size,
+not validator completion. A completed SHACL phase means the validator returned, including a
+nonconforming verdict. `RdfEvidenceGraph.validate({ onProgress })` exposes its union/SHACL phases.
+
+The synchronous JavaScript work can block same-thread timers. These events are not heartbeats,
+percentages, new timeout controls or interruptible worker execution. Worker isolation remains a
+separate decision. The public profiling harness records preflight and validation phase timings
+alongside its existing construction, resource and runtime measurements.
+
+Failure preserves completed semantic artifacts and prior snapshots/heads. Correcting and
+versioning an adapter still requires a fresh assembly and full validation, but compatible
+semantic artifacts can be reused. This preflight does not rewrite cached model assertions or
+choose an authoritative business rule. Evidence disagreements must be resolved at their owner.
+
+No extraction/assembly version changes are needed: accepted graph facts, cache identities,
+RDF serialization and conformance constraints are unchanged. The check rejects an existing
+single-kind violation earlier; it does not make old snapshots satisfy current validation.
+
+## Evidence and remaining work
+
+Tests cover full cross-source attribution, conceptual and physical nodes, exact authority,
+default privacy, late conflicts, duplicates/self-references, immutable artifacts/snapshots,
+corrected retries and non-kind failures that still reach full SHACL. CLI and packed-consumer
+cases use actual TypeScript SCIP and public adapters. Existing positive/negative named-dataset
+SHACL equivalence tests remain unchanged except for an additional timing/parity case.
+
+Broader T05 work remains: worker-based progress/cancellation, repeated/changed-input performance
+evaluation, and evidence-driven decisions about conformance-result reuse or incremental/native
+backends. This increment does not infer private consumer performance from public fixtures.

package/docs/ADR-022-release-documentation.md

@@ -0,0 +1,44 @@
+# ADR-022: Versioned installation documentation checked against release archives
+
+Status: implemented for T06 after 0.5.0; validation is recorded separately in
+[validation](VALIDATION.md). This changes release tooling and packaged documentation, not graph semantics.
+
+## Decision
+
+The two package manifests own the version of the current checkout/archive. Marked sections in
+the toolkit README, core README and release guide are generated from those manifests. They do
+not claim a version is already published: a Changesets version PR can precede registry availability.
+Publication evidence remains in the validation record and package-specific releases.
+
+`scripts/release-documentation.mjs` uses Node built-ins. It is usable by the publish job, which
+installs no project dependencies. Versioning regenerates the marked sections after Changesets
+updates the manifests and before the extraction inventory is refreshed. Missing, duplicate or
+malformed markers fail rather than causing unrelated prose to be overwritten.
+
+Source checks compare the complete generated sections and check explicit package pins and
+Weftlet archive names in active installation examples. The maintained scope is the two READMEs,
+`docs/RELEASING.md`, `docs/MIGRATING-TO-WEFTLET.md` and `docs/CONSUMER-TRIAL.md`.
+Feature introductions, earlier release records and historical inspection commands remain intact.
+Historical installation fences require an explicit `weftlet-history` classification; this is a
+reviewed documentation exception, not an automatic exemption based on an old version number.
+
+Packed checks read the actual two tarballs. Package names, versions, archive filenames and the
+toolkit's core dependency must match the release group. Required operational documents must be
+present and match the reviewed source, allowing equivalent LF/CRLF checkout representations.
+The same documentation checks run on those packed documents. Both archives are checked before
+any publish operation, including when publication resumes from prepared artifacts.
+
+The fresh-consumer smoke uses constrained argument arrays obtained from the checked current
+examples. It installs the documented archive pair and runs the documented pinned setup and
+configuration-validation commands against a disposable registry serving those archives. It
+never evaluates arbitrary Markdown as shell code and makes no model requests.
+
+## Boundaries
+
+This is a release-documentation check, not a natural-language verifier or general shell parser.
+New current version statements belong in the generated sections. New installation guides must
+be added to the explicit operational-document scope to receive the same checks. Historical
+validation records, changelogs, feature-introduction versions and private consumer documentation
+are not automatically rewritten. Existing immutable npm archives are unchanged.
+
+T07 document selection/authority and broader T05 validation progress/reuse remain separate.

package/docs/ADR-023-document-coverage-preview.md

@@ -0,0 +1,64 @@
+# ADR-023: Prospective committed document coverage
+
+Status: implemented as T07a after T06; source validation and publication are separate in
+[validation](VALIDATION.md). T07b classification/evidence and T07c hydration integration remain planned.
+
+## Decision
+
+`weftlet documents plan` and `planDocumentCoverage()` inspect the committed Markdown-link closure
+from explicit entry points. The report is `document-coverage-plan`, with `mode: prospective` and
+`changesHydrationSelection: false`. It is separate from `hydrate --plan`, whose inputs and cache
+estimates continue to describe actual hydration. No provider, adapter, indexer, cache, snapshot,
+runtime source or ontology compiler is initialized or written by the new operation.
+
+Entry points, exact scope roots and read limits are operation arguments. This increment adds no
+hydration configuration fields and changes no cache partitions, extractor versions or graph
+assembly identities. Existing config supplies repository identity, explicit approval/evidence-root
+labels and semantic budgets for comparison. This avoids making an unused traversal setting
+invalidate current snapshots or cached artifacts.
+
+The new NUL-delimited Git tree reader preserves exact committed paths and records type, mode,
+object ID and byte size, including directories, symlinks and gitlinks. It scopes correctly to a
+nested repository root. Existing Git listing/extraction APIs are unchanged. Invalid UTF-8 tree
+paths or malformed metadata fail closed instead of silently disappearing from the index.
+
+A separate canonical-link parser follows direct Markdown links and used reference definitions.
+It retains source lines, definition/use positions and conflicting definitions. It does not change
+the graph linker's existing treatment of bare and inline-code paths. Images, code examples, HTML
+and unused definitions do not become traversal edges. CommonMark-compatible links in Markdown,
+MDX and text files are supported; this is not a complete MDX/HTML parser.
+
+Relative paths resolve against their source document, leading `/` means repository root, and
+percent encoding and fragment/query removal are explicit. No basename/README guessing or remote
+fetch occurs. Malformed/escaping targets, scope exclusions, missing files, directories, symlinks,
+submodules and ambiguous references are reported distinctly. Scope roots bound document traversal;
+existing regular code/non-document targets outside those roots can still be classified without
+reading their contents. Resolved code links, external URLs
+and same-document fragments remain visible without being traversed. Visited-path deduplication
+terminates cycles while retaining every reaching-link occurrence.
+
+## Coverage and limits
+
+Traversal computes reachable supported documents before comparing extraction budgets. The
+existing `semantic.maxDocuments`/`maxSourceBytes` values apply only to that comparison; they never
+trim the traversal. Candidates include validation documents at this stage, so totals are not a
+promise of future model work. Missing links and unread descendants make coverage incomplete.
+`ready` requires complete supported local coverage and a passing budget comparison; it does not
+establish approved requirements, semantic quality, complete product coverage or hydration readiness.
+
+Separate read-safety limits default to 1,000 documents, 16 MiB total and 1 MiB per document,
+with ceilings of 10,000 documents, 64 MiB and 4 MiB respectively. Committed blob sizes are checked
+before reads; failed attempts count toward read limits. Discovered unread paths remain in the
+frontier and their descendants are explicitly unknown. Git metadata output is bounded to 64 MiB.
+The current string reader conservatively rejects NUL, byte-size mismatches and U+FFFD, including
+a literal replacement character, because it cannot prove lossless decoding in that case.
+
+Reports include commit, current configuration digest, coverage digest, paths, sizes, content
+digests, citations, issues and excluded working changes, but no document bodies. They are local
+diagnostic reports and may contain private paths/link destinations. Source approval matches
+remain explicit and do not propagate through links; prospective assertion review stays unreviewed.
+Evidence-root labels do not infer rule ownership or approve source assertions.
+
+Before traversal can drive extraction, T07b must preserve validation documents through a separate
+deterministic evidence path. T07c must connect the same selection to hydration, cache recovery and
+freshness checks, with real cross-source positive/negative fixtures and rename/delete behavior.