sneakoscope 8.3.2 → 8.4.0

package/dist/core/triwiki/context-graph/architecture/policy.js

@@ -0,0 +1,321 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { ARCHITECTURE_FINDING_CODES, ARCHITECTURE_MAP_POLICY_FILE, ARCHITECTURE_MAP_POLICY_SCHEMA } from './contracts.js';
+export const LAYER_EDGE_SEPARATOR = ' -> ';
+const LAYER_ID = /^[a-z][a-z0-9_]*$/;
+const EXCEPTION_ID = /^[a-z][a-z0-9-]*$/;
+const MODULE_ID_SHAPE = /^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/;
+export const ARCHITECTURE_MAP_THRESHOLD_KEYS = [
+    'max_diagram_nodes',
+    'max_diagram_edges',
+    'max_diagram_bytes',
+    'max_module_fan_out',
+    'max_module_fan_in'
+];
+function fail(code, detail) {
+    throw new Error(`${code}: ${detail}`);
+}
+function asRecord(value, where) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        fail('architecture_map_policy_not_an_object', where);
+    }
+    return value;
+}
+function asArray(value, where) {
+    if (!Array.isArray(value))
+        fail('architecture_map_policy_not_an_array', where);
+    return value;
+}
+function asText(value, where) {
+    if (typeof value !== 'string' || value.trim().length === 0)
+        fail('architecture_map_policy_not_text', where);
+    return value;
+}
+function asCount(value, where) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1) {
+        fail('architecture_map_policy_not_a_count', `${where} must be a positive safe integer`);
+    }
+    return value;
+}
+function asNonNeg(value, where) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+        fail('architecture_map_policy_not_nonneg', where);
+    }
+    return value;
+}
+function assertDistinct(values, code, where) {
+    const seen = new Set();
+    for (const value of values) {
+        if (seen.has(value))
+            fail(code, `${where}: ${value}`);
+        seen.add(value);
+    }
+}
+export function parseLayerEdge(edge) {
+    const parts = edge.split(LAYER_EDGE_SEPARATOR);
+    const from = parts[0];
+    const to = parts[1];
+    if (parts.length !== 2 || !from || !to || !LAYER_ID.test(from) || !LAYER_ID.test(to)) {
+        fail('architecture_map_policy_malformed_edge', edge);
+    }
+    return { from, to };
+}
+function parseLayers(value) {
+    const rows = asArray(value, 'layers');
+    if (!rows.length)
+        fail('architecture_map_policy_no_layers', 'layers');
+    const layers = [];
+    for (const [index, row] of rows.entries()) {
+        const where = `layers[${index}]`;
+        const record = asRecord(row, where);
+        const id = asText(record.id, `${where}.id`);
+        if (!LAYER_ID.test(id))
+            fail('architecture_map_policy_bad_layer_id', id);
+        const modules = asArray(record.modules, `${where}.modules`).map((entry, i) => {
+            const moduleId = asText(entry, `${where}.modules[${i}]`);
+            if (!MODULE_ID_SHAPE.test(moduleId) || moduleId.split('/').includes('..')) {
+                fail('architecture_map_policy_bad_module_id', moduleId);
+            }
+            return moduleId;
+        });
+        if (!modules.length)
+            fail('architecture_map_policy_empty_layer', where);
+        assertDistinct(modules, 'architecture_map_policy_duplicate_module', where);
+        layers.push(Object.freeze({
+            id,
+            purpose: asText(record.purpose, `${where}.purpose`),
+            modules: Object.freeze(modules)
+        }));
+    }
+    assertDistinct(layers.map((layer) => layer.id), 'architecture_map_policy_duplicate_layer', 'layers');
+    assertDistinct(layers.flatMap((layer) => layer.modules), 'architecture_map_policy_module_in_two_layers', 'layers');
+    return Object.freeze(layers);
+}
+function parseBoundaries(value, layerIds) {
+    const record = asRecord(value, 'boundaries');
+    if (record.mode !== 'allow-list')
+        fail('architecture_map_policy_bad_boundary_mode', String(record.mode));
+    const rules = asArray(record.allow, 'boundaries.allow').map((row, index) => {
+        const where = `boundaries.allow[${index}]`;
+        const rule = asRecord(row, where);
+        const from = asText(rule.from, `${where}.from`);
+        if (!layerIds.has(from))
+            fail('architecture_map_policy_unknown_layer', from);
+        const to = asArray(rule.to, `${where}.to`).map((entry, i) => {
+            const target = asText(entry, `${where}.to[${i}]`);
+            if (!layerIds.has(target))
+                fail('architecture_map_policy_unknown_layer', target);
+            return target;
+        });
+        return Object.freeze({ from, to: Object.freeze(to) });
+    });
+    assertDistinct(rules.map((rule) => rule.from), 'architecture_map_policy_duplicate_boundary', 'boundaries.allow');
+    return Object.freeze({ mode: 'allow-list', allow: Object.freeze(rules) });
+}
+function parseThresholds(value) {
+    const record = asRecord(value, 'thresholds');
+    return Object.freeze({
+        max_diagram_nodes: asCount(record.max_diagram_nodes, 'thresholds.max_diagram_nodes'),
+        max_diagram_edges: asCount(record.max_diagram_edges, 'thresholds.max_diagram_edges'),
+        max_diagram_bytes: asCount(record.max_diagram_bytes, 'thresholds.max_diagram_bytes'),
+        max_module_fan_out: asCount(record.max_module_fan_out, 'thresholds.max_module_fan_out'),
+        max_module_fan_in: asCount(record.max_module_fan_in, 'thresholds.max_module_fan_in')
+    });
+}
+function parseProfileBudget(value, where) {
+    const record = asRecord(value, where);
+    return Object.freeze({
+        maxNodes: asCount(record.maxNodes, `${where}.maxNodes`),
+        maxEdges: asCount(record.maxEdges, `${where}.maxEdges`),
+        maxLabelChars: asCount(record.maxLabelChars, `${where}.maxLabelChars`),
+        tokenBudget: asNonNeg(record.tokenBudget, `${where}.tokenBudget`)
+    });
+}
+function parseProfiles(value) {
+    const record = asRecord(value, 'profiles');
+    const keys = ['global', 'planning', 'implementation', 'review', 'protected'];
+    const out = {};
+    for (const key of keys) {
+        if (!(key in record))
+            fail('architecture_map_policy_missing_profile', key);
+        out[key] = parseProfileBudget(record[key], `profiles.${key}`);
+    }
+    return Object.freeze(out);
+}
+function parseExceptions(value, layerIds, allowed) {
+    const record = asRecord(value, 'exceptions');
+    if (record.mode !== 'shrink-only')
+        fail('architecture_map_policy_bad_exception_mode', String(record.mode));
+    const claimed = new Set();
+    const entries = asArray(record.entries, 'exceptions.entries').map((row, index) => {
+        const where = `exceptions.entries[${index}]`;
+        const entry = asRecord(row, where);
+        const id = asText(entry.id, `${where}.id`);
+        if (!EXCEPTION_ID.test(id))
+            fail('architecture_map_policy_bad_exception_id', id);
+        const edges = asArray(entry.edges, `${where}.edges`).map((item, i) => {
+            const text = asText(item, `${where}.edges[${i}]`);
+            const edge = parseLayerEdge(text);
+            if (!layerIds.has(edge.from) || !layerIds.has(edge.to)) {
+                fail('architecture_map_policy_unknown_layer', text);
+            }
+            if (allowed.has(text))
+                fail('architecture_map_policy_exception_already_allowed', text);
+            if (claimed.has(text))
+                fail('architecture_map_policy_edge_claimed_twice', text);
+            claimed.add(text);
+            return text;
+        });
+        const baseline = asCount(entry.baseline_module_edges, `${where}.baseline_module_edges`);
+        const ceiling = asCount(entry.ceiling_module_edges, `${where}.ceiling_module_edges`);
+        if (ceiling > baseline)
+            fail('architecture_map_policy_ceiling_above_baseline', where);
+        return Object.freeze({
+            id,
+            reason: asText(entry.reason, `${where}.reason`),
+            edges: Object.freeze(edges),
+            baseline_module_edges: baseline,
+            ceiling_module_edges: ceiling
+        });
+    });
+    assertDistinct(entries.map((entry) => entry.id), 'architecture_map_policy_duplicate_exception', 'exceptions.entries');
+    return Object.freeze({ mode: 'shrink-only', entries: Object.freeze(entries) });
+}
+function parseBlockingCodes(value) {
+    if (value === undefined)
+        return Object.freeze([...ARCHITECTURE_FINDING_CODES]);
+    const known = new Set(ARCHITECTURE_FINDING_CODES);
+    const codes = asArray(value, 'blockingCodes').map((entry, i) => {
+        const code = asText(entry, `blockingCodes[${i}]`);
+        if (!known.has(code))
+            fail('architecture_map_policy_unknown_blocking_code', code);
+        return code;
+    });
+    return Object.freeze(codes);
+}
+function parseViewBudgets(value) {
+    if (value === undefined)
+        return Object.freeze({});
+    const record = asRecord(value, 'viewBudgets');
+    const out = {};
+    for (const [viewId, budget] of Object.entries(record)) {
+        const row = asRecord(budget, `viewBudgets.${viewId}`);
+        out[viewId] = Object.freeze({
+            maxNodes: asCount(row.maxNodes, `viewBudgets.${viewId}.maxNodes`),
+            maxEdges: asCount(row.maxEdges, `viewBudgets.${viewId}.maxEdges`)
+        });
+    }
+    return Object.freeze(out);
+}
+function parseAccuracyFloors(value) {
+    const defaults = {
+        changedPathAccounting: 1,
+        projectionAccounting: 1,
+        protectedRelationRecall: 1,
+        eligibleExtractionSuccess: 0.995,
+        deterministicHashRuns: 3
+    };
+    if (value === undefined)
+        return Object.freeze(defaults);
+    const record = asRecord(value, 'accuracyFloors');
+    return Object.freeze({
+        changedPathAccounting: asNonNeg(record.changedPathAccounting ?? 1, 'accuracyFloors.changedPathAccounting'),
+        projectionAccounting: asNonNeg(record.projectionAccounting ?? 1, 'accuracyFloors.projectionAccounting'),
+        protectedRelationRecall: asNonNeg(record.protectedRelationRecall ?? 1, 'accuracyFloors.protectedRelationRecall'),
+        eligibleExtractionSuccess: asNonNeg(record.eligibleExtractionSuccess ?? 0.995, 'accuracyFloors.eligibleExtractionSuccess'),
+        deterministicHashRuns: asCount(record.deterministicHashRuns ?? 3, 'accuracyFloors.deterministicHashRuns')
+    });
+}
+export function parseArchitectureMapPolicy(value) {
+    const record = asRecord(value, 'policy');
+    if (record.schema !== ARCHITECTURE_MAP_POLICY_SCHEMA) {
+        fail('architecture_map_policy_schema_mismatch', String(record.schema));
+    }
+    const layers = parseLayers(record.layers);
+    const layerIds = new Set(layers.map((layer) => layer.id));
+    const boundaries = parseBoundaries(record.boundaries, layerIds);
+    const allowed = new Set(boundaries.allow.flatMap((rule) => rule.to.map((target) => `${rule.from}${LAYER_EDGE_SEPARATOR}${target}`)));
+    return Object.freeze({
+        schema: ARCHITECTURE_MAP_POLICY_SCHEMA,
+        version: typeof record.version === 'number' ? record.version : 1,
+        module_id_source: asText(record.module_id_source, 'module_id_source'),
+        layers,
+        boundaries,
+        thresholds: parseThresholds(record.thresholds),
+        profiles: parseProfiles(record.profiles),
+        absoluteTokenCeiling: asNonNeg(record.absoluteTokenCeiling ?? 3200, 'absoluteTokenCeiling'),
+        globalAtlasMaxBytes: asCount(record.globalAtlasMaxBytes ?? 1572864, 'globalAtlasMaxBytes'),
+        missionArtifactsMaxBytes: asCount(record.missionArtifactsMaxBytes ?? 358400, 'missionArtifactsMaxBytes'),
+        accuracyFloors: parseAccuracyFloors(record.accuracyFloors),
+        viewBudgets: parseViewBudgets(record.viewBudgets),
+        blockingCodes: parseBlockingCodes(record.blockingCodes),
+        exceptions: parseExceptions(record.exceptions, layerIds, allowed)
+    });
+}
+export function loadArchitectureMapPolicy(root) {
+    if (typeof root !== 'string' || !root)
+        fail('architecture_map_policy_root_missing', 'root');
+    const file = path.join(root, ...ARCHITECTURE_MAP_POLICY_FILE.split('/'));
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        fail('architecture_map_policy_unreadable', `${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch (error) {
+        fail('architecture_map_policy_invalid_json', `${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return parseArchitectureMapPolicy(json);
+}
+export function moduleLayerMap(policy) {
+    const map = new Map();
+    for (const layer of policy.layers) {
+        for (const moduleId of layer.modules)
+            map.set(moduleId, layer.id);
+    }
+    return map;
+}
+export function allowedLayerEdges(policy) {
+    const allowed = new Set();
+    for (const rule of policy.boundaries.allow) {
+        for (const target of rule.to)
+            allowed.add(`${rule.from}${LAYER_EDGE_SEPARATOR}${target}`);
+    }
+    for (const entry of policy.exceptions.entries) {
+        for (const edge of entry.edges)
+            allowed.add(edge);
+    }
+    return allowed;
+}
+export function severityForCode(policy, code) {
+    if (policy.blockingCodes.includes(code))
+        return 'blocking';
+    if (code === 'insufficient_graph')
+        return 'blocking';
+    return 'warning';
+}
+export function layerForModule(policy, moduleDir) {
+    const exact = moduleLayerMap(policy).get(moduleDir);
+    if (exact)
+        return exact;
+    let best = null;
+    for (const layer of policy.layers) {
+        for (const moduleId of layer.modules) {
+            if (moduleDir === moduleId || moduleDir.startsWith(`${moduleId}/`)) {
+                if (!best || moduleId.length > best.length)
+                    best = { id: layer.id, length: moduleId.length };
+            }
+        }
+    }
+    return best?.id ?? null;
+}
+export function isAllowedLayerEdge(policy, fromLayer, toLayer) {
+    if (fromLayer === toLayer)
+        return true;
+    return allowedLayerEdges(policy).has(`${fromLayer}${LAYER_EDGE_SEPARATOR}${toLayer}`);
+}

package/dist/core/triwiki/context-graph/architecture/slice.js

@@ -0,0 +1,100 @@
+import { byCodePoint } from './contracts.js';
+export const SELECTION_RULE_VERSION = 'architecture-slice.v1';
+function ownerIndex(nodes, edges) {
+    const modules = new Set(nodes.filter((node) => node.kind === 'module').map((node) => node.id));
+    const owner = new Map();
+    for (const edge of edges) {
+        if (edge.type !== 'contains' || !modules.has(edge.from))
+            continue;
+        if (!owner.has(edge.to))
+            owner.set(edge.to, edge.from);
+    }
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const edge of edges) {
+            if (edge.type !== 'contains' && edge.type !== 'defines')
+                continue;
+            const parent = modules.has(edge.from) ? edge.from : owner.get(edge.from);
+            if (!parent || owner.has(edge.to))
+                continue;
+            owner.set(edge.to, parent);
+            grew = true;
+        }
+    }
+    return owner;
+}
+export function buildArchitectureScope(input) {
+    return Object.freeze({
+        profile: input.profile,
+        seedNodeIds: Object.freeze([...(input.seedNodeIds ?? [])].sort(byCodePoint)),
+        seedPaths: Object.freeze([...(input.seedPaths ?? [])].sort(byCodePoint)),
+        selectionRuleVersion: SELECTION_RULE_VERSION
+    });
+}
+export function sliceArchitectureGraph(snapshot, policy, scope) {
+    const budget = policy.profiles[scope.profile] ?? policy.profiles.global;
+    const nodesById = new Map(snapshot.nodes.map((node) => [node.id, node]));
+    const owner = ownerIndex(snapshot.nodes, snapshot.edges);
+    const selected = new Set();
+    const protectedIds = new Set();
+    for (const id of scope.seedNodeIds) {
+        if (nodesById.has(id)) {
+            selected.add(id);
+            protectedIds.add(id);
+        }
+    }
+    for (const path of scope.seedPaths) {
+        for (const node of snapshot.nodes) {
+            if (node.path === path || (typeof node.metadata.dir === 'string' && node.metadata.dir === path)) {
+                selected.add(node.id);
+                protectedIds.add(node.id);
+                const moduleId = node.kind === 'module' ? node.id : owner.get(node.id);
+                if (moduleId) {
+                    selected.add(moduleId);
+                    protectedIds.add(moduleId);
+                }
+            }
+        }
+    }
+    const expandTypes = new Set(['contains', 'defines', 'imports', 'reexports', 'references']);
+    for (const edge of snapshot.edges) {
+        if (!expandTypes.has(edge.type))
+            continue;
+        if (selected.has(edge.from) || selected.has(edge.to)) {
+            selected.add(edge.from);
+            selected.add(edge.to);
+        }
+    }
+    const ranked = [...snapshot.nodes]
+        .filter((node) => node.kind === 'module' || node.risk === 'high' || node.risk === 'protected')
+        .sort((a, b) => {
+        const riskRank = (risk) => risk === 'protected' ? 3 : risk === 'high' ? 2 : risk === 'medium' ? 1 : 0;
+        return riskRank(b.risk) - riskRank(a.risk) || byCodePoint(a.id, b.id);
+    });
+    for (const node of ranked) {
+        if (selected.size >= budget.maxNodes)
+            break;
+        selected.add(node.id);
+        if (node.risk === 'protected')
+            protectedIds.add(node.id);
+    }
+    if (selected.size === 0) {
+        for (const node of snapshot.nodes.filter((n) => n.kind === 'module').sort((a, b) => byCodePoint(a.id, b.id))) {
+            if (selected.size >= budget.maxNodes)
+                break;
+            selected.add(node.id);
+        }
+    }
+    const edgeIds = snapshot.edges
+        .filter((edge) => selected.has(edge.from) && selected.has(edge.to))
+        .map((edge) => edge.id)
+        .sort(byCodePoint)
+        .slice(0, budget.maxEdges);
+    return Object.freeze({
+        scope,
+        nodeIds: Object.freeze([...selected].sort(byCodePoint)),
+        edgeIds: Object.freeze(edgeIds),
+        protectedNodeIds: Object.freeze([...protectedIds].sort(byCodePoint))
+    });
+}

