@weftlet/toolkit 0.0.0-stage → 0.1.0

package/dist/graph/query.js

@@ -0,0 +1,373 @@
+// Modified for standalone extraction; see docs/extraction-manifest.json.
+import { contextPackEvidenceAuthority } from "./authority.js";
+import { RdfEvidenceGraph } from "./rdf.js";
+import { sha256, stableJson } from "../infrastructure/util.js";
+import { diagnosticSummary, selectDiagnostics } from "./diagnostics.js";
+export const DEFAULT_CONTEXT_PACK_FACTS = 60;
+export const MAX_CONTEXT_PACK_FACTS = 200;
+const contextPackLanes = [
+    'productIntent',
+    'contractsAndInvariants',
+    'implementationAndConsumers',
+    'validationEvidence',
+];
+function isValidationFact(fact) {
+    const path = fact.provenance.path.toLowerCase();
+    return (fact.subject.kind === 'Evidence' ||
+        fact.object.kind === 'Evidence' ||
+        fact.predicate === 'verifiedBy' ||
+        /(?:^|\/)(?:test|tests|testing|validation|evidence)(?:\/|$)/.test(path) ||
+        /\.(?:spec|test)\.[cm]?[jt]sx?$/.test(path));
+}
+function isDeclaredFact(fact) {
+    if (fact.authority)
+        return fact.authority === 'declared' && !isValidationFact(fact);
+    return false;
+}
+export function contextPackLaneForFact(fact) {
+    if (fact.extractor.id === 'otlp-runtime-evidence')
+        return undefined;
+    const kinds = new Set([fact.subject.kind, fact.object.kind]);
+    if (isValidationFact(fact)) {
+        return 'validationEvidence';
+    }
+    if (kinds.has('Contract') ||
+        kinds.has('Invariant') ||
+        kinds.has('PersistenceModel') ||
+        ['governedBy', 'definedBy', 'persistsTo', 'authorizedBy'].includes(fact.predicate)) {
+        return 'contractsAndInvariants';
+    }
+    if ((isDeclaredFact(fact) || fact.sourceAuthority === 'declared') &&
+        (kinds.has('Document') ||
+            kinds.has('Capability') ||
+            kinds.has('Workflow') ||
+            ['decisionAuthority', 'operationallyOwnedBy', 'references'].includes(fact.predicate))) {
+        return 'productIntent';
+    }
+    return 'implementationAndConsumers';
+}
+export { contextPackEvidenceAuthority } from "./authority.js";
+function selectBalancedFacts(ranked, maxFacts) {
+    const queues = Object.fromEntries(contextPackLanes.map((lane) => [
+        lane,
+        ranked.filter((fact) => contextPackLaneForFact(fact) === lane),
+    ]));
+    const facts = [];
+    while (facts.length < maxFacts && contextPackLanes.some((lane) => queues[lane].length > 0)) {
+        for (const lane of contextPackLanes) {
+            const fact = queues[lane].shift();
+            if (fact)
+                facts.push(fact);
+            if (facts.length === maxFacts)
+                break;
+        }
+    }
+    const counts = Object.fromEntries(contextPackLanes.map((lane) => [
+        lane,
+        facts.filter((fact) => contextPackLaneForFact(fact) === lane).length,
+    ]));
+    return { facts, counts };
+}
+const searchStopWords = new Set([
+    'about',
+    'agent',
+    'and',
+    'from',
+    'into',
+    'preserving',
+    'replacing',
+    'rules',
+    'the',
+    'while',
+    'with',
+]);
+function focusTerms(values) {
+    return [
+        ...new Set(values
+            .filter((value) => Boolean(value))
+            .flatMap((value) => [value, ...value.split(/[^A-Za-z0-9_.:/-]+/)])
+            .map((value) => value.toLowerCase())
+            .filter((value) => value.length >= 4 && !searchStopWords.has(value))),
+    ];
+}
+function factSearchText(fact) {
+    return [
+        fact.subject.id,
+        fact.subject.label,
+        fact.predicate,
+        fact.object.id,
+        fact.object.label,
+        fact.provenance.path,
+    ]
+        .join(' ')
+        .toLowerCase();
+}
+function semanticPriority(fact) {
+    return /codex-cli|document-linker/.test(fact.extractor.id) ? 0 : 1;
+}
+function boundedFactLimit(value) {
+    if (value === undefined)
+        return DEFAULT_CONTEXT_PACK_FACTS;
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error('maxFacts must be a positive integer');
+    }
+    return Math.min(value, MAX_CONTEXT_PACK_FACTS);
+}
+export class MarkdownContextPackRenderer {
+    render(pack) {
+        const lines = [
+            `# Context Pack`,
+            '',
+            `Snapshot: \`${pack.snapshot.snapshotId}\` (${pack.snapshot.commitSha})`,
+            `Configuration: ${pack.snapshot.configurationDigest ?? 'legacy/unknown'}; scope: ${pack.snapshot.scope?.join(', ') ?? 'legacy/unknown'}`,
+            ...(pack.exploration ? [
+                `Relationships returned: ${pack.exploration.returned}/${pack.exploration.reachableFacts}; truncated: ${pack.exploration.truncated}; depth limit reached: ${pack.exploration.depthLimitReached}`,
+                ...(pack.exploration.continuation ? [`Continuation: ${pack.exploration.continuation}`] : []),
+            ] : []),
+            ...(pack.evidenceState ? [
+                `Stale relative to checkout: ${pack.evidenceState.stale}; configuration matches: ${pack.evidenceState.configurationMatches}`,
+                `Excluded working changes: ${pack.evidenceState.excludedWorkingChanges.join(', ') || '(none)'}`,
+                ...(pack.evidenceState.overlayFreshness ? [
+                    `Overlay freshness: ${pack.evidenceState.overlayFreshness}`,
+                    `Captured working changes: ${pack.evidenceState.capturedWorkingChanges?.join(', ') || '(none)'}`,
+                    `Changed since capture: ${pack.evidenceState.changedSinceCapture?.join(', ') || '(none)'}`,
+                ] : []),
+                'Saved evidence does not validate the current working diff.',
+            ] : []),
+            '',
+            '## Capabilities',
+            ...pack.capabilities.map((node) => `- ${node.label} (\`${node.id}\`)`),
+            '',
+            '## Governing invariants',
+            ...pack.invariants.map((item) => `- ${item.status}: ${item.message}`),
+            '',
+            '## Coverage',
+            ...contextPackLanes.map((lane) => `- ${lane}: ${pack.coverage.counts[lane]} relationships`),
+            ...(pack.coverage.gaps.length
+                ? pack.coverage.gaps.map((gap) => `- GAP: ${gap}`)
+                : ['- No Context Pack lane gaps detected.']),
+            ...contextPackLanes.flatMap((lane) => [
+                '',
+                `## ${lane}`,
+                ...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}\`, confidence ${fact.confidence}${fact.sourceAuthority ? `; source ${fact.sourceAuthority}; extraction ${fact.extractionReview ?? 'unknown'}` : ''})`),
+            ]),
+            '',
+            '## Runtime evidence',
+            ...(pack.runtimeEvidence.length
+                ? pack.runtimeEvidence.map((item) => `- [observed] ${item.accepted ? 'accepted' : 'segregated'} trace \`${item.traceId}\` ` +
+                    `(${item.serviceName}@${item.serviceVersion}; ` +
+                    `${item.capability ?? 'unmapped capability'}; ` +
+                    `${item.operation ?? 'unmapped operation'}; ` +
+                    `${item.environment ?? 'unknown environment'}; ` +
+                    `${item.observedAt ?? 'unknown observation time'})`)
+                : ['- GAP: No accepted exact-deployment runtime evidence matched this request.']),
+            '',
+            '## Suggested files',
+            ...pack.suggestedFiles.map((path) => `- \`${path}\``),
+            '',
+            '## Scoped diagnostics',
+            ...diagnosticSummary(pack).map((item) => `- ${item}`),
+        ];
+        return lines.join('\n');
+    }
+}
+export class SnapshotImpactQueryService {
+    store;
+    headName;
+    renderer;
+    constructor(store, headName, renderer = new MarkdownContextPackRenderer()) {
+        this.store = store;
+        this.headName = headName;
+        this.renderer = renderer;
+    }
+    async scan(request) {
+        const maxFacts = boundedFactLimit(request.maxFacts);
+        const saved = request.snapshotId
+            ? await this.store.read(request.snapshotId)
+            : await this.store.readHead(this.headName);
+        if (!saved)
+            throw new Error('No graph snapshot is available; run context-graph hydrate first');
+        const snapshot = { ...saved, facts: await new RdfEvidenceGraph(saved).facts() };
+        const maxDepth = request.maxDepth ?? 32;
+        if (!Number.isInteger(maxDepth) || maxDepth < 1 || maxDepth > 128) {
+            throw new Error('maxDepth must be an integer between 1 and 128');
+        }
+        const anchorTerms = [
+            request.ownerDocument,
+            ...(request.changedFiles ?? []),
+            ...(request.symbols ?? []),
+        ]
+            .filter((term) => Boolean(term))
+            .map((term) => term.toLowerCase());
+        const focus = focusTerms([
+            request.task,
+            ...(request.checklistItems ?? []),
+            ...(request.capabilities ?? []),
+        ]);
+        const terms = [...anchorTerms, ...focus];
+        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 distance = new Map(direct.map((fact) => [fact.id, 0]));
+        let frontier = new Set(direct.flatMap((fact) => [fact.subject, fact.object]
+            .filter((node) => node.kind !== 'Project')
+            .map((node) => node.id)));
+        const visitedNodes = new Set(frontier);
+        for (let depth = 0; depth < maxDepth && frontier.size > 0; depth += 1) {
+            const next = new Set();
+            for (const fact of snapshot.facts) {
+                if (!frontier.has(fact.subject.id) && !frontier.has(fact.object.id))
+                    continue;
+                ranked.set(fact.id, fact);
+                if (!distance.has(fact.id))
+                    distance.set(fact.id, depth + 1);
+                for (const node of [fact.subject, fact.object]) {
+                    if (node.kind !== 'Project' && !visitedNodes.has(node.id))
+                        next.add(node.id);
+                }
+            }
+            for (const node of next)
+                visitedNodes.add(node);
+            frontier = next;
+        }
+        const ordered = [...ranked.values()].sort((left, right) => {
+            const leftText = factSearchText(left);
+            const rightText = factSearchText(right);
+            const leftFocus = focus.filter((term) => leftText.includes(term)).length;
+            const rightFocus = focus.filter((term) => rightText.includes(term)).length;
+            return (rightFocus - leftFocus ||
+                semanticPriority(left) - semanticPriority(right) ||
+                (distance.get(left.id) ?? 4) - (distance.get(right.id) ?? 4) ||
+                left.id.localeCompare(right.id));
+        });
+        const allBalanced = [
+            ...selectBalancedFacts(ordered, ordered.length).facts,
+            ...ordered.filter((fact) => contextPackLaneForFact(fact) === undefined),
+        ];
+        const { continuation: _continuation, snapshotId: _snapshotId, ...query } = request;
+        const queryDigest = sha256(stableJson(query));
+        let offset = 0;
+        if (request.continuation) {
+            if (request.continuation.length > 2048)
+                throw new Error('Invalid continuation');
+            const token = JSON.parse(Buffer.from(request.continuation, 'base64url').toString('utf8'));
+            if (token.snapshot !== snapshot.manifest.snapshotId ||
+                token.digest !== snapshot.manifest.contentDigest || token.query !== queryDigest ||
+                !Number.isInteger(token.offset) || token.offset < 0 || token.offset > allBalanced.length) {
+                throw new Error('Continuation does not match this snapshot and query');
+            }
+            offset = token.offset;
+        }
+        const facts = allBalanced.slice(offset, offset + maxFacts);
+        const balanced = selectBalancedFacts(facts, facts.length);
+        const nextOffset = offset + facts.length;
+        const continuation = nextOffset < allBalanced.length ? Buffer.from(JSON.stringify({
+            snapshot: snapshot.manifest.snapshotId, digest: snapshot.manifest.contentDigest,
+            query: queryDigest, offset: nextOffset,
+        })).toString('base64url') : undefined;
+        const capabilities = [
+            ...new Map(facts
+                .flatMap((fact) => [fact.subject, fact.object])
+                .filter((node) => node.kind === 'Capability')
+                .map((node) => [node.id, node])).values(),
+        ];
+        const suggestedFiles = [
+            ...new Set([...direct, ...facts].map((fact) => fact.provenance.path).filter(Boolean)),
+        ].slice(0, 20);
+        const runtimeEvidence = snapshot.runtimeEvidence.filter((item) => item.accepted &&
+            (!terms.length ||
+                terms.some((term) => item.capability?.includes(term) || item.operation?.includes(term))));
+        const declaredCapabilityIds = new Set(snapshot.facts
+            .filter(isDeclaredFact)
+            .flatMap((fact) => [fact.subject, fact.object])
+            .filter((node) => node.kind === 'Capability')
+            .map((node) => node.id));
+        const queryDiagnostics = runtimeEvidence.flatMap((item) => {
+            if (!item.capability)
+                return [];
+            const capability = `capability:${item.capability.replace(/^(?:[^:]+:)?capability:/, '')}`;
+            if (declaredCapabilityIds.has(capability))
+                return [];
+            return [
+                {
+                    id: `runtime-intent-gap-${item.traceId}-${item.spanId}`,
+                    kind: 'drift',
+                    reason: `Observed runtime capability ${capability} has no declared product-intent mapping. Verify the source docs before concluding intent is absent.`,
+                    // This is a query over runtime references, not a cited passage in the source file.
+                    // The actual trace/span and source digest remain in pack.runtimeEvidence.
+                    provenance: [],
+                    relatedNodeIds: [capability],
+                    evidenceScope: 'snapshot-query',
+                },
+            ];
+        });
+        for (const [kind, missing, reason] of [
+            [
+                'missingIntent',
+                balanced.counts.productIntent === 0,
+                'No declared intent matched this query. Inspect the owner and philosophy sources before concluding a requirement is missing.',
+            ],
+            [
+                'implementationGaps',
+                balanced.counts.implementationAndConsumers === 0,
+                'No implementation relationships matched this query. Inspect code before concluding behavior is missing.',
+            ],
+            [
+                'runtimeGaps',
+                runtimeEvidence.length === 0,
+                'No accepted exact-deployment runtime evidence matched this query; runtime behavior is not observed.',
+            ],
+        ]) {
+            if (missing)
+                queryDiagnostics.push({
+                    id: `query-${kind}`,
+                    kind,
+                    reason,
+                    provenance: [],
+                    relatedNodeIds: [],
+                    evidenceScope: 'snapshot-query',
+                });
+        }
+        const plain = {
+            snapshot: {
+                snapshotId: snapshot.manifest.snapshotId,
+                commitSha: snapshot.manifest.commitSha,
+                contentDigest: snapshot.manifest.contentDigest,
+                configurationDigest: snapshot.manifest.configurationDigest,
+                scope: snapshot.manifest.scope,
+                baseSha: snapshot.manifest.baseSha,
+                overlayDigest: snapshot.manifest.overlayDigest,
+                overlayCapture: snapshot.manifest.overlayCapture,
+            },
+            capabilities,
+            facts,
+            invariants: snapshot.invariants.filter((item) => item.provenance.some((span) => suggestedFiles.includes(span.path))),
+            runtimeEvidence,
+            suggestedFiles,
+            coverage: {
+                counts: balanced.counts,
+                gaps: [...contextPackLanes
+                        .filter((lane) => balanced.counts[lane] === 0)
+                        .map((lane) => `No ${lane} evidence matched this request.`),
+                    ...(facts.some((fact) => fact.sourceAuthority === 'declared' && fact.extractionReview === 'unreviewed')
+                        ? ['Approved-source extraction remains unreviewed; verify cited intent before using it as a rule or gate.'] : [])],
+            },
+            diagnostics: selectDiagnostics(snapshot, request, facts, focus, queryDiagnostics),
+            exploration: {
+                returned: facts.length, reachableFacts: allBalanced.length, maxDepth,
+                depthLimitReached: frontier.size > 0, truncated: Boolean(continuation) || frontier.size > 0,
+                continuation,
+            },
+        };
+        return { ...plain, markdown: this.renderer.render(plain) };
+    }
+    matches(fact, terms) {
+        if (terms.length === 0)
+            return true;
+        const haystack = factSearchText(fact);
+        return terms.some((term) => haystack.includes(term));
+    }
+}

