@weftlet/toolkit 0.6.1 → 0.7.1

package/dist/graph/path-request.js

@@ -0,0 +1,24 @@
+import { parseGraphNeighborsRequest } from './neighborhood-request.js';
+const fields = new Set(['snapshotId', 'fromNodeId', 'toNodeId', 'direction', 'predicates', 'maxDepth', 'maxPaths', 'maxSteps', 'continuation']);
+export function parseGraphPathsRequest(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('graph.paths arguments must be an object');
+    const record = value;
+    if (Object.keys(record).some(key => !fields.has(key)))
+        throw new Error('Unknown graph.paths field');
+    const common = { snapshotId: record.snapshotId, direction: record.direction === undefined ? 'outgoing' : record.direction,
+        predicates: record.predicates, continuation: record.continuation };
+    const from = parseGraphNeighborsRequest({ ...common, nodeId: record.fromNodeId });
+    const to = parseGraphNeighborsRequest({ ...common, nodeId: record.toNodeId });
+    const bound = (name, fallback, maximum) => {
+        const item = record[name] === undefined ? fallback : record[name];
+        if (!Number.isInteger(item) || Number(item) < 1 || Number(item) > maximum) {
+            throw new Error(`${name} must be an integer between 1 and ${maximum}`);
+        }
+        return Number(item);
+    };
+    return { snapshotId: from.snapshotId, fromNodeId: from.nodeId, toNodeId: to.nodeId,
+        direction: from.direction, predicates: from.predicates, maxDepth: bound('maxDepth', 8, 32),
+        maxPaths: bound('maxPaths', 5, 20), maxSteps: bound('maxSteps', 1000, 10_000),
+        ...(from.continuation ? { continuation: from.continuation } : {}) };
+}

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

@@ -0,0 +1,45 @@
+import type { EvidencePath } from '@weftlet/core';
+export interface PathEdge {
+    readonly id: string;
+    readonly from: string;
+    readonly to: string;
+}
+export interface PathSearchOptions {
+    readonly maxDepth: number;
+    readonly maxPaths: number;
+    readonly maxSteps: number;
+    readonly offset?: number;
+}
+/** Pure, dependency-free search shared verbatim with the offline viewer. No global visited set:
+ * distinct simple paths and parallel assertions survive; cycles do not repeat a node. */
+export declare function searchEvidencePaths(edges: readonly PathEdge[], start: string, target: string, options: PathSearchOptions, knownNodeIds?: ReadonlySet<string>): {
+    paths: EvidencePath[];
+    frontier: {
+        pending: {
+            nodeId: string;
+            viaFactIds: string[];
+            nextFactId: string;
+            remainingCandidates: number;
+        }[];
+        depthLimited: {
+            count: number;
+            examples: {
+                readonly nodeId: string;
+                readonly viaFactIds: readonly string[];
+                readonly nextFactId: string;
+                readonly nextNodeId: string;
+            }[];
+            omitted: number;
+        };
+    };
+    search: {
+        searchLimit: number;
+        replayedSteps: number;
+        examinedSteps: number;
+        totalSteps: number;
+        stopReason: "exhausted" | "search-limit" | "path-page-limit" | "work-page-limit";
+        exhaustedWithinDepth: boolean;
+        depthLimitReached: boolean;
+        truncated: boolean;
+    };
+};

package/dist/graph/path-search.js

