melchizedek-agents 0.9.0

package/dist/lib/wiki/entities.js

@@ -0,0 +1,661 @@
+/**
+ * lib/wiki/entities.ts — the entity layer: a typed graph over repo truth.
+ *
+ * WHY this file exists:
+ *   lib/wiki/graph.ts derives ONE graph: documents joined by markdown
+ *   links. That graph answers "what should I read next", but it cannot
+ *   answer "which syndicates call web_search", "what breaks without
+ *   XAI_API_KEY", or "which decision constrains the export pipeline" —
+ *   because the things those questions name (agents, tools, models,
+ *   tables, env vars, decisions) are not documents. They are ENTITIES,
+ *   and the relations between them are typed, not hyperlinks.
+ *
+ *   This module is that second layer, and it keeps the same discipline as
+ *   the first: nodes and edges are DERIVED from repo truth wherever a
+ *   parser can see them, and merely ASSERTED where only judgment can.
+ *   The two tiers are labelled, never mixed:
+ *
+ *     extracted — a parser read it out of a YAML, a contract, DDL, an
+ *                 import statement, a link. Rebuildable, disposable,
+ *                 always regenerated by `wiki:build --graph`.
+ *     inferred  — a human or an agent read prose and asserted it, with
+ *                 evidence and an actor id. Never machine-overwritten;
+ *                 lives in .graph/relations.json beside the snapshot.
+ *
+ *   Everything here is bundle-agnostic. WHAT to extract from (this repo's
+ *   agent YAMLs, its SQL, its package.json) is the caller's business —
+ *   scripts/wiki/build.ts does that privately. This module owns the
+ *   vocabulary, the graph mechanics, the two stores, and the lint rules,
+ *   including the same private-closure invariant the document lint
+ *   enforces (wiki/decisions/0003): a public node may never point at a
+ *   private one, so any public slice of this graph is closed by
+ *   construction.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { z } from 'zod';
+import { isPrivatePath } from "./format.js";
+// ── Node vocabulary ──────────────────────────────────────────────────────────
+/**
+ * What kinds of thing this graph knows about. A document keeps its OKF
+ * identity (the bundle path); every other node is `kind:name`, so the two
+ * namespaces can never collide — a doc id always starts with '/'.
+ */
+export const NODE_KINDS = {
+    doc: 'a concept document in the bundle — identity is its bundle path',
+    syndicate: 'one agent-team definition (a YAML)',
+    agent: 'one orchestrator or subagent inside a syndicate',
+    model: 'a model id exactly as written in configuration',
+    provider: 'a provider adapter the model registry routes to',
+    tool: 'a tool an agent may declare by name',
+    'mcp-server': 'a remote MCP endpoint an agent dials at runtime',
+    module: 'one source module',
+    file: 'a repo file that is not a source module (DDL, config, prose)',
+    table: 'a database table',
+    env: 'an environment variable the code reads',
+    script: 'an npm script entrypoint',
+    external: 'a resource outside the repo, named by URL',
+};
+export function entityId(kind, name) {
+    return kind === 'doc' ? name : `${kind}:${name}`;
+}
+export function kindOf(id) {
+    if (id.startsWith('/'))
+        return 'doc';
+    const colon = id.indexOf(':');
+    return colon === -1 ? 'unknown' : id.slice(0, colon);
+}
+export function nameOf(id) {
+    if (id.startsWith('/'))
+        return id;
+    const colon = id.indexOf(':');
+    return colon === -1 ? id : id.slice(colon + 1);
+}
+/**
+ * The whole relation vocabulary. Extracted relations carry kind
+ * constraints because a parser produces them and a violation is a bug;
+ * inferred relations do not, because judgment legitimately connects
+ * anything to anything — the evidence field is what disciplines them.
+ */
+export const RELATIONS = {
+    // ── extracted ──
+    // NOTE on constraints: `from`/`to` are declared only where a violation
+    // would mean the EXTRACTOR is wrong (a model that is not a model, a table
+    // that is not a table). The generic structural relations below are left
+    // open, because what "contains" or "runs" what differs per repo — a
+    // syndicate contains agents here, a collection contains entries on a
+    // site, a dyno runs a script on a worker.
+    contains: {
+        tier: 'extracted',
+        phrase: 'contains',
+        gloss: 'the first is composed of the second',
+    },
+    uses_model: {
+        tier: 'extracted',
+        phrase: 'runs on',
+        gloss: 'the agent is configured with this model id',
+        to: ['model'],
+    },
+    routes_to: {
+        tier: 'extracted',
+        phrase: 'routes to',
+        gloss: 'the model id resolves to this provider adapter',
+        from: ['model'],
+        to: ['provider'],
+    },
+    requires_env: {
+        tier: 'extracted',
+        phrase: 'requires',
+        gloss: 'this environment variable must be set for the node to work',
+        to: ['env'],
+    },
+    uses_tool: {
+        tier: 'extracted',
+        phrase: 'calls',
+        gloss: 'the agent declares this tool by name',
+        to: ['tool'],
+    },
+    delegates_to: {
+        tier: 'extracted',
+        phrase: 'delegates to',
+        gloss: 'the agent is a reference to another syndicate, resolved at load time',
+        from: ['agent'],
+        to: ['syndicate'],
+    },
+    connects_mcp: {
+        tier: 'extracted',
+        phrase: 'dials',
+        gloss: 'the agent discovers tools from this MCP server at runtime',
+        from: ['agent'],
+        to: ['mcp-server'],
+    },
+    defined_in: {
+        tier: 'extracted',
+        phrase: 'is defined in',
+        gloss: 'where the thing is declared in source',
+        to: ['module', 'file'],
+    },
+    imports: {
+        tier: 'extracted',
+        phrase: 'imports',
+        gloss: 'a static import edge between source files',
+    },
+    reads_table: {
+        tier: 'extracted',
+        phrase: 'reads or writes',
+        gloss: 'the module names this table',
+        to: ['table'],
+    },
+    runs: {
+        tier: 'extracted',
+        phrase: 'runs',
+        gloss: 'an entrypoint — a script, a process, a dyno — executes this',
+    },
+    documents: {
+        tier: 'extracted',
+        phrase: 'documents',
+        gloss: 'the document derives from, and describes, this entity',
+        from: ['doc'],
+    },
+    derives_from: {
+        tier: 'extracted',
+        phrase: 'derives from',
+        gloss: 'declared in the document’s `sources:` frontmatter',
+        from: ['doc'],
+    },
+    references: {
+        tier: 'extracted',
+        phrase: 'points readers at',
+        gloss: 'the source names this resource for the reader to open',
+    },
+    links_to: {
+        tier: 'extracted',
+        phrase: 'links to',
+        gloss: 'a resolved markdown link between documents',
+        from: ['doc'],
+        to: ['doc'],
+    },
+    // ── inferred ──
+    depends_on: {
+        tier: 'inferred',
+        phrase: 'depends on',
+        gloss: 'the first cannot do its job unless the second holds',
+    },
+    constrains: {
+        tier: 'inferred',
+        phrase: 'constrains',
+        gloss: 'a decision or doctrine limits what the target may do',
+    },
+    supersedes: {
+        tier: 'inferred',
+        phrase: 'supersedes',
+        gloss: 'replaces an earlier decision or document',
+    },
+    explains: {
+        tier: 'inferred',
+        phrase: 'explains',
+        gloss: 'the document is where the target’s rationale is written down',
+    },
+    alternative_to: {
+        tier: 'inferred',
+        phrase: 'is an alternative to',
+        gloss: 'two ways of reaching the same capability',
+    },
+    mitigates: {
+        tier: 'inferred',
+        phrase: 'mitigates',
+        gloss: 'the mechanism exists to contain the named failure',
+    },
+    contradicts: {
+        tier: 'inferred',
+        phrase: 'contradicts',
+        gloss: 'two sources state incompatible things — a rot signal',
+    },
+};
+export function relationsByTier(tier) {
+    return Object.entries(RELATIONS)
+        .filter(([, spec]) => spec.tier === tier)
+        .map(([id]) => id)
+        .sort();
+}
+export function edgeKey(edge) {
+    return `${edge.from}|${edge.rel}|${edge.to}`;
+}
+/** Merge two records of the same node; private-ness is sticky (once, always). */
+function mergeNode(a, b) {
+    return {
+        ...a,
+        ...b,
+        private: a.private || b.private || undefined,
+        attrs: { ...(a.attrs ?? {}), ...(b.attrs ?? {}) },
+    };
+}
+export function buildEntityGraph(nodes, edges) {
+    const nodeMap = new Map();
+    for (const node of nodes) {
+        const existing = nodeMap.get(node.id);
+        nodeMap.set(node.id, existing ? mergeNode(existing, node) : node);
+    }
+    const seen = new Set();
+    const deduped = [];
+    for (const edge of edges) {
+        const key = edgeKey(edge);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        deduped.push(edge);
+    }
+    const outbound = new Map();
+    const inbound = new Map();
+    for (const edge of deduped) {
+        (outbound.get(edge.from) ?? outbound.set(edge.from, []).get(edge.from)).push(edge);
+        (inbound.get(edge.to) ?? inbound.set(edge.to, []).get(edge.to)).push(edge);
+    }
+    return { nodes: nodeMap, edges: deduped, outbound, inbound };
+}
+/** The document layer, restated as entities so both layers share one graph. */
+export function docLayer(docGraph) {
+    const nodes = [];
+    for (const node of docGraph.nodes.values()) {
+        if (node.kind !== 'concept')
+            continue;
+        nodes.push({
+            id: node.path,
+            kind: 'doc',
+            label: node.title,
+            source: node.path,
+            ...(node.isPrivate ? { private: true } : {}),
+            attrs: {
+                type: node.type,
+                status: node.status,
+                trust: node.trust,
+                words: node.wordCount,
+            },
+        });
+    }
+    const docIds = new Set(nodes.map((n) => n.id));
+    const edges = docGraph.edges
+        .filter((e) => e.resolved && docIds.has(e.source) && docIds.has(e.target))
+        .map((e) => ({
+        from: e.source,
+        to: e.target,
+        rel: 'links_to',
+        tier: 'extracted',
+        evidence: `${e.source}:${e.line}`,
+    }));
+    return { nodes, edges };
+}
+export function neighbors(graph, originId, options = {}) {
+    const depth = options.depth ?? 1;
+    const direction = options.direction ?? 'both';
+    const allowed = options.relations && options.relations.length > 0
+        ? new Set(options.relations)
+        : null;
+    // Two different bookkeepings, deliberately: EDGES are reported once each
+    // (so two relations between the same pair both show — a document that
+    // derives_from a module AND constrains it says two things), while NODES
+    // are expanded once (so the walk terminates).
+    const reported = new Set();
+    const expanded = new Set([originId]);
+    const result = [];
+    let frontier = [originId];
+    for (let d = 1; d <= depth; d++) {
+        const next = [];
+        for (const id of frontier) {
+            const candidates = [];
+            if (direction !== 'in') {
+                for (const e of graph.outbound.get(id) ?? []) {
+                    candidates.push({ edge: e, other: e.to, dir: 'out' });
+                }
+            }
+            if (direction !== 'out') {
+                for (const e of graph.inbound.get(id) ?? []) {
+                    candidates.push({ edge: e, other: e.from, dir: 'in' });
+                }
+            }
+            for (const c of candidates) {
+                if (allowed && !allowed.has(c.edge.rel))
+                    continue;
+                // Keyed by the EDGE, not the direction: walking the same edge back
+                // from the other end is not a second fact.
+                const key = edgeKey(c.edge);
+                if (reported.has(key))
+                    continue;
+                const node = graph.nodes.get(c.other);
+                if (!node)
+                    continue;
+                reported.add(key);
+                result.push({
+                    node,
+                    rel: c.edge.rel,
+                    direction: c.dir,
+                    distance: d,
+                    via: id,
+                    ...(c.edge.evidence ? { evidence: c.edge.evidence } : {}),
+                    tier: c.edge.tier,
+                });
+                if (!expanded.has(c.other)) {
+                    expanded.add(c.other);
+                    next.push(c.other);
+                }
+            }
+        }
+        frontier = next;
+    }
+    return result;
+}
+/** Shortest connection between two nodes, walking edges in either direction. */
+export function shortestPath(graph, fromId, toId, maxDepth = 6) {
+    if (!graph.nodes.has(fromId) || !graph.nodes.has(toId))
+        return null;
+    if (fromId === toId) {
+        return [{ node: graph.nodes.get(fromId), rel: '', direction: 'origin' }];
+    }
+    const prev = new Map();
+    const seen = new Set([fromId]);
+    let frontier = [fromId];
+    for (let d = 0; d < maxDepth && frontier.length > 0; d++) {
+        const next = [];
+        for (const id of frontier) {
+            const moves = [
+                ...(graph.outbound.get(id) ?? []).map((e) => ({
+                    other: e.to,
+                    rel: e.rel,
+                    dir: 'out',
+                })),
+                ...(graph.inbound.get(id) ?? []).map((e) => ({
+                    other: e.from,
+                    rel: e.rel,
+                    dir: 'in',
+                })),
+            ];
+            for (const move of moves) {
+                if (seen.has(move.other))
+                    continue;
+                seen.add(move.other);
+                prev.set(move.other, { id, rel: move.rel, dir: move.dir });
+                if (move.other === toId) {
+                    const chain = [];
+                    let cursor = toId;
+                    while (cursor !== fromId) {
+                        const step = prev.get(cursor);
+                        chain.unshift({
+                            node: graph.nodes.get(cursor),
+                            rel: step.rel,
+                            direction: step.dir,
+                        });
+                        cursor = step.id;
+                    }
+                    chain.unshift({
+                        node: graph.nodes.get(fromId),
+                        rel: '',
+                        direction: 'origin',
+                    });
+                    return chain;
+                }
+                next.push(move.other);
+            }
+        }
+        frontier = next;
+    }
+    return null;
+}
+/** Lexical node lookup: exact id, then id/label substring, then attrs. */
+export function findNodes(graph, query, limit = 10) {
+    const q = query.trim().toLowerCase();
+    if (q === '')
+        return [];
+    const matches = [];
+    for (const node of graph.nodes.values()) {
+        const id = node.id.toLowerCase();
+        const label = node.label.toLowerCase();
+        let score = 0;
+        if (id === q)
+            score = 100;
+        else if (label === q)
+            score = 90;
+        else if (nameOf(node.id).toLowerCase() === q)
+            score = 80;
+        else if (id.includes(q))
+            score = 40;
+        else if (label.includes(q))
+            score = 30;
+        else if ((node.source ?? '').toLowerCase().includes(q))
+            score = 10;
+        if (score > 0)
+            matches.push({ node, score });
+    }
+    return matches
+        .sort((a, b) => b.score - a.score || a.node.id.localeCompare(b.node.id))
+        .slice(0, limit);
+}
+export function nodesOfKind(graph, kind) {
+    return [...graph.nodes.values()]
+        .filter((n) => n.kind === kind)
+        .sort((a, b) => a.id.localeCompare(b.id));
+}
+export function entityStats(graph) {
+    const byKind = {};
+    const byRelation = {};
+    const byTier = { extracted: 0, inferred: 0 };
+    let isolated = 0;
+    for (const node of graph.nodes.values()) {
+        byKind[node.kind] = (byKind[node.kind] ?? 0) + 1;
+        const degree = (graph.outbound.get(node.id)?.length ?? 0) + (graph.inbound.get(node.id)?.length ?? 0);
+        if (degree === 0)
+            isolated++;
+    }
+    for (const edge of graph.edges) {
+        byRelation[edge.rel] = (byRelation[edge.rel] ?? 0) + 1;
+        byTier[edge.tier]++;
+    }
+    return { nodes: graph.nodes.size, edges: graph.edges.length, byKind, byRelation, byTier, isolated };
+}
+/** True for nodes that must never be referenced from a public one. */
+export function isPrivateNode(node) {
+    return node.private === true || (node.kind === 'doc' && isPrivatePath(node.id));
+}
+export function lintEntityGraph(graph) {
+    const findings = [];
+    for (const edge of graph.edges) {
+        const spec = RELATIONS[edge.rel];
+        const from = graph.nodes.get(edge.from);
+        const to = graph.nodes.get(edge.to);
+        if (!from || !to) {
+            findings.push({
+                severity: 'error',
+                rule: 'dangling-endpoint',
+                message: `${edge.from} —${edge.rel}→ ${edge.to}: ${!from ? edge.from : edge.to} is not a node in the graph`,
+            });
+            continue;
+        }
+        if (!spec) {
+            findings.push({
+                severity: 'info',
+                rule: 'unknown-relation',
+                message: `${edge.from} —${edge.rel}→ ${edge.to}: "${edge.rel}" is outside the vocabulary`,
+            });
+        }
+        else {
+            if (spec.tier !== edge.tier) {
+                findings.push({
+                    severity: 'warning',
+                    rule: 'tier-mismatch',
+                    message: `${edgeKey(edge)} is tagged ${edge.tier} but "${edge.rel}" is an ${spec.tier} relation`,
+                });
+            }
+            if (spec.from && spec.from.length > 0 && !spec.from.includes(from.kind)) {
+                findings.push({
+                    severity: 'warning',
+                    rule: 'kind-constraint',
+                    message: `${edgeKey(edge)}: "${edge.rel}" starts at ${spec.from.join('|')}, not ${from.kind}`,
+                });
+            }
+            if (spec.to && spec.to.length > 0 && !spec.to.includes(to.kind)) {
+                findings.push({
+                    severity: 'warning',
+                    rule: 'kind-constraint',
+                    message: `${edgeKey(edge)}: "${edge.rel}" points at ${spec.to.join('|')}, not ${to.kind}`,
+                });
+            }
+        }
+        if (edge.tier === 'inferred' && !edge.by) {
+            findings.push({
+                severity: 'warning',
+                rule: 'unattributed-assertion',
+                message: `${edgeKey(edge)} is inferred but names no actor`,
+            });
+        }
+        // The closure rule mirrors the DOCUMENT invariant exactly: what gets
+        // published is the bundle, so a public DOCUMENT may never point into
+        // private knowledge. Code-to-code edges are out of scope here — a
+        // public module importing a private one is a real fact of this repo,
+        // sanitized by the export pipeline's patches, not by this graph.
+        if (from.kind === 'doc' && !isPrivateNode(from) && isPrivateNode(to)) {
+            findings.push({
+                severity: 'error',
+                rule: 'private-closure',
+                message: `${edgeKey(edge)}: a public document may not point at the private annex`,
+            });
+        }
+        if (edge.from === edge.to) {
+            findings.push({
+                severity: 'warning',
+                rule: 'self-loop',
+                message: `${edge.from} —${edge.rel}→ itself`,
+            });
+        }
+    }
+    return findings;
+}
+// ── Stores ───────────────────────────────────────────────────────────────────
+/**
+ * Both stores live in a dot-directory inside the bundle: the vault walker
+ * skips dotfiles, so they are invisible to every document operation, they
+ * travel with WIKI_ROOT, and the export pipeline (which copies *.md only)
+ * cannot ship them by accident.
+ */
+export function graphDir(wikiRoot) {
+    return join(wikiRoot, '.graph');
+}
+export function snapshotPath(wikiRoot) {
+    return join(graphDir(wikiRoot), 'graph.json');
+}
+export function relationsPath(wikiRoot) {
+    return join(graphDir(wikiRoot), 'relations.json');
+}
+export const relationRecordSchema = z.looseObject({
+    from: z.string().min(1),
+    to: z.string().min(1),
+    rel: z.string().min(1),
+    /** What was read to justify this — a quotation or a path. */
+    evidence: z.string().min(3),
+    by: z.string().min(1),
+    at: z.string().optional(),
+    note: z.string().optional(),
+});
+export const relationStoreSchema = z.looseObject({
+    version: z.number().int().default(1),
+    relations: z.array(relationRecordSchema).default([]),
+});
+export function loadRelations(wikiRoot) {
+    const file = relationsPath(wikiRoot);
+    if (!existsSync(file))
+        return { records: [], issues: [] };
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(file, 'utf-8'));
+    }
+    catch (err) {
+        return {
+            records: [],
+            issues: [`relations.json does not parse: ${err instanceof Error ? err.message : String(err)}`],
+        };
+    }
+    const parsed = relationStoreSchema.safeParse(raw);
+    if (!parsed.success) {
+        return {
+            records: [],
+            issues: parsed.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`),
+        };
+    }
+    const records = [];
+    const issues = [];
+    const seen = new Set();
+    for (const [index, record] of parsed.data.relations.entries()) {
+        const key = edgeKey(record);
+        if (seen.has(key)) {
+            issues.push(`relations[${index}]: duplicate assertion ${key}`);
+            continue;
+        }
+        seen.add(key);
+        records.push(record);
+    }
+    return { records, issues };
+}
+export function relationEdges(records) {
+    return records.map((r) => ({
+        from: r.from,
+        to: r.to,
+        rel: r.rel,
+        tier: 'inferred',
+        evidence: r.evidence,
+        by: r.by,
+        ...(r.at ? { at: r.at } : {}),
+    }));
+}
+export function saveRelations(wikiRoot, records) {
+    const file = relationsPath(wikiRoot);
+    mkdirSync(dirname(file), { recursive: true });
+    const sorted = [...records].sort((a, b) => a.from.localeCompare(b.from) || a.rel.localeCompare(b.rel) || a.to.localeCompare(b.to));
+    writeFileSync(file, `${JSON.stringify({ version: 1, relations: sorted }, null, 2)}\n`, 'utf-8');
+}
+export function writeSnapshot(wikiRoot, graph, generated) {
+    const file = snapshotPath(wikiRoot);
+    mkdirSync(dirname(file), { recursive: true });
+    const snapshot = {
+        version: 1,
+        generated,
+        stats: entityStats(graph),
+        nodes: [...graph.nodes.values()].sort((a, b) => a.id.localeCompare(b.id)),
+        edges: graph.edges
+            .filter((e) => e.tier === 'extracted')
+            .sort((a, b) => edgeKey(a).localeCompare(edgeKey(b))),
+    };
+    writeFileSync(file, `${JSON.stringify(snapshot, null, 2)}\n`, 'utf-8');
+    return file;
+}
+export function readSnapshot(wikiRoot) {
+    const file = snapshotPath(wikiRoot);
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The read path every consumer uses: derived snapshot (structure, as of the
+ * last build) + asserted relations (read live, so a fresh assertion is
+ * visible immediately). Missing snapshot yields an empty graph plus the
+ * asserted edges, which lint will flag as dangling — honest, not silent.
+ */
+export function loadEntityGraph(wikiRoot) {
+    const snapshot = readSnapshot(wikiRoot);
+    const { records, issues } = loadRelations(wikiRoot);
+    const graph = buildEntityGraph(snapshot?.nodes ?? [], [...(snapshot?.edges ?? []), ...relationEdges(records)]);
+    return { graph, snapshot, issues, inferredCount: records.length };
+}
+/** Documents the snapshot has not seen yet — the staleness signal. */
+export function snapshotDrift(snapshot, currentDocPaths) {
+    if (!snapshot)
+        return { missing: [...currentDocPaths].sort(), removed: [] };
+    const known = new Set(snapshot.nodes.filter((n) => n.kind === 'doc').map((n) => n.id));
+    const current = new Set(currentDocPaths);
+    return {
+        missing: [...current].filter((p) => !known.has(p)).sort(),
+        removed: [...known].filter((p) => !current.has(p)).sort(),
+    };
+}