@zergai/ztc 0.2.1-dev.35568243511 → 0.2.2-dev.35681806994

package/node_modules/@ztc/sim-graph/src/sim_graph.ts

@@ -1,1305 +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).
- */
-
-// falkordblite (embedded graph DB + native binding) is imported lazily in
-// SimGraph.open() so that merely importing this module stays cheap.
-import type { FalkorDB, Graph } from 'falkordblite';
-
-// ── Types ─────────────────────────────────────────────────────────
-
-/**
- * Scalar + nested shape accepted by FalkorDB parameter binding. Mirrors
- * the internal `QueryParam` type from the `falkordb` package (which is
- * not exported) so consumers of `rawQuery` get the same strictness.
- */
-export type QueryParamValue =
-  | null
-  | string
-  | number
-  | boolean
-  | QueryParams
-  | QueryParamValue[];
-export interface QueryParams {
-  [key: string]: QueryParamValue;
-}
-
-export interface GraphFact {
-  id: string;
-  content: string;
-  category: string;
-  sourceTick: number;
-  validFrom: number;
-  invalidAt: number | null;
-}
-
-export interface GraphRelationship {
-  agentIdA: string;
-  agentIdB: string;
-  nameA: string;
-  nameB: string;
-  sentiment: number;
-  trust: number;
-  interactionCount: number;
-  lastNote: string | null;
-}
-
-export interface GraphFeedPost {
-  id: string;
-  content: string;
-  authorId: string;
-  authorName: string;
-  authorRole: string;
-  source: string;
-  createdAt: number;
-  replyTo: string | null;
-  reactionCount: number;
-  topicTags: string[];
-}
-
-export interface GraphContext {
-  facts: GraphFact[];
-  agents: Array<{ id: string; name: string; role: string }>;
-  relationships: GraphRelationship[];
-}
-
-export interface WorldView {
-  ownFacts: GraphFact[];
-  peerFacts: Array<{ peerName: string; peerRole: string; facts: GraphFact[] }>;
-  topicFacts: GraphFact[];
-}
-
-export interface SimulationGraphFact {
-  id: string;
-  subjectId: string;
-  predicate: string;
-  objectId: string;
-  content: string;
-  validFrom: number;
-  invalidAt: number | null;
-  sourceEventId: string;
-  data: Record<string, unknown>;
-}
-
-export interface SimulationGraphFactInput {
-  id: string;
-  subjectId: string;
-  predicate: string;
-  objectId?: string;
-  content: string;
-  validFrom: number;
-  invalidAt?: number | null;
-  sourceEventId?: string;
-  supersedesIds?: string[];
-  data?: Record<string, unknown>;
-}
-
-export interface SimulationGraphEdge {
-  sourceId: string;
-  targetId: string;
-  type: string;
-  tick: number;
-  data: Record<string, unknown>;
-}
-
-export interface SimulationFactGraph {
-  schemaVersion: 1;
-  facts: SimulationGraphFact[];
-  edges: SimulationGraphEdge[];
-}
-
-export interface RecordSimulationFactInput {
-  graph?: SimulationFactGraph;
-  fact: SimulationGraphFactInput;
-}
-
-export interface ProjectActiveFactsInput {
-  graph: SimulationFactGraph;
-  atTick: number;
-  subjectIds?: string[];
-  predicates?: string[];
-}
-
-export interface SimulationNeighborhoodInput {
-  graph: SimulationFactGraph;
-  startIds: string[];
-  maxDepth?: number;
-  edgeTypes?: string[];
-}
-
-export interface SimulationNeighborhood {
-  schemaVersion: 1;
-  factIds: string[];
-  facts: SimulationGraphFact[];
-  edges: SimulationGraphEdge[];
-  depthByFactId: Record<string, number>;
-}
-
-export type SimulationFocusGraphDirection = 'in' | 'out' | 'both';
-
-export interface SimulationFocusGraphNode {
-  id: string;
-  kind?: string;
-  label?: string;
-  data?: Record<string, unknown>;
-}
-
-export interface SimulationFocusGraphEdge {
-  sourceId: string;
-  targetId: string;
-  type: string;
-  createdAt?: string;
-  data: Record<string, unknown>;
-}
-
-export interface SimulationFocusRelationSpec {
-  name: string;
-  edgeTypes: string[];
-  direction?: SimulationFocusGraphDirection;
-  limit?: number;
-}
-
-export interface SimulationFocusLineageSpec {
-  edgeTypes: string[];
-  direction?: Exclude<SimulationFocusGraphDirection, 'both'>;
-  includeFocus?: boolean;
-  maxDepth?: number;
-}
-
-export interface BuildSimulationFocusGraphContextInput {
-  nodes?: SimulationFocusGraphNode[];
-  edges?: SimulationFocusGraphEdge[];
-  focusIds?: string[];
-  relations?: SimulationFocusRelationSpec[];
-  lineage?: SimulationFocusLineageSpec;
-  maxFocusIds?: number;
-}
-
-export interface SimulationFocusLineage {
-  focusId: string;
-  nodeIds: string[];
-  edgeTypes: string[];
-  edges: SimulationFocusGraphEdge[];
-}
-
-export interface SimulationFocusRelationGroup {
-  name: string;
-  focusId: string;
-  nodeIds: string[];
-  edges: SimulationFocusGraphEdge[];
-}
-
-export interface SimulationFocusGraphContext {
-  version: 1;
-  focusIds: string[];
-  lineages: SimulationFocusLineage[];
-  relationGroups: SimulationFocusRelationGroup[];
-}
-
-export interface SimulationSteeringEvent {
-  id: string;
-  eventType?: string;
-  acceptedSignalKinds?: string[];
-  subjectId?: string;
-  verdict?: string;
-  selectionStatus?: string;
-  createdAt?: string;
-  data?: Record<string, unknown>;
-}
-
-export interface SimulationSteeringSignal {
-  kind?: string;
-  subjectId?: string;
-  verdict?: string;
-  selectionStatus?: string;
-  priority?: number;
-  data?: Record<string, unknown>;
-}
-
-export interface SimulationSteeringTask {
-  id: string;
-  taskType?: string;
-  source?: string;
-  createdAt?: string;
-  signals?: SimulationSteeringSignal[];
-}
-
-export interface SimulationSteeringOutput {
-  id: string;
-  taskId: string;
-  outputType?: string;
-  createdAt?: string;
-  data?: Record<string, unknown>;
-}
-
-export interface SimulationSteeringInfluenceEdge {
-  sourceId: string;
-  targetId: string;
-  type: 'steering_influenced_task' | 'steering_influenced_output';
-  createdAt: string;
-  data: Record<string, unknown>;
-}
-
-export interface BuildSimulationSteeringInfluenceGraphInput {
-  steeringEvents?: SimulationSteeringEvent[];
-  tasks?: SimulationSteeringTask[];
-  outputs?: SimulationSteeringOutput[];
-  ignoreVerdictKinds?: string[];
-}
-
-export interface SimulationSteeringInfluenceGraph {
-  version: 1;
-  taskEdges: SimulationSteeringInfluenceEdge[];
-  outputEdges: SimulationSteeringInfluenceEdge[];
-}
-
-export interface SimulationRestartMemoryGraphStats {
-  nodes: number;
-  edges: number;
-  activeFactCount: number;
-}
-
-export interface SimulationRestartMemoryPacket<TFact = Record<string, unknown>> {
-  version: 1;
-  runId: string;
-  focusIds: string[];
-  activeFacts: TFact[];
-  graphStats: SimulationRestartMemoryGraphStats;
-}
-
-export interface BuildSimulationRestartMemoryInput<TFact = Record<string, unknown>> {
-  runId?: string;
-  focusIds?: string[];
-  activeFacts?: TFact[];
-  graphStats?: Partial<SimulationRestartMemoryGraphStats>;
-  maxFocusIds?: number;
-}
-
-export function recordSimulationFact(input: RecordSimulationFactInput): SimulationFactGraph {
-  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: ProjectActiveFactsInput): SimulationGraphFact[] {
-  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: SimulationNeighborhoodInput,
-): SimulationNeighborhood {
-  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: Record<string, number> = {};
-  const factIds: string[] = [];
-  const selectedEdges: SimulationGraphEdge[] = [];
-  const queue: Array<{ id: string; depth: number }> = [];
-
-  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 is SimulationGraphFact => fact !== undefined),
-    edges: selectedEdges.filter((edge) => (
-      depthByFactId[edge.sourceId] !== undefined &&
-      depthByFactId[edge.targetId] !== undefined
-    )),
-    depthByFactId,
-  };
-}
-
-export function buildSimulationFocusGraphContext(
-  input: BuildSimulationFocusGraphContextInput,
-): SimulationFocusGraphContext {
-  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: BuildSimulationSteeringInfluenceGraphInput,
-): SimulationSteeringInfluenceGraph {
-  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: SimulationSteeringInfluenceEdge[] = [];
-  const outputEdges: SimulationSteeringInfluenceEdge[] = [];
-
-  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<TFact = Record<string, unknown>>(
-  input: BuildSimulationRestartMemoryInput<TFact>,
-): SimulationRestartMemoryPacket<TFact> {
-  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: SimulationSteeringEvent,
-  task: SimulationSteeringTask,
-  signal: SimulationSteeringSignal,
-): SimulationSteeringInfluenceEdge {
-  return {
-    sourceId: event.id,
-    targetId: task.id,
-    type: 'steering_influenced_task',
-    createdAt: textValue(task.createdAt),
-    data: steeringInfluenceData(task, signal),
-  };
-}
-
-function steeringOutputEdge(
-  event: SimulationSteeringEvent,
-  task: SimulationSteeringTask,
-  signal: SimulationSteeringSignal,
-  output: SimulationSteeringOutput,
-): SimulationSteeringInfluenceEdge {
-  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: SimulationSteeringTask,
-  signal: SimulationSteeringSignal,
-): Record<string, unknown> {
-  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: SimulationSteeringEvent,
-  task: SimulationSteeringTask,
-  signal: SimulationSteeringSignal,
-  ignoreVerdictKinds: Set<string>,
-): boolean {
-  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: unknown, right: unknown): boolean {
-  const leftText = textValue(left);
-  const rightText = textValue(right);
-  return !leftText || !rightText || leftText === rightText;
-}
-
-function addUniqueSteeringInfluenceEdge(
-  edges: SimulationSteeringInfluenceEdge[],
-  edge: SimulationSteeringInfluenceEdge,
-): void {
-  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: SimulationSteeringEvent): SimulationSteeringEvent {
-  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: SimulationSteeringTask): SimulationSteeringTask {
-  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: SimulationSteeringSignal): SimulationSteeringSignal {
-  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: SimulationSteeringOutput): SimulationSteeringOutput {
-  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: string,
-  nodes: Map<string, SimulationFocusGraphNode>,
-  edges: SimulationFocusGraphEdge[],
-  lineage: SimulationFocusLineageSpec,
-): SimulationFocusLineage {
-  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: string[] = [];
-  const pathEdges: SimulationFocusGraphEdge[] = [];
-  const visited = new Set<string>();
-  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: string,
-  edges: SimulationFocusGraphEdge[],
-  relation: SimulationFocusRelationSpec,
-): SimulationFocusRelationGroup {
-  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: SimulationFocusGraphEdge,
-  focusId: string,
-  direction: SimulationFocusGraphDirection,
-): boolean {
-  if (direction === 'out') return edge.sourceId === focusId;
-  if (direction === 'in') return edge.targetId === focusId;
-  return edge.sourceId === focusId || edge.targetId === focusId;
-}
-
-function focusRelationOtherNodeId(
-  edge: SimulationFocusGraphEdge,
-  focusId: string,
-  direction: SimulationFocusGraphDirection,
-): string {
-  if (direction === 'out') return edge.targetId;
-  if (direction === 'in') return edge.sourceId;
-  return edge.sourceId === focusId ? edge.targetId : edge.sourceId;
-}
-
-function normalizeFocusGraphNode(node: SimulationFocusGraphNode): SimulationFocusGraphNode {
-  return {
-    id: textValue(node.id),
-    kind: textValue(node.kind),
-    label: textValue(node.label),
-    data: isRecord(node.data) ? { ...node.data } : {},
-  };
-}
-
-function normalizeFocusGraphEdge(edge: SimulationFocusGraphEdge): SimulationFocusGraphEdge {
-  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: SimulationFactGraph | undefined): SimulationFactGraph {
-  return {
-    schemaVersion: 1,
-    facts: (graph?.facts ?? []).map((fact) => normalizeSimulationGraphFact(fact)),
-    edges: dedupeSimulationEdges(graph?.edges ?? []),
-  };
-}
-
-function normalizeSimulationGraphFact(fact: SimulationGraphFactInput | SimulationGraphFact): SimulationGraphFact {
-  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: SimulationGraphEdge[]): SimulationGraphEdge[] {
-  const output: SimulationGraphEdge[] = [];
-  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: SimulationGraphEdge[],
-  edge: SimulationGraphEdge,
-): void {
-  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: unknown): string {
-  if (typeof value === 'string') return value.trim();
-  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
-  return '';
-}
-
-function finiteNumber(value: unknown, fallback: number): number {
-  const parsed = Number(value);
-  return Number.isFinite(parsed) ? parsed : fallback;
-}
-
-function wholeNumber(value: unknown, fallback: number): number {
-  return Math.max(0, Math.floor(finiteNumber(value, fallback)));
-}
-
-function uniqueText(values: string[]): string[] {
-  const output: string[] = [];
-  for (const value of values) {
-    const text = textValue(value);
-    if (!text || output.includes(text)) continue;
-    output.push(text);
-  }
-  return output;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-// ── SimGraph ──────────────────────────────────────────────────────
-
-export class SimGraph {
-  private db: FalkorDB;
-  private graph: Graph;
-  /** Per-instance counter (review #8: avoid module-level mutable state) */
-  private factCounter = 0;
-
-  private constructor(db: FalkorDB, graph: 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?: string): Promise<SimGraph> {
-    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(): Promise<void> {
-    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<T = Record<string, unknown>>(
-    cypher: string,
-    params?: QueryParams,
-  ): Promise<{ data?: T[] }> {
-    const result = await this.graph.query<[T]>(cypher, params ? { params } : undefined);
-    return { data: result.data as unknown as T[] | undefined };
-  }
-
-  /**
-   * Register a range index on a node label/property pair. Safe to call
-   * for already-indexed pairs — creation errors are swallowed.
-   */
-  async ensureNodeIndex(label: string, property: string): Promise<void> {
-    try {
-      await this.graph.createNodeRangeIndex(label, property);
-    } catch {
-      // Index may already exist — ignore
-    }
-  }
-
-  /** Create indices for common query patterns. */
-  private async initSchema(): Promise<void> {
-    // 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: {
-    id: string; name: string; role: string; organization: string; type: 'internal' | 'external';
-  }): Promise<void> {
-    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: {
-    id: string; name: string; industry: string; stage: string;
-  }): Promise<void> {
-    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: string, companyIdB: string): Promise<void> {
-    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: string, companyId: string): Promise<void> {
-    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: string,
-    content: string,
-    category: string,
-    tick: number,
-    aboutEntityId?: string,
-  ): Promise<string> {
-    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: string, tick: number): Promise<void> {
-    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: string,
-    content: string,
-    category: string,
-    tick: number,
-    aboutEntityId?: string,
-  ): Promise<string> {
-    // Find existing current facts by this agent in this category
-    if (aboutEntityId) {
-      const existing = await this.graph.query<[{ id: string }]>(
-        `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 as unknown as Record<string, string>).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: string, currentOnly: boolean = true): Promise<GraphFact[]> {
-    const whereClause = currentOnly ? 'AND f.invalid_at = -1' : '';
-    const result = await this.graph.query<[Record<string, unknown>]>(
-      `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: string, currentOnly: boolean = true): Promise<GraphFact[]> {
-    const whereClause = currentOnly ? 'AND f.invalid_at = -1' : '';
-    const result = await this.graph.query<[Record<string, unknown>]>(
-      `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: string, currentOnly: boolean = true): Promise<GraphFact[]> {
-    const whereClause = currentOnly ? 'AND f.invalid_at = -1' : '';
-    const result = await this.graph.query<[Record<string, unknown>]>(
-      `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: string, agentIdB: string,
-    sentiment: number, trust: number, interactionCount: number,
-    note?: string,
-  ): Promise<void> {
-    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: string, agentIdB: string): Promise<GraphRelationship | null> {
-    const result = await this.graph.query<[Record<string, unknown>]>(
-      `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] as unknown as Record<string, unknown>;
-    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: string): Promise<GraphRelationship[]> {
-    // Review #12: Query both directions
-    const result = await this.graph.query<[Record<string, unknown>]>(
-      `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: unknown) => {
-      const r = row as Record<string, unknown>;
-      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: {
-    id: string; content: string; authorId: string; authorName: string;
-    authorRole: string; source: string; tick: number; replyTo?: string;
-    topicTags?: string[];
-  }): Promise<void> {
-    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: string, postId: string): Promise<void> {
-    await this.graph.query(
-      `MATCH (a:Agent {id: $agentId}), (p:FeedPost {id: $postId})
-       MERGE (a)-[:REACTED_TO]->(p)`,
-      { params: { agentId, postId } },
-    );
-  }
-
-  async getRecentPosts(limit: number = 50, sinceTick?: number): Promise<GraphFeedPost[]> {
-    const whereClause = sinceTick !== undefined ? `WHERE p.created_at > $since` : '';
-    const result = await this.graph.query<[Record<string, unknown>]>(
-      `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: {
-    id: string; type: string; description: string; tick: number;
-    participantIds: string[];
-  }): Promise<void> {
-    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: string, tick: number): Promise<WorldView> {
-    // 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<[Record<string, unknown>]>(
-      `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<string, { peerName: string; peerRole: string; facts: GraphFact[] }>();
-    for (const row of (peerResult.data ?? []) as unknown as Record<string, unknown>[]) {
-      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: string): Promise<GraphContext> {
-    const factsResult = await this.graph.query<[Record<string, unknown>]>(
-      `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<[Record<string, unknown>]>(
-      `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: unknown) => {
-        const row = r as Record<string, unknown>;
-        return { id: String(row.id), name: String(row.name), role: String(row.role) };
-      }),
-      relationships: [],
-    };
-  }
-
-  // ── Helpers ─────────────────────────────────────────────────────
-
-  private parseFactRows(data: unknown[] | undefined): GraphFact[] {
-    if (!data) return [];
-    return data.map(row => {
-      const r = row as unknown as Record<string, unknown>;
-      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),
-      };
-    });
-  }
-
-  private parsePostRows(data: unknown[] | undefined): GraphFeedPost[] {
-    if (!data) return [];
-    return data.map(row => {
-      const r = row as unknown as Record<string, unknown>;
-      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) : [],
-      };
-    });
-  }
-}