@@ -0,0 +1,101 @@
+/** Pure, dependency-free search shared verbatim with the offline viewer. No global visited set:
+ * distinct simple paths and parallel assertions survive; cycles do not repeat a node. */
+export function searchEvidencePaths(edges, start, target, options, knownNodeIds) {
+    const searchLimit = 100_000;
+    const offset = options.offset ?? 0;
+    const validateBounds = () => {
+        for (const [value, maximum] of [[options.maxDepth, 32], [options.maxPaths, 20], [options.maxSteps, 10_000]]) {
+            if (!Number.isInteger(value) || value < 1 || value > maximum)
+                throw new Error('Invalid path search bound');
+        }
+        if (!Number.isInteger(offset) || offset < 0 || offset >= searchLimit)
+            throw new Error('Invalid path continuation offset');
+    };
+    validateBounds();
+    const adjacency = new Map();
+    const nodeIds = new Set();
+    for (const edge of [...edges].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0)) {
+        const entries = adjacency.get(edge.from) ?? [];
+        entries.push(edge);
+        adjacency.set(edge.from, entries);
+        nodeIds.add(edge.from);
+        nodeIds.add(edge.to);
+    }
+    const paths = [];
+    const stack = nodeIds.has(start) && nodeIds.has(target) && start !== target ? [{ nodeId: start, next: 0 }] : [];
+    const depthExamples = [];
+    let depthCount = 0;
+    let totalSteps = 0;
+    const trim = () => {
+        while (stack.length && stack.at(-1).next >= (adjacency.get(stack.at(-1).nodeId)?.length ?? 0))
+            stack.pop();
+    };
+    const step = () => {
+        const frame = stack.at(-1);
+        const edge = adjacency.get(frame.nodeId)[frame.next++];
+        totalSteps++;
+        if (stack.some(item => item.nodeId === edge.to))
+            return;
+        const viaFactIds = stack.slice(1).map(item => item.via);
+        if (viaFactIds.length === options.maxDepth) {
+            depthCount++;
+            if (depthExamples.length < 20)
+                depthExamples.push({ nodeId: frame.nodeId, viaFactIds,
+                    nextFactId: edge.id, nextNodeId: edge.to });
+        }
+        else if (edge.to === target) {
+            return { nodeIds: [...stack.map(item => item.nodeId), target], factIds: [...viaFactIds, edge.id] };
+        }
+        else {
+            stack.push({ nodeId: edge.to, next: 0, via: edge.id });
+        }
+    };
+    trim();
+    // Reconstruct only bounded search state. Never accept a caller-supplied stack or facts.
+    const replay = () => {
+        let replayPageSteps = 0;
+        let replayPagePaths = 0;
+        while (totalSteps < offset && stack.length) {
+            if (step())
+                replayPagePaths++;
+            replayPageSteps++;
+            if (replayPagePaths === options.maxPaths || replayPageSteps === options.maxSteps) {
+                replayPagePaths = 0;
+                replayPageSteps = 0;
+            }
+            trim();
+        }
+        if (totalSteps !== offset || (offset && (!stack.length || replayPagePaths || replayPageSteps))) {
+            throw new Error('Invalid path continuation boundary');
+        }
+    };
+    replay();
+    if (!offset && start === target && (nodeIds.has(start) || knownNodeIds?.has(start)))
+        paths.push({ nodeIds: [start], factIds: [] });
+    while (stack.length && paths.length < options.maxPaths && totalSteps - offset < options.maxSteps && totalSteps < searchLimit) {
+        const path = step();
+        if (path)
+            paths.push(path);
+        trim();
+    }
+    const pending = stack.flatMap((frame, index) => {
+        const entries = adjacency.get(frame.nodeId) ?? [];
+        return frame.next < entries.length ? [{ nodeId: frame.nodeId,
+                viaFactIds: stack.slice(1, index + 1).map(item => item.via), nextFactId: entries[frame.next].id,
+                remainingCandidates: entries.length - frame.next }] : [];
+    });
+    const exhaustedWithinDepth = stack.length === 0;
+    const stopReason = () => {
+        if (exhaustedWithinDepth)
+            return 'exhausted';
+        if (totalSteps === searchLimit)
+            return 'search-limit';
+        if (paths.length === options.maxPaths)
+            return 'path-page-limit';
+        return 'work-page-limit';
+    };
+    return { paths, frontier: { pending, depthLimited: { count: depthCount, examples: depthExamples,
+                omitted: depthCount - depthExamples.length } }, search: { searchLimit, replayedSteps: offset,
+            examinedSteps: totalSteps - offset, totalSteps, stopReason: stopReason(), exhaustedWithinDepth,
+            depthLimitReached: depthCount > 0, truncated: !exhaustedWithinDepth || depthCount > 0 } };
+}

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

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

package/dist/graph/paths-renderer.js

