@weftlet/toolkit 0.6.1 → 0.7.0

package/dist/graph/compatibility-renderer.js

@@ -0,0 +1,45 @@
+import { sourceLocation } from '@weftlet/core';
+import { factEvidenceDescription } from './evidence-description.js';
+import { diagnosticSummary } from './diagnostics.js';
+import { coverageDescription } from './coverage.js';
+const quoted = (value) => JSON.stringify(value).replace(/[\\`*_{}\[\]()<>!|]/g, '\\$&');
+const explanations = {
+    'missing-assertion': 'One or both exact assertion IDs are absent from this snapshot.',
+    'invalid-evidence': 'The selected records lack valid obligation metadata or matching snapshot/revision provenance.',
+    'wrong-roles': 'Select a producer guarantee first and a consumer requirement second.',
+    'different-contracts': 'The assertions do not identify the same exact repository/scoped/transport/versioned contract.',
+    'unknown-version': 'A contract version is unknown; no version equivalence is assumed.',
+    'missing-context': 'Documented domain, stage, numeric constraint or unit is missing.',
+    'different-domain': 'The documented domains differ.',
+    'different-metric': 'The documented metrics differ; no semantic equivalence is inferred.',
+    'different-unit': 'The units differ; no unit conversion is inferred.',
+    'different-stage': 'The measurement stages differ; no elapsed-time or transformation model is available.',
+    'unsupported-number': 'A numeric limit is nonfinite or outside the supported safe numeric magnitude.',
+    'competing-declarations': 'Other assertions describe this endpoint/property; no winning declaration was selected.',
+    'extraction-gaps': 'Relevant source/extraction gaps remain in the saved evidence.',
+    subset: 'At the same declared stage, every value allowed by the producer constraint is allowed by the consumer constraint.',
+    'overlap-only': 'Some allowed producer values do not satisfy the consumer constraint. This alone is not a contradiction.',
+    disjoint: 'At the same declared stage, no value satisfies both constraints. This is a documented range incompatibility for an untransformed accepted value.',
+    'consumer-revalidation': 'The consumer explicitly requires revalidation. Verify its check and rejection behavior; the declaration alone does not prove them.',
+};
+export function renderContractCompatibility(report) {
+    const { snapshot, assessment, context, evidenceState } = report;
+    return ['# Selected contract constraint assessment',
+        `Snapshot: ${quoted(snapshot.snapshotId)} (${snapshot.commitSha}); configuration ${snapshot.configurationDigest ?? 'unknown'}`,
+        `Scope: ${snapshot.scope?.map(quoted).join(', ') ?? 'unknown'}; selected assertions: ${quoted(report.selection.producerFactId)}, ${quoted(report.selection.consumerFactId)}`,
+        `Result: ${assessment.status}; authority: ${assessment.authority}; method: ${assessment.version}; CI gate eligible: false; fulfillment: not evaluated`,
+        ...assessment.reasons.map(reason => `- ${explanations[reason]}`),
+        ...(evidenceState ? [`Stale: ${evidenceState.stale}; configuration matches: ${evidenceState.configurationMatches}; extraction compatible: ${evidenceState.extractionCompatible ?? 'unknown'}`,
+            `Excluded working changes: ${evidenceState.excludedWorkingChanges.map(quoted).join(', ') || '(none)'}; overlay freshness: ${evidenceState.overlayFreshness ?? 'not an overlay'}`] : []),
+        '', '## Cited declarations', ...report.facts.map(fact => `- ${quoted(fact.id)} [${fact.authority ?? 'unspecified'}; source ${fact.sourceAuthority ?? 'unspecified'}; review ${fact.extractionReview ?? 'unspecified'}] ` +
+            `${quoted(sourceLocation(fact.provenance))}–${fact.provenance.endLine}@${fact.provenance.commitSha}: ${quoted(factEvidenceDescription(fact) ?? 'Not a structured obligation')}`),
+        '', '## Assessment limits', ...assessment.conditions.map(condition => `- ${condition}`),
+        coverageDescription(report.coverage), ...report.coverage.gaps.map(quoted),
+        '', '## Further evidence',
+        `Other contract-incident assertions: ${context.otherIncidentFacts}; competing declarations: ${context.competingFacts}; omitted competing IDs: ${context.omittedCompetingFacts}.`,
+        ...context.competingFactIds.map(id => `- Competing assertion: ${quoted(id)}`),
+        ...context.contractNodeIds.map(id => `- Use graph.neighbors with contract ${quoted(id)} and the same snapshot for all declarations and continuation.`),
+        ...context.endpointNodeIds.map(id => `- Use graph.neighbors with endpoint ${quoted(id)} for indexed definitions, mappings and tests; file existence alone proves no fulfillment.`),
+        '', '## Scoped diagnostics', ...diagnosticSummary(report).map(quoted),
+    ].join('\n');
+}

package/dist/graph/compatibility-request.d.ts

@@ -0,0 +1,3 @@
+import type { ContractCompatibilityRequest } from '@weftlet/core';
+/** No search, implicit current head, policy mutation or caller-supplied authority. */
+export declare function parseContractCompatibilityRequest(value: unknown): ContractCompatibilityRequest;

package/dist/graph/compatibility-request.js

@@ -0,0 +1,18 @@
+/** No search, implicit current head, policy mutation or caller-supplied authority. */
+export function parseContractCompatibilityRequest(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('graph.compatibility arguments must be an object');
+    const item = value, fields = ['snapshotId', 'producerFactId', 'consumerFactId'];
+    if (Object.keys(item).some(key => !fields.includes(key)))
+        throw new Error('Unknown graph.compatibility field');
+    const identifier = (key, maximum) => {
+        const value = item[key];
+        if (typeof value !== 'string' || !value.trim() || value.length > maximum)
+            throw new Error(`${key} must be a nonempty string of at most ${maximum} characters`);
+        return value;
+    };
+    const request = { snapshotId: identifier('snapshotId', 256), producerFactId: identifier('producerFactId', 8192), consumerFactId: identifier('consumerFactId', 8192) };
+    if (request.producerFactId === request.consumerFactId)
+        throw new Error('Select distinct producer and consumer assertion IDs');
+    return request;
+}

package/dist/graph/compatibility.d.ts

@@ -0,0 +1,7 @@
+import type { ContractCompatibilityReport, ContractCompatibilityRequest, ContractCompatibilityService, SnapshotStore } from '@weftlet/core';
+/** Read-only exact pair assessment over the same lossless RDF facts used by exploration and visualization. */
+export declare class SnapshotContractCompatibilityService implements ContractCompatibilityService {
+    private readonly store;
+    constructor(store: Pick<SnapshotStore, 'read'>);
+    assess(input: ContractCompatibilityRequest): Promise<ContractCompatibilityReport>;
+}

package/dist/graph/compatibility.js

@@ -0,0 +1,67 @@
+import { RdfEvidenceGraph } from './rdf.js';
+import { snapshotContext } from './snapshot-context.js';
+import { selectDiagnostics } from './diagnostics.js';
+import { parseContractCompatibilityRequest } from './compatibility-request.js';
+import { compareDeclaredConstraints } from './constraint-comparison.js';
+import { compatibilityContext } from './compatibility-context.js';
+import { renderContractCompatibility } from './compatibility-renderer.js';
+import { coverageForFacts } from './coverage.js';
+const conditions = [
+    'Only the two selected numeric declarations are compared, within this saved scope; other product obligations may exist.',
+    'Matching metric/unit names assume the same meaning. No unit conversion, transformations or elapsed-time model is inferred.',
+    'Source approval and assertion review stay on the cited facts. This assessment supplies no policy approval or CI pass/fail.',
+    'Implementation correctness, runtime delivery, consumer rejection/availability and current-diff validity are not established.',
+];
+async function assessSelected(snapshot, facts, context, diagnostics) {
+    const base = { version: 'declared-constraint-comparison-v1', scope: 'selected-assertion-pair',
+        authority: facts.some(fact => fact.authority === 'draft') ? 'draft' : 'inferred',
+        gateEligible: false, fulfillment: 'not-evaluated', conditions };
+    const unknown = (...reasons) => ({ ...base, status: 'unknown', reasons });
+    if (facts.length !== 2)
+        return unknown('missing-assertion');
+    if (facts.some(fact => !fact.contractObligation || fact.snapshotId !== snapshot.manifest.snapshotId ||
+        fact.provenance.commitSha !== snapshot.manifest.commitSha))
+        return unknown('invalid-evidence');
+    // Bound structural validation to these two records. Never revalidate the complete saved graph on a read query.
+    if (!(await new RdfEvidenceGraph({ ...snapshot, facts }).validate()).conforms)
+        return unknown('invalid-evidence');
+    const [producer, consumer] = facts;
+    if (producer.object.id !== consumer.object.id)
+        return unknown('different-contracts');
+    const gaps = [];
+    if (context.competingFacts)
+        gaps.push('competing-declarations');
+    if (['missingIntent', 'ambiguousIntent', 'implementationGaps'].some(key => {
+        const section = diagnostics[key];
+        return section.items.length || section.omittedRelevant;
+    }))
+        gaps.push('extraction-gaps');
+    if (gaps.length)
+        return unknown(...gaps);
+    return { ...base, ...compareDeclaredConstraints(producer.contractObligation.declaration, consumer.contractObligation.declaration) };
+}
+/** Read-only exact pair assessment over the same lossless RDF facts used by exploration and visualization. */
+export class SnapshotContractCompatibilityService {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    async assess(input) {
+        const request = parseContractCompatibilityRequest(input), snapshot = await this.store.read(request.snapshotId);
+        if (!snapshot)
+            throw new Error('No graph snapshot is available for that identifier');
+        if (snapshot.manifest.snapshotId !== request.snapshotId)
+            throw new Error('Saved snapshot identity does not match the requested identifier');
+        const all = await new RdfEvidenceGraph(snapshot).facts();
+        const byId = new Map(all.map(fact => [fact.id, fact]));
+        if (byId.size !== all.length)
+            throw new Error('Duplicate fact identities prevent exact compatibility selection');
+        const facts = [request.producerFactId, request.consumerFactId].flatMap(id => byId.has(id) ? [byId.get(id)] : []);
+        const context = compatibilityContext(all, facts);
+        const diagnostics = selectDiagnostics(snapshot, {}, facts, [], [], new Set(context.contractNodeIds));
+        const assessment = await assessSelected(snapshot, facts, context, diagnostics);
+        const plain = { snapshot: snapshotContext(snapshot.manifest), selection: request, facts,
+            coverage: coverageForFacts(facts, snapshot), assessment, context, diagnostics };
+        return { ...plain, markdown: renderContractCompatibility(plain) };
+    }
+}

package/dist/graph/constraint-comparison.d.ts

@@ -0,0 +1,7 @@
+import type { CompatibilityReason, ContractCompatibilityStatus, ObligationDeclaration } from '@weftlet/core';
+export interface ConstraintComparison {
+    readonly status: ContractCompatibilityStatus;
+    readonly reasons: readonly CompatibilityReason[];
+}
+/** Arithmetic on declared numeric sets only. No unit conversion, policy approval or implementation inference. */
+export declare function compareDeclaredConstraints(producer: ObligationDeclaration, consumer: ObligationDeclaration): ConstraintComparison;

package/dist/graph/constraint-comparison.js

@@ -0,0 +1,49 @@
+const unknown = (...reasons) => ({ status: 'unknown', reasons });
+function interval(constraint) {
+    if (constraint.operator === 'at-most')
+        return [-Infinity, constraint.value];
+    if (constraint.operator === 'at-least')
+        return [constraint.value, Infinity];
+    return [constraint.value, constraint.value];
+}
+function contextProblems(producer, consumer) {
+    const problems = [];
+    if (!producer.contract.version || !consumer.contract.version)
+        problems.push('unknown-version');
+    if (!producer.domain || !consumer.domain || !producer.stage || !consumer.stage ||
+        !producer.constraint || !consumer.constraint || !producer.constraint.unit || !consumer.constraint.unit)
+        return [...problems, 'missing-context'];
+    if (producer.domain !== consumer.domain)
+        problems.push('different-domain');
+    if (producer.constraint.metric !== consumer.constraint.metric)
+        problems.push('different-metric');
+    if (producer.constraint.unit !== consumer.constraint.unit)
+        problems.push('different-unit');
+    for (const { value } of [producer.constraint, consumer.constraint]) {
+        if (!Number.isFinite(value) || Math.abs(value) > Number.MAX_SAFE_INTEGER)
+            problems.push('unsupported-number');
+    }
+    return [...new Set(problems)];
+}
+/** Arithmetic on declared numeric sets only. No unit conversion, policy approval or implementation inference. */
+export function compareDeclaredConstraints(producer, consumer) {
+    if (producer.role !== 'guarantee' || consumer.role !== 'requirement')
+        return unknown('wrong-roles');
+    const keys = ['scope', 'id', 'kind', 'version'];
+    if (keys.some(key => producer.contract[key] !== consumer.contract[key]))
+        return unknown('different-contracts');
+    const problems = contextProblems(producer, consumer);
+    if (problems.length)
+        return unknown(...problems);
+    if (producer.stage !== consumer.stage)
+        return consumer.revalidation === 'required'
+            ? { status: 'revalidation-required', reasons: ['different-stage', 'consumer-revalidation'] } : unknown('different-stage');
+    const [pl, pu] = interval(producer.constraint), [cl, cu] = interval(consumer.constraint);
+    if (pu < cl || cu < pl)
+        return { status: 'disjoint-constraints', reasons: ['disjoint'] };
+    if (cl <= pl && pu <= cu)
+        return { status: 'compatible-constraints', reasons: ['subset'] };
+    if (consumer.revalidation === 'required')
+        return { status: 'revalidation-required', reasons: ['overlap-only', 'consumer-revalidation'] };
+    return { status: 'insufficient-guarantee', reasons: ['overlap-only'] };
+}

package/dist/graph/coverage.d.ts

@@ -1,8 +1,8 @@
-import { type ContextPackCoverage, type ContextPackLane, type GraphFact } from '@weftlet/core';
+import { type ContextPackCoverage, type ContextPackLane, type GraphFact, type GraphSnapshot } 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;
+export declare function coverageForFacts(facts: readonly GraphFact[], snapshot?: GraphSnapshot): ContextPackCoverage;

package/dist/graph/coverage.js

@@ -1,5 +1,6 @@
 import { repositoryFileNode } from '@weftlet/core';
 import { contextPackEvidenceAuthority } from './authority.js';
+import { projectCodeCoverage, codeCoverageDescription } from './code-coverage-projection.js';
 export const contextPackLanes = [
     'productIntent',
     'contractsAndInvariants',
@@ -34,6 +35,8 @@ export function contextPackLaneForFact(fact) {
     if (isValidationFact(fact)) {
         return 'validationEvidence';
     }
+    if (kinds.has('CodeSymbol'))
+        return 'implementationAndConsumers';
     if (kinds.has('Contract') ||
         kinds.has('Invariant') ||
         kinds.has('PersistenceModel') ||
@@ -51,9 +54,10 @@ export function contextPackLaneForFact(fact) {
     return 'implementationAndConsumers';
 }
 export function coverageDescription(coverage) {
-    return coverage.scope === 'returned-page' && coverage.countsAreNonExclusive
+    const page = coverage.scope === 'returned-page' && coverage.countsAreNonExclusive
         ? 'Counts describe evidence on this returned page and may overlap; a code relationship can also describe a contract. They are not a percentage, a count of display groups, or proof that behavior is correct.'
         : 'Coverage scope and overlap metadata are unavailable for this Context Pack; re-query saved evidence for an explicit report.';
+    return `${page} ${codeCoverageDescription(coverage.code)}`;
 }
 /** Reporting only: never changes a fact's authority, identity, primary lane or stored bytes. */
 export function isImplementationEvidence(fact) {
@@ -69,12 +73,12 @@ export function isImplementationEvidence(fact) {
     const nodes = [fact.subject, fact.object];
     // Explicit adapter authority also supports logical component/provider identities.
     if (fact.authority === 'implemented')
-        return nodes.some(node => ['Component', 'Provider'].includes(node.kind));
+        return nodes.some(node => ['Component', 'Provider', 'CodeSymbol'].includes(node.kind));
     // Legacy deterministic adapters omitted authority. Require their cited physical file,
     // rather than treating every fact in the implementation display group as code evidence.
     return nodes.some(node => node.kind === 'Component' && node.id === file.id);
 }
-export function coverageForFacts(facts) {
+export function coverageForFacts(facts, snapshot) {
     const counts = {
         productIntent: 0, contractsAndInvariants: 0, implementationAndConsumers: 0, validationEvidence: 0,
     };
@@ -86,6 +90,7 @@ export function coverageForFacts(facts) {
             counts.implementationAndConsumers++;
     }
     return { scope: 'returned-page', countsAreNonExclusive: true, counts,
+        ...(snapshot ? { code: projectCodeCoverage(snapshot).overview } : {}),
         gaps: [
             ...contextPackLanes.filter(lane => counts[lane] === 0)
                 .map(lane => `No ${lane} evidence appears on this returned page.`),

package/dist/graph/diagnostics.d.ts

@@ -1,5 +1,5 @@
 import type { ContextPack, DiagnosticKind, DiagnosticReport, GraphDiagnostic, GraphFact, GraphSnapshot, ImpactScanRequest } from "@weftlet/core";
 export declare const diagnosticKinds: readonly DiagnosticKind[];
 export declare const MAX_DIAGNOSTICS_PER_KIND = 5;
-export declare function selectDiagnostics(snapshot: Pick<GraphSnapshot, 'unresolved' | 'diagnostics'>, request: ImpactScanRequest, facts: readonly GraphFact[], focus: readonly string[], queryDiagnostics: readonly GraphDiagnostic[]): DiagnosticReport;
+export declare function selectDiagnostics(snapshot: Pick<GraphSnapshot, 'unresolved' | 'diagnostics'>, request: ImpactScanRequest, facts: readonly GraphFact[], focus: readonly string[], queryDiagnostics: readonly GraphDiagnostic[], exactNodeIds?: ReadonlySet<string>): DiagnosticReport;
 export declare function diagnosticSummary(pack: Pick<ContextPack, 'diagnostics'>): readonly string[];

package/dist/graph/diagnostics.js

@@ -6,7 +6,13 @@ export const diagnosticKinds = [
     'drift',
 ];
 export const MAX_DIAGNOSTICS_PER_KIND = 5;
-function relevantDiagnostic(item, request, facts, focus) {
+function overlapsReturnedEvidence(item, facts) {
+    return item.provenance.some(span => facts.some(fact => fact.provenance.path === span.path && fact.provenance.startLine <= span.endLine &&
+        fact.provenance.endLine >= span.startLine));
+}
+function relevantDiagnostic(item, request, facts, focus, exactNodeIds) {
+    if (exactNodeIds)
+        return item.relatedNodeIds.some(id => exactNodeIds.has(id)) || overlapsReturnedEvidence(item, facts);
     const hasSelectors = request.ownerDocument ||
         request.changedFiles?.length ||
         request.symbols?.length ||
@@ -23,19 +29,17 @@ function relevantDiagnostic(item, request, facts, focus) {
         return true;
     // A source document can contain many independent capabilities. Match the cited passage,
     // not every diagnostic from a philosophy document that contributed one selected fact.
-    if (item.provenance.some((span) => facts.some((fact) => fact.provenance.path === span.path &&
-        fact.provenance.startLine <= span.endLine &&
-        fact.provenance.endLine >= span.startLine)))
+    if (overlapsReturnedEvidence(item, facts))
         return true;
     return (item.provenance.some((span) => span.path === request.ownerDocument) &&
         (focus.length === 0 || focus.some((term) => item.reason.toLowerCase().includes(term))));
 }
-export function selectDiagnostics(snapshot, request, facts, focus, queryDiagnostics) {
+export function selectDiagnostics(snapshot, request, facts, focus, queryDiagnostics, exactNodeIds) {
     const report = { unclassifiedLegacyCount: snapshot.unresolved.length };
     const unique = [...new Map((snapshot.diagnostics ?? []).map((item) => [item.id, item])).values()];
     for (const kind of diagnosticKinds) {
         const candidates = unique.filter((item) => item.kind === kind);
-        const relevant = candidates.filter((item) => relevantDiagnostic(item, request, facts, focus));
+        const relevant = candidates.filter((item) => relevantDiagnostic(item, request, facts, focus, exactNodeIds));
         const ordered = [
             ...queryDiagnostics.filter((item) => item.kind === kind),
             ...relevant.sort((a, b) => a.id.localeCompare(b.id)),

package/dist/graph/evidence-description.d.ts

@@ -0,0 +1,3 @@
+import type { GraphFact } from '@weftlet/core';
+/** Display the same structured assertion returned by queries; unknown values are never inferred. */
+export declare function factEvidenceDescription(fact: GraphFact): string | undefined;

package/dist/graph/evidence-description.js

@@ -0,0 +1,13 @@
+import { codeEvidenceDescription } from './code-description.js';
+/** Display the same structured assertion returned by queries; unknown values are never inferred. */
+export function factEvidenceDescription(fact) {
+    const obligation = fact.contractObligation?.declaration;
+    if (!obligation)
+        return codeEvidenceDescription(fact);
+    const constraint = obligation.constraint;
+    return `declared ${obligation.role}: ${obligation.statement}; ${obligation.contract.kind} contract ` +
+        `${obligation.contract.scope}/${obligation.contract.id}; version ${obligation.contract.version ?? 'unknown'}; ` +
+        `domain ${obligation.domain ?? 'unknown'}; stage ${obligation.stage ?? 'unknown'}; ` +
+        (constraint ? `${constraint.metric} ${constraint.operator} ${constraint.value}; unit ${constraint.unit ?? 'unknown'}; ` : 'constraint unknown; ') +
+        `consumer revalidation ${obligation.revalidation ?? 'unknown'}; fulfillment, delivery and compatibility not evaluated`;
+}

package/dist/graph/identity-preflight.js

@@ -1,7 +1,7 @@
 import { sha256, stableJson } from '@weftlet/core';
 const publicKinds = new Set([
     'Project', 'Document', 'Capability', 'Workflow', 'Component', 'Contract', 'Evidence',
-    'Invariant', 'Snapshot', 'Provider', 'PersistenceModel', 'Scope',
+    'Invariant', 'Snapshot', 'Provider', 'PersistenceModel', 'Scope', 'CodeSymbol',
 ]);
 /** Find the single-kind constraint's conflicts without constructing RDF or changing any fact. */
 export function inspectGraphIdentities(facts, options) {

package/dist/graph/neighborhood-renderer.d.ts

@@ -0,0 +1,2 @@
+import type { GraphNeighborhood } from '@weftlet/core';
+export declare function renderGraphNeighborhood(result: Omit<GraphNeighborhood, 'markdown'>): string;

package/dist/graph/neighborhood-renderer.js

@@ -0,0 +1,38 @@
+import { factEvidenceDescription } from './evidence-description.js';
+import { sourceLocation } from '@weftlet/core';
+import { contextPackEvidenceAuthority } from './authority.js';
+import { coverageDescription } from './coverage.js';
+import { documentSelectionDescription } from './document-role-description.js';
+import { diagnosticSummary } from './diagnostics.js';
+const quoted = (value) => JSON.stringify(value).replace(/[\\`*_{}\[\]()<>!|]/g, '\\$&');
+export function renderGraphNeighborhood(result) {
+    const { snapshot, focus, selection, frontier, evidenceState } = result;
+    return [
+        '# Exact graph neighborhood',
+        `Snapshot: ${quoted(snapshot.snapshotId)} (${snapshot.commitSha})`,
+        `Configuration: ${snapshot.configurationDigest ?? 'legacy/unknown'}; scope: ${snapshot.scope?.map(quoted).join(', ') ?? 'legacy/unknown'}`,
+        ...[documentSelectionDescription(snapshot.documentSelection)].filter(Boolean),
+        `Node: ${quoted(focus.nodeId)}; ${focus.status}`,
+        `Direction: ${selection.direction}; predicates: ${selection.predicates.join(', ') || 'all'}`,
+        `Incident assertions: ${selection.incidentFacts}; matching: ${selection.matchingFacts}; filtered out: ${selection.filteredFacts}`,
+        `Page: ${selection.returnedFacts} assertions at offset ${selection.offset}; remaining: ${selection.remainingFacts}; truncated: ${selection.truncated}`,
+        ...(selection.continuation ? [`Continuation: ${selection.continuation}`] : []),
+        ...(evidenceState ? [
+            `Stale relative to checkout: ${evidenceState.stale}; configuration matches: ${evidenceState.configurationMatches}; extraction compatible: ${evidenceState.extractionCompatible ?? 'unknown'}`,
+            `Excluded working changes: ${evidenceState.excludedWorkingChanges.map(quoted).join(', ') || '(none)'}`,
+            ...(evidenceState.overlayFreshness ? [`Overlay freshness: ${evidenceState.overlayFreshness}`] : []),
+        ] : []),
+        'This is one-hop saved evidence. It does not validate the current diff or establish complete repository coverage.',
+        coverageDescription(result.coverage),
+        ...result.coverage.gaps.map(gap => `GAP: ${gap}`),
+        '', '## Cited assertions',
+        ...result.facts.map(fact => `- [${contextPackEvidenceAuthority(fact)}] ${quoted(fact.subject.id)} —${fact.predicate}→ ${quoted(fact.object.id)} ` +
+            `(${quoted(sourceLocation(fact.provenance))}–${fact.provenance.endLine}${fact.provenance.endColumn === undefined ? '' : `:${fact.provenance.endColumn}`}; confidence ${fact.confidence}; source ${fact.sourceAuthority ?? 'unspecified'}; extraction ${fact.extractionReview ?? 'unspecified'}${factEvidenceDescription(fact) ? `; ${factEvidenceDescription(fact)}` : ''})`),
+        '', '## Scoped diagnostics',
+        ...diagnosticSummary(result).map(item => `- ${quoted(item)}`),
+        '', '## Further exploration',
+        `Selected neighbors: ${frontier.totalNeighbors}; not yet returned across these pages: ${frontier.remainingNeighbors}.`,
+        ...frontier.neighbors.map(node => `- ${quoted(node.nodeId)}: ${node.otherIncidentFacts} incident assertions outside this focus neighborhood; use graph.neighbors with the same snapshot to inspect them.`),
+        'Counts concern the saved scope. Absence or an exhausted page is not proof that a product dependency does not exist.',
+    ].join('\n');
+}

