// === src/agents/chunker.ts ===
import { estimateTokens } from "../utils/llm.js";

const MAX_CHUNK_TOKENS = 80_000; // Leave room for system prompt + output
const OVERLAP_CHARS = 500; // Overlap between chunks to preserve context at boundaries

export interface Chunk {
  index: number;
  total: number;
  text: string;
  tokenEstimate: number;
}

/**
 * Split text into chunks that fit within LLM context limits.
 * Splits on paragraph boundaries when possible, with overlap.
 */
export function chunkInput(text: string): Chunk[] {
  const totalTokens = estimateTokens(text);

  if (totalTokens <= MAX_CHUNK_TOKENS) {
    return [{ index: 0, total: 1, text, tokenEstimate: totalTokens }];
  }

  const maxCharsPerChunk = MAX_CHUNK_TOKENS * 4; // reverse of token estimate
  const chunks: Chunk[] = [];
  let offset = 0;

  while (offset < text.length) {
    let end = Math.min(offset + maxCharsPerChunk, text.length);

    // Try to split on a paragraph boundary
    if (end < text.length) {
      const searchRegion = text.slice(Math.max(end - 2000, offset), end);
      const lastParagraph = searchRegion.lastIndexOf("\n\n");
      if (lastParagraph > 0) {
        end = Math.max(end - 2000, offset) + lastParagraph + 2;
      } else {
        // Fall back to line boundary
        const lastLine = searchRegion.lastIndexOf("\n");
        if (lastLine > 0) {
          end = Math.max(end - 2000, offset) + lastLine + 1;
        }
      }
    }

    const chunkText = text.slice(offset, end);
    chunks.push({
      index: chunks.length,
      total: 0, // filled in below
      text: chunkText,
      tokenEstimate: estimateTokens(chunkText),
    });

    // Advance with overlap
    offset = end - (end < text.length ? OVERLAP_CHARS : 0);
  }

  // Set total count
  for (const chunk of chunks) {
    chunk.total = chunks.length;
  }

  return chunks;
}

// === src/agents/extraction.ts ===
import { callAgentJSON, checkInputSize } from "../utils/llm.js";
import type { PipelineInput } from "../pipeline/index.js";
import { chunkInput } from "./chunker.js";
import { getPromptForSourceType } from "./prompts.js";
import { validateExtraction } from "../schema/extraction.js";

export interface RawExtraction {
  entities: Array<{
    name: string;
    type: string;
    description: string;
    properties?: Record<string, unknown>;
    tags?: string[];
    confidence?: number;
  }>;
  relations: Array<{
    source: string;
    target: string;
    type: string;
    label: string;
    bidirectional?: boolean;
  }>;
  processes: Array<{
    name: string;
    description: string;
    trigger?: string;
    steps: Array<{
      order: number;
      action: string;
      actor?: string;
      inputs?: string[];
      outputs?: string[];
    }>;
    participants: string[];
    outcomes: string[];
  }>;
  constraints: Array<{
    name: string;
    type: string;
    description: string;
    scope: string[];
    severity: "hard" | "soft";
  }>;
  model_name: string;
  model_description: string;
  source_summary: string;
  confidence: number;
  extraction_notes: string[];
}

const SYSTEM_PROMPT = `You are a world-model extraction agent. Your job is to analyze ANY input — text, code, conversation, documentation, descriptions — and extract a complete structured world model from it.

You must extract:

1. **Entities** — every distinct thing, actor, system, concept, resource, location, event, or group mentioned or implied. For each:
   - name: clear identifier
   - type: one of [actor, object, system, concept, location, event, group, resource]
   - description: what it is and why it matters in context
   - properties: any measurable/specific attributes
   - tags: categorization labels

2. **Relations** — every connection between entities. For each:
   - source: name of source entity (must match an entity name exactly)
   - target: name of target entity (must match an entity name exactly)
   - type: one of [has, is_a, part_of, depends_on, produces, consumes, controls, communicates_with, located_in, triggers, inherits, contains, uses, flows_to, opposes, enables, transforms]
   - label: human-readable description
   - bidirectional: true if the relation goes both ways

3. **Processes** — every dynamic sequence, workflow, or series of events. For each:
   - name, description, trigger
   - steps: ordered list with action, actor (entity name), inputs (entity names), outputs (entity names)
   - participants: all entity names involved
   - outcomes: what the process produces or changes

4. **Constraints** — every rule, invariant, limitation, boundary, or requirement. For each:
   - name, description
   - type: one of [invariant, rule, boundary, dependency, capacity, temporal, authorization]
   - scope: entity names this applies to
   - severity: hard (violation = error) or soft (violation = warning)

5. **Metadata**:
   - model_name: a concise name for the world being modeled
   - model_description: what domain/system this represents
   - source_summary: brief description of the input
   - confidence: 0-1 overall extraction confidence
   - extraction_notes: ambiguities, gaps, assumptions you made

RULES:
- Extract EVERYTHING — be thorough, not selective
- Infer implicit entities and relations (e.g., if "users log in", there's a User actor, an Authentication system, and a Login process)
- Entity names in relations/processes MUST exactly match entity names
- Output ONLY valid JSON matching the schema — no commentary outside the JSON
- If the input is code, model the architecture (modules, data flows, APIs, etc.)
- If the input is a conversation, model the topics, participants, decisions, and action items
- If the input is vague, extract what you can and note gaps in extraction_notes`;

const CHUNK_SYSTEM_PROMPT = `${SYSTEM_PROMPT}

IMPORTANT: You are processing chunk {chunkIndex} of {chunkTotal} from a larger input.
- Extract everything from THIS chunk
- Use consistent entity names (the chunks will be merged later)
- Note in extraction_notes that this is a partial extraction from chunk {chunkIndex}/{chunkTotal}`;

function mergeRawExtractions(extractions: RawExtraction[]): RawExtraction {
  const merged: RawExtraction = {
    entities: [],
    relations: [],
    processes: [],
    constraints: [],
    model_name: extractions[0]?.model_name ?? "Untitled",
    model_description: extractions[0]?.model_description ?? "",
    source_summary: extractions
      .map((e) => e.source_summary)
      .filter(Boolean)
      .join("; "),
    confidence: 0,
    extraction_notes: [],
  };

  // Deduplicate entities by normalized name
  const entityMap = new Map<string, RawExtraction["entities"][number]>();
  for (const ext of extractions) {
    for (const e of ext.entities) {
      const key = e.name.toLowerCase().trim();
      if (!entityMap.has(key)) {
        entityMap.set(key, e);
      } else {
        const existing = entityMap.get(key)!;
        // Keep longer description, merge props/tags
        if (e.description.length > existing.description.length) {
          existing.description = e.description;
        }
        if (e.properties) {
          existing.properties = { ...existing.properties, ...e.properties };
        }
        if (e.tags) {
          existing.tags = [...new Set([...(existing.tags ?? []), ...e.tags])];
        }
      }
    }
  }
  merged.entities = [...entityMap.values()];

  // Deduplicate relations by (source, target, type)
  const relSet = new Set<string>();
  for (const ext of extractions) {
    for (const r of ext.relations) {
      const key = `${r.source.toLowerCase()}::${r.type}::${r.target.toLowerCase()}`;
      if (!relSet.has(key)) {
        relSet.add(key);
        merged.relations.push(r);
      }
    }
  }

  // Deduplicate processes by name
  const procSet = new Set<string>();
  for (const ext of extractions) {
    for (const p of ext.processes) {
      const key = p.name.toLowerCase().trim();
      if (!procSet.has(key)) {
        procSet.add(key);
        merged.processes.push(p);
      }
    }
  }

  // Deduplicate constraints by name
  const cstrSet = new Set<string>();
  for (const ext of extractions) {
    for (const c of ext.constraints) {
      const key = c.name.toLowerCase().trim();
      if (!cstrSet.has(key)) {
        cstrSet.add(key);
        merged.constraints.push(c);
      }
    }
  }

  // Average confidence
  const confidences = extractions.map((e) => e.confidence).filter((c) => c > 0);
  merged.confidence = confidences.length
    ? confidences.reduce((a, b) => a + b, 0) / confidences.length
    : 0.5;

  // Collect all notes
  merged.extraction_notes = extractions.flatMap(
    (e) => e.extraction_notes ?? [],
  );
  if (extractions.length > 1) {
    merged.extraction_notes.push(
      `Merged from ${extractions.length} chunks (${merged.entities.length} unique entities after dedup)`,
    );
  }

  return merged;
}

class EmptyExtractionError extends Error {
  constructor(issues: string[]) {
    super(`Extraction produced empty result: ${issues.join("; ")}`);
    this.name = "EmptyExtractionError";
  }
}

function validateAndCoerce(raw: unknown, throwOnEmpty = false): RawExtraction {
  const { extraction, issues } = validateExtraction(raw);
  if (issues.length > 0) {
    process.stderr.write(`  [validation] ${issues.join("; ")}\n`);
  }
  // If extraction is completely empty and we should retry, throw
  if (
    throwOnEmpty &&
    extraction.entities.length === 0 &&
    extraction.relations.length === 0
  ) {
    throw new EmptyExtractionError(issues);
  }
  // Cast validated extraction to RawExtraction (shapes are compatible)
  return extraction as unknown as RawExtraction;
}

export async function extractionAgent(
  input: PipelineInput,
): Promise<{ input: PipelineInput; extraction: RawExtraction }> {
  if (!input.raw || !input.raw.trim()) {
    throw new Error("Cannot extract from empty input");
  }

  const sizeCheck = checkInputSize(input.raw);
  if (sizeCheck.warning) {
    process.stderr.write(`  [warn] ${sizeCheck.warning}\n`);
  }

  const chunks = chunkInput(input.raw);
  const sourcePrompt = getPromptForSourceType(input.sourceType);

  if (chunks.length === 1) {
    // Single chunk — direct extraction with source-specific prompt, retry on empty
    const userMessage = `Analyze the following ${input.sourceType} input and extract a complete world model.\n\n---\n\n${input.raw}`;
    const MAX_EMPTY_RETRIES = 2;
    for (let attempt = 0; attempt <= MAX_EMPTY_RETRIES; attempt++) {
      const rawResult = await callAgentJSON<unknown>(
        sourcePrompt,
        userMessage,
        {
          maxTokens: 16384,
        },
      );
      try {
        return {
          input,
          extraction: validateAndCoerce(rawResult, attempt < MAX_EMPTY_RETRIES),
        };
      } catch (err) {
        if (
          err instanceof EmptyExtractionError &&
          attempt < MAX_EMPTY_RETRIES
        ) {
          process.stderr.write(
            `  [retry] empty extraction, attempt ${attempt + 1}/${MAX_EMPTY_RETRIES}...\n`,
          );
          continue;
        }
        // Final attempt — accept whatever we got (coerced empty)
        return { input, extraction: validateAndCoerce(rawResult, false) };
      }
    }
    // Shouldn't reach here, but satisfy TypeScript
    const rawResult = await callAgentJSON<unknown>(sourcePrompt, userMessage, {
      maxTokens: 16384,
    });
    return { input, extraction: validateAndCoerce(rawResult, false) };
  }

  // Multi-chunk — extract per chunk with source-specific prompt, then merge
  const chunkSuffix = `\n\nIMPORTANT: You are processing chunk {chunkIndex} of {chunkTotal} from a larger input.\n- Extract everything from THIS chunk\n- Use consistent entity names (chunks will be merged later)\n- Note in extraction_notes that this is a partial extraction from chunk {chunkIndex}/{chunkTotal}`;

  const extractions: RawExtraction[] = [];
  for (const chunk of chunks) {
    const prompt = (sourcePrompt + chunkSuffix)
      .replace(/\{chunkIndex\}/g, String(chunk.index + 1))
      .replace(/\{chunkTotal\}/g, String(chunk.total));

    const userMessage = `Analyze chunk ${chunk.index + 1}/${chunk.total} of a ${input.sourceType} input and extract all world model elements.\n\n---\n\n${chunk.text}`;

    const rawResult = await callAgentJSON<unknown>(prompt, userMessage, {
      maxTokens: 16384,
    });
    extractions.push(validateAndCoerce(rawResult));
  }

  return { input, extraction: mergeRawExtractions(extractions) };
}

// === src/agents/index.ts ===
export { extractionAgent } from "./extraction.js";
export { structuringAgent } from "./structuring.js";
export { validationAgent } from "./validation.js";
export { refineWorldModel } from "./refinement.js";
export { chunkInput } from "./chunker.js";
export { getPromptForSourceType } from "./prompts.js";
export { secondPassAgent } from "./second-pass.js";

// === src/agents/prompts.ts ===
const BASE_SCHEMA = `Output ONLY valid JSON with this EXACT structure — no other text before or after:
{
  "entities": [
    { "name": "string", "type": "actor|object|system|concept|location|event|group|resource", "description": "string", "properties": {}, "tags": ["string"] }
  ],
  "relations": [
    { "source": "entity name string", "target": "entity name string", "type": "has|is_a|part_of|depends_on|produces|consumes|controls|communicates_with|located_in|triggers|inherits|contains|uses|flows_to|opposes|enables|transforms", "label": "string", "bidirectional": false }
  ],
  "processes": [
    { "name": "string", "description": "string", "trigger": "string", "steps": [{ "order": 1, "action": "string", "actor": "entity name", "inputs": ["entity name"], "outputs": ["entity name"] }], "participants": ["entity name"], "outcomes": ["string"] }
  ],
  "constraints": [
    { "name": "string", "type": "invariant|rule|boundary|dependency|capacity|temporal|authorization", "description": "string", "scope": ["entity name"], "severity": "hard|soft" }
  ],
  "model_name": "string",
  "model_description": "string",
  "source_summary": "string",
  "confidence": 0.9,
  "extraction_notes": ["string"]
}

IMPORTANT: Every field shown as an array MUST be an array (even if empty: []). Every field shown as a string MUST be a string. Do not use any other types.

RULES:
- Entity names in relations/processes MUST exactly match entity names
- Extract EVERYTHING — be thorough, not selective
- Infer implicit entities and relations
- Output ONLY valid JSON — no commentary, no markdown, no explanation outside the JSON`;

export const PROMPTS: Record<string, string> = {
  text: `You are a world-model extraction agent. Analyze the given text and extract a complete structured world model.

Focus on:
- Named entities (people, organizations, places, things, concepts)
- Relationships between them (ownership, hierarchy, dependency, flow)
- Any described processes, workflows, or sequences of events
- Rules, constraints, limitations mentioned or implied
- Implicit entities that must exist for described behaviors to work

EXAMPLE — input: "A library lets members borrow books. Each book has an ISBN and a genre. Members can reserve books. Late returns incur a $1/day fine."

Expected extraction (abbreviated):
{
  "entities": [
    {"name": "Library", "type": "system", "description": "System that manages book lending to members"},
    {"name": "Member", "type": "actor", "description": "Registered user who can borrow and reserve books"},
    {"name": "Book", "type": "object", "description": "Physical item available for borrowing", "properties": {"isbn": "string", "genre": "string"}},
    {"name": "Reservation", "type": "object", "description": "A hold placed on a book by a member"}
  ],
  "relations": [
    {"source": "Library", "target": "Book", "type": "contains", "label": "holds inventory of"},
    {"source": "Member", "target": "Book", "type": "uses", "label": "borrows"},
    {"source": "Member", "target": "Reservation", "type": "produces", "label": "creates reservation for a book"}
  ],
  "processes": [
    {"name": "Book Borrowing", "description": "Member borrows a book from the library", "steps": [{"order": 1, "action": "Member selects book", "actor": "Member"}, {"order": 2, "action": "Library checks availability", "actor": "Library"}, {"order": 3, "action": "Book is checked out to member", "actor": "Library"}], "participants": ["Member", "Library", "Book"], "outcomes": ["Book is borrowed"]}
  ],
  "constraints": [
    {"name": "Late Return Fine", "type": "rule", "description": "Late returns incur a $1/day fine", "scope": ["Member", "Book"], "severity": "hard"}
  ]
}

Note how the example extracts the implicit Reservation entity and the Library system entity even though they're not directly named as such. Apply the same thoroughness to the actual input.

${BASE_SCHEMA}`,

  code: `You are a world-model extraction agent specialized in SOURCE CODE analysis. Analyze the code and extract its architectural world model.

Focus on:
- Modules, classes, functions, and services as entities
- Import/export dependencies as relations — TRACE IMPORT CHAINS: if module A imports from module B and calls B's functions, that's a "uses" relation
- Data flow between components (who produces what, who consumes what)
- API endpoints, routes, handlers as processes with steps
- Type definitions and interfaces as concept entities
- Database models and schemas as resource entities
- Configuration and environment variables as constraints
- Error handling patterns as boundary constraints
- Authentication/authorization as authorization constraints
- External service integrations as system entities
- CLI commands / entry points as actor entities — trace which systems each command invokes by following the imports in its action handler
- Utility modules that are imported by multiple files — these are shared systems, create "uses" relations from each consumer

CRITICAL RULES:
- Follow import chains to establish relations. If file A imports function X from file B, and function X operates on type T from file C, then A uses B and B depends_on C
- Do NOT create entities for local variables, function parameters, intermediate values, or internal state. Only extract architectural components (modules, services, agents, data types, external systems)
- Do NOT create orphan entities — every entity should have at least one relation
- Name entities after the COMPONENT they represent, not the variable name (e.g., "Extraction Agent" not "extractionAgent", "Pipeline" not "pipeline instance")
- Prefer fewer, well-connected entities over many disconnected ones

Infer the ARCHITECTURE, not just list files. Model how data flows through the system.

${BASE_SCHEMA}`,

  conversation: `You are a world-model extraction agent specialized in CONVERSATION analysis. Analyze the conversation and extract a structured world model of its content.

Focus on:
- Participants as actor entities
- Topics discussed as concept entities
- Systems/products/tools mentioned as system/object entities
- Decisions made as event entities with relations to what they affect
- Action items as process entities with steps and assigned actors
- Agreements and disagreements as relations (enables/opposes)
- Deadlines and commitments as temporal constraints
- Open questions as extraction_notes

Model the SUBSTANCE of the conversation, not the conversation itself.

${BASE_SCHEMA}`,

  document: `You are a world-model extraction agent specialized in DOCUMENT and STRUCTURED DATA analysis. Analyze the input and extract a complete structured world model.

If the input is JSON:
- Object keys become entities or properties
- Nested objects become "contains" or "part_of" relations
- Arrays of objects become entity collections with shared type
- API endpoints become processes with request/response steps
- Schema definitions (OpenAPI, JSON Schema) become concept entities with property details

If the input is YAML/TOML:
- Configuration sections become system entities
- Key-value pairs become properties on entities
- References between sections become relations

If the input is CSV/tabular:
- Column headers define entity properties
- Each row is an instance — extract the SCHEMA, not individual rows
- Foreign key patterns become relations

For all documents:
- All named entities (organizations, roles, systems, concepts, regulations)
- Hierarchical relationships (org charts, system architectures, taxonomies)
- Described workflows and procedures as processes
- Requirements, policies, and rules as constraints
- Defined terms as concept entities
- Dependencies between components or teams
- Temporal sequences (phases, milestones, deadlines)

Treat the document as a specification of a world — extract that world completely.

${BASE_SCHEMA}`,

  url: `You are a world-model extraction agent. The input is content fetched from a URL. Analyze it and extract a complete structured world model.

Focus on:
- The domain/topic the page covers
- All entities, services, products, or concepts described
- Relationships between them
- Any processes, workflows, or user journeys described
- Pricing, limitations, or constraints mentioned
- Technical specifications as properties on entities

${BASE_SCHEMA}`,

  mixed: `You are a world-model extraction agent. The input contains MIXED content types (possibly text, code, data, and structured content together).

Focus on:
- Identify what each section represents (narrative, code, data, config)
- Extract entities from ALL sections — they may reference each other
- Cross-reference: code entities may implement concepts described in text
- Data sections may define entity properties or constraints
- Use consistent entity names across all sections

${BASE_SCHEMA}`,
};

export function getPromptForSourceType(sourceType: string): string {
  return PROMPTS[sourceType] ?? PROMPTS.text;
}

// === src/agents/query.ts ===
import { callAgent } from "../utils/llm.js";
import {
  findEntity,
  findDependents,
  pathsBetween,
  getStats,
  analyzeImpact,
} from "../utils/graph.js";
import type { WorldModelType } from "../schema/index.js";

export interface QueryResult {
  answer: string;
  method: "graph" | "inference";
  entities_referenced: string[];
  confidence: number;
}

// ─── Deterministic graph queries ──────────────────────────────

const GRAPH_PATTERNS: Array<{
  pattern: RegExp;
  handler: (
    model: WorldModelType,
    match: RegExpMatchArray,
  ) => QueryResult | null;
}> = [
  {
    // "what depends on X" / "what uses X" / "what needs X"
    pattern:
      /what\s+(?:depends\s+on|uses|needs|requires|consumes)\s+(?:the\s+)?(.+?)(?:\?|$)/i,
    handler: (model, match) => {
      const entity = findEntity(model, match[1].trim());
      if (!entity) return null;
      const deps = findDependents(model, entity.id);
      if (deps.incoming.length === 0) {
        return {
          answer: `Nothing in the model depends on ${entity.name}.`,
          method: "graph",
          entities_referenced: [entity.name],
          confidence: 1,
        };
      }
      const lines = deps.incoming.map(
        (d) =>
          `- ${d.entity.name} —[${d.relation.type}]→ ${entity.name}: ${d.relation.label}`,
      );
      return {
        answer: `${deps.incoming.length} entities depend on ${entity.name}:\n${lines.join("\n")}`,
        method: "graph",
        entities_referenced: [
          entity.name,
          ...deps.incoming.map((d) => d.entity.name),
        ],
        confidence: 1,
      };
    },
  },
  {
    // "what does X depend on" / "what does X use" / "what does X need"
    pattern:
      /what\s+does\s+(.+?)\s+(?:depend\s+on|use|need|require|consume)(?:\?|$)/i,
    handler: (model, match) => {
      const entity = findEntity(model, match[1].trim());
      if (!entity) return null;
      const deps = findDependents(model, entity.id);
      if (deps.outgoing.length === 0) {
        return {
          answer: `${entity.name} does not depend on anything in the model.`,
          method: "graph",
          entities_referenced: [entity.name],
          confidence: 1,
        };
      }
      const lines = deps.outgoing.map(
        (d) =>
          `- ${entity.name} —[${d.relation.type}]→ ${d.entity.name}: ${d.relation.label}`,
      );
      return {
        answer: `${entity.name} depends on ${deps.outgoing.length} entities:\n${lines.join("\n")}`,
        method: "graph",
        entities_referenced: [
          entity.name,
          ...deps.outgoing.map((d) => d.entity.name),
        ],
        confidence: 1,
      };
    },
  },
  {
    // "how is X connected to Y" / "path from X to Y" / "how does X relate to Y"
    pattern:
      /(?:how\s+(?:is|does)\s+(.+?)\s+(?:connected|related?)\s+to\s+(.+?)|path\s+from\s+(.+?)\s+to\s+(.+?))(?:\?|$)/i,
    handler: (model, match) => {
      const srcName = (match[1] || match[3])?.trim();
      const tgtName = (match[2] || match[4])?.trim();
      if (!srcName || !tgtName) return null;
      const src = findEntity(model, srcName);
      const tgt = findEntity(model, tgtName);
      if (!src || !tgt) return null;

      const paths = pathsBetween(model, src.id, tgt.id);
      if (paths.length === 0) {
        return {
          answer: `No path found from ${src.name} to ${tgt.name} in the model.`,
          method: "graph",
          entities_referenced: [src.name, tgt.name],
          confidence: 1,
        };
      }

      const pathDescs = paths.map((path, i) => {
        const hops = path
          .map((step, j) => {
            if (j === 0) return step.entity.name;
            return `—[${step.relation?.type ?? "?"}]→ ${step.entity.name}`;
          })
          .join(" ");
        return `  Path ${i + 1}: ${hops}`;
      });

      return {
        answer: `${paths.length} path(s) from ${src.name} to ${tgt.name}:\n${pathDescs.join("\n")}`,
        method: "graph",
        entities_referenced: [src.name, tgt.name],
        confidence: 1,
      };
    },
  },
  {
    // "what constraints apply to X" / "rules for X"
    pattern:
      /(?:what\s+constraints?\s+(?:apply|applies)\s+to|rules?\s+for)\s+(?:the\s+)?(.+?)(?:\?|$)/i,
    handler: (model, match) => {
      const entity = findEntity(model, match[1].trim());
      if (!entity) return null;

      const applicable = model.constraints.filter((c) =>
        c.scope.includes(entity.id),
      );

      if (applicable.length === 0) {
        return {
          answer: `No constraints apply to ${entity.name}.`,
          method: "graph",
          entities_referenced: [entity.name],
          confidence: 1,
        };
      }

      const lines = applicable.map(
        (c) => `- [${c.severity}] ${c.name}: ${c.description}`,
      );
      return {
        answer: `${applicable.length} constraint(s) apply to ${entity.name}:\n${lines.join("\n")}`,
        method: "graph",
        entities_referenced: [entity.name],
        confidence: 1,
      };
    },
  },
  {
    // "what breaks if I remove X" / "impact of removing X" / "what happens without X"
    pattern:
      /(?:what\s+(?:breaks|happens)|impact\s+of\s+removing|what\s+if\s+(?:we|I)\s+remove)\s+(?:if\s+(?:we|I)\s+remove\s+)?(?:the\s+)?(.+?)(?:\?|$)/i,
    handler: (model, match) => {
      const entity = findEntity(model, match[1].trim());
      if (!entity) return null;

      const result = analyzeImpact(model, entity.id);
      if (!result) return null;

      const lines = [result.summary];
      if (result.dependents.length > 0) {
        lines.push(
          `Dependents: ${result.dependents.map((d) => d.name).join(", ")}`,
        );
      }
      if (result.affectedProcesses.length > 0) {
        lines.push(
          `Affected processes: ${result.affectedProcesses.map((a) => a.process.name).join(", ")}`,
        );
      }
      if (result.affectedConstraints.length > 0) {
        lines.push(
          `Affected constraints: ${result.affectedConstraints.map((c) => `[${c.severity}] ${c.name}`).join(", ")}`,
        );
      }

      return {
        answer: lines.join("\n"),
        method: "graph" as const,
        entities_referenced: [
          entity.name,
          ...result.dependents.map((d) => d.name),
        ],
        confidence: 1,
      };
    },
  },
  {
    // "what processes involve X" / "where does X participate" / "processes for X"
    pattern:
      /(?:what\s+processes?\s+(?:involve|include|use|have)|(?:where|which\s+processes?)\s+does\s+.+?\s+participate|processes?\s+(?:for|with|involving))\s+(?:the\s+)?(.+?)(?:\?|$)/i,
    handler: (model, match) => {
      const entity = findEntity(model, match[1].trim());
      if (!entity) return null;

      const involved = model.processes.filter(
        (p) =>
          p.participants.includes(entity.id) ||
          p.steps.some((s) => s.actor === entity.id),
      );

      if (involved.length === 0) {
        return {
          answer: `${entity.name} does not participate in any processes.`,
          method: "graph" as const,
          entities_referenced: [entity.name],
          confidence: 1,
        };
      }

      const lines = involved.map((p) => {
        const steps = p.steps
          .filter((s) => s.actor === entity.id)
          .map((s) => `  ${s.order}. ${s.action}`);
        const role =
          steps.length > 0
            ? `\n  Steps as ${entity.name}:\n${steps.join("\n")}`
            : "\n  (participant, no direct steps)";
        return `- **${p.name}**: ${p.description}${role}`;
      });

      return {
        answer: `${entity.name} participates in ${involved.length} process${involved.length > 1 ? "es" : ""}:\n${lines.join("\n")}`,
        method: "graph" as const,
        entities_referenced: [entity.name, ...involved.map((p) => p.name)],
        confidence: 1,
      };
    },
  },
  {
    // "list all actors" / "show all systems" / "show actors" / "what actors are there"
    pattern: /(?:list|show|what)\s+(?:all\s+)?(\w+?)s?(?:\s|$|\?)/i,
    handler: (model, match) => {
      const typeQuery = match[1].toLowerCase();
      const validTypes = [
        "actor",
        "object",
        "system",
        "concept",
        "location",
        "event",
        "group",
        "resource",
      ];
      const matchedType = validTypes.find(
        (t) =>
          t === typeQuery ||
          t + "s" === typeQuery + "s" ||
          typeQuery.startsWith(t),
      );
      if (!matchedType) return null;

      const filtered = model.entities.filter((e) => e.type === matchedType);
      if (filtered.length === 0) {
        return {
          answer: `No ${matchedType} entities in this model.`,
          method: "graph" as const,
          entities_referenced: [],
          confidence: 1,
        };
      }

      const lines = filtered.map((e) => `- **${e.name}**: ${e.description}`);
      return {
        answer: `${filtered.length} ${matchedType}${filtered.length > 1 ? "s" : ""}:\n${lines.join("\n")}`,
        method: "graph" as const,
        entities_referenced: filtered.map((e) => e.name),
        confidence: 1,
      };
    },
  },
  {
    // "how many entities" / "stats" / "summary"
    pattern: /(?:how\s+many|stats|statistics|summary|overview)\b/i,
    handler: (model) => {
      const stats = getStats(model);
      const lines = [
        `Entities: ${stats.entities.total} (${Object.entries(
          stats.entities.byType,
        )
          .map(([t, c]) => `${c} ${t}`)
          .join(", ")})`,
        `Relations: ${stats.relations.total}`,
        `Processes: ${stats.processes.total} (${stats.processes.totalSteps} steps)`,
        `Constraints: ${stats.constraints.total} (${stats.constraints.hard} hard, ${stats.constraints.soft} soft)`,
        `Confidence: ${stats.confidence}`,
        "",
        "Most connected:",
        ...stats.mostConnected.map(
          (mc) => `  - ${mc.entity}: ${mc.connections} connections`,
        ),
      ];
      return {
        answer: lines.join("\n"),
        method: "graph",
        entities_referenced: stats.mostConnected.map((mc) => mc.entity),
        confidence: 1,
      };
    },
  },
  {
    // "what is X" / "describe X" / "tell me about X"
    pattern:
      /(?:what\s+is|describe|tell\s+me\s+about|who\s+is)\s+(?:the\s+)?(.+?)(?:\?|$)/i,
    handler: (model, match) => {
      const entity = findEntity(model, match[1].trim());
      if (!entity) return null;

      const deps = findDependents(model, entity.id);
      const constraints = model.constraints.filter((c) =>
        c.scope.includes(entity.id),
      );
      const processes = model.processes.filter((p) =>
        p.participants.includes(entity.id),
      );

      const lines = [
        `**${entity.name}** (${entity.type})`,
        entity.description,
        "",
      ];

      if (entity.properties && Object.keys(entity.properties).length > 0) {
        lines.push(`Properties: ${JSON.stringify(entity.properties)}`);
      }

      if (deps.incoming.length > 0) {
        lines.push(
          `Depended on by: ${deps.incoming.map((d) => d.entity.name).join(", ")}`,
        );
      }
      if (deps.outgoing.length > 0) {
        lines.push(
          `Depends on: ${deps.outgoing.map((d) => d.entity.name).join(", ")}`,
        );
      }
      if (processes.length > 0) {
        lines.push(
          `Participates in: ${processes.map((p) => p.name).join(", ")}`,
        );
      }
      if (constraints.length > 0) {
        lines.push(
          `Constraints: ${constraints.map((c) => `[${c.severity}] ${c.name}`).join(", ")}`,
        );
      }

      return {
        answer: lines.join("\n"),
        method: "graph",
        entities_referenced: [
          entity.name,
          ...deps.incoming.map((d) => d.entity.name),
          ...deps.outgoing.map((d) => d.entity.name),
        ],
        confidence: 1,
      };
    },
  },
];