package/dist/core/triwiki/context-graph/architecture/ssot-analysis.js

@@ -0,0 +1,59 @@
+import { byCodePoint } from './contracts.js';
+import { makeFinding } from './finding-factory.js';
+function severity(policy, code) {
+    return policy.blockingCodes.includes(code) ? 'blocking' : 'warning';
+}
+export function analyzeSsotCollisions(input) {
+    if (!input.inventory.length) {
+        if (!input.requireInventory)
+            return [];
+        return [
+            makeFinding({
+                code: 'insufficient_graph',
+                severity: severity(input.policy, 'insufficient_graph'),
+                subjectIds: ['ssot_inventory'],
+                evidenceIds: ['ssot_inventory:empty'],
+                ruleId: 'ssot-inventory-required',
+                message: 'SSOT inventory is empty; collision analysis cannot pass closed'
+            })
+        ];
+    }
+    const byPath = new Map();
+    for (const domain of input.inventory) {
+        for (const path of domain.canonicalSources) {
+            const owners = byPath.get(path) ?? [];
+            owners.push(domain.id);
+            byPath.set(path, owners);
+        }
+    }
+    const findings = [];
+    for (const [path, owners] of [...byPath.entries()].sort(([left], [right]) => byCodePoint(left, right))) {
+        const unique = [...new Set(owners)].sort(byCodePoint);
+        if (unique.length > 1) {
+            findings.push(makeFinding({
+                code: 'ssot_collision',
+                severity: severity(input.policy, 'ssot_collision'),
+                subjectIds: unique,
+                evidenceIds: [path],
+                ruleId: 'ssot-path-collision',
+                message: `Canonical path ${path} claimed by multiple SSOT domains: ${unique.join(', ')}`
+            }));
+        }
+    }
+    for (const domain of input.inventory) {
+        const writers = new Set(domain.allowedWriters);
+        for (const reader of domain.allowedReaders) {
+            if (writers.has(reader) && domain.canonicalSources.length === 0) {
+                findings.push(makeFinding({
+                    code: 'authority_bypass',
+                    severity: severity(input.policy, 'authority_bypass'),
+                    subjectIds: [domain.id, reader],
+                    evidenceIds: [domain.id],
+                    ruleId: 'ssot-authority-bypass',
+                    message: `SSOT domain ${domain.id} has reader/writer ${reader} without canonical sources`
+                }));
+            }
+        }
+    }
+    return findings.sort((left, right) => byCodePoint(left.id, right.id));
+}

