@weftlet/toolkit 0.6.0 → 0.7.0

package/dist/application/saved-paths.d.ts

@@ -0,0 +1,58 @@
+import type { GraphPathQueryService, GraphPathsRequest } from '@weftlet/core';
+import type { GitRepository } from '../repository/git.js';
+export declare class SavedGraphPathService implements GraphPathQueryService {
+    private readonly queries;
+    private readonly repository;
+    private readonly configurationDigest;
+    private readonly expectedExtractors?;
+    constructor(queries: GraphPathQueryService, repository: GitRepository, configurationDigest: string, expectedExtractors?: Readonly<Record<string, string>> | undefined);
+    paths(request: GraphPathsRequest): Promise<{
+        markdown: string;
+        evidenceState: {
+            readonly currentCommit?: string;
+            readonly excludedWorkingChanges: readonly string[];
+            readonly capturedWorkingChanges?: readonly string[];
+            readonly changedSinceCapture?: readonly string[];
+            readonly overlayFreshness?: "current" | "stale" | "unknown";
+            readonly stale: boolean;
+            readonly configurationMatches: boolean;
+            readonly extractionCompatible?: boolean;
+            readonly incompatibleExtractors?: readonly string[];
+            readonly eligibleForCurrentDiffValidation: false;
+        };
+        snapshot: import("@weftlet/core").ContextPack["snapshot"];
+        endpoints: {
+            readonly from: {
+                readonly nodeId: string;
+                readonly status: "present" | "absent-from-snapshot";
+            };
+            readonly to: {
+                readonly nodeId: string;
+                readonly status: "present" | "absent-from-snapshot";
+            };
+        };
+        paths: readonly import("@weftlet/core").EvidencePath[];
+        facts: readonly import("@weftlet/core").GraphFact[];
+        coverage: import("@weftlet/core").ContextPack["coverage"];
+        diagnostics: import("@weftlet/core").ContextPack["diagnostics"];
+        search: {
+            readonly version: string;
+            readonly order: "fact-id-depth-first";
+            readonly direction: import("@weftlet/core").GraphDirection;
+            readonly predicates: readonly import("@weftlet/core").GraphPredicate[];
+            readonly maxDepth: number;
+            readonly maxPaths: number;
+            readonly maxSteps: number;
+            readonly searchLimit: number;
+            readonly replayedSteps: number;
+            readonly examinedSteps: number;
+            readonly totalSteps: number;
+            readonly stopReason: "exhausted" | "path-page-limit" | "work-page-limit" | "search-limit";
+            readonly exhaustedWithinDepth: boolean;
+            readonly depthLimitReached: boolean;
+            readonly truncated: boolean;
+            readonly continuation?: string;
+        };
+        frontier: import("@weftlet/core").PathFrontier;
+    }>;
+}

package/dist/application/saved-paths.js

@@ -0,0 +1,20 @@
+import { renderGraphPaths } from '../graph/paths-renderer.js';
+import { inspectSavedEvidence } from './saved-evidence.js';
+export class SavedGraphPathService {
+    queries;
+    repository;
+    configurationDigest;
+    expectedExtractors;
+    constructor(queries, repository, configurationDigest, expectedExtractors) {
+        this.queries = queries;
+        this.repository = repository;
+        this.configurationDigest = configurationDigest;
+        this.expectedExtractors = expectedExtractors;
+    }
+    async paths(request) {
+        const result = await this.queries.paths(request);
+        const evidenceState = await inspectSavedEvidence(result.snapshot, this.repository, this.configurationDigest, this.expectedExtractors);
+        const withState = { ...result, evidenceState };
+        return { ...withState, markdown: renderGraphPaths(withState) };
+    }
+}

package/dist/extraction/call-syntax.d.ts