@@ -0,0 +1,36 @@
+import { factEvidenceDescription } from './evidence-description.js';
+import { sourceLocation } from '@weftlet/core';
+import { contextPackEvidenceAuthority } from './authority.js';
+import { coverageDescription } from './coverage.js';
+import { diagnosticSummary } from './diagnostics.js';
+import { documentSelectionDescription } from './document-role-description.js';
+const quoted = (value) => JSON.stringify(value).replace(/[\\`*_{}\[\]()<>!|]/g, '\\$&');
+export function renderGraphPaths(result) {
+    const { snapshot, endpoints, search, frontier, evidenceState } = result;
+    return [
+        '# Cited evidence paths',
+        `Snapshot: ${quoted(snapshot.snapshotId)} (${snapshot.commitSha}); configuration: ${snapshot.configurationDigest ?? 'unknown'}`,
+        `Scope: ${snapshot.scope?.map(quoted).join(', ') ?? 'unknown'}`,
+        documentSelectionDescription(snapshot.documentSelection),
+        `From ${quoted(endpoints.from.nodeId)} (${endpoints.from.status}) to ${quoted(endpoints.to.nodeId)} (${endpoints.to.status})`,
+        `Direction: ${search.direction}; predicates: ${search.predicates.join(', ') || 'all'}; order: ${search.order}`,
+        `Depth: ${search.maxDepth}; paths on page: ${result.paths.length}/${search.maxPaths}; stop: ${search.stopReason}; truncated: ${search.truncated}`,
+        `Candidate steps: ${search.examinedSteps} new + ${search.replayedSteps} replay; ${search.totalSteps}/${search.searchLimit} total ceiling.`,
+        `Unexamined prefixes: ${frontier.pending.length}; depth-limited extensions: ${frontier.depthLimited.count} (${frontier.depthLimited.omitted} examples omitted).`,
+        ...(search.continuation ? [`Continuation (same request): ${search.continuation}`] : []),
+        ...(search.depthLimitReached ? ['Depth limit reached: restart with a larger maxDepth or explore a frontier node. Continuation does not lift the depth bound.'] : []),
+        ...(search.stopReason === 'search-limit' ? ['Total search limit reached: narrow the relations or explore an intermediate node; no further continuation is available.'] : []),
+        ...(evidenceState ? [`Stale: ${evidenceState.stale}; configuration matches: ${evidenceState.configurationMatches}; extraction compatible: ${evidenceState.extractionCompatible ?? 'unknown'}; overlay freshness: ${evidenceState.overlayFreshness ?? 'not an overlay'}`,
+            `Excluded working changes: ${evidenceState.excludedWorkingChanges.map(quoted).join(', ') || '(none)'}`] : []),
+        'Paths are cited associations, not proof of causality, business compatibility or current-diff validation. A completed search covers only the selected saved facts and depth; absence is not proof of no product dependency.',
+        coverageDescription(result.coverage), ...result.coverage.gaps.map(quoted),
+        '', '## Paths',
+        ...result.paths.map((path, index) => `${index + 1}. ${path.nodeIds.map(quoted).join(' → ')}; facts: ${path.factIds.map(quoted).join(', ') || '(zero-length identity path)'}`),
+        '', '## Supporting assertions',
+        ...result.facts.map(fact => `- ${quoted(fact.id)} [${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)}` : ''})`),
+        '', '## Unexplored frontier',
+        ...frontier.pending.map(item => `- ${quoted(item.nodeId)} via ${item.viaFactIds.map(quoted).join(', ') || '(start)'}: ${item.remainingCandidates} candidates; next ${quoted(item.nextFactId)}`),
+        ...frontier.depthLimited.examples.map(item => `- Depth boundary: ${quoted(item.nodeId)} → ${quoted(item.nextNodeId)} via ${quoted(item.nextFactId)}`),
+        '', '## Scoped diagnostics', ...diagnosticSummary(result).map(quoted),
+    ].filter(line => line !== undefined).join('\n');
+}

package/dist/graph/paths.d.ts

@@ -0,0 +1,7 @@
+import type { GraphPathQueryService, GraphPaths, GraphPathsRequest, SnapshotStore } from '@weftlet/core';
+export declare const GRAPH_PATHS_VERSION = "simple-evidence-paths-v1";
+export declare class SnapshotGraphPathService implements GraphPathQueryService {
+    private readonly store;
+    constructor(store: Pick<SnapshotStore, 'read'>);
+    paths(input: GraphPathsRequest): Promise<GraphPaths>;
+}