// ─── LLM inference query ──────────────────────────────────────

function modelToContext(model: WorldModelType): string {
  const entities = model.entities
    .map((e) => `- ${e.name} (${e.type}): ${e.description}`)
    .join("\n");

  const relations = model.relations
    .map((r) => {
      const src =
        model.entities.find((e) => e.id === r.source)?.name ?? r.source;
      const tgt =
        model.entities.find((e) => e.id === r.target)?.name ?? r.target;
      return `- ${src} —[${r.type}]→ ${tgt}: ${r.label}`;
    })
    .join("\n");

  const processes = model.processes
    .map((p) => {
      const steps = p.steps
        .map((s) => {
          const actor = s.actor
            ? (model.entities.find((e) => e.id === s.actor)?.name ?? "?")
            : "?";
          return `  ${s.order}. ${actor}: ${s.action}`;
        })
        .join("\n");
      return `- ${p.name} (trigger: ${p.trigger ?? "n/a"}): ${p.description}\n${steps}\n  Outcomes: ${p.outcomes.join(", ")}`;
    })
    .join("\n");

  const constraints = model.constraints
    .map((c) => {
      const scopeNames = c.scope
        .map((id) => model.entities.find((e) => e.id === id)?.name ?? id)
        .join(", ");
      return `- [${c.severity}] ${c.name} (applies to: ${scopeNames}): ${c.description}`;
    })
    .join("\n");

  return `# World Model: ${model.name}\n${model.description}\n\n## Entities (${model.entities.length})\n${entities}\n\n## Relations (${model.relations.length})\n${relations}\n\n## Processes (${model.processes.length})\n${processes}\n\n## Constraints (${model.constraints.length})\n${constraints}`;
}

const QUERY_SYSTEM_PROMPT = `You are a world-model query agent. You answer questions based STRICTLY on the world model provided.

RULES:
- Only use information present in the model — do not hallucinate or infer beyond what the model states
- If the model doesn't contain enough information to answer, say so explicitly
- Reference specific entities, relations, processes, and constraints by name
- Be concise and direct
- If the question asks about something not in the model, say "The model does not contain information about [X]"`;

async function inferenceQuery(
  model: WorldModelType,
  question: string,
): Promise<QueryResult> {
  const context = modelToContext(model);
  const userMessage = `${context}\n\n---\n\nQuestion: ${question}`;

  const answer = await callAgent(QUERY_SYSTEM_PROMPT, userMessage, {
    maxTokens: 4096,
  });

  // Extract entity names that appear in the answer
  const referenced = model.entities
    .filter((e) => answer.toLowerCase().includes(e.name.toLowerCase()))
    .map((e) => e.name);

  return {
    answer,
    method: "inference",
    entities_referenced: referenced,
    confidence: 0.8,
  };
}

// ─── Public API ───────────────────────────────────────────────

export async function queryWorldModel(
  model: WorldModelType,
  question: string,
): Promise<QueryResult> {
  if (!question || !question.trim()) {
    return {
      answer: "No question provided.",
      method: "graph",
      entities_referenced: [],
      confidence: 1,
    };
  }

  // Try deterministic graph queries first
  for (const { pattern, handler } of GRAPH_PATTERNS) {
    const match = question.match(pattern);
    if (match) {
      const result = handler(model, match);
      if (result) return result;
      // Pattern matched but handler returned null (entity not found) — fall through to inference
    }
  }

  // Fall back to LLM inference
  return inferenceQuery(model, question);
}

// === src/agents/refinement.ts ===
import { callAgentJSON } from "../utils/llm.js";
import type { WorldModelType } from "../schema/index.js";
import type { PipelineInput } from "../pipeline/index.js";
import type { RawExtraction } from "./extraction.js";
import { structuringAgent } from "./structuring.js";
import { validationAgent } from "./validation.js";
import { mergeWorldModels } from "../utils/merge.js";

const REFINEMENT_PROMPT = `You are a world-model refinement agent. You are given an EXISTING world model and NEW input.
Your job is to extract ONLY what the new input adds, changes, or contradicts relative to the existing model.

## Existing World Model Summary:
{existingModelSummary}

## Instructions:
1. Extract new entities NOT already in the existing model
2. Extract new relations between entities (new or existing)
3. Extract new processes or refinements to existing processes
4. Extract new constraints or modifications to existing ones
5. If the new input CONTRADICTS something in the existing model, extract the new version and note the contradiction in extraction_notes

RULES:
- DO NOT re-extract entities/relations that already exist unchanged
- DO reference existing entity names exactly when creating new relations to them
- Mark confidence based on how clearly the new input supports each extraction
- Note in extraction_notes what was added vs what was modified
- Output ONLY valid JSON matching the extraction schema`;

function summarizeModel(model: WorldModelType): string {
  const entityList = model.entities
    .map((e) => `  - ${e.name} (${e.type}): ${e.description.slice(0, 100)}`)
    .join("\n");

  const relationList = model.relations
    .map((r) => {
      const src =
        model.entities.find((e) => e.id === r.source)?.name ?? r.source;
      const tgt =
        model.entities.find((e) => e.id === r.target)?.name ?? r.target;
      return `  - ${src} —[${r.type}]→ ${tgt}`;
    })
    .join("\n");

  const processList = model.processes
    .map((p) => `  - ${p.name}: ${p.description.slice(0, 80)}`)
    .join("\n");

  const constraintList = model.constraints
    .map((c) => `  - [${c.severity}] ${c.name}: ${c.description.slice(0, 80)}`)
    .join("\n");

  return `Entities (${model.entities.length}):\n${entityList}\n\nRelations (${model.relations.length}):\n${relationList}\n\nProcesses (${model.processes.length}):\n${processList}\n\nConstraints (${model.constraints.length}):\n${constraintList}`;
}

export async function refineWorldModel(
  existingModel: WorldModelType,
  newInput: PipelineInput,
  options?: {
    onStageStart?: (name: string) => void;
    onStageEnd?: (name: string, ms: number) => void;
  },
): Promise<{ worldModel: WorldModelType; delta: WorldModelType }> {
  const summary = summarizeModel(existingModel);
  const systemPrompt = REFINEMENT_PROMPT.replace(
    "{existingModelSummary}",
    summary,
  );

  // Extract delta
  options?.onStageStart?.("refinement-extraction");
  const start = Date.now();

  const userMessage = `Given the existing world model above, analyze this NEW ${newInput.sourceType} input and extract only what's new or changed.\n\n---\n\n${newInput.raw}`;

  const deltaExtraction = await callAgentJSON<RawExtraction>(
    systemPrompt,
    userMessage,
    {
      maxTokens: 16384,
    },
  );

  options?.onStageEnd?.("refinement-extraction", Date.now() - start);

  // Structure the delta into a world model
  options?.onStageStart?.("refinement-structuring");
  const structStart = Date.now();

  const { worldModel: deltaModel } = await structuringAgent({
    input: newInput,
    extraction: deltaExtraction,
  });

  options?.onStageEnd?.("refinement-structuring", Date.now() - structStart);

  // Merge existing + delta
  options?.onStageStart?.("refinement-merge");
  const mergeStart = Date.now();

  const merged = mergeWorldModels(existingModel, deltaModel, {
    name: existingModel.name,
    description: existingModel.description,
  });

  options?.onStageEnd?.("refinement-merge", Date.now() - mergeStart);

  // Validate the merged result
  options?.onStageStart?.("refinement-validation");
  const valStart = Date.now();

  const { worldModel: validatedModel } = await validationAgent({
    input: newInput,
    worldModel: merged,
  });

  options?.onStageEnd?.("refinement-validation", Date.now() - valStart);

  return { worldModel: validatedModel, delta: deltaModel };
}

// === src/agents/second-pass.ts ===
import { callAgentJSON } from "../utils/llm.js";
import type { WorldModelType } from "../schema/index.js";
import type { PipelineInput } from "../pipeline/index.js";
import type { RawExtraction } from "./extraction.js";
import { validateExtraction } from "../schema/extraction.js";

const SECOND_PASS_PROMPT = `You are a world-model COMPLETENESS agent. You are given:
1. The original raw input
2. A world model that was already extracted from it

Your job is to find everything the FIRST PASS MISSED. The first pass captures what's explicitly stated. You capture what's IMPLICIT.

Look for:

**Missing entities:**
- Entities that must EXIST for the described processes to work, but were never named
- Infrastructure entities (authentication, logging, error handling, networking)
- Role entities implied by actions ("someone approves" → there's an Approver actor)
- Data entities implied by processes ("saves to database" → there's a Record object)

**Missing relations:**
- Dependencies that are logically necessary but not stated
- Hierarchical relations implied by context (if X contains Y, Y is part_of X)
- Communication paths implied by processes (if A triggers B, A communicates_with B)

**Missing processes:**
- Error/failure paths (what happens when the main process fails?)
- Setup/teardown processes (what must happen before/after the described flow?)
- Maintenance processes (backups, migrations, updates)

**Missing constraints:**
- Physical/logical impossibilities not stated (can't be in two places, can't exceed capacity)
- Temporal constraints implied by ordering (step 2 can't happen before step 1)
- Authorization constraints implied by roles (only admins can X)
- Data integrity constraints (required fields, unique identifiers, referential integrity)

RULES:
- ONLY extract what's NEW — do not re-extract entities/relations already in the model
- Reference existing entity names exactly when creating relations to them
- Every extraction must be JUSTIFIED by the input — no hallucination
- Set confidence lower (0.3-0.7) since these are inferences, not direct extractions
- In extraction_notes, explain WHY each new element was inferred

Output ONLY valid JSON with this EXACT structure (no other text):
{
  "entities": [{ "name": "string", "type": "actor|object|system|concept|location|event|group|resource", "description": "string", "tags": ["string"] }],
  "relations": [{ "source": "entity name", "target": "entity name", "type": "has|is_a|part_of|depends_on|produces|consumes|controls|communicates_with|located_in|triggers|inherits|contains|uses|flows_to|opposes|enables|transforms", "label": "string" }],
  "processes": [{ "name": "string", "description": "string", "steps": [{ "order": 1, "action": "string", "actor": "entity name" }], "participants": ["entity name"], "outcomes": ["string"] }],
  "constraints": [{ "name": "string", "type": "invariant|rule|boundary|dependency|capacity|temporal|authorization", "description": "string", "scope": ["entity name"], "severity": "hard|soft" }],
  "model_name": "string",
  "model_description": "string",
  "source_summary": "string",
  "confidence": 0.5,
  "extraction_notes": ["string"]
}

If you find NOTHING new, return: {"entities":[],"relations":[],"processes":[],"constraints":[],"model_name":"","model_description":"","source_summary":"No new elements found","confidence":0.0,"extraction_notes":["Second pass found no implicit elements"]}`;

function summarizeModelForPrompt(model: WorldModelType): string {
  const entities = model.entities
    .map((e) => `- ${e.name} (${e.type}): ${e.description}`)
    .join("\n");

  const relations = model.relations
    .map((r) => {
      const src =
        model.entities.find((e) => e.id === r.source)?.name ?? r.source;
      const tgt =
        model.entities.find((e) => e.id === r.target)?.name ?? r.target;
      return `- ${src} —[${r.type}]→ ${tgt}: ${r.label}`;
    })
    .join("\n");

  const processes = model.processes
    .map((p) => {
      const steps = p.steps
        .map((s) => {
          const actor = s.actor
            ? (model.entities.find((e) => e.id === s.actor)?.name ?? s.actor)
            : "unknown";
          return `  ${s.order}. ${actor}: ${s.action}`;
        })
        .join("\n");
      return `- ${p.name}: ${p.description}\n${steps}`;
    })
    .join("\n");

  const constraints = model.constraints
    .map((c) => `- [${c.severity}] ${c.name}: ${c.description}`)
    .join("\n");

  return `ENTITIES (${model.entities.length}):\n${entities}\n\nRELATIONS (${model.relations.length}):\n${relations}\n\nPROCESSES (${model.processes.length}):\n${processes}\n\nCONSTRAINTS (${model.constraints.length}):\n${constraints}`;
}

export async function secondPassAgent(
  originalInput: PipelineInput,
  currentModel: WorldModelType,
): Promise<RawExtraction> {
  const modelSummary = summarizeModelForPrompt(currentModel);

  const userMessage = `## Original Input:\n${originalInput.raw}\n\n---\n\n## Already Extracted World Model:\n${modelSummary}\n\n---\n\nWhat did the first pass MISS? Extract only NEW entities, relations, processes, and constraints that are implicit in the input but not yet in the model.`;

  const rawResult = await callAgentJSON<unknown>(
    SECOND_PASS_PROMPT,
    userMessage,
    {
      maxTokens: 16384,
    },
  );

  const { extraction, issues } = validateExtraction(rawResult);
  if (issues.length > 0) {
    process.stderr.write(`  [second-pass validation] ${issues.join("; ")}\n`);
  }

  return extraction as unknown as RawExtraction;
}

// === src/agents/structuring.ts ===
import type { WorldModelType } from "../schema/index.js";
import { WorldModel } from "../schema/world-model.js";
import type { PipelineInput } from "../pipeline/index.js";
import type { RawExtraction } from "./extraction.js";
import { genId } from "../utils/ids.js";

export interface StructuringOutput {
  input: PipelineInput;
  worldModel: WorldModelType;
}

export function structuringAgent(stageInput: {
  input: PipelineInput;
  extraction: RawExtraction;
}): Promise<StructuringOutput> {
  const { input, extraction } = stageInput;

  // Normalize entity types the LLM may return outside the enum
  const VALID_ENTITY_TYPES = new Set([
    "actor",
    "object",
    "system",
    "concept",
    "location",
    "event",
    "group",
    "resource",
  ]);
  const ENTITY_TYPE_ALIASES: Record<string, string> = {
    person: "actor",
    user: "actor",
    role: "actor",
    agent: "actor",
    organization: "group",
    org: "group",
    team: "group",
    company: "group",
    place: "location",
    area: "location",
    region: "location",
    service: "system",
    platform: "system",
    tool: "system",
    application: "system",
    app: "system",
    idea: "concept",
    principle: "concept",
    pattern: "concept",
    category: "concept",
    item: "object",
    thing: "object",
    product: "object",
    data: "resource",
    asset: "resource",
    file: "resource",
    document: "resource",
    incident: "event",
    action: "event",
    occurrence: "event",
  };
  function normalizeEntityType(
    raw: string,
  ): WorldModelType["entities"][number]["type"] {
    const lower = raw.toLowerCase().trim();
    if (VALID_ENTITY_TYPES.has(lower))
      return lower as WorldModelType["entities"][number]["type"];
    return (ENTITY_TYPE_ALIASES[lower] ??
      "object") as WorldModelType["entities"][number]["type"];
  }

  // Normalize relation types
  const VALID_RELATION_TYPES = new Set([
    "has",
    "is_a",
    "part_of",
    "depends_on",
    "produces",
    "consumes",
    "controls",
    "communicates_with",
    "located_in",
    "triggers",
    "inherits",
    "contains",
    "uses",
    "flows_to",
    "opposes",
    "enables",
    "transforms",
  ]);
  function normalizeRelationType(
    raw: string,
  ): WorldModelType["relations"][number]["type"] {
    const lower = raw.toLowerCase().trim().replace(/ /g, "_");
    if (VALID_RELATION_TYPES.has(lower))
      return lower as WorldModelType["relations"][number]["type"];
    return "uses" as WorldModelType["relations"][number]["type"];
  }

  // Normalize constraint types
  const VALID_CONSTRAINT_TYPES = new Set([
    "invariant",
    "rule",
    "boundary",
    "dependency",
    "capacity",
    "temporal",
    "authorization",
  ]);
  function normalizeConstraintType(
    raw: string,
  ): WorldModelType["constraints"][number]["type"] {
    const lower = raw.toLowerCase().trim().replace(/ /g, "_");
    if (VALID_CONSTRAINT_TYPES.has(lower))
      return lower as WorldModelType["constraints"][number]["type"];
    return "rule" as WorldModelType["constraints"][number]["type"];
  }

  // Build entity name → ID map (case-insensitive + trimmed for robust matching)
  const entityIdMap = new Map<string, string>(); // normalized name → id
  const entityOriginalNames = new Map<string, string>(); // normalized name → original name
  const normalizeForLookup = (name: string) => name.toLowerCase().trim();

  // Deduplicate entities by normalized name during initial build
  const entities: Array<{
    id: string;
    name: string;
    type: WorldModelType["entities"][number]["type"];
    description: string;
    properties?: Record<string, unknown>;
    tags?: string[];
    confidence?: number;
  }> = [];

  for (const e of extraction.entities) {
    const key = normalizeForLookup(e.name);
    if (entityIdMap.has(key)) {
      // Duplicate — merge into existing entity
      const existingId = entityIdMap.get(key)!;
      const existing = entities.find((ent) => ent.id === existingId);
      if (existing) {
        // Keep the longer description
        if (e.description.length > existing.description.length) {
          existing.description = e.description;
        }
        // Merge properties
        if (e.properties) {
          existing.properties = { ...existing.properties, ...e.properties };
        }
        // Merge tags
        if (e.tags) {
          existing.tags = [...new Set([...(existing.tags ?? []), ...e.tags])];
        }
      }
    } else {
      const id = genId("ent");
      entityIdMap.set(key, id);
      entityOriginalNames.set(key, e.name);
      entities.push({
        id,
        name: e.name,
        type: normalizeEntityType(e.type),
        description: e.description,
        properties: e.properties,
        tags: e.tags,
        confidence: e.confidence,
      });
    }
  }

  const resolveEntityId = (name: string): string => {
    const key = normalizeForLookup(name);
    const existing = entityIdMap.get(key);
    if (existing) return existing;
    // Create a placeholder entity for unresolved references
    const id = genId("ent");
    entityIdMap.set(key, id);
    entityOriginalNames.set(key, name);
    entities.push({
      id,
      name,
      type: "object",
      description: `Auto-created entity for unresolved reference: ${name}`,
      properties: undefined,
      tags: ["auto-created"],
      confidence: 0.2,
    });
    return id;
  };

  const relations = extraction.relations.map((r) => ({
    id: genId("rel"),
    type: normalizeRelationType(r.type),
    source: resolveEntityId(r.source),
    target: resolveEntityId(r.target),
    label: r.label,
    bidirectional: r.bidirectional,
  }));

  const processes = extraction.processes.map((p) => ({
    id: genId("proc"),
    name: p.name,
    description: p.description,
    trigger: p.trigger,
    steps: p.steps.map((s, idx) => ({
      order: s.order ?? idx + 1,
      action: s.action,
      actor: s.actor ? resolveEntityId(s.actor) : undefined,
      input: s.inputs?.map(resolveEntityId),
      output: s.outputs?.map(resolveEntityId),
    })),
    participants: p.participants.map(resolveEntityId),
    outcomes: p.outcomes,
  }));

  const constraints = extraction.constraints.map((c) => ({
    id: genId("cstr"),
    name: c.name,
    type: normalizeConstraintType(c.type),
    description: c.description,
    scope: c.scope.map(resolveEntityId),
    severity: c.severity,
  }));

  const worldModel: WorldModelType = {
    id: genId("wm"),
    name: extraction.model_name || input.name || "Untitled World Model",
    description: extraction.model_description || "Extracted world model",
    version: "0.1.0",
    created_at: new Date().toISOString(),
    entities,
    relations,
    processes,
    constraints,
    metadata: {
      source_type: input.sourceType,
      source_summary: extraction.source_summary || "No summary",
      confidence: extraction.confidence ?? 0.5,
      extraction_notes: extraction.extraction_notes,
    },
  };

  // Validate output against Zod schema — catch structuring bugs before they propagate
  const parseResult = WorldModel.safeParse(worldModel);
  if (!parseResult.success) {
    const issues = parseResult.error.issues
      .slice(0, 3)
      .map((i) => i.message)
      .join("; ");
    process.stderr.write(
      `  [structuring] Output failed schema validation: ${issues}\n`,
    );
    // Don't throw — return what we have, validation agent will catch specifics
  }

  return Promise.resolve({ input, worldModel });
}

// === src/agents/transform.ts ===
import { callAgentJSON } from "../utils/llm.js";
import type { WorldModelType } from "../schema/index.js";
import type { RawExtraction } from "./extraction.js";
import { validateExtraction } from "../schema/extraction.js";
import { structuringAgent } from "./structuring.js";
import { mergeWorldModels } from "../utils/merge.js";
import { validationAgent } from "./validation.js";

const TRANSFORM_PROMPT = `You are a world-model transformation agent. You are given an existing world model and a transformation instruction.

Your job is to output the CHANGES needed to apply the transformation. Output entities, relations, processes, and constraints that should be ADDED to the model.

For REMOVALS, add an extraction_note like "REMOVE: Entity Name" or "REMOVE RELATION: Source -> Target".
For MODIFICATIONS, output the entity/relation with the new values — the merge will update by name.

## Existing World Model:
{modelSummary}

## Rules:
- Only output what CHANGES — don't re-output unchanged elements
- Reference existing entity names exactly
- If the transformation adds new entities, include full descriptions
- If the transformation modifies entities, output them with updated fields
- Note removals in extraction_notes with "REMOVE:" prefix

Output ONLY valid JSON with this structure:
{
  "entities": [{ "name": "string", "type": "actor|object|system|concept|location|event|group|resource", "description": "string", "tags": ["string"] }],
  "relations": [{ "source": "entity name", "target": "entity name", "type": "has|is_a|part_of|depends_on|produces|consumes|controls|communicates_with|located_in|triggers|inherits|contains|uses|flows_to|opposes|enables|transforms", "label": "string" }],
  "processes": [{ "name": "string", "description": "string", "steps": [{ "order": 1, "action": "string", "actor": "entity name" }], "participants": ["entity name"], "outcomes": ["string"] }],
  "constraints": [{ "name": "string", "type": "invariant|rule|boundary|dependency|capacity|temporal|authorization", "description": "string", "scope": ["entity name"], "severity": "hard|soft" }],
  "model_name": "",
  "model_description": "",
  "source_summary": "transformation applied",
  "confidence": 0.8,
  "extraction_notes": ["string"]
}`;

function summarizeModel(model: WorldModelType): string {
  const entities = model.entities
    .map((e) => `- ${e.name} (${e.type}): ${e.description}`)
    .join("\n");
  const relations = model.relations
    .map((r) => {
      const src =
        model.entities.find((e) => e.id === r.source)?.name ?? r.source;
      const tgt =
        model.entities.find((e) => e.id === r.target)?.name ?? r.target;
      return `- ${src} —[${r.type}]→ ${tgt}`;
    })
    .join("\n");
  const processes = model.processes
    .map((p) => `- ${p.name}: ${p.description}`)
    .join("\n");
  const constraints = model.constraints
    .map((c) => `- [${c.severity}] ${c.name}: ${c.description}`)
    .join("\n");

  return `Entities:\n${entities}\n\nRelations:\n${relations}\n\nProcesses:\n${processes}\n\nConstraints:\n${constraints}`;
}

export async function transformWorldModel(
  model: WorldModelType,
  instruction: string,
): Promise<{ model: WorldModelType; changes: string[] }> {
  const summary = summarizeModel(model);
  const systemPrompt = TRANSFORM_PROMPT.replace("{modelSummary}", summary);
  const userMessage = `Apply this transformation to the world model:\n\n${instruction}`;

  const rawResult = await callAgentJSON<unknown>(systemPrompt, userMessage, {
    maxTokens: 16384,
  });

  const { extraction, issues } = validateExtraction(rawResult);
  if (issues.length > 0) {
    process.stderr.write(`  [transform validation] ${issues.join("; ")}\n`);
  }

  const changes: string[] = [];

  // Process removals from extraction_notes
  let result = model;
  const removalNotes = (extraction.extraction_notes ?? []).filter((n) =>
    n.startsWith("REMOVE"),
  );

  if (removalNotes.length > 0) {
    const entitiesToRemove = new Set<string>();
    for (const note of removalNotes) {
      const entityMatch = note.match(/REMOVE:\s*(.+)/i);
      if (entityMatch) {
        entitiesToRemove.add(entityMatch[1].trim().toLowerCase());
        changes.push(`Removed: ${entityMatch[1].trim()}`);
      }
    }

    if (entitiesToRemove.size > 0) {
      const filteredEntities = result.entities.filter(
        (e) => !entitiesToRemove.has(e.name.toLowerCase()),
      );
      const removedIds = new Set(
        result.entities
          .filter((e) => entitiesToRemove.has(e.name.toLowerCase()))
          .map((e) => e.id),
      );
      result = {
        ...result,
        entities: filteredEntities,
        relations: result.relations.filter(
          (r) => !removedIds.has(r.source) && !removedIds.has(r.target),
        ),
        processes: result.processes.map((p) => ({
          ...p,
          participants: p.participants.filter((pid) => !removedIds.has(pid)),
        })),
        constraints: result.constraints.map((c) => ({
          ...c,
          scope: c.scope.filter((sid) => !removedIds.has(sid)),
        })),
      };
    }
  }

  // Merge additions
  const addedExtraction = extraction as unknown as RawExtraction;
  if (
    addedExtraction.entities.length > 0 ||
    addedExtraction.relations.length > 0 ||
    addedExtraction.processes.length > 0 ||
    addedExtraction.constraints.length > 0
  ) {
    const { worldModel: deltaModel } = await structuringAgent({
      input: { raw: instruction, sourceType: "text" },
      extraction: addedExtraction,
    });

    if (deltaModel.entities.length > 0)
      changes.push(`Added ${deltaModel.entities.length} entities`);
    if (deltaModel.relations.length > 0)
      changes.push(`Added ${deltaModel.relations.length} relations`);
    if (deltaModel.processes.length > 0)
      changes.push(`Added ${deltaModel.processes.length} processes`);
    if (deltaModel.constraints.length > 0)
      changes.push(`Added ${deltaModel.constraints.length} constraints`);

    result = mergeWorldModels(result, deltaModel, {
      name: result.name,
      description: result.description,
    });
  }

  // Re-validate
  const { worldModel: validated } = await validationAgent({
    input: { raw: instruction, sourceType: "text" },
    worldModel: result,
  });

  return { model: validated, changes };
}

// === src/agents/validation.ts ===
import type {
  WorldModelType,
  ValidationResultType,
  ValidationIssueType,
} from "../schema/index.js";
import type { PipelineInput } from "../pipeline/index.js";

export interface ValidationOutput {
  worldModel: WorldModelType;
  validation: ValidationResultType;
}

