meridian-core 0.1.0 → 0.1.2

package/dist/index.js

@@ -1,7 +1,1220 @@
 #!/usr/bin/env node
-import { runCli } from './cli.js';
+
+// src/cli.ts
+import { Command as Command7 } from "commander";
+
+// src/version.ts
+import { createRequire } from "node:module";
+var require2 = createRequire(import.meta.url);
+var { version } = require2("../package.json");
+var CLI_VERSION = version;
+
+// src/commands/analyze.ts
+import { Command as Command2 } from "commander";
+
+// ../core/src/analyze.ts
+import { createRequire as createRequire2 } from "node:module";
+
+// ../core/src/logger.ts
+var Logger = class {
+  level;
+  levels = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3
+  };
+  constructor(level = "info") {
+    this.level = level;
+  }
+  /**
+   * @param message - Log message
+   * @param context - Optional structured context
+   */
+  debug(message, context) {
+    this.log("debug", message, context);
+  }
+  /**
+   * @param message - Log message
+   * @param context - Optional structured context
+   */
+  info(message, context) {
+    this.log("info", message, context);
+  }
+  /**
+   * @param message - Log message
+   * @param context - Optional structured context
+   */
+  warn(message, context) {
+    this.log("warn", message, context);
+  }
+  /**
+   * @param message - Log message
+   * @param context - Optional structured context
+   */
+  error(message, context) {
+    this.log("error", message, context);
+  }
+  log(level, message, context) {
+    if (this.levels[level] < this.levels[this.level]) return;
+    const entry = {
+      level,
+      message,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      ...context && { context }
+    };
+    const output = JSON.stringify(entry);
+    if (level === "error") {
+      console.error(output);
+    } else if (level === "warn") {
+      console.warn(output);
+    } else {
+      console.log(output);
+    }
+  }
+};
+var logger = new Logger(
+  process.env.LOG_LEVEL ?? "info"
+);
+
+// ../core/src/field/index.ts
+function buildFieldGraph(trace2, context, options) {
+  logger.info("field:start", { contracts: context.footprintContracts.length });
+  const manifest = options?.manifest;
+  const contracts = new Set(context.footprintContracts);
+  for (const step of trace2.execution_path) {
+    if (step.contract_id) contracts.add(step.contract_id);
+  }
+  const dependencyGraph = [];
+  const manifestLookup = buildManifestLookup(manifest);
+  for (const address of contracts) {
+    const manifestEntry = manifestLookup.get(address);
+    const dependencies = manifestEntry?.dependencies ?? [];
+    dependencyGraph.push({
+      address,
+      name: manifestEntry?.name,
+      dependencies,
+      depth: dependencies.length > 0 ? 1 : 0
+    });
+  }
+  const manifestCoverage = computeManifestCoverage(contracts, manifest);
+  return {
+    contracts_mapped: dependencyGraph.length,
+    dependency_graph: dependencyGraph,
+    ttl_warnings: [],
+    manifest_coverage: manifestCoverage
+  };
+}
+function buildManifestLookup(manifest) {
+  const lookup = /* @__PURE__ */ new Map();
+  if (!manifest) return lookup;
+  for (const contract of manifest.contracts) {
+    lookup.set(contract.address, {
+      name: contract.name,
+      dependencies: contract.dependencies
+    });
+  }
+  return lookup;
+}
+function computeManifestCoverage(contracts, manifest) {
+  if (!manifest || contracts.size === 0) return 0;
+  const manifestAddresses = new Set(manifest.contracts.map((c) => c.address));
+  let covered = 0;
+  for (const addr of contracts) {
+    if (manifestAddresses.has(addr)) covered++;
+  }
+  return covered / contracts.size;
+}
+
+// ../core/src/gravity/index.ts
+function scoreGravity(trace2, field2, options) {
+  logger.info("gravity:start", { contracts: field2.contracts_mapped });
+  const manifest = options?.manifest;
+  const manifestLookup = buildManifestLookup2(manifest);
+  const affectedContracts = [];
+  const critical = [];
+  const warning = [];
+  const safe = [];
+  const monitor = [];
+  for (const node of field2.dependency_graph) {
+    const manifestEntry = manifestLookup.get(node.address);
+    let impact = "SAFE";
+    let reason = "Read-only dependency";
+    if (!trace2.success) {
+      const failedContract = trace2.failure_point?.contract_id;
+      if (failedContract === node.address) {
+        impact = "CRITICAL";
+        reason = trace2.failure_point?.root_cause ?? "Direct failure point";
+        critical.push(node.address);
+      } else if (node.dependencies.length > 0) {
+        impact = "MONITOR";
+        reason = "Indirect dependency of failed contract";
+        monitor.push(node.address);
+      } else {
+        safe.push(node.address);
+      }
+    } else {
+      const hasWrite = trace2.execution_path.some(
+        (s) => s.contract_id === node.address && s.type === "invoke"
+      );
+      if (hasWrite) {
+        impact = "WARNING";
+        reason = "Contract receives state writes";
+        warning.push(node.address);
+      } else {
+        safe.push(node.address);
+      }
+    }
+    affectedContracts.push({
+      address: node.address,
+      name: manifestEntry?.name ?? node.name,
+      impact,
+      active_users: manifestEntry?.active_users,
+      reason
+    });
+  }
+  const totalAffectedUsers = affectedContracts.reduce(
+    (sum, c) => sum + (c.active_users ?? 0),
+    0
+  );
+  const blastRadius = computeBlastRadius(critical.length, warning.length, field2.contracts_mapped);
+  const recovery = critical.length > 0 ? "PARTIAL" : "FULL";
+  return {
+    blast_radius: blastRadius,
+    affected_contracts: affectedContracts,
+    critical,
+    warning,
+    safe,
+    monitor,
+    total_affected_users: totalAffectedUsers,
+    recovery
+  };
+}
+function buildManifestLookup2(manifest) {
+  const lookup = /* @__PURE__ */ new Map();
+  if (!manifest) return lookup;
+  for (const c of manifest.contracts) {
+    lookup.set(c.address, { name: c.name, active_users: c.active_users });
+  }
+  return lookup;
+}
+function computeBlastRadius(criticalCount, warningCount, totalContracts) {
+  if (totalContracts === 0) return 0;
+  const score = (criticalCount * 40 + warningCount * 15) / totalContracts;
+  return Math.min(100, Math.round(score * 100) / 100);
+}
+
+// ../core/src/errors.ts
+var STELLAR_ERROR_TAXONOMY = {
+  "transaction failed": {
+    code: "TX_FAILED",
+    hint: "Review simulation failure_point for the exact contract and function that failed."
+  },
+  "bad sequence": {
+    code: "BAD_SEQUENCE",
+    hint: "Fetch the current account sequence number and rebuild the transaction."
+  },
+  "tx_bad_auth": {
+    code: "BAD_AUTH",
+    hint: "Ensure all required signers have signed and auth entries are valid."
+  },
+  "tx_insufficient_fee": {
+    code: "INSUFFICIENT_FEE",
+    hint: "Increase the fee to cover minResourceFee from simulation."
+  },
+  "tx_too_early": {
+    code: "TX_TOO_EARLY",
+    hint: "Wait until the minTime precondition is satisfied."
+  },
+  "tx_too_late": {
+    code: "TX_TOO_LATE",
+    hint: "Rebuild the transaction \u2014 the maxTime precondition has expired."
+  },
+  "entry_archived": {
+    code: "ENTRY_ARCHIVED",
+    hint: "Restore the archived ledger entry before submitting."
+  },
+  "contract_not_found": {
+    code: "CONTRACT_NOT_FOUND",
+    hint: "Verify the contract address exists on the target network."
+  },
+  "timeout": {
+    code: "RPC_TIMEOUT",
+    hint: "Retry the request or check RPC endpoint availability."
+  },
+  "network": {
+    code: "RPC_NETWORK_ERROR",
+    hint: "Check network connectivity and RPC endpoint configuration."
+  }
+};
+function classifyStellarError(raw, layer) {
+  const message = typeof raw === "string" ? raw : raw.message;
+  const lower = message.toLowerCase();
+  for (const [pattern, classification] of Object.entries(STELLAR_ERROR_TAXONOMY)) {
+    if (lower.includes(pattern)) {
+      return {
+        error: message,
+        code: classification.code,
+        hint: classification.hint,
+        layer
+      };
+    }
+  }
+  return {
+    error: message,
+    code: "STELLAR_UNKNOWN",
+    hint: "Check transaction XDR validity and network configuration.",
+    layer
+  };
+}
+function createMeridianError(error, code, hint, layer) {
+  return { error, code, hint, layer };
+}
+
+// ../core/src/trace/parser.ts
+import {
+  Address,
+  FeeBumpTransaction,
+  TransactionBuilder,
+  humanizeEvents,
+  xdr
+} from "@stellar/stellar-sdk";
+var STALENESS_THRESHOLD = 5;
+function parseExecutionPath(txXdr) {
+  const steps = [];
+  let index = 0;
+  try {
+    let tx;
+    try {
+      tx = TransactionBuilder.fromXDR(txXdr, "Public Global Stellar Network ; September 2015");
+    } catch {
+      tx = TransactionBuilder.fromXDR(txXdr, "Test SDF Network ; September 2015");
+    }
+    const envelope = tx instanceof FeeBumpTransaction ? tx.innerTransaction : tx;
+    for (const op of envelope.operations) {
+      steps.push(parseOperation(op, index));
+      index++;
+    }
+  } catch {
+    steps.push({
+      index: 0,
+      type: "classic",
+      description: "Unable to parse transaction XDR \u2014 raw simulation only"
+    });
+  }
+  return steps;
+}
+function parseOperation(op, index) {
+  if (op.type === "invokeHostFunction") {
+    const hostFn = op;
+    const fn = hostFn.func;
+    let contractId;
+    let functionName;
+    if (fn && typeof fn === "object" && "invokeContract" in fn) {
+      const invoke = fn;
+      contractId = invoke.invokeContract?.contractAddress;
+      functionName = invoke.invokeContract?.functionName;
+    }
+    return {
+      index,
+      type: "invoke",
+      contract_id: contractId,
+      function_name: functionName,
+      description: `Invoke ${functionName ?? "host function"} on ${contractId ?? "unknown contract"}`
+    };
+  }
+  return {
+    index,
+    type: "classic",
+    description: `Classic operation: ${op.type}`
+  };
+}
+function parseAuthEntries(events) {
+  const entries = [];
+  const humanized = humanizeEvents(events);
+  for (const event of humanized) {
+    const topicStrs = event.topics.map((t) => String(t));
+    const topicStr = topicStrs.join(":");
+    if (topicStr.includes("require_auth") || topicStr.includes("auth")) {
+      entries.push({
+        address: event.contractId ?? "unknown",
+        contract_id: event.contractId,
+        credentials: topicStrs
+      });
+    }
+  }
+  return entries;
+}
+function computeFeeEstimate(txXdr, minResourceFee) {
+  let classicBaseFee = 100;
+  try {
+    let tx;
+    try {
+      tx = TransactionBuilder.fromXDR(txXdr, "Public Global Stellar Network ; September 2015");
+    } catch {
+      tx = TransactionBuilder.fromXDR(txXdr, "Test SDF Network ; September 2015");
+    }
+    const envelope = tx instanceof FeeBumpTransaction ? tx.innerTransaction : tx;
+    classicBaseFee = Number(envelope.fee) || 100;
+  } catch {
+  }
+  const resourceFee = parseInt(minResourceFee, 10) || 0;
+  return {
+    classic_base_fee: classicBaseFee,
+    min_resource_fee: resourceFee,
+    total_fee: classicBaseFee + resourceFee
+  };
+}
+function extractResourceUsage(sorobanData) {
+  if (!sorobanData) {
+    return { cpu_instructions: 0, memory_bytes: 0, read_bytes: 0, write_bytes: 0 };
+  }
+  const resources = sorobanData.build().resources();
+  return {
+    cpu_instructions: resources.instructions(),
+    memory_bytes: 0,
+    read_bytes: resources.readBytes(),
+    write_bytes: resources.writeBytes()
+  };
+}
+function parseFailurePoint(error, executionPath) {
+  const lastInvoke = [...executionPath].reverse().find((s) => s.type === "invoke");
+  const errorLower = error.toLowerCase();
+  let errorCode = "SIMULATION_FAILED";
+  let rootCause = "Transaction simulation failed";
+  if (errorLower.includes("require_auth") || errorLower.includes("auth")) {
+    errorCode = "AUTH_REQUIRED";
+    rootCause = "Missing or invalid authorization credentials";
+  } else if (errorLower.includes("archived") || errorLower.includes("ttl")) {
+    errorCode = "ENTRY_ARCHIVED";
+    rootCause = "Ledger entry is archived or TTL expired";
+  } else if (errorLower.includes("insufficient")) {
+    errorCode = "INSUFFICIENT_BALANCE";
+    rootCause = "Insufficient balance for operation";
+  }
+  return {
+    step_index: lastInvoke?.index ?? 0,
+    contract_id: lastInvoke?.contract_id,
+    function_name: lastInvoke?.function_name,
+    error_code: errorCode,
+    error_message: error,
+    root_cause: rootCause
+  };
+}
+function parseSimulationResult(raw, txXdr) {
+  const executionPath = parseExecutionPath(txXdr);
+  const stalenessDelta = raw.latestLedger - raw.simulationLedger;
+  const isStale = stalenessDelta > STALENESS_THRESHOLD;
+  if (!raw.success && raw.error) {
+    return {
+      success: false,
+      failure_point: parseFailurePoint(raw.error, executionPath),
+      execution_path: executionPath,
+      auth_entries: parseAuthEntries(raw.events),
+      fee_estimate: computeFeeEstimate(txXdr, raw.minResourceFee),
+      resource_usage: extractResourceUsage(raw.sorobanData),
+      staleness_warning: isStale
+    };
+  }
+  return {
+    success: true,
+    execution_path: executionPath,
+    auth_entries: parseAuthEntries(raw.events),
+    fee_estimate: computeFeeEstimate(txXdr, raw.minResourceFee),
+    resource_usage: extractResourceUsage(raw.sorobanData),
+    staleness_warning: isStale
+  };
+}
+
+// ../core/src/trace/rpc.ts
+import { rpc, TransactionBuilder as TransactionBuilder2, Networks } from "@stellar/stellar-sdk";
+var DEFAULT_TIMEOUT_MS = 3e4;
+function resolveRpcUrl(network) {
+  const envKey = network === "mainnet" ? "STELLAR_RPC_MAINNET" : "STELLAR_RPC_TESTNET";
+  const url = process.env[envKey];
+  if (!url) {
+    throw new Error(`Missing environment variable: ${envKey}`);
+  }
+  return url;
+}
+async function withTimeout(promise, timeoutMs, label) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`timeout: ${label} exceeded ${timeoutMs}ms`)), timeoutMs);
+  });
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function simulateTransaction(txXdr, rpcUrl, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  const server = new rpc.Server(rpcUrl, { allowHttp: rpcUrl.startsWith("http://") });
+  try {
+    logger.debug("simulateTransaction:start", { rpcUrl });
+    const latestLedgerResponse = await withTimeout(
+      server.getLatestLedger(),
+      timeoutMs,
+      "getLatestLedger"
+    );
+    const transaction = TransactionBuilder2.fromXDR(
+      txXdr,
+      Networks.TESTNET
+      // network passphrase resolved during parse; RPC validates
+    );
+    const simResponse = await withTimeout(
+      server.simulateTransaction(transaction),
+      timeoutMs,
+      "simulateTransaction"
+    );
+    if (rpc.Api.isSimulationError(simResponse)) {
+      return {
+        success: false,
+        latestLedger: latestLedgerResponse.sequence,
+        simulationLedger: latestLedgerResponse.sequence,
+        minResourceFee: "0",
+        events: simResponse.events,
+        error: simResponse.error
+      };
+    }
+    return {
+      success: true,
+      latestLedger: latestLedgerResponse.sequence,
+      simulationLedger: latestLedgerResponse.sequence,
+      minResourceFee: simResponse.minResourceFee,
+      events: simResponse.events ?? [],
+      sorobanData: simResponse.transactionData
+    };
+  } catch (err) {
+    logger.error("simulateTransaction:failed", {
+      error: err instanceof Error ? err.message : String(err)
+    });
+    return classifyStellarError(err instanceof Error ? err : String(err), "TRACE");
+  }
+}
+
+// ../core/src/trace/index.ts
+async function trace(txXdr, options) {
+  const network = options?.network ?? "testnet";
+  const rpcUrl = options?.rpcUrl ?? resolveRpcUrl(network);
+  const timeoutMs = options?.timeoutMs ?? 3e4;
+  logger.info("trace:start", { network });
+  if (!txXdr || txXdr.trim().length === 0) {
+    return classifyStellarError("Invalid transaction XDR: empty input", "TRACE");
+  }
+  const raw = await simulateTransaction(txXdr, rpcUrl, timeoutMs);
+  if ("layer" in raw) {
+    return raw;
+  }
+  const result = parseSimulationResult(raw, txXdr);
+  logger.info("trace:complete", { success: result.success });
+  return result;
+}
+
+// ../core/src/analyze.ts
+function resolveEngineVersion() {
+  if (true) {
+    return "0.1.1";
+  }
+  const require3 = createRequire2(import.meta.url);
+  const { version: version2 } = require3("../package.json");
+  return version2;
+}
+var MERIDIAN_VERSION = resolveEngineVersion();
+var DEFAULT_CONFIDENCE_THRESHOLD = 0.75;
+function computeVerdict(traceSuccess, blastRadius, confidence, threshold, isStale) {
+  if (!traceSuccess) {
+    return { verdict: "ABORT", confidence: Math.min(confidence, 0.95) };
+  }
+  if (isStale || confidence < threshold) {
+    return { verdict: "WARN", confidence };
+  }
+  if (blastRadius >= 50) {
+    return { verdict: "WARN", confidence };
+  }
+  return { verdict: "CLEAR", confidence };
+}
+function computeConfidence(traceSuccess, manifestCoverage, isStale) {
+  let confidence = traceSuccess ? 0.85 : 0.3;
+  confidence += manifestCoverage * 0.1;
+  if (isStale) confidence -= 0.2;
+  return Math.max(0, Math.min(1, Math.round(confidence * 100) / 100));
+}
+function generateFixSequence(traceSuccess, failureRootCause) {
+  if (traceSuccess) return void 0;
+  return [
+    {
+      order: 1,
+      operation: "diagnose",
+      description: failureRootCause ?? "Review simulation failure point",
+      estimated_cost_stroops: 0,
+      estimated_time_minutes: 5
+    },
+    {
+      order: 2,
+      operation: "fix_auth",
+      description: "Ensure all require_auth credentials are signed and valid",
+      estimated_cost_stroops: 100,
+      estimated_time_minutes: 10
+    },
+    {
+      order: 3,
+      operation: "resimulate",
+      description: "Re-run MERIDIAN analysis after applying fixes",
+      estimated_cost_stroops: 0,
+      estimated_time_minutes: 2
+    }
+  ];
+}
+async function analyze(request) {
+  const startMs = Date.now();
+  const threshold = request.options?.confidence_threshold ?? DEFAULT_CONFIDENCE_THRESHOLD;
+  logger.info("analyze:start", { network: request.network });
+  const traceResult = await trace(request.tx, {
+    network: request.network,
+    rpcUrl: request.options?.rpc_url
+  });
+  if ("layer" in traceResult) {
+    return traceResult;
+  }
+  const context = {
+    ledgerSequence: 0,
+    latestLedger: 0,
+    footprintContracts: extractFootprintContracts(traceResult),
+    readOnly: [],
+    readWrite: []
+  };
+  const fieldResult = request.options?.skip_field ? emptyFieldResult() : buildFieldGraph(traceResult, context, {
+    network: request.network,
+    manifest: request.ecosystem
+  });
+  const gravityResult = request.options?.skip_gravity ? emptyGravityResult() : scoreGravity(traceResult, fieldResult, { manifest: request.ecosystem });
+  const isStale = traceResult.staleness_warning ?? false;
+  const confidence = computeConfidence(
+    traceResult.success,
+    fieldResult.manifest_coverage,
+    isStale
+  );
+  const { verdict } = computeVerdict(
+    traceResult.success,
+    gravityResult.blast_radius,
+    confidence,
+    threshold,
+    isStale
+  );
+  const warnings = [];
+  if (isStale) warnings.push("Simulation ledger is stale (>5 ledgers behind latest)");
+  if (confidence < threshold) {
+    warnings.push(`Confidence ${confidence} is below threshold ${threshold}`);
+  }
+  const fixSequence = generateFixSequence(
+    traceResult.success,
+    traceResult.failure_point?.root_cause
+  );
+  return {
+    product: "MERIDIAN",
+    version: MERIDIAN_VERSION,
+    verdict,
+    confidence,
+    trace: traceResult,
+    field: fieldResult,
+    gravity: gravityResult,
+    fix_sequence: fixSequence,
+    warnings: warnings.length > 0 ? warnings : void 0,
+    meta: {
+      analyzed_at: (/* @__PURE__ */ new Date()).toISOString(),
+      ledger_sequence: context.ledgerSequence,
+      simulation_stale: isStale,
+      network: request.network,
+      processing_ms: Date.now() - startMs
+    }
+  };
+}
+function extractFootprintContracts(trace2) {
+  const contracts = /* @__PURE__ */ new Set();
+  for (const step of trace2.execution_path) {
+    if (step.contract_id) contracts.add(step.contract_id);
+  }
+  return [...contracts];
+}
+function emptyFieldResult() {
+  return {
+    contracts_mapped: 0,
+    dependency_graph: [],
+    ttl_warnings: [],
+    manifest_coverage: 0
+  };
+}
+function emptyGravityResult() {
+  return {
+    blast_radius: 0,
+    affected_contracts: [],
+    critical: [],
+    warning: [],
+    safe: [],
+    monitor: [],
+    total_affected_users: 0,
+    recovery: "FULL"
+  };
+}
+
+// ../ai/src/brief.ts
+import Anthropic from "@anthropic-ai/sdk";
+var BRIEF_MODEL = "claude-sonnet-4-6";
+var MAX_BRIEF_WORDS = 300;
+var BRIEF_SYSTEM_PROMPT = `You are MERIDIAN BRIEF \u2014 a Stellar pre-execution risk synthesis engine.
+
+Your job: produce a structured mission briefing from TRACE and GRAVITY JSON inputs.
+You must NEVER hallucinate contract names, addresses, ledger values, or user counts.
+Every specific fact must come from the provided structured data.
+
+## Stellar Error Taxonomy
+- AUTH_REQUIRED: Missing or invalid require_auth credentials
+- ENTRY_ARCHIVED: Ledger entry TTL expired or archived
+- INSUFFICIENT_BALANCE: Account lacks required balance
+- BAD_SEQUENCE: Transaction sequence number mismatch
+- TX_FAILED: General simulation failure
+
+## Output Format (strict, max 300 words)
+1. **Verdict Reason** (1-2 sentences): Why CLEAR, WARN, or ABORT
+2. **Affected Parties**: Who is impacted and how many users (from GRAVITY data only)
+3. **Fix Sequence**: Numbered steps with estimated stroop costs (from fix_sequence data)
+4. **Confidence**: Explain confidence score; if < 0.75, explicitly recommend re-running after fixes
+
+Never use conversational prose. Be direct and actionable.`;
+function truncateToWordLimit(text, maxWords) {
+  const words = text.trim().split(/\s+/);
+  if (words.length <= maxWords) return text;
+  return words.slice(0, maxWords).join(" ") + "\u2026";
+}
+function generateFallbackBrief(input) {
+  const lines = [];
+  lines.push(`**Verdict: ${input.verdict}** (confidence: ${input.confidence})`);
+  if (!input.trace.success && input.trace.failure_point) {
+    const fp = input.trace.failure_point;
+    lines.push(
+      `Simulation failed at step ${fp.step_index}: ${fp.root_cause} (${fp.error_code}).`
+    );
+  } else {
+    lines.push("Transaction simulation succeeded with no critical failures detected.");
+  }
+  if (input.gravity.total_affected_users > 0) {
+    lines.push(
+      `**Affected Parties**: ${input.gravity.total_affected_users} users across ${input.gravity.affected_contracts.length} contracts.`
+    );
+  }
+  if (input.gravity.critical.length > 0) {
+    lines.push(`**Critical contracts**: ${input.gravity.critical.join(", ")}`);
+  }
+  if (input.fix_sequence && input.fix_sequence.length > 0) {
+    lines.push("**Fix Sequence**:");
+    for (const step of input.fix_sequence) {
+      lines.push(
+        `${step.order}. ${step.operation}: ${step.description} (~${step.estimated_cost_stroops} stroops, ~${step.estimated_time_minutes}min)`
+      );
+    }
+  }
+  if (input.confidence < 0.75) {
+    lines.push(
+      `**Confidence**: ${input.confidence} is below the 0.75 threshold. Re-run analysis after applying fixes.`
+    );
+  }
+  if (input.warnings && input.warnings.length > 0) {
+    lines.push(`**Warnings**: ${input.warnings.join("; ")}`);
+  }
+  return truncateToWordLimit(lines.join("\n"), MAX_BRIEF_WORDS);
+}
+async function synthesizeBrief(input, options) {
+  const apiKey = options?.apiKey ?? process.env.ANTHROPIC_API_KEY;
+  const maxWords = options?.maxWords ?? MAX_BRIEF_WORDS;
+  if (!apiKey) {
+    return generateFallbackBrief(input);
+  }
+  const client = new Anthropic({ apiKey });
+  const contextPayload = {
+    verdict: input.verdict,
+    confidence: input.confidence,
+    trace: {
+      success: input.trace.success,
+      failure_point: input.trace.failure_point,
+      execution_path: input.trace.execution_path,
+      auth_entries: input.trace.auth_entries,
+      fee_estimate: input.trace.fee_estimate,
+      staleness_warning: input.trace.staleness_warning
+    },
+    gravity: {
+      blast_radius: input.gravity.blast_radius,
+      affected_contracts: input.gravity.affected_contracts,
+      critical: input.gravity.critical,
+      warning: input.gravity.warning,
+      total_affected_users: input.gravity.total_affected_users,
+      recovery: input.gravity.recovery
+    },
+    fix_sequence: input.fix_sequence,
+    warnings: input.warnings
+  };
+  try {
+    const response = await client.messages.create({
+      model: BRIEF_MODEL,
+      max_tokens: 1024,
+      system: BRIEF_SYSTEM_PROMPT,
+      messages: [
+        {
+          role: "user",
+          content: `Synthesize a MERIDIAN risk brief from this structured analysis data:
+
+${JSON.stringify(contextPayload, null, 2)}`
+        }
+      ]
+    });
+    const textBlock = response.content.find((block) => block.type === "text");
+    if (!textBlock || textBlock.type !== "text") {
+      return createMeridianError(
+        "BRIEF synthesis returned no text content",
+        "BRIEF_EMPTY",
+        "Retry the analysis or check Anthropic API status",
+        "BRIEF"
+      );
+    }
+    return truncateToWordLimit(textBlock.text, maxWords);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return createMeridianError(
+      `BRIEF synthesis failed: ${message}`,
+      "BRIEF_API_ERROR",
+      "Check ANTHROPIC_API_KEY and retry. Fallback brief will be used.",
+      "BRIEF"
+    );
+  }
+}
+
+// src/lib/input.ts
+import { readFile } from "node:fs/promises";
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf-8").trim();
+}
+async function resolveTxInput(txArg, filePath) {
+  if (filePath) {
+    const contents = await readFile(filePath, "utf-8");
+    return contents.trim();
+  }
+  if (txArg && txArg.trim().length > 0) {
+    return txArg.trim();
+  }
+  if (!process.stdin.isTTY) {
+    const fromStdin = await readStdin();
+    if (fromStdin.length > 0) return fromStdin;
+  }
+  throw new Error(
+    "No transaction XDR provided. Pass it as an argument, via --file <path>, or pipe it over stdin."
+  );
+}
+
+// src/lib/manifest.ts
+import { readFile as readFile2 } from "node:fs/promises";
+async function loadManifest(filePath) {
+  if (!filePath) return void 0;
+  let raw;
+  try {
+    raw = await readFile2(filePath, "utf-8");
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to read ecosystem manifest at ${filePath}: ${message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Ecosystem manifest at ${filePath} is not valid JSON: ${message}`);
+  }
+  if (typeof parsed !== "object" || parsed === null || !Array.isArray(parsed.contracts)) {
+    throw new Error(
+      `Ecosystem manifest at ${filePath} must be an object with a "contracts" array.`
+    );
+  }
+  return parsed;
+}
+
+// src/lib/errors.ts
+import pc from "picocolors";
+function isMeridianError(value) {
+  return typeof value === "object" && value !== null && "layer" in value && "code" in value && "hint" in value;
+}
+function failWithMeridianError(error) {
+  console.error(pc.red(pc.bold(`\u2716 [${error.layer}] ${error.code}`)));
+  console.error(pc.red(error.error));
+  console.error(pc.dim(`hint: ${error.hint}`));
+  process.exit(1);
+}
+function failWithError(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(pc.red(pc.bold("\u2716 Error")));
+  console.error(pc.red(message));
+  process.exit(1);
+}
+
+// src/lib/output.ts
+import pc2 from "picocolors";
+function printJson(value) {
+  console.log(JSON.stringify(value, null, 2));
+}
+function verdictBadge(verdict) {
+  switch (verdict) {
+    case "CLEAR":
+      return pc2.bgGreen(pc2.black(" CLEAR "));
+    case "WARN":
+      return pc2.bgYellow(pc2.black(" WARN "));
+    case "ABORT":
+      return pc2.bgRed(pc2.white(pc2.bold(" ABORT ")));
+    default:
+      return verdict;
+  }
+}
+function section(title) {
+  console.log("");
+  console.log(pc2.bold(pc2.cyan(`\u2500\u2500 ${title} `.padEnd(48, "\u2500"))));
+}
+function field(label, value) {
+  console.log(`  ${pc2.dim(label + ":")} ${value}`);
+}
+function printTrace(trace2) {
+  section("TRACE");
+  field("success", trace2.success ? pc2.green("true") : pc2.red("false"));
+  if (trace2.staleness_warning) {
+    field("staleness_warning", pc2.yellow("true"));
+  }
+  if (trace2.failure_point) {
+    const fp = trace2.failure_point;
+    console.log(`  ${pc2.red("failure_point")}:`);
+    field("  step_index", fp.step_index);
+    if (fp.contract_id) field("  contract_id", fp.contract_id);
+    if (fp.function_name) field("  function_name", fp.function_name);
+    field("  error_code", fp.error_code);
+    field("  root_cause", fp.root_cause);
+  }
+  field("execution_path", `${trace2.execution_path.length} step(s)`);
+  field("auth_entries", `${trace2.auth_entries.length} entrie(s)`);
+  field(
+    "fee_estimate",
+    `total=${trace2.fee_estimate.total_fee} base=${trace2.fee_estimate.classic_base_fee} min_resource=${trace2.fee_estimate.min_resource_fee}`
+  );
+  field(
+    "resource_usage",
+    `cpu=${trace2.resource_usage.cpu_instructions} mem=${trace2.resource_usage.memory_bytes}b read=${trace2.resource_usage.read_bytes}b write=${trace2.resource_usage.write_bytes}b`
+  );
+}
+function printField(result) {
+  section("FIELD");
+  field("contracts_mapped", result.contracts_mapped);
+  field("manifest_coverage", `${Math.round(result.manifest_coverage * 100)}%`);
+  if (result.ttl_warnings.length > 0) {
+    console.log(`  ${pc2.yellow("ttl_warnings")}:`);
+    for (const warning of result.ttl_warnings) {
+      console.log(
+        `    - ${warning.contract_id} (${warning.ledger_key}) ttl_remaining=${warning.ttl_remaining} [${warning.severity}]`
+      );
+    }
+  }
+  if (result.dependency_graph.length > 0) {
+    console.log(`  ${pc2.dim("dependency_graph")}:`);
+    for (const node of result.dependency_graph) {
+      const label = node.name ? `${node.name} (${node.address})` : node.address;
+      const deps = node.dependencies.length > 0 ? ` \u2192 ${node.dependencies.join(", ")}` : "";
+      console.log(`    - ${label}${deps}`);
+    }
+  }
+}
+function printGravity(result) {
+  section("GRAVITY");
+  field("blast_radius", result.blast_radius);
+  field("total_affected_users", result.total_affected_users);
+  field("recovery", result.recovery);
+  if (result.critical.length > 0) field("critical", pc2.red(result.critical.join(", ")));
+  if (result.warning.length > 0) field("warning", pc2.yellow(result.warning.join(", ")));
+  if (result.monitor.length > 0) field("monitor", pc2.blue(result.monitor.join(", ")));
+  if (result.safe.length > 0) field("safe", pc2.green(result.safe.join(", ")));
+  if (result.affected_contracts.length > 0) {
+    console.log(`  ${pc2.dim("affected_contracts")}:`);
+    for (const contract of result.affected_contracts) {
+      const label = contract.name ? `${contract.name} (${contract.address})` : contract.address;
+      console.log(`    - [${contract.impact}] ${label} \u2014 ${contract.reason}`);
+    }
+  }
+}
+function printAnalysis(response) {
+  console.log("");
+  console.log(`${pc2.bold("MERIDIAN")} v${response.version}  ${verdictBadge(response.verdict)}  confidence=${response.confidence}`);
+  printTrace(response.trace);
+  printField(response.field);
+  printGravity(response.gravity);
+  if (response.fix_sequence && response.fix_sequence.length > 0) {
+    section("FIX SEQUENCE");
+    for (const step of response.fix_sequence) {
+      console.log(
+        `  ${pc2.bold(String(step.order) + ".")} ${step.operation} \u2014 ${step.description} ${pc2.dim(`(~${step.estimated_cost_stroops} stroops, ~${step.estimated_time_minutes}min)`)}`
+      );
+    }
+  }
+  if (response.warnings && response.warnings.length > 0) {
+    section("WARNINGS");
+    for (const warning of response.warnings) {
+      console.log(`  ${pc2.yellow("\u26A0")} ${warning}`);
+    }
+  }
+  section("BRIEF");
+  console.log(response.brief);
+  section("META");
+  field("analyzed_at", response.meta.analyzed_at);
+  field("network", response.meta.network);
+  field("ledger_sequence", response.meta.ledger_sequence);
+  field("simulation_stale", response.meta.simulation_stale);
+  field("processing_ms", response.meta.processing_ms);
+  console.log("");
+}
+
+// src/lib/options.ts
+import { InvalidArgumentError } from "commander";
+function parseNetwork(value) {
+  if (value !== "mainnet" && value !== "testnet") {
+    throw new InvalidArgumentError('Network must be "mainnet" or "testnet".');
+  }
+  return value;
+}
+function parseThreshold(value) {
+  const parsed = Number.parseFloat(value);
+  if (Number.isNaN(parsed) || parsed < 0 || parsed > 1) {
+    throw new InvalidArgumentError("Confidence threshold must be a number between 0 and 1.");
+  }
+  return parsed;
+}
+function withCommonOptions(command) {
+  return command.argument("[tx]", "Base64-encoded transaction XDR").option("-n, --network <network>", "Stellar network (mainnet | testnet)", parseNetwork, "testnet").option("--rpc-url <url>", "Override the Soroban RPC endpoint (else read from env)").option("-f, --file <path>", "Read the transaction XDR from a file instead of an argument").option("-e, --ecosystem <path>", "Path to an ecosystem manifest JSON file").option("--json", "Print raw JSON instead of a formatted report");
+}
+
+// src/commands/analyze.ts
+function analyzeCommand() {
+  const command = new Command2("analyze").description(
+    "Run the full MERIDIAN pipeline (TRACE + FIELD + GRAVITY + BRIEF) on a transaction"
+  );
+  withCommonOptions(command).option("--skip-field", "Skip the FIELD dependency-mapping layer").option("--skip-gravity", "Skip the GRAVITY blast-radius layer").option("--confidence-threshold <n>", "Minimum confidence required for a CLEAR verdict", parseThreshold).option("--no-brief", "Skip GenAI BRIEF synthesis (structured layers only)").option("--api-key <key>", "Anthropic API key for BRIEF synthesis (else read from env)").action(async (tx, options) => {
+    try {
+      const txXdr = await resolveTxInput(tx, options.file);
+      const ecosystem = await loadManifest(options.ecosystem);
+      const result = await analyze({
+        tx: txXdr,
+        network: options.network,
+        ecosystem,
+        options: {
+          skip_field: options.skipField,
+          skip_gravity: options.skipGravity,
+          confidence_threshold: options.confidenceThreshold,
+          rpc_url: options.rpcUrl
+        }
+      });
+      if (isMeridianError(result)) {
+        if (options.json) {
+          printJson(result);
+          process.exit(1);
+        }
+        failWithMeridianError(result);
+      }
+      let brief = "BRIEF synthesis skipped (--no-brief).";
+      let warnings = result.warnings;
+      if (options.brief) {
+        const briefInput = {
+          verdict: result.verdict,
+          confidence: result.confidence,
+          trace: result.trace,
+          field: result.field,
+          gravity: result.gravity,
+          fix_sequence: result.fix_sequence,
+          warnings: result.warnings
+        };
+        const briefResult = await synthesizeBrief(briefInput, { apiKey: options.apiKey });
+        if (isMeridianError(briefResult)) {
+          brief = generateFallbackBrief(briefInput);
+          warnings = [...result.warnings ?? [], briefResult.error];
+        } else {
+          brief = briefResult;
+        }
+      }
+      const response = { ...result, brief, warnings };
+      if (options.json) {
+        printJson(response);
+        return;
+      }
+      printAnalysis(response);
+    } catch (err) {
+      failWithError(err);
+    }
+  });
+  return command;
+}
+
+// src/commands/trace.ts
+import { Command as Command3 } from "commander";
+function traceCommand() {
+  const command = new Command3("trace").description(
+    "Run the TRACE engine only \u2014 simulate a transaction and report the execution path"
+  );
+  withCommonOptions(command).action(async (tx, options) => {
+    try {
+      const txXdr = await resolveTxInput(tx, options.file);
+      const result = await trace(txXdr, { network: options.network, rpcUrl: options.rpcUrl });
+      if (isMeridianError(result)) {
+        if (options.json) {
+          printJson(result);
+          process.exit(1);
+        }
+        failWithMeridianError(result);
+      }
+      if (options.json) {
+        printJson(result);
+        return;
+      }
+      printTrace(result);
+    } catch (err) {
+      failWithError(err);
+    }
+  });
+  return command;
+}
+
+// src/commands/field.ts
+import { Command as Command4 } from "commander";
+function fieldCommand() {
+  const command = new Command4("field").description(
+    "Run TRACE + FIELD \u2014 map the dependency graph touched by a transaction"
+  );
+  withCommonOptions(command).action(async (tx, options) => {
+    try {
+      const txXdr = await resolveTxInput(tx, options.file);
+      const manifest = await loadManifest(options.ecosystem);
+      const traceResult = await trace(txXdr, { network: options.network, rpcUrl: options.rpcUrl });
+      if (isMeridianError(traceResult)) {
+        if (options.json) {
+          printJson(traceResult);
+          process.exit(1);
+        }
+        failWithMeridianError(traceResult);
+      }
+      const fieldResult = buildFieldGraph(
+        traceResult,
+        {
+          ledgerSequence: 0,
+          latestLedger: 0,
+          footprintContracts: [],
+          readOnly: [],
+          readWrite: []
+        },
+        { network: options.network, manifest }
+      );
+      if (options.json) {
+        printJson(fieldResult);
+        return;
+      }
+      printField(fieldResult);
+    } catch (err) {
+      failWithError(err);
+    }
+  });
+  return command;
+}
+
+// src/commands/gravity.ts
+import { Command as Command5 } from "commander";
+function gravityCommand() {
+  const command = new Command5("gravity").description(
+    "Run TRACE + FIELD + GRAVITY \u2014 score the blast radius of a transaction"
+  );
+  withCommonOptions(command).action(
+    async (tx, options) => {
+      try {
+        const txXdr = await resolveTxInput(tx, options.file);
+        const manifest = await loadManifest(options.ecosystem);
+        const traceResult = await trace(txXdr, { network: options.network, rpcUrl: options.rpcUrl });
+        if (isMeridianError(traceResult)) {
+          if (options.json) {
+            printJson(traceResult);
+            process.exit(1);
+          }
+          failWithMeridianError(traceResult);
+        }
+        const fieldResult = buildFieldGraph(
+          traceResult,
+          {
+            ledgerSequence: 0,
+            latestLedger: 0,
+            footprintContracts: [],
+            readOnly: [],
+            readWrite: []
+          },
+          { network: options.network, manifest }
+        );
+        const gravityResult = scoreGravity(traceResult, fieldResult, { manifest });
+        if (options.json) {
+          printJson(gravityResult);
+          return;
+        }
+        printGravity(gravityResult);
+      } catch (err) {
+        failWithError(err);
+      }
+    }
+  );
+  return command;
+}
+
+// src/commands/version.ts
+import { Command as Command6 } from "commander";
+function versionCommand() {
+  return new Command6("version").description("Print MERIDIAN CLI and core engine version").option("--json", "Print raw JSON instead of a formatted report").action((options) => {
+    if (options.json) {
+      printJson({ product: "MERIDIAN", cli_version: CLI_VERSION, engine_version: MERIDIAN_VERSION });
+      return;
+    }
+    console.log(`meridian-core v${CLI_VERSION} (engine v${MERIDIAN_VERSION})`);
+  });
+}
+
+// src/cli.ts
+function buildProgram() {
+  const program = new Command7("meridian").description(
+    "MERIDIAN \u2014 pre-execution intelligence for Stellar developers.\nKnow what crosses before it does."
+  ).version(CLI_VERSION, "-v, --version", "Print the meridian-core CLI version").addHelpText(
+    "after",
+    `
+Examples:
+  $ meridian analyze <base64-xdr> --network testnet
+  $ cat tx.xdr | meridian analyze --network mainnet --json
+  $ meridian trace --file tx.xdr --network testnet
+  $ meridian gravity <base64-xdr> --ecosystem manifest.json
+
+Environment:
+  STELLAR_RPC_TESTNET   Soroban RPC endpoint for testnet (or use --rpc-url)
+  STELLAR_RPC_MAINNET   Soroban RPC endpoint for mainnet (or use --rpc-url)
+  ANTHROPIC_API_KEY     Claude API key for BRIEF synthesis (optional, falls back to a deterministic brief)
+`
+  );
+  program.addCommand(analyzeCommand(), { isDefault: true });
+  program.addCommand(traceCommand());
+  program.addCommand(fieldCommand());
+  program.addCommand(gravityCommand());
+  program.addCommand(versionCommand());
+  return program;
+}
+async function runCli(argv = process.argv) {
+  const program = buildProgram();
+  await program.parseAsync(argv);
+}
+
+// src/index.ts
 runCli().catch((err) => {
-    console.error(err instanceof Error ? err.message : err);
-    process.exit(1);
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
 });
-//# sourceMappingURL=index.js.map