@weftlet/toolkit 0.6.1 → 0.7.1

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 { stableJsonDigest } 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 = stableJsonDigest({ 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;
+}

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

@@ -0,0 +1,2 @@
+/** Shapes target only obligation records, keeping ordinary-fact validation cost unchanged. */
+export declare const obligationShapes = "\ncg:ContractObligationShape a sh:NodeShape; sh:targetClass cg:ContractObligation;\n sh:property [ sh:path cg:obligationVersion; sh:minCount 1; sh:maxCount 1; sh:hasValue 1 ];\n sh:property [ sh:path cg:obligationMethod; sh:minCount 1; sh:maxCount 1; sh:hasValue \"explicit-markdown\" ];\n sh:property [ sh:path cg:obligationRole; sh:minCount 1; sh:maxCount 1; sh:in (\"guarantee\" \"requirement\") ];\n sh:property [ sh:path cg:obligationId; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];\n sh:property [ sh:path cg:obligationStatement; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];\n sh:property [ sh:path cg:obligationRepository; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];\n sh:property [ sh:path cg:obligationScope; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];\n sh:property [ sh:path cg:obligationContract; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];\n sh:property [ sh:path cg:obligationTransport; sh:minCount 1; sh:maxCount 1; sh:in (\"queue\" \"stored-data\") ];\n sh:property [ sh:path cg:obligationContractVersion; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];\n sh:property [ sh:path cg:obligationDomain; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];\n sh:property [ sh:path cg:obligationStage; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];\n sh:property [ sh:path cg:obligationRevalidation; sh:maxCount 1; sh:in (\"required\" \"not-required\") ];\n sh:property [ sh:path cg:obligationEndpoint; sh:minCount 1; sh:maxCount 1; sh:class cg:ObligationEndpoint ];\n sh:property [ sh:path cg:authority; sh:in (\"inferred\" \"draft\") ];\n sh:property [ sh:path cg:extractionReview; sh:minCount 1; sh:hasValue \"deterministic\" ];\n sh:property [ sh:path rdf:predicate; sh:in (cg:emits cg:consumes) ].\ncg:ObligationEndpointShape a sh:NodeShape; sh:targetClass cg:ObligationEndpoint;\n sh:property [ sh:path cg:path; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];\n sh:property [ sh:path cg:digest; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];\n sh:property [ sh:path cg:commitSha; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];\n sh:property [ sh:path cg:startLine; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:integer; sh:minInclusive 1 ];\n sh:property [ sh:path cg:endLine; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:integer; sh:minInclusive 1 ].\ncg:ObligationConstraintShape a sh:NodeShape; sh:targetSubjectsOf cg:obligationMetric, cg:obligationOperator, cg:obligationValue, cg:obligationUnit;\n sh:property [ sh:path cg:obligationMetric; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];\n sh:property [ sh:path cg:obligationOperator; sh:minCount 1; sh:maxCount 1; sh:in (\"at-most\" \"at-least\" \"equal\") ];\n sh:property [ sh:path cg:obligationValue; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:double ];\n sh:property [ sh:path cg:obligationUnit; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ].\n";

package/dist/graph/obligation-shapes.js

@@ -0,0 +1,32 @@
+/** Shapes target only obligation records, keeping ordinary-fact validation cost unchanged. */
+export const obligationShapes = `
+cg:ContractObligationShape a sh:NodeShape; sh:targetClass cg:ContractObligation;
+ sh:property [ sh:path cg:obligationVersion; sh:minCount 1; sh:maxCount 1; sh:hasValue 1 ];
+ sh:property [ sh:path cg:obligationMethod; sh:minCount 1; sh:maxCount 1; sh:hasValue "explicit-markdown" ];
+ sh:property [ sh:path cg:obligationRole; sh:minCount 1; sh:maxCount 1; sh:in ("guarantee" "requirement") ];
+ sh:property [ sh:path cg:obligationId; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:obligationStatement; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:obligationRepository; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:obligationScope; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:obligationContract; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:obligationTransport; sh:minCount 1; sh:maxCount 1; sh:in ("queue" "stored-data") ];
+ sh:property [ sh:path cg:obligationContractVersion; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:obligationDomain; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:obligationStage; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:obligationRevalidation; sh:maxCount 1; sh:in ("required" "not-required") ];
+ sh:property [ sh:path cg:obligationEndpoint; sh:minCount 1; sh:maxCount 1; sh:class cg:ObligationEndpoint ];
+ sh:property [ sh:path cg:authority; sh:in ("inferred" "draft") ];
+ sh:property [ sh:path cg:extractionReview; sh:minCount 1; sh:hasValue "deterministic" ];
+ sh:property [ sh:path rdf:predicate; sh:in (cg:emits cg:consumes) ].
+cg:ObligationEndpointShape a sh:NodeShape; sh:targetClass cg:ObligationEndpoint;
+ sh:property [ sh:path cg:path; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:digest; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:commitSha; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:startLine; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:integer; sh:minInclusive 1 ];
+ sh:property [ sh:path cg:endLine; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:integer; sh:minInclusive 1 ].
+cg:ObligationConstraintShape a sh:NodeShape; sh:targetSubjectsOf cg:obligationMetric, cg:obligationOperator, cg:obligationValue, cg:obligationUnit;
+ sh:property [ sh:path cg:obligationMetric; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:obligationOperator; sh:minCount 1; sh:maxCount 1; sh:in ("at-most" "at-least" "equal") ];
+ sh:property [ sh:path cg:obligationValue; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:double ];
+ sh:property [ sh:path cg:obligationUnit; sh:maxCount 1; sh:datatype xsd:string; sh:minLength 1 ].
+`;

package/dist/graph/partitioned-shacl.d.ts

@@ -0,0 +1,14 @@
+import { type Quad } from 'n3';
+import type { RdfPartitions } from './rdf-partitions.js';
+export declare function assertPartitionLocalShapes(shapes: readonly Quad[]): void;
+export interface ShaclIssue {
+    category: 'extraction-gap';
+    focus?: string;
+    path?: string;
+    message: string;
+}
+/** Run the same strict validator/shapes on complete subjects with global class membership. */
+export declare function validatePartitions(partitions: RdfPartitions, types: ReadonlyMap<string, ReadonlySet<string>>, progress?: (completed: number) => void): Promise<{
+    conforms: boolean;
+    issues: ShaclIssue[];
+}>;

package/dist/graph/partitioned-shacl.js

@@ -0,0 +1,66 @@
+import { DataFactory, Store } from 'n3';
+import SHACLValidator from 'rdf-validate-shacl';
+import { RDF, evidenceShapes } from './shacl-shapes.js';
+const SH = 'http://www.w3.org/ns/shacl#', { namedNode: iri } = DataFactory;
+const targets = new Set([SH + 'targetClass', SH + 'targetSubjectsOf']);
+// All admitted constraints inspect the focus subject's outgoing triples. sh:class
+// additionally reads rdf:type on referenced objects, supplied from the entire graph.
+const allowed = new Set(['targetClass', 'targetSubjectsOf', 'property', 'path', 'minCount', 'maxCount',
+    'datatype', 'minLength', 'minInclusive', 'maxInclusive', 'hasValue', 'in', 'or', 'nodeKind', 'class']);
+export function assertPartitionLocalShapes(shapes) {
+    const propertyShapes = new Set(shapes.filter(quad => quad.predicate.value === SH + 'path')
+        .map(quad => quad.subject.value));
+    for (const quad of shapes) {
+        if (quad.predicate.value.startsWith(SH) && !allowed.has(quad.predicate.value.slice(SH.length))) {
+            throw Error(`SHACL partition locality must be reviewed for ${quad.predicate.value}`);
+        }
+        if (quad.predicate.value === SH + 'path' && quad.object.termType !== 'NamedNode') {
+            throw Error('SHACL partition locality requires direct predicate paths');
+        }
+        if (propertyShapes.has(quad.subject.value) && [SH + 'property', SH + 'or'].includes(quad.predicate.value)) {
+            throw Error('SHACL partition locality forbids nested value-shape traversal');
+        }
+        if (quad.predicate.value === RDF + 'type' && ![SH + 'NodeShape', SH + 'PropertyShape'].includes(quad.object.value)) {
+            throw Error('SHACL partition locality requires explicit reviewed targets');
+        }
+        if (!quad.predicate.value.startsWith(SH) && ![RDF + 'type', RDF + 'first', RDF + 'rest'].includes(quad.predicate.value)) {
+            throw Error(`Unsupported SHACL partition vocabulary: ${quad.predicate.value}`);
+        }
+    }
+}
+/** Run the same strict validator/shapes on complete subjects with global class membership. */
+export async function validatePartitions(partitions, types, progress) {
+    assertPartitionLocalShapes(evidenceShapes);
+    const targetRules = evidenceShapes.filter(quad => targets.has(quad.predicate.value));
+    const constraints = evidenceShapes.filter(quad => !targets.has(quad.predicate.value));
+    const issues = [];
+    let conforms = true, completed = 0;
+    for (const batch of partitions.validation()) {
+        // Select targets before adding support-only class triples; those objects are
+        // validated with their complete outgoing records in their own partition.
+        const shapes = new Store(constraints);
+        for (const target of targetRules) {
+            const selected = target.predicate.value === SH + 'targetClass'
+                ? batch.getQuads(null, iri(RDF + 'type'), target.object, null)
+                : batch.getQuads(null, target.object, null, null);
+            for (const quad of selected)
+                shapes.addQuad(target.subject, iri(SH + 'targetNode'), quad.subject);
+        }
+        const referenced = new Set();
+        for (const quad of batch)
+            if (quad.object.termType === 'NamedNode')
+                referenced.add(quad.object.value);
+        for (const node of referenced)
+            for (const type of types.get(node) ?? [])
+                batch.addQuad(iri(node), iri(RDF + 'type'), iri(type));
+        const report = await new SHACLValidator(shapes).validate(batch);
+        conforms &&= report.conforms;
+        for (const result of report.results)
+            issues.push({ category: 'extraction-gap', focus: result.focusNode?.value,
+                path: result.path?.value, message: result.message.map(message => message.value).join('; ') });
+        progress?.(++completed);
+        // Allow progress, cancellation observers and GC between bounded batches.
+        await new Promise(resolve => setImmediate(resolve));
+    }
+    return { conforms, issues };
+}

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

@@ -0,0 +1,11 @@
+export declare function parseGraphPathsRequest(value: unknown): {
+    continuation?: string | undefined;
+    snapshotId: string;
+    fromNodeId: string;
+    toNodeId: string;
+    direction: "incoming" | "outgoing" | "both";
+    predicates: ("references" | "realizes" | "implementedBy" | "consumes" | "emits" | "persistsTo" | "governedBy" | "definedBy" | "verifiedBy" | "operationallyOwnedBy" | "decisionAuthority" | "routesThrough" | "authorizedBy" | "sourcedFrom" | "contains" | "calls")[];
+    maxDepth: number;
+    maxPaths: number;
+    maxSteps: number;
+};