export function validationAgent(stageInput: {
  input: PipelineInput;
  worldModel: WorldModelType;
}): Promise<ValidationOutput> {
  const { worldModel } = stageInput;
  const issues: ValidationIssueType[] = [];

  const entityIds = new Set(worldModel.entities.map((e) => e.id));

  // Check relations reference valid entities
  for (const rel of worldModel.relations) {
    if (!entityIds.has(rel.source)) {
      issues.push({
        type: "error",
        code: "DANGLING_REL_SOURCE",
        message: `Relation "${rel.id}" references non-existent source entity "${rel.source}"`,
        path: `relations.${rel.id}.source`,
      });
    }
    if (!entityIds.has(rel.target)) {
      issues.push({
        type: "error",
        code: "DANGLING_REL_TARGET",
        message: `Relation "${rel.id}" references non-existent target entity "${rel.target}"`,
        path: `relations.${rel.id}.target`,
      });
    }
    if (rel.source === rel.target) {
      issues.push({
        type: "warning",
        code: "SELF_RELATION",
        message: `Relation "${rel.id}" is a self-reference on entity "${rel.source}"`,
        path: `relations.${rel.id}`,
      });
    }
  }

  // Check processes reference valid entities
  for (const proc of worldModel.processes) {
    for (const participant of proc.participants) {
      if (!entityIds.has(participant)) {
        issues.push({
          type: "error",
          code: "DANGLING_PROC_PARTICIPANT",
          message: `Process "${proc.name}" references non-existent participant "${participant}"`,
          path: `processes.${proc.id}.participants`,
        });
      }
    }
    for (const step of proc.steps) {
      if (step.actor && !entityIds.has(step.actor)) {
        issues.push({
          type: "error",
          code: "DANGLING_STEP_ACTOR",
          message: `Process "${proc.name}" step ${step.order} references non-existent actor "${step.actor}"`,
          path: `processes.${proc.id}.steps.${step.order}.actor`,
        });
      }
    }
    if (proc.steps.length === 0) {
      issues.push({
        type: "warning",
        code: "EMPTY_PROCESS",
        message: `Process "${proc.name}" has no steps`,
        path: `processes.${proc.id}.steps`,
      });
    }

    if (!proc.trigger) {
      issues.push({
        type: "info",
        code: "MISSING_TRIGGER",
        message: `Process "${proc.name}" has no trigger — when does it start?`,
        path: `processes.${proc.id}.trigger`,
      });
    }

    // Check step ordering
    if (proc.steps.length > 1) {
      const orders = proc.steps.map((s) => s.order);
      const hasDuplicates = new Set(orders).size !== orders.length;
      if (hasDuplicates) {
        issues.push({
          type: "warning",
          code: "DUPLICATE_STEP_ORDER",
          message: `Process "${proc.name}" has duplicate step order numbers: [${orders.join(", ")}]`,
          path: `processes.${proc.id}.steps`,
        });
      }
      const sorted = [...orders].sort((a, b) => a - b);
      const isMonotonic = orders.every((o, i) => o === sorted[i]);
      if (!isMonotonic) {
        issues.push({
          type: "warning",
          code: "UNORDERED_STEPS",
          message: `Process "${proc.name}" steps are not in ascending order: [${orders.join(", ")}]`,
          path: `processes.${proc.id}.steps`,
        });
      }
    }
  }

  // Check constraints reference valid entities
  for (const constraint of worldModel.constraints) {
    for (const scopeId of constraint.scope) {
      if (!entityIds.has(scopeId)) {
        issues.push({
          type: "error",
          code: "DANGLING_CONSTRAINT_SCOPE",
          message: `Constraint "${constraint.name}" references non-existent entity "${scopeId}"`,
          path: `constraints.${constraint.id}.scope`,
        });
      }
    }
  }

  // Check for orphan entities (no relations, not in any process/constraint)
  const referencedEntities = new Set<string>();
  for (const rel of worldModel.relations) {
    referencedEntities.add(rel.source);
    referencedEntities.add(rel.target);
  }
  for (const proc of worldModel.processes) {
    for (const p of proc.participants) referencedEntities.add(p);
    for (const s of proc.steps) {
      if (s.actor) referencedEntities.add(s.actor);
      for (const inp of s.input ?? []) referencedEntities.add(inp);
      for (const out of s.output ?? []) referencedEntities.add(out);
    }
  }
  for (const constraint of worldModel.constraints) {
    for (const s of constraint.scope) referencedEntities.add(s);
  }

  for (const entity of worldModel.entities) {
    if (!referencedEntities.has(entity.id)) {
      issues.push({
        type: "warning",
        code: "ORPHAN_ENTITY",
        message: `Entity "${entity.name}" (${entity.id}) is not referenced by any relation, process, or constraint`,
        path: `entities.${entity.id}`,
      });
    }
  }

  // Check for weak entity descriptions
  for (const entity of worldModel.entities) {
    if (!entity.description || entity.description.trim().length < 5) {
      issues.push({
        type: "warning",
        code: "WEAK_DESCRIPTION",
        message: `Entity "${entity.name}" has a missing or trivially short description`,
        path: `entities.${entity.id}.description`,
      });
    }
  }

  // Check for duplicate entity names
  const nameCount = new Map<string, number>();
  for (const entity of worldModel.entities) {
    nameCount.set(entity.name, (nameCount.get(entity.name) ?? 0) + 1);
  }
  for (const [name, count] of nameCount) {
    if (count > 1) {
      issues.push({
        type: "warning",
        code: "DUPLICATE_ENTITY_NAME",
        message: `Entity name "${name}" appears ${count} times — may indicate extraction duplication`,
        path: `entities`,
      });
    }
  }

  // Check for circular dependencies (A depends_on B, B depends_on A)
  const depTypes = new Set(["depends_on", "part_of", "contains", "inherits"]);
  const depEdges = worldModel.relations.filter((r) => depTypes.has(r.type));
  const visited = new Set<string>();
  const inStack = new Set<string>();

  function detectCycle(entityId: string, path: string[]): boolean {
    if (inStack.has(entityId)) {
      const cycleStart = path.indexOf(entityId);
      const cycle = path.slice(cycleStart);
      const cycleNames = cycle.map(
        (id) => worldModel.entities.find((e) => e.id === id)?.name ?? id,
      );
      issues.push({
        type: "warning",
        code: "CIRCULAR_DEPENDENCY",
        message: `Circular dependency detected: ${cycleNames.join(" → ")} → ${cycleNames[0]}`,
        path: `relations`,
      });
      return true;
    }
    if (visited.has(entityId)) return false;
    visited.add(entityId);
    inStack.add(entityId);
    for (const edge of depEdges) {
      if (edge.source === entityId) {
        detectCycle(edge.target, [...path, entityId]);
      }
    }
    inStack.delete(entityId);
    return false;
  }

  for (const entity of worldModel.entities) {
    if (!visited.has(entity.id)) {
      detectCycle(entity.id, []);
    }
  }

  // Completeness checks
  if (worldModel.entities.length === 0) {
    issues.push({
      type: "error",
      code: "NO_ENTITIES",
      message: "World model has no entities",
    });
  }
  if (worldModel.relations.length === 0) {
    issues.push({
      type: "warning",
      code: "NO_RELATIONS",
      message: "World model has no relations — entities are unconnected",
    });
  }

  // Check for low type diversity (one type dominates > 80% of entities)
  if (worldModel.entities.length >= 5) {
    const typeCounts = new Map<string, number>();
    for (const e of worldModel.entities) {
      typeCounts.set(e.type, (typeCounts.get(e.type) ?? 0) + 1);
    }
    for (const [type, count] of typeCounts) {
      const pct = count / worldModel.entities.length;
      if (pct > 0.8) {
        issues.push({
          type: "warning",
          code: "LOW_TYPE_DIVERSITY",
          message: `${Math.round(pct * 100)}% of entities are type "${type}" (${count}/${worldModel.entities.length}) — may indicate poor type classification`,
          path: "entities",
        });
      }
    }
  }

  // Check metadata confidence
  if (
    worldModel.metadata?.confidence !== undefined &&
    worldModel.metadata.confidence < 0.3
  ) {
    issues.push({
      type: "warning",
      code: "LOW_CONFIDENCE",
      message: `Model confidence is ${Math.round(worldModel.metadata.confidence * 100)}% — extraction may be unreliable`,
      path: "metadata.confidence",
    });
  }

  // Check for missing metadata
  if (!worldModel.metadata) {
    issues.push({
      type: "warning",
      code: "MISSING_METADATA",
      message: "Model has no metadata — source type and confidence unknown",
      path: "metadata",
    });
  }

  // Check for deep dependency chains (> 3 hops)
  {
    const depTypes = new Set(["depends_on", "part_of"]);
    const depEdges = worldModel.relations.filter((r) => depTypes.has(r.type));
    const adj = new Map<string, string[]>();
    for (const r of depEdges) {
      const arr = adj.get(r.source) ?? [];
      arr.push(r.target);
      adj.set(r.source, arr);
    }

    function longestChainFrom(id: string, visited: Set<string>): number {
      if (visited.has(id)) return 0;
      visited.add(id);
      let max = 0;
      for (const next of adj.get(id) ?? []) {
        max = Math.max(max, 1 + longestChainFrom(next, visited));
      }
      visited.delete(id);
      return max;
    }

    for (const entity of worldModel.entities) {
      const depth = longestChainFrom(entity.id, new Set());
      if (depth > 3) {
        issues.push({
          type: "warning",
          code: "DEEP_DEPENDENCY_CHAIN",
          message: `Entity "${entity.name}" starts a dependency chain ${depth} levels deep — may indicate fragile architecture`,
          path: `entities.${entity.id}`,
        });
      }
    }
  }

  // Check for disconnected subgraphs
  if (worldModel.entities.length >= 4 && worldModel.relations.length > 0) {
    const adj = new Map<string, Set<string>>();
    for (const e of worldModel.entities) adj.set(e.id, new Set());
    for (const r of worldModel.relations) {
      adj.get(r.source)?.add(r.target);
      adj.get(r.target)?.add(r.source);
    }
    const componentVisited = new Set<string>();
    let componentCount = 0;
    for (const e of worldModel.entities) {
      if (componentVisited.has(e.id)) continue;
      componentCount++;
      const queue = [e.id];
      while (queue.length > 0) {
        const id = queue.shift()!;
        if (componentVisited.has(id)) continue;
        componentVisited.add(id);
        for (const n of adj.get(id) ?? []) {
          if (!componentVisited.has(n)) queue.push(n);
        }
      }
    }
    if (componentCount > 1) {
      issues.push({
        type: "warning",
        code: "DISCONNECTED_SUBGRAPHS",
        message: `Model has ${componentCount} disconnected clusters — may indicate missing relations between components`,
        path: "relations",
      });
    }
  }

  const hasErrors = issues.some((i) => i.type === "error");

  // Compute quality score (0-100)
  let score = 100;

  // Penalize errors (-15 each) and warnings (-3 each)
  const errors = issues.filter((i) => i.type === "error").length;
  const warnings = issues.filter((i) => i.type === "warning").length;
  score -= errors * 15;
  score -= warnings * 3;

  // Reward completeness: having all four element types
  if (worldModel.entities.length === 0) score -= 20;
  if (worldModel.relations.length === 0) score -= 10;
  if (worldModel.processes.length === 0) score -= 5;
  if (worldModel.constraints.length === 0) score -= 5;

  // Reward relation density (relations / entities ratio — ideal ~1.0+)
  if (worldModel.entities.length > 0) {
    const density = worldModel.relations.length / worldModel.entities.length;
    if (density < 0.5) score -= 10;
    else if (density >= 1.0) score += 5;
  }

  // Reward confidence
  const conf = worldModel.metadata?.confidence ?? 0.5;
  score += Math.round((conf - 0.5) * 10); // +/-5 based on confidence

  score = Math.max(0, Math.min(100, score));

  const validation: ValidationResultType = {
    valid: !hasErrors,
    issues,
    stats: {
      entities: worldModel.entities.length,
      relations: worldModel.relations.length,
      processes: worldModel.processes.length,
      constraints: worldModel.constraints.length,
    },
    score,
  };

  return Promise.resolve({ worldModel, validation });
}

// === src/cli.ts ===
#!/usr/bin/env node

import { program } from "commander";
import { readFileSync, writeFileSync, existsSync } from "node:fs";
import { resolve } from "node:path";
import chalk from "chalk";
import { stringify as yamlStringify } from "yaml";
import { buildWorldModel } from "./swm.js";
import { fetchUrl, isUrl } from "./utils/fetch.js";
import { refineWorldModel } from "./agents/refinement.js";
import { mergeWorldModels, diffWorldModels } from "./utils/merge.js";
import {
  findEntity,
  findDependents,
  toMermaid,
  toDot,
  getStats,
  summarize,
  subgraph,
  findClusters,
  analyzeImpact,
} from "./utils/graph.js";
import { queryWorldModel } from "./agents/query.js";
import { intersection, difference, overlay } from "./utils/algebra.js";
import { toClaudeMd } from "./export/claude-md.js";
import { toSystemPrompt } from "./export/system-prompt.js";
import { toMcpSchema } from "./export/mcp-schema.js";
import {
  createTimeline,
  addSnapshot,
  entityHistory,
  timelineSummary,
} from "./utils/timeline.js";
import { coverage as coverageFn } from "./utils/coverage.js";
import type { Timeline } from "./utils/timeline.js";
import type { PipelineInput } from "./pipeline/index.js";
import type { WorldModelType } from "./schema/index.js";