@@ -0,0 +1,18 @@
+import ts from 'typescript';
+import type { GraphFact, SourceSpan } from '@weftlet/core';
+export type Callable = ts.FunctionDeclaration | ts.FunctionExpression | ts.ArrowFunction | ts.MethodDeclaration | ts.GetAccessorDeclaration | ts.SetAccessorDeclaration | ts.ConstructorDeclaration;
+export declare const isCallable: (node: ts.Node) => node is Callable;
+export declare function callableName(node: Callable): ts.Node | undefined;
+/** Ambient declarations may occur in .ts namespaces too; they supply no runtime body. */
+export declare function isAmbient(node: ts.Node): boolean;
+export declare function syntaxSpan(node: ts.Node, source: ts.SourceFile, digest: string, commitSha: string): SourceSpan;
+export declare const positionKey: (span: SourceSpan) => string;
+export declare function calleeToken(expression: ts.Expression): ts.Node | undefined;
+export interface ParsedCallSource {
+    readonly source: ts.SourceFile;
+    readonly digest: string;
+    readonly byPosition: ReadonlyMap<string, readonly GraphFact[]>;
+    readonly parseErrors: readonly ts.Diagnostic[];
+}
+export declare function parseCallSource(path: string, text: string, digest: string, facts: readonly GraphFact[]): ParsedCallSource;
+export declare function factsAt(node: ts.Node | undefined, parsed: ParsedCallSource, commitSha: string, role: 'definition' | 'reference'): GraphFact[];

package/dist/extraction/call-syntax.js

@@ -0,0 +1,61 @@
+import ts from 'typescript';
+export const isCallable = (node) => ts.isFunctionDeclaration(node) ||
+    ts.isFunctionExpression(node) || ts.isArrowFunction(node) || ts.isMethodDeclaration(node) ||
+    ts.isGetAccessorDeclaration(node) || ts.isSetAccessorDeclaration(node) || ts.isConstructorDeclaration(node);
+export function callableName(node) {
+    if ('name' in node && node.name)
+        return node.name;
+    if (ts.isConstructorDeclaration(node))
+        return node.getFirstToken();
+    const parent = node.parent;
+    if ((ts.isVariableDeclaration(parent) || ts.isPropertyDeclaration(parent) || ts.isPropertyAssignment(parent)) &&
+        parent.initializer === node && (ts.isIdentifier(parent.name) || ts.isPrivateIdentifier(parent.name)))
+        return parent.name;
+    return undefined;
+}
+/** Ambient declarations may occur in .ts namespaces too; they supply no runtime body. */
+export function isAmbient(node) {
+    if (node.getSourceFile().isDeclarationFile)
+        return true;
+    for (let current = node; current; current = current.parent) {
+        if (ts.canHaveModifiers(current) && ts.getModifiers(current)?.some(modifier => modifier.kind === ts.SyntaxKind.DeclareKeyword))
+            return true;
+    }
+    return false;
+}
+export function syntaxSpan(node, source, digest, commitSha) {
+    const start = source.getLineAndCharacterOfPosition(node.getStart(source));
+    const end = source.getLineAndCharacterOfPosition(node.getEnd());
+    return { path: source.fileName, startLine: start.line + 1, startColumn: start.character + 1,
+        endLine: end.line + 1, endColumn: end.character + 1, columnEncoding: 'utf-16', digest, commitSha };
+}
+export const positionKey = (span) => `${span.path}:${span.startLine}:${span.startColumn}:${span.endLine}:${span.endColumn}`;
+export function calleeToken(expression) {
+    while (ts.isParenthesizedExpression(expression) || ts.isNonNullExpression(expression) ||
+        ts.isAsExpression(expression) || ts.isTypeAssertionExpression(expression) || ts.isSatisfiesExpression(expression))
+        expression = expression.expression;
+    if (ts.isIdentifier(expression) || expression.kind === ts.SyntaxKind.SuperKeyword)
+        return expression;
+    if (ts.isPropertyAccessExpression(expression))
+        return expression.name;
+    if (ts.isElementAccessExpression(expression) && ts.isStringLiteral(expression.argumentExpression))
+        return expression.argumentExpression;
+    return undefined;
+}
+export function parseCallSource(path, text, digest, facts) {
+    const source = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true, path.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+    const byPosition = new Map();
+    for (const fact of facts) {
+        const key = positionKey(fact.provenance), group = byPosition.get(key) ?? [];
+        group.push(fact);
+        byPosition.set(key, group);
+    }
+    return { source, digest, byPosition,
+        parseErrors: source.parseDiagnostics };
+}
+export function factsAt(node, parsed, commitSha, role) {
+    if (!node)
+        return [];
+    return (parsed.byPosition.get(positionKey(syntaxSpan(node, parsed.source, parsed.digest, commitSha))) ?? [])
+        .filter(fact => fact.codeOccurrence?.role === role);
+}