package/dist/graph/neighborhood-request.d.ts

@@ -0,0 +1,9 @@
+/** Shared validation/defaults for public API, CLI and MCP. Never interpret IDs as text search. */
+export declare function parseGraphNeighborsRequest(value: unknown): {
+    continuation?: string | undefined;
+    snapshotId: string;
+    nodeId: string;
+    direction: "incoming" | "outgoing" | "both";
+    predicates: ("references" | "realizes" | "implementedBy" | "consumes" | "emits" | "persistsTo" | "governedBy" | "definedBy" | "verifiedBy" | "operationallyOwnedBy" | "decisionAuthority" | "routesThrough" | "authorizedBy" | "sourcedFrom" | "contains" | "calls")[];
+    maxFacts: number;
+};

package/dist/graph/neighborhood-request.js

@@ -0,0 +1,37 @@
+import { graphPredicates } from '@weftlet/core';
+const fields = new Set(['snapshotId', 'nodeId', 'direction', 'predicates', 'maxFacts', 'continuation']);
+function identifier(value, name, maximum) {
+    if (typeof value !== 'string' || !value.trim() || value.length > maximum) {
+        throw new Error(`${name} must be a non-empty string of at most ${maximum} characters`);
+    }
+    return value;
+}
+/** Shared validation/defaults for public API, CLI and MCP. Never interpret IDs as text search. */
+export function parseGraphNeighborsRequest(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('graph.neighbors arguments must be an object');
+    }
+    const record = value;
+    const unexpected = Object.keys(record).filter(field => !fields.has(field));
+    if (unexpected.length)
+        throw new Error(`Unknown graph.neighbors fields: ${unexpected.join(', ')}`);
+    const snapshotId = identifier(record.snapshotId, 'snapshotId', 256);
+    const nodeId = identifier(record.nodeId, 'nodeId', 8192);
+    const direction = record.direction === undefined ? 'both' : record.direction;
+    if (direction !== 'incoming' && direction !== 'outgoing' && direction !== 'both') {
+        throw new Error('direction must be incoming, outgoing or both');
+    }
+    const predicates = record.predicates === undefined ? [] : record.predicates;
+    if (!Array.isArray(predicates) || predicates.length > graphPredicates.length ||
+        predicates.some(item => !graphPredicates.includes(item))) {
+        throw new Error('predicates must be an array of supported graph predicates');
+    }
+    const maxFacts = record.maxFacts === undefined ? 60 : record.maxFacts;
+    if (!Number.isInteger(maxFacts) || Number(maxFacts) < 1 || Number(maxFacts) > 200) {
+        throw new Error('maxFacts must be an integer between 1 and 200');
+    }
+    const continuation = record.continuation === undefined ? undefined
+        : identifier(record.continuation, 'continuation', 2048);
+    return { snapshotId, nodeId, direction, predicates: [...new Set(predicates)].sort(),
+        maxFacts: Number(maxFacts), ...(continuation === undefined ? {} : { continuation }) };
+}

