@zergai/ztc 0.2.2-dev.35680553693 → 0.2.2-dev.35681806994

package/node_modules/@ztc/sim-graph/dist/sim_graph.js

@@ -1,795 +0,0 @@
-/**
- * SimGraph — FalkorDB Graph Backbone for Simulation
- *
- * Property graph storing entities, temporal facts, relationships,
- * feed posts, and events. Replaces flat in-memory stores with
- * structured, queryable graph data.
- *
- * Inspired by MiroFish/Graphiti's temporal knowledge graph but
- * implemented natively in TypeScript with FalkorDBLite (embedded,
- * no Docker, no Python).
- */
-export function recordSimulationFact(input) {
-    const graph = normalizeSimulationFactGraph(input.graph);
-    const fact = normalizeSimulationGraphFact(input.fact);
-    const existingFacts = graph.facts.filter((item) => item.id !== fact.id);
-    const supersedesEdges = uniqueText(input.fact.supersedesIds ?? [])
-        .filter((targetId) => targetId !== fact.id)
-        .map((targetId) => ({
-        sourceId: fact.id,
-        targetId,
-        type: 'supersedes',
-        tick: fact.validFrom,
-        data: {
-            sourceEventId: fact.sourceEventId,
-        },
-    }));
-    return {
-        schemaVersion: 1,
-        facts: [...existingFacts, fact],
-        edges: dedupeSimulationEdges([...graph.edges, ...supersedesEdges]),
-    };
-}
-export function projectActiveFacts(input) {
-    const graph = normalizeSimulationFactGraph(input.graph);
-    const atTick = finiteNumber(input.atTick, Number.POSITIVE_INFINITY);
-    const subjectIds = new Set(uniqueText(input.subjectIds ?? []));
-    const predicates = new Set(uniqueText(input.predicates ?? []));
-    const supersededIds = new Set(graph.edges
-        .filter((edge) => edge.type === 'supersedes' && edge.tick <= atTick)
-        .map((edge) => edge.targetId));
-    return graph.facts
-        .filter((fact) => fact.validFrom <= atTick)
-        .filter((fact) => fact.invalidAt === null || fact.invalidAt > atTick)
-        .filter((fact) => !supersededIds.has(fact.id))
-        .filter((fact) => subjectIds.size === 0 || subjectIds.has(fact.subjectId))
-        .filter((fact) => predicates.size === 0 || predicates.has(fact.predicate))
-        .sort((a, b) => {
-        if (a.validFrom !== b.validFrom)
-            return a.validFrom - b.validFrom;
-        return a.id.localeCompare(b.id);
-    });
-}
-export function traverseSimulationNeighborhood(input) {
-    const graph = normalizeSimulationFactGraph(input.graph);
-    const factById = new Map(graph.facts.map((fact) => [fact.id, fact]));
-    const maxDepth = Math.max(0, Math.floor(finiteNumber(input.maxDepth, 1)));
-    const allowedEdgeTypes = new Set(uniqueText(input.edgeTypes ?? []));
-    const eligibleEdges = graph.edges.filter((edge) => (allowedEdgeTypes.size === 0 || allowedEdgeTypes.has(edge.type)));
-    const depthByFactId = {};
-    const factIds = [];
-    const selectedEdges = [];
-    const queue = [];
-    for (const id of uniqueText(input.startIds)) {
-        if (!factById.has(id) || depthByFactId[id] !== undefined)
-            continue;
-        depthByFactId[id] = 0;
-        factIds.push(id);
-        queue.push({ id, depth: 0 });
-    }
-    while (queue.length > 0) {
-        const current = queue.shift();
-        if (current.depth >= maxDepth)
-            continue;
-        for (const edge of eligibleEdges) {
-            const neighborId = edge.sourceId === current.id
-                ? edge.targetId
-                : edge.targetId === current.id
-                    ? edge.sourceId
-                    : '';
-            if (!neighborId || !factById.has(neighborId))
-                continue;
-            addUniqueSimulationEdge(selectedEdges, edge);
-            if (depthByFactId[neighborId] !== undefined)
-                continue;
-            depthByFactId[neighborId] = current.depth + 1;
-            factIds.push(neighborId);
-            queue.push({ id: neighborId, depth: current.depth + 1 });
-        }
-    }
-    return {
-        schemaVersion: 1,
-        factIds,
-        facts: factIds.map((id) => factById.get(id)).filter((fact) => fact !== undefined),
-        edges: selectedEdges.filter((edge) => (depthByFactId[edge.sourceId] !== undefined &&
-            depthByFactId[edge.targetId] !== undefined)),
-        depthByFactId,
-    };
-}
-export function buildSimulationFocusGraphContext(input) {
-    const focusIds = uniqueText(input.focusIds ?? [])
-        .slice(0, Math.max(0, Math.floor(finiteNumber(input.maxFocusIds, 20))));
-    const nodes = new Map((input.nodes ?? [])
-        .map((node) => normalizeFocusGraphNode(node))
-        .filter((node) => node.id)
-        .map((node) => [node.id, node]));
-    const edges = (input.edges ?? [])
-        .map((edge) => normalizeFocusGraphEdge(edge))
-        .filter((edge) => edge.sourceId && edge.targetId && edge.type);
-    return {
-        version: 1,
-        focusIds,
-        lineages: input.lineage
-            ? focusIds.map((focusId) => buildSimulationFocusLineage(focusId, nodes, edges, input.lineage))
-            : [],
-        relationGroups: (input.relations ?? []).flatMap((relation) => (focusIds.map((focusId) => buildSimulationFocusRelationGroup(focusId, edges, relation)))),
-    };
-}
-export function buildSimulationSteeringInfluenceGraph(input) {
-    const events = (input.steeringEvents ?? [])
-        .map((event) => normalizeSteeringEvent(event))
-        .filter((event) => event.id);
-    const tasks = (input.tasks ?? [])
-        .map((task) => normalizeSteeringTask(task))
-        .filter((task) => task.id);
-    const outputs = (input.outputs ?? [])
-        .map((output) => normalizeSteeringOutput(output))
-        .filter((output) => output.id && output.taskId);
-    const ignoreVerdictKinds = new Set(uniqueText(input.ignoreVerdictKinds ?? ['hypothesis_submitted']));
-    const taskEdges = [];
-    const outputEdges = [];
-    for (const event of events) {
-        for (const task of tasks) {
-            for (const signal of task.signals ?? []) {
-                if (!steeringSignalMatchesEvent(event, task, signal, ignoreVerdictKinds))
-                    continue;
-                const taskEdge = steeringTaskEdge(event, task, signal);
-                addUniqueSteeringInfluenceEdge(taskEdges, taskEdge);
-                for (const output of outputs.filter((candidate) => candidate.taskId === task.id)) {
-                    addUniqueSteeringInfluenceEdge(outputEdges, steeringOutputEdge(event, task, signal, output));
-                }
-            }
-        }
-    }
-    return {
-        version: 1,
-        taskEdges,
-        outputEdges,
-    };
-}
-export function buildSimulationRestartMemory(input) {
-    const activeFacts = Array.isArray(input.activeFacts) ? [...input.activeFacts] : [];
-    const graphStats = input.graphStats ?? {};
-    const maxFocusIds = Math.max(0, Math.floor(finiteNumber(input.maxFocusIds, 20)));
-    return {
-        version: 1,
-        runId: textValue(input.runId),
-        focusIds: uniqueText(input.focusIds ?? []).slice(0, maxFocusIds),
-        activeFacts,
-        graphStats: {
-            nodes: wholeNumber(graphStats.nodes, 0),
-            edges: wholeNumber(graphStats.edges, 0),
-            activeFactCount: wholeNumber(graphStats.activeFactCount, activeFacts.length),
-        },
-    };
-}
-function steeringTaskEdge(event, task, signal) {
-    return {
-        sourceId: event.id,
-        targetId: task.id,
-        type: 'steering_influenced_task',
-        createdAt: textValue(task.createdAt),
-        data: steeringInfluenceData(task, signal),
-    };
-}
-function steeringOutputEdge(event, task, signal, output) {
-    const { priority: _priority, ...influenceData } = steeringInfluenceData(task, signal);
-    return {
-        sourceId: event.id,
-        targetId: output.id,
-        type: 'steering_influenced_output',
-        createdAt: textValue(output.createdAt),
-        data: {
-            ...influenceData,
-            ...(textValue(output.outputType) ? { outputType: textValue(output.outputType) } : {}),
-            ...(isRecord(output.data) ? { ...output.data } : {}),
-        },
-    };
-}
-function steeringInfluenceData(task, signal) {
-    return {
-        taskId: task.id,
-        taskType: textValue(task.taskType),
-        source: textValue(task.source),
-        steeringKind: textValue(signal.kind),
-        subjectId: textValue(signal.subjectId),
-        verdict: textValue(signal.verdict),
-        selectionStatus: textValue(signal.selectionStatus),
-        priority: finiteNumber(signal.priority, 0),
-    };
-}
-function steeringSignalMatchesEvent(event, task, signal, ignoreVerdictKinds) {
-    const eventTime = Date.parse(textValue(event.createdAt));
-    const taskTime = Date.parse(textValue(task.createdAt));
-    if (Number.isFinite(eventTime) && Number.isFinite(taskTime) && taskTime < eventTime)
-        return false;
-    const signalKind = textValue(signal.kind);
-    const acceptedKinds = new Set(uniqueText(event.acceptedSignalKinds ?? []));
-    if (acceptedKinds.size > 0 && !acceptedKinds.has(signalKind))
-        return false;
-    if (!matchingTextWhenBothPresent(event.subjectId, signal.subjectId))
-        return false;
-    if (!ignoreVerdictKinds.has(signalKind) && !matchingTextWhenBothPresent(event.verdict, signal.verdict))
-        return false;
-    if (!matchingTextWhenBothPresent(event.selectionStatus, signal.selectionStatus))
-        return false;
-    return true;
-}
-function matchingTextWhenBothPresent(left, right) {
-    const leftText = textValue(left);
-    const rightText = textValue(right);
-    return !leftText || !rightText || leftText === rightText;
-}
-function addUniqueSteeringInfluenceEdge(edges, edge) {
-    const key = `${edge.sourceId}\0${edge.targetId}\0${edge.type}`;
-    if (edges.some((candidate) => `${candidate.sourceId}\0${candidate.targetId}\0${candidate.type}` === key)) {
-        return;
-    }
-    edges.push(edge);
-}
-function normalizeSteeringEvent(event) {
-    return {
-        id: textValue(event.id),
-        eventType: textValue(event.eventType),
-        acceptedSignalKinds: uniqueText(event.acceptedSignalKinds ?? []),
-        subjectId: textValue(event.subjectId),
-        verdict: textValue(event.verdict),
-        selectionStatus: textValue(event.selectionStatus),
-        createdAt: textValue(event.createdAt),
-        data: isRecord(event.data) ? { ...event.data } : {},
-    };
-}
-function normalizeSteeringTask(task) {
-    return {
-        id: textValue(task.id),
-        taskType: textValue(task.taskType),
-        source: textValue(task.source),
-        createdAt: textValue(task.createdAt),
-        signals: (task.signals ?? []).map((signal) => normalizeSteeringSignal(signal)),
-    };
-}
-function normalizeSteeringSignal(signal) {
-    return {
-        kind: textValue(signal.kind),
-        subjectId: textValue(signal.subjectId),
-        verdict: textValue(signal.verdict),
-        selectionStatus: textValue(signal.selectionStatus),
-        priority: finiteNumber(signal.priority, 0),
-        data: isRecord(signal.data) ? { ...signal.data } : {},
-    };
-}
-function normalizeSteeringOutput(output) {
-    return {
-        id: textValue(output.id),
-        taskId: textValue(output.taskId),
-        outputType: textValue(output.outputType),
-        createdAt: textValue(output.createdAt),
-        data: isRecord(output.data) ? { ...output.data } : {},
-    };
-}
-function buildSimulationFocusLineage(focusId, nodes, edges, lineage) {
-    const edgeTypes = new Set(uniqueText(lineage.edgeTypes));
-    const direction = lineage.direction ?? 'out';
-    const maxDepth = Math.max(0, Math.floor(finiteNumber(lineage.maxDepth, 12)));
-    const pathIds = [];
-    const pathEdges = [];
-    const visited = new Set();
-    let currentId = focusId;
-    for (let depth = 0; currentId && !visited.has(currentId) && depth <= maxDepth; depth++) {
-        visited.add(currentId);
-        if (nodes.has(currentId))
-            pathIds.push(currentId);
-        const nextEdge = edges.find((edge) => (edgeTypes.has(edge.type) &&
-            (direction === 'out' ? edge.sourceId === currentId : edge.targetId === currentId)));
-        if (!nextEdge)
-            break;
-        pathEdges.push(nextEdge);
-        currentId = direction === 'out' ? nextEdge.targetId : nextEdge.sourceId;
-    }
-    const nodeIds = lineage.includeFocus === false
-        ? pathIds.slice(1).reverse()
-        : pathIds.reverse();
-    return {
-        focusId,
-        nodeIds,
-        edgeTypes: uniqueText(pathEdges.map((edge) => edge.type)),
-        edges: pathEdges,
-    };
-}
-function buildSimulationFocusRelationGroup(focusId, edges, relation) {
-    const edgeTypes = new Set(uniqueText(relation.edgeTypes));
-    const direction = relation.direction ?? 'both';
-    const limit = Math.max(0, Math.floor(finiteNumber(relation.limit, Number.MAX_SAFE_INTEGER)));
-    const selectedEdges = edges
-        .filter((edge) => edgeTypes.has(edge.type))
-        .filter((edge) => focusRelationEdgeMatches(edge, focusId, direction))
-        .slice(0, limit);
-    return {
-        name: textValue(relation.name),
-        focusId,
-        nodeIds: uniqueText(selectedEdges.map((edge) => focusRelationOtherNodeId(edge, focusId, direction))),
-        edges: selectedEdges,
-    };
-}
-function focusRelationEdgeMatches(edge, focusId, direction) {
-    if (direction === 'out')
-        return edge.sourceId === focusId;
-    if (direction === 'in')
-        return edge.targetId === focusId;
-    return edge.sourceId === focusId || edge.targetId === focusId;
-}
-function focusRelationOtherNodeId(edge, focusId, direction) {
-    if (direction === 'out')
-        return edge.targetId;
-    if (direction === 'in')
-        return edge.sourceId;
-    return edge.sourceId === focusId ? edge.targetId : edge.sourceId;
-}
-function normalizeFocusGraphNode(node) {
-    return {
-        id: textValue(node.id),
-        kind: textValue(node.kind),
-        label: textValue(node.label),
-        data: isRecord(node.data) ? { ...node.data } : {},
-    };
-}
-function normalizeFocusGraphEdge(edge) {
-    return {
-        sourceId: textValue(edge.sourceId),
-        targetId: textValue(edge.targetId),
-        type: textValue(edge.type),
-        createdAt: textValue(edge.createdAt),
-        data: isRecord(edge.data) ? { ...edge.data } : {},
-    };
-}
-function normalizeSimulationFactGraph(graph) {
-    return {
-        schemaVersion: 1,
-        facts: (graph?.facts ?? []).map((fact) => normalizeSimulationGraphFact(fact)),
-        edges: dedupeSimulationEdges(graph?.edges ?? []),
-    };
-}
-function normalizeSimulationGraphFact(fact) {
-    const id = textValue(fact.id);
-    if (!id) {
-        throw new Error('simulation fact id is required');
-    }
-    const subjectId = textValue(fact.subjectId);
-    if (!subjectId) {
-        throw new Error('simulation fact subject id is required');
-    }
-    const predicate = textValue(fact.predicate);
-    if (!predicate) {
-        throw new Error('simulation fact predicate is required');
-    }
-    return {
-        id,
-        subjectId,
-        predicate,
-        objectId: textValue(fact.objectId),
-        content: textValue(fact.content),
-        validFrom: finiteNumber(fact.validFrom, 0),
-        invalidAt: fact.invalidAt === null || fact.invalidAt === undefined
-            ? null
-            : finiteNumber(fact.invalidAt, 0),
-        sourceEventId: textValue(fact.sourceEventId),
-        data: isRecord(fact.data) ? { ...fact.data } : {},
-    };
-}
-function dedupeSimulationEdges(edges) {
-    const output = [];
-    for (const edge of edges) {
-        addUniqueSimulationEdge(output, {
-            sourceId: textValue(edge.sourceId),
-            targetId: textValue(edge.targetId),
-            type: textValue(edge.type),
-            tick: finiteNumber(edge.tick, 0),
-            data: isRecord(edge.data) ? { ...edge.data } : {},
-        });
-    }
-    return output;
-}
-function addUniqueSimulationEdge(output, edge) {
-    if (!edge.sourceId || !edge.targetId || !edge.type)
-        return;
-    const key = `${edge.sourceId}\0${edge.targetId}\0${edge.type}\0${edge.tick}`;
-    if (output.some((candidate) => (`${candidate.sourceId}\0${candidate.targetId}\0${candidate.type}\0${candidate.tick}` === key))) {
-        return;
-    }
-    output.push(edge);
-}
-function textValue(value) {
-    if (typeof value === 'string')
-        return value.trim();
-    if (typeof value === 'number' || typeof value === 'boolean')
-        return String(value);
-    return '';
-}
-function finiteNumber(value, fallback) {
-    const parsed = Number(value);
-    return Number.isFinite(parsed) ? parsed : fallback;
-}
-function wholeNumber(value, fallback) {
-    return Math.max(0, Math.floor(finiteNumber(value, fallback)));
-}
-function uniqueText(values) {
-    const output = [];
-    for (const value of values) {
-        const text = textValue(value);
-        if (!text || output.includes(text))
-            continue;
-        output.push(text);
-    }
-    return output;
-}
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-// ── SimGraph ──────────────────────────────────────────────────────
-export class SimGraph {
-    db;
-    graph;
-    /** Per-instance counter (review #8: avoid module-level mutable state) */
-    factCounter = 0;
-    constructor(db, graph) {
-        this.db = db;
-        this.graph = graph;
-    }
-    /**
-     * Open an embedded FalkorDB instance and select the simulation graph.
-     * If dataPath is provided, data persists to disk.
-     */
-    static async open(dataPath) {
-        const { FalkorDB } = await import('falkordblite');
-        const db = await FalkorDB.open(dataPath ? { path: dataPath, logLevel: 'warning' } : { logLevel: 'warning' });
-        const graph = db.selectGraph('sim');
-        const sg = new SimGraph(db, graph);
-        await sg.initSchema();
-        return sg;
-    }
-    /** Close the graph database and stop the embedded server. */
-    async close() {
-        await this.db.close();
-    }
-    /**
-     * Escape hatch for domain-specific adapters that want to use labels/
-     * relationships outside the built-in schema (e.g. cybersim's `:CS*`
-     * nodes). Returned shape matches FalkorDB's `graph.query` result.
-     */
-    async rawQuery(cypher, params) {
-        const result = await this.graph.query(cypher, params ? { params } : undefined);
-        return { data: result.data };
-    }
-    /**
-     * Register a range index on a node label/property pair. Safe to call
-     * for already-indexed pairs — creation errors are swallowed.
-     */
-    async ensureNodeIndex(label, property) {
-        try {
-            await this.graph.createNodeRangeIndex(label, property);
-        }
-        catch {
-            // Index may already exist — ignore
-        }
-    }
-    /** Create indices for common query patterns. */
-    async initSchema() {
-        // Node indices
-        const indices = [
-            ['Agent', 'id'], ['Fact', 'id'], ['Fact', 'category'],
-            ['FeedPost', 'id'], ['Topic', 'name'], ['Event', 'id'],
-            ['Company', 'id'],
-        ];
-        for (const [label, prop] of indices) {
-            try {
-                await this.graph.createNodeRangeIndex(label, prop);
-            }
-            catch {
-                // Index may already exist — ignore
-            }
-        }
-    }
-    // ── Entity Management ───────────────────────────────────────────
-    async addAgent(agent) {
-        await this.graph.query(`MERGE (a:Agent {id: $id})
-       SET a.name = $name, a.role = $role, a.organization = $organization, a.type = $type`, { params: { id: agent.id, name: agent.name, role: agent.role, organization: agent.organization, type: agent.type } });
-    }
-    async addCompany(company) {
-        await this.graph.query(`MERGE (c:Company {id: $id})
-       SET c.name = $name, c.industry = $industry, c.stage = $stage`, { params: { id: company.id, name: company.name, industry: company.industry, stage: company.stage } });
-    }
-    async addCompetitor(companyIdA, companyIdB) {
-        await this.graph.query(`MATCH (a:Company {id: $a}), (b:Company {id: $b})
-       MERGE (a)-[:COMPETES_WITH]->(b)
-       MERGE (b)-[:COMPETES_WITH]->(a)`, { params: { a: companyIdA, b: companyIdB } });
-    }
-    async addWorksAt(agentId, companyId) {
-        await this.graph.query(`MATCH (a:Agent {id: $agentId}), (c:Company {id: $companyId})
-       MERGE (a)-[:WORKS_AT]->(c)`, { params: { agentId, companyId } });
-    }
-    // ── Fact Management (Temporal) ──────────────────────────────────
-    /** Add a fact stated by an agent. Returns the fact ID. */
-    async addFact(agentId, content, category, tick, aboutEntityId) {
-        const factId = `fact-${++this.factCounter}`;
-        await this.graph.query(`MATCH (a:Agent {id: $agentId})
-       CREATE (f:Fact {id: $factId, content: $content, category: $category,
-                       source_tick: $tick, valid_from: $tick, invalid_at: -1})
-       CREATE (a)-[:STATED {tick: $tick}]->(f)`, { params: { agentId, factId, content, category, tick } });
-        // Link fact to entity if specified
-        if (aboutEntityId) {
-            await this.graph.query(`MATCH (f:Fact {id: $factId})
-         OPTIONAL MATCH (e:Company {id: $entityId})
-         OPTIONAL MATCH (a:Agent {id: $entityId})
-         OPTIONAL MATCH (t:Topic {name: $entityId})
-         WITH f, coalesce(e, a, t) AS target
-         WHERE target IS NOT NULL
-         CREATE (f)-[:ABOUT]->(target)`, { params: { factId, entityId: aboutEntityId } });
-        }
-        return factId;
-    }
-    /** Invalidate a fact at the given tick. */
-    async invalidateFact(factId, tick) {
-        await this.graph.query(`MATCH (f:Fact {id: $factId}) SET f.invalid_at = $tick`, { params: { factId, tick } });
-    }
-    /**
-     * Add a fact, checking for contradictions. If the same agent has
-     * a current fact in the same category about the same entity,
-     * invalidate the old fact and create a SUPERSEDES edge.
-     */
-    async addFactWithSupersede(agentId, content, category, tick, aboutEntityId) {
-        // Find existing current facts by this agent in this category
-        if (aboutEntityId) {
-            const existing = await this.graph.query(`MATCH (a:Agent {id: $agentId})-[:STATED]->(f:Fact)-[:ABOUT]->(e {id: $entityId})
-         WHERE f.category = $category AND f.invalid_at = -1
-         RETURN f.id AS id`, { params: { agentId, category, entityId: aboutEntityId } });
-            if (existing.data && existing.data.length > 0) {
-                for (const row of existing.data) {
-                    const oldId = row.id;
-                    if (oldId)
-                        await this.invalidateFact(oldId, tick);
-                }
-            }
-        }
-        const newFactId = await this.addFact(agentId, content, category, tick, aboutEntityId);
-        // Create SUPERSEDES edges
-        if (aboutEntityId) {
-            await this.graph.query(`MATCH (newF:Fact {id: $newId})
-         MATCH (a:Agent {id: $agentId})-[:STATED]->(oldF:Fact)-[:ABOUT]->(e {id: $entityId})
-         WHERE oldF.category = $category AND oldF.invalid_at = $tick AND oldF.id <> $newId
-         MERGE (newF)-[:SUPERSEDES]->(oldF)`, { params: { newId: newFactId, agentId, category, entityId: aboutEntityId, tick } });
-        }
-        return newFactId;
-    }
-    // ── Fact Queries ────────────────────────────────────────────────
-    /** Get all facts stated by an agent. */
-    async getAgentFacts(agentId, currentOnly = true) {
-        const whereClause = currentOnly ? 'AND f.invalid_at = -1' : '';
-        const result = await this.graph.query(`MATCH (a:Agent {id: $agentId})-[:STATED]->(f:Fact)
-       WHERE 1=1 ${whereClause}
-       RETURN f.id AS id, f.content AS content, f.category AS category,
-              f.source_tick AS sourceTick, f.valid_from AS validFrom, f.invalid_at AS invalidAt
-       ORDER BY f.source_tick DESC`, { params: { agentId } });
-        return this.parseFactRows(result.data);
-    }
-    /** Get all facts about an entity. */
-    async getFactsAbout(entityId, currentOnly = true) {
-        const whereClause = currentOnly ? 'AND f.invalid_at = -1' : '';
-        const result = await this.graph.query(`MATCH (f:Fact)-[:ABOUT]->(e {id: $entityId})
-       WHERE 1=1 ${whereClause}
-       RETURN f.id AS id, f.content AS content, f.category AS category,
-              f.source_tick AS sourceTick, f.valid_from AS validFrom, f.invalid_at AS invalidAt
-       ORDER BY f.source_tick DESC`, { params: { entityId } });
-        return this.parseFactRows(result.data);
-    }
-    /** Get facts matching a keyword in content. */
-    async getFactsByKeyword(keyword, currentOnly = true) {
-        const whereClause = currentOnly ? 'AND f.invalid_at = -1' : '';
-        const result = await this.graph.query(`MATCH (f:Fact)
-       WHERE f.content CONTAINS $keyword ${whereClause}
-       RETURN f.id AS id, f.content AS content, f.category AS category,
-              f.source_tick AS sourceTick, f.valid_from AS validFrom, f.invalid_at AS invalidAt
-       ORDER BY f.source_tick DESC
-       LIMIT 20`, { params: { keyword } });
-        return this.parseFactRows(result.data);
-    }
-    // ── Relationship Management ─────────────────────────────────────
-    async setRelationship(agentIdA, agentIdB, sentiment, trust, interactionCount, note) {
-        await this.graph.query(`MATCH (a:Agent {id: $a}), (b:Agent {id: $b})
-       MERGE (a)-[r:KNOWS]->(b)
-       SET r.sentiment = $sentiment, r.trust = $trust,
-           r.interaction_count = $interactionCount,
-           r.last_note = $note`, { params: { a: agentIdA, b: agentIdB, sentiment, trust, interactionCount, note: note ?? '' } });
-    }
-    /** Review #12: Query both directions for KNOWS relationship. */
-    async getRelationship(agentIdA, agentIdB) {
-        const result = await this.graph.query(`MATCH (a:Agent {id: $a})-[r:KNOWS]-(b:Agent {id: $b})
-       RETURN a.id AS agentIdA, b.id AS agentIdB, a.name AS nameA, b.name AS nameB,
-              r.sentiment AS sentiment, r.trust AS trust,
-              r.interaction_count AS interactionCount, r.last_note AS lastNote
-       LIMIT 1`, { params: { a: agentIdA, b: agentIdB } });
-        if (!result.data || result.data.length === 0)
-            return null;
-        const row = result.data[0];
-        return {
-            agentIdA: String(row.agentIdA),
-            agentIdB: String(row.agentIdB),
-            nameA: String(row.nameA),
-            nameB: String(row.nameB),
-            sentiment: Number(row.sentiment ?? 0),
-            trust: Number(row.trust ?? 0),
-            interactionCount: Number(row.interactionCount ?? 0),
-            lastNote: row.lastNote ? String(row.lastNote) : null,
-        };
-    }
-    async getRelationshipsFor(agentId) {
-        // Review #12: Query both directions
-        const result = await this.graph.query(`MATCH (a:Agent {id: $id})-[r:KNOWS]-(b:Agent)
-       RETURN a.id AS agentIdA, b.id AS agentIdB, a.name AS nameA, b.name AS nameB,
-              r.sentiment AS sentiment, r.trust AS trust,
-              r.interaction_count AS interactionCount, r.last_note AS lastNote
-       ORDER BY r.interaction_count DESC`, { params: { id: agentId } });
-        return (result.data ?? []).map((row) => {
-            const r = row;
-            return {
-                agentIdA: String(r.agentIdA),
-                agentIdB: String(r.agentIdB),
-                nameA: String(r.nameA),
-                nameB: String(r.nameB),
-                sentiment: Number(r.sentiment ?? 0),
-                trust: Number(r.trust ?? 0),
-                interactionCount: Number(r.interactionCount ?? 0),
-                lastNote: r.lastNote ? String(r.lastNote) : null,
-            };
-        });
-    }
-    // ── Feed Posts ──────────────────────────────────────────────────
-    async addPost(post) {
-        await this.graph.query(`MATCH (a:Agent {id: $authorId})
-       CREATE (p:FeedPost {id: $id, content: $content, author_id: $authorId,
-                           author_name: $authorName, author_role: $authorRole,
-                           source: $source, created_at: $tick,
-                           reply_to: $replyTo})
-       CREATE (a)-[:POSTED]->(p)`, {
-            params: {
-                id: post.id, content: post.content, authorId: post.authorId,
-                authorName: post.authorName, authorRole: post.authorRole,
-                source: post.source, tick: post.tick, replyTo: post.replyTo ?? '',
-            },
-        });
-        // Create reply edge
-        if (post.replyTo) {
-            await this.graph.query(`MATCH (child:FeedPost {id: $childId}), (parent:FeedPost {id: $parentId})
-         CREATE (child)-[:REPLY_TO]->(parent)`, { params: { childId: post.id, parentId: post.replyTo } });
-        }
-        // Tag topics
-        if (post.topicTags && post.topicTags.length > 0) {
-            for (const tag of post.topicTags) {
-                await this.graph.query(`MATCH (p:FeedPost {id: $postId})
-           MERGE (t:Topic {name: $tag})
-           CREATE (p)-[:TAGGED]->(t)`, { params: { postId: post.id, tag } });
-            }
-        }
-    }
-    async addReaction(agentId, postId) {
-        await this.graph.query(`MATCH (a:Agent {id: $agentId}), (p:FeedPost {id: $postId})
-       MERGE (a)-[:REACTED_TO]->(p)`, { params: { agentId, postId } });
-    }
-    async getRecentPosts(limit = 50, sinceTick) {
-        const whereClause = sinceTick !== undefined ? `WHERE p.created_at > $since` : '';
-        const result = await this.graph.query(`MATCH (p:FeedPost)
-       ${whereClause}
-       OPTIONAL MATCH (p)<-[:REACTED_TO]-(reactor:Agent)
-       OPTIONAL MATCH (p)-[:TAGGED]->(t:Topic)
-       RETURN p.id AS id, p.content AS content, p.author_id AS authorId,
-              p.author_name AS authorName, p.author_role AS authorRole,
-              p.source AS source, p.created_at AS createdAt,
-              p.reply_to AS replyTo,
-              count(DISTINCT reactor) AS reactionCount,
-              collect(DISTINCT t.name) AS topicTags
-       ORDER BY p.created_at DESC
-       LIMIT $limit`, { params: { limit, since: sinceTick ?? 0 } });
-        return this.parsePostRows(result.data);
-    }
-    // ── Events ──────────────────────────────────────────────────────
-    async addEvent(event) {
-        await this.graph.query(`CREATE (e:Event {id: $id, type: $type, description: $description, tick: $tick})`, { params: { id: event.id, type: event.type, description: event.description, tick: event.tick } });
-        for (const pid of event.participantIds) {
-            await this.graph.query(`MATCH (e:Event {id: $eventId}), (a:Agent {id: $agentId})
-         CREATE (e)-[:INVOLVED]->(a)`, { params: { eventId: event.id, agentId: pid } });
-        }
-    }
-    // ── Graph Traversal ─────────────────────────────────────────────
-    /**
-     * Get an agent's full world view at a given tick:
-     * - Facts they've stated (current)
-     * - Facts their peers have stated (current)
-     * - Facts about topics they've discussed
-     */
-    async getAgentWorldView(agentId, tick) {
-        // Own facts
-        const ownFacts = await this.getAgentFacts(agentId, true);
-        // Peer facts (from agents they KNOW — both directions, review #12)
-        const peerResult = await this.graph.query(`MATCH (a:Agent {id: $agentId})-[:KNOWS]-(peer:Agent)-[:STATED]->(f:Fact)
-       WHERE f.invalid_at = -1
-       RETURN peer.name AS peerName, peer.role AS peerRole,
-              f.id AS id, f.content AS content, f.category AS category,
-              f.source_tick AS sourceTick, f.valid_from AS validFrom, f.invalid_at AS invalidAt
-       ORDER BY f.source_tick DESC
-       LIMIT 30`, { params: { agentId } });
-        // Group peer facts by peer
-        const peerMap = new Map();
-        for (const row of (peerResult.data ?? [])) {
-            const peerName = String(row.peerName);
-            if (!peerMap.has(peerName)) {
-                peerMap.set(peerName, { peerName, peerRole: String(row.peerRole), facts: [] });
-            }
-            peerMap.get(peerName).facts.push({
-                id: String(row.id), content: String(row.content), category: String(row.category),
-                sourceTick: Number(row.sourceTick), validFrom: Number(row.validFrom),
-                invalidAt: Number(row.invalidAt) === -1 ? null : Number(row.invalidAt),
-            });
-        }
-        return {
-            ownFacts,
-            peerFacts: [...peerMap.values()],
-            topicFacts: [], // populated by caller if needed
-        };
-    }
-    /**
-     * Get context around any entity — all facts, agents, and relationships.
-     * Review #9: removed unused depth param (queries are always 1-hop).
-     */
-    async getEntityContext(entityId) {
-        const factsResult = await this.graph.query(`MATCH (e {id: $entityId})<-[:ABOUT]-(f:Fact)
-       WHERE f.invalid_at = -1
-       RETURN f.id AS id, f.content AS content, f.category AS category,
-              f.source_tick AS sourceTick, f.valid_from AS validFrom, f.invalid_at AS invalidAt
-       ORDER BY f.source_tick DESC
-       LIMIT 20`, { params: { entityId } });
-        const agentsResult = await this.graph.query(`MATCH (a:Agent)-[:STATED]->(f:Fact)-[:ABOUT]->(e {id: $entityId})
-       RETURN DISTINCT a.id AS id, a.name AS name, a.role AS role`, { params: { entityId } });
-        return {
-            facts: this.parseFactRows(factsResult.data),
-            agents: (agentsResult.data ?? []).map((r) => {
-                const row = r;
-                return { id: String(row.id), name: String(row.name), role: String(row.role) };
-            }),
-            relationships: [],
-        };
-    }
-    // ── Helpers ─────────────────────────────────────────────────────
-    parseFactRows(data) {
-        if (!data)
-            return [];
-        return data.map(row => {
-            const r = row;
-            return {
-                id: String(r.id ?? ''),
-                content: String(r.content ?? ''),
-                category: String(r.category ?? ''),
-                sourceTick: Number(r.sourceTick ?? 0),
-                validFrom: Number(r.validFrom ?? 0),
-                invalidAt: Number(r.invalidAt) === -1 ? null : Number(r.invalidAt ?? null),
-            };
-        });
-    }
-    parsePostRows(data) {
-        if (!data)
-            return [];
-        return data.map(row => {
-            const r = row;
-            return {
-                id: String(r.id ?? ''),
-                content: String(r.content ?? ''),
-                authorId: String(r.authorId ?? ''),
-                authorName: String(r.authorName ?? ''),
-                authorRole: String(r.authorRole ?? ''),
-                source: String(r.source ?? ''),
-                createdAt: Number(r.createdAt ?? 0),
-                replyTo: r.replyTo ? String(r.replyTo) : null,
-                reactionCount: Number(r.reactionCount ?? 0),
-                topicTags: Array.isArray(r.topicTags) ? r.topicTags.map(String) : [],
-            };
-        });
-    }
-}