function detectSourceType(
  raw: string,
  filePath?: string,
): PipelineInput["sourceType"] {
  // Check file extension first
  if (filePath) {
    const ext = filePath.split(".").pop()?.toLowerCase();
    const codeExts = new Set([
      "ts",
      "tsx",
      "js",
      "jsx",
      "py",
      "rb",
      "go",
      "rs",
      "java",
      "c",
      "cpp",
      "cs",
      "swift",
      "kt",
    ]);
    if (codeExts.has(ext ?? "")) return "code";
    if (
      ext === "json" ||
      ext === "yaml" ||
      ext === "yml" ||
      ext === "xml" ||
      ext === "csv" ||
      ext === "toml"
    )
      return "document";
    if (ext === "md" || ext === "txt" || ext === "rst") return "text";
  }

  const trimmed = raw.trimStart();

  // URL
  if (/^https?:\/\//i.test(trimmed)) return "url";

  // JSON
  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
    try {
      JSON.parse(raw);
      return "document";
    } catch {
      /* not valid JSON, continue */
    }
  }

  // YAML (multiple key: value lines, not code)
  const yamlLines = raw.split("\n").filter((l) => /^\w[\w\s]*:\s/.test(l));
  if (yamlLines.length >= 3 && !raw.includes("function ")) return "document";

  // XML/HTML-like structured data
  if (
    trimmed.startsWith("<?xml") ||
    trimmed.startsWith("<root") ||
    trimmed.startsWith("<!DOCTYPE")
  )
    return "document";

  // Code heuristics (multiple signals needed to avoid false positives)
  const codeSignals = [
    /\bfunction\s+\w+\s*\(/.test(raw),
    /\bclass\s+\w+/.test(raw),
    /^import\s+/m.test(raw),
    /^from\s+\S+\s+import/m.test(raw),
    /\bdef\s+\w+\s*\(/.test(raw),
    /\bfn\s+\w+\s*\(/.test(raw),
    /^(const|let|var)\s+\w+\s*=/m.test(raw),
    /=>\s*\{/.test(raw),
  ];
  if (codeSignals.filter(Boolean).length >= 2) return "code";

  // Conversation (speaker patterns: "Name:", "Speaker 1:", "Q:", "A:")
  if (/^[A-Z][a-z]+\s*:/m.test(raw) && /\n[A-Z][a-z]+\s*:/m.test(raw))
    return "conversation";

  return "text";
}

function readInput(inputArg?: string, filePath?: string): string {
  if (filePath) return readFileSync(resolve(filePath), "utf-8");
  if (inputArg) {
    try {
      return readFileSync(resolve(inputArg), "utf-8");
    } catch {
      return inputArg;
    }
  }
  throw new Error(
    "No input provided. Pass text, a file path, or use -f <file>.",
  );
}

async function readStdin(): Promise<string> {
  if (process.stdin.isTTY) {
    throw new Error(
      "No input provided. Pass text, a file path, a URL, or pipe via stdin.",
    );
  }
  const chunks: Buffer[] = [];
  for await (const chunk of process.stdin) {
    chunks.push(chunk as Buffer);
  }
  return Buffer.concat(chunks).toString("utf-8");
}

async function readInputAsync(
  inputArg?: string,
  filePaths?: string | string[],
): Promise<{ raw: string; detectedUrl?: string }> {
  // Multiple files — concatenate with headers
  if (Array.isArray(filePaths) && filePaths.length > 1) {
    const parts: string[] = [];
    for (const fp of filePaths) {
      const resolved = resolve(fp);
      if (!existsSync(resolved)) throw new Error(`File not found: ${resolved}`);
      const content = readFileSync(resolved, "utf-8");
      parts.push(`// === ${fp} ===\n${content}`);
    }
    return { raw: parts.join("\n\n") };
  }

  // Single file path (extract from array if needed)
  const filePath = Array.isArray(filePaths) ? filePaths[0] : filePaths;

  // Check if input is a URL — fetch it
  const candidate = filePath || inputArg || "";
  if (isUrl(candidate)) {
    process.stderr.write(chalk.gray(`  Fetching ${candidate}...\n`));
    const { text } = await fetchUrl(candidate);
    return { raw: text, detectedUrl: candidate };
  }
  // Try file/arg, fall back to stdin
  try {
    return { raw: readInput(inputArg, filePath) };
  } catch {
    return { raw: await readStdin() };
  }
}

async function readModel(path: string): Promise<WorldModelType> {
  if (path === "-" || (!process.stdin.isTTY && !existsSync(resolve(path)))) {
    const raw =
      path === "-"
        ? await readStdin()
        : (() => {
            throw new Error(`File not found: ${resolve(path)}`);
          })();
    try {
      return JSON.parse(raw) as WorldModelType;
    } catch {
      throw new Error("Invalid JSON from stdin — is this a world model?");
    }
  }
  const resolved = resolve(path);
  if (!existsSync(resolved)) {
    throw new Error(`File not found: ${resolved}`);
  }
  const raw = readFileSync(resolved, "utf-8");
  try {
    return JSON.parse(raw) as WorldModelType;
  } catch {
    throw new Error(`Invalid JSON in ${path} — is this a world model file?`);
  }
}

function formatOutput(
  model: WorldModelType,
  format: string,
  pretty: boolean,
): string {
  if (format === "yaml") return yamlStringify(model);
  if (format === "mermaid") return toMermaid(model);
  if (format === "dot") return toDot(model);
  return pretty ? JSON.stringify(model, null, 2) : JSON.stringify(model);
}

function stageCallbacks(quiet?: boolean) {
  let timer: ReturnType<typeof setInterval> | null = null;
  let stageStart = 0;
  return {
    onStageStart: (name: string) => {
      if (!quiet) {
        process.stderr.write(chalk.yellow(`  ▸ ${name}...`));
        stageStart = Date.now();
        timer = setInterval(() => {
          const elapsed = Math.round((Date.now() - stageStart) / 1000);
          process.stderr.write(
            `\r${chalk.yellow(`  ▸ ${name}... ${elapsed}s`)}`,
          );
        }, 2000);
      }
    },
    onStageEnd: (_name: string, ms: number, data?: unknown) => {
      if (timer) {
        clearInterval(timer);
        timer = null;
      }
      if (!quiet) {
        let detail = "";
        if (data && typeof data === "object") {
          const d = data as Record<string, unknown>;
          // After structuring or validation, show model stats
          if (d.worldModel && typeof d.worldModel === "object") {
            const wm = d.worldModel as Record<string, unknown[]>;
            detail = chalk.gray(
              ` (${wm.entities?.length ?? "?"}e ${wm.relations?.length ?? "?"}r ${wm.processes?.length ?? "?"}p ${wm.constraints?.length ?? "?"}c)`,
            );
          }
          // After extraction, show raw extraction counts
          if (d.extraction && typeof d.extraction === "object") {
            const ex = d.extraction as Record<string, unknown[]>;
            detail = chalk.gray(
              ` (${ex.entities?.length ?? "?"}e ${ex.relations?.length ?? "?"}r)`,
            );
          }
        }
        process.stderr.write(chalk.green(` done (${ms}ms)`) + detail + "\n");
      }
    },
  };
}

program
  .name("swm")
  .description(
    "Structured World Model — turn anything into a structured world model",
  )
  .version("0.1.0");

// ─── model ────────────────────────────────────────────────────
program
  .command("model")
  .description("Build a structured world model from input")
  .argument("[input]", "Text input or file path")
  .option(
    "-f, --file <paths...>",
    "Read input from one or more files (concatenated)",
  )
  .option("-o, --output <path>", "Write output to file")
  .option(
    "-t, --type <type>",
    "Source type: text, code, document, url, conversation, mixed",
  )
  .option(
    "--format <format>",
    "Output format: json, yaml, mermaid, dot",
    "json",
  )
  .option("--pretty", "Pretty-print JSON output", true)
  .option("--full", "Output full result (model + validation + score + timings)")
  .option("--quiet", "Suppress progress output")
  .option(
    "-p, --passes <n>",
    "Number of extraction passes (1=standard, 2-3=deeper)",
    "1",
  )
  .option(
    "-m, --model <model>",
    "Claude model to use (e.g. claude-opus-4-20250514, claude-haiku-4-5-20251001)",
  )
  .option(
    "--fix",
    "Auto-fix validation issues before outputting (remove orphans, dangling refs, duplicates)",
  )
  .option(
    "--min-score <n>",
    "Exit non-zero if quality score is below this threshold (0-100)",
  )
  .option("--watch", "Watch input file and rebuild on change")
  .option(
    "-n, --name <name>",
    "Set the world model name (overrides LLM-generated name)",
  )
  .option("-d, --description <desc>", "Set the world model description")
  .action(
    async (
      inputArg: string | undefined,
      opts: Record<string, string | boolean | undefined>,
    ) => {
      try {
        const { raw, detectedUrl } = await readInputAsync(
          inputArg,
          opts.file as string | string[] | undefined,
        );
        if (!raw.trim()) {
          console.error(chalk.red("Error: No input provided"));
          process.exit(1);
        }

        const sourceType =
          (opts.type as PipelineInput["sourceType"]) ||
          (detectedUrl
            ? "url"
            : detectSourceType(
                raw,
                (Array.isArray(opts.file)
                  ? opts.file[0]
                  : (opts.file as string)) ?? inputArg,
              ));
        const input: PipelineInput = {
          raw,
          sourceType,
          name:
            detectedUrl ||
            (opts.file as string) ||
            (inputArg && inputArg.length < 100 ? inputArg : undefined),
        };

        if (!opts.quiet) {
          console.error(chalk.blue("■ Structured World Model"));
          console.error(
            chalk.gray(`  Source: ${sourceType} (${raw.length} chars)\n`),
          );
        }

        const passes = parseInt((opts.passes as string) ?? "1", 10) || 1;
        let result = await buildWorldModel(input, {
          ...stageCallbacks(opts.quiet as boolean),
          passes,
          model: opts.model as string | undefined,
        });

        let finalModel = result.worldModel;
        if (opts.name) {
          finalModel = { ...finalModel, name: opts.name as string };
        }
        if (opts.description) {
          finalModel = {
            ...finalModel,
            description: opts.description as string,
          };
        }
        if (opts.fix) {
          const { fixWorldModel } = await import("./utils/fix.js");
          const { model: fixed, fixes } = fixWorldModel(finalModel);
          finalModel = fixed;
          if (!opts.quiet && fixes.length > 0) {
            console.error(chalk.yellow(`\n  Auto-fixed: ${fixes.join(", ")}`));
          }
          // Re-validate after fix to get accurate score
          const { validationAgent: va } =
            await import("./agents/validation.js");
          const { validation: revalidation } = await va({
            input,
            worldModel: finalModel,
          });
          result = {
            ...result,
            worldModel: finalModel,
            validation: revalidation,
          };
        }

        let output: string;
        if (opts.full) {
          const fullResult = {
            worldModel: finalModel,
            validation: result.validation,
            totalDurationMs: result.totalDurationMs,
          };
          output = JSON.stringify(fullResult, null, 2);
        } else {
          output = formatOutput(
            finalModel,
            (opts.format as string) ?? "json",
            (opts.pretty as boolean) ?? true,
          );
        }

        if (opts.output) {
          writeFileSync(resolve(opts.output as string), output, "utf-8");
          if (!opts.quiet)
            console.error(chalk.green(`\n  ✓ Written to ${opts.output}`));
        } else {
          console.log(output);
        }

        if (!opts.quiet) {
          const v = result.validation;
          const statusColor = v.valid ? chalk.green : chalk.red;
          console.error(
            statusColor(
              `\n  Validation: ${v.valid ? "PASSED" : "FAILED"} — ${v.stats.entities} entities, ${v.stats.relations} relations, ${v.stats.processes} processes, ${v.stats.constraints} constraints`,
            ),
          );
          if (v.issues.length > 0) {
            console.error(chalk.gray(`  Issues:`));
            for (const issue of v.issues) {
              const icon =
                issue.type === "error"
                  ? chalk.red("✗")
                  : issue.type === "warning"
                    ? chalk.yellow("!")
                    : chalk.blue("i");
              console.error(`    ${icon} ${issue.message}`);
            }
          }
          if (v.score !== undefined) {
            const sc =
              v.score >= 80
                ? chalk.green
                : v.score >= 50
                  ? chalk.yellow
                  : chalk.red;
            console.error(sc(`  Quality: ${v.score}/100`));
          }
          console.error(chalk.gray(`  Summary: ${summarize(finalModel)}`));
          console.error(chalk.gray(`\n  Total: ${result.totalDurationMs}ms`));
        }

        // Quality gate
        const minScore = opts.minScore
          ? parseInt(opts.minScore as string, 10)
          : undefined;
        if (minScore !== undefined && result.validation.score !== undefined) {
          if (result.validation.score < minScore) {
            console.error(
              chalk.red(
                `\n  Quality gate FAILED: score ${result.validation.score} < threshold ${minScore}`,
              ),
            );
            process.exit(1);
          }
        }
        // Watch mode
        if (opts.watch) {
          const watchPaths = Array.isArray(opts.file)
            ? opts.file
            : opts.file
              ? [opts.file as string]
              : inputArg
                ? [inputArg]
                : [];
          if (
            watchPaths.length === 0 ||
            !watchPaths.every((p) => existsSync(resolve(p as string)))
          ) {
            console.error(
              chalk.yellow("  --watch requires a file path (-f or argument)"),
            );
            return;
          }
          const { watch } = await import("node:fs");
          console.error(
            chalk.blue(
              `\n  Watching ${watchPaths.length} file(s) for changes... (Ctrl+C to stop)\n`,
            ),
          );
          let rebuilding = false;
          for (const wp of watchPaths) {
            watch(resolve(wp as string), async (eventType) => {
              if (eventType !== "change" || rebuilding) return;
              rebuilding = true;
              console.error(
                chalk.gray(
                  `\n  [${new Date().toLocaleTimeString()}] Change detected, rebuilding...`,
                ),
              );
              try {
                const { raw: newRaw } = await readInputAsync(
                  inputArg,
                  opts.file as string | string[] | undefined,
                );
                const newInput: PipelineInput = {
                  raw: newRaw,
                  sourceType: sourceType,
                  name: input.name,
                };
                const newResult = await buildWorldModel(newInput, {
                  ...stageCallbacks(opts.quiet as boolean),
                  passes,
                  model: opts.model as string | undefined,
                });
                let newFinal = newResult.worldModel;
                if (opts.fix) {
                  const { fixWorldModel } = await import("./utils/fix.js");
                  const { model: fixed } = fixWorldModel(newFinal);
                  newFinal = fixed;
                }
                const newOutput = formatOutput(
                  newFinal,
                  (opts.format as string) ?? "json",
                  (opts.pretty as boolean) ?? true,
                );
                if (opts.output) {
                  writeFileSync(
                    resolve(opts.output as string),
                    newOutput,
                    "utf-8",
                  );
                  console.error(
                    chalk.green(
                      `  ✓ Updated ${opts.output} — ${newResult.validation.stats.entities} entities, score: ${newResult.validation.score}/100`,
                    ),
                  );
                } else {
                  console.log(newOutput);
                }
              } catch (e) {
                console.error(
                  chalk.red(
                    `  Rebuild error: ${e instanceof Error ? e.message : String(e)}`,
                  ),
                );
              }
              rebuilding = false;
            });
          }
          // Keep process alive
          await new Promise(() => {});
        }
      } catch (err) {
        console.error(
          chalk.red(
            `Error: ${err instanceof Error ? err.message : String(err)}`,
          ),
        );
        process.exit(1);
      }
    },
  );

// ─── refine ───────────────────────────────────────────────────
program
  .command("refine")
  .description(
    "Refine an existing world model with new input (incremental extraction)",
  )
  .argument("<model>", "Path to existing world model JSON")
  .argument("[input]", "New text input or file path")
  .option("-f, --file <path>", "Read new input from file")
  .option("-o, --output <path>", "Write refined model to file")
  .option("-t, --type <type>", "Source type of new input")
  .option(
    "--format <format>",
    "Output format: json, yaml, mermaid, dot",
    "json",
  )
  .option("--quiet", "Suppress progress output")
  .action(
    async (
      modelPath: string,
      inputArg: string | undefined,
      opts: Record<string, string | boolean | undefined>,
    ) => {
      try {
        const existing = await readModel(modelPath);
        const raw = readInput(inputArg, opts.file as string | undefined);
        const sourceType =
          (opts.type as PipelineInput["sourceType"]) || detectSourceType(raw);

        if (!opts.quiet) {
          console.error(chalk.blue("■ Refining World Model"));
          console.error(
            chalk.gray(
              `  Existing: ${existing.entities.length} entities, ${existing.relations.length} relations`,
            ),
          );
          console.error(
            chalk.gray(`  New input: ${sourceType} (${raw.length} chars)\n`),
          );
        }

        const { worldModel, delta } = await refineWorldModel(
          existing,
          { raw, sourceType },
          stageCallbacks(opts.quiet as boolean),
        );

        const output = formatOutput(
          worldModel,
          (opts.format as string) ?? "json",
          true,
        );

        if (opts.output) {
          writeFileSync(resolve(opts.output as string), output, "utf-8");
          if (!opts.quiet)
            console.error(chalk.green(`\n  ✓ Written to ${opts.output}`));
        } else {
          console.log(output);
        }

        if (!opts.quiet) {
          console.error(
            chalk.gray(
              `\n  Delta: +${delta.entities.length} entities, +${delta.relations.length} relations, +${delta.processes.length} processes`,
            ),
          );
          console.error(
            chalk.gray(
              `  Result: ${worldModel.entities.length} entities, ${worldModel.relations.length} relations total`,
            ),
          );
        }
      } catch (err) {
        console.error(
          chalk.red(
            `Error: ${err instanceof Error ? err.message : String(err)}`,
          ),
        );
        process.exit(1);
      }
    },
  );

// ─── merge ────────────────────────────────────────────────────
program
  .command("merge")
  .description("Merge two world models into one")
  .argument("<modelA>", "Path to first world model JSON")
  .argument("<modelB>", "Path to second world model JSON")
  .option("-o, --output <path>", "Write merged model to file")
  .option("--format <format>", "Output format: json, yaml", "json")
  .action(
    async (
      pathA: string,
      pathB: string,
      opts: Record<string, string | undefined>,
    ) => {
      try {
        const a = await readModel(pathA);
        const b = await readModel(pathB);
        const merged = mergeWorldModels(a, b);
        const output = formatOutput(merged, opts.format ?? "json", true);

        if (opts.output) {
          writeFileSync(resolve(opts.output), output, "utf-8");
          console.error(
            chalk.green(`✓ Merged model written to ${opts.output}`),
          );
        } else {
          console.log(output);
        }

        console.error(
          chalk.gray(
            `  ${merged.entities.length} entities, ${merged.relations.length} relations`,
          ),
        );
      } catch (err) {
        console.error(
          chalk.red(
            `Error: ${err instanceof Error ? err.message : String(err)}`,
          ),
        );
        process.exit(1);
      }
    },
  );

// ─── diff ─────────────────────────────────────────────────────
program
  .command("diff")
  .description("Diff two world models")
  .argument("<before>", "Path to before world model JSON")
  .argument("<after>", "Path to after world model JSON")
  .action(async (beforePath: string, afterPath: string) => {
    try {
      const before = await readModel(beforePath);
      const after = await readModel(afterPath);
      const diff = diffWorldModels(before, after);

      console.log(chalk.blue("■ World Model Diff\n"));
      console.log(chalk.white(`  Summary: ${diff.summary}\n`));

      if (diff.entities.added.length) {
        console.log(chalk.green("  + Entities added:"));
        for (const name of diff.entities.added)
          console.log(chalk.green(`    + ${name}`));
      }
      if (diff.entities.removed.length) {
        console.log(chalk.red("  - Entities removed:"));
        for (const name of diff.entities.removed)
          console.log(chalk.red(`    - ${name}`));
      }
      if (diff.entities.modified.length) {
        console.log(chalk.yellow("  ~ Entities modified:"));
        for (const name of diff.entities.modified)
          console.log(chalk.yellow(`    ~ ${name}`));
      }
      if (diff.relations.added.length) {
        console.log(
          chalk.green(`  + ${diff.relations.added.length} relations added`),
        );
      }
      if (diff.relations.removed.length) {
        console.log(
          chalk.red(`  - ${diff.relations.removed.length} relations removed`),
        );
      }
      if (diff.processes.added.length) {
        console.log(
          chalk.green(`  + ${diff.processes.added.length} processes added`),
        );
      }
      if (diff.constraints.added.length) {
        console.log(
          chalk.green(`  + ${diff.constraints.added.length} constraints added`),
        );
      }

      // Score comparison
      const { validationAgent: va } = await import("./agents/validation.js");
      const { validation: vBefore } = await va({
        input: { raw: "", sourceType: "text" },
        worldModel: before,
      });
      const { validation: vAfter } = await va({
        input: { raw: "", sourceType: "text" },
        worldModel: after,
      });
      if (vBefore.score !== undefined && vAfter.score !== undefined) {
        const delta = vAfter.score - vBefore.score;
        const arrow =
          delta > 0
            ? chalk.green(`+${delta}`)
            : delta < 0
              ? chalk.red(`${delta}`)
              : chalk.gray("±0");
        console.log(
          `\n  Quality: ${vBefore.score} → ${vAfter.score} (${arrow})`,
        );
      }
    } catch (err) {
      console.error(
        chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`),
      );
      process.exit(1);
    }
  });

// ─── inspect ──────────────────────────────────────────────────
program
  .command("inspect")
  .description("Inspect a world model — stats, entity lookup, graph export")
  .argument("<model>", "Path to world model JSON")
  .option(
    "-e, --entity <name>",
    "Look up a specific entity and show its relations",
  )
  .option("--stats", "Show detailed statistics")
  .option("--format <format>", "Export format: mermaid, dot")
  .action(
    async (
      modelPath: string,
      opts: Record<string, string | boolean | undefined>,
    ) => {
      try {
        const model = await readModel(modelPath);

        if (opts.format) {
          console.log(formatOutput(model, opts.format as string, true));
          return;
        }

        if (opts.entity) {
          const entity = findEntity(model, opts.entity as string);
          if (!entity) {
            console.error(chalk.red(`Entity "${opts.entity}" not found`));
            process.exit(1);
          }

          console.log(
            chalk.blue(`■ ${entity.name}`) + chalk.gray(` (${entity.type})`),
          );
          console.log(chalk.white(`  ${entity.description}`));
          if (entity.properties) {
            console.log(
              chalk.gray(`  Properties: ${JSON.stringify(entity.properties)}`),
            );
          }

          const deps = findDependents(model, entity.id);
          if (deps.incoming.length) {
            console.log(chalk.gray("\n  Incoming:"));
            for (const d of deps.incoming) {
              console.log(
                `    ${d.entity.name} —[${d.relation.type}]→ ${entity.name}`,
              );
            }
          }
          if (deps.outgoing.length) {
            console.log(chalk.gray("\n  Outgoing:"));
            for (const d of deps.outgoing) {
              console.log(
                `    ${entity.name} —[${d.relation.type}]→ ${d.entity.name}`,
              );
            }
          }
          return;
        }

        // Default: show stats
        const stats = getStats(model);
        console.log(chalk.blue(`■ ${model.name}`));
        console.log(chalk.gray(`  ${model.description}\n`));
        console.log(`  Entities:    ${stats.entities.total}`);
        for (const [type, count] of Object.entries(stats.entities.byType)) {
          console.log(chalk.gray(`    ${type}: ${count}`));
        }
        console.log(`  Relations:   ${stats.relations.total}`);
        for (const [type, count] of Object.entries(stats.relations.byType)) {
          console.log(chalk.gray(`    ${type}: ${count}`));
        }
        console.log(
          `  Processes:   ${stats.processes.total} (${stats.processes.totalSteps} steps)`,
        );
        console.log(
          `  Constraints: ${stats.constraints.total} (${stats.constraints.hard} hard, ${stats.constraints.soft} soft)`,
        );
        console.log(`  Confidence:  ${stats.confidence}`);

        if (stats.mostConnected.length) {
          console.log(chalk.gray("\n  Most connected:"));
          for (const mc of stats.mostConnected) {
            console.log(`    ${mc.entity}: ${mc.connections} connections`);
          }
        }
      } catch (err) {
        console.error(
          chalk.red(
            `Error: ${err instanceof Error ? err.message : String(err)}`,
          ),
        );
        process.exit(1);
      }
    },
  );

// ─── validate ─────────────────────────────────────────────────
program
  .command("validate")
  .description("Validate a world model JSON file with full integrity checks")
  .argument("<file>", "Path to world model JSON")
  .option("--strict", "Exit non-zero on any warning (not just errors)")
  .action(async (file: string, opts: Record<string, boolean | undefined>) => {
    try {
      const model = await readModel(file);

      console.log(chalk.blue("■ Validating world model"));
      console.log(
        chalk.gray(
          `  ${model.entities.length} entities, ${model.relations.length} relations\n`,
        ),
      );

      const { validationAgent } = await import("./agents/validation.js");
      const { validation } = await validationAgent({
        input: { raw: "", sourceType: "text" },
        worldModel: model,
      });

      const statusColor = validation.valid ? chalk.green : chalk.red;
      console.log(
        statusColor(`  ${validation.valid ? "✓ VALID" : "✗ INVALID"}`),
      );

      if (validation.issues.length > 0) {
        for (const issue of validation.issues) {
          const icon =
            issue.type === "error"
              ? chalk.red("✗")
              : issue.type === "warning"
                ? chalk.yellow("!")
                : chalk.blue("i");
          console.log(`  ${icon} [${issue.code}] ${issue.message}`);
        }
      } else {
        console.log(chalk.green("  No issues found"));
      }

      console.log(
        chalk.gray(
          `\n  Stats: ${validation.stats.entities} entities, ${validation.stats.relations} relations, ${validation.stats.processes} processes, ${validation.stats.constraints} constraints`,
        ),
      );

      if (validation.score !== undefined) {
        const scoreColor =
          validation.score >= 80
            ? chalk.green
            : validation.score >= 50
              ? chalk.yellow
              : chalk.red;
        console.log(scoreColor(`  Quality score: ${validation.score}/100`));
      }

      if (!validation.valid) process.exit(1);
      if (opts.strict && validation.issues.length > 0) {
        console.error(
          chalk.red(
            `  Strict mode: ${validation.issues.length} issue(s) found`,
          ),
        );
        process.exit(1);
      }
    } catch (err) {
      console.error(
        chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`),
      );
      process.exit(1);
    }
  });

// ─── query ────────────────────────────────────────────────────
program
  .command("query")
  .description("Ask a question about a world model")
  .argument("<model>", "Path to world model JSON")
  .argument("<question>", "Natural language question")
  .option("--json", "Output result as JSON")
  .action(
    async (
      modelPath: string,
      question: string,
      opts: Record<string, boolean | undefined>,
    ) => {
      try {
        const model = await readModel(modelPath);
        const result = await queryWorldModel(model, question);

        if (opts.json) {
          console.log(JSON.stringify(result, null, 2));
        } else {
          console.log(result.answer);
          console.error(
            chalk.gray(
              `\n  Method: ${result.method} | Confidence: ${result.confidence} | Entities: ${result.entities_referenced.join(", ") || "none"}`,
            ),
          );
        }
      } catch (err) {
        console.error(
          chalk.red(
            `Error: ${err instanceof Error ? err.message : String(err)}`,
          ),
        );
        process.exit(1);
      }
    },
  );

// ─── algebra: intersect ───────────────────────────────────────
program
  .command("intersect")
  .description("Compute the intersection of two world models (shared entities)")
  .argument("<modelA>", "Path to first world model JSON")
  .argument("<modelB>", "Path to second world model JSON")
  .option("-o, --output <path>", "Write result to file")
  .action(
    async (
      pathA: string,
      pathB: string,
      opts: Record<string, string | undefined>,
    ) => {
      try {
        const result = intersection(
          await readModel(pathA),
          await readModel(pathB),
        );
        const output = JSON.stringify(result, null, 2);
        if (opts.output) {
          writeFileSync(resolve(opts.output), output, "utf-8");
          console.error(chalk.green(`✓ Written to ${opts.output}`));
        } else {
          console.log(output);
        }
        console.error(
          chalk.gray(
            `  ${result.entities.length} shared entities, ${result.relations.length} shared relations`,
          ),
        );
      } catch (err) {
        console.error(
          chalk.red(
            `Error: ${err instanceof Error ? err.message : String(err)}`,
          ),
        );
        process.exit(1);
      }
    },
  );

// ─── algebra: subtract ───────────────────────────────────────
program
  .command("subtract")
  .description("Compute A \\ B — entities in A that are not in B")
  .argument("<modelA>", "Path to base world model JSON")
  .argument("<modelB>", "Path to model to subtract")
  .option("-o, --output <path>", "Write result to file")
  .action(
    async (
      pathA: string,
      pathB: string,
      opts: Record<string, string | undefined>,
    ) => {
      try {
        const result = difference(
          await readModel(pathA),
          await readModel(pathB),
        );
        const output = JSON.stringify(result, null, 2);
        if (opts.output) {
          writeFileSync(resolve(opts.output), output, "utf-8");
          console.error(chalk.green(`✓ Written to ${opts.output}`));
        } else {
          console.log(output);
        }
        console.error(
          chalk.gray(`  ${result.entities.length} unique entities remaining`),
        );
      } catch (err) {
        console.error(
          chalk.red(
            `Error: ${err instanceof Error ? err.message : String(err)}`,
          ),
        );
        process.exit(1);
      }
    },
  );

// ─── algebra: overlay ────────────────────────────────────────
program
  .command("overlay")
  .description(
    "Apply a lens model on top of a base model (constraints, relations overlay)",
  )
  .argument("<base>", "Path to base world model JSON")
  .argument("<lens>", "Path to lens model to overlay")
  .option("-o, --output <path>", "Write result to file")
  .action(
    async (
      basePath: string,
      lensPath: string,
      opts: Record<string, string | undefined>,
    ) => {
      try {
        const result = overlay(
          await readModel(basePath),
          await readModel(lensPath),
        );
        const output = JSON.stringify(result, null, 2);
        if (opts.output) {
          writeFileSync(resolve(opts.output), output, "utf-8");
          console.error(chalk.green(`✓ Written to ${opts.output}`));
        } else {
          console.log(output);
        }
        console.error(
          chalk.gray(
            `  ${result.entities.length} entities, ${result.constraints.length} constraints after overlay`,
          ),
        );
      } catch (err) {
        console.error(
          chalk.red(
            `Error: ${err instanceof Error ? err.message : String(err)}`,
          ),
        );
        process.exit(1);
      }
    },
  );

// ─── export ──────────────────────────────────────────────────
program
  .command("export")
  .description("Export a world model as AI-consumable context")
  .argument("<model>", "Path to world model JSON")
  .option(
    "--as <format>",
    "Export format: claude-md, system-prompt, mcp",
    "claude-md",
  )
  .option("-o, --output <path>", "Write to file")
  .action(
    async (modelPath: string, opts: Record<string, string | undefined>) => {
      try {
        const model = await readModel(modelPath);
        let output: string;

        switch (opts.as) {
          case "claude-md":
            output = toClaudeMd(model);
            break;
          case "system-prompt":
            output = toSystemPrompt(model);
            break;
          case "mcp":
            output = JSON.stringify(toMcpSchema(model), null, 2);
            break;
          default:
            console.error(
              chalk.red(
                `Unknown export format: ${opts.as}. Use: claude-md, system-prompt, mcp`,
              ),
            );
            process.exit(1);
        }

        if (opts.output) {
          writeFileSync(resolve(opts.output), output, "utf-8");
          console.error(
            chalk.green(`✓ Exported as ${opts.as} to ${opts.output}`),
          );
        } else {
          console.log(output);
        }
      } catch (err) {
        console.error(
          chalk.red(
            `Error: ${err instanceof Error ? err.message : String(err)}`,
          ),
        );
        process.exit(1);
      }
    },
  );

// ─── timeline: snapshot ───────────────────────────────────────
program
  .command("snapshot")
  .description("Add a world model as a snapshot to a timeline")
  .argument("<model>", "Path to world model JSON")
  .option(
    "--timeline <path>",
    "Path to timeline JSON (created if missing)",
    "timeline.json",
  )
  .option("-l, --label <label>", "Label for this snapshot")
  .action(
    async (modelPath: string, opts: Record<string, string | undefined>) => {
      try {
        const model = await readModel(modelPath);
        const tlPath = resolve(opts.timeline ?? "timeline.json");

        let timeline: Timeline;
        try {
          const raw = readFileSync(tlPath, "utf-8");
          timeline = JSON.parse(raw) as Timeline;
        } catch {
          timeline = createTimeline(model.name);
          console.error(chalk.gray(`  Creating new timeline: ${tlPath}`));
        }

        timeline = addSnapshot(timeline, model, opts.label);
        writeFileSync(tlPath, JSON.stringify(timeline, null, 2), "utf-8");

        const snap = timeline.snapshots[timeline.snapshots.length - 1];
        console.error(chalk.green(`✓ Snapshot ${snap.id} added to ${tlPath}`));
        console.error(
          chalk.gray(
            `  ${snap.stats.entities} entities, ${snap.stats.relations} relations`,
          ),
        );
        if (snap.diff_from_previous) {
          console.error(
            chalk.gray(`  Changes: ${snap.diff_from_previous.summary}`),
          );
        }
        console.error(
          chalk.gray(`  Total snapshots: ${timeline.snapshots.length}`),
        );
      } catch (err) {
        console.error(
          chalk.red(
            `Error: ${err instanceof Error ? err.message : String(err)}`,
          ),
        );
        process.exit(1);
      }
    },
  );

// ─── timeline: history ────────────────────────────────────────
program
  .command("history")
  .description("Show timeline evolution or entity history")
  .argument("<timeline>", "Path to timeline JSON")
  .option("-e, --entity <name>", "Track a specific entity across snapshots")
  .action(async (tlPath: string, opts: Record<string, string | undefined>) => {
    try {
      const raw = readFileSync(resolve(tlPath), "utf-8");
      const timeline = JSON.parse(raw) as Timeline;

      if (opts.entity) {
        const history = entityHistory(timeline, opts.entity);
        if (history.length === 0) {
          console.log(
            chalk.yellow(`Entity "${opts.entity}" not found in any snapshot.`),
          );
          return;
        }
        console.log(
          chalk.blue(
            `■ History of "${opts.entity}" across ${timeline.snapshots.length} snapshots\n`,
          ),
        );
        for (const entry of history) {
          const icon =
            entry.event === "appeared"
              ? chalk.green("+")
              : entry.event === "disappeared"
                ? chalk.red("-")
                : entry.event === "modified"
                  ? chalk.yellow("~")
                  : chalk.gray("=");
          const label = entry.label ? ` (${entry.label})` : "";
          console.log(`  ${icon} ${entry.timestamp}${label}: ${entry.event}`);
          if (entry.description)
            console.log(chalk.gray(`    ${entry.description}`));
        }
      } else {
        console.log(timelineSummary(timeline));
      }
    } catch (err) {
      console.error(
        chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`),
      );
      process.exit(1);
    }
  });

// ─── serve ────────────────────────────────────────────────────
program
  .command("serve")
  .description(
    "Start an MCP server that serves a world model as live, queryable tools",
  )
  .argument("<model>", "Path to world model JSON")
  .action(async (modelPath: string) => {
    try {
      const resolved = resolve(modelPath);
      if (!existsSync(resolved)) {
        console.error(chalk.red(`File not found: ${resolved}`));
        process.exit(1);
      }
      const model = await readModel(modelPath);
      console.error(chalk.blue(`■ SWM MCP Server`));
      console.error(chalk.gray(`  Model: ${model.name}`));
      console.error(
        chalk.gray(
          `  Entities: ${model.entities.length}, Relations: ${model.relations.length}`,
        ),
      );
      console.error(
        chalk.gray(
          `  Tools: get_entity, get_relations, find_path, get_process, check_constraint, query, get_stats, get_diagram`,
        ),
      );
      console.error(chalk.green(`  Listening on stdio...\n`));

      const { startMcpServer } = await import("./serve/mcp-server.js");
      await startMcpServer(modelPath);
    } catch (err) {
      console.error(
        chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`),
      );
      process.exit(1);
    }
  });

// ─── schema ───────────────────────────────────────────────────
program
  .command("schema")
  .description(
    "Output the WorldModel JSON Schema (for validation or code generation)",
  )
  .action(async () => {
    const { getWorldModelJsonSchema } = await import("./schema/json-schema.js");
    console.log(JSON.stringify(getWorldModelJsonSchema(), null, 2));
  });

// ─── summary ──────────────────────────────────────────────────
program
  .command("summary")
  .description("One-line natural language summary of a world model (no LLM)")
  .argument("<model>", "Path to world model JSON")
  .action(async (modelPath: string) => {
    try {
      const model = await readModel(modelPath);
      console.log(summarize(model));
    } catch (err) {
      console.error(
        chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`),
      );
      process.exit(1);
    }
  });

// ─── entities ─────────────────────────────────────────────────
program
  .command("entities")
  .description("List all entities in a world model")
  .argument("<model>", "Path to world model JSON")
  .option(
    "-t, --type <type>",
    "Filter by entity type (actor, system, object, ...)",
  )
  .option("--json", "Output as JSON array")
  .action(
    async (
      modelPath: string,
      opts: Record<string, string | boolean | undefined>,
    ) => {
      try {
        const model = await readModel(modelPath);
        let entities = model.entities;
        if (opts.type) {
          entities = entities.filter((e) => e.type === opts.type);
        }
        if (opts.json) {
          console.log(JSON.stringify(entities, null, 2));
        } else {
          for (const e of entities) {
            const conf =
              e.confidence !== undefined
                ? chalk.gray(` (${Math.round(e.confidence * 100)}%)`)
                : "";
            console.log(`  [${e.type}] ${chalk.bold(e.name)}${conf}`);
            console.log(chalk.gray(`    ${e.description}`));
          }
          console.error(
            chalk.gray(
              `\n  ${entities.length} entities${opts.type ? ` of type "${opts.type}"` : ""}`,
            ),
          );
        }
      } catch (err) {
        console.error(
          chalk.red(
            `Error: ${err instanceof Error ? err.message : String(err)}`,
          ),
        );
        process.exit(1);
      }
    },
  );

// ─── relations ────────────────────────────────────────────────
program
  .command("relations")
  .description("List all relations in a world model")
  .argument("<model>", "Path to world model JSON")
  .option(
    "-t, --type <type>",
    "Filter by relation type (uses, depends_on, ...)",
  )
  .option("--json", "Output as JSON array")
  .action(
    async (
      modelPath: string,
      opts: Record<string, string | boolean | undefined>,
    ) => {
      try {
        const model = await readModel(modelPath);
        let relations = model.relations;
        if (opts.type) {
          relations = relations.filter((r) => r.type === opts.type);
        }
        if (opts.json) {
          console.log(JSON.stringify(relations, null, 2));
        } else {
          for (const r of relations) {
            const src =
              model.entities.find((e) => e.id === r.source)?.name ?? r.source;
            const tgt =
              model.entities.find((e) => e.id === r.target)?.name ?? r.target;
            console.log(`  ${src} ${chalk.yellow(`—[${r.type}]→`)} ${tgt}`);
            if (r.label) console.log(chalk.gray(`    ${r.label}`));
          }
          console.error(
            chalk.gray(
              `\n  ${relations.length} relations${opts.type ? ` of type "${opts.type}"` : ""}`,
            ),
          );
        }
      } catch (err) {
        console.error(
          chalk.red(
            `Error: ${err instanceof Error ? err.message : String(err)}`,
          ),
        );
        process.exit(1);
      }
    },
  );

// ─── coverage ─────────────────────────────────────────────────
program
  .command("coverage")
  .description("Measure how much of model A is covered by model B")
  .argument(
    "<reference>",
    "Path to reference model (the spec / source of truth)",
  )
  .argument("<target>", "Path to target model (what's being measured)")
  .option("--json", "Output as JSON")
  .action(
    async (
      refPath: string,
      tgtPath: string,
      opts: Record<string, boolean | undefined>,
    ) => {
      try {
        const ref = await readModel(refPath);
        const tgt = await readModel(tgtPath);
        const result = coverageFn(ref, tgt);

        if (opts.json) {
          console.log(JSON.stringify(result, null, 2));
          return;
        }

        const bar = (pct: number) => {
          const filled = Math.round(pct * 20);
          return (
            chalk.green("█".repeat(filled)) +
            chalk.gray("░".repeat(20 - filled))
          );
        };

        console.log(chalk.blue(`■ Coverage: ${ref.name} → ${tgt.name}\n`));
        console.log(
          `  Overall:     ${bar(result.overall)} ${Math.round(result.overall * 100)}%`,
        );
        console.log(
          `  Entities:    ${bar(result.entityCoverage)} ${Math.round(result.entityCoverage * 100)}%`,
        );
        console.log(
          `  Relations:   ${bar(result.relationCoverage)} ${Math.round(result.relationCoverage * 100)}%`,
        );
        console.log(
          `  Processes:   ${bar(result.processCoverage)} ${Math.round(result.processCoverage * 100)}%`,
        );
        console.log(
          `  Constraints: ${bar(result.constraintCoverage)} ${Math.round(result.constraintCoverage * 100)}%`,
        );

        if (result.missingEntities.length > 0) {
          console.log(
            chalk.red(
              `\n  Missing entities (${result.missingEntities.length}):`,
            ),
          );
          for (const name of result.missingEntities)
            console.log(chalk.red(`    - ${name}`));
        }
        if (result.extraEntities.length > 0) {
          console.log(
            chalk.yellow(
              `\n  Extra entities in target (${result.extraEntities.length}):`,
            ),
          );
          for (const name of result.extraEntities)
            console.log(chalk.yellow(`    + ${name}`));
        }
        if (result.missingProcesses.length > 0) {
          console.log(
            chalk.red(
              `\n  Missing processes: ${result.missingProcesses.join(", ")}`,
            ),
          );
        }
        if (result.missingConstraints.length > 0) {
          console.log(
            chalk.red(
              `\n  Missing constraints: ${result.missingConstraints.join(", ")}`,
            ),
          );
        }
      } catch (err) {
        console.error(
          chalk.red(
            `Error: ${err instanceof Error ? err.message : String(err)}`,
          ),
        );
        process.exit(1);
      }
    },
  );

// ─── processes ────────────────────────────────────────────────
program
  .command("processes")
  .description("List all processes with their steps")
  .argument("<model>", "Path to world model JSON")
  .option("--json", "Output as JSON array")
  .action(
    async (modelPath: string, opts: Record<string, boolean | undefined>) => {
      try {
        const model = await readModel(modelPath);
        if (opts.json) {
          console.log(JSON.stringify(model.processes, null, 2));
          return;
        }
        if (model.processes.length === 0) {
          console.log(chalk.gray("  No processes in this model."));
          return;
        }
        for (const proc of model.processes) {
          console.log(chalk.bold(`  ${proc.name}`));
          console.log(chalk.gray(`  ${proc.description}`));
          if (proc.trigger)
            console.log(chalk.gray(`  Trigger: ${proc.trigger}`));
          console.log("");
          for (const step of proc.steps) {
            const actor = step.actor
              ? (model.entities.find((e) => e.id === step.actor)?.name ?? "?")
              : "system";
            console.log(
              `    ${step.order}. ${chalk.cyan(actor)}: ${step.action}`,
            );
          }
          if (proc.outcomes.length > 0) {
            console.log(
              chalk.gray(`\n    Outcomes: ${proc.outcomes.join(", ")}`),
            );
          }
          console.log("");
        }
        console.error(
          chalk.gray(
            `  ${model.processes.length} processes, ${model.processes.reduce((a, p) => a + p.steps.length, 0)} total steps`,
          ),
        );
      } catch (err) {
        console.error(
          chalk.red(
            `Error: ${err instanceof Error ? err.message : String(err)}`,
          ),
        );
        process.exit(1);
      }
    },
  );

// ─── subgraph ─────────────────────────────────────────────────
program
  .command("subgraph")
  .description("Extract a subgraph centered on an entity (zoom in)")
  .argument("<model>", "Path to world model JSON")
  .argument("<entity>", "Entity name to center on")
  .option("-n, --hops <n>", "Max hops from center entity", "2")
  .option("-o, --output <path>", "Write subgraph to file")
  .option(
    "--format <format>",
    "Output format: json, yaml, mermaid, dot",
    "json",
  )
  .action(
    async (
      modelPath: string,
      entityName: string,
      opts: Record<string, string | undefined>,
    ) => {
      try {
        const model = await readModel(modelPath);
        const entity = findEntity(model, entityName);
        if (!entity) {
          console.error(chalk.red(`Entity "${entityName}" not found.`));
          process.exit(1);
        }
        const hops = parseInt(opts.hops ?? "2", 10) || 2;
        const sub = subgraph(model, entity.id, hops);
        const output = formatOutput(sub, opts.format ?? "json", true);

        if (opts.output) {
          writeFileSync(resolve(opts.output), output, "utf-8");
          console.error(chalk.green(`✓ Subgraph written to ${opts.output}`));
        } else {
          console.log(output);
        }
        console.error(
          chalk.gray(
            `  ${sub.entities.length} entities, ${sub.relations.length} relations within ${hops} hops of "${entity.name}"`,
          ),
        );
      } catch (err) {
        console.error(
          chalk.red(
            `Error: ${err instanceof Error ? err.message : String(err)}`,
          ),
        );
        process.exit(1);
      }
    },
  );

// ─── fix ──────────────────────────────────────────────────────
program
  .command("fix")
  .description(
    "Auto-fix validation issues (remove orphans, dangling refs, duplicates)",
  )
  .argument("<model>", "Path to world model JSON")
  .option(
    "-o, --output <path>",
    "Write fixed model to file (default: overwrite input)",
  )
  .option("--dry-run", "Show what would be fixed without writing")
  .action(
    async (
      modelPath: string,
      opts: Record<string, string | boolean | undefined>,
    ) => {
      try {
        const model = await readModel(modelPath);
        const { fixWorldModel } = await import("./utils/fix.js");
        const { model: fixed, fixes } = fixWorldModel(model);

        if (fixes.length === 0) {
          console.log(chalk.green("  No issues to fix."));
          return;
        }

        console.log(chalk.blue("■ Fixes applied:\n"));
        for (const fix of fixes) console.log(chalk.yellow(`  ✓ ${fix}`));

        console.log(
          chalk.gray(
            `\n  Before: ${model.entities.length} entities, ${model.relations.length} relations`,
          ),
        );
        console.log(
          chalk.gray(
            `  After:  ${fixed.entities.length} entities, ${fixed.relations.length} relations`,
          ),
        );

        if (opts.dryRun) {
          console.log(chalk.gray("\n  (dry run — no files written)"));
          return;
        }

        const outPath = (opts.output as string) ?? modelPath;
        writeFileSync(
          resolve(outPath),
          JSON.stringify(fixed, null, 2),
          "utf-8",
        );
        console.log(chalk.green(`\n  ✓ Written to ${outPath}`));
      } catch (err) {
        console.error(
          chalk.red(
            `Error: ${err instanceof Error ? err.message : String(err)}`,
          ),
        );
        process.exit(1);
      }
    },
  );

// ─── constraints ──────────────────────────────────────────────
program
  .command("constraints")
  .description("List all constraints with scoped entities")
  .argument("<model>", "Path to world model JSON")
  .option("-s, --severity <severity>", "Filter by severity: hard or soft")
  .option("--json", "Output as JSON array")
  .action(
    async (
      modelPath: string,
      opts: Record<string, string | boolean | undefined>,
    ) => {
      try {
        const model = await readModel(modelPath);
        let constraints = model.constraints;
        if (opts.severity) {
          constraints = constraints.filter((c) => c.severity === opts.severity);
        }
        if (opts.json) {
          console.log(JSON.stringify(constraints, null, 2));
          return;
        }
        if (constraints.length === 0) {
          console.log(chalk.gray("  No constraints in this model."));
          return;
        }
        for (const c of constraints) {
          const icon =
            c.severity === "hard" ? chalk.red("■") : chalk.yellow("□");
          const scopeNames = c.scope
            .map((id) => model.entities.find((e) => e.id === id)?.name ?? id)
            .join(", ");
          console.log(
            `  ${icon} ${chalk.bold(c.name)} ${chalk.gray(`[${c.severity}]`)}`,
          );
          console.log(chalk.white(`    ${c.description}`));
          if (scopeNames)
            console.log(chalk.gray(`    Applies to: ${scopeNames}`));
        }
        const hard = constraints.filter((c) => c.severity === "hard").length;
        const soft = constraints.filter((c) => c.severity === "soft").length;
        console.error(
          chalk.gray(
            `\n  ${constraints.length} constraints (${hard} hard, ${soft} soft)`,
          ),
        );
      } catch (err) {
        console.error(
          chalk.red(
            `Error: ${err instanceof Error ? err.message : String(err)}`,
          ),
        );
        process.exit(1);
      }
    },
  );

// ─── search ───────────────────────────────────────────────────
program
  .command("search")
  .description("Full-text search across all elements of a world model")
  .argument("<model>", "Path to world model JSON")
  .argument("<query>", "Search term (case-insensitive)")
  .action(async (modelPath: string, query: string) => {
    try {
      const model = await readModel(modelPath);
      const q = query.toLowerCase();
      let found = 0;

      const matchingEntities = model.entities.filter(
        (e) =>
          e.name.toLowerCase().includes(q) ||
          e.description.toLowerCase().includes(q),
      );
      if (matchingEntities.length > 0) {
        console.log(chalk.blue(`\n  Entities (${matchingEntities.length}):`));
        for (const e of matchingEntities) {
          console.log(
            `    [${e.type}] ${chalk.bold(e.name)}: ${e.description}`,
          );
        }
        found += matchingEntities.length;
      }

      const matchingRelations = model.relations.filter((r) => {
        const src = model.entities.find((e) => e.id === r.source)?.name ?? "";
        const tgt = model.entities.find((e) => e.id === r.target)?.name ?? "";
        return (
          r.label.toLowerCase().includes(q) ||
          r.type.includes(q) ||
          src.toLowerCase().includes(q) ||
          tgt.toLowerCase().includes(q)
        );
      });
      if (matchingRelations.length > 0) {
        console.log(chalk.blue(`\n  Relations (${matchingRelations.length}):`));
        for (const r of matchingRelations) {
          const src =
            model.entities.find((e) => e.id === r.source)?.name ?? r.source;
          const tgt =
            model.entities.find((e) => e.id === r.target)?.name ?? r.target;
          console.log(`    ${src} —[${r.type}]→ ${tgt}: ${r.label}`);
        }
        found += matchingRelations.length;
      }

      const matchingProcesses = model.processes.filter(
        (p) =>
          p.name.toLowerCase().includes(q) ||
          p.description.toLowerCase().includes(q) ||
          p.steps.some((s) => s.action.toLowerCase().includes(q)),
      );
      if (matchingProcesses.length > 0) {
        console.log(chalk.blue(`\n  Processes (${matchingProcesses.length}):`));
        for (const p of matchingProcesses) {
          console.log(`    ${chalk.bold(p.name)}: ${p.description}`);
        }
        found += matchingProcesses.length;
      }

      const matchingConstraints = model.constraints.filter(
        (c) =>
          c.name.toLowerCase().includes(q) ||
          c.description.toLowerCase().includes(q),
      );
      if (matchingConstraints.length > 0) {
        console.log(
          chalk.blue(`\n  Constraints (${matchingConstraints.length}):`),
        );
        for (const c of matchingConstraints) {
          console.log(
            `    [${c.severity}] ${chalk.bold(c.name)}: ${c.description}`,
          );
        }
        found += matchingConstraints.length;
      }

      if (found === 0) {
        console.log(chalk.gray(`  No matches for "${query}".`));
      } else {
        console.error(chalk.gray(`\n  ${found} matches for "${query}"`));
      }
    } catch (err) {
      console.error(
        chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`),
      );
      process.exit(1);
    }
  });

// ─── clusters ─────────────────────────────────────────────────
program
  .command("clusters")
  .description("Find natural clusters (connected components) in a world model")
  .argument("<model>", "Path to world model JSON")
  .option("--json", "Output as JSON array")
  .action(
    async (modelPath: string, opts: Record<string, boolean | undefined>) => {
      try {
        const model = await readModel(modelPath);
        const clusters = findClusters(model);

        if (opts.json) {
          console.log(
            JSON.stringify(
              clusters.map((c) => ({
                name: c.name,
                entities: c.entities.map((e) => e.name),
                internalRelations: c.internalRelations,
                externalRelations: c.externalRelations,
              })),
              null,
              2,
            ),
          );
          return;
        }

        if (clusters.length === 0) {
          console.log(chalk.gray("  No entities to cluster."));
          return;
        }

        console.log(
          chalk.blue(
            `■ ${clusters.length} cluster${clusters.length > 1 ? "s" : ""} found\n`,
          ),
        );
        for (const cluster of clusters) {
          console.log(
            chalk.bold(
              `  ${cluster.name} (${cluster.entities.length} entities)`,
            ),
          );
          console.log(
            chalk.gray(
              `    Internal relations: ${cluster.internalRelations} | External: ${cluster.externalRelations}`,
            ),
          );
          for (const e of cluster.entities) {
            console.log(`    - [${e.type}] ${e.name}`);
          }
          console.log("");
        }
      } catch (err) {
        console.error(
          chalk.red(
            `Error: ${err instanceof Error ? err.message : String(err)}`,
          ),
        );
        process.exit(1);
      }
    },
  );

// ─── transform ────────────────────────────────────────────────
program
  .command("transform")
  .description("Apply a natural language transformation to a world model")
  .argument("<model>", "Path to world model JSON")
  .argument("<instruction>", "What to change (natural language)")
  .option("-o, --output <path>", "Write transformed model to file")
  .action(
    async (
      modelPath: string,
      instruction: string,
      opts: Record<string, string | undefined>,
    ) => {
      try {
        const model = await readModel(modelPath);
        console.error(chalk.blue("■ Transforming world model"));
        console.error(chalk.gray(`  Instruction: ${instruction}\n`));

        const { transformWorldModel } = await import("./agents/transform.js");
        const { model: transformed, changes } = await transformWorldModel(
          model,
          instruction,
        );

        if (changes.length === 0) {
          console.error(chalk.yellow("  No changes applied."));
        } else {
          for (const c of changes) console.error(chalk.yellow(`  ✓ ${c}`));
        }

        console.error(
          chalk.gray(
            `\n  Before: ${model.entities.length} entities, ${model.relations.length} relations`,
          ),
        );
        console.error(
          chalk.gray(
            `  After:  ${transformed.entities.length} entities, ${transformed.relations.length} relations`,
          ),
        );

        const output = JSON.stringify(transformed, null, 2);
        if (opts.output) {
          writeFileSync(resolve(opts.output), output, "utf-8");
          console.error(chalk.green(`\n  ✓ Written to ${opts.output}`));
        } else {
          console.log(output);
        }
      } catch (err) {
        console.error(
          chalk.red(
            `Error: ${err instanceof Error ? err.message : String(err)}`,
          ),
        );
        process.exit(1);
      }
    },
  );

// ─── stats ────────────────────────────────────────────────────
program
  .command("stats")
  .description("Quick dashboard comparing one or more world models")
  .argument("<models...>", "Paths to world model JSON files")
  .action(async (modelPaths: string[]) => {
    try {
      const pad = (s: string, n: number) =>
        s.length >= n ? s.slice(0, n) : s + " ".repeat(n - s.length);

      const { validationAgent: va } = await import("./agents/validation.js");

      console.log(chalk.blue("■ World Model Dashboard\n"));
      console.log(
        chalk.gray(
          `  ${pad("Model", 30)} ${pad("Ent", 6)} ${pad("Rel", 6)} ${pad("Proc", 6)} ${pad("Cstr", 6)} ${pad("Conf", 6)} ${pad("Score", 6)}`,
        ),
      );
      console.log(chalk.gray("  " + "─".repeat(72)));

      for (const p of modelPaths) {
        const model = await readModel(p);
        const { validation } = await va({
          input: { raw: "", sourceType: "text" },
          worldModel: model,
        });
        const name =
          model.name.length > 28 ? model.name.slice(0, 27) + "…" : model.name;
        const conf =
          model.metadata?.confidence !== undefined
            ? `${Math.round(model.metadata.confidence * 100)}%`
            : "—";
        const scoreStr =
          validation.score !== undefined ? `${validation.score}` : "—";
        console.log(
          `  ${pad(name, 30)} ${pad(String(model.entities.length), 6)} ${pad(String(model.relations.length), 6)} ${pad(String(model.processes.length), 6)} ${pad(String(model.constraints.length), 6)} ${pad(conf, 6)} ${pad(scoreStr, 6)}`,
        );
      }
    } catch (err) {
      console.error(
        chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`),
      );
      process.exit(1);
    }
  });

// ─── help ─────────────────────────────────────────────────────
program
  .command("help")
  .description("Show grouped command reference")
  .action(() => {
    const g = chalk.gray;
    const b = chalk.bold;
    const c = chalk.cyan;
    console.log(b("\n  Structured World Model — Command Reference\n"));
    console.log(b("  Build"));
    console.log(
      `    ${c("model")} [input]         Build a world model from text, file, URL, or stdin`,
    );
    console.log(
      `    ${c("refine")} <model> [input] Incrementally refine with new input`,
    );
    console.log(
      `    ${c("transform")} <model> <instruction>  Apply natural language transformation`,
    );
    console.log("");
    console.log(b("  Inspect"));
    console.log(
      `    ${c("inspect")} <model>        Stats, entity lookup, graph export`,
    );
    console.log(
      `    ${c("summary")} <model>        One-line natural language summary`,
    );
    console.log(
      `    ${c("entities")} <model>       List entities (filterable by type)`,
    );
    console.log(
      `    ${c("relations")} <model>      List relations (filterable by type)`,
    );
    console.log(`    ${c("processes")} <model>      List processes with steps`);
    console.log(
      `    ${c("constraints")} <model>    List constraints with scoped entities`,
    );
    console.log(
      `    ${c("search")} <model> <query> Full-text search across all elements`,
    );
    console.log(
      `    ${c("clusters")} <model>       Find natural entity groups`,
    );
    console.log(
      `    ${c("subgraph")} <model> <entity>  Extract neighborhood around an entity`,
    );
    console.log(
      `    ${c("validate")} <model>       Full integrity check (exits 1 on errors)`,
    );
    console.log(
      `    ${c("fix")} <model>            Auto-fix validation issues`,
    );
    console.log(
      `    ${c("impact")} <model> <entity>  What breaks if you remove an entity`,
    );
    console.log(
      `    ${c("stats")} <models...>      Multi-model comparison table with scores`,
    );
    console.log(
      `    ${c("schema")}                 Output WorldModel JSON Schema`,
    );
    console.log("");
    console.log(b("  Compose"));
    console.log(
      `    ${c("merge")} <a> <b>          Union two models (dedup entities)`,
    );
    console.log(
      `    ${c("diff")} <before> <after>  What changed between two models`,
    );
    console.log(
      `    ${c("compare")} <a> <b>        Find semantic conflicts (type/severity disagreements)`,
    );
    console.log(
      `    ${c("intersect")} <a> <b>      Entities shared by both models`,
    );
    console.log(
      `    ${c("subtract")} <a> <b>       Entities in A but not in B`,
    );
    console.log(
      `    ${c("overlay")} <base> <lens>  Apply constraints/relations from lens onto base`,
    );
    console.log(
      `    ${c("coverage")} <ref> <target>  How much of ref is covered by target`,
    );
    console.log("");
    console.log(b("  Track"));
    console.log(
      `    ${c("snapshot")} <model>       Add to timeline (auto-diffs from previous)`,
    );
    console.log(
      `    ${c("history")} <timeline>     Show evolution or entity history`,
    );
    console.log("");
    console.log(b("  Export"));
    console.log(
      `    ${c("export")} <model> --as <fmt>  Export as claude-md, system-prompt, or mcp`,
    );
    console.log(
      `    ${c("mcp-config")} <model>     Generate MCP client config snippet`,
    );
    console.log("");
    console.log(b("  Serve"));
    console.log(
      `    ${c("serve")} <model>          Start MCP server with 9 live queryable tools`,
    );
    console.log("");
    console.log(b("  Query"));
    console.log(
      `    ${c("query")} <model> <question>  Natural language queries (10 graph patterns + LLM)`,
    );
    console.log("");
    console.log(
      g(
        "  All commands accepting <model> support - for stdin: cat m.json | swm summary -",
      ),
    );
    console.log(g("  Use swm <command> --help for detailed options\n"));
  });

// ─── impact ───────────────────────────────────────────────────
program
  .command("impact")
  .description("Analyze what breaks if an entity is removed")
  .argument("<model>", "Path to world model JSON")
  .argument("<entity>", "Entity name to analyze")
  .option("--json", "Output as JSON")
  .action(
    async (
      modelPath: string,
      entityName: string,
      opts: Record<string, boolean | undefined>,
    ) => {
      try {
        const model = await readModel(modelPath);
        const entity = findEntity(model, entityName);
        if (!entity) {
          console.error(chalk.red(`Entity "${entityName}" not found.`));
          process.exit(1);
        }

        const result = analyzeImpact(model, entity.id);
        if (!result) {
          console.error(chalk.red("Analysis failed."));
          process.exit(1);
        }

        if (opts.json) {
          console.log(JSON.stringify(result, null, 2));
          return;
        }

        const sevColor =
          result.severity === "critical"
            ? chalk.red
            : result.severity === "high"
              ? chalk.red
              : result.severity === "medium"
                ? chalk.yellow
                : chalk.green;
        console.log(
          chalk.blue(`■ Impact Analysis: removing "${entity.name}"\n`),
        );
        console.log(sevColor(`  Severity: ${result.severity.toUpperCase()}\n`));

        if (result.brokenRelations.length > 0) {
          console.log(
            chalk.gray(
              `  Broken relations (${result.brokenRelations.length}):`,
            ),
          );
          for (const r of result.brokenRelations) {
            const src =
              model.entities.find((e) => e.id === r.source)?.name ?? r.source;
            const tgt =
              model.entities.find((e) => e.id === r.target)?.name ?? r.target;
            console.log(`    ${src} —[${r.type}]→ ${tgt}`);
          }
        }
        if (result.dependents.length > 0) {
          console.log(
            chalk.gray(`\n  Dependents (${result.dependents.length}):`),
          );
          for (const d of result.dependents)
            console.log(`    ${d.name} (${d.type})`);
        }
        if (result.affectedProcesses.length > 0) {
          console.log(
            chalk.gray(
              `\n  Affected processes (${result.affectedProcesses.length}):`,
            ),
          );
          for (const ap of result.affectedProcesses)
            console.log(`    ${ap.process.name} (${ap.role})`);
        }
        if (result.affectedConstraints.length > 0) {
          console.log(
            chalk.gray(
              `\n  Affected constraints (${result.affectedConstraints.length}):`,
            ),
          );
          for (const c of result.affectedConstraints)
            console.log(`    [${c.severity}] ${c.name}`);
        }
        console.log(chalk.gray(`\n  ${result.summary}`));
      } catch (err) {
        console.error(
          chalk.red(
            `Error: ${err instanceof Error ? err.message : String(err)}`,
          ),
        );
        process.exit(1);
      }
    },
  );

// ─── compare ──────────────────────────────────────────────────
program
  .command("compare")
  .description("Find semantic conflicts between two models of the same domain")
  .argument("<modelA>", "Path to first world model JSON")
  .argument("<modelB>", "Path to second world model JSON")
  .option("--json", "Output as JSON")
  .action(
    async (
      pathA: string,
      pathB: string,
      opts: Record<string, boolean | undefined>,
    ) => {
      try {
        const a = await readModel(pathA);
        const b = await readModel(pathB);
        const { compare } = await import("./utils/compare.js");
        const result = compare(a, b);

        if (opts.json) {
          console.log(JSON.stringify(result, null, 2));
          return;
        }

        console.log(
          chalk.blue(`■ Semantic Comparison: ${a.name} vs ${b.name}\n`),
        );
        console.log(`  ${result.summary}\n`);

        if (result.conflicts.length > 0) {
          for (const c of result.conflicts) {
            console.log(
              chalk.yellow(`  ✗ ${c.kind.replace(/_/g, " ")}: ${c.element}`),
            );
            console.log(chalk.gray(`    ${a.name}: ${c.modelA}`));
            console.log(chalk.gray(`    ${b.name}: ${c.modelB}`));
          }
        }
      } catch (err) {
        console.error(
          chalk.red(
            `Error: ${err instanceof Error ? err.message : String(err)}`,
          ),
        );
        process.exit(1);
      }
    },
  );

// ─── mcp-config ───────────────────────────────────────────────
program
  .command("mcp-config")
  .description(
    "Generate MCP client config snippet for Claude Desktop / VS Code",
  )
  .argument("<model>", "Path to world model JSON")
  .action(async (modelPath: string) => {
    try {
      const absModel = resolve(modelPath);
      if (!existsSync(absModel)) {
        console.error(chalk.red(`File not found: ${absModel}`));
        process.exit(1);
      }
      const model = await readModel(modelPath);
      const serverName = `swm-${model.name
        .toLowerCase()
        .replace(/[^a-z0-9]/g, "-")
        .replace(/-+/g, "-")}`;

      const config = {
        mcpServers: {
          [serverName]: {
            command: "npx",
            args: ["tsx", resolve("src/cli.ts"), "serve", absModel],
          },
        },
      };

      console.log(chalk.blue(`■ MCP Configuration for "${model.name}"\n`));
      console.log(
        chalk.gray(
          "  Add to claude_desktop_config.json or .vscode/mcp.json:\n",
        ),
      );
      console.log(JSON.stringify(config, null, 2));
      console.log(chalk.gray(`\n  Server: ${serverName}`));
      console.log(
        chalk.gray(
          `  Tools: get_entity, get_relations, find_path, get_process, check_constraint, query, get_stats, get_diagram, analyze_impact`,
        ),
      );
      console.log(
        chalk.gray(
          `  Model: ${model.entities.length} entities, ${model.relations.length} relations`,
        ),
      );
    } catch (err) {
      console.error(
        chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`),
      );
      process.exit(1);
    }
  });