package/dist/graph/rdf.d.ts

@@ -0,0 +1,26 @@
+import type { GraphFact, GraphSnapshot } from "@weftlet/core";
+export declare const CG = "https://context-graph.dev/record#";
+export declare const nodeIri: (id: string) => string;
+export declare const factIri: (id: string) => string;
+/** Lossless RDF dataset: one named graph per cited assertion, with provenance in the default graph. */
+export declare class RdfEvidenceGraph {
+    readonly snapshot: GraphSnapshot;
+    private readonly dataset;
+    constructor(snapshot: GraphSnapshot);
+    validate(): Promise<{
+        conforms: boolean;
+        issues: {
+            category: "extraction-gap";
+            focus: string;
+            path: string;
+            message: string;
+        }[];
+    }>;
+    select(sparql: string, maxRows?: number): Promise<{
+        rows: Record<string, string>[];
+        truncated: boolean;
+    }>;
+    /** The traversal projection is read through SPARQL, not a separate fact source. */
+    facts(): Promise<readonly GraphFact[]>;
+    serialize(): Promise<string>;
+}

package/dist/graph/rdf.js

@@ -0,0 +1,144 @@
+import { QueryEngine } from '@comunica/query-sparql';
+import { DataFactory, Parser, Store, Writer } from 'n3';
+import SHACLValidator from 'rdf-validate-shacl';
+import { contextPackEvidenceAuthority } from "./authority.js";
+import { stableJson } from "../infrastructure/util.js";
+import { createRequire } from 'node:module';
+const { namedNode: iri, literal, quad } = DataFactory;
+export const CG = 'https://context-graph.dev/record#';
+const RDF = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#';
+const XSD = 'http://www.w3.org/2001/XMLSchema#';
+export const nodeIri = (id) => `urn:context-graph:node:${encodeURIComponent(id)}`;
+export const factIri = (id) => `urn:context-graph:fact:${encodeURIComponent(id)}`;
+const engine = new QueryEngine();
+const SparqlParser = createRequire(import.meta.url)('sparqljs').Parser;
+const shapes = new Parser().parse(`
+@prefix cg: <${CG}>.
+@prefix rdf: <${RDF}>.
+@prefix sh: <http://www.w3.org/ns/shacl#>.
+@prefix xsd: <${XSD}>.
+cg:FactShape a sh:NodeShape; sh:targetClass rdf:Statement;
+ sh:property [ sh:path cg:record; sh:minCount 1; sh:maxCount 1; sh:datatype xsd:string ];
+ sh:property [ sh:path rdf:subject; sh:minCount 1; sh:maxCount 1; sh:nodeKind sh:IRI ];
+ sh:property [ sh:path rdf:predicate; sh:minCount 1; sh:maxCount 1; sh:nodeKind sh:IRI ];
+ sh:property [ sh:path rdf:object; sh:minCount 1; sh:maxCount 1; sh:nodeKind sh:IRI ];
+ sh:property [ sh:path cg:authority; sh:minCount 1; sh:maxCount 1;
+   sh:in ("declared" "implemented" "validated" "observed" "inferred" "draft") ];
+ sh:property [ sh:path cg:path; sh:minCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:commit; sh:minCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:sourceDigest; sh:minCount 1; sh:datatype xsd:string; sh:minLength 1 ];
+ sh:property [ sh:path cg:startLine; sh:minCount 1; sh:datatype xsd:integer; sh:minInclusive 1 ];
+ sh:property [ sh:path cg:endLine; sh:minCount 1; sh:datatype xsd:integer; sh:minInclusive 1 ];
+ sh:property [ sh:path cg:confidence; sh:minCount 1; sh:datatype xsd:decimal; sh:minInclusive 0; sh:maxInclusive 1 ];
+ sh:property [ sh:path cg:extractor; sh:minCount 1; sh:datatype xsd:string; sh:minLength 1 ].
+cg:NodeShape a sh:NodeShape; sh:targetClass cg:Node;
+ sh:property [ sh:path cg:kind; sh:minCount 1; sh:maxCount 1 ].
+`);
+/** Lossless RDF dataset: one named graph per cited assertion, with provenance in the default graph. */
+export class RdfEvidenceGraph {
+    snapshot;
+    dataset = new Store();
+    constructor(snapshot) {
+        this.snapshot = snapshot;
+        for (const [ordinal, fact] of snapshot.facts.entries()) {
+            const record = iri(factIri(fact.id));
+            const subject = iri(nodeIri(fact.subject.id));
+            const object = iri(nodeIri(fact.object.id));
+            const predicate = iri(CG + fact.predicate);
+            this.dataset.addQuad(subject, predicate, object, record);
+            this.dataset.addQuad(record, iri(RDF + 'type'), iri(RDF + 'Statement'));
+            this.dataset.addQuad(record, iri(CG + 'ordinal'), literal(String(ordinal), iri(XSD + 'integer')));
+            for (const [p, value] of [['subject', subject], ['predicate', predicate], ['object', object]]) {
+                this.dataset.addQuad(record, iri(RDF + p), value);
+            }
+            for (const [p, value] of Object.entries({
+                authority: contextPackEvidenceAuthority(fact), path: fact.provenance.path,
+                commit: fact.provenance.commitSha, sourceDigest: fact.provenance.digest,
+                extractor: `${fact.extractor.id}@${fact.extractor.version}`,
+                snapshotId: fact.snapshotId, record: stableJson(fact),
+                ...(fact.sourceAuthority ? { sourceAuthority: fact.sourceAuthority } : {}),
+                ...(fact.extractionReview ? { extractionReview: fact.extractionReview } : {}),
+            }))
+                this.dataset.addQuad(record, iri(CG + p), literal(value));
+            for (const [p, value] of [['startLine', fact.provenance.startLine], ['endLine', fact.provenance.endLine]]) {
+                this.dataset.addQuad(record, iri(CG + p), literal(String(value), iri(XSD + 'integer')));
+            }
+            this.dataset.addQuad(record, iri(CG + 'confidence'), literal(String(fact.confidence), iri(XSD + 'decimal')));
+            for (const node of [fact.subject, fact.object]) {
+                const term = iri(nodeIri(node.id));
+                this.dataset.addQuad(term, iri(RDF + 'type'), iri(CG + 'Node'));
+                this.dataset.addQuad(term, iri(CG + 'identifier'), literal(node.id));
+                this.dataset.addQuad(term, iri(CG + 'kind'), literal(node.kind));
+                this.dataset.addQuad(term, iri(CG + 'label'), literal(node.label));
+                for (const [key, value] of Object.entries(node.attributes ?? {})) {
+                    const datatype = typeof value === 'boolean' ? 'boolean' : typeof value === 'number' ? 'decimal' : 'string';
+                    this.dataset.addQuad(term, iri(`${CG}attribute/${encodeURIComponent(key)}`), literal(String(value), iri(XSD + datatype)), record);
+                }
+            }
+        }
+        this.dataset.addQuad(iri('urn:context-graph:snapshot'), iri(CG + 'manifest'), literal(stableJson(snapshot.manifest)));
+        for (const scope of snapshot.manifest.scope ?? []) {
+            this.dataset.addQuad(iri('urn:context-graph:snapshot'), iri(CG + 'scope'), literal(scope));
+        }
+        if (snapshot.manifest.configurationDigest) {
+            this.dataset.addQuad(iri('urn:context-graph:snapshot'), iri(CG + 'configurationDigest'), literal(snapshot.manifest.configurationDigest));
+        }
+    }
+    async validate() {
+        const report = await new SHACLValidator(new Store(shapes)).validate(this.dataset);
+        const issues = report.results.map((result) => ({
+            category: 'extraction-gap',
+            focus: result.focusNode?.value,
+            path: result.path?.value,
+            message: result.message.map((message) => message.value).join('; '),
+        }));
+        for (const fact of this.snapshot.facts) {
+            if (fact.provenance.endLine < fact.provenance.startLine) {
+                issues.push({ category: 'extraction-gap', focus: factIri(fact.id), path: CG + 'endLine',
+                    message: 'Citation ends before it starts' });
+            }
+        }
+        return { conforms: report.conforms && issues.length === 0, issues };
+    }
+    async select(sparql, maxRows = 1000) {
+        if (!Number.isInteger(maxRows) || maxRows < 1 || maxRows > 100_000)
+            throw new Error('Invalid SPARQL row bound');
+        const ast = new SparqlParser().parse(sparql);
+        const hasService = (value) => {
+            if (!value || typeof value !== 'object')
+                return false;
+            if (value.type === 'service')
+                return true;
+            return Object.values(value).some(hasService);
+        };
+        if (ast.type !== 'query' || ast.queryType !== 'SELECT' || ast.from || hasService(ast)) {
+            throw new Error('Only local read queries are supported; remote datasets and updates are disabled');
+        }
+        const stream = await engine.queryBindings(sparql, { sources: [this.dataset], unionDefaultGraph: true });
+        const rows = [];
+        let truncated = false;
+        for await (const binding of stream) {
+            if (rows.length === maxRows) {
+                truncated = true;
+                stream.destroy();
+                break;
+            }
+            rows.push(Object.fromEntries([...binding].map(([key, value]) => [key.value, value.value])));
+        }
+        return { rows, truncated };
+    }
+    /** The traversal projection is read through SPARQL, not a separate fact source. */
+    async facts() {
+        const result = await this.select(`SELECT ?record WHERE {
+      ?fact <${CG}record> ?record; <${CG}ordinal> ?ordinal
+    } ORDER BY ?ordinal`, 100_000);
+        if (result.truncated)
+            throw new Error('Graph exceeds the 100000-fact projection bound');
+        return result.rows.map((row) => JSON.parse(row.record));
+    }
+    serialize() {
+        const writer = new Writer({ format: 'N-Quads' });
+        writer.addQuads(this.dataset.getQuads(null, null, null, null));
+        return new Promise((resolve, reject) => writer.end((error, text) => error ? reject(error) : resolve(text)));
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import "../runtime-check.mjs";
+export * from "@weftlet/core";
+export * from "./repository/git.js";
+export * from "./application/hydrator.js";
+export * from "./graph/query.js";
+export * from "./extraction/semantic.js";
+export * from "./extraction/telemetry.js";
+export * from "./visualization/visualization.js";
+export * from "./application/overlay.js";
+export * from "./graph/rdf.js";
+export * from "./extraction/providers.js";

package/dist/index.js

@@ -0,0 +1,12 @@
+// Modified for standalone extraction; see docs/extraction-manifest.json.
+import "../runtime-check.mjs";
+export * from "@weftlet/core";
+export * from "./repository/git.js";
+export * from "./application/hydrator.js";
+export * from "./graph/query.js";
+export * from "./extraction/semantic.js";
+export * from "./extraction/telemetry.js";
+export * from "./visualization/visualization.js";
+export * from "./application/overlay.js";
+export * from "./graph/rdf.js";
+export * from "./extraction/providers.js";

package/dist/infrastructure/module-resolution.d.ts

@@ -0,0 +1,2 @@
+/** Match Node's import conditions, anchored at the consumer rather than toolkit dist/. */
+export declare function resolveConsumerModule(specifier: string, repositoryRoot: string): string;

package/dist/infrastructure/module-resolution.js

@@ -0,0 +1,10 @@
+import { isAbsolute, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { resolve as resolveImport } from 'import-meta-resolve';
+/** Match Node's import conditions, anchored at the consumer rather than toolkit dist/. */
+export function resolveConsumerModule(specifier, repositoryRoot) {
+    if (isAbsolute(specifier))
+        return pathToFileURL(specifier).href;
+    const parent = pathToFileURL(resolve(repositoryRoot, 'package.json')).href;
+    return resolveImport(specifier, parent);
+}

package/dist/infrastructure/process.d.ts

@@ -0,0 +1,5 @@
+export interface ProcessResult {
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export declare function runProcess(command: string, args: readonly string[], cwd: string, environment?: Readonly<Record<string, string | undefined>>): Promise<ProcessResult>;

package/dist/infrastructure/process.js

@@ -0,0 +1,27 @@
+import { spawn } from 'node:child_process';
+export function runProcess(command, args, cwd, environment) {
+    const executable = process.platform === 'win32' && command === 'pnpm' ? 'pnpm.cmd' : command;
+    return new Promise((resolve, reject) => {
+        const child = spawn(executable, [...args], {
+            cwd,
+            env: environment ?? process.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString('utf8');
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString('utf8');
+        });
+        child.once('error', reject);
+        child.once('close', (code) => {
+            if (code === 0)
+                resolve({ stdout, stderr });
+            else
+                reject(new Error(`${command} exited ${code}: ${stderr.slice(-8000)}`));
+        });
+    });
+}

package/dist/infrastructure/util.d.ts

@@ -0,0 +1 @@
+export * from '@weftlet/core';

package/dist/infrastructure/util.js

@@ -0,0 +1,2 @@
+// Modified for standalone extraction; see docs/extraction-manifest.json.
+export * from '@weftlet/core';

package/dist/interfaces/cli.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import "../../runtime-check.mjs";
+import type { ImpactScanRequest } from "@weftlet/core";
+export declare function impactRequestFromArgs(args: readonly string[]): ImpactScanRequest;