@neat.is/core 0.3.8 → 0.4.2

package/dist/server.cjs

@@ -54,6 +54,7 @@ function mountBearerAuth(app, opts) {
   if (opts.trustProxy) return;
   const expected = Buffer.from(opts.token, "utf8");
   const suffixes = [...DEFAULT_UNAUTH_SUFFIXES, ...opts.extraUnauthenticatedSuffixes ?? []];
+  const publicRead = opts.publicRead === true;
   app.addHook("preHandler", (req, reply, done) => {
     const path38 = (req.url.split("?")[0] ?? "").replace(/\/+$/, "");
     for (const suffix of suffixes) {
@@ -62,6 +63,10 @@ function mountBearerAuth(app, opts) {
         return;
       }
     }
+    if (publicRead && PUBLIC_READ_METHODS.has(req.method)) {
+      done();
+      return;
+    }
     const header = req.headers.authorization;
     if (typeof header !== "string" || !header.startsWith("Bearer ")) {
       void reply.code(401).send({ error: "unauthorized" });
@@ -75,16 +80,21 @@ function mountBearerAuth(app, opts) {
     done();
   });
 }
+function parseBoolEnv(v) {
+  if (!v) return false;
+  return v === "true" || v === "1";
+}
 function readAuthEnv(env = process.env) {
   const t = env.NEAT_AUTH_TOKEN;
   const ot = env.NEAT_OTEL_TOKEN;
   return {
     authToken: t && t.length > 0 ? t : void 0,
     otelToken: ot && ot.length > 0 ? ot : t && t.length > 0 ? t : void 0,
-    trustProxy: env.NEAT_AUTH_PROXY === "true"
+    trustProxy: env.NEAT_AUTH_PROXY === "true",
+    publicRead: parseBoolEnv(env.NEAT_PUBLIC_READ)
   };
 }
-var import_node_crypto, LOOPBACK_HOSTS, BindAuthorityError, DEFAULT_UNAUTH_SUFFIXES;
+var import_node_crypto, LOOPBACK_HOSTS, BindAuthorityError, PUBLIC_READ_METHODS, DEFAULT_UNAUTH_SUFFIXES;
 var init_auth = __esm({
   "src/auth.ts"() {
     "use strict";
@@ -104,7 +114,13 @@ var init_auth = __esm({
         this.name = "BindAuthorityError";
       }
     };
-    DEFAULT_UNAUTH_SUFFIXES = ["/health", "/healthz", "/readyz"];
+    PUBLIC_READ_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "OPTIONS"]);
+    DEFAULT_UNAUTH_SUFFIXES = [
+      "/health",
+      "/healthz",
+      "/readyz",
+      "/api/config"
+    ];
   }
 });
 
@@ -307,6 +323,15 @@ function isoFromUnixNano(nanos) {
     return void 0;
   }
 }
