@weftlet/toolkit 0.5.0 → 0.6.1

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

@@ -1,8 +1,8 @@
 // Modified for standalone extraction; see docs/extraction-manifest.json.
 import { mkdir, readFile, writeFile, link, rm } from 'node:fs/promises';
-import { randomUUID } from 'node:crypto';
-import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { atomicRename } from './atomic-rename.js';
+import { physicalArtifactKey, temporaryArtifactPath } from '../infrastructure/artifact-paths.js';
 async function readJson(path) {
     try {
         return JSON.parse(await readFile(path, 'utf8'));
@@ -13,9 +13,21 @@ async function readJson(path) {
         throw error;
     }
 }
+async function readWithLegacyPath(path, legacyPath) {
+    const current = await readJson(path);
+    if (current !== undefined || path === legacyPath)
+        return current;
+    // No old file could have this component on supported filesystems. Do not attempt an
+    // overlong fallback after a normal cache miss; other I/O/corruption errors still propagate.
+    if (Buffer.byteLength(basename(legacyPath)) > 255)
+        return undefined;
+    if (process.platform === 'win32' && /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(basename(legacyPath)))
+        return undefined;
+    return readJson(legacyPath);
+}
 async function atomicJson(path, value) {
     await mkdir(dirname(path), { recursive: true });
-    const temporary = `${path}.${randomUUID()}.tmp`;
+    const temporary = temporaryArtifactPath(path);
     try {
         await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' });
         await atomicRename(temporary, path);
@@ -29,7 +41,7 @@ function safeKey(key) {
         throw new Error('Unsafe storage identifier');
     return key;
 }
-function snapshotPath(root, snapshotId) {
+function snapshotPath(root, snapshotId, legacy = false) {
     if (snapshotId.length > 256 ||
         !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(snapshotId) ||
         snapshotId === '.' ||
@@ -37,7 +49,7 @@ function snapshotPath(root, snapshotId) {
         throw new Error('snapshotId must be a safe storage identifier');
     }
     const directory = resolve(root, 'snapshots');
-    const candidate = resolve(directory, `${snapshotId}.json`);
+    const candidate = resolve(directory, `${legacy ? snapshotId : physicalArtifactKey(snapshotId)}.json`);
     const pathFromDirectory = relative(directory, candidate);
     if (pathFromDirectory === '..' ||
         pathFromDirectory.startsWith(`..${sep}`) ||
@@ -53,8 +65,15 @@ export class FileSnapshotStore {
     }
     async write(snapshot) {
         const destination = snapshotPath(this.root, snapshot.manifest.snapshotId);
+        const prior = await this.read(snapshot.manifest.snapshotId);
+        if (prior) {
+            if (prior.manifest.contentDigest !== snapshot.manifest.contentDigest) {
+                throw new Error(`Refusing to overwrite immutable snapshot ${snapshot.manifest.snapshotId} with different content`);
+            }
+            return; // Preserve an existing legacy file without copying or rewriting its bytes.
+        }
         await mkdir(dirname(destination), { recursive: true });
-        const temporary = `${destination}.${randomUUID()}.tmp`;
+        const temporary = temporaryArtifactPath(destination);
         try {
             await writeFile(temporary, JSON.stringify(snapshot), { flag: 'wx' });
             // Linking a complete file publishes atomically without ever replacing a winner.
@@ -73,16 +92,17 @@ export class FileSnapshotStore {
         }
     }
     read(snapshotId) {
-        return readJson(snapshotPath(this.root, snapshotId));
+        return readWithLegacyPath(snapshotPath(this.root, snapshotId), snapshotPath(this.root, snapshotId, true));
     }
     async readHead(headName) {
-        const head = await readJson(join(this.root, 'heads', `${safeKey(headName)}.json`));
+        const key = safeKey(headName);
+        const head = await readWithLegacyPath(join(this.root, 'heads', `${physicalArtifactKey(key)}.json`), join(this.root, 'heads', `${key}.json`));
         return head ? this.read(head.snapshotId) : undefined;
     }
     async updateHead(headName, snapshotId) {
         if (!(await this.read(snapshotId)))
             throw new Error('Cannot point a head to an absent snapshot');
-        return atomicJson(join(this.root, 'heads', `${safeKey(headName)}.json`), { snapshotId });
+        return atomicJson(join(this.root, 'heads', `${physicalArtifactKey(safeKey(headName))}.json`), { snapshotId });
     }
 }
 export class SemanticArtifactStore {
@@ -97,18 +117,26 @@ export class SemanticArtifactStore {
     }
     /** Only explicitly supplied roots are consulted; never enumerate other consumers' profiles. */
     async readEntry(key) {
-        const filename = `${safeKey(key)}.json`;
+        const filename = `${physicalArtifactKey(safeKey(key))}.json`;
         for (const [index, root] of [this.root, ...this.legacyRoots].entries()) {
-            const artifact = await readJson(join(root, 'artifacts', 'semantic', filename));
+            const artifact = await readWithLegacyPath(join(root, 'artifacts', 'semantic', filename), join(root, 'artifacts', 'semantic', `${key}.json`));
             if (artifact !== undefined)
                 return { artifact, origin: index === 0 ? 'primary' : 'legacy' };
         }
         return undefined;
     }
     async write(artifact) {
-        const path = join(this.root, 'artifacts', 'semantic', `${safeKey(artifact.key)}.json`);
+        const key = safeKey(artifact.key);
+        const path = join(this.root, 'artifacts', 'semantic', `${physicalArtifactKey(key)}.json`);
+        const prior = await readWithLegacyPath(path, join(this.root, 'artifacts', 'semantic', `${key}.json`));
+        if (prior) {
+            if (prior.outputDigest !== artifact.outputDigest) {
+                throw new Error('Concurrent semantic artifact differs; retry with explicit force refresh');
+            }
+            return;
+        }
         await mkdir(dirname(path), { recursive: true });
-        const temporary = `${path}.${randomUUID()}.tmp`;
+        const temporary = temporaryArtifactPath(path);
         try {
             await writeFile(temporary, JSON.stringify(artifact), { flag: 'wx' });
             await link(temporary, path);

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-021-identity-preflight-and-validation-timing.md

@@ -1,7 +1,10 @@
 # ADR-021: Early identity conflicts and honest validation phase timing
 
-Status: implemented in development source after 0.4.0. Publication and consumer acceptance
-are separate checkpoints in [validation](VALIDATION.md). This is the bounded T05a increment.
+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
 

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.

package/docs/ADR-024-implementation-coverage.md

@@ -0,0 +1,51 @@
+# ADR-024: Report evidence coverage independently of display groups
+
+Status: implemented after T07a; validation and publication are recorded separately in
+[validation](VALIDATION.md). This is a query-reporting correction, not T07b document classification.
+
+## Problem
+
+The consumer reports returned code relationships with zero implementation coverage. Public
+reproductions using the actual contract extractor and real SCIP confirm the defect: a file's
+definition or consumption of a Contract is placed in the contracts display group. Coverage used
+the exclusive display-group counts, so these code relationships could not count as implementation.
+The inverse also occurred: unapproved document/model facts in the fallback implementation group
+could suppress an implementation gap. Page-local absence was described as query-wide absence.
+
+## Decision
+
+Keep primary display groups, returned facts, ranking, pagination and authority unchanged. Compute
+implementation coverage from the returned evidence independently of display placement. A production
+code relationship can count toward both contract and implementation coverage without appearing twice
+in the returned facts. The other coverage categories retain their existing classification.
+
+New reports include `coverage.scope: "returned-page"` and `countsAreNonExclusive: true`.
+Both fields are optional in core for compatibility with older Context Packs. Counts are relationship
+counts, not percentages, totals of display sections, product completeness or proof of correct behavior.
+Markdown and HTML explain overlap. Missing-evidence messages refer to the returned page; continuation
+and traversal bounds can leave further evidence outside it. Existing source diagnostics remain intact.
+
+An implementation relationship must have effective `implemented` authority, a non-document,
+non-validation citation, and no unreviewed extraction marker. Current document/model, runtime,
+draft and validation evidence cannot qualify by merely mentioning a code file. Supported document
+extensions and test/spec names use the canonical core file policy. Conventional test/validation
+directories, including `__tests__` and `__mocks__`, are excluded from production coverage.
+
+Legacy deterministic adapters that omitted authority retain the existing authority fallback only
+when a canonical physical Component endpoint matches the cited file. An adapter explicitly marking
+a fact `implemented` may also use logical Component/Provider identities with a production citation.
+Unmarked legacy provider output cannot be distinguished from adapter output when their metadata is
+identical; no new claim of provider verification or execution is made. Saved fact authority is never
+rewritten by this reporting classification.
+
+## Compatibility and validation
+
+No extractor, prompt, semantic artifact, assembly or ranking identity changes. Existing immutable
+snapshots immediately benefit when queried by the updated toolkit; no model run or hydration is
+needed. Historical Context Packs keep their original reports unless queried again. Existing clients
+should inspect the new metadata rather than summing counts as a disjoint total.
+
+Regressions use actual contract extraction, real TypeScript SCIP, strict SHACL and immutable
+round-tripped facts. They cover overlapping counts, page continuation, API/MCP/Markdown/HTML
+consistency, document/model/test negatives and retained source diagnostics. Installed-package smoke
+checks query actual extracted facts rather than constructing coverage values by hand.