program.parse();

// === src/export/claude-md.ts ===
import type { WorldModelType } from "../schema/index.js";

/**
 * Export a world model as a CLAUDE.md file — a governing context document
 * that an AI agent can use as its operating reality.
 */
export function toClaudeMd(model: WorldModelType): string {
  const lines: string[] = [];

  lines.push(`# ${model.name}`);
  lines.push("");
  lines.push(model.description);
  lines.push("");
  lines.push(
    `> World model v${model.version} — ${model.entities.length} entities, ${model.relations.length} relations, ${model.processes.length} processes, ${model.constraints.length} constraints`,
  );
  lines.push(`> Confidence: ${model.metadata?.confidence ?? "unknown"}`);
  lines.push("");

  // ─── Domain Entities ────────────────────────────────────
  lines.push("## Domain Entities");
  lines.push("");
  lines.push("The system you are working with has these components:");
  lines.push("");

  const byType = new Map<string, WorldModelType["entities"]>();
  for (const e of model.entities) {
    const arr = byType.get(e.type) ?? [];
    arr.push(e);
    byType.set(e.type, arr);
  }

  for (const [type, entities] of byType) {
    lines.push(`### ${type.charAt(0).toUpperCase() + type.slice(1)}s`);
    lines.push("");
    for (const e of entities) {
      lines.push(`- **${e.name}**: ${e.description}`);
      if (e.properties && Object.keys(e.properties).length > 0) {
        for (const [k, v] of Object.entries(e.properties)) {
          lines.push(`  - ${k}: ${JSON.stringify(v)}`);
        }
      }
    }
    lines.push("");
  }

  // ─── Relationships ──────────────────────────────────────
  lines.push("## Relationships");
  lines.push("");
  lines.push("These are the dependencies and connections between components:");
  lines.push("");

  for (const r of model.relations) {
    const src = model.entities.find((e) => e.id === r.source)?.name ?? r.source;
    const tgt = model.entities.find((e) => e.id === r.target)?.name ?? r.target;
    lines.push(
      `- **${src}** ${r.type.replace(/_/g, " ")} **${tgt}**: ${r.label}`,
    );
  }
  lines.push("");

  // ─── Processes ──────────────────────────────────────────
  if (model.processes.length > 0) {
    lines.push("## Processes");
    lines.push("");
    lines.push("When these events occur, follow these sequences:");
    lines.push("");

    for (const p of model.processes) {
      lines.push(`### ${p.name}`);
      lines.push("");
      lines.push(p.description);
      if (p.trigger) {
        lines.push(`**Trigger:** ${p.trigger}`);
      }
      lines.push("");

      for (const step of p.steps) {
        const actor = step.actor
          ? (model.entities.find((e) => e.id === step.actor)?.name ?? "unknown")
          : "system";
        lines.push(`${step.order}. **${actor}**: ${step.action}`);
      }
      lines.push("");

      if (p.outcomes.length > 0) {
        lines.push(`**Outcomes:** ${p.outcomes.join(", ")}`);
        lines.push("");
      }
    }
  }

  // ─── Constraints ────────────────────────────────────────
  if (model.constraints.length > 0) {
    lines.push("## Constraints");
    lines.push("");
    lines.push("You MUST respect these rules at all times:");
    lines.push("");

    const hard = model.constraints.filter((c) => c.severity === "hard");
    const soft = model.constraints.filter((c) => c.severity === "soft");

    if (hard.length > 0) {
      lines.push("### Hard Constraints (violations are errors)");
      lines.push("");
      for (const c of hard) {
        const scopeNames = c.scope
          .map((id) => model.entities.find((e) => e.id === id)?.name ?? id)
          .join(", ");
        lines.push(
          `- **${c.name}** (applies to: ${scopeNames}): ${c.description}`,
        );
      }
      lines.push("");
    }

    if (soft.length > 0) {
      lines.push("### Soft Constraints (violations are warnings)");
      lines.push("");
      for (const c of soft) {
        const scopeNames = c.scope
          .map((id) => model.entities.find((e) => e.id === id)?.name ?? id)
          .join(", ");
        lines.push(
          `- **${c.name}** (applies to: ${scopeNames}): ${c.description}`,
        );
      }
      lines.push("");
    }
  }

  // ─── Extraction Notes ───────────────────────────────────
  if (
    model.metadata?.extraction_notes &&
    model.metadata.extraction_notes.length > 0
  ) {
    lines.push("## Notes");
    lines.push("");
    lines.push("The following observations were made during model extraction:");
    lines.push("");
    for (const note of model.metadata.extraction_notes) {
      lines.push(`- ${note}`);
    }
    lines.push("");
  }

  return lines.join("\n");
}

// === src/export/index.ts ===
export { toClaudeMd } from "./claude-md.js";
export { toSystemPrompt } from "./system-prompt.js";
export { toMcpSchema } from "./mcp-schema.js";

// === src/export/mcp-schema.ts ===
import type { WorldModelType } from "../schema/index.js";

interface MCPTool {
  name: string;
  description: string;
  inputSchema: {
    type: "object";
    properties: Record<
      string,
      { type: string; description: string; enum?: string[] }
    >;
    required: string[];
  };
}

interface MCPSchema {
  name: string;
  description: string;
  tools: MCPTool[];
}

/**
 * Export a world model as MCP tool definitions.
 * Each entity type gets query tools. Each process gets an execution tool.
 * Constraints become validation tools.
 */
export function toMcpSchema(model: WorldModelType): MCPSchema {
  const tools: MCPTool[] = [];

  // ─── Entity lookup tool ─────────────────────────────────
  const entityNames = model.entities.map((e) => e.name);
  tools.push({
    name: "get_entity",
    description: `Look up a domain entity by name. Available entities: ${entityNames.slice(0, 10).join(", ")}${entityNames.length > 10 ? ` and ${entityNames.length - 10} more` : ""}`,
    inputSchema: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "Name of the entity to look up",
          enum: entityNames,
        },
      },
      required: ["name"],
    },
  });

  // ─── Relation query tool ────────────────────────────────
  tools.push({
    name: "get_relations",
    description:
      "Get all relations for a given entity — what it depends on, what depends on it",
    inputSchema: {
      type: "object",
      properties: {
        entity: {
          type: "string",
          description: "Name of the entity",
          enum: entityNames,
        },
        direction: {
          type: "string",
          description: "Direction of relations to query",
          enum: ["incoming", "outgoing", "both"],
        },
      },
      required: ["entity"],
    },
  });

  // ─── Process execution tools ────────────────────────────
  for (const proc of model.processes) {
    const participantNames = proc.participants.map(
      (id) => model.entities.find((e) => e.id === id)?.name ?? id,
    );

    tools.push({
      name: `process_${proc.name.toLowerCase().replace(/[^a-z0-9]/g, "_")}`,
      description: `${proc.description}. Participants: ${participantNames.join(", ")}. ${proc.steps.length} steps.${proc.trigger ? ` Triggered by: ${proc.trigger}` : ""}`,
      inputSchema: {
        type: "object",
        properties: {
          step: {
            type: "string",
            description: `Which step to query or execute (1-${proc.steps.length})`,
          },
          context: {
            type: "string",
            description: "Additional context for this process invocation",
          },
        },
        required: [],
      },
    });
  }

  // ─── Constraint validation tool ─────────────────────────
  if (model.constraints.length > 0) {
    const constraintNames = model.constraints.map((c) => c.name);
    tools.push({
      name: "check_constraint",
      description:
        "Validate whether an action or state violates a domain constraint",
      inputSchema: {
        type: "object",
        properties: {
          constraint: {
            type: "string",
            description: "Name of the constraint to check",
            enum: constraintNames,
          },
          action: {
            type: "string",
            description:
              "Description of the action or state to validate against the constraint",
          },
        },
        required: ["constraint", "action"],
      },
    });
  }

  // ─── Query tool ─────────────────────────────────────────
  tools.push({
    name: "query_world_model",
    description: "Ask a natural language question about the domain model",
    inputSchema: {
      type: "object",
      properties: {
        question: {
          type: "string",
          description: "Natural language question about the domain",
        },
      },
      required: ["question"],
    },
  });

  return {
    name: model.name.toLowerCase().replace(/[^a-z0-9]/g, "-"),
    description: `MCP server for ${model.name}: ${model.description}`,
    tools,
  };
}

// === src/export/system-prompt.ts ===
import type { WorldModelType } from "../schema/index.js";

/**
 * Export a world model as a system prompt that makes an LLM
 * "an expert in this world."
 */
export function toSystemPrompt(model: WorldModelType): string {
  const entityList = model.entities
    .map((e) => `- ${e.name} (${e.type}): ${e.description}`)
    .join("\n");

  const relationList = model.relations
    .map((r) => {
      const src =
        model.entities.find((e) => e.id === r.source)?.name ?? r.source;
      const tgt =
        model.entities.find((e) => e.id === r.target)?.name ?? r.target;
      return `- ${src} ${r.type.replace(/_/g, " ")} ${tgt}`;
    })
    .join("\n");

  const processDescriptions = model.processes
    .map((p) => {
      const steps = p.steps
        .map((s) => {
          const actor = s.actor
            ? (model.entities.find((e) => e.id === s.actor)?.name ?? "unknown")
            : "system";
          return `  ${s.order}. ${actor}: ${s.action}`;
        })
        .join("\n");
      const trigger = p.trigger ? `\n  Trigger: ${p.trigger}` : "";
      return `${p.name}: ${p.description}${trigger}\n${steps}`;
    })
    .join("\n\n");

  const constraintList = model.constraints
    .map((c) => {
      const scopeNames = c.scope
        .map((id) => model.entities.find((e) => e.id === id)?.name ?? id)
        .join(", ");
      return `- [${c.severity.toUpperCase()}] ${c.name} (${scopeNames}): ${c.description}`;
    })
    .join("\n");

  return `You are an expert on the domain: ${model.name}.

${model.description}

You have complete knowledge of this domain's structure. Answer questions accurately based on the following world model. Do not speculate beyond what the model defines — if something isn't represented, say so.

ENTITIES (${model.entities.length}):
${entityList}

RELATIONSHIPS (${model.relations.length}):
${relationList}

PROCESSES (${model.processes.length}):
${processDescriptions}

CONSTRAINTS (${model.constraints.length}):
${constraintList}

When answering:
- Reference entities by their exact names
- Respect all HARD constraints as absolute rules
- Treat SOFT constraints as strong preferences
- Trace processes step-by-step when asked about workflows
- Identify which entities are involved when answering about any topic`;
}

// === src/index.ts ===
export { buildWorldModel } from "./swm.js";
export type { SWMOptions } from "./swm.js";
export { Pipeline } from "./pipeline/index.js";
export type { PipelineInput, PipelineResult } from "./pipeline/index.js";
export type { WorldModelType, ValidationResultType } from "./schema/index.js";

// Agents
export { refineWorldModel } from "./agents/refinement.js";
export { queryWorldModel } from "./agents/query.js";
export type { QueryResult } from "./agents/query.js";
export { transformWorldModel } from "./agents/transform.js";

// Graph operations
export {
  findEntity,
  findDependents,
  pathsBetween,
  toMermaid,
  toDot,
  getStats,
  summarize,
  subgraph,
  findClusters,
  analyzeImpact,
} from "./utils/graph.js";
export type { ImpactAnalysis } from "./utils/graph.js";
export type { Cluster } from "./utils/graph.js";

// Merge & diff
export { mergeWorldModels, diffWorldModels } from "./utils/merge.js";
export type { WorldModelDiff } from "./utils/merge.js";

// Compare
export { compare } from "./utils/compare.js";
export type { CompareResult, Conflict } from "./utils/compare.js";

// Algebra
export { intersection, difference, overlay } from "./utils/algebra.js";

// Coverage
export { coverage } from "./utils/coverage.js";
export type { CoverageResult } from "./utils/coverage.js";

// Fix
export { fixWorldModel } from "./utils/fix.js";
export type { FixResult } from "./utils/fix.js";

// Export formats
export { toClaudeMd } from "./export/claude-md.js";
export { toSystemPrompt } from "./export/system-prompt.js";
export { toMcpSchema } from "./export/mcp-schema.js";
export { getWorldModelJsonSchema } from "./schema/json-schema.js";

// Timeline
export {
  createTimeline,
  addSnapshot,
  entityHistory,
  timelineSummary,
} from "./utils/timeline.js";
export type { Timeline, Snapshot } from "./utils/timeline.js";

// === src/pipeline/index.ts ===
export { Pipeline } from "./pipeline.js";
export type {
  PipelineInput,
  PipelineResult,
  PipelineStageResult,
  PipelineStage,
  StageHandler,
} from "./pipeline.js";

// === src/pipeline/pipeline.ts ===
import type { WorldModelType, ValidationResultType } from "../schema/index.js";

export interface PipelineInput {
  raw: string;
  sourceType: "text" | "document" | "url" | "code" | "conversation" | "mixed";
  name?: string;
}

export interface PipelineStageResult<T> {
  stage: string;
  data: T;
  durationMs: number;
}

export interface PipelineResult {
  worldModel: WorldModelType;
  validation: ValidationResultType;
  stages: PipelineStageResult<unknown>[];
  totalDurationMs: number;
}

export type StageHandler<TIn, TOut> = (input: TIn) => Promise<TOut>;

export interface PipelineStage<TIn = unknown, TOut = unknown> {
  name: string;
  run: StageHandler<TIn, TOut>;
}

export class Pipeline {
  private stages: PipelineStage[] = [];
  private onStageStart?: (name: string) => void;
  private onStageEnd?: (
    name: string,
    durationMs: number,
    data?: unknown,
  ) => void;