package/dist/graph/neighborhood.d.ts

@@ -0,0 +1,8 @@
+import type { GraphExplorationService, GraphNeighborhood, GraphNeighborsRequest, SnapshotStore } from '@weftlet/core';
+export declare const GRAPH_NEIGHBORHOOD_VERSION = "exact-neighborhood-v1";
+/** One-hop, exact-ID exploration over the same lossless RDF projection as impact.scan. */
+export declare class SnapshotGraphExplorationService implements GraphExplorationService {
+    private readonly store;
+    constructor(store: Pick<SnapshotStore, 'read'>);
+    neighbors(input: GraphNeighborsRequest): Promise<GraphNeighborhood>;
+}

package/dist/graph/neighborhood.js

@@ -0,0 +1,100 @@
+import { snapshotContext } from './snapshot-context.js';
+import { sha256, stableJson } from '../infrastructure/util.js';
+import { RdfEvidenceGraph } from './rdf.js';
+import { coverageForFacts } from './coverage.js';
+import { parseGraphNeighborsRequest } from './neighborhood-request.js';
+import { renderGraphNeighborhood } from './neighborhood-renderer.js';
+import { selectDiagnostics } from './diagnostics.js';
+export const GRAPH_NEIGHBORHOOD_VERSION = 'exact-neighborhood-v1';
+function pageOffset(token, binding, length, pageSize) {
+    if (token === undefined)
+        return 0;
+    let value;
+    try {
+        if (!/^[A-Za-z0-9_-]+$/.test(token))
+            throw new Error();
+        value = JSON.parse(Buffer.from(token, 'base64url').toString('utf8'));
+        if (!value || typeof value !== 'object' || Array.isArray(value) ||
+            Object.keys(value).sort().join(',') !== 'binding,offset,version')
+            throw new Error();
+    }
+    catch {
+        throw new Error('Invalid graph.neighbors continuation');
+    }
+    if (value.version !== GRAPH_NEIGHBORHOOD_VERSION || value.binding !== binding) {
+        throw new Error('Continuation does not match this snapshot, node, filters or page size; restart graph.neighbors');
+    }
+    if (!Number.isSafeInteger(value.offset) || Number(value.offset) < 1 || Number(value.offset) >= length ||
+        Number(value.offset) % pageSize !== 0)
+        throw new Error('Invalid graph.neighbors continuation offset');
+    return Number(value.offset);
+}
+function opposite(fact, nodeId) {
+    return fact.subject.id === nodeId ? fact.object.id : fact.subject.id;
+}
+/** One-hop, exact-ID exploration over the same lossless RDF projection as impact.scan. */
+export class SnapshotGraphExplorationService {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    async neighbors(input) {
+        const request = parseGraphNeighborsRequest(input);
+        const saved = await this.store.read(request.snapshotId);
+        if (!saved)
+            throw new Error('No graph snapshot is available for that identifier');
+        if (saved.manifest.snapshotId !== request.snapshotId)
+            throw new Error('Saved snapshot identity does not match the requested identifier');
+        const all = await new RdfEvidenceGraph(saved).facts();
+        const adjacency = new Map();
+        const factIds = new Set();
+        for (const fact of all) {
+            if (factIds.has(fact.id))
+                throw new Error('Duplicate fact identities prevent stable graph.neighbors pagination');
+            factIds.add(fact.id);
+            for (const nodeId of new Set([fact.subject.id, fact.object.id])) {
+                const adjacent = adjacency.get(nodeId) ?? [];
+                adjacent.push(fact);
+                adjacency.set(nodeId, adjacent);
+            }
+        }
+        const incident = adjacency.get(request.nodeId) ?? [];
+        const selected = incident.filter(fact => (request.direction === 'both' || (request.direction === 'outgoing' ? fact.subject.id : fact.object.id) === request.nodeId) &&
+            (!request.predicates.length || request.predicates.includes(fact.predicate)))
+            .sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+        const { continuation: _continuation, ...query } = request;
+        // Bind to actual projected facts too: even a corrupt store reusing a manifest digest
+        // must not silently turn a saved continuation into a different neighborhood/frontier.
+        const binding = sha256(stableJson({ version: GRAPH_NEIGHBORHOOD_VERSION, query, manifest: saved.manifest,
+            facts: all, diagnostics: saved.diagnostics, unresolved: saved.unresolved }));
+        const offset = pageOffset(request.continuation, binding, selected.length, request.maxFacts);
+        const facts = selected.slice(offset, offset + request.maxFacts);
+        const end = offset + facts.length;
+        const next = end < selected.length ? Buffer.from(JSON.stringify({
+            version: GRAPH_NEIGHBORHOOD_VERSION, binding, offset: end,
+        })).toString('base64url') : undefined;
+        const neighborIds = (items) => new Set(items.map(fact => opposite(fact, request.nodeId))
+            .filter(id => id !== request.nodeId));
+        const totalNeighbors = neighborIds(selected).size;
+        const neighbors = [...neighborIds(facts)].sort().map(nodeId => ({
+            nodeId,
+            factIds: facts.filter(fact => opposite(fact, request.nodeId) === nodeId).map(fact => fact.id),
+            otherIncidentFacts: adjacency.get(nodeId).filter(fact => fact.subject.id !== request.nodeId && fact.object.id !== request.nodeId).length,
+        }));
+        const manifest = saved.manifest;
+        const plain = {
+            snapshot: snapshotContext(manifest),
+            focus: { nodeId: request.nodeId, status: incident.length ? 'present' : 'absent-from-snapshot' },
+            facts,
+            coverage: coverageForFacts(facts, saved),
+            diagnostics: selectDiagnostics(saved, {}, facts, [], [], new Set([request.nodeId, ...facts.flatMap(fact => [fact.subject.id, fact.object.id])])),
+            selection: { version: GRAPH_NEIGHBORHOOD_VERSION, direction: request.direction, predicates: request.predicates,
+                maxFacts: request.maxFacts, incidentFacts: incident.length, matchingFacts: selected.length,
+                filteredFacts: incident.length - selected.length, offset, returnedFacts: facts.length,
+                remainingFacts: selected.length - end, truncated: Boolean(next), ...(next ? { continuation: next } : {}) },
+            frontier: { scope: 'selected-one-hop-neighborhood', totalNeighbors,
+                remainingNeighbors: totalNeighbors - neighborIds(selected.slice(0, end)).size, neighbors },
+        };
+        return { ...plain, markdown: renderGraphNeighborhood(plain) };
+    }
+}

