@datasynx/agentic-ai-cartography 2.2.0 → 2.3.0

package/dist/index.js

@@ -130,6 +130,8 @@ var DOMAIN_PALETTE = [
   "#5eead4"
 ];
 var DRIFT_FIELDS = ["type", "name", "domain", "subDomain", "qualityScore", "metadata", "tags", "owner", "cost"];
+var ANOMALY_KINDS = ["orphan", "shadow-it"];
+var ANOMALY_SEVERITIES = ["low", "medium", "high"];
 var DEFAULT_ANOMALY_THRESHOLDS = {
   orphanWeakDegree: 1,
   shadowConfidence: 0.4,
@@ -1275,8 +1277,8 @@ var cloudGcpScanner = {
   allowedCommands: ["gcloud"],
   detect: (ctx) => Boolean((ctx.commandExists ?? commandExists)("gcloud")),
   async scan(ctx) {
-    const { project } = parseScanHint(ctx.hint);
-    const pf = project ? ` --project ${project}` : "";
+    const { project: project2 } = parseScanHint(ctx.hint);
+    const pf = project2 ? ` --project ${project2}` : "";
     const runG = createScanRunner((c) => ctx.run(c, { timeout: 2e4 }), { threshold: 3 });
     const nodes = [];
     const edges = [];
@@ -1964,9 +1966,9 @@ async function buildCartographyToolHandlers(db, sessionId, opts = {}) {
     tool("scan_gcp_resources", "Scan Google Cloud Platform via gcloud CLI \u2014 100% readonly (list, describe)", {
       project: z2.string().regex(SCAN_ARG_PATTERNS["gcp-project"], "invalid GCP project id").optional().describe("GCP Project ID \u2014 default: current gcloud project")
     }, async (args) => {
-      const project = args["project"];
-      if (project) assertSafeScanArg("gcp-project", project);
-      return runScannerTool(cloudGcpScanner, project ? `project=${project}` : "");
+      const project2 = args["project"];
+      if (project2) assertSafeScanArg("gcp-project", project2);
+      return runScannerTool(cloudGcpScanner, project2 ? `project=${project2}` : "");
     }, { annotations: READ_SCAN }),
     tool("scan_azure_resources", "Scan Azure infrastructure via az CLI \u2014 100% readonly (list, show)", {
       subscription: z2.string().regex(SCAN_ARG_PATTERNS["azure-subscription"], "invalid Azure subscription id").optional().describe("Azure Subscription ID"),
@@ -2118,14 +2120,14 @@ async function buildCartographyToolHandlers(db, sessionId, opts = {}) {
         "neon"
       ];
       const found = [];
-      const notFound = [];
+      const notFound2 = [];
       for (const t of knownTools) {
         const r = commandExists(t);
         if (r) found.push(`${t}: ${r}`);
-        else notFound.push(t);
+        else notFound2.push(t);
       }
       results["TOOLS_FOUND"] = found.join("\n") || "(none found)";
-      results["TOOLS_NOT_FOUND"] = notFound.join(", ");
+      results["TOOLS_NOT_FOUND"] = notFound2.join(", ");
       if (hint) {
         const terms = hint.split(/[\s,]+/).filter(Boolean);
         const hintResults = [];
@@ -4262,6 +4264,86 @@ var SqliteStoreBackend = class {
   }
 };
 
+// src/store/query.ts
+var NotFoundError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NotFoundError";
+  }
+};
+var MAX_NODE_LIMIT = 1e3;
+var MAX_DEPTH = 64;
+function clamp(value, min, max) {
+  return Math.floor(Math.max(min, Math.min(value, max)));
+}
+var SqliteQueryBackend = class {
+  constructor(db, defaultSession = "latest") {
+    this.db = db;
+    this.defaultSession = defaultSession;
+  }
+  /**
+   * Resolve the session id for a request, scoped to `ctx.tenant`. An explicit id must
+   * belong to the tenant or it resolves to undefined (cross-tenant isolation); else the
+   * newest `discover` session for the tenant. Mirrors `resolveSession` in the MCP server.
+   */
+  resolveSession(ctx, sessionId) {
+    const requested = sessionId ?? (this.defaultSession === "latest" ? void 0 : this.defaultSession);
+    if (requested) {
+      const s = this.db.getSession(requested);
+      if (s && s.tenant === ctx.tenant) return s.id;
+      throw new NotFoundError(`session not found`);
+    }
+    const latest = this.db.getLatestSession("discover", ctx.tenant) ?? this.db.getLatestSession(void 0, ctx.tenant);
+    if (!latest) throw new NotFoundError(`no session available`);
+    return latest.id;
+  }
+  summary(ctx, sessionId) {
+    return this.db.getGraphSummary(this.resolveSession(ctx, sessionId));
+  }
+  nodes(ctx, q, sessionId) {
+    const sid = this.resolveSession(ctx, sessionId);
+    const limit = clamp(q.limit ?? 100, 1, MAX_NODE_LIMIT);
+    const offset = Math.floor(Math.max(0, q.offset ?? 0));
+    const total = this.db.getNodeCount(sid);
+    if (q.search) {
+      const nodes2 = this.db.searchNodes(sid, q.search, { ...q.types ? { types: q.types } : {}, limit });
+      return { nodes: nodes2, total: nodes2.length, limit, offset: 0 };
+    }
+    const nodes = this.db.getNodes(sid, { limit, offset });
+    return { nodes, total, limit, offset };
+  }
+  node(ctx, id, sessionId) {
+    return this.db.getNode(this.resolveSession(ctx, sessionId), id);
+  }
+  dependencies(ctx, id, q, sessionId) {
+    const sid = this.resolveSession(ctx, sessionId);
+    return this.db.getDependencies(sid, id, {
+      direction: q.direction ?? "downstream",
+      maxDepth: clamp(q.maxDepth ?? 8, 1, MAX_DEPTH)
+    });
+  }
+  diff(ctx, base, current) {
+    for (const id of [base, current]) {
+      const s = this.db.getSession(id);
+      if (!s || s.tenant !== ctx.tenant) throw new NotFoundError(`session not found`);
+    }
+    try {
+      return this.db.diffSessions(base, current);
+    } catch (err) {
+      throw new NotFoundError(err instanceof Error ? err.message : "diff failed");
+    }
+  }
+  sessions(ctx) {
+    return this.db.getSessions(ctx.tenant);
+  }
+  health(ctx) {
+    return { store: "sqlite", sessions: this.db.getSessions(ctx.tenant).length };
+  }
+};
+function createSqliteQueryBackend(db, defaultSession = "latest") {
+  return new SqliteQueryBackend(db, defaultSession);
+}
+
 // src/central/merge.ts
 function computeIdentity(org, node) {
   return {
@@ -5292,7 +5374,7 @@ async function resolveNlQuery(db, sessionId, search, raw, opts) {
 
 // src/mcp/server.ts
 var SERVER_NAME = "cartography";
-var SERVER_VERSION = "2.2.0";
+var SERVER_VERSION = "2.3.0";
 var SERVICE_TYPES = NODE_TYPE_GROUPS.web;
 var DATA_TYPES = NODE_TYPE_GROUPS.data;
 var lexicalSearch = async (db, sessionId, query, opts) => db.searchNodes(sessionId, query, { types: opts.types, limit: opts.limit }).map((node) => ({ node }));
@@ -5793,6 +5875,50 @@ import { randomUUID as randomUUID2 } from "crypto";
 import http from "http";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+
+// src/api/auth.ts
+var LOOPBACK_HOSTS2 = /* @__PURE__ */ new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+function isLoopbackHost(host2) {
+  return LOOPBACK_HOSTS2.has(host2);
+}
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+function bearerToken(header) {
+  if (!header) return void 0;
+  const trimmed = header.trim();
+  if (trimmed.length < 7 || trimmed.slice(0, 6).toLowerCase() !== "bearer") return void 0;
+  const rest = trimmed.slice(6);
+  if (!/^\s/.test(rest)) return void 0;
+  const token = rest.trimStart();
+  return token.length > 0 ? token : void 0;
+}
+function checkBearer(authorizationHeader, token) {
+  if (!token) return true;
+  const provided = bearerToken(authorizationHeader);
+  return provided !== void 0 && timingSafeEqual(provided, token);
+}
+function assertSafeBind(opts) {
+  if (isLoopbackHost(opts.host)) return;
+  if (opts.allowedHosts === void 0) {
+    throw new Error(
+      `Refusing to bind a non-loopback host (${opts.host}) without an explicit allowedHosts allowlist. Pass { allowedHosts: ['your.public.host:port'] } to opt in, or bind 127.0.0.1 for local-only use.`
+    );
+  }
+  if (!opts.token) {
+    throw new Error(
+      `Refusing to bind a non-loopback host (${opts.host}) without an auth token. Pass { token } (or --token / CARTOGRAPHY_HTTP_TOKEN) so requests must carry 'Authorization: Bearer <token>'.`
+    );
+  }
+}
+function defaultAllowedHosts(host2, port) {
+  return [`${host2}:${port}`, `localhost:${port}`, `127.0.0.1:${port}`];
+}
+
+// src/mcp/transports.ts
 async function runStdio(server) {
   const transport = new StdioServerTransport();
   await server.connect(transport);
@@ -5821,17 +5947,6 @@ async function readCappedBody(req, cap) {
     return { overflow: false, value: void 0 };
   }
 }
-function timingSafeEqual(a, b) {
-  if (a.length !== b.length) return false;
-  let diff = 0;
-  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
-  return diff === 0;
-}
-function bearerToken(header) {
-  if (!header) return void 0;
-  const m = /^Bearer\s+(.+)$/i.exec(header.trim());
-  return m ? m[1] : void 0;
-}
 async function readJsonBody(req) {
   const chunks = [];
   for await (const chunk of req) chunks.push(chunk);
@@ -5842,22 +5957,11 @@ async function readJsonBody(req) {
     return void 0;
   }
 }
-var LOOPBACK_HOSTS2 = /* @__PURE__ */ new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
 async function runHttp(factory, opts = {}) {
   const host2 = opts.host ?? "127.0.0.1";
   const port = opts.port ?? 3737;
-  const isLoopback = LOOPBACK_HOSTS2.has(host2);
-  if (!isLoopback && opts.allowedHosts === void 0) {
-    throw new Error(
-      `Refusing to bind a non-loopback host (${host2}) without an explicit allowedHosts allowlist. Pass { allowedHosts: ['your.public.host:port'] } to opt in, or bind 127.0.0.1 for local-only use.`
-    );
-  }
-  if (!isLoopback && !opts.token) {
-    throw new Error(
-      `Refusing to bind a non-loopback host (${host2}) without an auth token. Pass { token } (or --token / CARTOGRAPHY_HTTP_TOKEN) so requests must carry 'Authorization: Bearer <token>'.`
-    );
-  }
-  const allowedHosts = opts.allowedHosts ?? [`${host2}:${port}`, `localhost:${port}`, `127.0.0.1:${port}`];
+  assertSafeBind({ host: host2, port, ...opts.allowedHosts ? { allowedHosts: opts.allowedHosts } : {}, ...opts.token ? { token: opts.token } : {} });
+  const allowedHosts = opts.allowedHosts ?? defaultAllowedHosts(host2, port);
   const token = opts.token;
   const transports = /* @__PURE__ */ new Map();
   const httpServer = http.createServer(async (req, res) => {
@@ -5868,12 +5972,9 @@ async function runHttp(factory, opts = {}) {
         res.writeHead(404, { "content-type": "application/json" }).end('{"error":"not found"}');
         return;
       }
-      if (token) {
-        const provided = bearerToken(req.headers["authorization"]);
-        if (!provided || !timingSafeEqual(provided, token)) {
-          res.writeHead(401, { "content-type": "application/json", "www-authenticate": "Bearer" }).end('{"error":"unauthorized"}');
-          return;
-        }
+      if (!checkBearer(req.headers["authorization"], token)) {
+        res.writeHead(401, { "content-type": "application/json", "www-authenticate": "Bearer" }).end('{"error":"unauthorized"}');
+        return;
       }
       if (isIngest) {
         const hostHeader = (req.headers["host"] ?? "").toLowerCase();
@@ -5927,7 +6028,7 @@ async function runHttp(factory, opts = {}) {
       if (!res.headersSent) res.writeHead(500, { "content-type": "application/json" }).end('{"error":"internal error"}');
     }
   });
-  await new Promise((resolve2) => httpServer.listen(port, host2, resolve2));
+  await new Promise((resolve3) => httpServer.listen(port, host2, resolve3));
   return httpServer;
 }
 
@@ -6109,8 +6210,8 @@ async function createSemanticSearch(db, embedder, opts = {}) {
     return lexicalSearch2();
   }
   const store = new VectorStore(db, provider);
-  const ok = await store.init();
-  if (!ok) {
+  const ok3 = await store.init();
+  if (!ok3) {
     log2?.("semantic search: vector store unavailable (sqlite-vec not installed or failed to load) \u2014 using lexical search");
     return lexicalSearch2();
   }
@@ -6719,6 +6820,1037 @@ function localDiscoveryFn(registry, plugins) {
   };
 }
 
+// src/api/server.ts
+import http2 from "http";
+
+// src/api/tenant.ts
+var TENANT_HEADER = "x-cartograph-tenant";
+var InvalidTenantError = class extends Error {
+  constructor() {
+    super("invalid tenant");
+    this.name = "InvalidTenantError";
+  }
+};
+function resolveTenant(req, url, opts = {}) {
+  const headerName = (opts.header ?? TENANT_HEADER).toLowerCase();
+  const raw = headerValue(req, headerName) ?? url.searchParams.get("tenant") ?? void 0;
+  if (raw === void 0 || raw === "") {
+    return { tenant: opts.defaultTenant ?? DEFAULT_TENANT };
+  }
+  if (raw.trim().length > 128) {
+    throw new InvalidTenantError();
+  }
+  const normalized = normalizeTenant(raw);
+  if (normalized === DEFAULT_TENANT && raw.trim() !== DEFAULT_TENANT) {
+    throw new InvalidTenantError();
+  }
+  return { tenant: normalized };
+}
+function headerValue(req, name) {
+  const v = req.headers[name];
+  if (Array.isArray(v)) return v[0];
+  return v;
+}
+
+// src/api/schemas.ts
+import { z as z8 } from "zod";
+var DIRECTIONS = ["downstream", "upstream", "both"];
+var CostSchema = z8.object({
+  amount: z8.number(),
+  currency: z8.string(),
+  period: z8.enum(COST_PERIODS),
+  source: z8.string().optional()
+});
+var NodeSchema2 = z8.object({
+  id: z8.string(),
+  type: z8.string(),
+  name: z8.string(),
+  confidence: z8.number(),
+  domain: z8.string().optional(),
+  subDomain: z8.string().optional(),
+  qualityScore: z8.number().optional(),
+  owner: z8.string().optional(),
+  cost: CostSchema.optional(),
+  tags: z8.array(z8.string())
+});
+var EdgeSchema2 = z8.object({
+  sourceId: z8.string(),
+  targetId: z8.string(),
+  relationship: z8.string(),
+  confidence: z8.number(),
+  evidence: z8.string()
+});
+var AnomalySchema = z8.object({
+  nodeId: z8.string(),
+  kind: z8.enum(ANOMALY_KINDS),
+  severity: z8.enum(ANOMALY_SEVERITIES),
+  reason: z8.string()
+});
+var TopConnectedSchema = z8.object({
+  id: z8.string(),
+  name: z8.string(),
+  type: z8.string(),
+  degree: z8.number().int()
+});
+var CostByDomainSchema = z8.object({
+  domain: z8.string(),
+  currency: z8.string(),
+  period: z8.string(),
+  total: z8.number(),
+  nodes: z8.number().int()
+});
+var CostByOwnerSchema = z8.object({
+  owner: z8.string(),
+  currency: z8.string(),
+  period: z8.string(),
+  total: z8.number(),
+  nodes: z8.number().int()
+});
+var SummaryResponse = z8.object({
+  sessionId: z8.string(),
+  totals: z8.object({ nodes: z8.number().int(), edges: z8.number().int() }),
+  nodesByType: z8.record(z8.string(), z8.number().int()),
+  nodesByDomain: z8.record(z8.string(), z8.number().int()),
+  edgesByRelationship: z8.record(z8.string(), z8.number().int()),
+  topConnected: z8.array(TopConnectedSchema),
+  anomalies: z8.array(AnomalySchema),
+  contributors: z8.number().int(),
+  costByDomain: z8.array(CostByDomainSchema),
+  costByOwner: z8.array(CostByOwnerSchema),
+  costCoverage: z8.object({ withCost: z8.number().int(), total: z8.number().int() })
+});
+var NodesResponse = z8.object({
+  nodes: z8.array(NodeSchema2),
+  total: z8.number().int(),
+  limit: z8.number().int(),
+  offset: z8.number().int()
+});
+var DependencyNodeSchema = NodeSchema2.extend({ depth: z8.number().int() });
+var DependenciesResponse = z8.object({
+  root: NodeSchema2.optional(),
+  direction: z8.enum(DIRECTIONS),
+  maxDepth: z8.number().int(),
+  nodes: z8.array(DependencyNodeSchema),
+  edges: z8.array(EdgeSchema2)
+});
+var SessionEndpointSchema = z8.object({
+  sessionId: z8.string(),
+  startedAt: z8.string(),
+  nodeCount: z8.number().int(),
+  edgeCount: z8.number().int()
+});
+var NodeChangeSchema = z8.object({
+  id: z8.string(),
+  changedFields: z8.array(z8.string()),
+  confidenceDelta: z8.number()
+});
+var DiffResponse = z8.object({
+  base: SessionEndpointSchema,
+  current: SessionEndpointSchema,
+  summary: z8.object({
+    nodesAdded: z8.number().int(),
+    nodesRemoved: z8.number().int(),
+    nodesChanged: z8.number().int(),
+    edgesAdded: z8.number().int(),
+    edgesRemoved: z8.number().int()
+  }),
+  nodes: z8.object({
+    added: z8.array(NodeSchema2),
+    removed: z8.array(NodeSchema2),
+    changed: z8.array(NodeChangeSchema),
+    unchanged: z8.number().int()
+  }),
+  edges: z8.object({
+    added: z8.array(EdgeSchema2),
+    removed: z8.array(EdgeSchema2),
+    unchanged: z8.number().int()
+  }),
+  anomalies: z8.object({ added: z8.array(AnomalySchema) })
+});
+var SessionSchema = z8.object({
+  id: z8.string(),
+  mode: z8.literal("discover"),
+  startedAt: z8.string(),
+  completedAt: z8.string().optional(),
+  name: z8.string().optional(),
+  tenant: z8.string(),
+  lastScannedAt: z8.string().optional()
+});
+var SessionsResponse = z8.object({ sessions: z8.array(SessionSchema) });
+var HealthResponse = z8.object({
+  status: z8.literal("ok"),
+  version: z8.string(),
+  store: z8.literal("sqlite"),
+  sessions: z8.number().int()
+});
+var ErrorResponse = z8.object({
+  error: z8.string(),
+  code: z8.string().optional()
+});
+var API_SCHEMAS = {
+  Node: NodeSchema2,
+  Edge: EdgeSchema2,
+  Anomaly: AnomalySchema,
+  Summary: SummaryResponse,
+  Nodes: NodesResponse,
+  Dependencies: DependenciesResponse,
+  Diff: DiffResponse,
+  Session: SessionSchema,
+  Sessions: SessionsResponse,
+  Health: HealthResponse,
+  Error: ErrorResponse
+};
+
+// src/api/rest.ts
+function toApiNode(n) {
+  const out = { id: n.id, type: n.type, name: n.name, confidence: n.confidence, tags: n.tags };
+  if (n.domain !== void 0) out["domain"] = n.domain;
+  if (n.subDomain !== void 0) out["subDomain"] = n.subDomain;
+  if (n.qualityScore !== void 0) out["qualityScore"] = n.qualityScore;
+  if (n.owner !== void 0) out["owner"] = n.owner;
+  if (n.cost !== void 0) out["cost"] = n.cost;
+  return out;
+}
+function toApiEdge(e) {
+  return { sourceId: e.sourceId, targetId: e.targetId, relationship: e.relationship, confidence: e.confidence, evidence: e.evidence };
+}
+function toApiSession(s) {
+  const out = { id: s.id, mode: s.mode, startedAt: s.startedAt, tenant: s.tenant };
+  if (s.completedAt !== void 0) out["completedAt"] = s.completedAt;
+  if (s.name !== void 0) out["name"] = s.name;
+  if (s.lastScannedAt !== void 0) out["lastScannedAt"] = s.lastScannedAt;
+  return out;
+}
+function toApiAnomaly(a) {
+  return { nodeId: a.nodeId, kind: a.kind, severity: a.severity, reason: a.reason };
+}
+function projectDependencies(r) {
+  return {
+    ...r.root ? { root: toApiNode(r.root) } : {},
+    direction: r.direction,
+    maxDepth: r.maxDepth,
+    nodes: r.nodes.map((n) => ({ ...toApiNode(n), depth: n.depth })),
+    edges: r.edges.map(toApiEdge)
+  };
+}
+function projectDiff(diff) {
+  return {
+    base: { sessionId: diff.base.sessionId, startedAt: diff.base.startedAt, nodeCount: diff.base.nodeCount, edgeCount: diff.base.edgeCount },
+    current: { sessionId: diff.current.sessionId, startedAt: diff.current.startedAt, nodeCount: diff.current.nodeCount, edgeCount: diff.current.edgeCount },
+    summary: diff.summary,
+    nodes: {
+      added: diff.nodes.added.map(toApiNode),
+      removed: diff.nodes.removed.map(toApiNode),
+      changed: diff.nodes.changed.map((c) => ({ id: c.id, changedFields: c.changedFields, confidenceDelta: c.confidenceDelta })),
+      unchanged: diff.nodes.unchanged
+    },
+    edges: {
+      added: diff.edges.added.map(toApiEdge),
+      removed: diff.edges.removed.map(toApiEdge),
+      unchanged: diff.edges.unchanged
+    },
+    anomalies: { added: diff.anomalies.added.map(toApiAnomaly) }
+  };
+}
+function ok(body) {
+  return { status: 200, body };
+}
+function badRequest(error) {
+  return { status: 400, body: { error } };
+}
+function notFound(error = "not found") {
+  return { status: 404, body: { error } };
+}
+function guard(fn) {
+  try {
+    return fn();
+  } catch (err) {
+    if (err instanceof NotFoundError) return notFound(err.message);
+    throw err;
+  }
+}
+function validateOut(schema, body) {
+  if (process.env["NODE_ENV"] !== "production") {
+    const r = schema.safeParse(body);
+    if (!r.success) throw new Error(`API response failed its own schema contract: ${r.error.message}`);
+  }
+  return body;
+}
+function intParam(url, name) {
+  const raw = url.searchParams.get(name);
+  if (raw === null || raw.trim() === "") return void 0;
+  const n = Number(raw);
+  return Number.isInteger(n) ? n : void 0;
+}
+function sessionParam(url) {
+  return url.searchParams.get("session") ?? void 0;
+}
+function handleSummary(ctx, url, d) {
+  return guard(() => ok(validateOut(SummaryResponse, d.backend.summary(ctx, sessionParam(url)))));
+}
+function handleNodes(ctx, url, d) {
+  return guard(() => {
+    const search = url.searchParams.get("search") ?? void 0;
+    const typesRaw = url.searchParams.get("types");
+    const types = typesRaw ? typesRaw.split(",").map((s) => s.trim()).filter(Boolean) : void 0;
+    const limit = intParam(url, "limit");
+    const offset = intParam(url, "offset");
+    const r = d.backend.nodes(
+      ctx,
+      { ...search ? { search } : {}, ...types ? { types } : {}, ...limit !== void 0 ? { limit } : {}, ...offset !== void 0 ? { offset } : {} },
+      sessionParam(url)
+    );
+    return ok(validateOut(NodesResponse, { nodes: r.nodes.map(toApiNode), total: r.total, limit: r.limit, offset: r.offset }));
+  });
+}
+function handleDependencies(ctx, id, url, d) {
+  const directionRaw = url.searchParams.get("direction");
+  if (directionRaw !== null && !DIRECTIONS.includes(directionRaw)) {
+    return badRequest(`direction must be one of ${DIRECTIONS.join(", ")}`);
+  }
+  return guard(() => {
+    const direction = directionRaw ?? void 0;
+    const maxDepth = intParam(url, "maxDepth");
+    const r = d.backend.dependencies(
+      ctx,
+      id,
+      { ...direction ? { direction } : {}, ...maxDepth !== void 0 ? { maxDepth } : {} },
+      sessionParam(url)
+    );
+    return ok(validateOut(DependenciesResponse, projectDependencies(r)));
+  });
+}
+function handleDiff(ctx, url, d) {
+  const base = url.searchParams.get("base");
+  const current = url.searchParams.get("current");
+  if (!base || !current) return badRequest("both `base` and `current` query params are required");
+  return guard(() => {
+    const diff = d.backend.diff(ctx, base, current);
+    return ok(validateOut(DiffResponse, projectDiff(diff)));
+  });
+}
+function handleSessions(ctx, d) {
+  return guard(() => ok(validateOut(SessionsResponse, { sessions: d.backend.sessions(ctx).map(toApiSession) })));
+}
+function handleHealth(ctx, d) {
+  const h = d.backend.health(ctx);
+  return ok(validateOut(HealthResponse, { status: "ok", version: d.version, store: h.store, sessions: h.sessions }));
+}
+
+// src/api/openapi.ts
+function defOf(schema) {
+  return schema.def ?? {};
+}
+function unwrapOptional(schema) {
+  const def = defOf(schema);
+  if ((def.type === "optional" || def.type === "nullable") && def.innerType) {
+    return { inner: def.innerType, optional: true };
+  }
+  return { inner: schema, optional: false };
+}
+function zodToJsonSchema(schema) {
+  const def = defOf(schema);
+  switch (def.type) {
+    case "string":
+      return { type: "string" };
+    case "number": {
+      const isInt = (def.checks ?? []).some((c) => c._zod?.def?.check === "number_format");
+      return { type: isInt ? "integer" : "number" };
+    }
+    case "boolean":
+      return { type: "boolean" };
+    case "literal": {
+      const values = def.values ?? [];
+      return values.length === 1 ? { const: values[0] } : { enum: values };
+    }
+    case "enum":
+      return { type: "string", enum: Object.values(def.entries ?? {}) };
+    case "array":
+      return { type: "array", items: def.element ? zodToJsonSchema(def.element) : {} };
+    case "record":
+      return { type: "object", additionalProperties: def.valueType ? zodToJsonSchema(def.valueType) : true };
+    case "optional":
+    case "nullable":
+      return def.innerType ? zodToJsonSchema(def.innerType) : {};
+    case "object": {
+      const shape = def.shape ?? {};
+      const properties = {};
+      const required = [];
+      for (const key of Object.keys(shape)) {
+        const { inner, optional } = unwrapOptional(shape[key]);
+        properties[key] = zodToJsonSchema(inner);
+        if (!optional) required.push(key);
+      }
+      return { type: "object", properties, required, additionalProperties: false };
+    }
+    default:
+      throw new Error(`zodToJsonSchema: unsupported zod construct "${def.type ?? "unknown"}". Extend src/api/openapi.ts.`);
+  }
+}
+var TENANT_PARAM = {
+  name: "tenant",
+  in: "query",
+  required: false,
+  description: 'Tenant/org scope (also accepted via the X-Cartograph-Tenant header). Defaults to "local".',
+  schema: { type: "string" }
+};
+var SESSION_PARAM = {
+  name: "session",
+  in: "query",
+  required: false,
+  description: "Session id to query, or omit for the latest discovery session.",
+  schema: { type: "string" }
+};
+function errorResponses() {
+  const err = { description: "Error", content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } };
+  return { "400": { ...err, description: "Bad request" }, "401": { ...err, description: "Unauthorized" }, "404": { ...err, description: "Not found" } };
+}
+function ok2(ref, description) {
+  return { description, content: { "application/json": { schema: { $ref: `#/components/schemas/${ref}` } } } };
+}
+function buildOpenApiDocument(opts) {
+  const schemas = {};
+  for (const [name, schema] of Object.entries(API_SCHEMAS)) {
+    schemas[name] = zodToJsonSchema(schema);
+  }
+  return {
+    openapi: "3.1.0",
+    info: {
+      title: "Cartograph API",
+      version: opts.version,
+      description: "Read-only REST API over the discovered infrastructure/agentic-AI topology. Every endpoint is tenant-scoped and bearer-authenticated."
+    },
+    servers: [{ url: "/" }],
+    security: [{ bearerAuth: [] }],
+    components: {
+      securitySchemes: { bearerAuth: { type: "http", scheme: "bearer" } },
+      schemas
+    },
+    paths: {
+      "/v1/health": {
+        get: {
+          summary: "Liveness + store/coverage probe",
+          security: [],
+          responses: { "200": ok2("Health", "Service health") }
+        }
+      },
+      "/v1/openapi.json": {
+        get: {
+          summary: "This OpenAPI document",
+          security: [],
+          responses: { "200": { description: "OpenAPI 3.1 document", content: { "application/json": { schema: { type: "object" } } } } }
+        }
+      },
+      "/v1/summary": {
+        get: {
+          summary: "Low-token topology aggregate for the resolved session",
+          parameters: [SESSION_PARAM, TENANT_PARAM],
+          responses: { "200": ok2("Summary", "Topology summary"), ...errorResponses() }
+        }
+      },
+      "/v1/nodes": {
+        get: {
+          summary: "List/search/paginate nodes",
+          parameters: [
+            { name: "search", in: "query", required: false, description: "Lexical/semantic search anchor.", schema: { type: "string" } },
+            { name: "types", in: "query", required: false, description: "Comma-separated node-type filter.", schema: { type: "string" } },
+            { name: "limit", in: "query", required: false, description: "Page size (default 100, max 1000).", schema: { type: "integer" } },
+            { name: "offset", in: "query", required: false, description: "Page offset (ignored for search).", schema: { type: "integer" } },
+            SESSION_PARAM,
+            TENANT_PARAM
+          ],
+          responses: { "200": ok2("Nodes", "A page of nodes"), ...errorResponses() }
+        }
+      },
+      "/v1/nodes/{id}/dependencies": {
+        get: {
+          summary: "Dependency traversal from a node",
+          parameters: [
+            { name: "id", in: "path", required: true, description: 'Node id ("{type}:{id}").', schema: { type: "string" } },
+            { name: "direction", in: "query", required: false, description: "downstream | upstream | both (default downstream).", schema: { type: "string", enum: ["downstream", "upstream", "both"] } },
+            { name: "maxDepth", in: "query", required: false, description: "Traversal depth (default 8, max 64).", schema: { type: "integer" } },
+            SESSION_PARAM,
+            TENANT_PARAM
+          ],
+          responses: { "200": ok2("Dependencies", "Traversal result"), ...errorResponses() }
+        }
+      },
+      "/v1/diff": {
+        get: {
+          summary: "Compare two sessions (drift)",
+          parameters: [
+            { name: "base", in: "query", required: true, description: "Base session id.", schema: { type: "string" } },
+            { name: "current", in: "query", required: true, description: "Current session id.", schema: { type: "string" } },
+            TENANT_PARAM
+          ],
+          responses: { "200": ok2("Diff", "Topology delta"), ...errorResponses() }
+        }
+      },
+      "/v1/sessions": {
+        get: {
+          summary: "List discovery sessions for the tenant",
+          parameters: [TENANT_PARAM],
+          responses: { "200": ok2("Sessions", "Sessions"), ...errorResponses() }
+        }
+      }
+    }
+  };
+}
+
+// src/api/graphql.ts
+var SDL = `# Cartograph read-only GraphQL API (4.2). Mirrors the REST surface.
+schema { query: Query }
+
+type Query {
+  summary(session: String): Summary
+  nodes(search: String, types: [String!], limit: Int, offset: Int, session: String): NodeConnection
+  node(id: String!, session: String): Node
+  dependencies(id: String!, direction: Direction, maxDepth: Int, session: String): Dependencies
+  diff(base: String!, current: String!): Diff
+  sessions: [Session!]!
+}
+
+enum Direction { downstream upstream both }
+
+type Totals { nodes: Int! edges: Int! }
+type Count { key: String! value: Int! }
+type TopConnected { id: String! name: String! type: String! degree: Int! }
+type Anomaly { nodeId: String! kind: String! severity: String! reason: String! }
+type Cost { amount: Float! currency: String! period: String! source: String }
+type CostRollup { key: String! currency: String! period: String! total: Float! nodes: Int! }
+type CostCoverage { withCost: Int! total: Int! }
+
+type Node {
+  id: String! type: String! name: String! confidence: Float!
+  domain: String subDomain: String qualityScore: Float owner: String cost: Cost tags: [String!]!
+}
+type DependencyNode {
+  id: String! type: String! name: String! confidence: Float!
+  domain: String subDomain: String qualityScore: Float owner: String cost: Cost tags: [String!]! depth: Int!
+}
+type Edge { sourceId: String! targetId: String! relationship: String! confidence: Float! evidence: String! }
+
+type Summary {
+  sessionId: String!
+  totals: Totals!
+  topConnected: [TopConnected!]!
+  anomalies: [Anomaly!]!
+  contributors: Int!
+  costByDomain: [CostRollup!]!
+  costByOwner: [CostRollup!]!
+  costCoverage: CostCoverage!
+}
+
+type NodeConnection { nodes: [Node!]! total: Int! limit: Int! offset: Int! }
+type Dependencies { root: Node direction: Direction! maxDepth: Int! nodes: [DependencyNode!]! edges: [Edge!]! }
+
+type SessionEndpoint { sessionId: String! startedAt: String! nodeCount: Int! edgeCount: Int! }
+type DiffSummary { nodesAdded: Int! nodesRemoved: Int! nodesChanged: Int! edgesAdded: Int! edgesRemoved: Int! }
+type NodeChange { id: String! changedFields: [String!]! confidenceDelta: Float! }
+type DiffNodes { added: [Node!]! removed: [Node!]! changed: [NodeChange!]! unchanged: Int! }
+type DiffEdges { added: [Edge!]! removed: [Edge!]! unchanged: Int! }
+type DiffAnomalies { added: [Anomaly!]! }
+type Diff {
+  base: SessionEndpoint! current: SessionEndpoint! summary: DiffSummary!
+  nodes: DiffNodes! edges: DiffEdges! anomalies: DiffAnomalies!
+}
+
+type Session { id: String! mode: String! startedAt: String! completedAt: String name: String tenant: String! lastScannedAt: String }
+`;
+var resolvers = {
+  summary: (ctx, args, backend) => backend.summary(ctx, str(args["session"])),
+  nodes: (ctx, args, backend) => {
+    const r = backend.nodes(
+      ctx,
+      {
+        ...str(args["search"]) ? { search: str(args["search"]) } : {},
+        ...Array.isArray(args["types"]) ? { types: args["types"].map(String) } : {},
+        ...num(args["limit"]) !== void 0 ? { limit: num(args["limit"]) } : {},
+        ...num(args["offset"]) !== void 0 ? { offset: num(args["offset"]) } : {}
+      },
+      str(args["session"])
+    );
+    return { nodes: r.nodes.map(toApiNode), total: r.total, limit: r.limit, offset: r.offset };
+  },
+  node: (ctx, args, backend) => {
+    const n = backend.node(ctx, String(args["id"]), str(args["session"]));
+    return n ? toApiNode(n) : null;
+  },
+  dependencies: (ctx, args, backend) => {
+    const r = backend.dependencies(
+      ctx,
+      String(args["id"]),
+      {
+        ...str(args["direction"]) ? { direction: str(args["direction"]) } : {},
+        ...num(args["maxDepth"]) !== void 0 ? { maxDepth: num(args["maxDepth"]) } : {}
+      },
+      str(args["session"])
+    );
+    return projectDependencies(r);
+  },
+  diff: (ctx, args, backend) => projectDiff(backend.diff(ctx, String(args["base"]), String(args["current"]))),
+  sessions: (ctx, _args, backend) => backend.sessions(ctx).map(toApiSession)
+};
+function str(v) {
+  return typeof v === "string" ? v : void 0;
+}
+function num(v) {
+  return typeof v === "number" && Number.isInteger(v) ? v : void 0;
+}
+var NAME_RE = /[_A-Za-z][_0-9A-Za-z]*/y;
+function tokenize2(src) {
+  const tokens = [];
+  let i = 0;
+  while (i < src.length) {
+    const c = src[i];
+    if (/\s|,/.test(c)) {
+      i++;
+      continue;
+    }
+    if (c === "#") {
+      while (i < src.length && src[i] !== "\n") i++;
+      continue;
+    }
+    if ("{}()[]:!$".includes(c)) {
+      tokens.push(c);
+      i++;
+      continue;
+    }
+    if (c === '"') {
+      let j = i + 1;
+      let s = "";
+      while (j < src.length && src[j] !== '"') {
+        s += src[j];
+        j++;
+      }
+      tokens.push(JSON.stringify(s));
+      i = j + 1;
+      continue;
+    }
+    NAME_RE.lastIndex = i;
+    const m = NAME_RE.exec(src);
+    if (m && m.index === i) {
+      tokens.push(m[0]);
+      i = NAME_RE.lastIndex;
+      continue;
+    }
+    const numMatch = /-?\d+(\.\d+)?/y;
+    numMatch.lastIndex = i;
+    const nm = numMatch.exec(src);
+    if (nm && nm.index === i) {
+      tokens.push(nm[0]);
+      i = numMatch.lastIndex;
+      continue;
+    }
+    throw new Error(`unexpected character '${c}'`);
+  }
+  return tokens;
+}
+var MAX_SELECTION_DEPTH = 32;
+var Parser = class {
+  constructor(tokens, variables) {
+    this.tokens = tokens;
+    this.variables = variables;
+  }
+  pos = 0;
+  depth = 0;
+  peek() {
+    return this.tokens[this.pos];
+  }
+  next() {
+    return this.tokens[this.pos++];
+  }
+  expect(tok) {
+    if (this.tokens[this.pos] !== tok) throw new Error(`expected '${tok}', got '${this.tokens[this.pos] ?? "<eof>"}'`);
+    this.pos++;
+  }
+  parseDocument() {
+    if (this.peek() === "mutation" || this.peek() === "subscription") {
+      throw new Error("only query operations are supported (read-only API)");
+    }
+    if (this.peek() === "query") {
+      this.next();
+      if (this.peek() && this.peek() !== "{" && this.peek() !== "(") this.next();
+      if (this.peek() === "(") this.skipBalanced("(", ")");
+    }
+    this.expect("{");
+    const selections = this.parseSelectionSet();
+    return selections;
+  }
+  skipBalanced(open, close) {
+    this.expect(open);
+    let depth = 1;
+    while (depth > 0) {
+      const t = this.next();
+      if (t === void 0) throw new Error("unbalanced");
+      if (t === open) depth++;
+      else if (t === close) depth--;
+    }
+  }
+  parseSelectionSet() {
+    if (++this.depth > MAX_SELECTION_DEPTH) throw new Error(`selection set nested deeper than ${MAX_SELECTION_DEPTH}`);
+    const out = [];
+    while (this.peek() !== "}") {
+      if (this.peek() === void 0) throw new Error("unexpected end of selection set");
+      out.push(this.parseSelection());
+    }
+    this.expect("}");
+    this.depth--;
+    return out;
+  }
+  parseSelection() {
+    let name = this.next();
+    const alias = name;
+    if (this.peek() === ":") {
+      this.next();
+      name = this.next();
+    }
+    const args = {};
+    if (this.peek() === "(") {
+      this.next();
+      while (this.peek() !== ")") {
+        const argName = this.next();
+        this.expect(":");
+        args[argName] = this.parseValue();
+      }
+      this.expect(")");
+    }
+    let selections = [];
+    if (this.peek() === "{") {
+      this.next();
+      selections = this.parseSelectionSet();
+    }
+    return { name, alias, args, selections };
+  }
+  parseValue() {
+    const t = this.next();
+    if (t === "$") {
+      const v = this.next();
+      return this.variables[v];
+    }
+    if (t === "[") {
+      const arr = [];
+      while (this.peek() !== "]") arr.push(this.parseValue());
+      this.expect("]");
+      return arr;
+    }
+    if (t.startsWith('"')) return JSON.parse(t);
+    if (t === "true") return true;
+    if (t === "false") return false;
+    if (t === "null") return null;
+    if (/^-?\d+(\.\d+)?$/.test(t)) return Number(t);
+    return t;
+  }
+};
+function project(value, selections) {
+  if (value === null || value === void 0) return null;
+  if (selections.length === 0) return value;
+  if (Array.isArray(value)) return value.map((v) => project(v, selections));
+  if (typeof value !== "object") return value;
+  const obj = value;
+  const out = {};
+  for (const sel of selections) {
+    if (sel.name === "__typename") {
+      out[sel.alias] = void 0;
+      continue;
+    }
+    out[sel.alias] = project(obj[sel.name], sel.selections);
+  }
+  return out;
+}
+function introspectionSchema() {
+  const names = [...SDL.matchAll(/^(?:type|enum)\s+([_A-Za-z][_0-9A-Za-z]*)/gm)].map((m) => m[1]);
+  const types = names.map((name) => ({ name, kind: /^[A-Z]/.test(name) ? "OBJECT" : "SCALAR" }));
+  return {
+    __schema: {
+      queryType: { name: "Query" },
+      mutationType: null,
+      subscriptionType: null,
+      types,
+      directives: []
+    }
+  };
+}
+async function executeGraphql(ctx, body, deps) {
+  const req = body ?? {};
+  if (typeof req.query !== "string" || req.query.trim() === "") {
+    return { errors: [{ message: "missing query" }] };
+  }
+  const variables = typeof req.variables === "object" && req.variables !== null ? req.variables : {};
+  let selections;
+  try {
+    selections = new Parser(tokenize2(req.query), variables).parseDocument();
+  } catch (err) {
+    return { errors: [{ message: `syntax error: ${err instanceof Error ? err.message : String(err)}` }] };
+  }
+  const data = {};
+  const errors = [];
+  for (const sel of selections) {
+    try {
+      if (sel.name === "__schema") {
+        data[sel.alias] = project(introspectionSchema()["__schema"], sel.selections);
+        continue;
+      }
+      if (sel.name === "__typename") {
+        data[sel.alias] = "Query";
+        continue;
+      }
+      const resolver = resolvers[sel.name];
+      if (!resolver) {
+        errors.push({ message: `Cannot query field "${sel.name}" on type "Query"` });
+        continue;
+      }
+      const resolved = resolver(ctx, sel.args, deps.backend);
+      data[sel.alias] = project(resolved, sel.selections);
+    } catch (err) {
+      errors.push({ message: err instanceof Error ? err.message : String(err) });
+    }
+  }
+  return errors.length > 0 ? { data, errors } : { data };
+}
+function handleGraphqlGet() {
+  return { status: 200, body: SDL };
+}
+
+// src/api/server.ts
+var DEPENDENCIES_RE = /^\/v1\/nodes\/(.+)\/dependencies$/;
+var MAX_GRAPHQL_BYTES = 1024 * 1024;
+function send(res, status, body, headers = {}) {
+  res.writeHead(status, { "content-type": "application/json", ...headers }).end(JSON.stringify(body));
+}
+async function readBody(req, cap) {
+  const chunks = [];
+  let total = 0;
+  let overflow = false;
+  for await (const chunk of req) {
+    if (overflow) continue;
+    const buf = chunk;
+    total += buf.length;
+    if (total > cap) {
+      overflow = true;
+      chunks.length = 0;
+      continue;
+    }
+    chunks.push(buf);
+  }
+  if (overflow) return { overflow: true, value: void 0 };
+  if (chunks.length === 0) return { overflow: false, value: void 0 };
+  try {
+    return { overflow: false, value: JSON.parse(Buffer.concat(chunks).toString("utf8")) };
+  } catch {
+    return { overflow: false, value: void 0 };
+  }
+}
+async function runApi(opts) {
+  const host2 = opts.host ?? "127.0.0.1";
+  const requestedPort = opts.port ?? 3737;
+  const token = opts.token;
+  const graphqlEnabled = opts.graphql !== false;
+  const defaultTenant = opts.tenant?.defaultTenant ?? DEFAULT_TENANT;
+  const log2 = opts.log ?? (() => {
+  });
+  const restDeps = { backend: opts.backend, version: opts.version };
+  const openApiDoc = buildOpenApiDocument({ version: opts.version });
+  const allowedOrigins = opts.allowedOrigins ?? [];
+  assertSafeBind({ host: host2, port: requestedPort, ...opts.allowedHosts ? { allowedHosts: opts.allowedHosts } : {}, ...token ? { token } : {} });
+  let allowedHosts = opts.allowedHosts ?? [];
+  const corsHeaders = (req) => {
+    const origin = req.headers["origin"];
+    if (typeof origin === "string" && allowedOrigins.includes(origin)) {
+      return {
+        "access-control-allow-origin": origin,
+        "vary": "Origin",
+        "access-control-allow-methods": "GET, POST, OPTIONS",
+        "access-control-allow-headers": "authorization, content-type, x-cartograph-tenant"
+      };
+    }
+    return {};
+  };
+  const server = http2.createServer((req, res) => {
+    const started = Date.now();
+    let tenantLabel = "-";
+    const finish = (status) => {
+      log2(`[cartography-api] ${req.method ?? "-"} ${req.url ?? "-"} ${status} ${Date.now() - started}ms tenant=${tenantLabel}`);
+    };
+    void (async () => {
+      try {
+        const url = new URL(req.url ?? "/", `http://${req.headers["host"] ?? host2}`);
+        const path = url.pathname;
+        const cors = corsHeaders(req);
+        if (req.method === "OPTIONS") {
+          res.writeHead(204, cors).end();
+          finish(204);
+          return;
+        }
+        const hostHeader = (req.headers["host"] ?? "").toLowerCase();
+        if (!allowedHosts.some((h) => h.toLowerCase() === hostHeader)) {
+          send(res, 403, { error: "host not allowed" }, cors);
+          finish(403);
+          return;
+        }
+        if (path === "/v1/openapi.json" && req.method === "GET") {
+          send(res, 200, openApiDoc, cors);
+          finish(200);
+          return;
+        }
+        if (path === "/v1/health") {
+          if (req.method !== "GET") {
+            send(res, 405, { error: "method not allowed" }, { allow: "GET", ...cors });
+            finish(405);
+            return;
+          }
+          tenantLabel = defaultTenant;
+          const r = handleHealth({ tenant: defaultTenant }, restDeps);
+          send(res, r.status, r.body, cors);
+          finish(r.status);
+          return;
+        }
+        if (!checkBearer(req.headers["authorization"], token)) {
+          send(res, 401, { error: "unauthorized" }, { "www-authenticate": "Bearer", ...cors });
+          finish(401);
+          return;
+        }
+        let ctx;
+        try {
+          ctx = resolveTenant(req, url, opts.tenant ?? {});
+          tenantLabel = ctx.tenant;
+        } catch (err) {
+          if (err instanceof InvalidTenantError) {
+            send(res, 400, { error: "invalid tenant" }, cors);
+            finish(400);
+            return;
+          }
+          throw err;
+        }
+        if (graphqlEnabled && path === "/graphql") {
+          if (req.method === "GET") {
+            const g = handleGraphqlGet();
+            res.writeHead(g.status, { "content-type": "text/plain; charset=utf-8", ...cors }).end(g.body);
+            finish(g.status);
+            return;
+          }
+          if (req.method === "POST") {
+            const { overflow, value } = await readBody(req, MAX_GRAPHQL_BYTES);
+            if (overflow) {
+              send(res, 413, { error: "payload too large" }, cors);
+              finish(413);
+              return;
+            }
+            const result = await executeGraphql(ctx, value, { backend: opts.backend });
+            send(res, 200, result, cors);
+            finish(200);
+            return;
+          }
+          send(res, 405, { error: "method not allowed" }, { allow: "GET, POST", ...cors });
+          finish(405);
+          return;
+        }
+        if (path.startsWith("/v1/")) {
+          if (req.method !== "GET") {
+            send(res, 405, { error: "method not allowed" }, { allow: "GET", ...cors });
+            finish(405);
+            return;
+          }
+          const result = dispatchRest(ctx, path, url, restDeps);
+          if (result) {
+            send(res, result.status, result.body, cors);
+            finish(result.status);
+            return;
+          }
+        }
+        send(res, 404, { error: "not found" }, cors);
+        finish(404);
+      } catch (err) {
+        process.stderr.write(`[cartography-api] request failed: ${err instanceof Error ? err.message : String(err)}
+`);
+        if (!res.headersSent) send(res, 500, { error: "internal error" });
+        finish(500);
+      }
+    })();
+  });
+  await new Promise((resolve3) => server.listen(requestedPort, host2, resolve3));
+  const actualPort = server.address().port;
+  if (allowedHosts.length === 0) allowedHosts = defaultAllowedHosts(host2, actualPort);
+  return server;
+}
+function dispatchRest(ctx, path, url, deps) {
+  switch (path) {
+    case "/v1/summary":
+      return handleSummary(ctx, url, deps);
+    case "/v1/nodes":
+      return handleNodes(ctx, url, deps);
+    case "/v1/diff":
+      return handleDiff(ctx, url, deps);
+    case "/v1/sessions":
+      return handleSessions(ctx, deps);
+    default: {
+      const m = DEPENDENCIES_RE.exec(path);
+      if (m) return handleDependencies(ctx, decodeURIComponent(m[1]), url, deps);
+      return void 0;
+    }
+  }
+}
+
+// src/api/start.ts
+import { readFileSync as readFileSync4 } from "fs";
+import { dirname as dirname3, resolve } from "path";
+import { fileURLToPath } from "url";
+function readVersion() {
+  try {
+    const dir = import.meta.dirname ?? dirname3(fileURLToPath(import.meta.url));
+    return JSON.parse(readFileSync4(resolve(dir, "..", "package.json"), "utf-8")).version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+function parseApiArgs(argv) {
+  const opts = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--http") continue;
+    else if (a === "--no-graphql") opts.graphql = false;
+    else if (a === "--port") opts.port = Number(argv[++i]);
+    else if (a === "--host") opts.host = argv[++i];
+    else if (a === "--allowed-hosts") opts.allowedHosts = splitList(argv[++i]);
+    else if (a === "--allowed-origins") opts.allowedOrigins = splitList(argv[++i]);
+    else if (a === "--token") opts.token = argv[++i];
+    else if (a === "--db") opts.dbPath = argv[++i];
+    else if (a === "--session") opts.session = argv[++i];
+    else if (a === "--tenant" || a === "--org") opts.tenant = argv[++i];
+    else if (a === "--help" || a === "-h") opts.help = true;
+  }
+  return opts;
+}
+function splitList(raw) {
+  return (raw ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+}
+async function startApi(opts = {}) {
+  const log2 = opts.log ?? ((m) => process.stderr.write(m + "\n"));
+  const db = new CartographyDB(opts.dbPath ?? defaultConfig().dbPath);
+  const backend = createSqliteQueryBackend(db, opts.session ?? "latest");
+  const token = opts.token ?? process.env["CARTOGRAPHY_HTTP_TOKEN"];
+  const host2 = opts.host ?? "127.0.0.1";
+  const port = opts.port ?? 3737;
+  const version = readVersion();
+  const server = await runApi({
+    host: host2,
+    port,
+    backend,
+    version,
+    ...opts.allowedHosts ? { allowedHosts: opts.allowedHosts } : {},
+    ...opts.allowedOrigins ? { allowedOrigins: opts.allowedOrigins } : {},
+    ...token ? { token } : {},
+    ...opts.graphql === false ? { graphql: false } : {},
+    ...opts.tenant ? { tenant: { defaultTenant: normalizeTenant(opts.tenant) } } : {},
+    log: log2
+  });
+  const graphqlNote = opts.graphql === false ? " [REST only]" : " + /graphql";
+  log2(
+    `Cartograph API (REST${graphqlNote}) on http://${host2}:${port}/v1${token ? " (auth: bearer token required)" : ""} (tenant: ${normalizeTenant(opts.tenant)})`
+  );
+  return server;
+}
+
 // src/installer/format.ts
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
@@ -6791,8 +7923,8 @@ function defaultServerEntry(opts = {}) {
 }
 
 // src/installer/install.ts
-import { mkdirSync as mkdirSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync3, existsSync as existsSync4 } from "fs";
-import { dirname as dirname3 } from "path";
+import { mkdirSync as mkdirSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync3, existsSync as existsSync4 } from "fs";
+import { dirname as dirname4 } from "path";
 import { homedir as homedir3 } from "os";
 function currentOs() {
   if (process.platform === "win32") return "win";
@@ -6808,7 +7940,7 @@ function planInstall(spec, ctx, opts) {
     throw new Error(`${spec.label} does not support the "${ctx.scope}" scope.`);
   }
   const fileExists = existsSync4(path);
-  const before = fileExists ? readFileSync4(path, "utf8") : "";
+  const before = fileExists ? readFileSync5(path, "utf8") : "";
   const existing = parseConfig(before, spec.format);
   const merged = spec.apply(existing, opts.serverName ?? DEFAULT_SERVER_NAME, opts.entry);
   const after = serializeConfig(merged, spec.format);
@@ -6825,7 +7957,7 @@ function planInstall(spec, ctx, opts) {
   };
 }
 function applyInstall(plan) {
-  mkdirSync4(dirname3(plan.path), { recursive: true });
+  mkdirSync4(dirname4(plan.path), { recursive: true });
   writeFileSync3(plan.path, plan.after, "utf8");
 }
 function renderDiff(before, after) {
@@ -7199,13 +8331,13 @@ function createClaudeProvider() {
 }
 
 // src/providers/shell.ts
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 function createBashTool() {
   const shell = IS_WIN ? "powershell" : "posix";
   return {
     name: "Bash",
     description: "Run a read-only shell command (inspect ports, processes, config). Mutating or destructive commands are blocked by the read-only allowlist.",
-    inputShape: { command: z8.string().describe("The read-only shell command to run") },
+    inputShape: { command: z9.string().describe("The read-only shell command to run") },
     annotations: { readOnlyHint: true, openWorldHint: true },
     handler: async (args) => {
       const command = String(args["command"] ?? "").trim();
@@ -7674,8 +8806,8 @@ Use ask_user when you need context from the user.`;
 }
 
 // src/cost.ts
-import { readFileSync as readFileSync5 } from "fs";
-import { resolve } from "path";
+import { readFileSync as readFileSync6 } from "fs";
+import { resolve as resolve2 } from "path";
 function splitCsvLine(line) {
   const out = [];
   let cur = "";
@@ -7753,7 +8885,7 @@ var CsvCostSource = class {
   }
   id;
   async fetch() {
-    const text = readFileSync5(resolve(this.opts.filePath), "utf-8");
+    const text = readFileSync6(resolve2(this.opts.filePath), "utf-8");
     const records = parseCostCsv(text);
     const match = this.opts.match ?? "nodeId";
     const out = /* @__PURE__ */ new Map();
@@ -7784,11 +8916,11 @@ async function enrichCosts(db, sessionId, source) {
   let matched = 0;
   const unmatchedIds = [];
   for (const [nodeId, rec] of records) {
-    const ok = db.enrichNodeAttribution(sessionId, nodeId, {
+    const ok3 = db.enrichNodeAttribution(sessionId, nodeId, {
       owner: rec.owner ?? void 0,
       cost: rec.cost ?? void 0
     });
-    if (ok) matched++;
+    if (ok3) matched++;
     else unmatchedIds.push(nodeId);
   }
   return { source: source.id, total: records.size, matched, unmatched: unmatchedIds.length, unmatchedIds };
@@ -7895,10 +9027,10 @@ function assignColors(domains) {
   return result;
 }
 function shadeVariant(hex, amount) {
-  const num = parseInt(hex.replace("#", ""), 16);
-  const r = Math.min(255, (num >> 16) + amount);
-  const g = Math.min(255, (num >> 8 & 255) + amount);
-  const b = Math.min(255, (num & 255) + amount);
+  const num2 = parseInt(hex.replace("#", ""), 16);
+  const r = Math.min(255, (num2 >> 16) + amount);
+  const g = Math.min(255, (num2 >> 8 & 255) + amount);
+  const b = Math.min(255, (num2 & 255) + amount);
   return `#${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`;
 }
 function groupByDomain(assets) {
@@ -9541,7 +10673,7 @@ function formatComplianceText(report) {
 }
 
 // src/config.ts
-import { readFileSync as readFileSync6 } from "fs";
+import { readFileSync as readFileSync7 } from "fs";
 var ConfigError = class extends Error {
   constructor(message) {
     super(message);
@@ -9566,7 +10698,7 @@ function loadConfig(path) {
 function readConfigFile(path) {
   let raw;
   try {
-    raw = readFileSync6(path, "utf-8");
+    raw = readFileSync7(path, "utf-8");
   } catch (err) {
     throw new ConfigError(
       `Cannot read config file ${path}: ${err instanceof Error ? err.message : String(err)}`
@@ -9827,7 +10959,7 @@ async function pushDeltas(config, items, opts = {}) {
       sentHashes.push(...batch.map((b) => b.contentHash));
       continue;
     }
-    let ok = false;
+    let ok3 = false;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
       const controller = new AbortController();
       const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -9846,7 +10978,7 @@ async function pushDeltas(config, items, opts = {}) {
         const elapsed = Date.now() - startedAt;
         if (res.ok) {
           log2(`pushed ${batch.length} item(s) \u2192 ${safeUrl} [${res.status}] ${elapsed}ms (attempt ${attempt + 1})`);
-          ok = true;
+          ok3 = true;
           break;
         }
         if (res.status >= 400 && res.status < 500) {
@@ -9865,7 +10997,7 @@ async function pushDeltas(config, items, opts = {}) {
         await sleep(base + Math.floor(Math.random() * 100));
       }
     }
-    if (ok) {
+    if (ok3) {
       sent += batch.length;
       sentHashes.push(...batch.map((b) => b.contentHash));
     } else {
@@ -9924,14 +11056,14 @@ function runSyncClassify(db, sessionId, config, opts = {}) {
 
 // src/preflight.ts
 import { execSync as execSync2 } from "child_process";
-import { existsSync as existsSync5, readFileSync as readFileSync7 } from "fs";
+import { existsSync as existsSync5, readFileSync as readFileSync8 } from "fs";
 import { join as join6 } from "path";
 function isOAuthLoggedIn() {
   const home = process.env.HOME ?? process.env.USERPROFILE ?? "/tmp";
   const credFile = join6(home, ".claude", ".credentials.json");
   if (!existsSync5(credFile)) return false;
   try {
-    const creds = JSON.parse(readFileSync7(credFile, "utf8"));
+    const creds = JSON.parse(readFileSync8(credFile, "utf8"));
     const oauth = creds["claudeAiOauth"];
     return typeof oauth?.["accessToken"] === "string" && oauth["accessToken"].length > 0;
   } catch {
@@ -9997,7 +11129,10 @@ export {
   DriftConfigSchema,
   INGEST_SCHEMA_VERSION,
   IngestEnvelopeSchema,
+  InvalidTenantError,
+  LOOPBACK_HOSTS2 as LOOPBACK_HOSTS,
   MCP_BIN,
+  NotFoundError,
   PACKAGE_NAME,
   PERSONAL,
   PORT_MAP,
@@ -10008,26 +11143,33 @@ export {
   RuleCheckSchema,
   RulesetSchema,
   SCAN_ARG_PATTERNS,
+  SDL,
   SEVERITY_WEIGHT,
   SHARING_LEVELS,
   ScannerRegistry,
   ScannerShape,
   SharingLevelSchema,
+  SqliteQueryBackend,
   SqliteStoreBackend,
   StdoutSink,
+  TENANT_HEADER,
   VectorStore,
   WebhookSink,
   applyInstall,
   applySharingLevel,
   assertReadOnly,
+  assertSafeBind,
   assertSafeScanArg,
   assignColors,
+  bearerToken,
   bookmarksScanner,
   buildCartographyToolHandlers,
   buildMapData,
+  buildOpenApiDocument,
   buildReport,
   buildSinks,
   centralDbFromEnv,
+  checkBearer,
   checkPrerequisites,
   checkReadOnly,
   clampText,
@@ -10055,10 +11197,12 @@ export {
   createOpenAIProvider,
   createScanRunner,
   createSemanticSearch,
+  createSqliteQueryBackend,
   currentOs,
   cursorDeeplink,
   databasesScanner,
   deepMerge,
+  defaultAllowedHosts,
   defaultConfig,
   defaultContext,
   defaultProviderRegistry,
@@ -10075,6 +11219,7 @@ export {
   evaluateCheck,
   evaluateRule,
   evidenceLine,
+  executeGraphql,
   executeNlQuery,
   exportAll,
   exportBackstageYAML,
@@ -10095,6 +11240,7 @@ export {
   getRuleset,
   globalId,
   groupByDomain,
+  handleGraphqlGet,
   hexCorners,
   hexDistance,
   hexNeighbors,
@@ -10105,6 +11251,7 @@ export {
   hostname,
   ingestEnvelope,
   installedAppsScanner,
+  isLoopbackHost,
   isPersonalHost,
   isReadOnlyCommand,
   isRemembered,
@@ -10133,6 +11280,7 @@ export {
   normalizeTenant,
   orgKeyPath,
   osUser,
+  parseApiArgs,
   parseComposeDeps,
   parseConfig,
   parseConnectionString,
@@ -10158,10 +11306,12 @@ export {
   resolveEffectiveLevel,
   resolveNlQuery,
   resolveSharingLevel,
+  resolveTenant,
   revalidateAnonymized,
   reversalKey,
   reversePseudonym,
   rotateOrgKey,
+  runApi,
   runDiscovery,
   runDrift,
   runHttp,
@@ -10184,8 +11334,11 @@ export {
   shareHash,
   splitSegments,
   stableStringify,
+  startApi,
   stripSensitive,
+  timingSafeEqual,
   validateScanner,
-  vscodeDeeplink
+  vscodeDeeplink,
+  zodToJsonSchema
 };
 //# sourceMappingURL=index.js.map