  constructor(options?: {
    onStageStart?: (name: string) => void;
    onStageEnd?: (name: string, durationMs: number, data?: unknown) => void;
  }) {
    this.onStageStart = options?.onStageStart;
    this.onStageEnd = options?.onStageEnd;
  }

  addStage<TIn, TOut>(name: string, run: StageHandler<TIn, TOut>): Pipeline {
    this.stages.push({ name, run: run as StageHandler<unknown, unknown> });
    return this;
  }

  async execute(input: PipelineInput): Promise<PipelineResult> {
    const stageResults: PipelineStageResult<unknown>[] = [];
    let current: unknown = input;
    const totalStart = Date.now();

    for (const stage of this.stages) {
      this.onStageStart?.(stage.name);
      const start = Date.now();

      current = await stage.run(current);

      const durationMs = Date.now() - start;
      this.onStageEnd?.(stage.name, durationMs, current);

      stageResults.push({
        stage: stage.name,
        data: current,
        durationMs,
      });
    }

    const finalResult = current as {
      worldModel: WorldModelType;
      validation: ValidationResultType;
    };

    return {
      worldModel: finalResult.worldModel,
      validation: finalResult.validation,
      stages: stageResults,
      totalDurationMs: Date.now() - totalStart,
    };
  }
}

// === src/schema/extraction.ts ===
import { z } from "zod/v4";

/**
 * Zod schema for raw extraction output from the LLM.
 * Used to validate + coerce LLM responses before structuring.
 * Intentionally lenient — uses defaults and coercion rather than
 * rejecting partial extractions.
 */

const RawEntitySchema = z.object({
  name: z.string().default("unnamed"),
  type: z.string().default("object"),
  description: z.string().default(""),
  properties: z.record(z.string(), z.unknown()).optional(),
  tags: z.array(z.string()).optional(),
  confidence: z.number().min(0).max(1).optional(),
});

const RawRelationSchema = z.object({
  source: z.string(),
  target: z.string(),
  type: z.string().default("uses"),
  label: z.string().default(""),
  bidirectional: z.boolean().optional(),
});

const RawProcessStepSchema = z.object({
  order: z.number().optional(),
  action: z.string().default(""),
  actor: z.string().optional(),
  inputs: z.array(z.string()).optional(),
  outputs: z.array(z.string()).optional(),
});

const RawProcessSchema = z.object({
  name: z.string().default("unnamed process"),
  description: z.string().default(""),
  trigger: z.string().optional(),
  steps: z.array(RawProcessStepSchema).default([]),
  participants: z.array(z.string()).default([]),
  outcomes: z.array(z.string()).default([]),
});

const RawConstraintSchema = z.object({
  name: z.string().default("unnamed constraint"),
  type: z.string().default("rule"),
  description: z.string().default(""),
  scope: z.array(z.string()).default([]),
  severity: z.enum(["hard", "soft"]).default("soft"),
});

export const RawExtractionSchema = z.object({
  entities: z.array(RawEntitySchema).default([]),
  relations: z.array(RawRelationSchema).default([]),
  processes: z.array(RawProcessSchema).default([]),
  constraints: z.array(RawConstraintSchema).default([]),
  model_name: z.string().default("Untitled"),
  model_description: z.string().default(""),
  source_summary: z.string().default(""),
  confidence: z.number().min(0).max(1).default(0.5),
  extraction_notes: z.array(z.string()).default([]),
});

export type ValidatedRawExtraction = z.infer<typeof RawExtractionSchema>;

/**
 * Validate and coerce raw LLM extraction output.
 * Returns a clean extraction with defaults for missing fields,
 * plus any validation issues encountered.
 */
export function validateExtraction(raw: unknown): {
  extraction: ValidatedRawExtraction;
  issues: string[];
} {
  const issues: string[] = [];

  // Handle completely wrong types
  if (raw === null || raw === undefined) {
    issues.push("Extraction was null/undefined — returning empty model");
    return { extraction: RawExtractionSchema.parse({}), issues };
  }

  if (typeof raw !== "object") {
    issues.push(
      `Extraction was ${typeof raw} instead of object — returning empty model`,
    );
    return { extraction: RawExtractionSchema.parse({}), issues };
  }

  const result = RawExtractionSchema.safeParse(raw);

  if (result.success) {
    // Filter out entities with empty names
    const extraction = result.data;
    const beforeCount = extraction.entities.length;
    extraction.entities = extraction.entities.filter(
      (e) => e.name && e.name !== "unnamed",
    );
    if (extraction.entities.length < beforeCount) {
      issues.push(
        `Dropped ${beforeCount - extraction.entities.length} entities with empty/default names`,
      );
    }

    // Filter out relations with empty source/target
    const relBefore = extraction.relations.length;
    extraction.relations = extraction.relations.filter(
      (r) => r.source && r.target,
    );
    if (extraction.relations.length < relBefore) {
      issues.push(
        `Dropped ${relBefore - extraction.relations.length} relations with empty source/target`,
      );
    }

    return { extraction, issues };
  }

  // Partial parse — try to salvage what we can
  issues.push(
    `Extraction had schema errors: ${result.error.issues
      .slice(0, 3)
      .map((i) => i.message)
      .join("; ")}`,
  );

  // Attempt lenient parse by stripping invalid fields
  try {
    const obj = raw as Record<string, unknown>;
    const lenient = RawExtractionSchema.parse({
      entities: Array.isArray(obj.entities) ? obj.entities : [],
      relations: Array.isArray(obj.relations) ? obj.relations : [],
      processes: Array.isArray(obj.processes) ? obj.processes : [],
      constraints: Array.isArray(obj.constraints) ? obj.constraints : [],
      model_name:
        typeof obj.model_name === "string" ? obj.model_name : "Untitled",
      model_description:
        typeof obj.model_description === "string" ? obj.model_description : "",
      source_summary:
        typeof obj.source_summary === "string" ? obj.source_summary : "",
      confidence: typeof obj.confidence === "number" ? obj.confidence : 0.5,
      extraction_notes: Array.isArray(obj.extraction_notes)
        ? obj.extraction_notes
        : [],
    });
    issues.push("Recovered partial extraction via lenient parse");
    return { extraction: lenient, issues };
  } catch {
    issues.push("Lenient parse also failed — returning empty model");
    return { extraction: RawExtractionSchema.parse({}), issues };
  }
}

// === src/schema/index.ts ===
export {
  Entity,
  EntityId,
  Relation,
  RelationId,
  Process,
  ProcessId,
  ProcessStep,
  Constraint,
  ConstraintId,
  WorldModel,
  ValidationIssue,
  ValidationResult,
} from "./world-model.js";

export type {
  Entity as EntityType,
  Relation as RelationType,
  Process as ProcessType,
  Constraint as ConstraintType,
  WorldModel as WorldModelType,
  ValidationIssue as ValidationIssueType,
  ValidationResult as ValidationResultType,
} from "./world-model.js";

// === src/schema/json-schema.ts ===
import { z } from "zod/v4";
import { WorldModel } from "./world-model.js";

/**
 * Export the WorldModel Zod schema as a JSON Schema object.
 */
export function getWorldModelJsonSchema(): Record<string, unknown> {
  return z.toJSONSchema(WorldModel, { target: "draft-2020-12" });
}

// === src/schema/world-model.ts ===
import { z } from "zod/v4";

// ─── Primitives ───────────────────────────────────────────────

export const EntityId = z.string().describe("Unique entity identifier");
export const RelationId = z.string().describe("Unique relation identifier");
export const ProcessId = z.string().describe("Unique process identifier");
export const ConstraintId = z.string().describe("Unique constraint identifier");

// ─── Entity ───────────────────────────────────────────────────
// Something that exists in the world. Can be concrete (a server, a user)
// or abstract (a policy, a concept).

export const Entity = z.object({
  id: EntityId,
  name: z.string().describe("Human-readable name"),
  type: z
    .enum([
      "actor",
      "object",
      "system",
      "concept",
      "location",
      "event",
      "group",
      "resource",
    ])
    .describe("Ontological category"),
  description: z.string().describe("What this entity is and why it matters"),
  properties: z
    .record(z.string(), z.unknown())
    .describe("Arbitrary key-value attributes")
    .optional(),
  tags: z.array(z.string()).optional(),
  confidence: z
    .number()
    .min(0)
    .max(1)
    .optional()
    .describe(
      "Extraction confidence for this entity (1=explicit, 0.5=inferred, 0=placeholder)",
    ),
});

export type Entity = z.infer<typeof Entity>;

// ─── Relation ─────────────────────────────────────────────────
// A directed edge between two entities.

export const Relation = z.object({
  id: RelationId,
  type: z
    .enum([
      "has",
      "is_a",
      "part_of",
      "depends_on",
      "produces",
      "consumes",
      "controls",
      "communicates_with",
      "located_in",
      "triggers",
      "inherits",
      "contains",
      "uses",
      "flows_to",
      "opposes",
      "enables",
      "transforms",
    ])
    .describe("Semantic type of the relation"),
  source: EntityId.describe("Source entity ID"),
  target: EntityId.describe("Target entity ID"),
  label: z.string().describe("Human-readable description of the relation"),
  weight: z
    .number()
    .min(0)
    .max(1)
    .optional()
    .describe("Strength/confidence of the relation"),
  bidirectional: z.boolean().optional(),
});

export type Relation = z.infer<typeof Relation>;

// ─── Process ──────────────────────────────────────────────────
// A dynamic sequence — something that happens over time.

export const ProcessStep = z.object({
  order: z.number(),
  action: z.string().describe("What happens in this step"),
  actor: EntityId.optional().describe("Who/what performs the action"),
  input: z.array(EntityId).optional(),
  output: z.array(EntityId).optional(),
});

export const Process = z.object({
  id: ProcessId,
  name: z.string(),
  description: z.string(),
  trigger: z.string().optional().describe("What initiates this process"),
  steps: z.array(ProcessStep),
  participants: z.array(EntityId).describe("All entities involved"),
  outcomes: z
    .array(z.string())
    .describe("What this process produces or changes"),
});

export type Process = z.infer<typeof Process>;

// ─── Constraint ───────────────────────────────────────────────
// An invariant — something that must always be true.

export const Constraint = z.object({
  id: ConstraintId,
  name: z.string(),
  type: z.enum([
    "invariant",
    "rule",
    "boundary",
    "dependency",
    "capacity",
    "temporal",
    "authorization",
  ]),
  description: z.string().describe("What must hold true"),
  scope: z
    .array(EntityId)
    .describe("Which entities this constraint applies to"),
  severity: z
    .enum(["hard", "soft"])
    .describe("Hard = violation is an error, Soft = violation is a warning"),
});

export type Constraint = z.infer<typeof Constraint>;

// ─── World Model ──────────────────────────────────────────────
// The complete structured representation.

export const WorldModel = z.object({
  id: z.string(),
  name: z.string().describe("Name of this world model"),
  description: z.string().describe("What domain/system this model represents"),
  version: z.string().default("0.1.0"),
  created_at: z.string(),

  entities: z.array(Entity),
  relations: z.array(Relation),
  processes: z.array(Process),
  constraints: z.array(Constraint),

  metadata: z
    .object({
      source_type: z
        .enum(["text", "document", "url", "code", "conversation", "mixed"])
        .describe("What kind of input produced this model"),
      source_summary: z.string().describe("Brief description of the input"),
      confidence: z
        .number()
        .min(0)
        .max(1)
        .describe("Overall extraction confidence"),
      extraction_notes: z
        .array(z.string())
        .optional()
        .describe("Observations, ambiguities, or gaps noted during extraction"),
    })
    .optional(),
});

export type WorldModel = z.infer<typeof WorldModel>;

// ─── Validation result ────────────────────────────────────────

export const ValidationIssue = z.object({
  type: z.enum(["error", "warning", "info"]),
  code: z.string(),
  message: z.string(),
  path: z.string().optional().describe("JSONPath to the problematic element"),
});

export type ValidationIssue = z.infer<typeof ValidationIssue>;

export const ValidationResult = z.object({
  valid: z.boolean(),
  issues: z.array(ValidationIssue),
  stats: z.object({
    entities: z.number(),
    relations: z.number(),
    processes: z.number(),
    constraints: z.number(),
  }),
  score: z
    .number()
    .min(0)
    .max(100)
    .optional()
    .describe(
      "Quality score 0-100 based on completeness, integrity, and diversity",
    ),
});

export type ValidationResult = z.infer<typeof ValidationResult>;

// === src/serve/index.ts ===
export { startMcpServer } from "./mcp-server.js";

// === src/serve/mcp-server.ts ===
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod/v4";
import { readFileSync } from "node:fs";
import { resolve } from "node:path";
import type { WorldModelType } from "../schema/index.js";
import {
  findEntity,
  findDependents,
  pathsBetween,
  getStats,
  toMermaid,
  analyzeImpact,
} from "../utils/graph.js";
import { queryWorldModel } from "../agents/query.js";

/**
 * Create and start an MCP server that serves a world model as live, queryable tools.
 * Any AI agent that connects gets instant domain expertise.
 */