package/dist/graph/obligation-rdf.d.ts

@@ -0,0 +1,5 @@
+import { type Store, type NamedNode } from 'n3';
+import { type GraphFact } from '@weftlet/core';
+export declare function addObligationEvidence(dataset: Store, record: NamedNode, fact: GraphFact): void;
+/** Structural integrity only: declarations cannot prove fulfillment, compatibility or runtime delivery. */
+export declare function obligationEvidenceIssues(fact: GraphFact, repositoryId: string): readonly string[];

package/dist/graph/obligation-rdf.js

@@ -0,0 +1,67 @@
+import { DataFactory } from 'n3';
+import { obligationContractNode, parseObligationDeclaration, repositoryFileNode } from '@weftlet/core';
+import { CG, RDF, XSD } from './shacl-shapes.js';
+const { namedNode: iri, literal } = DataFactory;
+export function addObligationEvidence(dataset, record, fact) {
+    const evidence = fact.contractObligation;
+    if (!evidence && fact.extractor.id !== 'document-obligation-extractor')
+        return;
+    dataset.addQuad(record, iri(RDF + 'type'), iri(CG + 'ContractObligation'));
+    if (!evidence)
+        return;
+    const prop = (node, key, value, datatype = 'string') => {
+        if (value !== undefined)
+            dataset.addQuad(node, iri(CG + key), literal(String(value), iri(XSD + datatype)));
+    };
+    const item = evidence.declaration ?? {};
+    const contract = item.contract, constraint = item.constraint;
+    prop(record, 'obligationVersion', item.schemaVersion, 'integer');
+    for (const [key, value] of Object.entries({ obligationMethod: evidence.method, obligationRepository: evidence.repositoryId,
+        obligationId: item.id, obligationRole: item.role, obligationStatement: item.statement,
+        obligationScope: contract?.scope, obligationContract: contract?.id, obligationTransport: contract?.kind,
+        obligationContractVersion: contract?.version, obligationDomain: item.domain, obligationStage: item.stage,
+        obligationRevalidation: item.revalidation, obligationMetric: constraint?.metric,
+        obligationOperator: constraint?.operator, obligationUnit: constraint?.unit }))
+        prop(record, key, value);
+    prop(record, 'obligationValue', constraint?.value, 'double');
+    if (evidence.endpointSource) {
+        const endpoint = iri(`${record.value}:obligation-endpoint`);
+        dataset.addQuad(record, iri(CG + 'obligationEndpoint'), endpoint);
+        dataset.addQuad(endpoint, iri(RDF + 'type'), iri(CG + 'ObligationEndpoint'));
+        for (const [key, value] of Object.entries(evidence.endpointSource))
+            prop(endpoint, key, value, typeof value === 'number' ? 'integer' : 'string');
+    }
+}
+function identityMatches(fact, declaration, repositoryId) {
+    const expected = repositoryFileNode(declaration.endpoint);
+    return fact.contractObligation.repositoryId === repositoryId &&
+        fact.object.id === obligationContractNode(repositoryId, declaration.contract).id && fact.object.kind === 'Contract' &&
+        fact.subject.id === expected.id && fact.subject.kind === expected.kind &&
+        fact.predicate === (declaration.role === 'guarantee' ? 'emits' : 'consumes');
+}
+/** Structural integrity only: declarations cannot prove fulfillment, compatibility or runtime delivery. */
+export function obligationEvidenceIssues(fact, repositoryId) {
+    const evidence = fact.contractObligation;
+    if (!evidence)
+        return fact.extractor.id === 'document-obligation-extractor' ? ['Obligation extraction requires declaration metadata'] : [];
+    let declaration;
+    try {
+        declaration = parseObligationDeclaration(evidence.declaration);
+    }
+    catch {
+        return ['Malformed obligation declaration'];
+    }
+    const issues = [], endpoint = evidence.endpointSource;
+    if (!identityMatches(fact, declaration, repositoryId))
+        issues.push('Obligation role or scoped contract/endpoint identity does not match its declaration');
+    if (!endpoint || endpoint.path !== declaration.endpoint || endpoint.commitSha !== fact.provenance.commitSha ||
+        endpoint.endLine < endpoint.startLine)
+        issues.push('Obligation endpoint citation does not match its declared file/revision');
+    if (fact.codeBinding || fact.codeCall || fact.codeOccurrence)
+        issues.push('Obligation declarations must remain separate from implementation evidence');
+    if (fact.sourceRole === 'validation')
+        issues.push('Validation evidence cannot declare product obligations');
+    if (fact.authority === 'draft' && fact.sourceAuthority !== 'draft')
+        issues.push('Draft obligations require draft source authority');
+    return issues;
+}