package/dist/core/triwiki/context-graph/architecture/topology-overlay.js

@@ -0,0 +1,106 @@
+import { byCodePoint } from './contracts.js';
+import { hashCanonical } from './fingerprint.js';
+const TOPOLOGY_NODE_KINDS = new Set([
+    'command',
+    'route',
+    'pipeline',
+    'gate',
+    'schema',
+    'config'
+]);
+const TOPOLOGY_EDGE_TYPES = new Set([
+    'routes_to',
+    'depends_on',
+    'owns',
+    'gated_by',
+    'affected_by',
+    'derived_from'
+]);
+export function emptyTopologyOverlay() {
+    return Object.freeze({
+        nodes: Object.freeze([]),
+        edges: Object.freeze([]),
+        sourceManifestHashes: Object.freeze({}),
+        extractionErrors: Object.freeze([])
+    });
+}
+export function buildTopologyOverlayFromSnapshot(snapshot) {
+    const nodes = snapshot.nodes
+        .filter((node) => TOPOLOGY_NODE_KINDS.has(node.kind))
+        .slice()
+        .sort((a, b) => byCodePoint(a.id, b.id));
+    const nodeIds = new Set(nodes.map((node) => node.id));
+    const edges = snapshot.edges
+        .filter((edge) => TOPOLOGY_EDGE_TYPES.has(edge.type) &&
+        (nodeIds.has(edge.from) || nodeIds.has(edge.to) || TOPOLOGY_EDGE_TYPES.has(edge.type)))
+        .slice()
+        .sort((a, b) => byCodePoint(a.id, b.id));
+    return Object.freeze({
+        nodes: Object.freeze(nodes),
+        edges: Object.freeze(edges),
+        sourceManifestHashes: Object.freeze({
+            snapshot: snapshot.snapshotHash
+        }),
+        extractionErrors: Object.freeze([])
+    });
+}
+export function mergeTopologyOntoGraph(graph, overlay) {
+    const nodesById = new Map(graph.nodes.map((node) => [node.id, node]));
+    const issues = [...overlay.extractionErrors];
+    for (const node of overlay.nodes) {
+        const existing = nodesById.get(node.id);
+        if (!existing) {
+            nodesById.set(node.id, node);
+            continue;
+        }
+        if (existing.kind !== node.kind) {
+            const issue = typeof existing.path === 'string'
+                ? {
+                    code: 'topology_node_kind_conflict',
+                    message: `overlay kind ${node.kind} ignored for ${node.id}; code graph has ${existing.kind}`,
+                    path: existing.path
+                }
+                : {
+                    code: 'topology_node_kind_conflict',
+                    message: `overlay kind ${node.kind} ignored for ${node.id}; code graph has ${existing.kind}`
+                };
+            issues.push(issue);
+        }
+    }
+    const edgeIds = new Set(graph.edges.map((edge) => edge.id));
+    const edges = [...graph.edges];
+    for (const edge of overlay.edges) {
+        if (edgeIds.has(edge.id))
+            continue;
+        if (!nodesById.has(edge.from) || !nodesById.has(edge.to)) {
+            issues.push({
+                code: 'topology_dangling_edge',
+                message: `overlay edge ${edge.id} skipped; missing endpoint`,
+                path: edge.provenance.path
+            });
+            continue;
+        }
+        edgeIds.add(edge.id);
+        edges.push(edge);
+    }
+    return {
+        nodes: [...nodesById.values()].sort((a, b) => byCodePoint(a.id, b.id)),
+        edges: edges.sort((a, b) => byCodePoint(a.id, b.id)),
+        issues
+    };
+}
+export function mergeGraphWithTopology(graph, overlay) {
+    const merged = mergeTopologyOntoGraph(graph, overlay);
+    return {
+        nodes: Object.freeze(merged.nodes),
+        edges: Object.freeze(merged.edges)
+    };
+}
+export function topologyOverlayHash(overlay) {
+    return hashCanonical({
+        nodes: overlay.nodes.map((node) => node.id),
+        edges: overlay.edges.map((edge) => edge.id),
+        sourceManifestHashes: overlay.sourceManifestHashes,
+        extractionErrors: overlay.extractionErrors
+    });
+}