package/dist/extraction/canonical-document-links.d.ts

@@ -1,10 +1,12 @@
 export interface CanonicalDocumentDefinition {
     readonly target: string;
+    readonly title?: string;
     readonly startLine: number;
     readonly endLine: number;
 }
 export interface CanonicalDocumentLink {
     readonly kind: 'link' | 'ambiguous-reference';
+    readonly title?: string;
     readonly target?: string;
     readonly startLine: number;
     readonly endLine: number;
@@ -15,7 +17,9 @@ export interface CanonicalDocumentLink {
     readonly referenceEndLine?: number;
 }
 /** Explicit Markdown links only: this deliberately does not change the graph linker's policy. */
-export declare function canonicalDocumentLinks(content: string): readonly CanonicalDocumentLink[];
+export declare function canonicalDocumentLinks(content: string, options?: {
+    readonly includeTitles?: boolean;
+}): readonly CanonicalDocumentLink[];
 export type CanonicalDocumentLinkResolution = {
     readonly kind: 'path';
     readonly path: string;

package/dist/extraction/canonical-document-links.js

@@ -1,7 +1,7 @@
 import { posix } from 'node:path';
 import { fromMarkdown } from 'mdast-util-from-markdown';
 /** Explicit Markdown links only: this deliberately does not change the graph linker's policy. */
-export function canonicalDocumentLinks(content) {
+export function canonicalDocumentLinks(content, options = {}) {
     const tree = fromMarkdown(content);
     const definitions = new Map();
     const collect = (node) => {
@@ -18,20 +18,20 @@ export function canonicalDocumentLinks(content) {
     const links = [];
     const visit = (node) => {
         if (node.type === 'link' && node.position) {
-            links.push({ kind: 'link', target: node.url,
+            links.push({ kind: 'link', target: node.url, ...(options.includeTitles && node.title ? { title: node.title } : {}),
                 startLine: node.position.start.line, endLine: node.position.end.line });
             return;
         }
         if (node.type === 'linkReference' && node.position) {
             const declared = (definitions.get(node.identifier) ?? []).flatMap(definition => definition.position
-                ? [{ target: definition.url, startLine: definition.position.start.line, endLine: definition.position.end.line }]
+                ? [{ target: definition.url, ...(options.includeTitles && definition.title ? { title: definition.title } : {}), startLine: definition.position.start.line, endLine: definition.position.end.line }]
                 : []);
             const first = declared[0];
             if (!first)
                 return;
             const reference = { identifier: node.identifier,
                 referenceStartLine: node.position.start.line, referenceEndLine: node.position.end.line };
-            if (new Set(declared.map(definition => definition.target)).size > 1) {
+            if (new Set(declared.map(definition => JSON.stringify([definition.target, definition.title]))).size > 1) {
                 // Never silently choose the first conflicting definition, as normal Markdown rendering does.
                 links.push({ kind: 'ambiguous-reference', ...reference,
                     startLine: node.position.start.line, endLine: node.position.end.line, definitions: declared });

package/dist/extraction/code-inventory.d.ts

@@ -0,0 +1,6 @@
+import type { CodeInventory } from '@weftlet/core';
+import type { GitTreeEntry } from '../repository/git.js';
+import type { ScipSourceProject } from '../configuration/scip-project.js';
+import type { ScipIndexResult } from './scip-runtime.js';
+/** No package contents, dependencies or active checkout are read. Boundary names are physical paths. */
+export declare function buildCodeInventory(entries: readonly GitTreeEntry[], selectedPaths: readonly string[], codeRoots: readonly string[], project: ScipSourceProject | undefined, index: ScipIndexResult): CodeInventory;

package/dist/extraction/code-inventory.js

@@ -0,0 +1,26 @@
+import { matchesRepositoryGlob } from '../repository/glob.js';
+import { sha256, stableJson } from '../infrastructure/util.js';
+/** No package contents, dependencies or active checkout are read. Boundary names are physical paths. */
+export function buildCodeInventory(entries, selectedPaths, codeRoots, project, index) {
+    const regular = entries.filter(entry => entry.type === 'blob' && ['100644', '100755'].includes(entry.mode));
+    const manifests = regular.filter(entry => entry.path === 'package.json' || entry.path.endsWith('/package.json'));
+    const roots = new Map(manifests.map(entry => [entry.path === 'package.json' ? '.' : entry.path.slice(0, -'/package.json'.length),
+        { path: entry.path, blobId: entry.objectId }]));
+    const orderedRoots = [...roots.keys()].filter(root => root !== '.').sort((a, b) => b.length - a.length || a.localeCompare(b));
+    const indexed = index.indexedPaths === undefined ? undefined : new Set(index.indexedPaths);
+    const selected = new Set(selectedPaths);
+    const files = regular.filter(entry => /\.(?:[cm]?ts|tsx)$/.test(entry.path)).map(entry => ({
+        path: entry.path, blobId: entry.objectId, projectRoot: orderedRoots.find(root => entry.path.startsWith(`${root}/`)) ?? '.',
+        codeRootSelected: selected.has(entry.path),
+        requested: project ? project.include.some(pattern => matchesRepositoryGlob(entry.path, pattern)) ? 'included' : 'excluded' : 'unknown',
+        ...(indexed ? { indexed: indexed.has(entry.path) } : {}),
+    })).sort((a, b) => a.path.localeCompare(b.path));
+    const projects = [...new Set(['.', ...roots.keys()])].sort().map(root => ({ root, ...(roots.has(root) ? { manifest: roots.get(root) } : {}) }));
+    const known = new Set(files.map(file => file.path));
+    const plain = { version: 'committed-code-inventory-v1', scipIndexDigest: index.digest,
+        selection: project ? 'source-project' : 'indexer-command',
+        indexObservation: indexed ? 'recorded' : 'unavailable', codeRoots: [...codeRoots],
+        ...(project ? { includePatterns: [...project.include] } : {}), projects, files,
+        ...(indexed ? { otherIndexedFiles: [...indexed].filter(path => !known.has(path)).length } : {}) };
+    return { ...plain, digest: sha256(stableJson(plain)) };
+}

package/dist/extraction/document-code-bindings.d.ts

@@ -0,0 +1,14 @@
+import type { ExtractionContext, GraphDiagnostic, GraphFact, SemanticSource } from '@weftlet/core';
+import type { GitRepository } from '../repository/git.js';
+export declare const documentCodeBindingIdentity: {
+    readonly id: "document-code-binding-extractor";
+    readonly version: "1.0.0";
+};
+export interface BindingSource extends SemanticSource {
+    readonly metadata: Pick<GraphFact, 'sourceAuthority' | 'sourceRole' | 'sourceOwnership' | 'sourcePolicyDigest'>;
+}
+/** Resolve only explicit declarations against current indexed evidence; no provider, checkout or basename search. */
+export declare function extractDocumentCodeBindings(repository: Pick<GitRepository, 'listEntriesAt' | 'readFileAt'>, context: ExtractionContext, sources: readonly BindingSource[], codeFacts: readonly GraphFact[], subjectFacts: readonly GraphFact[]): Promise<{
+    facts: readonly GraphFact[];
+    diagnostics: readonly GraphDiagnostic[];
+}>;

package/dist/extraction/document-code-bindings.js

@@ -0,0 +1,121 @@
+import { repositoryFileNode } from '@weftlet/core';
+import { sha256, stableJson } from '../infrastructure/util.js';
+import { documentSymbolLinks } from './symbol-selectors.js';
+import { resolveSymbolSelector } from './symbol-resolution.js';
+export const documentCodeBindingIdentity = { id: 'document-code-binding-extractor', version: '1.0.0' };
+const subjectKinds = new Set(['Capability', 'Workflow', 'Contract', 'Invariant']);
+const proof = (fact) => ({ factId: fact.id, provenance: fact.provenance });
+/** Resolve the declared subject independently of code selection; retain every supporting assertion. */
+function mappingSubject(subjectId, predicate, source, subjectFacts) {
+    if (!subjectId)
+        return { subject: repositoryFileNode(source.path), basis: [] };
+    const basis = subjectFacts.filter(fact => !fact.codeBinding && [fact.subject, fact.object].some(node => node.id === subjectId));
+    const nodes = basis.flatMap(fact => [fact.subject, fact.object].filter(node => node.id === subjectId));
+    if (!nodes.length || new Set(nodes.map(node => node.kind)).size !== 1 || !subjectKinds.has(nodes[0].kind) || basis.length > 100) {
+        return { problem: 'Mapping subject must identify one existing business node with at most 100 supporting assertions.' };
+    }
+    if (source.metadata.sourceRole === 'validation' && predicate === 'implementedBy') {
+        return { problem: 'A validation document cannot establish a product implementation mapping.' };
+    }
+    return { subject: nodes[0], basis };
+}
+/** Keep both a reference use and all destination declarations in the evidence envelope. */
+function linkCitations(source, link, commitSha) {
+    const cite = (startLine, endLine) => ({ path: source.path, startLine, endLine,
+        digest: source.digest, commitSha });
+    const citations = [cite(link.startLine, link.endLine)];
+    if (link.referenceStartLine !== undefined)
+        citations.push(cite(link.referenceStartLine, link.referenceEndLine));
+    for (const definition of link.definitions ?? [])
+        citations.push(cite(definition.startLine, definition.endLine));
+    return [...new Map(citations.map(span => [stableJson(span), span])).values()];
+}
+/** Resolve only explicit declarations against current indexed evidence; no provider, checkout or basename search. */
+export async function extractDocumentCodeBindings(repository, context, sources, codeFacts, subjectFacts) {
+    const facts = new Map(), diagnostics = new Map();
+    const selectedSources = sources.map(source => ({ source, links: documentSymbolLinks(source.path, source.content) })).filter(item => item.links.length);
+    if (!selectedSources.length)
+        return { facts: [], diagnostics: [] };
+    const entries = new Map((await repository.listEntriesAt(context.commitSha)).map(entry => [entry.path, entry]));
+    const current = codeFacts.filter(fact => fact.provenance.commitSha === context.commitSha);
+    const texts = new Map();
+    const read = async (path) => {
+        let text = texts.get(path);
+        if (text === undefined) {
+            text = await repository.readFileAt(context.commitSha, path);
+            texts.set(path, text);
+        }
+        return text;
+    };
+    const regular = (path) => { const entry = entries.get(path); return entry?.type === 'blob' && ['100644', '100755'].includes(entry.mode); };
+    const verifyDefinitions = async (proofs) => {
+        if (proofs.length > 1000)
+            return `Binding requires ${proofs.length} occurrence proofs, exceeding the 1000-proof bound; no partial binding emitted.`;
+        for (const fact of proofs) {
+            if (!regular(fact.provenance.path) || fact.provenance.digest !== sha256(await read(fact.provenance.path))) {
+                return 'Indexed definition does not match regular committed target bytes.';
+            }
+        }
+        return undefined;
+    };
+    for (const { source, links } of selectedSources) {
+        for (const item of links) {
+            const documentCitations = linkCitations(source, item.link, context.commitSha);
+            const gap = (reason, related = []) => {
+                const record = { kind: 'implementationGaps', reason, provenance: documentCitations,
+                    relatedNodeIds: [...new Set([repositoryFileNode(source.path).id, ...related])].sort(), evidenceScope: 'source' };
+                const id = sha256(stableJson({ ...record, extractor: documentCodeBindingIdentity }));
+                diagnostics.set(id, { id, ...record });
+            };
+            if (!regular(source.path) || sha256(source.content) !== source.digest || await read(source.path) !== source.content) {
+                gap('Binding document does not match regular committed source bytes.');
+                continue;
+            }
+            if (item.problem || !item.selector) {
+                gap(item.problem);
+                continue;
+            }
+            const selector = item.selector, entry = entries.get(selector.path);
+            if (!entry || entry.type !== 'blob' || !['100644', '100755'].includes(entry.mode)) {
+                gap(`Symbol target ${selector.path} is not a regular committed file.`, [repositoryFileNode(selector.path).id]);
+                continue;
+            }
+            const text = await read(selector.path);
+            if (current.some(fact => fact.provenance.path === selector.path && fact.provenance.digest !== sha256(text))) {
+                gap('Indexed target does not match the cited committed bytes.');
+                continue;
+            }
+            const resolution = resolveSymbolSelector(selector, current, text);
+            if ('problem' in resolution) {
+                gap(`${resolution.problem} Candidate identities: ${resolution.candidates.length}; at most 100 IDs are included.`, resolution.candidates.slice(0, 100));
+                continue;
+            }
+            const proofProblem = await verifyDefinitions([...resolution.selected, ...resolution.definitions]);
+            if (proofProblem) {
+                gap(proofProblem, [resolution.node.id]);
+                continue;
+            }
+            const mapped = mappingSubject(item.subjectId, item.predicate, source, subjectFacts);
+            if ('problem' in mapped) {
+                gap(mapped.problem, item.subjectId ? [item.subjectId] : []);
+                continue;
+            }
+            const { subject, basis } = mapped;
+            const subjectEvidence = basis.map(fact => ({ ...proof(fact),
+                ...(fact.authority === undefined ? {} : { authority: fact.authority }),
+                ...(fact.sourceAuthority === undefined ? {} : { sourceAuthority: fact.sourceAuthority }),
+                ...(fact.extractionReview === undefined ? {} : { extractionReview: fact.extractionReview }),
+            })).sort((a, b) => a.factId.localeCompare(b.factId));
+            const codeBinding = { schemaVersion: 1, method: 'explicit-markdown', selector,
+                documentCitations, selectedOccurrences: resolution.selected.map(proof), definitions: resolution.definitions.map(proof), subjectEvidence };
+            const assertion = { subject, predicate: item.predicate, object: resolution.node, provenance: documentCitations[0],
+                codeBinding, extractor: documentCodeBindingIdentity, confidence: Math.min(1, ...basis.map(fact => fact.confidence)),
+                authority: 'inferred', ...source.metadata,
+                extractionReview: basis.some(fact => fact.extractionReview === 'unreviewed') ? 'unreviewed' : 'deterministic' };
+            const id = sha256(stableJson(assertion));
+            facts.set(id, { id, ...assertion, snapshotId: context.snapshotId });
+        }
+    }
+    return { facts: [...facts.values()].sort((a, b) => a.id.localeCompare(b.id)),
+        diagnostics: [...diagnostics.values()].sort((a, b) => a.id.localeCompare(b.id)) };
+}

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

@@ -0,0 +1,12 @@
+import { type ExtractionContext, type GraphDiagnostic, type GraphFact } from '@weftlet/core';
+import type { GitRepository } from '../repository/git.js';
+import type { BindingSource } from './document-code-bindings.js';
+export declare const documentObligationIdentity: {
+    readonly id: "document-obligation-extractor";
+    readonly version: "1.0.0";
+};
+/** Exact opt-in declarations only. Prose interpretation, inferred transport joins and policy verdicts are separate. */
+export declare function extractDocumentObligations(repository: Pick<GitRepository, 'listEntriesAt' | 'readFileAt'>, context: ExtractionContext, sources: readonly BindingSource[]): Promise<{
+    facts: readonly GraphFact[];
+    diagnostics: readonly GraphDiagnostic[];
+}>;

package/dist/extraction/document-obligations.js

@@ -0,0 +1,112 @@
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { createHash } from 'node:crypto';
+import { obligationContractNode, parseObligationDeclaration, repositoryFileNode } from '@weftlet/core';
+import { parseUniqueJson } from '../infrastructure/unique-json.js';
+import { sha256, stableJson } from '../infrastructure/util.js';
+export const documentObligationIdentity = { id: 'document-obligation-extractor', version: '1.0.0' };
+/** Git names the original blob bytes. Reject text decoding that cannot reproduce them. */
+function matchesCommittedBlob(content, objectId) {
+    const bytes = Buffer.from(content, 'utf8');
+    const algorithm = objectId.length === 64 ? 'sha256' : 'sha1';
+    return createHash(algorithm).update(`blob ${bytes.length}\0`).update(bytes).digest('hex') === objectId;
+}
+function blocks(source, commitSha) {
+    const result = [];
+    const visit = (node) => {
+        if (node.type === 'code' && node.lang === 'weftlet-obligation')
+            result.push({ content: node.value,
+                provenance: { path: source.path, digest: source.digest, commitSha,
+                    startLine: node.position.start.line, endLine: node.position.end.line } });
+        if ('children' in node)
+            for (const child of node.children)
+                visit(child);
+    };
+    visit(fromMarkdown(source.content));
+    return result;
+}
+/** Exact opt-in declarations only. Prose interpretation, inferred transport joins and policy verdicts are separate. */
+export async function extractDocumentObligations(repository, context, sources) {
+    const selected = sources.map(source => ({ source, blocks: blocks(source, context.commitSha) })).filter(item => item.blocks.length);
+    if (!selected.length)
+        return { facts: [], diagnostics: [] };
+    if (selected.reduce((sum, item) => sum + item.blocks.length, 0) > 500)
+        throw new Error('Obligation sources exceed the 500-declaration bound; no partial extraction');
+    const entries = new Map((await repository.listEntriesAt(context.commitSha)).map(entry => [entry.path, entry]));
+    const regular = (path) => { const entry = entries.get(path); return entry?.type === 'blob' && ['100644', '100755'].includes(entry.mode); };
+    const texts = new Map();
+    const read = async (path) => {
+        if (!texts.has(path))
+            texts.set(path, await repository.readFileAt(context.commitSha, path));
+        return texts.get(path);
+    };
+    const facts = [], diagnostics = [];
+    const gap = (reason, provenance, relatedNodeIds) => {
+        const item = { reason: `Contract obligation: ${reason}`, provenance, relatedNodeIds,
+            kind: 'implementationGaps', evidenceScope: 'source' };
+        diagnostics.push({ ...item, id: sha256(stableJson({ ...item, extractor: documentObligationIdentity })) });
+    };
+    for (const { source, blocks } of selected) {
+        if (!regular(source.path) || sha256(source.content) !== source.digest || await read(source.path) !== source.content ||
+            !matchesCommittedBlob(source.content, entries.get(source.path).objectId)) {
+            gap('source does not match regular committed bytes.', blocks.map(block => block.provenance), [repositoryFileNode(source.path).id]);
+            continue;
+        }
+        if (source.metadata.sourceRole === 'validation') {
+            gap('validation sources cannot declare producer guarantees or consumer requirements.', blocks.map(block => block.provenance), [repositoryFileNode(source.path).id]);
+            continue;
+        }
+        for (const block of blocks) {
+            let declaration;
+            try {
+                if (Buffer.byteLength(block.content) > 65_536)
+                    throw new Error('Declaration exceeds 64 KiB');
+                declaration = parseObligationDeclaration(parseUniqueJson(block.content));
+            }
+            catch {
+                gap('invalid declaration: use bounded schemaVersion 1 JSON with unique supported keys; no relationship emitted.', [block.provenance], [repositoryFileNode(source.path).id]);
+                continue;
+            }
+            const subject = repositoryFileNode(declaration.endpoint), object = obligationContractNode(context.repositoryId, declaration.contract);
+            if (!regular(declaration.endpoint)) {
+                gap('endpoint is missing or is not a regular committed file; no relationship emitted.', [block.provenance], [subject.id, object.id]);
+                continue;
+            }
+            const endpoint = await read(declaration.endpoint);
+            if (!matchesCommittedBlob(endpoint, entries.get(declaration.endpoint).objectId)) {
+                gap('endpoint cannot be read as lossless committed UTF-8 text; no relationship emitted.', [block.provenance], [subject.id, object.id]);
+                continue;
+            }
+            const assertion = { subject, object, predicate: declaration.role === 'guarantee' ? 'emits' : 'consumes',
+                provenance: block.provenance, extractor: documentObligationIdentity, confidence: 1,
+                authority: 'inferred', extractionReview: 'deterministic', ...source.metadata,
+                contractObligation: { method: 'explicit-markdown', repositoryId: context.repositoryId, declaration,
+                    endpointSource: { path: declaration.endpoint, digest: sha256(endpoint), commitSha: context.commitSha,
+                        startLine: 1, endLine: endpoint.split('\n').length } } };
+            facts.push({ ...assertion, id: sha256(stableJson(assertion)), snapshotId: context.snapshotId });
+        }
+    }
+    diagnoseObligationGroups(facts, gap);
+    return { facts: facts.sort((a, b) => a.id.localeCompare(b.id)), diagnostics: diagnostics.sort((a, b) => a.id.localeCompare(b.id)) };
+}
+function diagnoseObligationGroups(facts, gap) {
+    const identities = new Map();
+    for (const fact of facts) {
+        const key = stableJson([fact.provenance.path, fact.contractObligation.declaration.id]);
+        const group = identities.get(key) ?? [];
+        group.push(fact);
+        identities.set(key, group);
+    }
+    for (const group of identities.values())
+        if (group.length > 1)
+            gap('duplicate declaration ID within a source; all cited assertions retained for review.', group.map(fact => fact.provenance), [...new Set(group.flatMap(fact => [fact.subject.id, fact.object.id]))]);
+    const contracts = new Map();
+    for (const fact of facts) {
+        const group = contracts.get(fact.object.id) ?? [];
+        group.push(fact);
+        contracts.set(fact.object.id, group);
+    }
+    for (const group of contracts.values())
+        if (new Set(group.map(fact => fact.contractObligation.declaration.role)).size < 2) {
+            gap('only one side of this contract has structured obligations in the selected documents; other producers/consumers and compatibility remain unknown.', group.map(fact => fact.provenance), [group[0].object.id]);
+        }
+}

package/dist/extraction/mapping-candidates.d.ts

@@ -0,0 +1,13 @@
+import type { GraphFact, MappingCandidate } from '@weftlet/core';
+/** Join real callable syntax to exact indexed name occurrences, never fuzzy labels. */
+export declare function mappingCandidates(path: string, text: string, digest: string, commit: string, facts: readonly GraphFact[], limits: {
+    maxCandidates: number;
+    maxInputBytes: number;
+}): {
+    candidates: (MappingCandidate & {
+        text: string;
+    })[];
+    issues: string[];
+    excluded: number;
+    observed: number;
+};

package/dist/extraction/mapping-candidates.js

@@ -0,0 +1,46 @@
+import ts from 'typescript';
+import { callableName, factsAt, isAmbient, isCallable, parseCallSource, syntaxSpan } from './call-syntax.js';
+/** Join real callable syntax to exact indexed name occurrences, never fuzzy labels. */
+export function mappingCandidates(path, text, digest, commit, facts, limits) {
+    const parsed = parseCallSource(path, text, digest, facts);
+    const candidates = [], issues = [];
+    let excluded = 0, observed = 0;
+    const seen = new Set();
+    if (parsed.parseErrors.length)
+        return { candidates, issues: ['invalid-typescript'], excluded, observed };
+    const add = (node, definitions) => {
+        observed++;
+        const symbol = definitions[0].subject;
+        if (seen.has(symbol.id))
+            issues.push('multiple-implementation-bodies');
+        seen.add(symbol.id);
+        if (observed > limits.maxCandidates) {
+            issues.push('candidate-budget-exceeded');
+            return;
+        }
+        const body = syntaxSpan(node, parsed.source, digest, commit);
+        const proofs = facts.filter(f => f.codeOccurrence?.role === 'definition' && f.subject.id === symbol.id);
+        // Avoid expanding many overlapping large callable bodies merely to discover a budget failure.
+        const excerpt = node.getText(parsed.source), excerptBytes = Buffer.byteLength(excerpt);
+        const tooLarge = excerptBytes > limits.maxInputBytes;
+        if (tooLarge)
+            issues.push('input-budget-exceeded');
+        candidates.push({ node: symbol, body, excerptBytes, definitions: proofs, text: tooLarge ? '' : excerpt });
+    };
+    const visit = (node) => {
+        if (isCallable(node)) {
+            const definitions = factsAt(callableName(node), parsed, commit, 'definition');
+            const ids = new Set(definitions.map(f => f.subject.id));
+            if (!node.body || isAmbient(node) || !callableName(node))
+                excluded++;
+            else if (ids.size !== 1 || definitions.some(f => f.subject.codeSymbol?.resolution !== 'indexed-definition')) {
+                issues.push('callable-without-unambiguous-indexed-definition');
+            }
+            else
+                add(node, definitions);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(parsed.source);
+    return { candidates, issues: [...new Set(issues)], excluded, observed };
+}