+function pickEnv(spanAttrs, resourceAttrs) {
+  for (const attrs of [spanAttrs, resourceAttrs]) {
+    for (const key of [ENV_ATTR_CANONICAL, ENV_ATTR_COMPAT]) {
+      const v = attrs[key];
+      if (typeof v === "string" && v.length > 0) return v;
+    }
+  }
+  return ENV_FALLBACK;
+}
 function parseOtlpRequest(body) {
   const out = [];
   for (const rs of body.resourceSpans ?? []) {
@@ -326,6 +351,7 @@ function parseOtlpRequest(body) {
           endTimeUnixNano: span.endTimeUnixNano ?? "0",
           startTimeIso: isoFromUnixNano(span.startTimeUnixNano),
           durationNanos: durationNanos(span.startTimeUnixNano, span.endTimeUnixNano),
+          env: pickEnv(attrs, resourceAttrs),
           attributes: attrs,
           dbSystem: typeof attrs["db.system"] === "string" ? attrs["db.system"] : void 0,
           dbName: typeof attrs["db.name"] === "string" ? attrs["db.name"] : void 0,
@@ -464,7 +490,7 @@ async function buildOtelReceiver(opts) {
   };
   return decorated;
 }
-var import_node_path35, import_node_url2, import_fastify2, import_protobufjs, exportTraceServiceRequestType, exportTraceServiceResponseType, cachedProtobufResponseBody;
+var import_node_path35, import_node_url2, import_fastify2, import_protobufjs, ENV_ATTR_CANONICAL, ENV_ATTR_COMPAT, ENV_FALLBACK, exportTraceServiceRequestType, exportTraceServiceResponseType, cachedProtobufResponseBody;
 var init_otel = __esm({
   "src/otel.ts"() {
     "use strict";
@@ -474,6 +500,9 @@ var init_otel = __esm({
     import_fastify2 = __toESM(require("fastify"), 1);
     import_protobufjs = __toESM(require("protobufjs"), 1);
     init_auth();
+    ENV_ATTR_CANONICAL = "deployment.environment.name";
+    ENV_ATTR_COMPAT = "deployment.environment";
+    ENV_FALLBACK = "unknown";
     exportTraceServiceRequestType = null;
     exportTraceServiceResponseType = null;
     cachedProtobufResponseBody = null;
@@ -506,7 +535,7 @@ function getGraph(project = DEFAULT_PROJECT) {
 init_cjs_shims();
 var import_fastify = __toESM(require("fastify"), 1);
 var import_cors = __toESM(require("@fastify/cors"), 1);
-var import_types21 = require("@neat.is/types");
+var import_types22 = require("@neat.is/types");
 
 // src/divergences.ts
 init_cjs_shims();
@@ -1763,52 +1792,64 @@ function cacheSpanService(span, now) {
   if (!span.traceId || !span.spanId) return;
   const key = parentSpanKey(span.traceId, span.spanId);
   parentSpanCache.delete(key);
-  parentSpanCache.set(key, { service: span.service, expiresAt: now + PARENT_SPAN_CACHE_TTL_MS });
+  parentSpanCache.set(key, {
+    service: span.service,
+    env: span.env ?? "unknown",
+    expiresAt: now + PARENT_SPAN_CACHE_TTL_MS
+  });
   while (parentSpanCache.size > PARENT_SPAN_CACHE_SIZE) {
     const oldest = parentSpanCache.keys().next().value;
     if (!oldest) break;
     parentSpanCache.delete(oldest);
   }
 }
-function lookupParentSpanService(traceId, parentSpanId, now) {
+function lookupParentSpan(traceId, parentSpanId, now) {
   const entry = parentSpanCache.get(parentSpanKey(traceId, parentSpanId));
   if (!entry) return null;
   if (entry.expiresAt <= now) {
     parentSpanCache.delete(parentSpanKey(traceId, parentSpanId));
     return null;
   }
-  return entry.service;
+  return { service: entry.service, env: entry.env };
 }
-function resolveServiceId(graph, host) {
-  const direct = (0, import_types4.serviceId)(host);
-  if (graph.hasNode(direct)) return direct;
-  let found = null;
+function resolveServiceId(graph, host, env) {
+  const envTagged = (0, import_types4.serviceId)(host, env);
+  if (graph.hasNode(envTagged)) return envTagged;
+  const envLess = (0, import_types4.serviceId)(host);
+  if (envLess !== envTagged && graph.hasNode(envLess)) return envLess;
+  let sameEnv = null;
+  let envLessMatch = null;
+  let anyMatch = null;
   graph.forEachNode((id, attrs) => {
-    if (found) return;
+    if (sameEnv) return;
     const a = attrs;
     if (a.type !== import_types4.NodeType.ServiceNode) return;
-    if (a.name === host) {
-      found = id;
+    const matchesByName = a.name === host;
+    const matchesByAlias = a.aliases ? a.aliases.includes(host) : false;
+    if (!matchesByName && !matchesByAlias) return;
+    const nodeEnv = a.env ?? "unknown";
+    if (nodeEnv === env) {
+      sameEnv = id;
       return;
     }
-    if (a.aliases && a.aliases.includes(host)) {
-      found = id;
-    }
+    if (nodeEnv === "unknown" && !envLessMatch) envLessMatch = id;
+    else if (!anyMatch) anyMatch = id;
   });
-  return found;
+  return sameEnv ?? envLessMatch ?? anyMatch;
 }
 function frontierIdFor(host) {
   return (0, import_types4.frontierId)(host);
 }
-function ensureServiceNode(graph, serviceName) {
-  const id = (0, import_types4.serviceId)(serviceName);
+function ensureServiceNode(graph, serviceName, env) {
+  const id = (0, import_types4.serviceId)(serviceName, env);
   if (graph.hasNode(id)) return id;
   const node = {
     id,
     type: import_types4.NodeType.ServiceNode,
     name: serviceName,
     language: "unknown",
-    discoveredVia: "otel"
+    discoveredVia: "otel",
+    ...env !== "unknown" ? { env } : {}
   };
   graph.addNode(id, node);
   return id;
@@ -1943,7 +1984,8 @@ function sanitizeAttributes(attrs) {
 async function handleSpan(ctx, span) {
   const ts = span.startTimeIso ?? nowIso(ctx);
   const nowMs = ctx.now ? ctx.now() : Date.now();
-  const sourceId = ensureServiceNode(ctx.graph, span.service);
+  const env = span.env ?? "unknown";
+  const sourceId = ensureServiceNode(ctx.graph, span.service, env);
   const isError = span.statusCode === 2;
   cacheSpanService(span, nowMs);
   let affectedNode = sourceId;
@@ -1966,7 +2008,7 @@ async function handleSpan(ctx, span) {
     const host = pickAddress(span);
     let resolvedViaAddress = false;
     if (host && host !== span.service) {
-      const targetId = resolveServiceId(ctx.graph, host);
+      const targetId = resolveServiceId(ctx.graph, host, env);
       if (targetId && targetId !== sourceId) {
         upsertObservedEdge(
           ctx.graph,
@@ -1993,9 +2035,9 @@ async function handleSpan(ctx, span) {
       }
     }
     if (!resolvedViaAddress && span.parentSpanId) {
-      const parentService = lookupParentSpanService(span.traceId, span.parentSpanId, nowMs);
-      if (parentService && parentService !== span.service) {
-        const parentId = ensureServiceNode(ctx.graph, parentService);
+      const parent = lookupParentSpan(span.traceId, span.parentSpanId, nowMs);
+      if (parent && parent.service !== span.service) {
+        const parentId = ensureServiceNode(ctx.graph, parent.service, parent.env);
         upsertObservedEdge(
           ctx.graph,
           import_types4.EdgeType.CALLS,
@@ -2191,6 +2233,28 @@ async function readErrorEvents(errorsPath) {
     throw err;
   }
 }
+function mergeSnapshot(graph, snapshot) {
+  const exported = snapshot.graph;
+  let nodesAdded = 0;
+  let edgesAdded = 0;
+  for (const node of exported.nodes ?? []) {
+    if (graph.hasNode(node.key)) continue;
+    if (!node.attributes) continue;
+    graph.addNode(node.key, node.attributes);
+    nodesAdded++;
+  }
+  for (const edge of exported.edges ?? []) {
+    const attrs = edge.attributes;
+    if (!attrs) continue;
+    const id = edge.key ?? attrs.id;
+    if (!id) continue;
+    if (graph.hasEdge(id)) continue;
+    if (!graph.hasNode(edge.source) || !graph.hasNode(edge.target)) continue;
+    graph.addEdgeWithKey(id, edge.source, edge.target, attrs);
+    edgesAdded++;
+  }
+  return { nodesAdded, edgesAdded };
+}
 
 // src/extract/services.ts
 init_cjs_shims();
@@ -2214,8 +2278,36 @@ var IGNORED_DIRS = /* @__PURE__ */ new Set([
   ".turbo",
   "dist",
   "build",
-  ".next"
+  ".next",
+  // Python virtualenv shapes (issue #344). Walking into a venv pulls in the
+  // entire CPython stdlib + every installed package as if it were first-party
+  // service code — 20k+ files, none of which the user wrote. The shape names
+  // cover the three common venv tools (`venv` / `python -m venv`,
+  // `virtualenv`) and the tox + PEP 582 conventions.
+  ".venv",
+  "venv",
+  "__pypackages__",
+  ".tox",
+  // `site-packages` shows up nested inside venvs that don't carry one of the
+  // outer names (system Python on macOS, in-place pyenv layouts). Listing it
+  // here means we stop the walk at the boundary even when the wrapper dir
+  // wasn't recognisable.
+  "site-packages"
 ]);
+var PYVENV_MARKER_CACHE = /* @__PURE__ */ new Map();
+async function isPythonVenvDir(dir) {
+  const cached = PYVENV_MARKER_CACHE.get(dir);
+  if (cached !== void 0) return cached;
+  try {
+    const stat = await import_node_fs4.promises.stat(import_node_path4.default.join(dir, "pyvenv.cfg"));
+    const ok = stat.isFile();
+    PYVENV_MARKER_CACHE.set(dir, ok);
+    return ok;
+  } catch {
+    PYVENV_MARKER_CACHE.set(dir, false);
+    return false;
+  }
+}
 function isConfigFile(name) {
   const ext = import_node_path4.default.extname(name);
   if (CONFIG_FILE_EXTENSIONS.has(ext)) return { match: true, fileType: ext.slice(1) };
@@ -2552,6 +2644,7 @@ async function walkDirs(start, scanPath, options, visit) {
         const rel = import_node_path8.default.relative(scanPath, child).split(import_node_path8.default.sep).join("/");
         if (rel && options.ig.ignores(rel + "/")) continue;
       }
+      if (await isPythonVenvDir(child)) continue;
       await visit(child);
       await recurse(child, depth + 1);
     }
@@ -2587,6 +2680,18 @@ async function expandWorkspaceGlobs(scanPath, globs) {
   }
   return [...found];
 }
+function detectJsFramework(pkg) {
+  const deps = { ...pkg.dependencies ?? {}, ...pkg.devDependencies ?? {} };
+  if (deps["next"] !== void 0) return "next";
+  if (deps["remix"] !== void 0) return "remix";
+  for (const k of Object.keys(deps)) {
+    if (k.startsWith("@remix-run/")) return "remix";
+  }
+  if (deps["@sveltejs/kit"] !== void 0) return "sveltekit";
+  if (deps["nuxt"] !== void 0) return "nuxt";
+  if (deps["astro"] !== void 0) return "astro";
+  return void 0;
+}
 async function discoverNodeService(scanPath, dir) {
   const pkgPath = import_node_path8.default.join(dir, "package.json");
   if (!await exists(pkgPath)) return null;
@@ -2598,6 +2703,7 @@ async function discoverNodeService(scanPath, dir) {
     return null;
   }
   if (!pkg.name) return null;
+  const framework = detectJsFramework(pkg);
   const node = {
     id: (0, import_types6.serviceId)(pkg.name),
     type: import_types6.NodeType.ServiceNode,
@@ -2606,7 +2712,8 @@ async function discoverNodeService(scanPath, dir) {
     version: pkg.version,
     dependencies: pkg.dependencies ?? {},
     repoPath: import_node_path8.default.relative(scanPath, dir),
-    ...pkg.engines?.node ? { nodeEngine: pkg.engines.node } : {}
+    ...pkg.engines?.node ? { nodeEngine: pkg.engines.node } : {},
+    ...framework ? { framework } : {}
   };
   return { pkg, dir, node };
 }
@@ -2816,7 +2923,9 @@ async function walkYamlFiles(start, depth = 0, max = 5) {
   for (const entry of entries) {
     if (entry.isDirectory()) {
       if (IGNORED_DIRS.has(entry.name)) continue;
-      out.push(...await walkYamlFiles(import_node_path9.default.join(start, entry.name), depth + 1, max));
+      const child = import_node_path9.default.join(start, entry.name);
+      if (await isPythonVenvDir(child)) continue;
+      out.push(...await walkYamlFiles(child, depth + 1, max));
     } else if (entry.isFile() && CONFIG_FILE_EXTENSIONS.has(import_node_path9.default.extname(entry.name))) {
       out.push(import_node_path9.default.join(start, entry.name));
     }
@@ -3498,7 +3607,9 @@ async function walkConfigFiles(dir) {
     for (const entry of entries) {
       const full = import_node_path18.default.join(current, entry.name);
       if (entry.isDirectory()) {
-        if (!IGNORED_DIRS.has(entry.name)) await walk(full);
+        if (IGNORED_DIRS.has(entry.name)) continue;
+        if (await isPythonVenvDir(full)) continue;
+        await walk(full);
       } else if (entry.isFile() && isConfigFile(entry.name).match) {
         out.push(full);
       }
@@ -3566,7 +3677,9 @@ async function walkSourceFiles(dir) {
     for (const entry of entries) {
       const full = import_node_path19.default.join(current, entry.name);
       if (entry.isDirectory()) {
-        if (!IGNORED_DIRS.has(entry.name)) await walk(full);
+        if (IGNORED_DIRS.has(entry.name)) continue;
+        if (await isPythonVenvDir(full)) continue;
+        await walk(full);
       } else if (entry.isFile() && SERVICE_FILE_EXTENSIONS.has(import_node_path19.default.extname(entry.name))) {
         out.push(full);
       }
@@ -4202,7 +4315,9 @@ async function walkTfFiles(start, depth = 0, max = 5) {
   for (const entry of entries) {
     if (entry.isDirectory()) {
       if (IGNORED_DIRS.has(entry.name) || entry.name === ".terraform") continue;
-      out.push(...await walkTfFiles(import_node_path27.default.join(start, entry.name), depth + 1, max));
+      const child = import_node_path27.default.join(start, entry.name);
+      if (await isPythonVenvDir(child)) continue;
+      out.push(...await walkTfFiles(child, depth + 1, max));
     } else if (entry.isFile() && entry.name.endsWith(".tf")) {
       out.push(import_node_path27.default.join(start, entry.name));
     }
@@ -4250,7 +4365,9 @@ async function walkYamlFiles2(start, depth = 0, max = 5) {
   for (const entry of entries) {
     if (entry.isDirectory()) {
       if (IGNORED_DIRS.has(entry.name)) continue;
-      out.push(...await walkYamlFiles2(import_node_path28.default.join(start, entry.name), depth + 1, max));
+      const child = import_node_path28.default.join(start, entry.name);
+      if (await isPythonVenvDir(child)) continue;
+      out.push(...await walkYamlFiles2(child, depth + 1, max));
     } else if (entry.isFile() && CONFIG_FILE_EXTENSIONS.has(import_node_path28.default.extname(entry.name))) {
       out.push(import_node_path28.default.join(start, entry.name));
     }
@@ -4461,25 +4578,138 @@ function canonicalJson(value) {
   });
 }
 
-// src/projects.ts
+// src/persist.ts
 init_cjs_shims();
+var import_node_fs19 = require("fs");
 var import_node_path31 = __toESM(require("path"), 1);
+var import_types20 = require("@neat.is/types");
+var SCHEMA_VERSION = 4;
+function migrateV1ToV2(payload) {
+  const nodes = payload.graph.nodes;
+  if (Array.isArray(nodes)) {
+    for (const node of nodes) {
+      if (node.attributes && "pgDriverVersion" in node.attributes) {
+        delete node.attributes.pgDriverVersion;
+      }
+    }
+  }
+  return { ...payload, schemaVersion: 2 };
+}
+function migrateV3ToV4(payload) {
+  return { ...payload, schemaVersion: 4 };
+}
+function migrateV2ToV3(payload) {
+  const edges = payload.graph.edges;
+  if (Array.isArray(edges)) {
+    for (const edge of edges) {
+      const attrs = edge.attributes;
+      if (!attrs || attrs.provenance !== "FRONTIER") continue;
+      attrs.provenance = import_types20.Provenance.OBSERVED;
+      const type = typeof attrs.type === "string" ? attrs.type : void 0;
+      const source = typeof attrs.source === "string" ? attrs.source : void 0;
+      const target = typeof attrs.target === "string" ? attrs.target : void 0;
+      if (type && source && target) {
+        const newId = (0, import_types20.observedEdgeId)(source, target, type);
+        attrs.id = newId;
+        if (edge.key) edge.key = newId;
+      }
+    }
+  }
+  return { ...payload, schemaVersion: 3 };
+}
+async function ensureDir(filePath) {
+  await import_node_fs19.promises.mkdir(import_node_path31.default.dirname(filePath), { recursive: true });
+}
+async function saveGraphToDisk(graph, outPath) {
+  await ensureDir(outPath);
+  const payload = {
+    schemaVersion: SCHEMA_VERSION,
+    exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    graph: graph.export()
+  };
+  const tmp = `${outPath}.tmp`;
+  await import_node_fs19.promises.writeFile(tmp, JSON.stringify(payload), "utf8");
+  await import_node_fs19.promises.rename(tmp, outPath);
+}
+async function loadGraphFromDisk(graph, outPath) {
+  let raw;
+  try {
+    raw = await import_node_fs19.promises.readFile(outPath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return;
+    throw err;
+  }
+  let payload = JSON.parse(raw);
+  if (payload.schemaVersion === 1) {
+    payload = migrateV1ToV2(payload);
+  }
+  if (payload.schemaVersion === 2) {
+    payload = migrateV2ToV3(payload);
+  }
+  if (payload.schemaVersion === 3) {
+    payload = migrateV3ToV4(payload);
+  }
+  if (payload.schemaVersion !== SCHEMA_VERSION) {
+    throw new Error(
+      `persist: unsupported snapshot schemaVersion ${payload.schemaVersion} (expected ${SCHEMA_VERSION})`
+    );
+  }
+  graph.clear();
+  graph.import(payload.graph);
+}
+function startPersistLoop(graph, outPath, intervalMs = 6e4) {
+  let stopped = false;
+  const tick = async () => {
+    if (stopped) return;
+    try {
+      await saveGraphToDisk(graph, outPath);
+    } catch (err) {
+      console.error("persist: periodic save failed", err);
+    }
+  };
+  const interval = setInterval(() => {
+    void tick();
+  }, intervalMs);
+  const onSignal = (signal) => {
+    void (async () => {
+      try {
+        await saveGraphToDisk(graph, outPath);
+      } catch (err) {
+        console.error(`persist: ${signal} save failed`, err);
+      } finally {
+        process.exit(0);
+      }
+    })();
+  };
+  process.on("SIGTERM", onSignal);
+  process.on("SIGINT", onSignal);
+  return () => {
+    stopped = true;
+    clearInterval(interval);
+    process.off("SIGTERM", onSignal);
+    process.off("SIGINT", onSignal);
+  };
+}
+
+// src/projects.ts
+init_cjs_shims();
+var import_node_path32 = __toESM(require("path"), 1);
 function pathsForProject(project, baseDir) {
   if (project === DEFAULT_PROJECT) {
     return {
-      snapshotPath: import_node_path31.default.join(baseDir, "graph.json"),
-      errorsPath: import_node_path31.default.join(baseDir, "errors.ndjson"),
-      staleEventsPath: import_node_path31.default.join(baseDir, "stale-events.ndjson"),
-      embeddingsCachePath: import_node_path31.default.join(baseDir, "embeddings.json"),
-      policyViolationsPath: import_node_path31.default.join(baseDir, "policy-violations.ndjson")
+      snapshotPath: import_node_path32.default.join(baseDir, "graph.json"),
+      errorsPath: import_node_path32.default.join(baseDir, "errors.ndjson"),
+      staleEventsPath: import_node_path32.default.join(baseDir, "stale-events.ndjson"),
+      embeddingsCachePath: import_node_path32.default.join(baseDir, "embeddings.json"),
+      policyViolationsPath: import_node_path32.default.join(baseDir, "policy-violations.ndjson")
     };
   }
   return {
-    snapshotPath: import_node_path31.default.join(baseDir, `${project}.json`),
-    errorsPath: import_node_path31.default.join(baseDir, `errors.${project}.ndjson`),
-    staleEventsPath: import_node_path31.default.join(baseDir, `stale-events.${project}.ndjson`),
-    embeddingsCachePath: import_node_path31.default.join(baseDir, `embeddings.${project}.json`),
-    policyViolationsPath: import_node_path31.default.join(baseDir, `policy-violations.${project}.ndjson`)
+    snapshotPath: import_node_path32.default.join(baseDir, `${project}.json`),
+    errorsPath: import_node_path32.default.join(baseDir, `errors.${project}.ndjson`),
+    staleEventsPath: import_node_path32.default.join(baseDir, `stale-events.${project}.ndjson`),
+    embeddingsCachePath: import_node_path32.default.join(baseDir, `embeddings.${project}.json`),
+    policyViolationsPath: import_node_path32.default.join(baseDir, `policy-violations.${project}.ndjson`)
   };
 }
 var Projects = class {
@@ -4519,23 +4749,23 @@ function parseExtraProjects(raw) {
 
 // src/registry.ts
 init_cjs_shims();
-var import_node_fs19 = require("fs");
+var import_node_fs20 = require("fs");
 var import_node_os2 = __toESM(require("os"), 1);
-var import_node_path32 = __toESM(require("path"), 1);
-var import_types20 = require("@neat.is/types");
+var import_node_path33 = __toESM(require("path"), 1);
+var import_types21 = require("@neat.is/types");
 function neatHome() {
   const override = process.env.NEAT_HOME;
-  if (override && override.length > 0) return import_node_path32.default.resolve(override);
-  return import_node_path32.default.join(import_node_os2.default.homedir(), ".neat");
+  if (override && override.length > 0) return import_node_path33.default.resolve(override);
+  return import_node_path33.default.join(import_node_os2.default.homedir(), ".neat");
 }
 function registryPath() {
-  return import_node_path32.default.join(neatHome(), "projects.json");
+  return import_node_path33.default.join(neatHome(), "projects.json");
 }
 async function readRegistry() {
   const file = registryPath();
   let raw;
   try {
-    raw = await import_node_fs19.promises.readFile(file, "utf8");
+    raw = await import_node_fs20.promises.readFile(file, "utf8");
   } catch (err) {
     if (err.code === "ENOENT") {
       return { version: 1, projects: [] };
@@ -4543,7 +4773,7 @@ async function readRegistry() {
     throw err;
   }
   const parsed = JSON.parse(raw);
-  return import_types20.RegistryFileSchema.parse(parsed);
+  return import_types21.RegistryFileSchema.parse(parsed);
 }
 async function getProject(name) {
   const reg = await readRegistry();
@@ -4626,10 +4856,19 @@ function projectFromReq(req) {
   const params = req.params;
   return params.project ?? DEFAULT_PROJECT;
 }
-function resolveProject(registry, req, reply) {
+function resolveProject(registry, req, reply, bootstrap) {
   const name = projectFromReq(req);
   const ctx = registry.get(name);
   if (!ctx) {
+    const phase = bootstrap?.status(name);
+    if (phase === "bootstrapping") {
+      void reply.code(503).send({ ready: false, project: name, status: "bootstrapping" });
+      return null;
+    }
+    if (phase === "broken") {
+      void reply.code(503).send({ ready: false, project: name, status: "broken" });
+      return null;
+    }
     void reply.code(404).send({ error: "project not found", project: name });
     return null;
   }
@@ -4659,36 +4898,38 @@ function buildLegacyRegistry(opts) {
 function registerRoutes(scope, ctx) {
   const { registry, startedAt, errorsPathFor, staleEventsPathFor } = ctx;
   scope.get("/events", (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
     if (!proj) return;
     handleSse(req, reply, { project: proj.name });
   });
-  scope.get("/health", async (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
-    if (!proj) return;
-    const uptimeMs = Date.now() - startedAt;
-    return {
-      ok: true,
-      project: proj.name,
-      uptimeMs,
-      // Legacy fields kept additively. The web shell's StatusBar reads
-      // nodeCount / edgeCount; ADR-061's HealthResponseSchema validates
-      // the canonical triple and lets the extras pass through.
-      uptime: Math.floor(uptimeMs / 1e3),
-      nodeCount: proj.graph.order,
-      edgeCount: proj.graph.size,
-      lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
-    };
-  });
+  if (ctx.scope === "project") {
+    scope.get("/health", async (req, reply) => {
+      const proj = resolveProject(registry, req, reply, ctx.bootstrap);
+      if (!proj) return;
+      const uptimeMs = Date.now() - startedAt;
+      return {
+        ok: true,
+        project: proj.name,
+        uptimeMs,
+        // Legacy fields kept additively. The web shell's StatusBar reads
+        // nodeCount / edgeCount; ADR-061's HealthResponseSchema validates
+        // the canonical triple and lets the extras pass through.
+        uptime: Math.floor(uptimeMs / 1e3),
+        nodeCount: proj.graph.order,
+        edgeCount: proj.graph.size,
+        lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
+      };
+    });
+  }
   scope.get("/graph", async (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
     if (!proj) return;
     return serializeGraph(proj.graph);
   });
   scope.get(
     "/graph/node/:id",
     async (req, reply) => {
-      const proj = resolveProject(registry, req, reply);
+      const proj = resolveProject(registry, req, reply, ctx.bootstrap);
       if (!proj) return;
       const { id } = req.params;
       if (!proj.graph.hasNode(id)) {
@@ -4700,7 +4941,7 @@ function registerRoutes(scope, ctx) {
   scope.get(
     "/graph/edges/:id",
     async (req, reply) => {
-      const proj = resolveProject(registry, req, reply);
+      const proj = resolveProject(registry, req, reply, ctx.bootstrap);
       if (!proj) return;
       const { id } = req.params;
       if (!proj.graph.hasNode(id)) {
@@ -4712,7 +4953,7 @@ function registerRoutes(scope, ctx) {
     }
   );
   scope.get("/graph/dependencies/:nodeId", async (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
     if (!proj) return;
     const { nodeId } = req.params;
     if (!proj.graph.hasNode(nodeId)) {
@@ -4727,18 +4968,18 @@ function registerRoutes(scope, ctx) {
     return getTransitiveDependencies(proj.graph, nodeId, depth);
   });
   scope.get("/graph/divergences", async (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
     if (!proj) return;
     let typeFilter;
     if (req.query.type) {
       const candidates = req.query.type.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
       const parsed = [];
       for (const c of candidates) {
-        const r = import_types21.DivergenceTypeSchema.safeParse(c);
+        const r = import_types22.DivergenceTypeSchema.safeParse(c);
         if (!r.success) {
           return reply.code(400).send({
             error: `unknown divergence type "${c}"`,
-            allowed: import_types21.DivergenceTypeSchema.options
+            allowed: import_types22.DivergenceTypeSchema.options
           });
         }
         parsed.push(r.data);
@@ -4762,7 +5003,7 @@ function registerRoutes(scope, ctx) {
     });
   });
   scope.get("/incidents", async (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
     if (!proj) return;
     const epath = errorsPathFor(proj);
     if (!epath) return { count: 0, total: 0, events: [] };
@@ -4774,7 +5015,7 @@ function registerRoutes(scope, ctx) {
     return { count: sliced.length, total, events: sliced };
   });
   scope.get("/stale-events", async (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
     if (!proj) return;
     const spath = staleEventsPathFor(proj);
     if (!spath) return { count: 0, total: 0, events: [] };
@@ -4789,7 +5030,7 @@ function registerRoutes(scope, ctx) {
   scope.get(
     "/incidents/:nodeId",
     async (req, reply) => {
-      const proj = resolveProject(registry, req, reply);
+      const proj = resolveProject(registry, req, reply, ctx.bootstrap);
       if (!proj) return;
       const { nodeId } = req.params;
       if (!proj.graph.hasNode(nodeId)) {
@@ -4805,7 +5046,7 @@ function registerRoutes(scope, ctx) {
     }
   );
   scope.get("/graph/root-cause/:nodeId", async (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
     if (!proj) return;
     const { nodeId } = req.params;
     if (!proj.graph.hasNode(nodeId)) {
@@ -4825,7 +5066,7 @@ function registerRoutes(scope, ctx) {
     return result;
   });
   scope.get("/graph/blast-radius/:nodeId", async (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
     if (!proj) return;
     const { nodeId } = req.params;
     if (!proj.graph.hasNode(nodeId)) {
@@ -4838,7 +5079,7 @@ function registerRoutes(scope, ctx) {
     return getBlastRadius(proj.graph, nodeId, depth);
   });
   scope.get("/search", async (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
     if (!proj) return;
     const raw = (req.query.q ?? "").trim();
     if (!raw) return reply.code(400).send({ error: "query parameter `q` is required" });
@@ -4869,7 +5110,7 @@ function registerRoutes(scope, ctx) {
   scope.get(
     "/graph/diff",
     async (req, reply) => {
-      const proj = resolveProject(registry, req, reply);
+      const proj = resolveProject(registry, req, reply, ctx.bootstrap);
       if (!proj) return;
       const against = req.query.against;
       if (!against) {
@@ -4883,8 +5124,37 @@ function registerRoutes(scope, ctx) {
       }
     }
   );
+  scope.post("/snapshot", async (req, reply) => {
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
+    if (!proj) return;
+    const body = req.body;
+    if (!body || typeof body !== "object" || !body.snapshot) {
+      return reply.code(400).send({ error: "request body must be { snapshot: <persisted-graph> }" });
+    }
+    const snap = body.snapshot;
+    if (typeof snap.schemaVersion !== "number" || snap.schemaVersion !== SCHEMA_VERSION) {
+      return reply.code(400).send({
+        error: `unsupported snapshot schemaVersion ${snap.schemaVersion} (expected ${SCHEMA_VERSION})`
+      });
+    }
+    try {
+      const result = mergeSnapshot(proj.graph, snap);
+      return {
+        project: proj.name,
+        nodesAdded: result.nodesAdded,
+        edgesAdded: result.edgesAdded,
+        nodeCount: proj.graph.order,
+        edgeCount: proj.graph.size
+      };
+    } catch (err) {
+      return reply.code(400).send({
+        error: "snapshot merge failed",
+        details: err.message
+      });
+    }
+  });
   scope.post("/graph/scan", async (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
     if (!proj) return;
     if (!proj.scanPath) {
       return reply.code(409).send({ error: "scan path not configured for this project", project: proj.name });
@@ -4900,7 +5170,7 @@ function registerRoutes(scope, ctx) {
     };
   });
   scope.get("/policies", async (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
     if (!proj) return;
     const policyPath = ctx.policyFilePathFor(proj);
     if (!policyPath) {
@@ -4917,12 +5187,12 @@ function registerRoutes(scope, ctx) {
     }
   });
   scope.get("/policies/violations", async (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
     if (!proj) return;
     const log = new PolicyViolationsLog(proj.paths.policyViolationsPath);
     let violations = await log.readAll();
     if (req.query.severity) {
-      const sev = import_types21.PolicySeveritySchema.safeParse(req.query.severity);
+      const sev = import_types22.PolicySeveritySchema.safeParse(req.query.severity);
       if (!sev.success) {
         return reply.code(400).send({
           error: "invalid severity",
@@ -4937,9 +5207,9 @@ function registerRoutes(scope, ctx) {
     return { violations };
   });
   scope.post("/policies/check", async (req, reply) => {
-    const proj = resolveProject(registry, req, reply);
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap);
     if (!proj) return;
-    const parsed = import_types21.PoliciesCheckBodySchema.safeParse(req.body ?? {});
+    const parsed = import_types22.PoliciesCheckBodySchema.safeParse(req.body ?? {});
     if (!parsed.success) {
       return reply.code(400).send({
         error: "invalid /policies/check body",
@@ -4976,7 +5246,15 @@ function registerRoutes(scope, ctx) {
 async function buildApi(opts) {
   const app = (0, import_fastify.default)({ logger: false });
   await app.register(import_cors.default, { origin: true });
-  mountBearerAuth(app, { token: opts.authToken, trustProxy: opts.trustProxy });
+  mountBearerAuth(app, {
+    token: opts.authToken,
+    trustProxy: opts.trustProxy,
+    publicRead: opts.publicRead
+  });
+  app.get("/api/config", async () => ({
+    publicRead: opts.publicRead === true,
+    authProxy: opts.trustProxy === true
+  }));
   const startedAt = opts.startedAt ?? Date.now();
   const registry = buildLegacyRegistry(opts);
   const legacyErrorsExplicit = !opts.projects && opts.errorsPath !== void 0;
@@ -5000,10 +5278,36 @@ async function buildApi(opts) {
   const routeCtx = {
     registry,
     startedAt,
+    scope: "root",
     errorsPathFor,
     staleEventsPathFor,
-    policyFilePathFor
+    policyFilePathFor,
+    bootstrap: opts.bootstrap
   };
+  app.get("/health", async () => {
+    const uptimeMs = Date.now() - startedAt;
+    const bootstrapList = opts.bootstrap?.list() ?? [];
+    const byName = new Map(bootstrapList.map((p) => [p.name, p]));
+    const names = /* @__PURE__ */ new Set([
+      ...registry.list(),
+      ...bootstrapList.map((p) => p.name)
+    ]);
+    const projects = [...names].sort().map((name) => {
+      const proj = registry.get(name);
+      const tracked = byName.get(name);
+      return {
+        name,
+        nodeCount: proj?.graph.order ?? 0,
+        edgeCount: proj?.graph.size ?? 0,
+        ...tracked ? { status: tracked.status, elapsedMs: tracked.elapsedMs } : {}
+      };
+    });
+    return {
+      ok: true,
+      uptimeMs,
+      projects
+    };
+  });
   app.get("/projects", async (_req, reply) => {
     try {
       return await listProjects();
@@ -5031,120 +5335,13 @@ async function buildApi(opts) {
   registerRoutes(app, routeCtx);
   await app.register(
     async (scope) => {
-      registerRoutes(scope, routeCtx);
+      registerRoutes(scope, { ...routeCtx, scope: "project" });
     },
     { prefix: "/projects/:project" }
   );
   return app;
 }
 
-// src/persist.ts
-init_cjs_shims();
-var import_node_fs20 = require("fs");
-var import_node_path33 = __toESM(require("path"), 1);
-var import_types22 = require("@neat.is/types");
-var SCHEMA_VERSION = 3;
-function migrateV1ToV2(payload) {
-  const nodes = payload.graph.nodes;
-  if (Array.isArray(nodes)) {
-    for (const node of nodes) {
-      if (node.attributes && "pgDriverVersion" in node.attributes) {
-        delete node.attributes.pgDriverVersion;
-      }
-    }
-  }
-  return { ...payload, schemaVersion: 2 };
-}
-function migrateV2ToV3(payload) {
-  const edges = payload.graph.edges;
-  if (Array.isArray(edges)) {
-    for (const edge of edges) {
-      const attrs = edge.attributes;
-      if (!attrs || attrs.provenance !== "FRONTIER") continue;
-      attrs.provenance = import_types22.Provenance.OBSERVED;
-      const type = typeof attrs.type === "string" ? attrs.type : void 0;
-      const source = typeof attrs.source === "string" ? attrs.source : void 0;
-      const target = typeof attrs.target === "string" ? attrs.target : void 0;
-      if (type && source && target) {
-        const newId = (0, import_types22.observedEdgeId)(source, target, type);
-        attrs.id = newId;
-        if (edge.key) edge.key = newId;
-      }
-    }
-  }
-  return { ...payload, schemaVersion: 3 };
-}
-async function ensureDir(filePath) {
-  await import_node_fs20.promises.mkdir(import_node_path33.default.dirname(filePath), { recursive: true });
-}
-async function saveGraphToDisk(graph, outPath) {
-  await ensureDir(outPath);
-  const payload = {
-    schemaVersion: SCHEMA_VERSION,
-    exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    graph: graph.export()
-  };
-  const tmp = `${outPath}.tmp`;
-  await import_node_fs20.promises.writeFile(tmp, JSON.stringify(payload), "utf8");
-  await import_node_fs20.promises.rename(tmp, outPath);
-}
-async function loadGraphFromDisk(graph, outPath) {
-  let raw;
-  try {
-    raw = await import_node_fs20.promises.readFile(outPath, "utf8");
-  } catch (err) {
-    if (err.code === "ENOENT") return;
-    throw err;
-  }
-  let payload = JSON.parse(raw);
-  if (payload.schemaVersion === 1) {
-    payload = migrateV1ToV2(payload);
-  }
-  if (payload.schemaVersion === 2) {
-    payload = migrateV2ToV3(payload);
-  }
-  if (payload.schemaVersion !== SCHEMA_VERSION) {
-    throw new Error(
-      `persist: unsupported snapshot schemaVersion ${payload.schemaVersion} (expected ${SCHEMA_VERSION})`
-    );
-  }
-  graph.clear();
-  graph.import(payload.graph);
-}
-function startPersistLoop(graph, outPath, intervalMs = 6e4) {
-  let stopped = false;
-  const tick = async () => {
-    if (stopped) return;
-    try {
-      await saveGraphToDisk(graph, outPath);
-    } catch (err) {
-      console.error("persist: periodic save failed", err);
-    }
-  };
-  const interval = setInterval(() => {
-    void tick();
-  }, intervalMs);
-  const onSignal = (signal) => {
-    void (async () => {
-      try {
-        await saveGraphToDisk(graph, outPath);
-      } catch (err) {
-        console.error(`persist: ${signal} save failed`, err);
-      } finally {
-        process.exit(0);
-      }
-    })();
-  };
-  process.on("SIGTERM", onSignal);
-  process.on("SIGINT", onSignal);
-  return () => {
-    stopped = true;
-    clearInterval(interval);
-    process.off("SIGTERM", onSignal);
-    process.off("SIGINT", onSignal);
-  };
-}
-
 // src/server.ts
 init_otel();
 init_otel_grpc();
@@ -5489,7 +5686,8 @@ async function main() {
   const app = await buildApi({
     projects: registry,
     authToken: auth.authToken,
-    trustProxy: auth.trustProxy
+    trustProxy: auth.trustProxy,
+    publicRead: auth.publicRead
   });
   await app.listen({ port, host });
   console.log(`neat-core listening on http://${host}:${port}`);