@weftlet/toolkit 0.7.0 → 0.7.2

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-search.d.ts

@@ -16,11 +16,13 @@ export declare function searchEvidencePaths(edges: readonly PathEdge[], start: s
     paths: EvidencePath[];
     frontier: {
         pending: {
-            nodeId: string;
-            viaFactIds: string[];
-            nextFactId: string;
-            remainingCandidates: number;
+            readonly nodeId: string;
+            readonly viaFactIds: readonly string[];
+            readonly nextFactId: string;
+            readonly remainingCandidates: number;
         }[];
+        pendingCount: number;
+        omittedPending: number;
         depthLimited: {
             count: number;
             examples: {

package/dist/graph/path-search.js

@@ -14,7 +14,10 @@ export function searchEvidencePaths(edges, start, target, options, knownNodeIds)
     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)) {
+    // Building adjacency already visits every input edge. Prefer closing edges in
+    // that index; candidate examination below still counts every selected edge.
+    for (const edge of [...edges].sort((a, b) => Number(b.to === target) - Number(a.to === target) ||
+        (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);
@@ -22,40 +25,55 @@ export function searchEvidencePaths(edges, start, target, options, knownNodeIds)
         nodeIds.add(edge.to);
     }
     const paths = [];
-    const stack = nodeIds.has(start) && nodeIds.has(target) && start !== target ? [{ nodeId: start, next: 0 }] : [];
+    // At most one prefix is allocated per examined edge, bounded by searchLimit.
+    // Parent links retain distinct simple paths without copying whole path arrays.
+    const queue = nodeIds.has(start) && nodeIds.has(target) && start !== target
+        ? [{ nodeId: start, next: 0, depth: 0 }] : [];
+    let head = 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();
+        while (head < queue.length && queue[head].next >= (adjacency.get(queue[head].nodeId)?.length ?? 0))
+            head++;
+    };
+    const prefixPath = (frame) => {
+        const nodeIds = [], factIds = [];
+        for (let cursor = frame; cursor; cursor = cursor.parent) {
+            nodeIds.push(cursor.nodeId);
+            if (cursor.via !== undefined)
+                factIds.push(cursor.via);
+        }
+        return { nodeIds: nodeIds.reverse(), factIds: factIds.reverse() };
     };
     const step = () => {
-        const frame = stack.at(-1);
+        const frame = queue[head];
         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) {
+        for (let cursor = frame; cursor; cursor = cursor.parent) {
+            if (cursor.nodeId === edge.to)
+                return;
+        }
+        if (frame.depth === options.maxDepth) {
             depthCount++;
             if (depthExamples.length < 20)
-                depthExamples.push({ nodeId: frame.nodeId, viaFactIds,
+                depthExamples.push({ nodeId: frame.nodeId, viaFactIds: prefixPath(frame).factIds,
                     nextFactId: edge.id, nextNodeId: edge.to });
         }
         else if (edge.to === target) {
-            return { nodeIds: [...stack.map(item => item.nodeId), target], factIds: [...viaFactIds, edge.id] };
+            const path = prefixPath(frame);
+            return { nodeIds: [...path.nodeIds, target], factIds: [...path.factIds, edge.id] };
         }
-        else {
-            stack.push({ nodeId: edge.to, next: 0, via: edge.id });
+        else if (adjacency.has(edge.to)) {
+            queue.push({ nodeId: edge.to, next: 0, depth: frame.depth + 1, via: edge.id, parent: frame });
         }
     };
     trim();
-    // Reconstruct only bounded search state. Never accept a caller-supplied stack or facts.
+    // Reconstruct bounded search state; never accept a caller-supplied queue or facts.
     const replay = () => {
         let replayPageSteps = 0;
         let replayPagePaths = 0;
-        while (totalSteps < offset && stack.length) {
+        while (totalSteps < offset && head < queue.length) {
             if (step())
                 replayPagePaths++;
             replayPageSteps++;
@@ -65,26 +83,33 @@ export function searchEvidencePaths(edges, start, target, options, knownNodeIds)
             }
             trim();
         }
-        if (totalSteps !== offset || (offset && (!stack.length || replayPagePaths || replayPageSteps))) {
+        if (totalSteps !== offset || (offset && (head === queue.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) {
+    while (head < queue.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 pending = [];
+    let pendingCount = 0;
+    for (let index = head; index < queue.length; index++) {
+        const frame = queue[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;
+        if (frame.next >= entries.length)
+            continue;
+        pendingCount++;
+        if (pending.length < 32)
+            pending.push({ nodeId: frame.nodeId,
+                viaFactIds: prefixPath(frame).factIds, nextFactId: entries[frame.next].id,
+                remainingCandidates: entries.length - frame.next });
+    }
+    const exhaustedWithinDepth = head === queue.length;
     const stopReason = () => {
         if (exhaustedWithinDepth)
             return 'exhausted';
@@ -94,7 +119,8 @@ export function searchEvidencePaths(edges, start, target, options, knownNodeIds)
             return 'path-page-limit';
         return 'work-page-limit';
     };
-    return { paths, frontier: { pending, depthLimited: { count: depthCount, examples: depthExamples,
+    return { paths, frontier: { pending, pendingCount, omittedPending: pendingCount - pending.length,
+            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.js

@@ -16,7 +16,7 @@ export function renderGraphPaths(result) {
         `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).`,
+        `Unexamined prefixes: ${frontier.pendingCount ?? frontier.pending.length} (${frontier.omittedPending ?? 0} examples omitted); 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.'] : []),

package/dist/graph/paths.d.ts

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

package/dist/graph/paths.js

@@ -1,12 +1,12 @@
 import { snapshotContext } from './snapshot-context.js';
-import { sha256, stableJson } from '../infrastructure/util.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';
+export const GRAPH_PATHS_VERSION = 'simple-evidence-paths-v2';
 function continuationOffset(token, binding) {
     if (!token)
         return 0;
@@ -41,8 +41,8 @@ export class SnapshotGraphPathService {
         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 = sha256(stableJson({ version: GRAPH_PATHS_VERSION, query, manifest: saved.manifest,
-            facts: all, diagnostics: saved.diagnostics, unresolved: saved.unresolved }));
+        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 => {
@@ -65,7 +65,7 @@ export class SnapshotGraphPathService {
             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,
+            search: { version: GRAPH_PATHS_VERSION, order: 'shortest-first-target-first', direction: request.direction,
                 predicates: request.predicates, maxDepth: request.maxDepth, maxPaths: request.maxPaths, maxSteps: request.maxSteps,
                 ...result.search, ...(next ? { continuation: next } : {}) }, frontier: result.frontier,
         };

package/dist/graph/ranking.d.ts

@@ -1,6 +1,6 @@
 import type { GraphFact } from '@weftlet/core';
 /** Binds continuation offsets to the ordering policy; changing this requires restarting a scan. */
-export declare const IMPACT_RANKING_VERSION = "proximity-diversity-v1";
+export declare const IMPACT_RANKING_VERSION = "local-relationships-diversity-v2";
 export declare function factSearchText(fact: GraphFact): string;
 export interface RankedImpactFact {
     readonly fact: GraphFact;

package/dist/graph/ranking.js

@@ -1,6 +1,7 @@
 import { stableJson } from '../infrastructure/util.js';
+import { impactRankingSignals } from './impact-signals.js';
 /** Binds continuation offsets to the ordering policy; changing this requires restarting a scan. */
-export const IMPACT_RANKING_VERSION = 'proximity-diversity-v1';
+export const IMPACT_RANKING_VERSION = 'local-relationships-diversity-v2';
 export function factSearchText(fact) {
     return [fact.subject.id, fact.subject.label, fact.predicate, fact.object.id,
         fact.object.label, fact.provenance.path].join(' ').toLowerCase();
@@ -24,6 +25,9 @@ function stableTie(fact) {
 }
 /** Order an already bounded reachable set. No facts are pruned and no authority is changed. */
 export function rankImpactFacts(facts, direct, anchorTerms, focus) {
+    const signals = impactRankingSignals(facts, anchorTerms);
+    const costs = new Map(facts.map(fact => [fact, signals.penalty(fact)]));
+    const cost = (fact, forward) => Math.max(edgeCost(fact, forward), costs.get(fact));
     const adjacent = new Map();
     const connect = (from, to, cost) => {
         if (from.kind === 'Project' || to.kind === 'Project')
@@ -33,8 +37,8 @@ export function rankImpactFacts(facts, direct, anchorTerms, focus) {
         adjacent.set(from.id, edges);
     };
     for (const fact of facts) {
-        connect(fact.subject, fact.object, edgeCost(fact, true));
-        connect(fact.object, fact.subject, edgeCost(fact, false));
+        connect(fact.subject, fact.object, cost(fact, true));
+        connect(fact.object, fact.subject, cost(fact, false));
     }
     const distance = new Map();
     // Integer edge costs permit a bucket queue: O(edges + maximum path cost), without a heap dependency.
@@ -46,10 +50,8 @@ export function rankImpactFacts(facts, direct, anchorTerms, focus) {
         (pending[cost] ??= []).push(id);
     };
     for (const fact of direct) {
-        const eligible = [fact.subject, fact.object].filter((node) => node.kind !== 'Project');
-        const matching = eligible.filter((node) => anchorTerms.some((term) => `${node.id} ${node.label}`.toLowerCase().includes(term)));
         // Some adapters only identify an anchor through its citation. Keep those queries supported.
-        for (const node of matching.length ? matching : eligible)
+        for (const node of signals.seedNodes(fact))
             enqueue(node.id, 0);
     }
     for (let cost = 0; cost < pending.length; cost++) {
@@ -65,14 +67,20 @@ export function rankImpactFacts(facts, direct, anchorTerms, focus) {
         const text = factSearchText(fact);
         return {
             fact,
-            proximity: directIds.has(fact.id) ? 0 : Math.min((distance.get(fact.subject.id) ?? Infinity) + edgeCost(fact, true), (distance.get(fact.object.id) ?? Infinity) + edgeCost(fact, false)),
+            proximity: costs.get(fact) + (directIds.has(fact.id) ? 0 : Math.min((distance.get(fact.subject.id) ?? Infinity) + cost(fact, true), (distance.get(fact.object.id) ?? Infinity) + cost(fact, false))),
+            relationshipOrder: signals.relationshipOrder(fact),
             focus: focus.filter((term) => text.includes(term)).length,
             tie: stableTie(fact),
         };
     });
     const lexical = (a, b) => a < b ? -1 : a > b ? 1 : 0;
-    const compare = (a, b) => b.focus - a.focus || lexical(a.tie, b.tie) || lexical(a.fact.id, b.fact.id);
-    rows.sort((a, b) => a.proximity - b.proximity || compare(a, b));
+    const compare = (a, b) => a.relationshipOrder - b.relationshipOrder || b.focus - a.focus || lexical(a.tie, b.tie) || lexical(a.fact.id, b.fact.id);
+    // Allocate each source's early slots to relationships before local occurrence
+    // detail. Otherwise hundreds of nearer variable references consume a file's
+    // diversity allowance before its file-to-symbol consumer can be considered.
+    // Final ordering below still charges distance and shared-library penalties.
+    rows.sort((a, b) => costs.get(a.fact) - costs.get(b.fact) ||
+        a.relationshipOrder - b.relationshipOrder || a.proximity - b.proximity || compare(a, b));
     const counts = new Map();
     const diverse = rows.map((row) => {
         const seen = counts.get(row.fact.provenance.path) ?? 0;

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 {};