@neat.is/core 0.4.9 → 0.4.11

package/dist/cli.cjs

@@ -639,6 +639,7 @@ init_cjs_shims();
 init_cjs_shims();
 var import_node_fs3 = require("fs");
 var import_node_path3 = __toESM(require("path"), 1);
+var sourceMapJs = __toESM(require("source-map-js"), 1);
 
 // src/policy.ts
 init_cjs_shims();
@@ -1693,6 +1694,14 @@ function warnUnidentifiedSpan(project) {
     `[neatd] span lacked service.name; routed to 'unidentified' in project ${project}; check your OTel SDK config.`
   );
 }
+var noSourceMapWarnedServices = /* @__PURE__ */ new Set();
+function warnNoSourceMaps(serviceName) {
+  if (noSourceMapWarnedServices.has(serviceName)) return;
+  noSourceMapWarnedServices.add(serviceName);
+  console.warn(
+    `[neat] ${serviceName}: no .map files found under dist/; observed file edges will land on dist paths, not src. Set sourceMap: true in tsconfig to enable file-level reconciliation.`
+  );
+}
 function pickAttr(span, ...keys) {
   for (const k of keys) {
     const v = span.attributes[k];
@@ -1735,8 +1744,13 @@ function languageForExt(relPath) {
       return void 0;
   }
 }
-function relPathForRuntimeFile(filepath, serviceNode) {
+function relPathForRuntimeFile(filepath, serviceNode, scanPath) {
   let p = toPosix(filepath).replace(/^file:\/\//, "");
+  if (scanPath && scanPath.length > 0) {
+    const absRoot = toPosix(import_node_path3.default.resolve(scanPath, serviceNode?.repoPath ?? ""));
+    const anchor = absRoot.endsWith("/") ? absRoot : `${absRoot}/`;
+    if (p.startsWith(anchor)) return p.slice(anchor.length);
+  }
   const root = serviceNode?.repoPath;
   if (root && root !== "." && root.length > 0) {
     const rootPosix = toPosix(root);
@@ -1753,16 +1767,65 @@ function relPathForRuntimeFile(filepath, serviceNode) {
   p = p.replace(/^[A-Za-z]:/, "").replace(/^\/+/, "");
   return p.length > 0 ? p : null;
 }
-function callSiteFromSpan(span, serviceNode) {
+var sourceMapCache = /* @__PURE__ */ new Map();
+function resolveDistToSrc(absFilepath, line) {
+  if (!absFilepath.endsWith(".js")) return null;
+  let entry2 = sourceMapCache.get(absFilepath);
+  if (entry2 === void 0) {
+    entry2 = null;
+    const mapPath = `${absFilepath}.map`;
+    try {
+      if ((0, import_node_fs3.existsSync)(mapPath)) {
+        const raw = JSON.parse((0, import_node_fs3.readFileSync)(mapPath, "utf8"));
+        const consumer = new sourceMapJs.SourceMapConsumer(raw);
+        entry2 = { consumer, dir: import_node_path3.default.dirname(mapPath) };
+      }
+    } catch {
+      entry2 = null;
+    }
+    sourceMapCache.set(absFilepath, entry2);
+  }
+  if (!entry2) return null;
+  try {
+    const pos = entry2.consumer.originalPositionFor({
+      line: line !== void 0 && Number.isFinite(line) ? line : 1,
+      column: 0
+    });
+    if (!pos || !pos.source) return null;
+    const root = entry2.consumer.sourceRoot ?? "";
+    const resolved = import_node_path3.default.resolve(entry2.dir, root, pos.source);
+    return { filepath: resolved, ...pos.line ? { line: pos.line } : {} };
+  } catch {
+    return null;
+  }
+}
+function callSiteFromSpan(span, serviceNode, scanPath) {
   const filepath = span.attributes[CODE_FILEPATH_ATTR];
   if (typeof filepath !== "string" || filepath.length === 0) return null;
-  const relPath = relPathForRuntimeFile(filepath, serviceNode);
-  if (!relPath) return null;
   const linenoRaw = span.attributes[CODE_LINENO_ATTR];
-  const line = typeof linenoRaw === "number" && Number.isFinite(linenoRaw) ? linenoRaw : void 0;
+  let line = typeof linenoRaw === "number" && Number.isFinite(linenoRaw) ? linenoRaw : void 0;
+  const abs = toPosix(filepath).replace(/^file:\/\//, "");
+  const resolved = resolveDistToSrc(abs, line);
+  let effectivePath = filepath;
+  let originalRelPath;
+  if (resolved) {
+    originalRelPath = relPathForRuntimeFile(filepath, serviceNode, scanPath) ?? void 0;
+    effectivePath = resolved.filepath;
+    if (resolved.line !== void 0) line = resolved.line;
+  }
+  const relPath = relPathForRuntimeFile(effectivePath, serviceNode, scanPath);
+  if (!relPath) return null;
+  if (!resolved && abs.endsWith(".js") && relPath.startsWith("dist/") && serviceNode?.name) {
+    warnNoSourceMaps(serviceNode.name);
+  }
   const fnRaw = span.attributes[CODE_FUNCTION_ATTR];
   const fn = typeof fnRaw === "string" && fnRaw.length > 0 ? fnRaw : void 0;
-  return { relPath, ...line !== void 0 ? { line } : {}, ...fn ? { fn } : {} };
+  return {
+    relPath,
+    ...line !== void 0 ? { line } : {},
+    ...fn ? { fn } : {},
+    ...originalRelPath && originalRelPath !== relPath ? { originalRelPath } : {}
+  };
 }
 function ensureObservedFileNode(graph, serviceName, serviceNodeId, callSite) {
   const fileNodeId = (0, import_types3.fileId)(serviceName, callSite.relPath);
@@ -1774,6 +1837,7 @@ function ensureObservedFileNode(graph, serviceName, serviceNodeId, callSite) {
       service: serviceName,
       path: callSite.relPath,
       ...language ? { language } : {},
+      ...callSite.originalRelPath ? { originalPath: callSite.originalRelPath } : {},
       discoveredVia: "otel"
     };
     graph.addNode(fileNodeId, node);
@@ -1799,6 +1863,12 @@ function makeInferredEdgeId(type, source, target) {
 }
 var INFERRED_CONFIDENCE = 0.6;
 var STITCH_MAX_DEPTH = 2;
+var WIRE_SPAN_KIND_CLIENT = 3;
+var WIRE_SPAN_KIND_PRODUCER = 4;
+function spanMintsObservedEdge(kind) {
+  if (kind === void 0 || kind === 0) return true;
+  return kind === WIRE_SPAN_KIND_CLIENT || kind === WIRE_SPAN_KIND_PRODUCER;
+}
 var PARENT_SPAN_CACHE_SIZE = 1e4;
 var PARENT_SPAN_CACHE_TTL_MS = 5 * 60 * 1e3;
 var parentSpanCache = /* @__PURE__ */ new Map();
@@ -2034,12 +2104,13 @@ async function handleSpan(ctx, span) {
   const isError = span.statusCode === 2;
   cacheSpanService(span, nowMs);
   const sourceServiceNode = ctx.graph.getNodeAttributes(sourceId);
-  const callSite = callSiteFromSpan(span, sourceServiceNode);
+  const callSite = callSiteFromSpan(span, sourceServiceNode, ctx.scanPath);
   const observedSource = () => callSite ? ensureObservedFileNode(ctx.graph, span.service, sourceId, callSite) : sourceId;
   let affectedNode = sourceId;
+  const mintsFromCallerSide = spanMintsObservedEdge(span.kind);
   if (span.dbSystem) {
     const host = pickAddress(span);
-    if (host) {
+    if (mintsFromCallerSide && host) {
       ensureDatabaseNode(ctx.graph, host, span.dbSystem);
       const targetId = (0, import_types3.databaseId)(host);
       const result = upsertObservedEdge(
@@ -2055,7 +2126,7 @@ async function handleSpan(ctx, span) {
   } else {
     const host = pickAddress(span);
     let resolvedViaAddress = false;
-    if (host && host !== span.service) {
+    if (mintsFromCallerSide && host && host !== span.service) {
       const targetId = resolveServiceId(ctx.graph, host, env);
       if (targetId && targetId !== sourceId) {
         upsertObservedEdge(
@@ -3851,8 +3922,14 @@ function collectStringLiterals(node, out) {
     if (child) collectStringLiterals(child, out);
   }
 }
+var PARSE_CHUNK = 16384;
+function parseSource(parser, source) {
+  return parser.parse(
+    (index) => index >= source.length ? "" : source.slice(index, index + PARSE_CHUNK)
+  );
+}
 function callsFromSource(source, parser, knownHosts) {
-  const tree = parser.parse(source);
+  const tree = parseSource(parser, source);
   const literals = [];
   collectStringLiterals(tree.rootNode, literals);
   const out = [];
@@ -5298,6 +5375,66 @@ function registryPath() {
 function registryLockPath() {
   return import_node_path34.default.join(neatHome(), "projects.json.lock");
 }
+function daemonPidPath() {
+  return import_node_path34.default.join(neatHome(), "neatd.pid");
+}
+function isPidAliveDefault(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+async function readPidFile(file) {
+  try {
+    const raw = await import_node_fs21.promises.readFile(file, "utf8");
+    const pid = Number.parseInt(raw.trim(), 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : void 0;
+  } catch {
+    return void 0;
+  }
+}
+var defaultLockHolderProbe = {
+  isPidAlive: isPidAliveDefault,
+  daemonPidFromFile: () => readPidFile(daemonPidPath()),
+  async daemonResponds() {
+    const base = process.env.NEAT_API_URL ?? "http://localhost:8080";
+    try {
+      await fetch(`${base}/health`, { signal: AbortSignal.timeout(750) });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+};
+async function readLockPid(lockPath) {
+  return readPidFile(lockPath);
+}
+async function classifyLockHolder(lockPath, probe = defaultLockHolderProbe) {
+  const lockPid = await readLockPid(lockPath);
+  const daemonPid = await probe.daemonPidFromFile();
+  if (daemonPid !== void 0 && daemonPid !== process.pid && probe.isPidAlive(daemonPid) && // The lock already names the daemon, or the daemon answers on its port.
+  // Either confirms a live daemon is in the picture (the second guards
+  // against a stale pidfile whose PID got reused).
+  (daemonPid === lockPid || await probe.daemonResponds())) {
+    return { kind: "daemon", pid: daemonPid };
+  }
+  if (lockPid !== void 0 && lockPid !== process.pid && probe.isPidAlive(lockPid)) {
+    return { kind: "command", pid: lockPid };
+  }
+  return { kind: "stale" };
+}
+function lockHolderMessage(holder, lockPath, timeoutMs) {
+  switch (holder.kind) {
+    case "daemon":
+      return `The neat daemon (pid ${holder.pid}) is holding the registry lock. Register this project through the daemon, or stop neatd and re-run \`neat init\`.`;
+    case "command":
+      return `Another neat command (pid ${holder.pid}) is holding the registry lock. Wait for it to finish, or check \`ps\` if you're not sure what's running.`;
+    case "stale":
+      return `neat registry: timed out after ${timeoutMs}ms waiting for ${lockPath}. Another neat process is holding the lock; if no such process exists, remove the file by hand.`;
+  }
+}
 async function normalizeProjectPath(input) {
   const resolved = import_node_path34.default.resolve(input);
   try {
@@ -5318,21 +5455,31 @@ async function writeAtomically(target, contents) {
   }
   await import_node_fs21.promises.rename(tmp, target);
 }
-async function acquireLock(lockPath, timeoutMs = LOCK_TIMEOUT_MS) {
+async function acquireLock(lockPath, timeoutMs = LOCK_TIMEOUT_MS, probe = defaultLockHolderProbe) {
   const deadline = Date.now() + timeoutMs;
   await import_node_fs21.promises.mkdir(import_node_path34.default.dirname(lockPath), { recursive: true });
+  let probedHolder = false;
   while (true) {
     try {
       const fd = await import_node_fs21.promises.open(lockPath, "wx");
-      await fd.close();
+      try {
+        await fd.writeFile(`${process.pid}
+`, "utf8");
+      } finally {
+        await fd.close();
+      }
       return;
     } catch (err) {
       const code = err.code;
       if (code !== "EEXIST") throw err;
+      if (!probedHolder) {
+        probedHolder = true;
+        const holder = await classifyLockHolder(lockPath, probe);
+        if (holder.kind === "daemon") throw new Error(lockHolderMessage(holder, lockPath, timeoutMs));
+      }
       if (Date.now() >= deadline) {
-        throw new Error(
-          `neat registry: timed out after ${timeoutMs}ms waiting for ${lockPath}. Another neat process is holding the lock; if no such process exists, remove the file by hand.`
-        );
+        const holder = await classifyLockHolder(lockPath, probe);
+        throw new Error(lockHolderMessage(holder, lockPath, timeoutMs));
       }
       await new Promise((r) => setTimeout(r, LOCK_RETRY_MS));
     }
@@ -6525,6 +6672,7 @@ async function startWatch(graph, opts) {
   const onSpan = makeSpanHandler({
     graph,
     errorsPath: opts.errorsPath,
+    scanPath: opts.scanPath,
     project: projectName,
     writeErrorEventInline: false,
     onPolicyTrigger
@@ -6539,6 +6687,7 @@ async function startWatch(graph, opts) {
     const onSpanGrpc = makeSpanHandler({
       graph,
       errorsPath: opts.errorsPath,
+      scanPath: opts.scanPath,
       project: projectName,
       onPolicyTrigger
     });
@@ -6804,13 +6953,20 @@ var import_node_path40 = __toESM(require("path"), 1);
 // src/installers/templates.ts
 init_cjs_shims();
 var OTEL_INIT_HEADER = "// Generated by `neat init --apply` (ADR-069). OpenTelemetry auto-instrumentation hook.";
-var OTEL_INIT_STAMP = "// neat-template-version: 3 \u2014 file-first call-site capture (ADR-089) + OTLP bearer auth (#410).";
+var OTEL_INIT_STAMP = "// neat-template-version: 4 \u2014 layered file-first capture (ADR-090): stack walk + handler-entry + off-stack facades.";
 var OTEL_OTLP_HEADERS_JS = "if (process.env.NEAT_OTEL_TOKEN) process.env.OTEL_EXPORTER_OTLP_HEADERS ||= 'Authorization=Bearer ' + process.env.NEAT_OTEL_TOKEN";
-function neatCallsiteProcessorSource(ts) {
-  const stackT = ts ? ": string" : "";
+function neatCaptureSource(ts) {
   const spanT = ts ? ": any" : "";
   const strOpt = ts ? ": string | undefined" : "";
-  return `function __neatPickUserFrame(stack${stackT}) {
+  const anyT = ts ? ": any" : "";
+  const fnT = ts ? ": any" : "";
+  const arrAny = ts ? ": any[]" : "";
+  return `// Context key shared by the facade/handler wraps (writers) and the
+// processor fallback (reader). Symbol.for keeps it stable even if the wraps
+// and the processor end up in different module instances.
+const NEAT_USER_FRAME = Symbol.for('neat.user-frame')
+
+function __neatPickUserFrame(stack${strOpt}) {
   const lines = String(stack || '').split('\\n')
   for (let i = 0; i < lines.length; i++) {
     const raw = lines[i].trim()
@@ -6819,6 +6975,9 @@ function neatCallsiteProcessorSource(ts) {
     if (raw.indexOf('@opentelemetry') !== -1) continue
     if (raw.indexOf('node:') !== -1) continue
     if (raw.indexOf('NeatCallSiteSpanProcessor') !== -1) continue
+    // Skip NEAT's own inlined wraps/helpers (all carry the __neat prefix) so a
+    // facade frame never masquerades as the user's call site.
+    if (raw.indexOf('__neat') !== -1) continue
     const bodyText = raw.slice(3)
     const loc = bodyText.match(/:(\\d+):(\\d+)\\)?$/)
     if (!loc) continue
@@ -6840,32 +6999,245 @@ function neatCallsiteProcessorSource(ts) {
   return null
 }
 
+// Layer 2/3 fallback source: the frame a handler-entry or facade wrap pushed
+// into context. Reads the span's own parent context first, then the active
+// context \u2014 the capture spike confirmed both return the value for undici.
+function __neatFrameFromContext(parentContext${anyT}) {
+  try {
+    const fromParent =
+      parentContext && typeof parentContext.getValue === 'function'
+        ? parentContext.getValue(NEAT_USER_FRAME)
+        : undefined
+    return fromParent || context.active().getValue(NEAT_USER_FRAME) || null
+  } catch (_e) {
+    return null
+  }
+}
+
+function __neatSetCodeAttrs(span${spanT}, frame${anyT}) {
+  span.setAttribute('code.filepath', frame.filepath)
+  if (typeof frame.lineno === 'number') span.setAttribute('code.lineno', frame.lineno)
+  if (frame.function) span.setAttribute('code.function', frame.function)
+}
+
 class NeatCallSiteSpanProcessor {
-  onStart(span${spanT}) {
+  onStart(span${spanT}, parentContext${anyT}) {
     if (!span || (span.kind !== 2 && span.kind !== 3)) return
-    const frame = __neatPickUserFrame(new Error().stack)
+    // Layer 1 \u2014 synchronous stack walk (sync-wrapper instrumentations).
+    let frame = __neatPickUserFrame(new Error().stack)
+    // Layer 2/3 \u2014 the handler-entry or off-stack-facade frame from context.
+    if (!frame) frame = __neatFrameFromContext(parentContext)
     if (!frame) return
-    span.setAttribute('code.filepath', frame.filepath)
-    if (typeof frame.lineno === 'number') span.setAttribute('code.lineno', frame.lineno)
-    if (frame.function) span.setAttribute('code.function', frame.function)
+    __neatSetCodeAttrs(span, frame)
   }
   onEnd() {}
   forceFlush() { return Promise.resolve() }
   shutdown() { return Promise.resolve() }
+}
+
+// Capture the caller's synchronous frame at the wrap point and run \`fn\` with
+// that frame pushed into the active context (file-awareness.md \xA74 layer 3). An
+// off-stack instrumentation that creates its span inside \`fn\` inherits the
+// frame; the processor reads it via __neatFrameFromContext.
+function __neatRunWithUserFrame(fn${fnT}) {
+  const frame = __neatPickUserFrame(new Error().stack)
+  if (!frame) return fn()
+  return context.with(context.active().setValue(NEAT_USER_FRAME, frame), fn)
+}
+
+// Handler-entry attribution (file-awareness.md \xA74 layer 2). Stamp the framework
+// SERVER span with the handler frame captured at route registration, and push
+// the same frame into context so downstream CLIENT/PRODUCER spans inherit the
+// handler-file floor when their own stack carries none.
+function __neatStampHandler(frame${anyT}, run${fnT}) {
+  try {
+    const active = trace.getActiveSpan()
+    if (active && active.kind === 1 && typeof active.setAttribute === 'function') {
+      __neatSetCodeAttrs(active, frame)
+    }
+  } catch (_e) {}
+  try {
+    return context.with(context.active().setValue(NEAT_USER_FRAME, frame), run)
+  } catch (_e) {
+    return run()
+  }
+}
+
+// require-in-the-middle is a transitive dependency of the OTel instrumentation
+// packages NEAT installs, so it resolves in any instrumented CJS service.
+// Guarded: when it's absent (or the host runs as pure ESM, where require isn't
+// defined) the off-stack/handler wraps degrade to the stack walk + context
+// floor, never to a crash.
+function __neatHook(modules${arrAny}, onload${fnT}) {
+  try {
+    const RITM = require('require-in-the-middle')
+    const Hook = RITM && RITM.Hook ? RITM.Hook : RITM
+    new Hook(modules, { internals: false }, onload)
+    return true
+  } catch (_e) {
+    return false
+  }
+}
+
+// Off-stack facade: Node's built-in fetch / undici. The instrumentation creates
+// the CLIENT span inside a diagnostics_channel handler detached from the
+// caller's stack, so wrap the global so the user frame is in context when the
+// span is created. The capture spike (2026-05-28) validated this on real
+// undici. .name is restored to 'fetch' for ecosystem compatibility; the inner
+// __neat name is what the frame skip keys on.
+function __neatWrapFetch() {
+  try {
+    const g${anyT} = globalThis
+    if (typeof g.fetch === 'function' && !g.fetch.__neatWrapped) {
+      const realFetch = g.fetch
+      // The wrapper keeps its __neat-prefixed name so the frame skip in
+      // __neatPickUserFrame never mistakes the wrapper's own frame for the
+      // user's call site (renaming it to 'fetch' would defeat the skip).
+      const __neatFetch${anyT} = function (input${anyT}, init${anyT}) {
+        return __neatRunWithUserFrame(function () { return realFetch(input, init) })
+      }
+      __neatFetch.__neatWrapped = true
+      g.fetch = __neatFetch
+    }
+  } catch (_e) {}
+}
+
+// Off-stack facade: @prisma/client. Prisma's query engine backdates its spans
+// from Rust, off the caller's stack. Wrap the model methods on the client
+// prototype so the call-site frame (still synchronous at \`prisma.user.find\`)
+// is pushed into context for the engine dispatch.
+function __neatWrapPrisma() {
+  __neatHook(['@prisma/client'], function (exports${anyT}) {
+    try {
+      const Client = exports && exports.PrismaClient
+      if (typeof Client === 'function' && !Client.__neatWrapped) {
+        const ops = ['findUnique','findUniqueOrThrow','findFirst','findFirstOrThrow','findMany','create','createMany','update','updateMany','upsert','delete','deleteMany','count','aggregate','groupBy']
+        const __neatPrismaWrapModel = function (model${anyT}) {
+          if (!model || model.__neatWrapped) return model
+          for (let i = 0; i < ops.length; i++) {
+            const op = ops[i]
+            const orig = model[op]
+            if (typeof orig !== 'function') continue
+            model[op] = function __neatPrismaOp(${ts ? "...args: any[]" : "...args"}) {
+              const self = this
+              return __neatRunWithUserFrame(function () { return orig.apply(self, args) })
+            }
+          }
+          model.__neatWrapped = true
+          return model
+        }
+        const proto = Client.prototype
+        const handler = function (model${anyT}) { return __neatPrismaWrapModel(model) }
+        // Model accessors are lazily created getters on the instance; wrap the
+        // \`$extends\`-free common path by trapping property access via a proxy
+        // on each constructed client.
+        exports.PrismaClient = new Proxy(Client, {
+          construct(Target${anyT}, argList${anyT}, NewTarget${anyT}) {
+            const instance = Reflect.construct(Target, argList, NewTarget)
+            return new Proxy(instance, {
+              get(target${anyT}, prop${anyT}, receiver${anyT}) {
+                const value = Reflect.get(target, prop, receiver)
+                if (value && typeof value === 'object' && typeof prop === 'string' && prop[0] !== '$' && prop[0] !== '_') {
+                  return handler(value)
+                }
+                return value
+              },
+            })
+          },
+        })
+        exports.PrismaClient.__neatWrapped = true
+        void proto
+      }
+    } catch (_e) {}
+    return exports
+  })
+}
+
+// Handler-entry facades. express / connect share the Layer model (each route
+// handler is a function registered on a Router); the wrap captures the
+// registration frame and stamps + propagates it when the handler runs. The
+// registry is the extensibility seam \u2014 koa, fastify (via @fastify/otel),
+// nestjs, restify, and hapi add an entry as their patch surface is wired.
+function __neatWrapConnectStyle(mod${anyT}) {
+  try {
+    // express() returns an app whose route verbs live on Router.prototype and
+    // the application proto; connect apps expose \`use\`. Wrap the registration
+    // verbs so the user handler is wound with its registration frame.
+    const verbs = ['use','get','post','put','delete','patch','all','options','head']
+    const wrapTarget = function (target${anyT}) {
+      if (!target || target.__neatVerbsWrapped) return
+      for (let i = 0; i < verbs.length; i++) {
+        const verb = verbs[i]
+        const orig = target[verb]
+        if (typeof orig !== 'function') continue
+        target[verb] = function __neatVerb(${ts ? "...args: any[]" : "...args"}) {
+          const frame = __neatPickUserFrame(new Error().stack)
+          if (frame) {
+            for (let a = 0; a < args.length; a++) {
+              const h = args[a]
+              if (typeof h === 'function' && !h.__neatHandlerWrapped && h.length <= 4) {
+                const inner = h
+                const __neatHandler${anyT} = function (${ts ? "...hargs: any[]" : "...hargs"}) {
+                  const self = this
+                  return __neatStampHandler(frame, function () { return inner.apply(self, hargs) })
+                }
+                __neatHandler.__neatHandlerWrapped = true
+                args[a] = __neatHandler
+              }
+            }
+          }
+          return orig.apply(this, args)
+        }
+      }
+      target.__neatVerbsWrapped = true
+    }
+    if (mod && mod.Router && mod.Router.prototype) wrapTarget(mod.Router.prototype)
+    if (mod && mod.application) wrapTarget(mod.application)
+    if (mod && mod.prototype) wrapTarget(mod.prototype)
+  } catch (_e) {}
+}
+
+function __neatInstallHandlerEntry() {
+  __neatHook(['express'], function (exports${anyT}) { __neatWrapConnectStyle(exports); return exports })
+  __neatHook(['connect'], function (exports${anyT}) { __neatWrapConnectStyle(exports); return exports })
+}
+
+// Install every off-stack and handler-entry wrap. Called once after sdk.start()
+// \u2014 before user code requires the framework / Prisma modules, so the hooks land
+// on first require. Each wrap is independently guarded.
+function __neatInstallFacades() {
+  __neatWrapFetch()
+  __neatWrapPrisma()
+  __neatInstallHandlerEntry()
 }`;
 }
-var CALLSITE_PROCESSOR_JS = neatCallsiteProcessorSource(false);
-var CALLSITE_PROCESSOR_TS = neatCallsiteProcessorSource(true);
-function neatRegisterCallsiteSource(ts) {
+var CALLSITE_PROCESSOR_JS = neatCaptureSource(false);
+var CALLSITE_PROCESSOR_TS = neatCaptureSource(true);
+function neatWireCaptureSource(ts) {
   const providerT = ts ? ": any" : "";
   return `try {
   const provider${providerT} = trace.getTracerProvider()
   const delegate = provider && typeof provider.getDelegate === 'function' ? provider.getDelegate() : provider
-  if (delegate && typeof delegate.addSpanProcessor === 'function') {
-    delegate.addSpanProcessor(new NeatCallSiteSpanProcessor())
-  }
-} catch {
-  // capture is best-effort; span export is unaffected
+  if (!delegate || typeof delegate.addSpanProcessor !== 'function') {
+    throw new Error('[neat] could not resolve a TracerProvider to attach the call-site processor; file-first OBSERVED capture would be silent (file-awareness.md \xA74)')
+  }
+  const __neatProcessor = new NeatCallSiteSpanProcessor()
+  delegate.addSpanProcessor(__neatProcessor)
+  // Post-init assertion: confirm attachment on providers that expose their
+  // processor list. An un-introspectable provider is trusted (we just called
+  // its addSpanProcessor); a list that exists and lacks our processor throws.
+  const registered = delegate._registeredSpanProcessors
+  if (Array.isArray(registered) && registered.indexOf(__neatProcessor) === -1) {
+    throw new Error('[neat] call-site processor did not attach to the active TracerProvider (file-awareness.md \xA74)')
+  }
+} catch (err) {
+  throw err
+}
+try {
+  __neatInstallFacades()
+} catch (_e) {
+  // Facade install is best-effort: the stack-walk + handler-entry floor still
+  // attribute the sync-wrapper majority even if an off-stack wrap fails.
 }`;
 }
 var OTEL_INIT_CJS = `${OTEL_INIT_HEADER}
@@ -6876,7 +7248,7 @@ ${OTEL_OTLP_HEADERS_JS}
 
 const { NodeSDK } = require('@opentelemetry/sdk-node')
 const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node')
-const { trace } = require('@opentelemetry/api')
+const { trace, context } = require('@opentelemetry/api')
 
 ${CALLSITE_PROCESSOR_JS}
 
@@ -6884,7 +7256,7 @@ const instrumentations = [getNodeAutoInstrumentations()]
 __INSTRUMENTATION_BLOCK__
 const sdk = new NodeSDK({ instrumentations })
 sdk.start()
-${neatRegisterCallsiteSource(false)}
+${neatWireCaptureSource(false)}
 `;
 var OTEL_INIT_ESM = `${OTEL_INIT_HEADER}
 ${OTEL_INIT_STAMP}
@@ -6894,7 +7266,7 @@ ${OTEL_OTLP_HEADERS_JS}
 
 import { NodeSDK } from '@opentelemetry/sdk-node'
 import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
-import { trace } from '@opentelemetry/api'
+import { trace, context } from '@opentelemetry/api'
 
 ${CALLSITE_PROCESSOR_JS}
 
@@ -6902,17 +7274,22 @@ const instrumentations = [getNodeAutoInstrumentations()]
 __INSTRUMENTATION_BLOCK__
 const sdk = new NodeSDK({ instrumentations })
 sdk.start()
-${neatRegisterCallsiteSource(false)}
+${neatWireCaptureSource(false)}
 `;
 var OTEL_INIT_TS = `${OTEL_INIT_HEADER}
 ${OTEL_INIT_STAMP}
+// @ts-nocheck \u2014 generated runtime shim. The layered capture mechanism uses
+// dynamic patterns (facade wraps, Proxy traps, a createRequire bridge) that a
+// strict user tsconfig would reject; suppressing type-checking here keeps the
+// generated file from breaking the host project's \`tsc\` gate (#427) without
+// constraining the runtime logic. The file is regenerated, never hand-edited.
 process.env.OTEL_SERVICE_NAME ||= '__SERVICE_NAME__'
 process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ||= 'http://localhost:4318/projects/__PROJECT__/v1/traces'
 ${OTEL_OTLP_HEADERS_JS}
 
 import { NodeSDK } from '@opentelemetry/sdk-node'
 import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
-import { trace } from '@opentelemetry/api'
+import { trace, context } from '@opentelemetry/api'
 
 ${CALLSITE_PROCESSOR_TS}
 
@@ -6920,7 +7297,7 @@ const instrumentations = [getNodeAutoInstrumentations()]
 __INSTRUMENTATION_BLOCK__
 const sdk = new NodeSDK({ instrumentations })
 sdk.start()
-${neatRegisterCallsiteSource(true)}
+${neatWireCaptureSource(true)}
 `;
 function renderNodeOtelInit(template, serviceName, projectName, registrations = []) {
   const block = registrations.length === 0 ? "" : `