autotel-cli 0.13.1 → 0.15.0

package/dist/index.js

@@ -4,15 +4,16 @@ import * as fs from "node:fs";
 import { readFileSync } from "node:fs";
 import * as path$1 from "node:path";
 import path from "node:path";
-import { execSync } from "node:child_process";
+import { execFileSync, execSync } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
-import { glob } from "glob";
+import { glob, globSync } from "glob";
 import chalk from "chalk";
 import { checkbox, confirm, select } from "@inquirer/prompts";
 import ora from "ora";
 import * as semver from "semver";
 import { Project, SyntaxKind } from "ts-morph";
 import { fileURLToPath } from "node:url";
+import { JsonTraceSerializer, ProtobufTraceSerializer } from "@opentelemetry/otlp-transformer";
 import { buildCollectorGuide, buildInstrumentationGuide, clearSemanticConventionCache, collectUsage, detectAnomalies, discoverLogFields, discoverServices, discoverTraceFields, findRootCause, getCollectorComponentReadme, getCollectorComponentSchema, getModelStats, getSemanticConventionNamespace, listCollectorComponents, listCollectorVersions, listModels, listSemanticConventionNamespaces, listToolUsage, pickErrorMessage, rankExpensiveTraces, rankSlowTraces, refreshCollectorCatalog, resolveCollectorVersion, scoreSpan, suggestCollectorConfig, suggestInstrumentationFixes, toLogSearchQuery, toMetricSearchQuery, toSpanSearchQuery, toTraceSearchQuery, validateCollectorComponentConfig, validateOtlpReceiverConfig } from "autotel-mcp";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { appendFile, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
@@ -2250,6 +2251,7 @@ const AutotelErrorCodes = {
 	E_INSTALL_FAILED: "AUTOTEL_E_INSTALL_FAILED",
 	E_WRITE_FAILED: "AUTOTEL_E_WRITE_FAILED",
 	E_READ_FAILED: "AUTOTEL_E_READ_FAILED",
+	E_RATE_LIMITED: "AUTOTEL_E_RATE_LIMITED",
 	E_UNKNOWN: "AUTOTEL_E_UNKNOWN"
 };
 /**
@@ -3851,6 +3853,2256 @@ async function runAdd(type, name, options) {
 	}
 }
 //#endregion
+//#region src/lib/map/facts.ts
+function isAutotelModule(specifier) {
+	return specifier === "autotel" || specifier.startsWith("autotel/") || specifier.startsWith("autotel-");
+}
+/**
+* Whether a canonical Autotel API is actually called in these facts.
+*
+* Import provenance matters: a local helper with the same name must not count.
+* Namespace and aliased imports are resolved here once for every scanner rule
+* and for project-level integration detection.
+*/
+function usesAutotelApi$1(facts, names, autoImports = []) {
+	return names.some((name) => {
+		if (autoImports.includes(name) && facts.callsTo(name).length > 0) return true;
+		for (const [local, module] of facts.imports) {
+			if (!isAutotelModule(module)) continue;
+			const imported = facts.importedNames.get(local);
+			if (imported === name && facts.callsTo(local).length > 0) return true;
+			if (imported === "*" && facts.memberCalls(name).some((call) => call.root === local)) return true;
+		}
+		return false;
+	});
+}
+/** Names that mean "this error was recorded", not swallowed. */
+const ERROR_SINKS = /* @__PURE__ */ new Set([
+	"error",
+	"recordStructuredError",
+	"recordException",
+	"captureException",
+	"recordError",
+	"fail"
+]);
+/** Autotel's structured-throw constructors. */
+const STRUCTURED_ERROR_NAMES = /* @__PURE__ */ new Set([
+	"createStructuredError",
+	"createError",
+	"AutotelError"
+]);
+function createParser() {
+	const project = new Project({
+		skipAddingFilesFromTsConfig: true,
+		skipFileDependencyResolution: true,
+		compilerOptions: {
+			allowJs: true,
+			checkJs: false
+		}
+	});
+	const cache = /* @__PURE__ */ new Map();
+	return (absolutePath) => {
+		const cached = cache.get(absolutePath);
+		if (cached !== void 0) return cached;
+		let file;
+		try {
+			if (absolutePath.endsWith(".vue")) {
+				const text = fs.readFileSync(absolutePath, "utf8");
+				const scripts = [...text.matchAll(/<script\b[^>]*>([\s\S]*?)<\/script>/gi)];
+				if (scripts.length === 0) file = project.createSourceFile(`${absolutePath}.ts`, "");
+				else {
+					const chars = [...text].map((char) => char === "\n" ? "\n" : " ");
+					for (const match of scripts) {
+						const body = match[1] ?? "";
+						const bodyOffset = (match.index ?? 0) + match[0].indexOf(body);
+						for (let index = 0; index < body.length; index++) chars[bodyOffset + index] = body[index] ?? " ";
+					}
+					file = project.createSourceFile(`${absolutePath}.ts`, chars.join(""));
+				}
+			} else file = project.addSourceFileAtPath(absolutePath);
+		} catch {
+			file = null;
+		}
+		cache.set(absolutePath, file);
+		return file;
+	};
+}
+/** Rightmost name and leftmost identifier of a callee expression. */
+function calleeParts(expr) {
+	const access = expr.asKind(SyntaxKind.PropertyAccessExpression);
+	if (access) {
+		let root = access.getExpression();
+		for (;;) {
+			const inner = root.asKind(SyntaxKind.PropertyAccessExpression);
+			if (!inner) break;
+			root = inner.getExpression();
+		}
+		return {
+			member: access.getName(),
+			root: root.isKind(SyntaxKind.Identifier) ? root.getText() : null
+		};
+	}
+	const text = expr.getText();
+	return {
+		member: text,
+		root: expr.isKind(SyntaxKind.Identifier) ? text : null
+	};
+}
+function isEmptyBlock(block) {
+	if (!block) return true;
+	const asBlock = block.asKind(SyntaxKind.Block);
+	return asBlock ? asBlock.getStatements().length === 0 : false;
+}
+/** Whether a catch block records the error rather than dropping it. */
+function catchHandles(block) {
+	let handled = false;
+	block.forEachDescendant((node, traversal) => {
+		if (node.isKind(SyntaxKind.ThrowStatement)) {
+			handled = true;
+			traversal.stop();
+			return;
+		}
+		if (!node.isKind(SyntaxKind.CallExpression)) return;
+		const { member } = calleeParts(node.getExpression());
+		if (ERROR_SINKS.has(member)) {
+			handled = true;
+			traversal.stop();
+		}
+	});
+	return handled;
+}
+function classifyThrow(expression) {
+	if (!expression) return "other";
+	const newExpr = expression.asKind(SyntaxKind.NewExpression);
+	if (newExpr) {
+		const name = newExpr.getExpression().getText();
+		if (STRUCTURED_ERROR_NAMES.has(name)) return "structured";
+		return name === "Error" || name.endsWith("Error") ? "plain-error" : "other";
+	}
+	const call = expression.asKind(SyntaxKind.CallExpression);
+	if (call) {
+		const { member } = calleeParts(call.getExpression());
+		if (STRUCTURED_ERROR_NAMES.has(member)) return "structured";
+		return "other";
+	}
+	return "other";
+}
+function classifyImportedThrow(expression, imports, importedNames) {
+	const direct = classifyThrow(expression);
+	if (direct !== "other") return direct;
+	const call = expression?.asKind(SyntaxKind.CallExpression) ?? expression?.asKind(SyntaxKind.NewExpression);
+	if (!call) return direct;
+	const { member, root } = calleeParts(call.getExpression());
+	const localModule = imports.get(member);
+	if (STRUCTURED_ERROR_NAMES.has(importedNames.get(member) ?? "") && localModule !== void 0) return "structured";
+	if (root && importedNames.get(root) === "*" && imports.has(root) && STRUCTURED_ERROR_NAMES.has(member)) return "structured";
+	return direct;
+}
+function objectProperties(node) {
+	const object = node?.asKind(SyntaxKind.ObjectLiteralExpression);
+	if (!object) return /* @__PURE__ */ new Set();
+	return new Set(object.getProperties().flatMap((property) => {
+		if (property.isKind(SyntaxKind.PropertyAssignment) || property.isKind(SyntaxKind.ShorthandPropertyAssignment) || property.isKind(SyntaxKind.MethodDeclaration) || property.isKind(SyntaxKind.GetAccessor) || property.isKind(SyntaxKind.SetAccessor)) return [property.getName().replaceAll(/^['"]|['"]$/g, "")];
+		return [];
+	}));
+}
+function structuredProps(expression) {
+	const call = expression?.asKind(SyntaxKind.CallExpression);
+	if (call) return objectProperties(call.getArguments()[0]);
+	const created = expression?.asKind(SyntaxKind.NewExpression);
+	return created ? objectProperties(created.getArguments()[0]) : /* @__PURE__ */ new Set();
+}
+function structuredIdentity(expression) {
+	const call = expression?.asKind(SyntaxKind.CallExpression);
+	const created = expression?.asKind(SyntaxKind.NewExpression);
+	const object = (call?.getArguments()[0] ?? created?.getArguments()[0])?.asKind(SyntaxKind.ObjectLiteralExpression);
+	if (!object) return null;
+	const message = object.getProperty("message");
+	const status = object.getProperty("status");
+	if (!message?.isKind(SyntaxKind.PropertyAssignment) || !status?.isKind(SyntaxKind.PropertyAssignment)) return null;
+	const messageText = message.getInitializer()?.getText();
+	const statusText = status.getInitializer()?.getText();
+	const literal = messageText && /^(['"`])([\s\S]*)\1$/.exec(messageText);
+	if (!literal?.[2] || !statusText || !/^\d+$/.test(statusText)) return null;
+	return {
+		signature: `${statusText}|${literal[2]}`,
+		label: literal[2]
+	};
+}
+const NETWORK_CALLS = /* @__PURE__ */ new Set([
+	"fetch",
+	"$fetch",
+	"useFetch",
+	"useAsyncData",
+	"query"
+]);
+function networkCallHandled(call) {
+	for (const ancestor of call.getAncestors()) {
+		if (ancestor.isKind(SyntaxKind.TryStatement)) {
+			const tryBlock = ancestor.getTryBlock();
+			if (call.getStart() >= tryBlock.getStart() && call.getEnd() <= tryBlock.getEnd() && ancestor.getCatchClause()) return true;
+		}
+		if (ancestor.isKind(SyntaxKind.CallExpression)) {
+			const expression = ancestor.getExpression();
+			if (expression.isKind(SyntaxKind.PropertyAccessExpression) && expression.getName() === "catch") return true;
+		}
+		if (ancestor.isKind(SyntaxKind.VariableDeclaration)) {
+			const name = ancestor.getNameNode();
+			if (name.isKind(SyntaxKind.ObjectBindingPattern) && name.getElements().some((element) => element.getNameNode().getText() === "error")) return true;
+		}
+	}
+	return false;
+}
+/**
+* Reduce a parsed file to {@link FileFacts} in a single walk.
+*
+* @param scope Narrows the walk to one subtree — the handler function, for a
+* framework that registers many routes in one file. Imports are always read
+* from the whole file: that is where they are.
+*/
+function buildFileFacts(source, scope) {
+	const imports = /* @__PURE__ */ new Map();
+	const importedNames = /* @__PURE__ */ new Map();
+	const modules = /* @__PURE__ */ new Set();
+	for (const declaration of source.getImportDeclarations()) {
+		const specifier = declaration.getModuleSpecifierValue();
+		modules.add(specifier);
+		const bind = (name, importedName = name) => {
+			imports.set(name, specifier);
+			importedNames.set(name, importedName);
+		};
+		const defaultImport = declaration.getDefaultImport();
+		if (defaultImport) bind(defaultImport.getText());
+		for (const named of declaration.getNamedImports()) bind(named.getAliasNode()?.getText() ?? named.getName(), named.getName());
+		const namespaceImport = declaration.getNamespaceImport();
+		if (namespaceImport) bind(namespaceImport.getText(), "*");
+	}
+	const calls = [];
+	const throws = [];
+	const catches = [];
+	const network = [];
+	const factoryBindings = /* @__PURE__ */ new Map();
+	const names = /* @__PURE__ */ new Set();
+	const visit = (node) => {
+		if (node.isKind(SyntaxKind.Identifier)) {
+			names.add(node.getText());
+			return;
+		}
+		if (node.isKind(SyntaxKind.CallExpression)) {
+			const { member, root } = calleeParts(node.getExpression());
+			const fact = {
+				text: node.getExpression().getText(),
+				member,
+				root,
+				line: node.getStartLineNumber(),
+				args: node.getArguments().length
+			};
+			calls.push(fact);
+			if (NETWORK_CALLS.has(member)) network.push({
+				name: member,
+				line: fact.line,
+				handled: networkCallHandled(node)
+			});
+			return;
+		}
+		if (node.isKind(SyntaxKind.ThrowStatement)) {
+			const identity = structuredIdentity(node.getExpression());
+			const fact = {
+				kind: classifyImportedThrow(node.getExpression(), imports, importedNames),
+				line: node.getStartLineNumber(),
+				props: structuredProps(node.getExpression())
+			};
+			if (identity) {
+				fact.signature = identity.signature;
+				fact.label = identity.label;
+			}
+			throws.push(fact);
+			return;
+		}
+		if (node.isKind(SyntaxKind.VariableDeclaration)) {
+			const call = node.getInitializer()?.asKind(SyntaxKind.CallExpression);
+			const name = node.getNameNode();
+			if (call && name.isKind(SyntaxKind.Identifier)) factoryBindings.set(name.getText(), calleeParts(call.getExpression()).member);
+		}
+		if (node.isKind(SyntaxKind.CatchClause)) {
+			const block = node.getBlock();
+			catches.push({
+				line: node.getStartLineNumber(),
+				isEmpty: isEmptyBlock(block),
+				handled: catchHandles(block)
+			});
+		}
+	};
+	const roots = Array.isArray(scope) ? scope : [scope ?? source];
+	for (const root of roots) root.forEachDescendant(visit);
+	const byName = /* @__PURE__ */ new Map();
+	const byMember = /* @__PURE__ */ new Map();
+	for (const call of calls) {
+		if (call.root !== null && call.text === call.root) {
+			const bucket = byName.get(call.text);
+			if (bucket) bucket.push(call);
+			else byName.set(call.text, [call]);
+		}
+		const memberBucket = byMember.get(call.member);
+		if (memberBucket) memberBucket.push(call);
+		else byMember.set(call.member, [call]);
+	}
+	const callsTo = (name) => byName.get(name) ?? [];
+	const memberCalls = (member) => byMember.get(member) ?? [];
+	return {
+		imports,
+		importedNames,
+		modules,
+		calls,
+		throws,
+		catches,
+		network,
+		factoryBindings,
+		names,
+		callsTo,
+		memberCalls
+	};
+}
+/** Repo-relative POSIX path — the spelling used everywhere in the map file. */
+function relativeFile(root, absolutePath) {
+	return path$1.relative(root, absolutePath).split(path$1.sep).join("/");
+}
+/** The source line at `line` (1-indexed), trimmed, for evidence snippets. */
+function lineSnippet(source, line) {
+	return source.getFullText().split("\n")[line - 1]?.trim() || void 0;
+}
+//#endregion
+//#region src/lib/map/adapters.ts
+const HTTP_METHODS = /* @__PURE__ */ new Set([
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE",
+	"HEAD",
+	"OPTIONS"
+]);
+const IGNORE = [
+	"**/node_modules/**",
+	"**/dist/**",
+	"**/.output/**",
+	"**/*.test.*",
+	"**/*.spec.*"
+];
+function files(root, pattern) {
+	return globSync(pattern, {
+		cwd: root,
+		absolute: true,
+		ignore: IGNORE
+	}).toSorted();
+}
+/**
+* Convert filesystem segments to a route path.
+*
+* Covers the three conventions in play at once: Next's `(group)` and
+* `[...slug]`, Nitro's `[id]`, and SvelteKit's `[id]`. They do not collide, so
+* one function is less to keep in sync than three.
+*/
+function segmentsToPath(segments) {
+	return `/${segments.filter((segment) => segment.length > 0).filter((segment) => !/^\(.*\)$/.test(segment)).map((segment) => {
+		if (/^\[?\[\.{3}(.+?)\]\]?$/.exec(segment)) return "*";
+		const dynamic = /^\[(.+?)\]$/.exec(segment);
+		return dynamic ? `:${dynamic[1]}` : segment;
+	}).join("/")}`.replaceAll(/\/+/g, "/").replace(/(.)\/$/, "$1");
+}
+function locationOf(node, source) {
+	if (!node || !source) return null;
+	return {
+		line: node.getStartLineNumber(),
+		column: source.getLineAndColumnAtPos(node.getStart()).column
+	};
+}
+/** Exported HTTP-method handlers in a route file, with where each is declared. */
+function methodExports(source) {
+	const found = [];
+	for (const [name, declarations] of source.getExportedDeclarations()) {
+		if (!HTTP_METHODS.has(name)) continue;
+		found.push({
+			method: name,
+			handler: locationOf(declarations[0], source)
+		});
+	}
+	return found;
+}
+/** The declaration a file's default export points at. */
+function defaultExportLocation(source) {
+	return locationOf(source.getExportedDeclarations().get("default")?.[0], source);
+}
+/**
+* Calls to named APIs from one package family, resolved through aliases and
+* namespace imports. Text mentions and same-named local helpers do not count.
+*/
+function importedCalls(source, modulePrefix, canonicalNames) {
+	const names = new Set(canonicalNames);
+	const locals = /* @__PURE__ */ new Map();
+	const namespaces = /* @__PURE__ */ new Set();
+	for (const declaration of source.getImportDeclarations()) {
+		if (!declaration.getModuleSpecifierValue().startsWith(modulePrefix)) continue;
+		for (const named of declaration.getNamedImports()) {
+			if (!names.has(named.getName())) continue;
+			locals.set(named.getAliasNode()?.getText() ?? named.getName(), named.getName());
+		}
+		const namespace = declaration.getNamespaceImport()?.getText();
+		if (namespace) namespaces.add(namespace);
+	}
+	const found = /* @__PURE__ */ new Map();
+	for (const call of source.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+		const expression = call.getExpression();
+		if (expression.isKind(SyntaxKind.Identifier)) {
+			const canonical = locals.get(expression.getText());
+			if (canonical && !found.has(canonical)) found.set(canonical, call);
+			continue;
+		}
+		if (expression.isKind(SyntaxKind.PropertyAccessExpression) && namespaces.has(expression.getExpression().getText()) && names.has(expression.getName()) && !found.has(expression.getName())) found.set(expression.getName(), call);
+	}
+	return found;
+}
+function nextAppDir(root) {
+	for (const candidate of ["app", "src/app"]) if (files(root, `${candidate}/**/route.{ts,tsx,js,jsx}`).length > 0) return candidate;
+	return null;
+}
+const nextAdapter = {
+	framework: "next",
+	autoImports: [],
+	extractRoutes({ projectRoot, parse }) {
+		const routes = [];
+		const appDir = nextAppDir(projectRoot);
+		if (appDir) for (const absolute of files(projectRoot, `${appDir}/**/route.{ts,tsx,js,jsx}`)) {
+			const relative = relativeFile(projectRoot, absolute);
+			const routePath = segmentsToPath(relative.slice(appDir.length + 1).replace(/(?:^|\/)route\.[tj]sx?$/, "").split("/"));
+			const source = parse(absolute);
+			const methods = source ? methodExports(source) : [];
+			if (methods.length === 0) {
+				routes.push({
+					framework: "next",
+					kind: "api",
+					method: null,
+					path: routePath,
+					file: relative,
+					handler: null
+				});
+				continue;
+			}
+			for (const { method, handler } of methods) routes.push({
+				framework: "next",
+				kind: "api",
+				method,
+				path: routePath,
+				file: relative,
+				handler
+			});
+		}
+		for (const absolute of [...files(projectRoot, "pages/api/**/*.{ts,tsx,js,jsx}"), ...files(projectRoot, "src/pages/api/**/*.{ts,tsx,js,jsx}")]) {
+			const relative = relativeFile(projectRoot, absolute);
+			const routePath = segmentsToPath(relative.replace(/^(?:src\/)?pages/, "").replace(/\.[tj]sx?$/, "").replace(/\/index$/, "").split("/"));
+			const source = parse(absolute);
+			routes.push({
+				framework: "next",
+				kind: "api",
+				method: null,
+				path: routePath,
+				file: relative,
+				handler: source ? defaultExportLocation(source) : null
+			});
+		}
+		for (const candidate of ["middleware.ts", "src/middleware.ts"]) {
+			const absolute = path$1.join(projectRoot, candidate);
+			if (!fileExists(absolute)) continue;
+			const source = parse(absolute);
+			routes.push({
+				framework: "next",
+				kind: "middleware",
+				method: null,
+				path: "/*",
+				file: candidate,
+				handler: source ? defaultExportLocation(source) : null
+			});
+		}
+		for (const appRoot of ["app", "src/app"]) for (const absolute of files(projectRoot, `${appRoot}/**/page.{ts,tsx,js,jsx}`)) {
+			const relative = relativeFile(projectRoot, absolute);
+			const dir = relative.slice(appRoot.length + 1).replace(/(?:^|\/)page\.[tj]sx?$/, "");
+			const source = parse(absolute);
+			routes.push({
+				framework: "next",
+				kind: "page",
+				method: null,
+				path: segmentsToPath(dir.split("/")),
+				file: relative,
+				handler: source ? defaultExportLocation(source) : null
+			});
+		}
+		for (const pagesRoot of ["pages", "src/pages"]) for (const absolute of files(projectRoot, `${pagesRoot}/**/*.{ts,tsx,js,jsx}`)) {
+			const relative = relativeFile(projectRoot, absolute);
+			const belowRoot = relative.slice(pagesRoot.length + 1);
+			if (belowRoot.startsWith("api/") || /^_(?:app|document|error)\.[tj]sx?$/.test(belowRoot)) continue;
+			const routePath = segmentsToPath(belowRoot.replace(/\.[tj]sx?$/, "").replace(/\/index$/, "").split("/"));
+			const source = parse(absolute);
+			routes.push({
+				framework: "next",
+				kind: "page",
+				method: null,
+				path: routePath,
+				file: relative,
+				handler: source ? defaultExportLocation(source) : null
+			});
+		}
+		return routes;
+	}
+};
+/** Nitro encodes the method in the filename: `users.post.ts` is `POST /users`. */
+function nitroMethodSuffix(fileName) {
+	const match = /^(.*)\.(get|post|put|patch|delete|head|options)$/i.exec(fileName);
+	if (!match?.[1] || !match[2]) return {
+		method: null,
+		base: fileName
+	};
+	return {
+		method: match[2].toUpperCase(),
+		base: match[1]
+	};
+}
+const nitroAdapter = {
+	framework: "nitro",
+	autoImports: ["useLogger", "defineEventHandler"],
+	extractRoutes({ projectRoot, parse }) {
+		const routes = [];
+		for (const group of [
+			{
+				glob: "server/api/**/*.{ts,js}",
+				prefix: "server/api",
+				kind: "api"
+			},
+			{
+				glob: "server/routes/**/*.{ts,js}",
+				prefix: "server/routes",
+				kind: "api"
+			},
+			{
+				glob: "server/middleware/*.{ts,js}",
+				prefix: "server/middleware",
+				kind: "middleware"
+			}
+		]) for (const absolute of files(projectRoot, group.glob)) {
+			const relative = relativeFile(projectRoot, absolute);
+			const segments = relative.slice(group.prefix.length).replace(/\.[tj]s$/, "").split("/").filter(Boolean);
+			const { method, base } = nitroMethodSuffix(segments.pop() ?? "");
+			if (base !== "index") segments.push(base);
+			const routePath = group.kind === "middleware" ? "/*" : segmentsToPath(group.prefix === "server/api" ? ["api", ...segments] : segments);
+			const source = parse(absolute);
+			routes.push({
+				framework: "nitro",
+				kind: group.kind,
+				method,
+				path: routePath,
+				file: relative,
+				handler: source ? defaultExportLocation(source) : null
+			});
+		}
+		for (const pagesRoot of ["pages", "app/pages"]) for (const absolute of files(projectRoot, `${pagesRoot}/**/*.{vue,ts,tsx,js,jsx}`)) {
+			const relative = relativeFile(projectRoot, absolute);
+			const routePath = segmentsToPath(relative.slice(pagesRoot.length + 1).replace(/\.(?:vue|[tj]sx?)$/, "").replace(/\/index$/, "").split("/"));
+			const source = parse(absolute);
+			routes.push({
+				framework: "nitro",
+				kind: "page",
+				method: null,
+				path: routePath,
+				file: relative,
+				handler: source ? defaultExportLocation(source) : null
+			});
+		}
+		return routes;
+	}
+};
+const svelteKitAdapter = {
+	framework: "sveltekit",
+	autoImports: [],
+	extractRoutes({ projectRoot, parse }) {
+		const routes = [];
+		for (const absolute of files(projectRoot, "src/routes/**/+server.{ts,js}")) {
+			const relative = relativeFile(projectRoot, absolute);
+			const routePath = segmentsToPath(relative.slice(10).replace(/\/\+server\.[tj]s$/, "").split("/"));
+			const source = parse(absolute);
+			const methods = source ? methodExports(source) : [];
+			if (methods.length === 0) {
+				routes.push({
+					framework: "sveltekit",
+					kind: "api",
+					method: null,
+					path: routePath,
+					file: relative,
+					handler: null
+				});
+				continue;
+			}
+			for (const { method, handler } of methods) routes.push({
+				framework: "sveltekit",
+				kind: "api",
+				method,
+				path: routePath,
+				file: relative,
+				handler
+			});
+		}
+		for (const absolute of files(projectRoot, "src/routes/**/+{page,layout}.server.{ts,js}")) {
+			const relative = relativeFile(projectRoot, absolute);
+			const dir = relative.slice(10).replace(/\/\+(?:page|layout)\.server\.[tj]s$/, "");
+			const source = parse(absolute);
+			routes.push({
+				framework: "sveltekit",
+				kind: "server-fn",
+				method: null,
+				path: segmentsToPath(dir.split("/")),
+				file: relative,
+				handler: source ? locationOf(source.getExportedDeclarations().get("load")?.[0], source) ?? locationOf(source.getExportedDeclarations().get("actions")?.[0], source) : null
+			});
+		}
+		for (const candidate of ["src/hooks.server.ts", "src/hooks.server.js"]) {
+			if (!fileExists(path$1.join(projectRoot, candidate))) continue;
+			const source = parse(path$1.join(projectRoot, candidate));
+			routes.push({
+				framework: "sveltekit",
+				kind: "middleware",
+				method: null,
+				path: "/*",
+				file: candidate,
+				handler: source ? locationOf(source.getExportedDeclarations().get("handle")?.[0], source) : null
+			});
+		}
+		for (const absolute of files(projectRoot, "src/routes/**/+page.{ts,js}")) {
+			const relative = relativeFile(projectRoot, absolute);
+			const dir = relative.slice(10).replace(/\/\+page\.[tj]s$/, "");
+			const source = parse(absolute);
+			routes.push({
+				framework: "sveltekit",
+				kind: "page",
+				method: null,
+				path: segmentsToPath(dir.split("/")),
+				file: relative,
+				handler: source ? locationOf(source.getExportedDeclarations().get("load")?.[0], source) : null
+			});
+		}
+		return routes;
+	}
+};
+const tanstackAdapter = {
+	framework: "tanstack-start",
+	autoImports: [],
+	extractRoutes({ projectRoot, parse }) {
+		const routes = [];
+		for (const absolute of files(projectRoot, "src/routes/**/*.{ts,tsx}")) {
+			const text = readFileSafe(absolute) ?? "";
+			if (!/createServerFileRoute|createServerFn|createFileRoute/.test(text)) continue;
+			const relative = relativeFile(projectRoot, absolute);
+			const dir = relative.slice(10).replace(/\.[tj]sx?$/, "").replace(/\/index$/, "");
+			const source = parse(absolute);
+			if (!source) continue;
+			const calls = importedCalls(source, "@tanstack/", [
+				"createServerFileRoute",
+				"createServerFn",
+				"createFileRoute"
+			]);
+			const serverRoute = calls.get("createServerFileRoute");
+			const serverFn = calls.get("createServerFn");
+			const page = calls.get("createFileRoute");
+			const routePath = segmentsToPath(dir.split("/"));
+			if (serverRoute || serverFn) routes.push({
+				framework: "tanstack-start",
+				kind: serverRoute ? "api" : "server-fn",
+				method: null,
+				path: routePath,
+				file: relative,
+				handler: locationOf(serverRoute ?? serverFn, source)
+			});
+			if (page) routes.push({
+				framework: "tanstack-start",
+				kind: "page",
+				method: null,
+				path: routePath,
+				file: relative,
+				handler: locationOf(page, source)
+			});
+		}
+		return routes;
+	}
+};
+const cloudflareAdapter = {
+	framework: "cloudflare",
+	autoImports: [],
+	extractRoutes({ projectRoot, parse }) {
+		for (const candidate of [
+			"src/index.ts",
+			"src/worker.ts",
+			"src/index.js",
+			"index.ts"
+		]) {
+			const absolute = path$1.join(projectRoot, candidate);
+			if (!fileExists(absolute)) continue;
+			const source = parse(absolute);
+			return [{
+				framework: "cloudflare",
+				kind: "api",
+				method: null,
+				path: "/*",
+				file: candidate,
+				handler: source ? defaultExportLocation(source) : null
+			}];
+		}
+		return [];
+	}
+};
+const ROUTER_CALL = /\.\s*(get|post|put|patch|delete|all|use)\s*\(\s*['"`]/;
+/**
+* One adapter for every framework that registers routes as `app.get(path, fn)`.
+*
+* Hono, Express, Fastify, and Elysia differ in everything except the shape this
+* scan cares about, so four adapters would be the same file copied four times.
+* Files are text-filtered before parsing: an app of any size has few route
+* files, and parsing all of `src/` to find them costs far more than reading it.
+*/
+function routerAdapter(framework) {
+	return {
+		framework,
+		autoImports: [],
+		extractRoutes({ projectRoot, parse }) {
+			const routes = [];
+			for (const absolute of [...files(projectRoot, "{src,app,server,routes}/**/*.{ts,js,mts,mjs}"), ...files(projectRoot, "*.{ts,js,mts,mjs}")]) {
+				const text = readFileSafe(absolute);
+				if (!text || !ROUTER_CALL.test(text)) continue;
+				const source = parse(absolute);
+				if (!source) continue;
+				const relative = relativeFile(projectRoot, absolute);
+				for (const call of source.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+					const callee = call.getExpression();
+					const match = /\.(get|post|put|patch|delete|all|use)$/.exec(callee.getText());
+					if (!match?.[1]) continue;
+					const args = call.getArguments();
+					const first = args[0];
+					if (!first || args.length < 2) continue;
+					const literal = /^['"`](.*)['"`]$/s.exec(first.getText());
+					if (!literal?.[1]) continue;
+					const routePath = literal[1];
+					if (routePath !== "*" && !routePath.startsWith("/")) continue;
+					const verb = match[1];
+					routes.push({
+						framework,
+						kind: verb === "use" ? "middleware" : "api",
+						method: verb === "use" || verb === "all" ? null : verb.toUpperCase(),
+						path: routePath,
+						file: relative,
+						handler: {
+							line: call.getStartLineNumber(),
+							column: source.getLineAndColumnAtPos(call.getStart()).column
+						}
+					});
+				}
+			}
+			return routes;
+		},
+		scopesFor(route, source) {
+			const line = route.handler?.line;
+			if (line === void 0) return;
+			const call = source.getDescendantsOfKind(SyntaxKind.CallExpression).find((candidate) => candidate.getStartLineNumber() === line && /\.(get|post|put|patch|delete|all|use)$/.test(candidate.getExpression().getText()));
+			if (!call) return;
+			const handler = call.getArguments().at(-1);
+			const declarations = handler ? handler.getDescendantsOfKind(SyntaxKind.Identifier).flatMap((identifier) => {
+				const declaration = identifier.getDefinitions()[0]?.getDeclarationNode();
+				return declaration?.isKind(SyntaxKind.FunctionDeclaration) || declaration?.isKind(SyntaxKind.VariableDeclaration) ? [declaration] : [];
+			}) : [];
+			if (handler?.isKind(SyntaxKind.Identifier)) {
+				const declaration = handler.getDefinitions()[0]?.getDeclarationNode();
+				if (declaration?.isKind(SyntaxKind.FunctionDeclaration) || declaration?.isKind(SyntaxKind.VariableDeclaration)) declarations.push(declaration);
+			}
+			return [call, ...new Set(declarations)];
+		}
+	};
+}
+function getAdapter(framework) {
+	switch (framework) {
+		case "next": return nextAdapter;
+		case "nitro": return nitroAdapter;
+		case "sveltekit": return svelteKitAdapter;
+		case "tanstack-start": return tanstackAdapter;
+		case "cloudflare": return cloudflareAdapter;
+		case "hono":
+		case "express":
+		case "fastify":
+		case "elysia": return routerAdapter(framework);
+	}
+}
+const SUPPORTED_FRAMEWORKS = [
+	"next",
+	"nitro",
+	"tanstack-start",
+	"sveltekit",
+	"hono",
+	"express",
+	"fastify",
+	"elysia",
+	"cloudflare"
+];
+function isFramework(value) {
+	return SUPPORTED_FRAMEWORKS.includes(value);
+}
+/**
+* Pick the framework to scan for.
+*
+* Meta-frameworks are checked first: a Nuxt app has `h3` installed and an
+* Express app does not become a Next app because it renders one page.
+*/
+function detectFramework(projectRoot, deps) {
+	const warnings = [];
+	const matched = [
+		["next", deps.has("next")],
+		["nitro", deps.has("nuxt") || deps.has("nitropack") || deps.has("h3")],
+		["tanstack-start", deps.has("@tanstack/react-start") || deps.has("@tanstack/start")],
+		["sveltekit", deps.has("@sveltejs/kit")],
+		["cloudflare", fileExists(path$1.join(projectRoot, "wrangler.toml")) || fileExists(path$1.join(projectRoot, "wrangler.jsonc")) || fileExists(path$1.join(projectRoot, "wrangler.json"))],
+		["hono", deps.has("hono")],
+		["elysia", deps.has("elysia")],
+		["fastify", deps.has("fastify")],
+		["express", deps.has("express")]
+	].filter(([, present]) => present).map(([name]) => name);
+	if (matched.length === 0) return {
+		framework: null,
+		warnings
+	};
+	if (matched.length > 1) warnings.push(`Multiple frameworks detected (${matched.join(", ")}); scanning as ${matched[0]}. Use --framework to override.`);
+	return {
+		framework: matched[0] ?? null,
+		warnings
+	};
+}
+//#endregion
+//#region src/lib/map/exemptions.ts
+/**
+* Paths with nothing to instrument, as consecutive path segments.
+*
+* Matched segment by segment rather than as a substring: an exemption skips
+* every rule, so a loose match is the worst bug this tool can have — it drops a
+* real handler out of the score instead of reporting a gap.
+*/
+const EXEMPT_SEGMENTS = [
+	{
+		segments: ["health"],
+		reason: "health check — nothing to instrument"
+	},
+	{
+		segments: ["healthz"],
+		reason: "health check — nothing to instrument"
+	},
+	{
+		segments: ["livez"],
+		reason: "liveness probe — nothing to instrument"
+	},
+	{
+		segments: ["readyz"],
+		reason: "readiness probe — nothing to instrument"
+	},
+	{
+		segments: ["ping"],
+		reason: "liveness probe — nothing to instrument"
+	},
+	{
+		segments: ["metrics"],
+		reason: "metrics endpoint — telemetry plumbing"
+	},
+	{
+		segments: ["api", "otel"],
+		reason: "autotel infrastructure — telemetry ingest"
+	},
+	{
+		segments: ["api", "telemetry"],
+		reason: "autotel infrastructure — telemetry ingest"
+	}
+];
+/** Path or file split into lowercase segments, extension and method suffix dropped. */
+function segmentsOf(value) {
+	return value.toLowerCase().split("/").filter((segment) => segment.length > 0).map((segment) => segment.split(".")[0] ?? segment);
+}
+function containsRun(segments, pattern) {
+	return segments.some((_, index) => pattern.every((name, offset) => segments[index + offset] === name));
+}
+/** The exemption for this entry point, if any. Depends only on path and file. */
+function getRouteExemption(route) {
+	const pathSegments = segmentsOf(route.path);
+	const fileSegments = segmentsOf(route.file);
+	for (const candidate of EXEMPT_SEGMENTS) if (containsRun(pathSegments, candidate.segments) || containsRun(fileSegments, candidate.segments)) return {
+		reason: candidate.reason,
+		skip: "all"
+	};
+	return null;
+}
+function isSkipped(exemption, id) {
+	return exemption.skip === "all" || exemption.skip.includes(id);
+}
+function isExemptRoute(route) {
+	return getRouteExemption(route) !== null;
+}
+const DIRECTIVE = /(?:\/\/|\/\*|\*)\s*autotel-map-disable(?<scope>-next-line|-line)?(?:\s+(?<ids>[a-z*-]+(?:\s*,\s*[a-z*-]+)*))?(?:\s*--\s*(?<reason>.*?))?\s*(?:\*\/)?\s*$/;
+/** Every `autotel-map-disable` comment in a file, indexed for lookup. */
+function collectSuppressions(sourceText) {
+	const all = [];
+	const lines = sourceText.split("\n");
+	for (const [index, text] of lines.entries()) {
+		const match = DIRECTIVE.exec(text);
+		if (!match) continue;
+		const scope = match.groups?.["scope"] === "-next-line" ? "next-line" : match.groups?.["scope"] === "-line" ? "line" : "file";
+		const reason = match.groups?.["reason"]?.trim() || null;
+		const ids = (match.groups?.["ids"] ?? "*").split(",").map((id) => id.trim()).filter(Boolean);
+		for (const id of ids) all.push({
+			id,
+			declaredAt: index + 1,
+			reason,
+			scope
+		});
+	}
+	const matches = (suppression, id) => suppression.id === "*" || suppression.id === id;
+	return {
+		file: (id) => all.find((suppression) => suppression.scope === "file" && matches(suppression, id)),
+		at: (id, line) => all.find((suppression) => matches(suppression, id) && (suppression.scope === "next-line" && suppression.declaredAt + 1 === line || suppression.scope === "line" && suppression.declaredAt === line)),
+		unknown: (known) => all.filter((suppression) => suppression.id !== "*" && !known.includes(suppression.id))
+	};
+}
+function suppressionMessage(suppression) {
+	return suppression.reason ? `disabled: ${suppression.reason}` : "disabled by autotel-map-disable";
+}
+/** How many checks on this entry point were waived by a comment. */
+function countSuppressed(route) {
+	return Object.values(route.checks).filter((check) => check?.suppressed).length;
+}
+//#endregion
+//#region src/lib/map/types.ts
+/** Entry-point kinds that own a server-side span and request event. */
+const HANDLER_KINDS = [
+	"api",
+	"middleware",
+	"server-fn"
+];
+//#endregion
+//#region src/lib/map/rules.ts
+/**
+* Everything that puts this handler on a trace.
+*
+* The framework wrappers belong here alongside `trace()`: `withAutotel(...)`
+* from `autotel-adapters/next` creates the request span, and a rule that only
+* knew about `trace()` would report a fully instrumented route as invisible.
+*/
+const SPAN_WRAPPERS = [
+	"trace",
+	"span",
+	"instrument",
+	"withTracing",
+	"enterSpan",
+	"traceGenAI",
+	"traceLLM",
+	"withAutotel",
+	"withAutotelFetch",
+	"withAutotelHandler",
+	"autotelHandle",
+	"autotelMiddleware",
+	"defineAutotelEventHandler"
+];
+const REQUEST_LOGGERS = [
+	"getRequestLogger",
+	"useLogger",
+	"getExecutionLogger"
+];
+/** Request-logger and span-context members that attach business context. */
+const CONTEXT_MEMBERS = [
+	"set",
+	"setAttribute",
+	"setAttributes",
+	"info",
+	"warn",
+	"error"
+];
+const AUDIT_APIS = [
+	"withAudit",
+	"securityEvent",
+	"withSecurity",
+	"setAuditAttributes",
+	"forceKeepAuditEvent"
+];
+const GENAI_TRACERS = [
+	"traceGenAI",
+	"traceLLM",
+	"recordGenAiUsage"
+];
+/** Calls that mean "an LLM was invoked", across the common SDKs. */
+const LLM_CALLS = [
+	"generateText",
+	"streamText",
+	"generateObject",
+	"streamObject",
+	"completions",
+	"create",
+	"invoke",
+	"chat"
+];
+/**
+* Whether the file calls one of these autotel APIs.
+*
+* The name has to come from autotel — imported from an `autotel*` module, or
+* injected by the framework integration. Otherwise a local helper called
+* `trace()` would score as instrumentation.
+*/
+function usesAutotelApi(context, names) {
+	return usesAutotelApi$1(context.facts, names, context.autoImports);
+}
+function autotelLocalNames(context, canonicalNames) {
+	const locals = new Set(context.autoImports.filter((name) => canonicalNames.includes(name)));
+	for (const canonical of canonicalNames) locals.add(canonical);
+	for (const [local, module] of context.facts.imports) {
+		if (!isAutotelModule(module)) continue;
+		const imported = context.facts.importedNames.get(local) ?? "";
+		if (canonicalNames.includes(imported)) locals.add(local);
+		else if (imported === "*") for (const canonical of canonicalNames) locals.add(`${local}.${canonical}`);
+	}
+	return locals;
+}
+function loggerMemberCalls(context, member) {
+	const factories = autotelLocalNames(context, REQUEST_LOGGERS);
+	return context.facts.memberCalls(member).filter((call) => {
+		if (call.root && factories.has(context.facts.factoryBindings.get(call.root) ?? "")) return true;
+		return [...factories].some((factory) => call.text.startsWith(`${factory}().`));
+	});
+}
+const traceRule = {
+	id: "trace",
+	category: "requirement",
+	title: "span",
+	question: "Does this entry point produce a span?",
+	weight: 40,
+	appliesTo: { kinds: HANDLER_KINDS },
+	fix: ({ target }) => `export const handler = trace('${target.method?.toLowerCase() ?? "handle"} ${target.path}', async () => { /* … */ });`,
+	check(context) {
+		if (usesAutotelApi(context, SPAN_WRAPPERS)) return null;
+		if (context.project.ambientTracing) return null;
+		if (!context.project.hasAutotel) return { message: "autotel not installed — nothing observes this handler" };
+		return { message: "no trace() or span() — this handler is invisible when it breaks" };
+	}
+};
+const contextRule = {
+	id: "context",
+	category: "requirement",
+	title: "context",
+	question: "Does the span carry business context, or only method and status?",
+	weight: 25,
+	appliesTo: { kinds: HANDLER_KINDS },
+	fix: ({ target }) => target.framework === "nitro" ? "const log = useLogger(event); log.set({ 'user.id': userId });" : "const log = getRequestLogger(); log.set({ 'user.id': userId });",
+	check(context) {
+		const hasLogger = usesAutotelApi(context, REQUEST_LOGGERS);
+		const setsContext = CONTEXT_MEMBERS.some((member) => loggerMemberCalls(context, member).length > 0);
+		if (hasLogger && setsContext) return null;
+		if (hasLogger) return {
+			message: "request logger acquired but never given attributes",
+			line: context.facts.callsTo("getRequestLogger")[0]?.line
+		};
+		return { message: context.project.ambientTracing ? "handler adds nothing to its request span — only method, path and status are recorded" : "no request-scoped attributes — the span says what failed, not for whom" };
+	}
+};
+const structuredErrorsRule = {
+	id: "structured-errors",
+	category: "requirement",
+	title: "errors",
+	question: "Do thrown errors explain why they failed and how to fix them?",
+	weight: 15,
+	appliesTo: {
+		kinds: HANDLER_KINDS,
+		when: ({ facts }) => facts.throws.length > 0
+	},
+	fix: () => "throw createStructuredError({ message: 'Payment declined', why: '…', fix: '…', status: 402 });",
+	check({ facts }) {
+		const plain = facts.throws.find((entry) => entry.kind === "plain-error");
+		if (plain) return {
+			message: "throws a bare Error — no why, fix, or status for the caller",
+			line: plain.line
+		};
+		const incomplete = facts.throws.find((entry) => entry.kind === "structured" && (!entry.props.has("why") || !entry.props.has("fix")));
+		if (!incomplete) return null;
+		return {
+			message: `structured error is missing ${["why", "fix"].filter((name) => !incomplete.props.has(name)).join(" and ")}`,
+			line: incomplete.line
+		};
+	}
+};
+const pageErrorHandlingRule = {
+	id: "page-error-handling",
+	category: "requirement",
+	title: "fetch",
+	question: "Does this page handle its data request failing?",
+	weight: 20,
+	appliesTo: {
+		kinds: ["page"],
+		when: ({ facts }) => facts.network.length > 0
+	},
+	fix: () => "try { const data = await fetchData(); } catch (error) { /* render an error state */ }",
+	check({ facts }) {
+		const unhandled = facts.network.find((call) => !call.handled);
+		if (!unhandled) return null;
+		return {
+			message: `${unhandled.name}() has no error path — the page breaks when it fails`,
+			line: unhandled.line
+		};
+	}
+};
+const errorHandlingRule = {
+	id: "error-handling",
+	category: "requirement",
+	title: "catch",
+	question: "Does every catch block record the failure?",
+	weight: 10,
+	appliesTo: {
+		kinds: HANDLER_KINDS,
+		when: ({ facts }) => facts.catches.length > 0
+	},
+	fix: () => "catch (error) { log.error(error); throw error; }",
+	check({ facts }) {
+		const swallowed = facts.catches.find((entry) => entry.isEmpty || !entry.handled);
+		if (!swallowed) return null;
+		return {
+			message: swallowed.isEmpty ? "empty catch block — the failure disappears" : "catch block neither records nor rethrows — the failure disappears",
+			line: swallowed.line
+		};
+	}
+};
+const auditRule = {
+	id: "audit",
+	category: "requirement",
+	title: "audit",
+	question: "Does this money or auth path leave an audit trail?",
+	weight: 25,
+	appliesTo: {
+		kinds: HANDLER_KINDS,
+		when: ({ target }) => target.sensitivity.level === "high"
+	},
+	fix: ({ target }) => `withAudit({ action: '${target.path.replaceAll("/", ".").replace(/^\./, "")}', resource: '…', actorId }, async (ctx, log) => { /* … */ });`,
+	check(context) {
+		if (usesAutotelApi(context, AUDIT_APIS)) return null;
+		return { message: `no audit trail (${context.target.sensitivity.reasons[0] ?? "sensitive route"}) — withAudit() survives tail sampling` };
+	}
+};
+const WRITE_CALLS$1 = [
+	"create",
+	"update",
+	"insert",
+	"upsert",
+	"delete",
+	"destroy"
+];
+/**
+* Every rule, in report order.
+*
+* Adding a rule is one entry here plus one id in {@link CheckId}: weight,
+* column title, docs link, and applicability all travel with the rule.
+*/
+const RULES = [
+	traceRule,
+	contextRule,
+	structuredErrorsRule,
+	errorHandlingRule,
+	pageErrorHandlingRule,
+	auditRule,
+	{
+		id: "audit-coverage",
+		category: "opportunity",
+		title: "audit+",
+		question: "Should this state change join the project audit trail?",
+		appliesTo: {
+			kinds: HANDLER_KINDS,
+			when: ({ target, project, facts }) => target.sensitivity.level !== "high" && project.hasAuditUsage && WRITE_CALLS$1.some((name) => facts.memberCalls(name).length > 0)
+		},
+		fix: ({ target }) => `securityEvent({ name: '${target.path.replaceAll("/", ".").replace(/^\./, "")}.changed', category: 'data', outcome: 'success' });`,
+		check(context) {
+			if (usesAutotelApi(context, AUDIT_APIS)) return null;
+			return {
+				message: "changes state with no security event — this project records audit signals elsewhere",
+				line: WRITE_CALLS$1.flatMap((name) => context.facts.memberCalls(name)).toSorted((a, b) => a.line - b.line)[0]?.line
+			};
+		}
+	},
+	{
+		id: "error-catalog",
+		category: "opportunity",
+		title: "catalog",
+		question: "Should duplicated structured errors become catalog entries?",
+		appliesTo: {
+			kinds: HANDLER_KINDS,
+			when: ({ project, facts }) => project.hasErrorCatalog && facts.throws.some((entry) => entry.signature !== void 0 && project.repeatedErrors.has(entry.signature))
+		},
+		fix: () => "const billing = defineErrorCatalog('billing', { PAYMENT_DECLINED: { status: 402, message: 'Card declined', why: '…', fix: '…' } });",
+		check({ facts, project }) {
+			const thrown = facts.throws.find((entry) => entry.signature !== void 0 && project.repeatedErrors.has(entry.signature));
+			if (!thrown?.signature) return null;
+			const repeated = project.repeatedErrors.get(thrown.signature);
+			if (!repeated) return null;
+			return {
+				message: `"${repeated.label}" is repeated in ${repeated.files.length} files — one error catalog entry would cover them`,
+				line: thrown.line
+			};
+		}
+	},
+	{
+		id: "genai",
+		category: "opportunity",
+		title: "genai",
+		question: "Are LLM calls traced with token usage and cost?",
+		appliesTo: {
+			kinds: HANDLER_KINDS,
+			when: ({ project }) => project.hasLlmDependency
+		},
+		fix: () => "traceGenAI({ operation: 'chat', model }, async () => client.chat.completions.create(…));",
+		check(context) {
+			const llmCall = LLM_CALLS.flatMap((name) => context.facts.memberCalls(name)).find((call) => call.root !== null && call.root !== "JSON");
+			if (!llmCall) return null;
+			if (usesAutotelApi(context, GENAI_TRACERS)) return null;
+			return {
+				message: "LLM call with no gen_ai.* span — token usage and cost go unrecorded",
+				line: llmCall.line
+			};
+		}
+	},
+	{
+		id: "validation",
+		category: "opportunity",
+		title: "input",
+		question: "Are rejected inputs visible in telemetry?",
+		appliesTo: {
+			kinds: HANDLER_KINDS,
+			when: ({ project }) => project.hasZod
+		},
+		fix: () => "const parse = defineValidator('createOrder', schema, { boundary: 'http' });",
+		check(context) {
+			const parseCall = context.facts.memberCalls("parse")[0] ?? context.facts.memberCalls("safeParse")[0];
+			if (!parseCall) return null;
+			if (usesAutotelApi(context, ["defineValidator"])) return null;
+			return {
+				message: "input validated without telemetry — defineValidator() records which field failed",
+				line: parseCall.line
+			};
+		}
+	},
+	{
+		id: "redaction",
+		category: "opportunity",
+		scope: "project",
+		title: "pii",
+		question: "Is PII redacted before attributes leave the process?",
+		appliesTo: {
+			kinds: HANDLER_KINDS,
+			when: ({ target, project }) => target.sensitivity.level !== "none" && project.hasAutotel && !project.hasRedaction
+		},
+		fix: () => "init({ service, attributeRedactor: 'default' })",
+		check(context) {
+			return { message: `sensitive routes but init() sets no attributeRedactor${context.project.instrumentationFile ? ` (${context.project.instrumentationFile})` : ""}` };
+		}
+	}
+];
+const RULES_BY_ID = new Map(RULES.map((rule) => [rule.id, rule]));
+function getRule(id) {
+	return RULES_BY_ID.get(id);
+}
+/** Rules that move the score, in report order. */
+const REQUIREMENTS = RULES.filter((rule) => rule.category === "requirement");
+/**
+* Run every applicable rule against one entry point.
+*
+* Rules that are irrelevant by kind are left out of the result entirely; rules
+* that are relevant but gated by `when` are reported as `n/a`, so the map
+* distinguishes "this question makes no sense here" from "this question does
+* not apply right now".
+*/
+function runRules(context) {
+	const results = {
+		checks: {},
+		suggestions: {},
+		warnings: []
+	};
+	const { target } = context;
+	const exemption = getRouteExemption(target);
+	const relevant = RULES.filter((rule) => rule.appliesTo.kinds.includes(target.kind));
+	const suppressions = collectSuppressions(context.source.getFullText());
+	const knownIds = RULES.map((rule) => rule.id);
+	for (const suppression of suppressions.unknown(knownIds)) results.warnings.push(`${target.file}:${suppression.declaredAt} disables "${suppression.id}", which is not a check autotel map runs`);
+	for (const rule of relevant) {
+		const bucket = rule.category === "requirement" ? results.checks : results.suggestions;
+		if (exemption && isSkipped(exemption, rule.id)) {
+			if (rule.category === "requirement") results.checks[rule.id] = {
+				status: "n/a",
+				message: exemption.reason
+			};
+			continue;
+		}
+		if (rule.appliesTo.when && !rule.appliesTo.when(context)) {
+			if (rule.category === "requirement") results.checks[rule.id] = { status: "n/a" };
+			continue;
+		}
+		const report = rule.check(context);
+		if (!report) {
+			if (rule.category === "requirement") results.checks[rule.id] = { status: "pass" };
+			continue;
+		}
+		const line = report.line ?? target.handler?.line ?? 1;
+		const disabled = suppressions.file(rule.id) ?? suppressions.at(rule.id, line);
+		if (disabled) {
+			if (rule.category === "requirement") results.checks[rule.id] = suppressedResult(disabled, target.file);
+			continue;
+		}
+		bucket[rule.id] = {
+			status: "fail",
+			message: report.message,
+			fix: rule.fix(context),
+			evidence: {
+				file: target.file,
+				line,
+				snippet: lineSnippet(context.source, line)
+			}
+		};
+	}
+	return results;
+}
+/**
+* Results for an entry point whose file could not be read or parsed.
+*
+* A file that will not parse is a real failure, but only of requirements —
+* there is no basis to suggest anything about code that could not be read.
+*/
+function unreadableResults(target) {
+	const results = {
+		checks: {},
+		suggestions: {},
+		warnings: []
+	};
+	const exemption = getRouteExemption(target);
+	for (const rule of RULES) {
+		if (rule.category !== "requirement") continue;
+		if (!rule.appliesTo.kinds.includes(target.kind)) continue;
+		results.checks[rule.id] = exemption && isSkipped(exemption, rule.id) ? {
+			status: "n/a",
+			message: exemption.reason
+		} : {
+			status: "fail",
+			message: "file could not be parsed",
+			evidence: {
+				file: target.file,
+				line: 1
+			}
+		};
+	}
+	return results;
+}
+/**
+* A finding the author waived with a comment.
+*
+* `n/a` rather than `pass`: the rule did find something, and calling that a
+* pass would read as coverage the entry point does not have.
+*/
+function suppressedResult(suppression, file) {
+	return {
+		status: "n/a",
+		suppressed: true,
+		message: suppressionMessage(suppression),
+		evidence: {
+			file,
+			line: suppression.declaredAt
+		}
+	};
+}
+//#endregion
+//#region src/lib/map/score.ts
+/** Fallback weight for a rule id that is not in the registry. */
+const UNKNOWN_WEIGHT = 10;
+/**
+* Score one entry point from its requirement results.
+*
+* Opportunities are deliberately unreachable from here: they live in
+* `route.suggestions`, and their type carries no weight to subtract.
+*/
+function scoreRoute(checks) {
+	let score = 100;
+	for (const [id, result] of Object.entries(checks)) {
+		if (result.status !== "fail") continue;
+		const rule = getRule(id);
+		if (rule && rule.category !== "requirement") continue;
+		score -= rule?.category === "requirement" ? rule.weight : UNKNOWN_WEIGHT;
+	}
+	return Math.max(0, score);
+}
+/**
+* Weighted average of the per-entry scores.
+*
+* A sensitive handler counts double: the weights say which entry points the
+* number should follow.
+*
+* Exempt entries are left out entirely. Every rule is `n/a` for them, so they
+* score a free 100, and averaging those in would let a project of health checks
+* report a high score while its real handlers are dark.
+*/
+function scoreGlobal(routes) {
+	const scored = routes.filter((route) => !isExemptRoute(route));
+	if (scored.length === 0) return 100;
+	let totalWeight = 0;
+	let weightedSum = 0;
+	for (const route of scored) {
+		const weight = route.sensitivity.level === "high" ? 2 : 1;
+		totalWeight += weight;
+		weightedSum += route.score * weight;
+	}
+	return Math.round(weightedSum / totalWeight);
+}
+/** Grade band a score falls into, at 90 / 70 / 50. */
+function gradeFromScore(score) {
+	if (score >= 90) return "excellent";
+	if (score >= 70) return "good";
+	if (score >= 50) return "needs-work";
+	return "at-risk";
+}
+/**
+* How much of an entry point the map can actually see.
+*
+* `exempt` covers entry points with nothing to instrument; it is not part of
+* the unobserved tally, because it is not a gap anyone should close.
+*/
+function classifyRouteObservability(route) {
+	if (isExemptRoute(route)) return "exempt";
+	if (route.kind === "page") {
+		const applicable = Object.values(route.checks).filter((check) => check?.status !== "n/a");
+		if (applicable.length === 0) return "exempt";
+		const passed = applicable.filter((check) => check?.status === "pass").length;
+		if (passed === applicable.length) return "instrumented";
+		if (passed > 0) return "partial";
+		return "dark";
+	}
+	const span = route.checks["trace"]?.status === "pass";
+	const context = route.checks["context"]?.status === "pass";
+	if (span && context) return "instrumented";
+	if (span || context) return "partial";
+	return "dark";
+}
+/** The one line to show next to an entry point: its heaviest unmet requirement. */
+function topIssue(route) {
+	let heaviest;
+	for (const rule of REQUIREMENTS) if (route.checks[rule.id]?.status === "fail" && (!heaviest || rule.weight > heaviest.weight)) heaviest = rule;
+	return heaviest ? route.checks[heaviest.id]?.message ?? heaviest.id : "ok";
+}
+//#endregion
+//#region src/lib/map/baseline.ts
+/** Committed alongside the code, so the score can be tracked over time. */
+const MAP_FILE_NAME = "autotel.map.json";
+function writeMapFile(projectRoot, map) {
+	const target = path$1.join(projectRoot, MAP_FILE_NAME);
+	atomicWrite(target, `${JSON.stringify(map, null, 2)}\n`, { root: projectRoot });
+	return target;
+}
+function baselineError(source, reason) {
+	return new AutotelError({
+		type: "validation",
+		code: AutotelErrorCodes.E_INVALID_INPUT,
+		message: `Baseline "${source}" ${reason}`,
+		fix: `Run "autotel map" on the baseline commit and commit ${MAP_FILE_NAME}, or pass --baseline git:<ref>.`
+	});
+}
+function readGitBaseline(cwd, ref) {
+	try {
+		return execFileSync("git", [
+			"-C",
+			cwd,
+			"show",
+			`${ref}:${execFileSync("git", [
+				"-C",
+				cwd,
+				"rev-parse",
+				"--show-prefix"
+			], {
+				encoding: "utf8",
+				stdio: [
+					"ignore",
+					"pipe",
+					"ignore"
+				]
+			}).trim()}${MAP_FILE_NAME}`
+		], {
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			],
+			maxBuffer: 64 * 1024 * 1024
+		});
+	} catch {
+		return null;
+	}
+}
+function parseMapFile(raw, label) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		throw baselineError(label, "is not valid JSON");
+	}
+	const map = parsed;
+	if (map?.version !== 1 || !Array.isArray(map.routes) || typeof map.score !== "number") throw baselineError(label, `is not an ${MAP_FILE_NAME} (version 1)`);
+	return map;
+}
+/**
+* Read the map to compare against. Local-only: no network, no token, no
+* repository access, so a private repo gates like a public one.
+*
+* @param spec `git:<ref>` to read the committed copy through git, otherwise a
+* path. Defaults to `autotel.map.json`, falling back to `git:HEAD`.
+*/
+function loadBaseline(projectRoot, spec) {
+	if (spec?.startsWith("git:")) {
+		const raw = readGitBaseline(projectRoot, spec.slice(4) || "HEAD");
+		if (raw === null) throw baselineError(spec, "could not be read");
+		return {
+			map: parseMapFile(raw, spec),
+			source: {
+				kind: "git",
+				label: spec
+			}
+		};
+	}
+	if (spec) {
+		const target = path$1.isAbsolute(spec) ? spec : path$1.resolve(projectRoot, spec);
+		let raw;
+		try {
+			raw = fs.readFileSync(target, "utf8");
+		} catch {
+			throw baselineError(spec, "could not be read");
+		}
+		return {
+			map: parseMapFile(raw, spec),
+			source: {
+				kind: "file",
+				label: spec
+			}
+		};
+	}
+	let raw;
+	try {
+		raw = fs.readFileSync(path$1.resolve(projectRoot, MAP_FILE_NAME), "utf8");
+	} catch (error) {
+		if (error.code !== "ENOENT") throw baselineError(MAP_FILE_NAME, "could not be read");
+		const gitRaw = readGitBaseline(projectRoot, "HEAD");
+		if (gitRaw === null) throw baselineError(MAP_FILE_NAME, "could not be read");
+		return {
+			map: parseMapFile(gitRaw, "git:HEAD"),
+			source: {
+				kind: "git",
+				label: "git:HEAD"
+			}
+		};
+	}
+	return {
+		map: parseMapFile(raw, MAP_FILE_NAME),
+		source: {
+			kind: "file",
+			label: MAP_FILE_NAME
+		}
+	};
+}
+/**
+* Compare a fresh scan against a baseline, per entry point and per check.
+*
+* The unit is the requirement, not the score: a refactor that instruments one
+* route and breaks another leaves the number untouched. A deleted route is not
+* a regression, and a new dark one is reported but does not gate — that bar is
+* `--min-score`'s job.
+*/
+function compareToBaseline(baseline, current, source) {
+	const currentById = new Map(current.routes.map((route) => [route.id, route]));
+	const baselineById = new Map(baseline.routes.map((route) => [route.id, route]));
+	const regressions = [];
+	const fixed = [];
+	const removed = [];
+	for (const before of baseline.routes) {
+		const after = currentById.get(before.id);
+		if (!after) {
+			removed.push({
+				path: before.path,
+				method: before.method
+			});
+			continue;
+		}
+		for (const id of Object.keys(before.checks)) {
+			const was = before.checks[id];
+			const now = after.checks[id];
+			if (!was || !now) continue;
+			const entry = {
+				routeId: after.id,
+				path: after.path,
+				method: after.method,
+				file: after.file,
+				check: id
+			};
+			if (was.status === "pass" && now.status === "fail") regressions.push({
+				...entry,
+				to: "fail"
+			});
+			else if (was.status === "pass" && now.status === "n/a" && now.suppressed) regressions.push({
+				...entry,
+				to: "suppressed"
+			});
+			else if (was.status === "fail" && now.status === "pass") fixed.push(entry);
+		}
+	}
+	const added = current.routes.filter((route) => !baselineById.has(route.id)).map((route) => ({
+		path: route.path,
+		method: route.method,
+		file: route.file,
+		dark: classifyRouteObservability(route) === "dark"
+	}));
+	const carried = current.routes.filter((route) => baselineById.has(route.id));
+	const carriedBefore = baseline.routes.filter((route) => currentById.has(route.id));
+	return {
+		source,
+		baselineScore: baseline.score,
+		score: current.score,
+		delta: scoreGlobal(carried) - scoreGlobal(carriedBefore),
+		totalDelta: current.score - baseline.score,
+		regressions,
+		fixed,
+		added,
+		removed
+	};
+}
+/** Whether the comparison should fail the command (exit 1). */
+function hasRegressed(comparison) {
+	return comparison.regressions.length > 0 || comparison.delta < 0;
+}
+//#endregion
+//#region src/lib/map/project-facts.ts
+const LLM_PACKAGES = [
+	"openai",
+	"@anthropic-ai/sdk",
+	"ai",
+	"@ai-sdk/openai",
+	"@ai-sdk/anthropic",
+	"@ai-sdk/google",
+	"ai-sdk-ollama",
+	"ollama",
+	"@google/generative-ai",
+	"@mistralai/mistralai",
+	"cohere-ai",
+	"langchain",
+	"@langchain/core"
+];
+const RUNTIME_AUTOTEL_PACKAGES = [
+	"autotel",
+	"autotel-edge",
+	"autotel-cloudflare",
+	"autotel-nuxt",
+	"autotel-tanstack",
+	"autotel-hono",
+	"autotel-adapters"
+];
+/**
+* Files where a framework integration is wired up.
+*
+* Kept to a fixed list rather than a glob: this answers "did anyone install the
+* middleware", and the answer is always in the app's entry file or its hooks.
+*/
+const WIRING_FILES = [
+	"src/index.ts",
+	"src/app.ts",
+	"src/server.ts",
+	"src/main.ts",
+	"index.ts",
+	"app.ts",
+	"server.ts",
+	"middleware.ts",
+	"src/middleware.ts",
+	"src/hooks.server.ts",
+	"hooks.server.ts",
+	"nuxt.config.ts",
+	"src/router.tsx",
+	"app/router.tsx"
+];
+/** Autotel framework integrations that create a request span when called. */
+const AMBIENT_APIS = ["autotelMiddleware", "autotelHandle"];
+function hasAmbientTracing(projectRoot, instrumentationPath) {
+	const parse = createParser();
+	const candidates = new Set([instrumentationPath, ...WIRING_FILES.map((file) => path$1.join(projectRoot, file))].filter((file) => file !== null && fileExists(file)));
+	for (const file of candidates) {
+		const source = parse(file);
+		if (source && usesAutotelApi$1(buildFileFacts(source), AMBIENT_APIS)) return true;
+	}
+	return false;
+}
+function projectSource(projectRoot) {
+	const files = globSync("{src,app,server,routes,pages}/**/*.{ts,tsx,js,jsx,mts,mjs}", {
+		cwd: projectRoot,
+		absolute: true,
+		ignore: [
+			"**/node_modules/**",
+			"**/dist/**",
+			"**/*.test.*",
+			"**/*.spec.*"
+		]
+	});
+	const occurrences = /* @__PURE__ */ new Map();
+	const chunks = [];
+	const call = /createStructuredError\s*\(\s*\{([\s\S]*?)\}\s*\)/g;
+	for (const file of files) {
+		const source = readFileSafe(file) ?? "";
+		chunks.push(source);
+		for (const match of source.matchAll(call)) {
+			const body = match[1] ?? "";
+			const message = /\bmessage\s*:\s*(['"`])([\s\S]*?)\1/.exec(body)?.[2];
+			const status = /\bstatus\s*:\s*(\d+)/.exec(body)?.[1];
+			if (!message || !status) continue;
+			const signature = `${status}|${message}`;
+			const entry = occurrences.get(signature) ?? {
+				label: message,
+				files: /* @__PURE__ */ new Set()
+			};
+			entry.files.add(path$1.relative(projectRoot, file).split(path$1.sep).join("/"));
+			occurrences.set(signature, entry);
+		}
+	}
+	return {
+		text: chunks.join("\n"),
+		repeatedErrors: new Map([...occurrences].filter(([, entry]) => entry.files.size > 1).map(([signature, entry]) => [signature, {
+			label: entry.label,
+			files: [...entry.files].toSorted()
+		}]))
+	};
+}
+function collectDeps(pkg) {
+	return /* @__PURE__ */ new Set([...Object.keys(pkg?.dependencies ?? {}), ...Object.keys(pkg?.devDependencies ?? {})]);
+}
+function collectProjectFacts(projectRoot) {
+	const pkg = readJsonSafe(path$1.join(projectRoot, "package.json"));
+	const deps = collectDeps(pkg);
+	const instrumentation = findInstrumentationFile(projectRoot);
+	const instrumentationText = instrumentation ? readFileSafe(instrumentation.path) ?? "" : "";
+	const ambientText = `${instrumentationText}\n${WIRING_FILES.map((candidate) => fileExists(path$1.join(projectRoot, candidate)) ? readFileSafe(path$1.join(projectRoot, candidate)) ?? "" : "").join("\n")}`;
+	const source = projectSource(projectRoot);
+	const projectSignalText = `${ambientText}\n${source.text}`;
+	return {
+		name: pkg?.name ?? path$1.basename(projectRoot),
+		deps,
+		hasAutotel: RUNTIME_AUTOTEL_PACKAGES.some((name) => deps.has(name)),
+		ambientTracing: deps.has("autotel-nuxt") || hasAmbientTracing(projectRoot, instrumentation?.path ?? null),
+		hasRedaction: instrumentationText.includes("attributeRedactor"),
+		instrumentationFile: instrumentation ? path$1.relative(projectRoot, instrumentation.path).split(path$1.sep).join("/") : null,
+		hasLlmDependency: LLM_PACKAGES.some((name) => deps.has(name)),
+		hasZod: deps.has("zod"),
+		hasAuditUsage: deps.has("autotel-audit") && /securityEvent|withSecurity|withAudit|defineAuditCatalog/.test(projectSignalText),
+		hasErrorCatalog: projectSignalText.includes("defineErrorCatalog"),
+		repeatedErrors: source.repeatedErrors
+	};
+}
+//#endregion
+//#region src/lib/map/sensitivity.ts
+const MONEY_PACKAGES = [
+	"stripe",
+	"@stripe/stripe-js",
+	"@paddle/paddle-node-sdk",
+	"@lemonsqueezy/lemonsqueezy.js",
+	"braintree"
+];
+const AUTH_PACKAGES = [
+	"better-auth",
+	"next-auth",
+	"lucia",
+	"@auth/core",
+	"@clerk/nextjs",
+	"@clerk/backend",
+	"passport"
+];
+const MONEY_TERMS = [
+	"checkout",
+	"payment",
+	"billing",
+	"invoice",
+	"refund",
+	"subscription",
+	"charge",
+	"payout",
+	"order"
+];
+const AUTH_TERMS = [
+	"auth",
+	"oauth",
+	"login",
+	"logout",
+	"signin",
+	"signup",
+	"register",
+	"password",
+	"token",
+	"session",
+	"mfa",
+	"otp",
+	"admin"
+];
+/**
+* Whole-word matcher per term, allowing a plural.
+*
+* Anchoring matters more than it looks: with plain substrings `/api/authors`
+* reads as authentication. A route wrongly marked sensitive is handed a
+* 25-point audit requirement it has no reason to satisfy, and counts double in
+* the global score — the fastest way to make the number untrustworthy.
+*/
+function compileTerms(terms) {
+	return terms.map((term) => [term, new RegExp(`(?:^|[^a-z0-9])${term}s?(?:[^a-z0-9]|$)`, "i")]);
+}
+const MONEY_PATTERNS = compileTerms(MONEY_TERMS);
+const AUTH_PATTERNS = compileTerms(AUTH_TERMS);
+function matchTerm(value, patterns) {
+	for (const [term, pattern] of patterns) if (pattern.test(value)) return term;
+	return null;
+}
+const PII_FIELDS = /email|phone|address|ssn|iban|dateOfBirth|passport/i;
+const WRITE_CALLS = /* @__PURE__ */ new Set([
+	"create",
+	"update",
+	"insert",
+	"upsert",
+	"delete"
+]);
+function importsPackage(facts, pkg) {
+	for (const specifier of facts.modules) if (specifier === pkg || specifier.startsWith(`${pkg}/`)) return true;
+	return false;
+}
+/**
+* Classify an entry point as money / auth / PII sensitive.
+*
+* Reads resolved imports and the identifiers actually in the AST rather than
+* searching raw source: substring matching cannot tell an import from a
+* comment, so a `// TODO: drop stripe` would be enough to mark a route as
+* handling money.
+*/
+function classifySensitivity(route, facts) {
+	const reasons = [];
+	for (const pkg of MONEY_PACKAGES) if (importsPackage(facts, pkg)) reasons.push(`money: imports ${pkg}`);
+	const moneyTerm = matchTerm(route.path, MONEY_PATTERNS);
+	if (moneyTerm) reasons.push(`money: path says "${moneyTerm}"`);
+	for (const pkg of AUTH_PACKAGES) if (importsPackage(facts, pkg)) reasons.push(`auth: imports ${pkg}`);
+	const authTerm = matchTerm(route.path, AUTH_PATTERNS);
+	if (authTerm) reasons.push(`auth: path says "${authTerm}"`);
+	const touchesPii = [...facts.names].some((name) => PII_FIELDS.test(name));
+	const writes = facts.calls.some((call) => WRITE_CALLS.has(call.member.toLowerCase()));
+	if (touchesPii && writes) reasons.push("pii: write operation with sensitive fields");
+	const hasMoney = reasons.some((reason) => reason.startsWith("money:"));
+	const hasAuth = reasons.some((reason) => reason.startsWith("auth:"));
+	const hasPii = reasons.some((reason) => reason.startsWith("pii:"));
+	if (hasMoney || hasAuth) return {
+		level: "high",
+		reasons
+	};
+	if (hasPii) return {
+		level: "medium",
+		reasons
+	};
+	return {
+		level: "none",
+		reasons: []
+	};
+}
+/** What makes this entry point sensitive — `money`, `auth`, `pii`, or nothing. */
+function sensitivityLabel(sensitivity) {
+	if (sensitivity.reasons.some((r) => r.startsWith("money:"))) return "money";
+	if (sensitivity.reasons.some((r) => r.startsWith("auth:"))) return "auth";
+	if (sensitivity.level === "medium") return "pii";
+	return "";
+}
+//#endregion
+//#region src/lib/map/report.ts
+const GRADE_COLOUR = {
+	excellent: chalk.green,
+	good: chalk.green,
+	"needs-work": chalk.yellow,
+	"at-risk": chalk.red
+};
+/** Entry-point label without colour — the one width calculations can trust. */
+function plainLabel(route) {
+	const method = route.method ? `${route.method} ` : "";
+	const badge = sensitivityLabel(route.sensitivity);
+	return `${method}${route.path}${badge ? ` [${badge}]` : ""}`;
+}
+function label(route) {
+	const method = route.method ? `${route.method} ` : "";
+	const badge = sensitivityLabel(route.sensitivity);
+	return `${method}${route.path}${badge ? chalk.magenta(` [${badge}]`) : ""}`;
+}
+/** Points this entry point is losing, weighted the way the global score weighs it. */
+function lostPoints(route) {
+	const weight = route.sensitivity.level === "high" ? 2 : 1;
+	return (100 - route.score) * weight;
+}
+/**
+* The default view: the number, the tally, and the three entry points worth
+* fixing first.
+*
+* Three rather than all of them on purpose — a list of forty gaps is a list
+* nobody starts. `--all` is one keystroke away when the whole picture is wanted.
+*/
+function formatReport(result, options = {}) {
+	const { map, summary, grade } = result;
+	const lines = [];
+	const colour = GRADE_COLOUR[grade];
+	lines.push("");
+	lines.push(chalk.bold(`Observability map — ${map.projectName} (${map.framework})`));
+	lines.push("");
+	lines.push(`  ${colour(chalk.bold(`${map.score}/100`))}  ${colour(grade)}`);
+	lines.push(chalk.dim(`  ${map.routes.length} entry point${map.routes.length === 1 ? "" : "s"} · ${summary.instrumented} instrumented · ${summary.partial} partial · ${summary.dark} dark · ${summary.exempt} exempt` + (summary.suppressedChecks > 0 ? ` · ${summary.suppressedChecks} suppressed` : "")));
+	const worst = map.routes.filter((route) => classifyRouteObservability(route) !== "exempt" && route.score < 100).toSorted((a, b) => lostPoints(b) - lostPoints(a)).slice(0, 3);
+	if (worst.length > 0) {
+		lines.push("");
+		lines.push(chalk.bold("Fix these first"));
+		for (const [index, route] of worst.entries()) {
+			lines.push(`  ${index + 1}. ${label(route)}`);
+			lines.push(`     ${chalk.yellow(topIssue(route))}`);
+			lines.push(chalk.dim(`     ${route.file}${route.handler ? `:${route.handler.line}` : ""}  (${route.score}/100)`));
+		}
+	}
+	const perRoute = map.routes.flatMap((route) => Object.entries(route.suggestions).filter(([, check]) => check?.status === "fail").map(([, check]) => `${label(route)} — ${check?.message ?? ""}`));
+	const suggestions = [...result.suggestions.map((suggestion) => suggestion.message), ...perRoute.slice(0, 3)];
+	if (suggestions.length > 0) {
+		lines.push("");
+		lines.push(chalk.bold("Suggestions"));
+		for (const suggestion of suggestions) lines.push(chalk.dim(`  · ${suggestion}`));
+	}
+	lines.push("");
+	if (options.mapPath) lines.push(chalk.dim(`Wrote ${options.mapPath}`));
+	lines.push(chalk.cyan("Next: autotel map --all  ·  autotel map <route|file>  ·  autotel map --json"));
+	return lines.join("\n");
+}
+/** Every entry point as a check matrix — one column per requirement. */
+function formatMatrix(result) {
+	const lines = [""];
+	const columns = REQUIREMENTS.map((rule) => rule.id);
+	const headers = REQUIREMENTS.map((rule) => rule.title);
+	const nameWidth = Math.max(20, ...result.map.routes.map((route) => plainLabel(route).length));
+	lines.push(chalk.bold(`${"entry point".padEnd(nameWidth)}  ${headers.map((header) => header.padEnd(8)).join("")}score`));
+	for (const route of result.map.routes) {
+		const padding = " ".repeat(Math.max(0, nameWidth - plainLabel(route).length));
+		const cells = columns.map((id) => mark(route.checks[id]?.status).padEnd(8)).join("");
+		lines.push(`${label(route)}${padding}  ${cells}${route.score}`);
+	}
+	lines.push("");
+	lines.push(chalk.dim("✓ pass   ✗ fail   – not applicable"));
+	return lines.join("\n");
+}
+function mark(status) {
+	if (status === "pass") return chalk.green("✓");
+	if (status === "fail") return chalk.red("✗");
+	return chalk.dim("–");
+}
+/** Find an entry point by route path or file path. */
+function findEntry(result, query) {
+	const needle = query.toLowerCase();
+	return result.map.routes.find((route) => route.file.toLowerCase() === needle) ?? result.map.routes.find((route) => route.path.toLowerCase() === needle) ?? result.map.routes.find((route) => route.file.toLowerCase().includes(needle) || route.path.toLowerCase().includes(needle));
+}
+/** One entry point in full: every rule, its verdict, and the code that fixes it. */
+function formatInspect(route) {
+	const lines = [
+		"",
+		chalk.bold(label(route)),
+		chalk.dim(`${route.file}${route.handler ? `:${route.handler.line}` : ""} · ${route.kind} · ${route.score}/100`)
+	];
+	if (route.sensitivity.reasons.length > 0) lines.push(chalk.magenta(`sensitive: ${route.sensitivity.reasons.join(", ")}`));
+	lines.push("");
+	for (const rule of RULES) {
+		const result = route.checks[rule.id] ?? route.suggestions[rule.id];
+		if (!result) continue;
+		if (result.status === "n/a" && !result.suppressed) continue;
+		const kind = rule.category === "requirement" ? "" : chalk.dim(" (suggestion)");
+		lines.push(`${mark(result.status)} ${chalk.bold(rule.title)}${kind}`);
+		lines.push(`  ${chalk.dim(rule.question)}`);
+		if (result.message) lines.push(`  ${result.message}`);
+		if (result.evidence?.snippet) lines.push(chalk.dim(`  ${result.evidence.line}| ${result.evidence.snippet}`));
+		if (result.status === "fail" && result.fix) lines.push(chalk.cyan(`  → ${result.fix}`));
+		lines.push("");
+	}
+	return lines.join("\n");
+}
+function formatEntryNotFound(result, query) {
+	const known = result.map.routes.slice(0, 10).map((route) => `  ${label(route)}  ${chalk.dim(route.file)}`);
+	return [
+		"",
+		chalk.yellow(`No entry point matches "${query}".`),
+		"",
+		chalk.dim("Known entry points:"),
+		...known
+	].join("\n");
+}
+function formatWarnings(warnings) {
+	return ["", ...warnings.map((warning) => chalk.yellow(`! ${warning}`))].join("\n");
+}
+function formatBaseline(comparison) {
+	const lines = ["", chalk.bold(`Baseline (${comparison.source.label})`)];
+	const sign = comparison.totalDelta >= 0 ? "+" : "";
+	lines.push(`  ${comparison.baselineScore} → ${comparison.score} (${sign}${comparison.totalDelta})`);
+	for (const regression of comparison.regressions) {
+		const rule = getRule(regression.check);
+		lines.push(chalk.red(`  ✗ ${regression.method ?? ""} ${regression.path} — "${rule?.title ?? regression.check}" now ${regression.to}`));
+		lines.push(chalk.dim(`    ${regression.file}`));
+	}
+	for (const fix of comparison.fixed) {
+		const rule = getRule(fix.check);
+		lines.push(chalk.green(`  ✓ ${fix.method ?? ""} ${fix.path} — "${rule?.title ?? fix.check}" fixed`));
+	}
+	const darkAdded = comparison.added.filter((route) => route.dark);
+	if (darkAdded.length > 0) {
+		lines.push(chalk.yellow(`  ${darkAdded.length} new entry point${darkAdded.length === 1 ? "" : "s"} with no instrumentation`));
+		for (const route of darkAdded) lines.push(chalk.dim(`    ${route.method ?? ""} ${route.path} (${route.file})`));
+	}
+	if (comparison.removed.length > 0) lines.push(chalk.dim(`  ${comparison.removed.length} entry point(s) removed`));
+	return lines.join("\n");
+}
+function formatGate(score, threshold) {
+	return score < threshold ? chalk.red(`\nScore ${score} is below --min-score ${threshold}.`) : chalk.green(`\nScore ${score} meets --min-score ${threshold}.`);
+}
+//#endregion
+//#region src/lib/map/scan.ts
+/** Stable identity for an entry point, so a baseline can match it across runs. */
+function routeId(route) {
+	return `${route.method ?? "*"} ${route.path} (${route.file})`;
+}
+/** Find entry points for `framework`, run the rules against each, and score them. */
+function scan(options) {
+	const { projectRoot, framework } = options;
+	const parse = createParser();
+	const project = options.project ?? collectProjectFacts(projectRoot);
+	const adapter = getAdapter(framework);
+	const warnings = [];
+	const routes = [];
+	const factsCache = /* @__PURE__ */ new Map();
+	for (const raw of adapter.extractRoutes({
+		projectRoot,
+		parse
+	})) {
+		const source = parse(path$1.join(projectRoot, raw.file));
+		let facts = null;
+		if (source) {
+			const scope = adapter.scopesFor?.(raw, source);
+			if (scope) facts = buildFileFacts(source, scope);
+			else {
+				const cached = factsCache.get(raw.file);
+				facts = cached ?? buildFileFacts(source);
+				if (!cached) factsCache.set(raw.file, facts);
+			}
+		}
+		const sensitivity = facts !== null ? classifySensitivity(raw, facts) : {
+			level: "none",
+			reasons: []
+		};
+		const target = {
+			...raw,
+			sensitivity
+		};
+		const results = source !== null && facts !== null ? runRules({
+			target,
+			facts,
+			project,
+			autoImports: adapter.autoImports,
+			source
+		}) : unreadableResults(target);
+		warnings.push(...results.warnings);
+		routes.push({
+			...raw,
+			id: routeId(raw),
+			checks: results.checks,
+			suggestions: results.suggestions,
+			sensitivity,
+			score: scoreRoute(results.checks)
+		});
+	}
+	const suggestions = hoistProjectSuggestions(routes);
+	const score = scoreGlobal(routes);
+	const summary = {
+		instrumented: 0,
+		partial: 0,
+		dark: 0,
+		exempt: 0,
+		suppressedChecks: 0
+	};
+	for (const route of routes) {
+		summary[classifyRouteObservability(route)]++;
+		summary.suppressedChecks += countSuppressed(route);
+	}
+	return {
+		map: {
+			version: 1,
+			generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			framework,
+			projectName: project.name,
+			score,
+			routes
+		},
+		grade: gradeFromScore(score),
+		suggestions,
+		warnings: [...new Set(warnings)],
+		summary
+	};
+}
+/**
+* Move project-scoped suggestions off the routes and into one list.
+*
+* Setting `attributeRedactor` is a single edit, so leaving a copy on every
+* entry point where PII is in play would make the report claim there are five
+* things to do. The first entry point that raised it keeps the evidence, which
+* is where the reader should look first.
+*/
+function hoistProjectSuggestions(routes) {
+	const hoisted = /* @__PURE__ */ new Map();
+	for (const route of routes) for (const [id, result] of Object.entries(route.suggestions)) {
+		const rule = getRule(id);
+		if (rule?.category !== "opportunity" || rule.scope !== "project") continue;
+		delete route.suggestions[id];
+		if (hoisted.has(id) || result.status !== "fail") continue;
+		hoisted.set(id, {
+			id,
+			message: result.message ?? rule.question,
+			...result.evidence ? { evidence: result.evidence } : {}
+		});
+	}
+	return [...hoisted.values()];
+}
+//#endregion
+//#region src/commands/map.ts
+/**
+* Read `--min-score`, rejecting anything that is not a whole 0-100.
+*
+* The whole string has to parse: `parseInt` reads `80oops` as 80 and `abc` as
+* nothing at all, and a threshold that quietly becomes `undefined` turns the
+* gate off — CI then reports success for a bar it never checked.
+*/
+function parseMinScore(value) {
+	if (value === void 0 || value === "") return void 0;
+	const threshold = Number(value);
+	if (!Number.isInteger(threshold) || threshold < 0 || threshold > 100) throw new AutotelError({
+		type: "validation",
+		code: AutotelErrorCodes.E_INVALID_FLAG,
+		message: `--min-score expects a whole number from 0 to 100, got "${value}"`,
+		fix: "Pass e.g. --min-score 70"
+	});
+	return threshold;
+}
+function resolveFramework(requested, projectRoot, deps) {
+	if (requested !== void 0 && requested !== "") {
+		if (!isFramework(requested)) throw new AutotelError({
+			type: "validation",
+			code: AutotelErrorCodes.E_INVALID_FLAG,
+			message: `Unknown framework "${requested}"`,
+			fix: `Use one of: ${SUPPORTED_FRAMEWORKS.join(", ")}`,
+			expected: { frameworks: [...SUPPORTED_FRAMEWORKS] }
+		});
+		return {
+			framework: requested,
+			warnings: []
+		};
+	}
+	const detected = detectFramework(projectRoot, deps);
+	if (!detected.framework) throw new AutotelError({
+		type: "environment",
+		code: AutotelErrorCodes.E_INVALID_INPUT,
+		message: "Could not detect a supported framework in this project",
+		fix: `Pass --framework <name>. Supported: ${SUPPORTED_FRAMEWORKS.join(", ")}`,
+		expected: { frameworks: [...SUPPORTED_FRAMEWORKS] }
+	});
+	return {
+		framework: detected.framework,
+		warnings: detected.warnings
+	};
+}
+/**
+* Scan the project for entry points and score their observability.
+*
+* Pure with respect to the filesystem except for the `autotel.map.json` write.
+*/
+function runMapScan(options) {
+	const project = discoverProject(options.cwd);
+	if (!project) throw new AutotelError({
+		type: "environment",
+		code: AutotelErrorCodes.E_NO_PACKAGE_JSON,
+		message: `No package.json found from ${options.cwd}`,
+		fix: "Run autotel map from inside a package, or pass --cwd <path>."
+	});
+	const projectRoot = options.workspaceRoot ? project.workspace.workspaceRoot ?? project.packageRoot : project.packageRoot;
+	const facts = collectProjectFacts(projectRoot);
+	const { framework, warnings } = resolveFramework(options.framework, projectRoot, facts.deps);
+	const baselineMap = options.baseline ? loadBaseline(projectRoot, typeof options.baseline === "string" ? options.baseline : void 0) : null;
+	const result = scan({
+		projectRoot,
+		framework,
+		project: facts
+	});
+	const baseline = baselineMap ? compareToBaseline(baselineMap.map, result.map, baselineMap.source) : null;
+	const wouldClobberBaseline = baseline !== null && hasRegressed(baseline);
+	return {
+		projectRoot,
+		framework,
+		frameworkWarnings: warnings,
+		scan: result,
+		mapPath: options.write && !wouldClobberBaseline ? writeMapFile(projectRoot, result.map) : null,
+		baseline
+	};
+}
+/**
+* Pick the view for the flags that were passed.
+*
+* The three views answer three different questions — "how am I doing", "show
+* me everything", "explain this one file" — so they are separate renderers
+* rather than one renderer with three modes.
+*/
+function formatMapResult(result, options) {
+	const sections = [];
+	const warnings = [...result.frameworkWarnings, ...result.scan.warnings];
+	if (warnings.length > 0) sections.push(formatWarnings(warnings));
+	if (options.entry) {
+		const route = findEntry(result.scan, options.entry);
+		sections.push(route ? formatInspect(route) : formatEntryNotFound(result.scan, options.entry));
+	} else if (options.all) sections.push(formatMatrix(result.scan));
+	else sections.push(formatReport(result.scan, { mapPath: result.mapPath }));
+	if (result.baseline) sections.push(formatBaseline(result.baseline));
+	if (options.minScore !== void 0) sections.push(formatGate(result.scan.map.score, options.minScore));
+	return sections.join("\n");
+}
+/** `autotel map` — static observability map of every entry point. */
+function runMap(options) {
+	configureJsonOutput({
+		...options.outputFile !== void 0 ? { outputFile: options.outputFile } : {},
+		outputRoot: options.cwd
+	});
+	const minScore = parseMinScore(options.minScore);
+	const result = runMapScan(options);
+	if (options.json) printJson({
+		ok: true,
+		command: "map",
+		mapFile: MAP_FILE_NAME,
+		mapPath: result.mapPath,
+		framework: result.framework,
+		grade: result.scan.grade,
+		summary: result.scan.summary,
+		suggestions: result.scan.suggestions,
+		warnings: [...result.frameworkWarnings, ...result.scan.warnings],
+		...result.baseline ? { baseline: result.baseline } : {},
+		map: result.scan.map
+	});
+	else process.stdout.write(`${formatMapResult(result, {
+		all: options.all,
+		...options.entry !== void 0 ? { entry: options.entry } : {},
+		...minScore !== void 0 ? { minScore } : {}
+	})}\n`);
+	if (minScore !== void 0 && result.scan.map.score < minScore) {
+		process.exitCode = 1;
+		return;
+	}
+	if (result.baseline && hasRegressed(result.baseline)) process.exitCode = 1;
+}
+//#endregion
 //#region src/lib/codemod-trace.ts
 const TRACE_IMPORT_MODULE = "autotel";
 function hasTraceImport(sourceFile) {
@@ -4382,6 +6634,75 @@ const COMMANDS = [
 		mayReadEnv: false,
 		supportsJson: true
 	},
+	{
+		name: "map",
+		description: "Score the observability of every entry point in your project (static analysis)",
+		args: [{
+			name: "entry",
+			required: false,
+			description: "Inspect one entry point by route or file path"
+		}],
+		flags: [
+			...GLOBAL_FLAGS,
+			...AGENT_FLAGS,
+			{
+				name: "--framework",
+				takesValue: true,
+				description: "Override framework detection (next, nitro, tanstack-start, sveltekit, hono, express, fastify, elysia, cloudflare)"
+			},
+			{
+				name: "--all",
+				description: "Show every entry point as a check matrix"
+			},
+			{
+				name: "--min-score",
+				takesValue: true,
+				description: "Exit 1 when the global score is below this threshold"
+			},
+			{
+				name: "--baseline",
+				takesValue: true,
+				description: "Compare against a committed autotel.map.json and exit 1 on regression (path, or git:<ref>)"
+			},
+			{
+				name: "--no-write",
+				description: "Skip writing autotel.map.json"
+			},
+			{
+				name: "--workspace-root",
+				description: "Scan from the workspace root"
+			}
+		],
+		mutating: false,
+		network: false,
+		writesFiles: true,
+		supportsDryRun: false,
+		requiresPackageJson: true,
+		mayReadEnv: false,
+		supportsJson: true,
+		examples: [
+			{
+				description: "Score this project and write autotel.map.json",
+				command: "autotel map"
+			},
+			{
+				description: "Every entry point, as a check matrix",
+				command: "autotel map --all"
+			},
+			{
+				description: "Explain one entry point and how to fix it",
+				command: "autotel map app/api/checkout/route.ts"
+			},
+			{
+				description: "Gate CI on a minimum score",
+				command: "autotel map --min-score 70 --json"
+			},
+			{
+				description: "Fail the build when a check regresses against main",
+				command: "autotel map --baseline git:origin/main"
+			}
+		]
+	},
 	{
 		name: "codemod trace",
 		description: "Wrap functions in trace() with span name from function/variable/method name",
@@ -4892,6 +7213,11 @@ const ERROR_CATALOGUE = [
 		type: "io",
 		description: "Failed to read a file"
 	},
+	{
+		code: AutotelErrorCodes.E_RATE_LIMITED,
+		type: "runtime",
+		description: "Backend rate limit outlasted the retry budget — wait and retry"
+	},
 	{
 		code: AutotelErrorCodes.E_UNKNOWN,
 		type: "runtime",
@@ -5058,6 +7384,9 @@ function applyFlagsToEnv(flags) {
 	if (flags.lokiBaseUrl !== void 0) process.env.LOKI_BASE_URL = flags.lokiBaseUrl;
 	if (flags.collectorPort !== void 0) process.env.AUTOTEL_COLLECTOR_PORT = String(flags.collectorPort);
 	if (flags.fixturePath !== void 0) process.env.AUTOTEL_FIXTURE_PATH = flags.fixturePath;
+	if (flags.logfireBaseUrl !== void 0) process.env.LOGFIRE_BASE_URL = flags.logfireBaseUrl;
+	if (flags.datadogSite !== void 0) process.env.DD_SITE = flags.datadogSite;
+	if (flags.signozBaseUrl !== void 0) process.env.SIGNOZ_BASE_URL = flags.signozBaseUrl;
 }
 /**
 * Build a backend from CLI flags/env. Caller is responsible for calling
@@ -5132,10 +7461,17 @@ function toInvestigateError(command, error) {
 			expected: { issues }
 		});
 	}
+	const message = error instanceof Error ? error.message : String(error);
+	if (/\bHTTP 429\b/.test(message)) return new AutotelError({
+		type: "runtime",
+		code: AutotelErrorCodes.E_RATE_LIMITED,
+		message: `autotel ${command} failed: ${message} — the backend rate limit outlasted the retry budget. Wait for the limit window to reset and run the command again.`,
+		retryable: true
+	});
 	return new AutotelError({
 		type: "runtime",
 		code: "AUTOTEL_E_UNKNOWN",
-		message: `autotel ${command} failed: ${error instanceof Error ? error.message : String(error)}`,
+		message: `autotel ${command} failed: ${message}`,
 		retryable: false
 	});
 }
@@ -5153,7 +7489,7 @@ const floatArg = (v) => Number.parseFloat(v);
 * investigate command. Applied to a Command in place (mutates + returns).
 */
 function addBackendFlags(cmd) {
-	return cmd.option("--backend <kind>", "Backend: collector|jaeger|tempo|prometheus|loki|stack|auto|fixture (env: AUTOTEL_BACKEND)").option("--jaeger-base-url <url>", "Jaeger base URL (env: JAEGER_BASE_URL)").option("--tempo-base-url <url>", "Tempo base URL (env: TEMPO_BASE_URL)").option("--prometheus-base-url <url>", "Prometheus base URL (env: PROMETHEUS_BASE_URL)").option("--loki-base-url <url>", "Loki base URL (env: LOKI_BASE_URL)").option("--collector-port <n>", "OTLP receiver port for the collector backend", intArg).option("--fixture-path <path>", "Fixture JSON for the fixture backend").option("--output-file <path>", "Persist JSON output to this file").option("--no-secrets-in-output", "Redact secret-shaped values");
+	return cmd.option("--backend <kind>", "Backend: collector|jaeger|tempo|prometheus|loki|stack|auto|fixture|logfire|datadog|signoz (env: AUTOTEL_BACKEND)").option("--jaeger-base-url <url>", "Jaeger base URL (env: JAEGER_BASE_URL)").option("--tempo-base-url <url>", "Tempo base URL (env: TEMPO_BASE_URL)").option("--prometheus-base-url <url>", "Prometheus base URL (env: PROMETHEUS_BASE_URL)").option("--loki-base-url <url>", "Loki base URL (env: LOKI_BASE_URL)").option("--collector-port <n>", "OTLP receiver port for the collector backend", intArg).option("--fixture-path <path>", "Fixture JSON for the fixture backend").option("--logfire-base-url <url>", "Logfire region URL (env: LOGFIRE_BASE_URL; token via LOGFIRE_READ_TOKEN)").option("--datadog-site <site>", "Datadog site, e.g. datadoghq.eu, or a full API URL (env: DD_SITE; keys via DD_API_KEY + DD_APP_KEY)").option("--signoz-base-url <url>", "SigNoz base URL (env: SIGNOZ_BASE_URL; key via SIGNOZ_API_KEY)").option("--output-file <path>", "Persist JSON output to this file").option("--no-secrets-in-output", "Redact secret-shaped values");
 }
 /**
 * Smaller flag set for commands that don't need a backend (semconv,
@@ -5171,6 +7507,9 @@ function backendFlagsFromOpts(opts) {
 		lokiBaseUrl: opts.lokiBaseUrl,
 		collectorPort: opts.collectorPort,
 		fixturePath: opts.fixturePath,
+		logfireBaseUrl: opts.logfireBaseUrl,
+		datadogSite: opts.datadogSite,
+		signozBaseUrl: opts.signozBaseUrl,
 		outputFile: opts.outputFile,
 		noSecrets: opts.secretsInOutput === false
 	};
@@ -5198,22 +7537,200 @@ function windowFlagsFromOpts(opts) {
 	};
 }
 //#endregion
+//#region src/commands/investigate/freshness.ts
+const PROBE_SPAN_NAME = "autotel.freshness.probe";
+const PROBE_SCOPE = "autotel-cli/freshness";
+/** Nominal probe span duration; a zero-length span reads oddly in a UI. */
+const PROBE_DURATION_MS = 1;
+function randomHex(bytes) {
+	const out = [];
+	for (let index = 0; index < bytes; index++) out.push(Math.floor(Math.random() * 256).toString(16).padStart(2, "0"));
+	return out.join("");
+}
+/** Epoch ms → OTel's `[seconds, nanoseconds]` pair. */
+function toHrTime(ms) {
+	const seconds = Math.floor(ms / 1e3);
+	return [seconds, Math.round((ms - seconds * 1e3) * 1e6)];
+}
+/** One finished span, ready for either serializer. */
+function buildProbeSpan(service, startMs) {
+	const traceId = randomHex(16);
+	const spanId = randomHex(8);
+	return {
+		name: PROBE_SPAN_NAME,
+		kind: 0,
+		spanContext: () => ({
+			traceId,
+			spanId,
+			traceFlags: 1
+		}),
+		parentSpanContext: void 0,
+		startTime: toHrTime(startMs),
+		endTime: toHrTime(startMs + PROBE_DURATION_MS),
+		duration: toHrTime(PROBE_DURATION_MS),
+		status: { code: 0 },
+		attributes: {},
+		links: [],
+		events: [],
+		ended: true,
+		resource: { attributes: { "service.name": service } },
+		instrumentationScope: { name: PROBE_SCOPE },
+		droppedAttributesCount: 0,
+		droppedEventsCount: 0,
+		droppedLinksCount: 0
+	};
+}
+/** Serialize a probe span into an OTLP request body plus its content type. */
+function encodeProbe(span, encoding) {
+	const spans = [span];
+	return encoding === "json" ? {
+		body: JsonTraceSerializer.serializeRequest(spans) ?? /* @__PURE__ */ new Uint8Array(),
+		contentType: "application/json"
+	} : {
+		body: ProtobufTraceSerializer.serializeRequest(spans) ?? /* @__PURE__ */ new Uint8Array(),
+		contentType: "application/x-protobuf"
+	};
+}
+/**
+* Parse the standard `OTEL_EXPORTER_OTLP_HEADERS` format (`k=v,k2=v2`).
+*
+* Hosted OTLP endpoints all require an auth header, and this is the variable
+* users already set for their exporters — so the probe reads the same one
+* rather than inventing a flag that would put a token in argv.
+*/
+function otlpHeadersFromEnv(raw) {
+	const headers = {};
+	for (const pair of (raw ?? "").split(",")) {
+		const separator = pair.indexOf("=");
+		if (separator <= 0) continue;
+		const key = pair.slice(0, separator).trim();
+		const value = pair.slice(separator + 1).trim();
+		if (key === "") continue;
+		headers[key] = value;
+	}
+	return headers;
+}
+/** POST an OTLP/HTTP trace. Kept separate so tests never touch the network. */
+async function sendOtlpTrace(endpoint, span, headers = {}, encoding = "protobuf") {
+	const url = resolveOtlpTraceUrl(endpoint);
+	const { body, contentType } = encodeProbe(span, encoding);
+	const response = await fetch(url, {
+		method: "POST",
+		headers: {
+			"Content-Type": contentType,
+			...headers
+		},
+		body
+	});
+	if (!response.ok) {
+		const otherEncoding = encoding === "json" ? "protobuf" : "json";
+		throw new Error(`OTLP endpoint ${url} rejected the probe span: ${response.status} ${response.statusText}. Sent ${encoding}; if the receiver wants the other encoding, pass --otlp-encoding ${otherEncoding}.`);
+	}
+}
+/** Resolve an OTLP base endpoint without discarding vendor-specific paths. */
+function resolveOtlpTraceUrl(endpoint) {
+	const url = new URL(endpoint);
+	const basePath = url.pathname.replace(/\/+$/, "");
+	if (!basePath.endsWith("/v1/traces")) url.pathname = `${basePath}/v1/traces`;
+	return url.toString();
+}
+const DEFAULT_TIMEOUT_MS = 12e4;
+const DEFAULT_POLL_INTERVAL_MS = 2e3;
+function defaultSleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+const DEADLINE_REACHED = Symbol("freshness-deadline-reached");
+async function beforeDeadline(promise, remainingMs) {
+	if (remainingMs <= 0) return DEADLINE_REACHED;
+	let timer;
+	try {
+		return await Promise.race([promise, new Promise((resolve) => {
+			timer = setTimeout(() => resolve(DEADLINE_REACHED), remainingMs);
+		})]);
+	} finally {
+		if (timer !== void 0) clearTimeout(timer);
+	}
+}
+/**
+* Write one probe span and time how long the backend takes to serve it back.
+*
+* An empty successful read means "not yet". Read failures are surfaced because
+* authentication and configuration errors cannot become fresh by polling.
+*/
+async function measureFreshness(options) {
+	const { backend, otlpEndpoint, encoding = "protobuf", timeoutMs = DEFAULT_TIMEOUT_MS, pollIntervalMs = DEFAULT_POLL_INTERVAL_MS, headers = otlpHeadersFromEnv(process.env.OTEL_EXPORTER_OTLP_HEADERS), now = Date.now, sleep = defaultSleep, send = sendOtlpTrace } = options;
+	const probeService = `autotel-freshness-probe-${randomHex(6)}`;
+	const startedAt = now();
+	const timedOutResult = (attempts) => ({
+		probeService,
+		otlpEndpoint,
+		encoding,
+		timeToQueryableSeconds: null,
+		timedOut: true,
+		attempts,
+		timeoutMs
+	});
+	if (await beforeDeadline(send(otlpEndpoint, buildProbeSpan(probeService, startedAt), headers, encoding), timeoutMs) === DEADLINE_REACHED) return timedOutResult(0);
+	let attempts = 0;
+	for (;;) {
+		attempts++;
+		const remainingMs = timeoutMs - (now() - startedAt);
+		const result = await beforeDeadline(backend.searchTraces({
+			service: probeService,
+			limit: 1
+		}), remainingMs);
+		if (result === DEADLINE_REACHED) return timedOutResult(attempts);
+		if ((result.items?.length ?? 0) > 0) return {
+			probeService,
+			otlpEndpoint,
+			encoding,
+			timeToQueryableSeconds: (now() - startedAt) / 1e3,
+			timedOut: false,
+			attempts,
+			timeoutMs
+		};
+		if (now() - startedAt >= timeoutMs) return timedOutResult(attempts);
+		await sleep(Math.min(pollIntervalMs, timeoutMs - (now() - startedAt)));
+	}
+}
+//#endregion
 //#region src/commands/investigate/health.ts
+function resolvedFreshnessEncoding(requested, backend) {
+	return requested ?? (backend.kind === "collector" ? "json" : "protobuf");
+}
 async function runHealth(flags) {
 	await runInvestigate("health", flags, async (backend) => {
 		const [health, capabilities] = await Promise.all([backend.healthCheck(), Promise.resolve(backend.capabilities())]);
-		return {
+		const base = {
 			...health,
 			signals: capabilities
 		};
+		if (!flags.otlpEndpoint) return base;
+		const encoding = resolvedFreshnessEncoding(flags.otlpEncoding, backend);
+		const freshness = await measureFreshness({
+			backend,
+			otlpEndpoint: flags.otlpEndpoint,
+			timeoutMs: flags.freshnessTimeoutMs,
+			encoding
+		});
+		return {
+			...base,
+			freshness
+		};
 	});
 }
 async function runCapabilities(flags) {
 	await runInvestigate("capabilities", flags, async (backend) => backend.capabilities());
 }
 function registerHealthCommands(program) {
-	const healthCmd = new Command("health").description("Backend health check + signal coverage (JSON)").action(async function() {
-		await runHealth(backendFlagsFromOpts(this.opts()));
+	const healthCmd = new Command("health").description("Backend health check + signal coverage (JSON)").option("--otlp-endpoint <url>", "Also measure ingest-to-queryable lag: write a probe span to this OTLP/HTTP endpoint and poll until it reads back").option("--freshness-timeout-ms <ms>", "Give up waiting for the probe span after this long (default 120000)", (value) => Number.parseInt(value, 10)).option("--otlp-encoding <encoding>", "Probe payload encoding: protobuf (default, and the only one some vendors accept) or json (the built-in collector)").action(async function() {
+		const opts = this.opts();
+		await runHealth({
+			...backendFlagsFromOpts(opts),
+			otlpEndpoint: opts.otlpEndpoint,
+			freshnessTimeoutMs: opts.freshnessTimeoutMs,
+			otlpEncoding: opts.otlpEncoding
+		});
 	});
 	addBackendFlags(healthCmd);
 	program.addCommand(healthCmd);
@@ -6752,6 +9269,27 @@ function createProgram() {
 	});
 	addGlobalOptions(addCmd);
 	program.addCommand(addCmd);
+	const mapCmd = new Command("map").description("Score the observability of every entry point in your project").argument("[entry]", "Inspect one entry point by route or file path").option("--framework <name>", "Override framework detection (next, nitro, tanstack-start, sveltekit, hono, express, fastify, elysia, cloudflare)").option("--all", "Show every entry point as a check matrix").option("--min-score <n>", "Exit 1 when the global score is below this threshold").option("--baseline [source]", "Compare against a committed autotel.map.json and exit 1 on regression (path, or git:<ref>)").option("--no-write", "Skip writing autotel.map.json").option("--json", "Output machine-readable JSON").option("--output-file <path>", "Persist JSON output to this path").option("--workspace-root", "Scan from the workspace root instead of the package root").action((entry, opts) => {
+		runMap({
+			cwd: opts.cwd ?? process.cwd(),
+			dryRun: false,
+			noInstall: false,
+			printInstallCmd: false,
+			verbose: opts.verbose ?? false,
+			quiet: opts.quiet ?? false,
+			workspaceRoot: opts.workspaceRoot ?? false,
+			entry,
+			framework: opts.framework,
+			all: opts.all ?? false,
+			minScore: opts.minScore,
+			baseline: opts.baseline,
+			write: opts.write !== false,
+			json: opts.json ?? false,
+			outputFile: opts.outputFile
+		});
+	});
+	addGlobalOptions(mapCmd);
+	program.addCommand(mapCmd);
 	const codemodCmd = new Command("codemod").description("Codemod commands for adopting autotel");
 	const traceCmd = new Command("trace").description("Wrap functions in trace() with span name from function/variable/method name").argument("<path>", "File path or glob (e.g. src/index.ts, src/**/*.ts)").option("--dry-run", "Print changes without writing files").option("--name-pattern <pattern>", "Span name template: {name}, {file}, {path}").option("--skip <regex>...", "Skip functions whose name matches (repeatable)").option("--print-files", "Print per-file summary (wrapped count, skipped)").action(async (pathArg, opts) => {
 		await runCodemodTrace({
@@ -6906,5 +9444,3 @@ run().catch((error) => {
 });
 //#endregion
 export {};
-
-//# sourceMappingURL=index.js.map