@weftlet/toolkit 0.5.0 → 0.6.0

package/dist/extraction/document-classification.js

@@ -0,0 +1,161 @@
+import { posix } from 'node:path';
+import { sha256, stableJson } from '@weftlet/core';
+import { matchesRepositoryGlob } from '../repository/glob.js';
+const maximumDocuments = 10_000;
+const maximumMappings = 1000;
+const compare = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const uniqueSorted = (values) => [...new Set(values)].sort(compare);
+const roles = new Set(['intent', 'plan', 'validation', 'reference']);
+const unsafe = /[\x00-\x1f\x7f-\x9f\uFFFD:[\]{}]/;
+function record(value, name, fields) {
+    if (!value || typeof value !== 'object' || Array.isArray(value) ||
+        Object.keys(value).some(key => !fields.includes(key))) {
+        throw new Error(`${name} must be an object containing only supported fields`);
+    }
+    return value;
+}
+function array(value, name, maximum) {
+    if (!Array.isArray(value) || value.length > maximum) {
+        throw new Error(`${name} must be an array of at most ${maximum} entries`);
+    }
+    return value;
+}
+function documentPath(value, name) {
+    if (typeof value !== 'string' || !value || value.length > 4096 || value !== value.trim() ||
+        unsafe.test(value) || /[\\*?]/.test(value) || value.startsWith('/') || value.startsWith('../') ||
+        posix.normalize(value) !== value || !/\.(?:md|mdx|txt)$/i.test(value)) {
+        throw new Error(`${name} must be a canonical repository-relative .md, .mdx or .txt document path`);
+    }
+    return value;
+}
+function documentPaths(value, name) {
+    const paths = array(value, name, maximumDocuments).map(path => documentPath(path, name));
+    if (new Set(paths).size !== paths.length)
+        throw new Error(`${name} must not contain duplicate document paths`);
+    return paths.sort(compare);
+}
+function pattern(value, name, evidenceRoot = false) {
+    if (typeof value !== 'string' || value.length > 4096 || value !== value.trim() || unsafe.test(value)) {
+        throw new Error(`${name} must be a repository-relative pattern using only * and ? wildcards`);
+    }
+    const normalized = value.replaceAll('\\', '/').replace(/^\.\//, '');
+    const result = evidenceRoot ? normalized.replace(/\/$/, '') || '.' : normalized;
+    const segments = result.split('/');
+    if (!result || result.startsWith('!') || result.startsWith('/') ||
+        (result !== '.' && segments.some(segment => !segment || segment === '.' || segment === '..')) ||
+        (!evidenceRoot && result === '.') || /\*{3}/.test(result)) {
+        throw new Error(`${name} must be a repository-relative pattern using only * and ? wildcards`);
+    }
+    return result;
+}
+function patterns(value, name, evidenceRoot = false) {
+    return uniqueSorted(array(value, name, maximumMappings).map(item => pattern(item, name, evidenceRoot)));
+}
+function mappingId(value, ids) {
+    if (typeof value !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/.test(value) || ids.has(value)) {
+        throw new Error('Document policy mapping IDs must be unique ASCII identifiers of at most 128 characters');
+    }
+    ids.add(value);
+    return value;
+}
+/** Parse bounded explicit policy; normalize ordering, never infer approval or ownership. */
+export function parseDocumentClassificationPolicy(value) {
+    const input = record(value, 'Document policy', ['schemaVersion', 'roles', 'owners']);
+    if (input.schemaVersion !== 1)
+        throw new Error('Document policy schemaVersion must be 1');
+    const ids = new Set();
+    const roleMappings = array(input.roles === undefined ? [] : input.roles, 'Document policy roles', maximumMappings).map(value => {
+        const mapping = record(value, 'Document role mapping', ['id', 'pattern', 'role']);
+        if (typeof mapping.role !== 'string' || !roles.has(mapping.role))
+            throw new Error('Document policy role must be intent, plan, validation or reference');
+        return { id: mappingId(mapping.id, ids), pattern: pattern(mapping.pattern, 'Document role pattern'),
+            role: mapping.role };
+    });
+    const ownerMappings = array(input.owners === undefined ? [] : input.owners, 'Document policy owners', maximumMappings).map(value => {
+        const mapping = record(value, 'Document owner mapping', ['id', 'pattern', 'ownerDocument']);
+        return { id: mappingId(mapping.id, ids), pattern: pattern(mapping.pattern, 'Document owner pattern'),
+            ownerDocument: documentPath(mapping.ownerDocument, 'Owner document') };
+    });
+    return { schemaVersion: 1, roles: roleMappings.sort((a, b) => compare(a.id, b.id)),
+        owners: ownerMappings.sort((a, b) => compare(a.id, b.id)) };
+}
+function evidenceRootMatches(path, root) {
+    return root === '.' || path === root || path.startsWith(`${root}/`) ||
+        matchesRepositoryGlob(path, root) || matchesRepositoryGlob(path, `${root}/**`);
+}
+function classifyRole(path, settings) {
+    const approvedBy = settings.approvedIntentSources.filter(pattern => matchesRepositoryGlob(path, pattern));
+    const matches = settings.policy.roles.filter(mapping => matchesRepositoryGlob(path, mapping.pattern));
+    const selectedRoles = new Set(matches.map(mapping => mapping.role));
+    let sourceRole = 'unclassified';
+    let roleStatus = 'default';
+    if (selectedRoles.size > 1)
+        roleStatus = 'ambiguous';
+    else if (matches.length) {
+        sourceRole = matches[0].role;
+        roleStatus = 'explicit';
+    }
+    else if (settings.evidenceRoots.some(root => evidenceRootMatches(path, root)))
+        sourceRole = 'validation';
+    else if (approvedBy.length)
+        sourceRole = 'intent';
+    return { sourceRole, roleStatus, matchedRoleMappings: matches.map(mapping => mapping.id), approvedBy,
+        sourceAuthority: approvedBy.length ? 'declared' : 'inferred' };
+}
+function classifyOwnership(path, role, settings) {
+    const mappings = settings.policy.owners.filter(mapping => matchesRepositoryGlob(path, mapping.pattern));
+    const ownerDocuments = uniqueSorted(mappings.map(mapping => mapping.ownerDocument));
+    const mappingIds = mappings.map(mapping => mapping.id);
+    const result = (status) => ({ status, ownerDocuments, mappingIds });
+    if (!ownerDocuments.length)
+        return result(['validation', 'reference'].includes(role) ? 'not-required' : 'missing');
+    if (ownerDocuments.length > 1)
+        return result('ambiguous');
+    const owner = ownerDocuments[0];
+    if (!settings.availableDocuments.has(owner))
+        return result('unavailable');
+    const classification = classifyRole(owner, settings);
+    if (!classification.approvedBy.length)
+        return result('unapproved');
+    if (classification.sourceRole !== 'intent' || classification.roleStatus === 'ambiguous')
+        return result('ineligible');
+    return result('resolved');
+}
+const ownershipMessages = {
+    missing: 'This document role requires an explicit source-of-truth owner mapping.',
+    ambiguous: 'Explicit owner mappings disagree on the source-of-truth document.',
+    unavailable: 'The explicit owner is not an available read document in the selected coverage.',
+    unapproved: 'The explicit owner does not match the configured approved intent sources.',
+    ineligible: 'The approved explicit owner does not have an unambiguous intent role.',
+};
+function classificationIssues(document) {
+    const issues = [];
+    const add = (code, message, paths) => issues.push({ code, severity: 'warning', message, paths });
+    if (document.roleStatus === 'ambiguous')
+        add('role-ambiguous', 'Explicit document role mappings conflict; no role was selected.', [document.path]);
+    else if (document.sourceRole === 'unclassified')
+        add('role-unclassified', 'No explicit role or configured default classifies this document.', [document.path]);
+    const message = ownershipMessages[document.ownership.status];
+    if (message)
+        add(`ownership-${document.ownership.status}`, message, uniqueSorted([document.path, ...document.ownership.ownerDocuments]));
+    return issues;
+}
+/** Classify source-level evidence only; links, owner mappings and roles never approve a child. */
+export function classifyDocumentSources(paths, context, policy) {
+    const selected = documentPaths(paths, 'Document paths');
+    const normalized = parseDocumentClassificationPolicy(policy === undefined ? { schemaVersion: 1 } : policy);
+    const settings = {
+        policy: { schemaVersion: 1, roles: normalized.roles, owners: normalized.owners },
+        approvedIntentSources: patterns(context.approvedIntentSources, 'Approved intent source patterns'),
+        evidenceRoots: patterns(context.evidenceRoots, 'Evidence roots', true),
+        availableDocuments: new Set(documentPaths(context.availableDocuments, 'Available document paths')),
+    };
+    const documents = selected.map(path => {
+        const classification = classifyRole(path, settings);
+        return { path, ...classification, ownership: classifyOwnership(path, classification.sourceRole, settings) };
+    });
+    const issues = documents.flatMap(classificationIssues);
+    const policyDigest = sha256(stableJson({ policy: settings.policy,
+        approvedIntentSources: settings.approvedIntentSources, evidenceRoots: settings.evidenceRoots }));
+    return { policyDigest, documents, issues, complete: !issues.length };
+}

package/dist/extraction/document-evidence.d.ts

@@ -0,0 +1,21 @@
+import { type ExtractionContext, type GraphDiagnostic, type GraphFact } from '@weftlet/core';
+import type { GitRepository } from '../repository/git.js';
+import { type DocumentClassificationPolicy, type DocumentClassificationReport } from './document-classification.js';
+import { type DocumentTraversalOptions, type DocumentTraversalReport } from './document-traversal.js';
+export declare const documentEvidenceExtractorIdentity: {
+    readonly id: "document-evidence-extractor";
+    readonly version: "1.0.0";
+};
+type DocumentEvidenceOptions = DocumentTraversalOptions & {
+    readonly documentPolicy?: DocumentClassificationPolicy;
+    readonly approvedIntentSources?: readonly string[];
+    readonly evidenceRoots?: readonly string[];
+};
+/** Deterministic committed document structure only; never interprets prose, approves rules or publishes evidence. */
+export declare function extractDocumentEvidence(repository: Pick<GitRepository, 'listEntriesAt' | 'readFileAt'>, context: ExtractionContext, options: DocumentEvidenceOptions): Promise<{
+    facts: readonly GraphFact[];
+    diagnostics: readonly GraphDiagnostic[];
+    traversal: DocumentTraversalReport;
+    classification: DocumentClassificationReport;
+}>;
+export {};

package/dist/extraction/document-evidence.js

@@ -0,0 +1,83 @@
+import { repositoryFileNode } from '@weftlet/core';
+import { sha256, stableJson } from '../infrastructure/util.js';
+import { classifyDocumentSources } from './document-classification.js';
+import { traverseDocuments } from './document-traversal.js';
+export const documentEvidenceExtractorIdentity = { id: 'document-evidence-extractor', version: '1.0.0' };
+function span(state, path, startLine = 1, endLine = startLine) {
+    const document = state.documents.get(path);
+    return document ? { path, startLine, endLine, digest: document.digest, commitSha: state.context.commitSha } : undefined;
+}
+function addFact(state, subject, predicate, object, provenance) {
+    const classification = state.classified.get(provenance.path);
+    const record = { subject, predicate, object, provenance, extractor: documentEvidenceExtractorIdentity,
+        confidence: 1, authority: 'inferred', extractionReview: 'deterministic',
+        sourceAuthority: classification.sourceAuthority, sourceRole: classification.sourceRole,
+        sourceOwnership: classification.ownership, sourcePolicyDigest: state.policyDigest };
+    const id = sha256(stableJson({ ...record, repositoryId: state.context.repositoryId }));
+    state.facts.set(id, { id, ...record, snapshotId: state.context.snapshotId });
+}
+function addDiagnostic(state, kind, reason, provenance, paths) {
+    const citations = [...new Map(provenance.map(citation => [stableJson(citation), citation])).values()];
+    const relatedNodeIds = [...new Set(paths.map(path => repositoryFileNode(path).id))].sort();
+    const record = { kind, reason, provenance: citations, relatedNodeIds, evidenceScope: 'source' };
+    const id = sha256(stableJson({ ...record, extractor: documentEvidenceExtractorIdentity,
+        commitSha: state.context.commitSha, policyDigest: state.policyDigest, repositoryId: state.context.repositoryId }));
+    state.diagnostics.set(id, { id, ...record });
+}
+function linkCitations(state, link) {
+    const citations = [span(state, link.sourcePath, link.startLine, link.endLine)];
+    if (link.referenceStartLine !== undefined) {
+        citations.push(span(state, link.sourcePath, link.referenceStartLine, link.referenceEndLine));
+    }
+    for (const definition of link.definitions ?? []) {
+        citations.push(span(state, link.sourcePath, definition.startLine, definition.endLine));
+    }
+    return citations.filter((citation) => citation !== undefined);
+}
+function extractLinks(state, links) {
+    for (const link of links) {
+        const citations = linkCitations(state, link);
+        if ((link.status === 'document' || link.status === 'non-document') && link.path) {
+            for (const citation of citations) {
+                addFact(state, repositoryFileNode(link.sourcePath), 'references', repositoryFileNode(link.path), citation);
+            }
+        }
+        else if (link.status !== 'external' && link.status !== 'fragment') {
+            addDiagnostic(state, 'implementationGaps', `Canonical document link is unresolved (${link.status}); no relationship was emitted.`, citations, [link.sourcePath, ...(link.path ? [link.path] : [])]);
+        }
+    }
+}
+function reportGaps(state, traversal, classification) {
+    for (const issue of traversal.issues) {
+        // Link diagnostics above retain their exact declaration/use citations instead of line-one placeholders.
+        if (/^(?:link-|ambiguous-reference$|malformed$|outside-repository$)/.test(issue.code))
+            continue;
+        const citations = issue.paths.flatMap(path => { const citation = span(state, path); return citation ? [citation] : []; });
+        addDiagnostic(state, 'implementationGaps', `Document traversal gap [${issue.code}]: ${issue.message}`, citations, issue.paths);
+    }
+    for (const issue of classification.issues) {
+        const citations = issue.paths.flatMap(path => { const citation = span(state, path); return citation ? [citation] : []; });
+        addDiagnostic(state, issue.code.includes('ambiguous') ? 'ambiguousIntent' : 'missingIntent', `Document classification gap [${issue.code}]: ${issue.message}`, citations, issue.paths);
+    }
+}
+/** Deterministic committed document structure only; never interprets prose, approves rules or publishes evidence. */
+export async function extractDocumentEvidence(repository, context, options) {
+    const traversal = await traverseDocuments(repository, context.commitSha, options);
+    const documents = traversal.documents.filter((document) => document.status === 'read' && document.digest !== undefined);
+    const paths = documents.map(document => document.path);
+    const classification = classifyDocumentSources(paths, {
+        approvedIntentSources: options.approvedIntentSources ?? [], evidenceRoots: options.evidenceRoots ?? [],
+        availableDocuments: paths,
+    }, options.documentPolicy);
+    const state = { context, documents: new Map(documents.map(document => [document.path, document])),
+        classified: new Map(classification.documents.map(document => [document.path, document])),
+        policyDigest: classification.policyDigest, facts: new Map(), diagnostics: new Map() };
+    const project = { id: `project:${context.repositoryId}`, kind: 'Project', label: context.repositoryId };
+    for (const document of documents) {
+        addFact(state, project, 'contains', repositoryFileNode(document.path), span(state, document.path));
+    }
+    extractLinks(state, traversal.links);
+    reportGaps(state, traversal, classification);
+    return { facts: [...state.facts.values()].sort((a, b) => a.id.localeCompare(b.id)),
+        diagnostics: [...state.diagnostics.values()].sort((a, b) => a.id.localeCompare(b.id)), traversal, classification };
+}

package/dist/extraction/document-traversal.d.ts

@@ -0,0 +1,76 @@
+import type { GitRepository } from '../repository/git.js';
+import { type CanonicalDocumentLink } from './canonical-document-links.js';
+export interface DocumentTraversalOptions {
+    readonly entryPoints: readonly string[];
+    readonly roots?: readonly string[];
+    readonly maxReadDocuments?: number;
+    readonly maxReadBytes?: number;
+    readonly maxDocumentBytes?: number;
+    readonly maxDocuments?: number;
+    readonly maxSourceBytes?: number;
+}
+export interface DocumentReachingLink {
+    readonly sourcePath: string;
+    readonly startLine: number;
+    readonly endLine: number;
+    readonly referenceStartLine?: number;
+    readonly referenceEndLine?: number;
+}
+export interface TraversalDocument {
+    readonly path: string;
+    readonly bytes: number;
+    readonly digest?: string;
+    readonly status: 'read' | 'unread';
+    readonly entryPoint: boolean;
+    readonly reachedBy: readonly DocumentReachingLink[];
+}
+export type DocumentLinkStatus = 'document' | 'non-document' | 'external' | 'fragment' | 'missing' | 'outside-scope' | 'outside-repository' | 'directory' | 'symlink' | 'submodule' | 'ambiguous' | 'malformed' | 'unsupported';
+export interface DocumentTraversalLink extends DocumentReachingLink {
+    readonly target?: string;
+    readonly path?: string;
+    readonly status: DocumentLinkStatus;
+    readonly definitions?: CanonicalDocumentLink['definitions'];
+}
+export interface DocumentTraversalIssue {
+    readonly code: string;
+    readonly severity: 'error' | 'warning';
+    readonly message: string;
+    readonly paths: readonly string[];
+}
+export interface DocumentTraversalReport {
+    readonly entryPoints: readonly string[];
+    readonly roots: readonly string[];
+    readonly documents: readonly TraversalDocument[];
+    readonly links: readonly DocumentTraversalLink[];
+    readonly issues: readonly DocumentTraversalIssue[];
+    readonly coverage: {
+        readonly complete: boolean;
+        readonly unvisited: readonly string[];
+    };
+    readonly limits: {
+        readonly maxReadDocuments: number;
+        readonly maxReadBytes: number;
+        readonly maxDocumentBytes: number;
+    };
+    /** Read counters include attempted reads, charged at committed blob sizes even on failure. */
+    readonly counters: {
+        readonly readDocuments: number;
+        readonly readBytes: number;
+        readonly discoveredDocuments: number;
+        readonly links: number;
+    };
+    /** Prospective extraction comparison; incomplete traversal yields only known lower bounds. */
+    readonly budgets: {
+        readonly maxDocuments: number;
+        readonly maxSourceBytes: number;
+        readonly documents: number;
+        readonly bytes: number;
+        readonly withinLimits: boolean;
+    };
+}
+type TraversalRepository = Pick<GitRepository, 'listEntriesAt' | 'readFileAt'>;
+/** Validate operation/configuration bounds without reading repository data. */
+export declare function validateDocumentTraversalOptions(options: DocumentTraversalOptions): void;
+/** Prospective committed Markdown closure only: never loads execution adapters or writes evidence. */
+export declare function traverseDocuments(repository: TraversalRepository, commitSha: string, options: DocumentTraversalOptions): Promise<DocumentTraversalReport>;
+export {};

package/dist/extraction/document-traversal.js

@@ -0,0 +1,210 @@
+import { createHash } from 'node:crypto';
+import { posix } from 'node:path';
+import { canonicalDocumentLinks, resolveCanonicalDocumentLink } from './canonical-document-links.js';
+const compare = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const supportedDocument = (path) => /\.(?:md|mdx|txt)$/i.test(path);
+const unsafePath = (path) => /[\\:*?\[\]{}\x00-\x1f\x7f-\x9f\uFFFD]/.test(path);
+const inside = (path, root) => root === '.' || path === root || path.startsWith(`${root}/`);
+function paths(value, name, allowRoot) {
+    if (!Array.isArray(value) || !value.length || value.length > 10_000 ||
+        new Set(value).size !== value.length || value.some(path => typeof path !== 'string' || !path ||
+        path !== path.trim() || unsafePath(path) || path.length > 4096 || path.endsWith('/') || posix.isAbsolute(path) ||
+        path === '..' || path.startsWith('../') || posix.normalize(path) !== path || (!allowRoot && path === '.'))) {
+        throw new Error(`${name} must contain unique canonical repository-relative paths without globs or control characters`);
+    }
+    return [...value].sort(compare);
+}
+function bound(value, fallback, maximum, name) {
+    const resolved = value === undefined ? fallback : value;
+    if (!Number.isSafeInteger(resolved) || resolved < 1 || resolved > maximum) {
+        throw new Error(`${name} must be an integer from 1 through ${maximum}`);
+    }
+    return resolved;
+}
+function settings(options) {
+    return {
+        entryPoints: paths(options.entryPoints, 'entryPoints', false), roots: paths(options.roots ?? ['.'], 'roots', true),
+        limits: {
+            maxReadDocuments: bound(options.maxReadDocuments, 1000, 10_000, 'maxReadDocuments'),
+            maxReadBytes: bound(options.maxReadBytes, 16 * 1024 * 1024, 64 * 1024 * 1024, 'maxReadBytes'),
+            maxDocumentBytes: bound(options.maxDocumentBytes, 1024 * 1024, 4 * 1024 * 1024, 'maxDocumentBytes'),
+        },
+        maxDocuments: bound(options.maxDocuments, 8, 10_000, 'maxDocuments'),
+        maxSourceBytes: bound(options.maxSourceBytes, 65_536, 4 * 1024 * 1024, 'maxSourceBytes'),
+    };
+}
+/** Validate operation/configuration bounds without reading repository data. */
+export function validateDocumentTraversalOptions(options) {
+    settings(options);
+}
+function issue(state, code, message, affected, coverage = true) {
+    state.issues.push({ code, severity: 'error', message, paths: affected });
+    if (coverage)
+        state.complete = false;
+}
+function entryBoundary(entry) {
+    if (entry?.type === 'commit' || entry?.mode === '160000')
+        return 'submodule';
+    return entry?.mode === '120000' ? 'symlink' : undefined;
+}
+function regularBlob(entry) {
+    return entry?.type === 'blob' && ['100644', '100755'].includes(entry.mode) &&
+        Number.isSafeInteger(entry.size) && entry.size >= 0;
+}
+function classifyTarget(path, tracked, roots) {
+    if (unsafePath(path))
+        return 'unsupported';
+    const segments = path.split('/');
+    for (let count = 1; count < segments.length; count++) {
+        const ancestor = tracked.get(segments.slice(0, count).join('/'));
+        const boundary = ancestor?.mode === '120000' ? 'symlink' : entryBoundary(ancestor);
+        if (boundary)
+            return boundary;
+    }
+    const entry = tracked.get(path);
+    const boundary = entryBoundary(entry);
+    if (boundary)
+        return boundary;
+    // Roots bound document traversal; an existing regular code/asset link needs no body read.
+    const regular = regularBlob(entry);
+    if (regular && !supportedDocument(path))
+        return 'non-document';
+    if (!roots.some(root => inside(path, root)))
+        return 'outside-scope';
+    if (path === '.' || entry?.type === 'tree')
+        return 'directory';
+    if (!entry)
+        return 'missing';
+    return regular ? 'document' : 'unsupported';
+}
+function discover(state, entryPoints, path, reaching) {
+    const old = state.documents.get(path);
+    if (old) {
+        if (reaching)
+            state.documents.set(path, { ...old, reachedBy: [...old.reachedBy, reaching] });
+        return;
+    }
+    state.documents.set(path, { path, bytes: state.tracked.get(path).size, status: 'unread',
+        entryPoint: entryPoints.includes(path), reachedBy: reaching ? [reaching] : [] });
+    state.queue.push(path);
+}
+function initializeEntries(state, selection) {
+    for (const root of selection.roots)
+        if (root !== '.' && !state.tracked.has(root)) {
+            issue(state, 'missing-root', 'A configured traversal root is not a committed entry.', [root]);
+        }
+    for (const path of selection.entryPoints) {
+        const status = classifyTarget(path, state.tracked, selection.roots);
+        if (status === 'document')
+            discover(state, selection.entryPoints, path);
+        else
+            issue(state, `entry-${status}`, 'An entry point is not an in-scope regular document.', [path]);
+    }
+}
+function readLimit(document, state, limits) {
+    if (document.bytes > limits.maxDocumentBytes)
+        return 'document-read-bytes';
+    if (state.readDocuments >= limits.maxReadDocuments)
+        return 'document-read-count';
+    return state.readBytes + document.bytes > limits.maxReadBytes ? 'total-read-bytes' : undefined;
+}
+async function readDocumentLinks(repository, commitSha, document, state, limits) {
+    const blocked = readLimit(document, state, limits);
+    if (blocked) {
+        issue(state, blocked, 'A discovered document was not read because a traversal safety limit would be exceeded.', [document.path]);
+        return;
+    }
+    state.readDocuments++;
+    state.readBytes += document.bytes;
+    let content;
+    try {
+        content = await repository.readFileAt(commitSha, document.path);
+    }
+    catch {
+        issue(state, 'document-read-failed', 'A committed document could not be read.', [document.path]);
+        return;
+    }
+    // Git's string API cannot prove whether U+FFFD was literal or introduced by lossy UTF-8 decoding.
+    if (content.includes('\uFFFD') || content.includes('\0') || Buffer.byteLength(content) !== document.bytes) {
+        issue(state, 'unsupported-document-encoding', 'Document bytes cannot be represented unambiguously as supported UTF-8 text.', [document.path]);
+        return;
+    }
+    try {
+        return { references: canonicalDocumentLinks(content), digest: createHash('sha256').update(content).digest('hex') };
+    }
+    catch {
+        issue(state, 'document-parse-failed', 'Committed Markdown links could not be parsed.', [document.path]);
+        return;
+    }
+}
+function followReference(state, selection, path, reference) {
+    const citation = { sourcePath: path, startLine: reference.startLine, endLine: reference.endLine,
+        ...(reference.referenceStartLine === undefined ? {} : { referenceStartLine: reference.referenceStartLine,
+            referenceEndLine: reference.referenceEndLine }) };
+    if (reference.kind === 'ambiguous-reference') {
+        state.links.push({ ...citation, status: 'ambiguous', definitions: reference.definitions });
+        issue(state, 'ambiguous-reference', 'A used reference has conflicting Markdown definitions.', [path]);
+        return;
+    }
+    const resolved = resolveCanonicalDocumentLink(path, reference.target);
+    if (resolved.kind !== 'path') {
+        state.links.push({ ...citation, target: reference.target, status: resolved.kind });
+        if (resolved.kind !== 'external' && resolved.kind !== 'fragment')
+            issue(state, resolved.kind, resolved.reason, [path]);
+        return;
+    }
+    const classified = classifyTarget(resolved.path, state.tracked, selection.roots);
+    const status = resolved.directoryHint && ['document', 'non-document'].includes(classified) ? 'unsupported' : classified;
+    state.links.push({ ...citation, target: reference.target, path: resolved.path, status });
+    if (status === 'document')
+        discover(state, selection.entryPoints, resolved.path, citation);
+    else if (status !== 'non-document')
+        issue(state, `link-${status}`, 'A canonical local link could not be traversed as a regular in-scope document.', [path, resolved.path]);
+}
+async function walkDocuments(repository, commitSha, state, selection) {
+    for (let index = 0; index < state.queue.length; index++) {
+        const path = state.queue[index];
+        const read = await readDocumentLinks(repository, commitSha, state.documents.get(path), state, selection.limits);
+        if (!read)
+            continue;
+        state.documents.set(path, { ...state.documents.get(path), status: 'read', digest: read.digest });
+        for (const reference of read.references)
+            followReference(state, selection, path, reference);
+    }
+}
+function finishReport(state, selection, indexReadable) {
+    const { entryPoints, roots, limits, maxDocuments, maxSourceBytes } = selection;
+    const ordered = [...state.documents.values()].sort((a, b) => compare(a.path, b.path));
+    const bytes = ordered.reduce((sum, document) => sum + document.bytes, 0);
+    const oversized = ordered.filter(document => document.bytes > maxSourceBytes).map(document => document.path);
+    if (ordered.length > maxDocuments)
+        issue(state, 'document-budget', 'Known reachable documents exceed the prospective extraction count budget.', ordered.map(document => document.path), false);
+    if (oversized.length)
+        issue(state, 'source-byte-budget', 'Known reachable documents exceed the prospective per-source extraction byte budget.', oversized, false);
+    return { entryPoints, roots, documents: ordered, links: state.links, issues: state.issues,
+        coverage: { complete: state.complete, unvisited: indexReadable ? ordered.filter(document => document.status === 'unread').map(document => document.path) : entryPoints },
+        limits, counters: { readDocuments: state.readDocuments, readBytes: state.readBytes, discoveredDocuments: ordered.length, links: state.links.length },
+        budgets: { maxDocuments, maxSourceBytes, documents: ordered.length, bytes,
+            withinLimits: ordered.length <= maxDocuments && !oversized.length } };
+}
+/** Prospective committed Markdown closure only: never loads execution adapters or writes evidence. */
+export async function traverseDocuments(repository, commitSha, options) {
+    if (!/^(?:[a-f\d]{40}|[a-f\d]{64})$/i.test(commitSha)) {
+        throw new Error('Document traversal requires a resolved immutable commit SHA');
+    }
+    const selection = settings(options);
+    const state = { tracked: new Map(), documents: new Map(), links: [], issues: [], queue: [],
+        complete: true, readDocuments: 0, readBytes: 0 };
+    let indexReadable = true;
+    try {
+        state.tracked = new Map((await repository.listEntriesAt(commitSha)).map(entry => [entry.path, entry]));
+    }
+    catch {
+        indexReadable = false;
+        issue(state, 'repository-index-unavailable', 'Committed repository entries could not be read.', selection.entryPoints);
+    }
+    if (indexReadable)
+        initializeEntries(state, selection);
+    await walkDocuments(repository, commitSha, state, selection);
+    return finishReport(state, selection, indexReadable);
+}

package/dist/extraction/document.d.ts

@@ -6,7 +6,9 @@ export declare const documentLinkerIdentity: {
 export declare function linkSemanticDocuments(context: ExtractionContext, hydrated: readonly {
     source: SemanticSource;
     artifact: SemanticArtifact;
-}[], trackedPaths: readonly string[], approvedSourcePaths?: readonly string[]): {
+}[], trackedPaths: readonly string[], approvedSourcePaths?: readonly string[], options?: {
+    readonly canonicalReferences?: boolean;
+}): {
     readonly facts: readonly GraphFact[];
     readonly diagnostics: readonly GraphDiagnostic[];
 };

package/dist/extraction/document.js

@@ -2,7 +2,7 @@ import { sha256, stableJson } from '../infrastructure/util.js';
 import { documentReferences, resolveDocumentReference } from './document-references.js';
 import { repositoryFileNode as fileNode } from '@weftlet/core';
 export const documentLinkerIdentity = { id: 'document-linker', version: '2.0.0' };
-export function linkSemanticDocuments(context, hydrated, trackedPaths, approvedSourcePaths = []) {
+export function linkSemanticDocuments(context, hydrated, trackedPaths, approvedSourcePaths = [], options = {}) {
     const facts = new Map();
     const diagnostics = new Map();
     const tracked = new Set(trackedPaths);
@@ -27,6 +27,8 @@ export function linkSemanticDocuments(context, hydrated, trackedPaths, approvedS
             }
         }
         for (const reference of documentReferences(source.content)) {
+            if (options.canonicalReferences === false && reference.relativeTo === 'document')
+                continue;
             const resolved = resolveDocumentReference(source.path, reference, tracked);
             if (resolved.kind === 'ignored')
                 continue;

package/dist/graph/authority.js

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

package/dist/graph/coverage.d.ts

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