export async function startMcpServer(modelPath: string): Promise<void> {
  const resolved = resolve(modelPath);
  const raw = readFileSync(resolved, "utf-8");
  const model: WorldModelType = JSON.parse(raw);

  const entityNames = model.entities.map((e) => e.name);

  const server = new McpServer({
    name: `swm-${model.name.toLowerCase().replace(/[^a-z0-9]/g, "-")}`,
    version: model.version ?? "0.1.0",
  });

  // ─── Tool: get_entity ───────────────────────────────────
  server.tool(
    "get_entity",
    `Look up a domain entity. This world model has ${model.entities.length} entities across ${new Set(model.entities.map((e) => e.type)).size} types.`,
    {
      name: z
        .string()
        .describe(
          `Entity name to look up. Available: ${entityNames.slice(0, 15).join(", ")}${entityNames.length > 15 ? "..." : ""}`,
        ),
    },
    async ({ name }) => {
      const entity = findEntity(model, name);
      if (!entity) {
        return {
          content: [
            {
              type: "text" as const,
              text: `Entity "${name}" not found. Available: ${entityNames.join(", ")}`,
            },
          ],
        };
      }

      const deps = findDependents(model, entity.id);
      const constraints = model.constraints.filter((c) =>
        c.scope.includes(entity.id),
      );
      const processes = model.processes.filter((p) =>
        p.participants.includes(entity.id),
      );

      const lines = [
        `**${entity.name}** (${entity.type})`,
        entity.description,
        "",
      ];

      if (entity.properties && Object.keys(entity.properties).length > 0) {
        lines.push(`Properties: ${JSON.stringify(entity.properties, null, 2)}`);
      }
      if (deps.incoming.length > 0) {
        lines.push(
          `\nDepended on by: ${deps.incoming.map((d) => `${d.entity.name} [${d.relation.type}]`).join(", ")}`,
        );
      }
      if (deps.outgoing.length > 0) {
        lines.push(
          `Depends on: ${deps.outgoing.map((d) => `${d.entity.name} [${d.relation.type}]`).join(", ")}`,
        );
      }
      if (processes.length > 0) {
        lines.push(
          `Participates in: ${processes.map((p) => p.name).join(", ")}`,
        );
      }
      if (constraints.length > 0) {
        lines.push(
          `Constraints: ${constraints.map((c) => `[${c.severity}] ${c.name}`).join(", ")}`,
        );
      }

      return { content: [{ type: "text" as const, text: lines.join("\n") }] };
    },
  );

  // ─── Tool: get_relations ────────────────────────────────
  server.tool(
    "get_relations",
    "Get all relations for a given entity — incoming, outgoing, or both",
    {
      entity: z.string().describe("Entity name"),
      direction: z
        .enum(["incoming", "outgoing", "both"])
        .default("both")
        .describe("Direction of relations"),
    },
    async ({ entity: name, direction }) => {
      const entity = findEntity(model, name);
      if (!entity) {
        return {
          content: [
            { type: "text" as const, text: `Entity "${name}" not found.` },
          ],
        };
      }

      const deps = findDependents(model, entity.id);
      const lines: string[] = [];

      if (direction !== "outgoing" && deps.incoming.length > 0) {
        lines.push("**Incoming:**");
        for (const d of deps.incoming) {
          lines.push(
            `  ${d.entity.name} —[${d.relation.type}]→ ${entity.name}: ${d.relation.label}`,
          );
        }
      }
      if (direction !== "incoming" && deps.outgoing.length > 0) {
        lines.push("**Outgoing:**");
        for (const d of deps.outgoing) {
          lines.push(
            `  ${entity.name} —[${d.relation.type}]→ ${d.entity.name}: ${d.relation.label}`,
          );
        }
      }

      if (lines.length === 0) lines.push("No relations found.");
      return { content: [{ type: "text" as const, text: lines.join("\n") }] };
    },
  );

  // ─── Tool: find_path ────────────────────────────────────
  server.tool(
    "find_path",
    "Find connection paths between two entities in the domain model",
    {
      from: z.string().describe("Source entity name"),
      to: z.string().describe("Target entity name"),
    },
    async ({ from, to }) => {
      const src = findEntity(model, from);
      const tgt = findEntity(model, to);
      if (!src)
        return {
          content: [
            { type: "text" as const, text: `Entity "${from}" not found.` },
          ],
        };
      if (!tgt)
        return {
          content: [
            { type: "text" as const, text: `Entity "${to}" not found.` },
          ],
        };

      const paths = pathsBetween(model, src.id, tgt.id);
      if (paths.length === 0) {
        return {
          content: [
            {
              type: "text" as const,
              text: `No path found from ${src.name} to ${tgt.name}.`,
            },
          ],
        };
      }

      const lines = paths.map((path, i) => {
        const hops = path
          .map((step, j) =>
            j === 0
              ? step.entity.name
              : `—[${step.relation?.type ?? "?"}]→ ${step.entity.name}`,
          )
          .join(" ");
        return `Path ${i + 1}: ${hops}`;
      });

      return { content: [{ type: "text" as const, text: lines.join("\n") }] };
    },
  );

  // ─── Tool: get_process ──────────────────────────────────
  server.tool(
    "get_process",
    `Get details of a domain process. Available: ${model.processes.map((p) => p.name).join(", ")}`,
    { name: z.string().describe("Process name") },
    async ({ name }) => {
      const proc = model.processes.find((p) =>
        p.name.toLowerCase().includes(name.toLowerCase()),
      );
      if (!proc) {
        return {
          content: [
            {
              type: "text" as const,
              text: `Process "${name}" not found. Available: ${model.processes.map((p) => p.name).join(", ")}`,
            },
          ],
        };
      }

      const lines = [
        `**${proc.name}**`,
        proc.description,
        proc.trigger ? `Trigger: ${proc.trigger}` : "",
        "",
        "Steps:",
      ];

      for (const step of proc.steps) {
        const actor = step.actor
          ? (model.entities.find((e) => e.id === step.actor)?.name ?? "?")
          : "system";
        lines.push(`  ${step.order}. **${actor}**: ${step.action}`);
      }

      const participants = proc.participants
        .map((id) => model.entities.find((e) => e.id === id)?.name ?? id)
        .join(", ");
      lines.push(`\nParticipants: ${participants}`);
      lines.push(`Outcomes: ${proc.outcomes.join(", ")}`);

      return { content: [{ type: "text" as const, text: lines.join("\n") }] };
    },
  );

  // ─── Tool: check_constraint ─────────────────────────────
  server.tool(
    "check_constraint",
    `Check if an action violates a domain constraint. Constraints: ${model.constraints.map((c) => `[${c.severity}] ${c.name}`).join(", ")}`,
    {
      action: z.string().describe("Description of the action to validate"),
    },
    async ({ action }) => {
      const lines = ["Checking action against all constraints:\n"];

      for (const c of model.constraints) {
        const scopeNames = c.scope
          .map((id) => model.entities.find((e) => e.id === id)?.name ?? id)
          .join(", ");
        lines.push(
          `[${c.severity.toUpperCase()}] ${c.name} (applies to: ${scopeNames})`,
        );
        lines.push(`  Rule: ${c.description}`);
        lines.push("");
      }

      lines.push(`\nAction to evaluate: "${action}"`);
      lines.push("Review each constraint above against this action.");

      return { content: [{ type: "text" as const, text: lines.join("\n") }] };
    },
  );

  // ─── Tool: query ────────────────────────────────────────
  server.tool(
    "query",
    "Ask any natural language question about this domain. Uses graph analysis for structural questions, LLM inference for open-ended ones.",
    { question: z.string().describe("Your question about the domain") },
    async ({ question }) => {
      const result = await queryWorldModel(model, question);
      return {
        content: [
          {
            type: "text" as const,
            text: `${result.answer}\n\n---\nMethod: ${result.method} | Confidence: ${result.confidence}`,
          },
        ],
      };
    },
  );

  // ─── Tool: get_stats ────────────────────────────────────
  server.tool(
    "get_stats",
    "Get statistical overview of the domain model",
    {},
    async () => {
      const stats = getStats(model);
      const lines = [
        `**${model.name}**`,
        model.description,
        "",
        `Entities: ${stats.entities.total} (${Object.entries(
          stats.entities.byType,
        )
          .map(([t, c]) => `${c} ${t}`)
          .join(", ")})`,
        `Relations: ${stats.relations.total} (${Object.entries(
          stats.relations.byType,
        )
          .map(([t, c]) => `${c} ${t}`)
          .join(", ")})`,
        `Processes: ${stats.processes.total} (${stats.processes.totalSteps} total steps)`,
        `Constraints: ${stats.constraints.total} (${stats.constraints.hard} hard, ${stats.constraints.soft} soft)`,
        `Confidence: ${stats.confidence}`,
        "",
        "Most connected entities:",
        ...stats.mostConnected.map(
          (mc) => `  ${mc.entity}: ${mc.connections} connections`,
        ),
      ];
      return { content: [{ type: "text" as const, text: lines.join("\n") }] };
    },
  );

  // ─── Tool: get_diagram ──────────────────────────────────
  server.tool(
    "get_diagram",
    "Get a Mermaid diagram of the world model for visualization",
    {},
    async () => {
      return { content: [{ type: "text" as const, text: toMermaid(model) }] };
    },
  );

  // ─── Tool: analyze_impact ────────────────────────────────
  server.tool(
    "analyze_impact",
    "Analyze what breaks if an entity is removed — broken relations, dependents, affected processes and constraints, severity rating",
    {
      entity: z.string().describe("Entity name to analyze"),
    },
    async ({ entity: name }) => {
      const entity = findEntity(model, name);
      if (!entity) {
        return {
          content: [
            { type: "text" as const, text: `Entity "${name}" not found.` },
          ],
        };
      }
      const result = analyzeImpact(model, entity.id);
      if (!result) {
        return {
          content: [{ type: "text" as const, text: "Analysis failed." }],
        };
      }

      const lines = [
        `**Impact of removing ${entity.name}** — Severity: ${result.severity.toUpperCase()}`,
        "",
        result.summary,
      ];
      if (result.dependents.length > 0) {
        lines.push(
          `\nDependents: ${result.dependents.map((d) => d.name).join(", ")}`,
        );
      }
      if (result.affectedProcesses.length > 0) {
        lines.push(
          `Affected processes: ${result.affectedProcesses.map((a) => `${a.process.name} (${a.role})`).join(", ")}`,
        );
      }
      if (result.affectedConstraints.length > 0) {
        lines.push(
          `Affected constraints: ${result.affectedConstraints.map((c) => `[${c.severity}] ${c.name}`).join(", ")}`,
        );
      }
      return { content: [{ type: "text" as const, text: lines.join("\n") }] };
    },
  );

  // ─── Resource: full model ───────────────────────────────
  server.resource("world-model", `swm://model/${model.id}`, async () => ({
    contents: [
      {
        uri: `swm://model/${model.id}`,
        text: JSON.stringify(model, null, 2),
        mimeType: "application/json",
      },
    ],
  }));

  // Connect via stdio
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

// === src/swm.ts ===
import { Pipeline } from "./pipeline/index.js";
import type { PipelineInput, PipelineResult } from "./pipeline/index.js";
import { extractionAgent } from "./agents/extraction.js";
import { structuringAgent } from "./agents/structuring.js";
import { validationAgent } from "./agents/validation.js";
import { secondPassAgent } from "./agents/second-pass.js";
import { mergeWorldModels } from "./utils/merge.js";
import { setDefaultModel } from "./utils/llm.js";
import type { WorldModelType } from "./schema/index.js";

export interface SWMOptions {
  onStageStart?: (name: string) => void;
  onStageEnd?: (name: string, durationMs: number, data?: unknown) => void;
  /** Number of extraction passes (1 = standard, 2+ = deeper). Default 1. Max 3. */
  passes?: number;
  /** Claude model to use. Default: claude-sonnet-4-20250514 */
  model?: string;
}

export async function buildWorldModel(
  input: PipelineInput,
  options?: SWMOptions,
): Promise<PipelineResult> {
  if (options?.model) setDefaultModel(options.model);
  const passes = Math.min(Math.max(options?.passes ?? 1, 1), 3);
  const callbacks = {
    onStageStart: options?.onStageStart,
    onStageEnd: options?.onStageEnd,
  };

  // Pass 1: standard pipeline
  const pipeline = new Pipeline(callbacks);
  pipeline
    .addStage("extraction", extractionAgent)
    .addStage("structuring", structuringAgent)
    .addStage("validation", validationAgent);

  const firstPassResult = await pipeline.execute(input);

  if (passes === 1) {
    return firstPassResult;
  }

  // Multi-pass: run second-pass agent, merge, re-validate
  let currentModel = firstPassResult.worldModel;
  const allStages = [...firstPassResult.stages];
  let totalMs = firstPassResult.totalDurationMs;

  for (let pass = 2; pass <= passes; pass++) {
    const passLabel = `pass-${pass}-extraction`;

    callbacks.onStageStart?.(passLabel);
    const passStart = Date.now();

    const deltaExtraction = await secondPassAgent(input, currentModel);

    const passMs = Date.now() - passStart;
    callbacks.onStageEnd?.(passLabel, passMs);
    allStages.push({
      stage: passLabel,
      data: deltaExtraction,
      durationMs: passMs,
    });
    totalMs += passMs;

    // Skip if delta extraction is empty (second pass found nothing or failed)
    const hasContent =
      deltaExtraction.entities.length > 0 ||
      deltaExtraction.relations.length > 0 ||
      deltaExtraction.processes.length > 0 ||
      deltaExtraction.constraints.length > 0;

    if (!hasContent) {
      callbacks.onStageStart?.(`pass-${pass}-skip`);
      callbacks.onStageEnd?.(`pass-${pass}-skip`, 0);
      allStages.push({
        stage: `pass-${pass}-skip`,
        data: "empty delta — nothing new found",
        durationMs: 0,
      });
      continue;
    }

    // Structure the delta
    callbacks.onStageStart?.(`pass-${pass}-structuring`);
    const structStart = Date.now();

    const { worldModel: deltaModel } = await structuringAgent({
      input,
      extraction: deltaExtraction,
    });

    const structMs = Date.now() - structStart;
    callbacks.onStageEnd?.(`pass-${pass}-structuring`, structMs);
    allStages.push({
      stage: `pass-${pass}-structuring`,
      data: deltaModel,
      durationMs: structMs,
    });
    totalMs += structMs;

    // Merge
    callbacks.onStageStart?.(`pass-${pass}-merge`);
    const mergeStart = Date.now();

    currentModel = mergeWorldModels(currentModel, deltaModel, {
      name: currentModel.name,
      description: currentModel.description,
    });

    const mergeMs = Date.now() - mergeStart;
    callbacks.onStageEnd?.(`pass-${pass}-merge`, mergeMs);
    allStages.push({
      stage: `pass-${pass}-merge`,
      data: currentModel,
      durationMs: mergeMs,
    });
    totalMs += mergeMs;
  }

  // Final validation on the merged model
  callbacks.onStageStart?.("final-validation");
  const valStart = Date.now();

  const { worldModel: finalModel, validation } = await validationAgent({
    input,
    worldModel: currentModel,
  });

  const valMs = Date.now() - valStart;
  callbacks.onStageEnd?.("final-validation", valMs);
  allStages.push({
    stage: "final-validation",
    data: validation,
    durationMs: valMs,
  });
  totalMs += valMs;

  return {
    worldModel: finalModel,
    validation,
    stages: allStages,
    totalDurationMs: totalMs,
  };
}

export { Pipeline };
export type { PipelineInput, PipelineResult };

// === src/utils/algebra.ts ===
import type { WorldModelType } from "../schema/index.js";
import { genId } from "./ids.js";

type Entity = WorldModelType["entities"][number];
type Relation = WorldModelType["relations"][number];

function normalizeKey(name: string): string {
  return name
    .toLowerCase()
    .replace(/[^a-z0-9]/g, "_")
    .replace(/_+/g, "_")
    .replace(/^_|_$/g, "");
}

function entityKey(e: Entity): string {
  return normalizeKey(e.name);
}

function relKey(r: Relation, model: WorldModelType): string {
  const src = model.entities.find((e) => e.id === r.source)?.name ?? r.source;
  const tgt = model.entities.find((e) => e.id === r.target)?.name ?? r.target;
  return `${normalizeKey(src)}::${r.type}::${normalizeKey(tgt)}`;
}

function procKey(p: WorldModelType["processes"][number]): string {
  return normalizeKey(p.name);
}

function cstrKey(c: WorldModelType["constraints"][number]): string {
  return normalizeKey(c.name);
}

/**
 * Intersection: entities, relations, processes, constraints that appear in BOTH models.
 * Matched by name (entities, processes, constraints) or by (source, type, target) for relations.
 */
export function intersection(
  a: WorldModelType,
  b: WorldModelType,
): WorldModelType {
  const bEntityKeys = new Set(b.entities.map(entityKey));
  const bRelKeys = new Set(b.relations.map((r) => relKey(r, b)));
  const bProcKeys = new Set(b.processes.map(procKey));
  const bCstrKeys = new Set(b.constraints.map(cstrKey));

  const entities = a.entities
    .filter((e) => bEntityKeys.has(entityKey(e)))
    .map((e) => ({ ...e, id: genId("ent") }));

  const entityIdMap = new Map<string, string>();
  for (const origE of a.entities) {
    const newE = entities.find((e) => entityKey(e) === entityKey(origE));
    if (newE) entityIdMap.set(origE.id, newE.id);
  }
  // Also map B's IDs
  for (const origE of b.entities) {
    const newE = entities.find((e) => entityKey(e) === entityKey(origE));
    if (newE) entityIdMap.set(origE.id, newE.id);
  }

  const resolve = (id: string) => entityIdMap.get(id) ?? id;

  const relations = a.relations
    .filter((r) => bRelKeys.has(relKey(r, a)))
    .map((r) => ({
      ...r,
      id: genId("rel"),
      source: resolve(r.source),
      target: resolve(r.target),
    }));

  const processes = a.processes
    .filter((p) => bProcKeys.has(procKey(p)))
    .map((p) => ({
      ...p,
      id: genId("proc"),
      participants: p.participants.map(resolve),
      steps: p.steps.map((s) => ({
        ...s,
        actor: s.actor ? resolve(s.actor) : undefined,
        input: s.input?.map(resolve),
        output: s.output?.map(resolve),
      })),
    }));

  const constraints = a.constraints
    .filter((c) => bCstrKeys.has(cstrKey(c)))
    .map((c) => ({ ...c, id: genId("cstr"), scope: c.scope.map(resolve) }));

  return {
    id: genId("wm"),
    name: `${a.name} ∩ ${b.name}`,
    description: `Intersection of ${a.name} and ${b.name}`,
    version: "0.1.0",
    created_at: new Date().toISOString(),
    entities,
    relations,
    processes,
    constraints,
    metadata: {
      source_type: "mixed",
      source_summary: `Intersection: ${entities.length} shared entities`,
      confidence: Math.min(
        a.metadata?.confidence ?? 0.5,
        b.metadata?.confidence ?? 0.5,
      ),
    },
  };
}

/**
 * Difference: entities in A that are NOT in B.
 * Relations, processes, constraints are kept only if all their entity references remain.
 */
export function difference(
  a: WorldModelType,
  b: WorldModelType,
): WorldModelType {
  const bEntityKeys = new Set(b.entities.map(entityKey));

  const entities = a.entities
    .filter((e) => !bEntityKeys.has(entityKey(e)))
    .map((e) => ({ ...e, id: genId("ent") }));

  const entityIdMap = new Map<string, string>();
  for (const origE of a.entities) {
    const newE = entities.find((ne) => entityKey(ne) === entityKey(origE));
    if (newE) entityIdMap.set(origE.id, newE.id);
  }

  const remainingIds = new Set(entities.map((e) => e.id));
  const resolve = (id: string) => entityIdMap.get(id) ?? id;

  // Keep relations only if both endpoints remain
  const relations = a.relations
    .filter((r) => {
      const src = resolve(r.source);
      const tgt = resolve(r.target);
      return remainingIds.has(src) && remainingIds.has(tgt);
    })
    .map((r) => ({
      ...r,
      id: genId("rel"),
      source: resolve(r.source),
      target: resolve(r.target),
    }));

  // Keep processes only if all participants remain
  const processes = a.processes
    .filter((p) =>
      p.participants.every((pid) => remainingIds.has(resolve(pid))),
    )
    .map((p) => ({
      ...p,
      id: genId("proc"),
      participants: p.participants.map(resolve),
      steps: p.steps.map((s) => ({
        ...s,
        actor: s.actor ? resolve(s.actor) : undefined,
        input: s.input?.map(resolve),
        output: s.output?.map(resolve),
      })),
    }));

  // Keep constraints only if all scope entities remain
  const constraints = a.constraints
    .filter((c) => c.scope.every((sid) => remainingIds.has(resolve(sid))))
    .map((c) => ({ ...c, id: genId("cstr"), scope: c.scope.map(resolve) }));

  return {
    id: genId("wm"),
    name: `${a.name} \\ ${b.name}`,
    description: `Entities in ${a.name} but not in ${b.name}`,
    version: "0.1.0",
    created_at: new Date().toISOString(),
    entities,
    relations,
    processes,
    constraints,
    metadata: {
      source_type: "mixed",
      source_summary: `Difference: ${entities.length} entities unique to ${a.name}`,
      confidence: a.metadata?.confidence ?? 0.5,
    },
  };
}

/**
 * Overlay: apply B as a "lens" on top of A.
 * - All of A's entities remain
 * - B's constraints and relations are applied to matching entities in A
 * - B's entities that don't exist in A are added
 * - B's constraints override A's constraints with the same name
 */
export function overlay(
  base: WorldModelType,
  lens: WorldModelType,
): WorldModelType {
  // Start with all of base's entities
  const entityIdMap = new Map<string, string>();
  const entities: Entity[] = base.entities.map((e) => {
    const newId = genId("ent");
    entityIdMap.set(e.id, newId);
    return { ...e, id: newId };
  });

  // Map lens entities to base entities by name, or add new ones
  for (const le of lens.entities) {
    const key = entityKey(le);
    const existing = entities.find((e) => entityKey(e) === key);
    if (existing) {
      entityIdMap.set(le.id, existing.id);
      // Merge lens properties onto base
      if (le.properties) {
        existing.properties = { ...existing.properties, ...le.properties };
      }
      if (le.tags) {
        existing.tags = [...new Set([...(existing.tags ?? []), ...le.tags])];
      }
    } else {
      const newId = genId("ent");
      entityIdMap.set(le.id, newId);
      entities.push({ ...le, id: newId });
    }
  }

  const resolve = (id: string) => entityIdMap.get(id) ?? id;

  // Union all relations, dedup by (source, type, target)
  const relSeen = new Set<string>();
  const relations: Relation[] = [];

  for (const r of [...base.relations, ...lens.relations]) {
    const src = resolve(r.source);
    const tgt = resolve(r.target);
    const key = `${src}::${r.type}::${tgt}`;
    if (!relSeen.has(key)) {
      relSeen.add(key);
      relations.push({ ...r, id: genId("rel"), source: src, target: tgt });
    }
  }

  // Union processes, lens takes precedence for same name
  const procMap = new Map<string, WorldModelType["processes"][number]>();
  for (const p of base.processes) {
    procMap.set(procKey(p), {
      ...p,
      id: genId("proc"),
      participants: p.participants.map(resolve),
      steps: p.steps.map((s) => ({
        ...s,
        actor: s.actor ? resolve(s.actor) : undefined,
        input: s.input?.map(resolve),
        output: s.output?.map(resolve),
      })),
    });
  }
  for (const p of lens.processes) {
    procMap.set(procKey(p), {
      ...p,
      id: genId("proc"),
      participants: p.participants.map(resolve),
      steps: p.steps.map((s) => ({
        ...s,
        actor: s.actor ? resolve(s.actor) : undefined,
        input: s.input?.map(resolve),
        output: s.output?.map(resolve),
      })),
    });
  }

  // Constraints: lens overrides base for same name
  const cstrMap = new Map<string, WorldModelType["constraints"][number]>();
  for (const c of base.constraints) {
    cstrMap.set(cstrKey(c), {
      ...c,
      id: genId("cstr"),
      scope: c.scope.map(resolve),
    });
  }
  for (const c of lens.constraints) {
    cstrMap.set(cstrKey(c), {
      ...c,
      id: genId("cstr"),
      scope: c.scope.map(resolve),
    });
  }

  return {
    id: genId("wm"),
    name: `${base.name} + ${lens.name}`,
    description: `${base.name} with ${lens.name} overlay applied`,
    version: "0.1.0",
    created_at: new Date().toISOString(),
    entities,
    relations,
    processes: [...procMap.values()],
    constraints: [...cstrMap.values()],
    metadata: {
      source_type: "mixed",
      source_summary: `Overlay: ${base.name} (base) + ${lens.name} (lens)`,
      confidence: Math.min(
        base.metadata?.confidence ?? 0.5,
        lens.metadata?.confidence ?? 0.5,
      ),
    },
  };
}

// === src/utils/compare.ts ===
import type { WorldModelType } from "../schema/index.js";

export interface Conflict {
  kind: "entity_type" | "relation_type" | "constraint_severity" | "description";
  element: string;
  modelA: string;
  modelB: string;
}

export interface CompareResult {
  conflicts: Conflict[];
  agreements: number;
  conflictRate: number;
  summary: string;
}

function normalize(name: string): string {
  return name.toLowerCase().trim();
}

/**
 * Semantic comparison — find disagreements between two models of the same domain.
 * Same-named entities with different types, relations with different types, etc.
 */
export function compare(a: WorldModelType, b: WorldModelType): CompareResult {
  const conflicts: Conflict[] = [];
  let agreements = 0;

  // Entity type conflicts
  const aEntities = new Map(a.entities.map((e) => [normalize(e.name), e]));
  const bEntities = new Map(b.entities.map((e) => [normalize(e.name), e]));

  for (const [key, entA] of aEntities) {
    const entB = bEntities.get(key);
    if (!entB) continue;

    if (entA.type !== entB.type) {
      conflicts.push({
        kind: "entity_type",
        element: entA.name,
        modelA: entA.type,
        modelB: entB.type,
      });
    } else {
      agreements++;
    }
  }

  // Relation type conflicts (same source+target, different type)
  const relKey = (
    r: WorldModelType["relations"][number],
    model: WorldModelType,
  ) => {
    const src = normalize(
      model.entities.find((e) => e.id === r.source)?.name ?? r.source,
    );
    const tgt = normalize(
      model.entities.find((e) => e.id === r.target)?.name ?? r.target,
    );
    return `${src}::${tgt}`;
  };

  const aRels = new Map<string, WorldModelType["relations"][number]>();
  for (const r of a.relations) aRels.set(relKey(r, a), r);

  const bRels = new Map<string, WorldModelType["relations"][number]>();
  for (const r of b.relations) bRels.set(relKey(r, b), r);

  for (const [key, relA] of aRels) {
    const relB = bRels.get(key);
    if (!relB) continue;

    if (relA.type !== relB.type) {
      const src =
        a.entities.find((e) => e.id === relA.source)?.name ?? relA.source;
      const tgt =
        a.entities.find((e) => e.id === relA.target)?.name ?? relA.target;
      conflicts.push({
        kind: "relation_type",
        element: `${src} → ${tgt}`,
        modelA: relA.type,
        modelB: relB.type,
      });
    } else {
      agreements++;
    }
  }

  // Constraint severity conflicts
  const aCstrs = new Map(a.constraints.map((c) => [normalize(c.name), c]));
  const bCstrs = new Map(b.constraints.map((c) => [normalize(c.name), c]));

  for (const [key, cA] of aCstrs) {
    const cB = bCstrs.get(key);
    if (!cB) continue;

    if (cA.severity !== cB.severity) {
      conflicts.push({
        kind: "constraint_severity",
        element: cA.name,
        modelA: cA.severity,
        modelB: cB.severity,
      });
    } else {
      agreements++;
    }
  }

  const total = agreements + conflicts.length;
  const conflictRate =
    total > 0 ? Math.round((conflicts.length / total) * 100) / 100 : 0;

  const parts: string[] = [];
  if (conflicts.length === 0) {
    parts.push("No conflicts — models agree on all shared elements.");
  } else {
    parts.push(
      `${conflicts.length} conflict${conflicts.length > 1 ? "s" : ""} found.`,
    );
    const byKind = new Map<string, number>();
    for (const c of conflicts)
      byKind.set(c.kind, (byKind.get(c.kind) ?? 0) + 1);
    for (const [kind, count] of byKind) {
      parts.push(
        `${count} ${kind.replace(/_/g, " ")} conflict${count > 1 ? "s" : ""}`,
      );
    }
  }
  parts.push(
    `${agreements} agreements, ${Math.round(conflictRate * 100)}% conflict rate.`,
  );

  return {
    conflicts,
    agreements,
    conflictRate,
    summary: parts.join(" "),
  };
}

// === src/utils/coverage.ts ===
import type { WorldModelType } from "../schema/index.js";

export interface CoverageResult {
  /** What percentage of A's entities appear in B (by name) */
  entityCoverage: number;
  /** What percentage of A's relations appear in B */
  relationCoverage: number;
  /** What percentage of A's processes appear in B */
  processCoverage: number;
  /** What percentage of A's constraints appear in B */
  constraintCoverage: number;
  /** Overall weighted coverage */
  overall: number;
  /** Entities in A missing from B */
  missingEntities: string[];
  /** Entities in B not in A (extra) */
  extraEntities: string[];
  /** Relations in A missing from B */
  missingRelations: string[];
  /** Processes in A missing from B */
  missingProcesses: string[];
  /** Constraints in A missing from B */
  missingConstraints: string[];
}

function normalize(name: string): string {
  return name.toLowerCase().trim();
}

function pct(covered: number, total: number): number {
  if (total === 0) return 1; // empty set is fully covered
  return Math.round((covered / total) * 100) / 100;
}

/**
 * Measure how much of model A is covered by model B.
 * "Does B contain everything A specifies?"
 */
export function coverage(a: WorldModelType, b: WorldModelType): CoverageResult {
  // Entity coverage by normalized name
  const aEntityNames = new Set(a.entities.map((e) => normalize(e.name)));
  const bEntityNames = new Set(b.entities.map((e) => normalize(e.name)));

  const coveredEntities = [...aEntityNames].filter((n) => bEntityNames.has(n));
  const missingEntities = [...aEntityNames]
    .filter((n) => !bEntityNames.has(n))
    .map((n) => a.entities.find((e) => normalize(e.name) === n)?.name ?? n);
  const extraEntities = [...bEntityNames]
    .filter((n) => !aEntityNames.has(n))
    .map((n) => b.entities.find((e) => normalize(e.name) === n)?.name ?? n);

  // Relation coverage by (source name, type, target name)
  const relKey = (
    r: WorldModelType["relations"][number],
    model: WorldModelType,
  ) => {
    const src = normalize(
      model.entities.find((e) => e.id === r.source)?.name ?? r.source,
    );
    const tgt = normalize(
      model.entities.find((e) => e.id === r.target)?.name ?? r.target,
    );
    return `${src}::${r.type}::${tgt}`;
  };

  const aRelKeys = a.relations.map((r) => relKey(r, a));
  const bRelSet = new Set(b.relations.map((r) => relKey(r, b)));
  const coveredRels = aRelKeys.filter((k) => bRelSet.has(k));
  const missingRelations = aRelKeys.filter((k) => !bRelSet.has(k));

  // Process coverage by normalized name
  const aProcNames = new Set(a.processes.map((p) => normalize(p.name)));
  const bProcNames = new Set(b.processes.map((p) => normalize(p.name)));
  const coveredProcs = [...aProcNames].filter((n) => bProcNames.has(n));
  const missingProcesses = [...aProcNames]
    .filter((n) => !bProcNames.has(n))
    .map((n) => a.processes.find((p) => normalize(p.name) === n)?.name ?? n);

  // Constraint coverage by normalized name
  const aCstrNames = new Set(a.constraints.map((c) => normalize(c.name)));
  const bCstrNames = new Set(b.constraints.map((c) => normalize(c.name)));
  const coveredCstrs = [...aCstrNames].filter((n) => bCstrNames.has(n));
  const missingConstraints = [...aCstrNames]
    .filter((n) => !bCstrNames.has(n))
    .map((n) => a.constraints.find((c) => normalize(c.name) === n)?.name ?? n);

  const entityCoverage = pct(coveredEntities.length, aEntityNames.size);
  const relationCoverage = pct(coveredRels.length, aRelKeys.length);
  const processCoverage = pct(coveredProcs.length, aProcNames.size);
  const constraintCoverage = pct(coveredCstrs.length, aCstrNames.size);

  // Weighted overall: entities 40%, relations 30%, processes 15%, constraints 15%
  const overall =
    Math.round(
      (entityCoverage * 0.4 +
        relationCoverage * 0.3 +
        processCoverage * 0.15 +
        constraintCoverage * 0.15) *
        100,
    ) / 100;

  return {
    entityCoverage,
    relationCoverage,
    processCoverage,
    constraintCoverage,
    overall,
    missingEntities,
    extraEntities,
    missingRelations,
    missingProcesses,
    missingConstraints,
  };
}

// === src/utils/fetch.ts ===
/**
 * Fetch text content from a URL. Strips HTML tags for cleaner extraction.
 */
export async function fetchUrl(
  url: string,
): Promise<{ text: string; contentType: string }> {
  const response = await fetch(url, {
    headers: {
      "User-Agent": "SWM/0.1.0 (Structured World Model)",
      Accept: "text/html,text/plain,application/json,*/*",
    },
    signal: AbortSignal.timeout(30_000),
  });

  if (!response.ok) {
    throw new Error(
      `Failed to fetch ${url}: ${response.status} ${response.statusText}`,
    );
  }

  const contentType = response.headers.get("content-type") ?? "text/plain";
  const raw = await response.text();

  // Strip HTML tags if it's an HTML page — keep text content for extraction
  if (contentType.includes("html")) {
    return { text: stripHtml(raw), contentType };
  }

  return { text: raw, contentType };
}

export function stripHtml(html: string): string {
  return (
    html
      // Remove script and style blocks entirely
      .replace(/<script[\s\S]*?<\/script>/gi, "")
      .replace(/<style[\s\S]*?<\/style>/gi, "")
      .replace(/<nav[\s\S]*?<\/nav>/gi, "")
      .replace(/<footer[\s\S]*?<\/footer>/gi, "")
      // Replace common block elements with newlines
      .replace(
        /<\/?(p|div|br|h[1-6]|li|tr|td|th|blockquote|pre|hr)[^>]*>/gi,
        "\n",
      )
      // Remove all remaining tags
      .replace(/<[^>]+>/g, " ")
      // Decode common HTML entities
      .replace(/&amp;/g, "&")
      .replace(/&lt;/g, "<")
      .replace(/&gt;/g, ">")
      .replace(/&quot;/g, '"')
      .replace(/&#39;/g, "'")
      .replace(/&nbsp;/g, " ")
      // Collapse whitespace
      .replace(/[ \t]+/g, " ")
      .replace(/\n\s*\n/g, "\n\n")
      .trim()
  );
}

export function isUrl(input: string): boolean {
  return /^https?:\/\//i.test(input.trim());
}

// === src/utils/fix.ts ===
import type { WorldModelType, ValidationIssueType } from "../schema/index.js";

export interface FixResult {
  model: WorldModelType;
  fixes: string[];
}

/**
 * Auto-fix common validation issues in a world model.
 * Returns a cleaned model and a list of what was fixed.
 */
export function fixWorldModel(model: WorldModelType): FixResult {
  const fixes: string[] = [];
  let entities = [...model.entities];
  let relations = [...model.relations];
  let processes = [...model.processes];
  let constraints = [...model.constraints];

  const entityIds = () => new Set(entities.map((e) => e.id));

  // Fix 0: Merge duplicate entities FIRST (before orphan removal eats them)
  {
    const normalize = (n: string) => n.toLowerCase().trim();
    const nameGroups = new Map<string, typeof entities>();
    for (const e of entities) {
      const key = normalize(e.name);
      const group = nameGroups.get(key) ?? [];
      group.push(e);
      nameGroups.set(key, group);
    }

    let mergedCount = 0;
    const idRemap = new Map<string, string>();
    const deduped: typeof entities = [];

    for (const group of nameGroups.values()) {
      if (group.length === 1) {
        deduped.push(group[0]);
        continue;
      }
      const keeper = group.reduce((a, b) =>
        (b.description?.length ?? 0) > (a.description?.length ?? 0) ? b : a,
      );
      for (const e of group) {
        if (e.id !== keeper.id) {
          idRemap.set(e.id, keeper.id);
          if (e.properties)
            keeper.properties = { ...keeper.properties, ...e.properties };
          if (e.tags)
            keeper.tags = [...new Set([...(keeper.tags ?? []), ...e.tags])];
        }
      }
      deduped.push(keeper);
      mergedCount += group.length - 1;
    }

    if (mergedCount > 0) {
      entities = deduped;
      const remap = (id: string) => idRemap.get(id) ?? id;
      relations = relations.map((r) => ({
        ...r,
        source: remap(r.source),
        target: remap(r.target),
      }));
      processes = processes.map((p) => ({
        ...p,
        participants: p.participants.map(remap),
        steps: p.steps.map((s) => ({
          ...s,
          actor: s.actor ? remap(s.actor) : undefined,
        })),
      }));
      constraints = constraints.map((c) => ({
        ...c,
        scope: c.scope.map(remap),
      }));
      fixes.push(`Merged ${mergedCount} duplicate entities`);
    }
  }

  // Fix 0b: Remove low-confidence placeholder entities (auto-created by structuring)
  {
    const before = entities.length;
    const removedIds = new Set<string>();
    entities = entities.filter((e) => {
      if (
        e.confidence !== undefined &&
        e.confidence <= 0.2 &&
        e.tags?.includes("auto-created")
      ) {
        removedIds.add(e.id);
        return false;
      }
      return true;
    });
    if (removedIds.size > 0) {
      // Clean references to removed placeholders
      relations = relations.filter(
        (r) => !removedIds.has(r.source) && !removedIds.has(r.target),
      );
      processes = processes.map((p) => ({
        ...p,
        participants: p.participants.filter((pid) => !removedIds.has(pid)),
        steps: p.steps.map((s) => ({
          ...s,
          actor: s.actor && removedIds.has(s.actor) ? undefined : s.actor,
          input: s.input?.filter((id) => !removedIds.has(id)),
          output: s.output?.filter((id) => !removedIds.has(id)),
        })),
      }));
      constraints = constraints.map((c) => ({
        ...c,
        scope: c.scope.filter((id) => !removedIds.has(id)),
      }));
      fixes.push(
        `Removed ${removedIds.size} low-confidence placeholder entities`,
      );
    }
  }

  // Fix 1: Remove relations with dangling source or target
  {
    const ids = entityIds();
    const before = relations.length;
    relations = relations.filter((r) => ids.has(r.source) && ids.has(r.target));
    const removed = before - relations.length;
    if (removed > 0)
      fixes.push(`Removed ${removed} relations with dangling references`);
  }

  // Fix 2: Remove self-referencing relations
  {
    const before = relations.length;
    relations = relations.filter((r) => r.source !== r.target);
    const removed = before - relations.length;
    if (removed > 0)
      fixes.push(`Removed ${removed} self-referencing relations`);
  }

  // Fix 3: Remove orphan entities (not referenced by any relation, process, or constraint)
  {
    const referenced = new Set<string>();
    for (const r of relations) {
      referenced.add(r.source);
      referenced.add(r.target);
    }
    for (const p of processes) {
      for (const pid of p.participants) referenced.add(pid);
      for (const s of p.steps) {
        if (s.actor) referenced.add(s.actor);
        for (const inp of s.input ?? []) referenced.add(inp);
        for (const out of s.output ?? []) referenced.add(out);
      }
    }
    for (const c of constraints) {
      for (const sid of c.scope) referenced.add(sid);
    }

    const before = entities.length;
    entities = entities.filter((e) => referenced.has(e.id));
    const removed = before - entities.length;
    if (removed > 0) fixes.push(`Removed ${removed} orphan entities`);
  }

  // Fix 4: Remove process participants that reference non-existent entities
  {
    const ids = entityIds();
    let fixedCount = 0;
    processes = processes.map((p) => {
      const validParticipants = p.participants.filter((pid) => ids.has(pid));
      if (validParticipants.length < p.participants.length) fixedCount++;
      return { ...p, participants: validParticipants };
    });
    if (fixedCount > 0)
      fixes.push(`Cleaned dangling participants in ${fixedCount} processes`);
  }

  // Fix 5: Remove constraint scopes that reference non-existent entities
  {
    const ids = entityIds();
    let fixedCount = 0;
    constraints = constraints.map((c) => {
      const validScope = c.scope.filter((sid) => ids.has(sid));
      if (validScope.length < c.scope.length) fixedCount++;
      return { ...c, scope: validScope };
    });
    if (fixedCount > 0)
      fixes.push(`Cleaned dangling scope in ${fixedCount} constraints`);
  }

  // Fix 6: Remove empty processes (no steps)
  {
    const before = processes.length;
    processes = processes.filter((p) => p.steps.length > 0);
    const removed = before - processes.length;
    if (removed > 0) fixes.push(`Removed ${removed} empty processes`);
  }

  // Fix 7: Sort process steps by order
  {
    let fixedCount = 0;
    processes = processes.map((p) => {
      const sorted = [...p.steps].sort((a, b) => a.order - b.order);
      const wasUnsorted = p.steps.some((s, i) => s.order !== sorted[i].order);
      if (wasUnsorted) fixedCount++;
      return { ...p, steps: sorted };
    });
    if (fixedCount > 0) fixes.push(`Sorted steps in ${fixedCount} processes`);
  }

  // Fix 8: Deduplicate relations (same source, type, target)
  {
    const seen = new Set<string>();
    const before = relations.length;
    relations = relations.filter((r) => {
      const key = `${r.source}::${r.type}::${r.target}`;
      if (seen.has(key)) return false;
      seen.add(key);
      return true;
    });
    const removed = before - relations.length;
    if (removed > 0) fixes.push(`Removed ${removed} duplicate relations`);
  }

  // Fix 9: Clear dangling step actors
  {
    const ids = entityIds();
    let fixedCount = 0;
    processes = processes.map((p) => ({
      ...p,
      steps: p.steps.map((s) => {
        if (s.actor && !ids.has(s.actor)) {
          fixedCount++;
          return { ...s, actor: undefined };
        }
        return s;
      }),
    }));
    if (fixedCount > 0)
      fixes.push(`Cleared ${fixedCount} dangling step actors`);
  }

  // Fix 10: Renumber duplicate step orders sequentially
  {
    let fixedCount = 0;
    processes = processes.map((p) => {
      const orders = p.steps.map((s) => s.order);
      const hasDupes = new Set(orders).size !== orders.length;
      if (hasDupes) {
        fixedCount++;
        return { ...p, steps: p.steps.map((s, i) => ({ ...s, order: i + 1 })) };
      }
      return p;
    });
    if (fixedCount > 0)
      fixes.push(
        `Renumbered steps in ${fixedCount} processes with duplicate orders`,
      );
  }

  return {
    model: { ...model, entities, relations, processes, constraints },
    fixes,
  };
}

// === src/utils/graph.ts ===
import type { WorldModelType } from "../schema/index.js";

type Entity = WorldModelType["entities"][number];
type Relation = WorldModelType["relations"][number];

/**
 * Find all entities that directly depend on or relate to a given entity.
 */
export function findDependents(
  model: WorldModelType,
  entityId: string,
): {
  incoming: Array<{ relation: Relation; entity: Entity }>;
  outgoing: Array<{ relation: Relation; entity: Entity }>;
} {
  const entityMap = new Map(model.entities.map((e) => [e.id, e]));

  const incoming = model.relations
    .filter((r) => r.target === entityId)
    .map((r) => ({ relation: r, entity: entityMap.get(r.source)! }))
    .filter((r) => r.entity);

  const outgoing = model.relations
    .filter((r) => r.source === entityId)
    .map((r) => ({ relation: r, entity: entityMap.get(r.target)! }))
    .filter((r) => r.entity);

  return { incoming, outgoing };
}

/**
 * Find entity by name (case-insensitive partial match).
 */
export function findEntity(
  model: WorldModelType,
  query: string,
): Entity | undefined {
  const q = query.toLowerCase();
  return (
    model.entities.find((e) => e.name.toLowerCase() === q) ??
    model.entities.find((e) => e.name.toLowerCase().includes(q))
  );
}

/**
 * BFS to find shortest path between two entities via relations.
 */
export function pathsBetween(
  model: WorldModelType,
  sourceId: string,
  targetId: string,
  maxDepth = 10,
): Array<{ entity: Entity; relation?: Relation }[]> {
  const entityMap = new Map(model.entities.map((e) => [e.id, e]));

  // Build adjacency list (both directions for traversal)
  const adjacency = new Map<
    string,
    Array<{ neighborId: string; relation: Relation }>
  >();
  for (const ent of model.entities) {
    adjacency.set(ent.id, []);
  }
  for (const rel of model.relations) {
    adjacency.get(rel.source)?.push({ neighborId: rel.target, relation: rel });
    if (rel.bidirectional) {
      adjacency
        .get(rel.target)
        ?.push({ neighborId: rel.source, relation: rel });
    }
  }

  // BFS
  const results: Array<{ entity: Entity; relation?: Relation }>[] = [];
  const queue: Array<{
    path: Array<{ entityId: string; relation?: Relation }>;
  }> = [{ path: [{ entityId: sourceId }] }];
  const visited = new Set<string>();

  while (queue.length > 0 && results.length < 5) {
    const current = queue.shift()!;
    const lastNode = current.path[current.path.length - 1];

    if (lastNode.entityId === targetId && current.path.length > 1) {
      results.push(
        current.path.map((step) => ({
          entity: entityMap.get(step.entityId)!,
          relation: step.relation,
        })),
      );
      continue;
    }

    if (current.path.length >= maxDepth) continue;

    const neighbors = adjacency.get(lastNode.entityId) ?? [];
    for (const neighbor of neighbors) {
      if (
        !visited.has(neighbor.neighborId) ||
        neighbor.neighborId === targetId
      ) {
        queue.push({
          path: [
            ...current.path,
            { entityId: neighbor.neighborId, relation: neighbor.relation },
          ],
        });
      }
    }
    visited.add(lastNode.entityId);
  }

  return results;
}

/**
 * Export world model as Mermaid diagram.
 */
export function toMermaid(model: WorldModelType): string {
  const lines: string[] = [];
  if (model.name) {
    lines.push("---", `title: ${model.name}`, "---");
  }
  lines.push("graph TD");
  const entityMap = new Map(model.entities.map((e) => [e.id, e]));

  // Sanitize ID for Mermaid (no special chars)
  const mermaidId = (id: string) => id.replace(/[^a-zA-Z0-9_]/g, "_");
  const mermaidEscape = (s: string) =>
    s
      .replace(/"/g, "'")
      .replace(/`/g, "'")
      .replace(/[[\]{}()<>]/g, "")
      .replace(/\n/g, " ");

  // Add entity nodes with shape based on type
  for (const e of model.entities) {
    const mid = mermaidId(e.id);
    const label = mermaidEscape(e.name);
    switch (e.type) {
      case "actor":
        lines.push(`  ${mid}(["\`**${label}**\nactor\`"])`);
        break;
      case "system":
        lines.push(`  ${mid}[["${label}"]`);
        break;
      case "concept":
        lines.push(`  ${mid}>"${label}"]`);
        break;
      case "event":
        lines.push(`  ${mid}(("${label}"))`);
        break;
      default:
        lines.push(`  ${mid}["${label}"]`);
    }
  }

  // Add relation edges
  for (const r of model.relations) {
    const src = mermaidId(r.source);
    const tgt = mermaidId(r.target);
    const label = r.type.replace(/_/g, " ");
    if (r.bidirectional) {
      lines.push(`  ${src} <-- "${label}" --> ${tgt}`);
    } else {
      lines.push(`  ${src} -- "${label}" --> ${tgt}`);
    }
  }

  return lines.join("\n");
}

/**
 * Export world model as DOT (Graphviz) format.
 */
export function toDot(model: WorldModelType): string {
  const lines: string[] = [
    "digraph WorldModel {",
    "  rankdir=LR;",
    '  node [shape=box, style="rounded,filled", fillcolor="#f0f0f0", fontname="Helvetica"];',
    '  edge [fontname="Helvetica", fontsize=10];',
    "",
  ];

  const typeColors: Record<string, string> = {
    actor: "#d4edda",
    system: "#cce5ff",
    object: "#f0f0f0",
    concept: "#fff3cd",
    location: "#e2d5f1",
    event: "#f8d7da",
    group: "#d1ecf1",
    resource: "#ffeeba",
  };

  const dotEscape = (s: string) =>
    s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, " ");

  for (const e of model.entities) {
    const color = typeColors[e.type] ?? "#f0f0f0";
    const label = `${dotEscape(e.name)}\\n(${e.type})`;
    lines.push(`  "${e.id}" [label="${label}", fillcolor="${color}"];`);
  }

  lines.push("");

  for (const r of model.relations) {
    const label = r.type.replace(/_/g, " ");
    const dir = r.bidirectional ? ", dir=both" : "";
    lines.push(`  "${r.source}" -> "${r.target}" [label="${label}"${dir}];`);
  }

  lines.push("}");
  return lines.join("\n");
}

/**
 * Get model statistics.
 */
export function getStats(model: WorldModelType) {
  const entityTypes = new Map<string, number>();
  for (const e of model.entities) {
    entityTypes.set(e.type, (entityTypes.get(e.type) ?? 0) + 1);
  }

  const relationTypes = new Map<string, number>();
  for (const r of model.relations) {
    relationTypes.set(r.type, (relationTypes.get(r.type) ?? 0) + 1);
  }

  // Find most connected entities
  const connectionCount = new Map<string, number>();
  for (const r of model.relations) {
    connectionCount.set(r.source, (connectionCount.get(r.source) ?? 0) + 1);
    connectionCount.set(r.target, (connectionCount.get(r.target) ?? 0) + 1);
  }

  const entityMap = new Map(model.entities.map((e) => [e.id, e]));
  const mostConnected = [...connectionCount.entries()]
    .sort((a, b) => b[1] - a[1])
    .slice(0, 5)
    .map(([id, count]) => ({
      entity: entityMap.get(id)?.name ?? id,
      connections: count,
    }));

  return {
    entities: {
      total: model.entities.length,
      byType: Object.fromEntries(entityTypes),
    },
    relations: {
      total: model.relations.length,
      byType: Object.fromEntries(relationTypes),
    },
    processes: {
      total: model.processes.length,
      totalSteps: model.processes.reduce((acc, p) => acc + p.steps.length, 0),
    },
    constraints: {
      total: model.constraints.length,
      hard: model.constraints.filter((c) => c.severity === "hard").length,
      soft: model.constraints.filter((c) => c.severity === "soft").length,
    },
    mostConnected,
    confidence: model.metadata?.confidence,
  };
}

/**
 * Extract a subgraph centered on an entity, including all entities within N hops.
 * Returns a new WorldModel containing only the reachable entities and their relations.
 */
export function subgraph(
  model: WorldModelType,
  centerId: string,
  maxHops = 2,
): WorldModelType {
  // BFS to find all reachable entity IDs within maxHops
  const reachable = new Set<string>([centerId]);
  let frontier = new Set<string>([centerId]);

  for (let hop = 0; hop < maxHops && frontier.size > 0; hop++) {
    const nextFrontier = new Set<string>();
    for (const id of frontier) {
      for (const rel of model.relations) {
        if (rel.source === id && !reachable.has(rel.target)) {
          reachable.add(rel.target);
          nextFrontier.add(rel.target);
        }
        if (rel.target === id && !reachable.has(rel.source)) {
          reachable.add(rel.source);
          nextFrontier.add(rel.source);
        }
      }
    }
    frontier = nextFrontier;
  }

  const entities = model.entities.filter((e) => reachable.has(e.id));
  const relations = model.relations.filter(
    (r) => reachable.has(r.source) && reachable.has(r.target),
  );
  const processes = model.processes.filter((p) =>
    p.participants.some((pid) => reachable.has(pid)),
  );
  const constraints = model.constraints.filter((c) =>
    c.scope.some((sid) => reachable.has(sid)),
  );

  const centerName =
    model.entities.find((e) => e.id === centerId)?.name ?? centerId;

  return {
    id: model.id,
    name: `${model.name} — ${centerName} subgraph`,
    description: `Subgraph of ${model.name} centered on ${centerName} (${maxHops} hops)`,
    version: model.version,
    created_at: new Date().toISOString(),
    entities,
    relations,
    processes,
    constraints,
    metadata: {
      source_type: "mixed",
      source_summary: `Subgraph: ${entities.length} entities within ${maxHops} hops of ${centerName}`,
      confidence: model.metadata?.confidence ?? 0.5,
    },
  };
}

export interface Cluster {
  name: string;
  entities: Entity[];
  internalRelations: number;
  externalRelations: number;
}

/**
 * Find natural clusters in a world model using connected components
 * on strongly-connected subgraphs. Entities that are densely interconnected
 * get grouped together.
 */
export interface ImpactAnalysis {
  entity: Entity;
  brokenRelations: Relation[];
  affectedProcesses: Array<{
    process: WorldModelType["processes"][number];
    role: string;
  }>;
  affectedConstraints: WorldModelType["constraints"][number][];
  dependents: Entity[];
  severity: "low" | "medium" | "high" | "critical";
  summary: string;
}

/**
 * Analyze the impact of removing an entity from the model.
 * "What breaks if we remove X?"
 */
export function analyzeImpact(
  model: WorldModelType,
  entityId: string,
): ImpactAnalysis | null {
  const entity = model.entities.find((e) => e.id === entityId);
  if (!entity) return null;

  // Relations that would break
  const brokenRelations = model.relations.filter(
    (r) => r.source === entityId || r.target === entityId,
  );

  // Processes that would lose a participant or step actor
  const affectedProcesses = model.processes
    .filter(
      (p) =>
        p.participants.includes(entityId) ||
        p.steps.some((s) => s.actor === entityId),
    )
    .map((p) => {
      const isActor = p.steps.some((s) => s.actor === entityId);
      return {
        process: p,
        role: isActor ? "step actor" : "participant",
      };
    });

  // Constraints that scope this entity
  const affectedConstraints = model.constraints.filter((c) =>
    c.scope.includes(entityId),
  );

  // Entities that depend on this one (via depends_on, part_of, etc.)
  const depTypes = new Set(["depends_on", "part_of", "uses", "consumes"]);
  const dependents = model.relations
    .filter((r) => r.target === entityId && depTypes.has(r.type))
    .map((r) => model.entities.find((e) => e.id === r.source)!)
    .filter(Boolean);

  // Compute severity
  const score =
    brokenRelations.length * 2 +
    affectedProcesses.length * 3 +
    affectedConstraints.filter((c) => c.severity === "hard").length * 5 +
    dependents.length * 2;

  const severity: ImpactAnalysis["severity"] =
    score >= 15
      ? "critical"
      : score >= 8
        ? "high"
        : score >= 3
          ? "medium"
          : "low";

  // Summary
  const parts: string[] = [`Removing ${entity.name} (${entity.type})`];
  if (brokenRelations.length > 0)
    parts.push(`breaks ${brokenRelations.length} relations`);
  if (dependents.length > 0)
    parts.push(`${dependents.length} entities depend on it`);
  if (affectedProcesses.length > 0)
    parts.push(`disrupts ${affectedProcesses.length} processes`);
  if (affectedConstraints.length > 0)
    parts.push(`invalidates ${affectedConstraints.length} constraints`);
  parts.push(`Severity: ${severity}.`);

  return {
    entity,
    brokenRelations,
    affectedProcesses,
    affectedConstraints,
    dependents,
    severity,
    summary: parts.join(". ") + ".",
  };
}

export function findClusters(model: WorldModelType): Cluster[] {
  if (model.entities.length === 0) return [];

  // Build undirected adjacency
  const adj = new Map<string, Set<string>>();
  for (const e of model.entities) adj.set(e.id, new Set());
  for (const r of model.relations) {
    adj.get(r.source)?.add(r.target);
    adj.get(r.target)?.add(r.source);
  }

  // Find connected components via BFS
  const visited = new Set<string>();
  const components: string[][] = [];

  for (const entity of model.entities) {
    if (visited.has(entity.id)) continue;
    const component: string[] = [];
    const queue = [entity.id];
    while (queue.length > 0) {
      const id = queue.shift()!;
      if (visited.has(id)) continue;
      visited.add(id);
      component.push(id);
      for (const neighbor of adj.get(id) ?? []) {
        if (!visited.has(neighbor)) queue.push(neighbor);
      }
    }
    components.push(component);
  }

  const entityMap = new Map(model.entities.map((e) => [e.id, e]));

  return components
    .map((component) => {
      const entitySet = new Set(component);
      const entities = component
        .map((id) => entityMap.get(id)!)
        .filter(Boolean);

      const internalRelations = model.relations.filter(
        (r) => entitySet.has(r.source) && entitySet.has(r.target),
      ).length;

      const externalRelations = model.relations.filter(
        (r) =>
          (entitySet.has(r.source) || entitySet.has(r.target)) &&
          !(entitySet.has(r.source) && entitySet.has(r.target)),
      ).length;

      // Name the cluster after its most connected entity
      const connectionCounts = new Map<string, number>();
      for (const r of model.relations) {
        if (entitySet.has(r.source))
          connectionCounts.set(
            r.source,
            (connectionCounts.get(r.source) ?? 0) + 1,
          );
        if (entitySet.has(r.target))
          connectionCounts.set(
            r.target,
            (connectionCounts.get(r.target) ?? 0) + 1,
          );
      }
      const topEntity = [...connectionCounts.entries()].sort(
        (a, b) => b[1] - a[1],
      )[0];
      const name = topEntity
        ? `${entityMap.get(topEntity[0])?.name ?? "Unknown"} cluster`
        : (entities[0]?.name ?? "Isolated");

      return { name, entities, internalRelations, externalRelations };
    })
    .sort((a, b) => b.entities.length - a.entities.length);
}

/**
 * Generate a natural-language summary of a world model. No LLM — pure graph analysis.
 */
export function summarize(model: WorldModelType): string {
  const stats = getStats(model);
  const parts: string[] = [];

  // What is it
  parts.push(model.description || model.name);

  // Scale
  const typeParts: string[] = [];
  for (const [type, count] of Object.entries(stats.entities.byType)) {
    typeParts.push(`${count} ${type}${count > 1 ? "s" : ""}`);
  }
  parts.push(
    `${stats.entities.total} entities (${typeParts.join(", ")}), ${stats.relations.total} relations.`,
  );

  // Center of gravity
  if (stats.mostConnected.length > 0) {
    const top = stats.mostConnected.slice(0, 3).map((mc) => mc.entity);
    parts.push(`Centered around ${top.join(", ")}.`);
  }

  // Processes
  if (stats.processes.total > 0) {
    const procNames = model.processes.map((p) => p.name).slice(0, 3);
    parts.push(
      `${stats.processes.total} process${stats.processes.total > 1 ? "es" : ""}: ${procNames.join(", ")}${model.processes.length > 3 ? ", ..." : ""}.`,
    );
  }

  // Constraints
  if (stats.constraints.total > 0) {
    const cParts: string[] = [];
    if (stats.constraints.hard > 0)
      cParts.push(`${stats.constraints.hard} hard`);
    if (stats.constraints.soft > 0)
      cParts.push(`${stats.constraints.soft} soft`);
    parts.push(
      `${stats.constraints.total} constraints (${cParts.join(", ")}).`,
    );
  }

  // Confidence
  if (stats.confidence !== undefined) {
    parts.push(`Confidence: ${Math.round(stats.confidence * 100)}%.`);
  }

  return parts.join(" ");
}

// === src/utils/ids.ts ===
import { randomBytes } from "node:crypto";

export function genId(prefix: string): string {
  const hex = randomBytes(6).toString("hex");
  return `${prefix}_${hex}`;
}

// === src/utils/llm.ts ===
import Anthropic from "@anthropic-ai/sdk";

let client: Anthropic | null = null;
let defaultModel = "claude-sonnet-4-20250514";

export function getClient(): Anthropic {
  if (!client) {
    client = new Anthropic();
  }
  return client;
}

export function setDefaultModel(model: string): void {
  defaultModel = model;
}

export function getDefaultModel(): string {
  return defaultModel;
}

export interface AgentMessage {
  role: "user" | "assistant";
  content: string;
}

export interface CallOptions {
  model?: string;
  maxTokens?: number;
  retries?: number;
  timeoutMs?: number;
}

const DEFAULT_RETRIES = 3;
const BASE_DELAY_MS = 1000;
const DEFAULT_TIMEOUT_MS = 120_000; // 2 minutes
const MAX_INPUT_TOKENS_WARNING = 150_000;

function isRetryable(err: unknown): boolean {
  if (err instanceof Anthropic.APIError) {
    return err.status === 429 || err.status >= 500;
  }
  if (err instanceof Error) {
    const msg = err.message.toLowerCase();
    return (
      msg.includes("timeout") ||
      msg.includes("econnreset") ||
      msg.includes("socket") ||
      msg.includes("aborted")
    );
  }
  return false;
}

async function withRetry<T>(
  fn: () => Promise<T>,
  retries: number,
  label: string,
): Promise<T> {
  let lastErr: unknown;
  for (let attempt = 0; attempt <= retries; attempt++) {
    try {
      return await fn();
    } catch (err) {
      lastErr = err;
      if (attempt < retries && isRetryable(err)) {
        const delay = BASE_DELAY_MS * Math.pow(2, attempt);
        const jitter = Math.random() * delay * 0.3;
        const waitMs = Math.round(delay + jitter);
        process.stderr.write(
          `\n  [retry] ${label} attempt ${attempt + 1}/${retries} failed, retrying in ${waitMs}ms...\n`,
        );
        await new Promise((r) => setTimeout(r, waitMs));
      } else {
        throw err;
      }
    }
  }
  throw lastErr;
}

/**
 * Wrap a promise with a timeout. Rejects with a clear error if the timeout fires.
 */
function withTimeout<T>(
  promise: Promise<T>,
  ms: number,
  label: string,
): Promise<T> {
  return new Promise<T>((resolve, reject) => {
    const timer = setTimeout(() => {
      reject(new Error(`${label} timed out after ${ms}ms`));
    }, ms);

    promise.then(
      (val) => {
        clearTimeout(timer);
        resolve(val);
      },
      (err) => {
        clearTimeout(timer);
        reject(err);
      },
    );
  });
}

export async function callAgent(
  systemPrompt: string,
  userMessage: string,
  options?: CallOptions,
): Promise<string> {
  if (!systemPrompt) throw new Error("callAgent: systemPrompt is required");
  if (!userMessage) throw new Error("callAgent: userMessage is required");

  const llm = getClient();
  const retries = options?.retries ?? DEFAULT_RETRIES;
  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;

  return withRetry(
    async () => {
      const apiCall = llm.messages.create({
        model: options?.model ?? defaultModel,
        max_tokens: options?.maxTokens ?? 8192,
        system: systemPrompt,
        messages: [{ role: "user", content: userMessage }],
      });

      const response = await withTimeout(apiCall, timeoutMs, "LLM call");

      const textBlock = response.content.find((b) => b.type === "text");
      if (!textBlock || textBlock.type !== "text") {
        throw new Error("No text response from LLM");
      }
      return textBlock.text;
    },
    retries,
    "callAgent",
  );
}

export async function callAgentJSON<T>(
  systemPrompt: string,
  userMessage: string,
  options?: CallOptions,
): Promise<T> {
  const retries = options?.retries ?? DEFAULT_RETRIES;

  return withRetry(
    async () => {
      const raw = await callAgent(systemPrompt, userMessage, {
        ...options,
        retries: 0,
      });

      // Extract JSON from markdown code fences if present
      const jsonMatch = raw.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
      const jsonStr = jsonMatch ? jsonMatch[1].trim() : raw.trim();

      try {
        return JSON.parse(jsonStr) as T;
      } catch {
        throw new Error(
          `Failed to parse LLM response as JSON (${raw.length} chars):\n${raw.slice(0, 800)}`,
        );
      }
    },
    retries,
    "callAgentJSON",
  );
}

/**
 * Estimate token count from text (rough: 1 token ≈ 4 chars).
 */
export function estimateTokens(text: string): number {
  return Math.ceil(text.length / 4);
}

/**
 * Check input size and warn if it's very large.
 * Returns { safe: boolean, tokens: number, warning?: string }
 */
export function checkInputSize(text: string): {
  safe: boolean;
  tokens: number;
  warning?: string;
} {
  const tokens = estimateTokens(text);
  if (tokens > MAX_INPUT_TOKENS_WARNING) {
    return {
      safe: false,
      tokens,
      warning: `Input is ~${tokens.toLocaleString()} tokens (${text.length.toLocaleString()} chars). This exceeds the ${MAX_INPUT_TOKENS_WARNING.toLocaleString()} token warning threshold. The input will be chunked automatically.`,
    };
  }
  return { safe: true, tokens };
}

// === src/utils/merge.ts ===
import type { WorldModelType } from "../schema/index.js";
import { genId } from "./ids.js";

/**
 * Merge two world models into one. Deduplicates entities by name,
 * remaps all IDs, and unions relations/processes/constraints.
 */
export function mergeWorldModels(
  a: WorldModelType,
  b: WorldModelType,
  options?: { name?: string; description?: string },
): WorldModelType {
  // Build unified entity set, deduplicating by normalized name
  const entityMap = new Map<string, WorldModelType["entities"][number]>();
  const oldIdToNewId = new Map<string, string>();

  function normalizeEntityName(name: string): string {
    return name
      .toLowerCase()
      .replace(/[^a-z0-9]/g, "_")
      .replace(/_+/g, "_")
      .replace(/^_|_$/g, "");
  }

  function addEntity(e: WorldModelType["entities"][number]) {
    const key = normalizeEntityName(e.name);
    const existing = entityMap.get(key);
    if (existing) {
      oldIdToNewId.set(e.id, existing.id);
      // Merge properties and tags
      if (e.properties) {
        existing.properties = { ...existing.properties, ...e.properties };
      }
      if (e.tags) {
        const tagSet = new Set([...(existing.tags ?? []), ...e.tags]);
        existing.tags = [...tagSet];
      }
      // Keep the longer description
      if (e.description.length > existing.description.length) {
        existing.description = e.description;
      }
      // Boost confidence for cross-validated entities (appears in both models)
      const existingConf = existing.confidence ?? 0.5;
      const newConf = e.confidence ?? 0.5;
      existing.confidence = Math.min(1, (existingConf + newConf) / 2 + 0.1);
    } else {
      const newId = genId("ent");
      oldIdToNewId.set(e.id, newId);
      entityMap.set(key, { ...e, id: newId });
    }
  }

  for (const e of a.entities) addEntity(e);
  for (const e of b.entities) addEntity(e);

  const resolve = (oldId: string): string => oldIdToNewId.get(oldId) ?? oldId;

  // Merge relations, deduplicate by (source, target, type)
  const relationKey = (r: { source: string; target: string; type: string }) =>
    `${resolve(r.source)}::${r.type}::${resolve(r.target)}`;

  const relationMap = new Map<string, WorldModelType["relations"][number]>();

  for (const r of [...a.relations, ...b.relations]) {
    const key = relationKey(r);
    if (!relationMap.has(key)) {
      relationMap.set(key, {
        ...r,
        id: genId("rel"),
        source: resolve(r.source),
        target: resolve(r.target),
      });
    }
  }

  // Merge processes, deduplicate by normalized name
  const processMap = new Map<string, WorldModelType["processes"][number]>();

  for (const p of [...a.processes, ...b.processes]) {
    const key = normalizeEntityName(p.name);
    if (!processMap.has(key)) {
      processMap.set(key, {
        ...p,
        id: genId("proc"),
        participants: p.participants.map(resolve),
        steps: p.steps.map((s) => ({
          ...s,
          actor: s.actor ? resolve(s.actor) : undefined,
          input: s.input?.map(resolve),
          output: s.output?.map(resolve),
        })),
      });
    } else {
      // Keep the one with more steps
      const existing = processMap.get(key)!;
      if (p.steps.length > existing.steps.length) {
        processMap.set(key, {
          ...p,
          id: existing.id,
          participants: p.participants.map(resolve),
          steps: p.steps.map((s) => ({
            ...s,
            actor: s.actor ? resolve(s.actor) : undefined,
            input: s.input?.map(resolve),
            output: s.output?.map(resolve),
          })),
        });
      }
    }
  }

  // Merge constraints, deduplicate by normalized name
  const constraintMap = new Map<
    string,
    WorldModelType["constraints"][number]
  >();

  for (const c of [...a.constraints, ...b.constraints]) {
    const key = normalizeEntityName(c.name);
    if (!constraintMap.has(key)) {
      constraintMap.set(key, {
        ...c,
        id: genId("cstr"),
        scope: c.scope.map(resolve),
      });
    }
  }

  // Compute merged confidence
  const confA = a.metadata?.confidence ?? 0.5;
  const confB = b.metadata?.confidence ?? 0.5;
  const mergedConfidence = Math.min(1, (confA + confB) / 2);

  return {
    id: genId("wm"),
    name: options?.name ?? `${a.name} + ${b.name}`,
    description:
      options?.description ?? `Merged model from: ${a.name}, ${b.name}`,
    version: "0.1.0",
    created_at: new Date().toISOString(),
    entities: [...entityMap.values()],
    relations: [...relationMap.values()],
    processes: [...processMap.values()],
    constraints: [...constraintMap.values()],
    metadata: {
      source_type: "mixed",
      source_summary: `Merged from ${a.entities.length + b.entities.length} entities across 2 models`,
      confidence: mergedConfidence,
      extraction_notes: [
        ...(a.metadata?.extraction_notes ?? []),
        ...(b.metadata?.extraction_notes ?? []),
        `Merged: ${a.name} (${a.entities.length} entities) + ${b.name} (${b.entities.length} entities)`,
      ],
    },
  };
}

/**
 * Diff two world models. Returns what was added, removed, and changed.
 */
export interface WorldModelDiff {
  entities: {
    added: string[];
    removed: string[];
    modified: string[];
  };
  relations: {
    added: string[];
    removed: string[];
  };
  processes: {
    added: string[];
    removed: string[];
  };
  constraints: {
    added: string[];
    removed: string[];
  };
  summary: string;
}

export function diffWorldModels(
  before: WorldModelType,
  after: WorldModelType,
): WorldModelDiff {
  function nameSet(items: Array<{ name: string }>): Set<string> {
    return new Set(items.map((i) => i.name));
  }

  function descMap(
    items: Array<{ name: string; description: string }>,
  ): Map<string, string> {
    return new Map(items.map((i) => [i.name, i.description]));
  }

  const entBefore = nameSet(before.entities);
  const entAfter = nameSet(after.entities);
  const descBefore = descMap(before.entities);
  const descAfter = descMap(after.entities);

  const entAdded = [...entAfter].filter((n) => !entBefore.has(n));
  const entRemoved = [...entBefore].filter((n) => !entAfter.has(n));
  const entModified = [...entAfter].filter(
    (n) => entBefore.has(n) && descBefore.get(n) !== descAfter.get(n),
  );

  const relKey = (
    r: { source: string; target: string; type: string },
    model: WorldModelType,
  ) => {
    const src = model.entities.find((e) => e.id === r.source)?.name ?? r.source;
    const tgt = model.entities.find((e) => e.id === r.target)?.name ?? r.target;
    return `${src}::${r.type}::${tgt}`;
  };

  const relBefore = new Set(before.relations.map((r) => relKey(r, before)));
  const relAfter = new Set(after.relations.map((r) => relKey(r, after)));

  const procBefore = nameSet(before.processes);
  const procAfter = nameSet(after.processes);

  const cstrBefore = nameSet(before.constraints);
  const cstrAfter = nameSet(after.constraints);

  const diff: WorldModelDiff = {
    entities: {
      added: entAdded,
      removed: entRemoved,
      modified: entModified,
    },
    relations: {
      added: [...relAfter].filter((r) => !relBefore.has(r)),
      removed: [...relBefore].filter((r) => !relAfter.has(r)),
    },
    processes: {
      added: [...procAfter].filter((p) => !procBefore.has(p)),
      removed: [...procBefore].filter((p) => !procAfter.has(p)),
    },
    constraints: {
      added: [...cstrAfter].filter((c) => !cstrBefore.has(c)),
      removed: [...cstrBefore].filter((c) => !cstrAfter.has(c)),
    },
    summary: "",
  };

  const parts: string[] = [];
  if (entAdded.length) parts.push(`+${entAdded.length} entities`);
  if (entRemoved.length) parts.push(`-${entRemoved.length} entities`);
  if (entModified.length)
    parts.push(`~${entModified.length} entities modified`);
  if (diff.relations.added.length)
    parts.push(`+${diff.relations.added.length} relations`);
  if (diff.relations.removed.length)
    parts.push(`-${diff.relations.removed.length} relations`);
  if (diff.processes.added.length)
    parts.push(`+${diff.processes.added.length} processes`);
  if (diff.constraints.added.length)
    parts.push(`+${diff.constraints.added.length} constraints`);

  diff.summary = parts.length ? parts.join(", ") : "No changes";
  return diff;
}

// === src/utils/timeline.ts ===
import type { WorldModelType } from "../schema/index.js";
import { diffWorldModels, type WorldModelDiff } from "./merge.js";
import { genId } from "./ids.js";

export interface Snapshot {
  id: string;
  timestamp: string;
  label?: string;
  model: WorldModelType;
  diff_from_previous?: WorldModelDiff;
  stats: {
    entities: number;
    relations: number;
    processes: number;
    constraints: number;
  };
}

export interface Timeline {
  id: string;
  name: string;
  description: string;
  created_at: string;
  snapshots: Snapshot[];
}

/**
 * Create a new empty timeline.
 */
export function createTimeline(name: string, description?: string): Timeline {
  return {
    id: genId("tl"),
    name,
    description: description ?? `Timeline for ${name}`,
    created_at: new Date().toISOString(),
    snapshots: [],
  };
}

/**
 * Add a world model as a new snapshot to a timeline.
 * Automatically computes diff from the previous snapshot.
 */
export function addSnapshot(
  timeline: Timeline,
  model: WorldModelType,
  label?: string,
): Timeline {
  const previous =
    timeline.snapshots.length > 0
      ? timeline.snapshots[timeline.snapshots.length - 1]
      : null;

  const diff = previous ? diffWorldModels(previous.model, model) : undefined;

  const snapshot: Snapshot = {
    id: genId("snap"),
    timestamp: new Date().toISOString(),
    label,
    model,
    diff_from_previous: diff,
    stats: {
      entities: model.entities.length,
      relations: model.relations.length,
      processes: model.processes.length,
      constraints: model.constraints.length,
    },
  };

  return {
    ...timeline,
    snapshots: [...timeline.snapshots, snapshot],
  };
}

/**
 * Get the history of a specific entity across all snapshots.
 * Returns when it appeared, disappeared, or changed description.
 */
export function entityHistory(
  timeline: Timeline,
  entityName: string,
): Array<{
  snapshot_id: string;
  timestamp: string;
  label?: string;
  event: "appeared" | "disappeared" | "modified" | "unchanged";
  description?: string;
}> {
  const history: Array<{
    snapshot_id: string;
    timestamp: string;
    label?: string;
    event: "appeared" | "disappeared" | "modified" | "unchanged";
    description?: string;
  }> = [];

  const normalizedName = entityName.toLowerCase();
  let previousEntity: { name: string; description: string } | null = null;

  for (const snap of timeline.snapshots) {
    const entity = snap.model.entities.find(
      (e) => e.name.toLowerCase() === normalizedName,
    );

    if (entity && !previousEntity) {
      history.push({
        snapshot_id: snap.id,
        timestamp: snap.timestamp,
        label: snap.label,
        event: "appeared",
        description: entity.description,
      });
    } else if (!entity && previousEntity) {
      history.push({
        snapshot_id: snap.id,
        timestamp: snap.timestamp,
        label: snap.label,
        event: "disappeared",
      });
    } else if (entity && previousEntity) {
      if (entity.description !== previousEntity.description) {
        history.push({
          snapshot_id: snap.id,
          timestamp: snap.timestamp,
          label: snap.label,
          event: "modified",
          description: entity.description,
        });
      } else {
        history.push({
          snapshot_id: snap.id,
          timestamp: snap.timestamp,
          label: snap.label,
          event: "unchanged",
        });
      }
    }

    previousEntity = entity
      ? { name: entity.name, description: entity.description }
      : null;
  }

  return history;
}

/**
 * Get a summary of how the timeline has evolved.
 */
export function timelineSummary(timeline: Timeline): string {
  const lines: string[] = [];
  lines.push(`Timeline: ${timeline.name}`);
  lines.push(`Snapshots: ${timeline.snapshots.length}`);
  lines.push("");

  for (const snap of timeline.snapshots) {
    const diffStr = snap.diff_from_previous
      ? ` (${snap.diff_from_previous.summary})`
      : " (initial)";
    lines.push(
      `  ${snap.timestamp} ${snap.label ?? ""} — ${snap.stats.entities} entities, ${snap.stats.relations} relations${diffStr}`,
    );
  }

  if (timeline.snapshots.length >= 2) {
    const first = timeline.snapshots[0];
    const last = timeline.snapshots[timeline.snapshots.length - 1];
    lines.push("");
    lines.push(
      `Growth: ${first.stats.entities} → ${last.stats.entities} entities, ${first.stats.relations} → ${last.stats.relations} relations`,
    );
  }

  return lines.join("\n");
}