package/dist/graph/paths.js

@@ -0,0 +1,74 @@
+import { snapshotContext } from './snapshot-context.js';
+import { stableJsonDigest } from '../infrastructure/util.js';
+import { RdfEvidenceGraph } from './rdf.js';
+import { coverageForFacts } from './coverage.js';
+import { selectDiagnostics } from './diagnostics.js';
+import { parseGraphPathsRequest } from './path-request.js';
+import { searchEvidencePaths } from './path-search.js';
+import { renderGraphPaths } from './paths-renderer.js';
+export const GRAPH_PATHS_VERSION = 'simple-evidence-paths-v1';
+function continuationOffset(token, binding) {
+    if (!token)
+        return 0;
+    try {
+        if (!/^[A-Za-z0-9_-]+$/.test(token))
+            throw new Error();
+        const 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' ||
+            value.version !== GRAPH_PATHS_VERSION || value.binding !== binding ||
+            !Number.isInteger(value.offset) || value.offset < 1 || value.offset >= 100_000)
+            throw new Error();
+        return value.offset;
+    }
+    catch {
+        throw new Error('Invalid graph.paths continuation or query/snapshot mismatch; restart graph.paths');
+    }
+}
+export class SnapshotGraphPathService {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    async paths(input) {
+        const request = parseGraphPathsRequest(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();
+        if (new Set(all.map(fact => fact.id)).size !== all.length)
+            throw new Error('Duplicate fact identities prevent stable graph.paths pagination');
+        const { continuation, ...query } = request;
+        const binding = stableJsonDigest({ version: GRAPH_PATHS_VERSION, query, manifest: saved.manifest,
+            facts: all, diagnostics: saved.diagnostics, unresolved: saved.unresolved });
+        const offset = continuationOffset(continuation, binding);
+        const selected = all.filter(fact => !request.predicates.length || request.predicates.includes(fact.predicate));
+        const edges = selected.flatMap(fact => {
+            const forward = { id: fact.id, from: fact.subject.id, to: fact.object.id };
+            const reverse = { id: fact.id, from: fact.object.id, to: fact.subject.id };
+            return request.direction === 'incoming' ? [reverse] : request.direction === 'outgoing' || forward.from === forward.to
+                ? [forward] : [forward, reverse];
+        });
+        const nodes = new Set(all.flatMap(fact => [fact.subject.id, fact.object.id]));
+        const result = searchEvidencePaths(edges, request.fromNodeId, request.toNodeId, { ...request, offset }, nodes);
+        const factIds = new Set(result.paths.flatMap(path => path.factIds));
+        const facts = all.filter(fact => factIds.has(fact.id));
+        const endpoint = (nodeId) => ({ nodeId, status: nodes.has(nodeId) ? 'present' : 'absent-from-snapshot' });
+        const next = !result.search.exhaustedWithinDepth && result.search.stopReason !== 'search-limit'
+            ? Buffer.from(JSON.stringify({ version: GRAPH_PATHS_VERSION, binding, offset: result.search.totalSteps })).toString('base64url') : undefined;
+        const manifest = saved.manifest;
+        const plain = {
+            snapshot: snapshotContext(manifest),
+            endpoints: { from: endpoint(request.fromNodeId), to: endpoint(request.toNodeId) },
+            paths: result.paths, facts, coverage: coverageForFacts(facts, saved),
+            diagnostics: selectDiagnostics(saved, {}, facts, [], [], new Set([request.fromNodeId, request.toNodeId,
+                ...facts.flatMap(fact => [fact.subject.id, fact.object.id])])),
+            search: { version: GRAPH_PATHS_VERSION, order: 'fact-id-depth-first', direction: request.direction,
+                predicates: request.predicates, maxDepth: request.maxDepth, maxPaths: request.maxPaths, maxSteps: request.maxSteps,
+                ...result.search, ...(next ? { continuation: next } : {}) }, frontier: result.frontier,
+        };
+        return { ...plain, markdown: renderGraphPaths(plain) };
+    }
+}

package/dist/graph/query.js

@@ -1,4 +1,7 @@
 // Modified for standalone extraction; see docs/extraction-manifest.json.
+import { unexpandedCodeDescription } from './code-description.js';
+import { factEvidenceDescription } from './evidence-description.js';
+import { sourceLocation } from '@weftlet/core';
 import { contextPackEvidenceAuthority } from "./authority.js";
 import { RdfEvidenceGraph } from "./rdf.js";
 import { sha256, stableJson } from "../infrastructure/util.js";
@@ -61,7 +64,8 @@ function markdownFactDetails(fact) {
     const document = sourceDocumentDescription(fact)?.replace(/[\\`*_{}\[\]()<>!|]/g, '\\$&').replace(/[\r\n]/g, ' ');
     return `confidence ${fact.confidence}` +
         (fact.sourceAuthority ? `; source ${fact.sourceAuthority}; extraction ${fact.extractionReview ?? 'unknown'}` : '') +
-        (document ? `; ${document}` : '');
+        (document ? `; ${document}` : '') +
+        (factEvidenceDescription(fact) ? `; ${factEvidenceDescription(fact)}` : '');
 }
 export class MarkdownContextPackRenderer {
     render(pack) {
@@ -106,7 +110,7 @@ export class MarkdownContextPackRenderer {
                 ...pack.facts
                     .filter((fact) => contextPackLaneForFact(fact) === lane)
                     .map((fact) => `- [${contextPackEvidenceAuthority(fact)}] ${fact.subject.label} —${fact.predicate}→ ${fact.object.label} ` +
-                    `(\`${fact.provenance.path}:${fact.provenance.startLine}\`, ${markdownFactDetails(fact)})`),
+                    `(\`${sourceLocation(fact.provenance)}\`, ${markdownFactDetails(fact)})`),
             ]),
             '',
             '## Runtime evidence',
@@ -122,6 +126,7 @@ export class MarkdownContextPackRenderer {
             '## Suggested files',
             ...pack.suggestedFiles.map((path) => `- \`${path}\``),
             '',
+            ...unexpandedCodeDescription(pack.exploration),
             '## Scoped diagnostics',
             ...diagnosticSummary(pack).map((item) => `- ${item}`),
         ];
@@ -165,8 +170,16 @@ export class SnapshotImpactQueryService {
         const directTerms = anchorTerms.length > 0 ? anchorTerms : focus;
         const direct = snapshot.facts.filter((fact) => this.matches(fact, directTerms));
         const ranked = new Map(direct.map((fact) => [fact.id, fact]));
+        const unexpandedCodeTargets = new Set();
+        const expand = (node) => {
+            if (node.kind === 'CodeSymbol' && node.codeSymbol?.resolution === 'no-indexed-definition') {
+                unexpandedCodeTargets.add(node.id);
+                return false;
+            }
+            return node.kind !== 'Project';
+        };
         let frontier = new Set(direct.flatMap((fact) => [fact.subject, fact.object]
-            .filter((node) => node.kind !== 'Project')
+            .filter(expand)
             .map((node) => node.id)));
         const visitedNodes = new Set(frontier);
         for (let depth = 0; depth < maxDepth && frontier.size > 0; depth += 1) {
@@ -176,7 +189,7 @@ export class SnapshotImpactQueryService {
                     continue;
                 ranked.set(fact.id, fact);
                 for (const node of [fact.subject, fact.object]) {
-                    if (node.kind !== 'Project' && !visitedNodes.has(node.id))
+                    if (expand(node) && !visitedNodes.has(node.id))
                         next.add(node.id);
                 }
             }
@@ -196,7 +209,7 @@ export class SnapshotImpactQueryService {
             ...tier.filter((fact) => contextPackLaneForFact(fact) === undefined),
         ]);
         const { continuation: _continuation, snapshotId: _snapshotId, ...query } = request;
-        const queryDigest = sha256(stableJson({ ranking: IMPACT_RANKING_VERSION, query }));
+        const queryDigest = sha256(stableJson({ ranking: IMPACT_RANKING_VERSION, codeTraversal: 'indexed-symbols-v1', query }));
         let offset = 0;
         if (request.continuation) {
             if (request.continuation.length > 2048)
@@ -215,7 +228,7 @@ export class SnapshotImpactQueryService {
             offset = token.offset;
         }
         const facts = allBalanced.slice(offset, offset + maxFacts);
-        const coverage = coverageForFacts(facts);
+        const coverage = coverageForFacts(facts, snapshot);
         const nextOffset = offset + facts.length;
         const continuation = nextOffset < allBalanced.length ? Buffer.from(JSON.stringify({
             snapshot: snapshot.manifest.snapshotId, digest: snapshot.manifest.contentDigest,
@@ -306,6 +319,10 @@ export class SnapshotImpactQueryService {
             diagnostics: selectDiagnostics(snapshot, request, facts, focus, queryDiagnostics),
             exploration: {
                 rankingVersion: IMPACT_RANKING_VERSION,
+                codeTraversalVersion: 'indexed-symbols-v1',
+                unexpandedCodeTargets: [...unexpandedCodeTargets].sort().slice(0, 100),
+                unexpandedCodeTargetCount: unexpandedCodeTargets.size,
+                unexpandedCodeTargetsTruncated: unexpandedCodeTargets.size > 100,
                 returned: facts.length, reachableFacts: allBalanced.length, maxDepth,
                 depthLimitReached: frontier.size > 0, truncated: Boolean(continuation) || frontier.size > 0,
                 continuation,

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

@@ -0,0 +1,24 @@
+import { Store, type Term } from 'n3';
+import type { GraphSnapshot } from '@weftlet/core';
+type Quad = Parameters<Store['add']>[0];
+/** Complete subject groups: repeated identities are joined before validation, never split. */
+export declare class RdfPartitions {
+    private readonly snapshot;
+    private readonly batchSize;
+    private readonly records;
+    private readonly nodes;
+    constructor(snapshot: GraphSnapshot, batchSize?: number);
+    /** RDF/JS matching over the same records, without a second whole-graph quad store. */
+    match(subject?: Term | null, predicate?: Term | null, object?: Term | null, graph?: Term | null): IterableIterator<Quad>;
+    /** Exact cardinalities for the record projection; other patterns count the same iterator. */
+    countMatches(subject?: Term | null, predicate?: Term | null, object?: Term | null, graph?: Term | null): number;
+    /** Each union subject occurs in exactly one partition, with all its outgoing triples. */
+    validation(): IterableIterator<Store>;
+    /** Original named dataset, in bounded groups. Triple order is not a content identity. */
+    named(): IterableIterator<Store>;
+    private recordPartitions;
+    /** Only cross-subject information used by the admitted SHACL fragment is rdf:type. */
+    get count(): number;
+    types(progress?: (completed: number) => void): Map<string, Set<string>>;
+}
+export {};

package/dist/graph/rdf-partitions.js

@@ -0,0 +1,170 @@
+import { DataFactory, Store } from 'n3';
+import { stableJson } from '../infrastructure/util.js';
+import { addAttributes, addFactEdges, addFactRecord, addManifest, addNodeRdf, nodeIri } from './rdf-records.js';
+import { CG, RDF } from './shacl-shapes.js';
+const { namedNode: iri } = DataFactory;
+/** Complete subject groups: repeated identities are joined before validation, never split. */
+export class RdfPartitions {
+    snapshot;
+    batchSize;
+    records = new Map();
+    nodes = new Map();
+    constructor(snapshot, batchSize = 256) {
+        this.snapshot = snapshot;
+        this.batchSize = batchSize;
+        if (!Number.isSafeInteger(batchSize) || batchSize < 1)
+            throw Error('Invalid RDF partition size');
+        for (const [ordinal, fact] of snapshot.facts.entries()) {
+            const records = this.records.get(fact.id) ?? [];
+            records.push({ fact, ordinal });
+            this.records.set(fact.id, records);
+            for (const node of [fact.subject, fact.object]) {
+                const group = this.nodes.get(node.id) ?? { variants: new Map(), outgoing: [], attributes: [] };
+                group.variants.set(stableJson(node), node);
+                this.nodes.set(node.id, group);
+                if (Object.keys(node.attributes ?? {}).length)
+                    group.attributes.push({ node, factId: fact.id });
+            }
+            this.nodes.get(fact.subject.id).outgoing.push(fact);
+        }
+    }
+    /** RDF/JS matching over the same records, without a second whole-graph quad store. */
+    *match(subject, predicate, object, graph) {
+        const decode = (term, prefix, suffix = false) => {
+            if (term?.termType !== 'NamedNode' || !term.value.startsWith(prefix))
+                return undefined;
+            try {
+                return decodeURIComponent(suffix ? term.value.slice(prefix.length).split(':')[0] : term.value.slice(prefix.length));
+            }
+            catch {
+                return undefined;
+            }
+        };
+        const recordId = decode(subject, 'urn:context-graph:fact:', true);
+        const graphId = decode(graph, 'urn:context-graph:fact:');
+        const nodeId = decode(subject, 'urn:context-graph:node:');
+        let groups;
+        if (recordId !== undefined || graphId !== undefined) {
+            const batch = new Store();
+            for (const { fact, ordinal } of this.records.get(recordId ?? graphId) ?? []) {
+                addFactRecord(batch, fact, ordinal);
+                addFactEdges(batch, fact);
+            }
+            groups = [batch];
+        }
+        else if (nodeId !== undefined) {
+            const batch = new Store(), group = this.nodes.get(nodeId);
+            if (group) {
+                for (const node of group.variants.values())
+                    addNodeRdf(batch, node);
+                for (const fact of group.outgoing)
+                    addFactEdges(batch, fact);
+                for (const { node, factId } of group.attributes)
+                    addAttributes(batch, node, iri(`urn:context-graph:fact:${encodeURIComponent(factId)}`));
+            }
+            groups = [batch];
+        }
+        else if (subject?.value === 'urn:context-graph:snapshot') {
+            const batch = new Store();
+            addManifest(batch, this.snapshot);
+            groups = [batch];
+        }
+        else if (subject)
+            groups = [];
+        else
+            groups = this.named();
+        for (const batch of groups)
+            for (const quad of batch)
+                if ((!subject || subject.equals(quad.subject)) && (!predicate || predicate.equals(quad.predicate)) &&
+                    (!object || object.equals(quad.object)) && (!graph || graph.equals(quad.graph)))
+                    yield quad;
+    }
+    /** Exact cardinalities for the record projection; other patterns count the same iterator. */
+    countMatches(subject, predicate, object, graph) {
+        if (!subject && !object && [CG + 'record', CG + 'ordinal'].includes(predicate?.value ?? '')) {
+            if (graph && graph.termType !== 'DefaultGraph')
+                return 0;
+            if (predicate.value === CG + 'ordinal')
+                return this.snapshot.facts.length;
+            let count = 0;
+            for (const group of this.records.values())
+                count += group.length === 1 ? 1 : new Set(group.map(({ fact }) => stableJson(fact))).size;
+            return count;
+        }
+        let count = 0;
+        for (const _quad of this.match(subject, predicate, object, graph))
+            count++;
+        return count;
+    }
+    /** Each union subject occurs in exactly one partition, with all its outgoing triples. */
+    *validation() {
+        yield* this.recordPartitions(false);
+        let batch = new Store(), count = 0;
+        for (const [id, group] of this.nodes) {
+            for (const node of group.variants.values()) {
+                addNodeRdf(batch, node);
+                addAttributes(batch, node);
+            }
+            for (const fact of group.outgoing)
+                batch.addQuad(iri(nodeIri(id)), iri(CG + fact.predicate), iri(nodeIri(fact.object.id)));
+            if (++count % this.batchSize === 0) {
+                yield batch;
+                batch = new Store();
+            }
+        }
+        if (batch.size)
+            yield batch;
+        const manifest = new Store();
+        addManifest(manifest, this.snapshot);
+        yield manifest;
+    }
+    /** Original named dataset, in bounded groups. Triple order is not a content identity. */
+    *named() {
+        yield* this.recordPartitions(true);
+        let batch = new Store(), count = 0;
+        for (const group of this.nodes.values()) {
+            for (const node of group.variants.values())
+                addNodeRdf(batch, node);
+            if (++count % this.batchSize === 0) {
+                yield batch;
+                batch = new Store();
+            }
+        }
+        if (batch.size)
+            yield batch;
+        const manifest = new Store();
+        addManifest(manifest, this.snapshot);
+        yield manifest;
+    }
+    *recordPartitions(edges) {
+        let batch = new Store(), count = 0;
+        for (const records of this.records.values()) {
+            for (const { fact, ordinal } of records) {
+                addFactRecord(batch, fact, ordinal);
+                if (edges)
+                    addFactEdges(batch, fact);
+            }
+            if (++count % this.batchSize === 0) {
+                yield batch;
+                batch = new Store();
+            }
+        }
+        if (batch.size)
+            yield batch;
+    }
+    /** Only cross-subject information used by the admitted SHACL fragment is rdf:type. */
+    get count() { return Math.ceil(this.records.size / this.batchSize) + Math.ceil(this.nodes.size / this.batchSize) + 1; }
+    types(progress) {
+        const result = new Map();
+        let completed = 0;
+        for (const batch of this.validation()) {
+            for (const quad of batch.getQuads(null, iri(RDF + 'type'), null, null)) {
+                const values = result.get(quad.subject.value) ?? new Set();
+                values.add(quad.object.value);
+                result.set(quad.subject.value, values);
+            }
+            progress?.(++completed);
+        }
+        return result;
+    }
+}

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

@@ -0,0 +1,7 @@
+import type { GraphFact } from '@weftlet/core';
+/**
+ * Equivalent to SELECT cg:record JOIN cg:ordinal ORDER BY ordinal. The record
+ * literal uses the canonical RDF encoder, not a separate interpretation of facts.
+ * Preserve duplicate-ID join multiplicity too; callers can reject corrupt IDs.
+ */
+export declare function projectRdfFacts(facts: readonly GraphFact[]): readonly GraphFact[];

package/dist/graph/rdf-projection.js

@@ -0,0 +1,27 @@
+import { stableJson } from '../infrastructure/util.js';
+/**
+ * Equivalent to SELECT cg:record JOIN cg:ordinal ORDER BY ordinal. The record
+ * literal uses the canonical RDF encoder, not a separate interpretation of facts.
+ * Preserve duplicate-ID join multiplicity too; callers can reject corrupt IDs.
+ */
+export function projectRdfFacts(facts) {
+    const counts = new Map();
+    for (const fact of facts)
+        counts.set(fact.id, (counts.get(fact.id) ?? 0) + 1);
+    const duplicates = new Map();
+    for (const fact of facts)
+        if (counts.get(fact.id) > 1) {
+            const records = duplicates.get(fact.id) ?? new Set();
+            records.add(stableJson(fact));
+            duplicates.set(fact.id, records);
+        }
+    const result = [];
+    for (const fact of facts) {
+        if (duplicates.has(fact.id))
+            for (const record of duplicates.get(fact.id))
+                result.push(JSON.parse(record));
+        else
+            result.push(JSON.parse(stableJson(fact)));
+    }
+    return result;
+}

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

@@ -0,0 +1,12 @@
+import { DataFactory, Store } from 'n3';
+import type { GraphFact, GraphSnapshot, GraphNode } from '@weftlet/core';
+declare const iri: <Iri extends string = string>(value: Iri) => import("n3").NamedNode<Iri>;
+export declare const nodeIri: (id: string) => string;
+export declare const factIri: (id: string) => string;
+export declare function addFactRecord(dataset: Store, fact: GraphFact, ordinal: number): void;
+export declare function addNodeRdf(dataset: Store, node: GraphNode): void;
+export declare function addAttributes(dataset: Store, node: GraphNode, graph?: ReturnType<typeof iri> | ReturnType<typeof DataFactory.defaultGraph>): void;
+export declare function addFactEdges(dataset: Store, fact: GraphFact): void;
+export declare function addManifest(dataset: Store, snapshot: GraphSnapshot): void;
+export declare function evidenceDataset(snapshot: GraphSnapshot): Store;
+export {};