@happyvertical/smrt-dev-mcp 0.47.1 → 0.48.0

package/dist/observation-VJgHaPps.js

@@ -0,0 +1,802 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { createHash } from "node:crypto";
+import { ObjectRegistry, readDispatchHealth, readJobHealth, readMigrationStatus, readRecentChanges, readRegistryDrift, readScheduleHealth, snapshotRegistry } from "@happyvertical/smrt-core";
+import { discoverSmrtPackages, resolveManifestPath } from "@happyvertical/smrt-core/manifest/discover-smrt-packages";
+import { SchemaComparer } from "@happyvertical/smrt-core/migrations";
+import { getPackageConfig, loadConfig } from "@happyvertical/smrt-config";
+import { getDatabase } from "@happyvertical/sql";
+//#region src/tools/runtime/boot.ts
+/**
+* Confined runtime bootstrap for the Level 2 observation plane (#1831).
+*
+* "Booting" here means registering *manifests* into the in-process
+* `ObjectRegistry` — the project's own `.smrt/manifest.json` (or built
+* `dist/manifest.json`) plus every installed SMRT package manifest that the
+* project's dependency tree resolves to. No project source is imported, no
+* module is executed, no database is touched. That confinement is the safety
+* boundary: an observing agent sees what the runtime *would* register, never
+* what arbitrary project code does on import.
+*
+* The registry is a process-global singleton, so a process boots once. There
+* is deliberately no re-boot tool; restart the process to observe a rebuilt
+* manifest.
+*/
+/** Provenance label for facts read from authored/installed manifests. */
+var DECLARED_PROVENANCE = "declared (manifest)";
+/** Project manifest candidates, most authoritative first. */
+var PROJECT_MANIFEST_CANDIDATES = [".smrt/manifest.json", "dist/manifest.json"];
+function relativePath(projectRoot, path) {
+	const rel = relative(projectRoot, path);
+	if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return basename(path);
+	return rel.split(sep).join("/");
+}
+function readManifest(path) {
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8"));
+		return parsed && typeof parsed === "object" ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+function registerManifest(manifest, fallbackPackageName) {
+	const manifestPackageName = typeof manifest.packageName === "string" && manifest.packageName ? manifest.packageName : fallbackPackageName ?? void 0;
+	let count = 0;
+	for (const [name, definition] of Object.entries(manifest.objects ?? {})) {
+		if (!definition || typeof definition !== "object") continue;
+		const ownPackage = definition.packageName;
+		ObjectRegistry.registerFromManifest(name, definition, typeof ownPackage === "string" && ownPackage ? ownPackage : manifestPackageName);
+		count += 1;
+	}
+	return count;
+}
+var booted = null;
+var bootedProjectRoot = null;
+var bootedProjectManifestPath = null;
+var bootedProjectManifestMtimeMs = null;
+/**
+* Whether the project manifest on disk is newer than the one this process
+* booted. The registry is process-global and boots once, so this is the only
+* signal an agent has that a rebuild happened underneath it.
+*/
+function getBootStaleness() {
+	if (!booted || !bootedProjectManifestPath) return {
+		stale: false,
+		bootedAt: booted?.bootedAt ?? null,
+		manifestModifiedAt: null
+	};
+	try {
+		const mtimeMs = statSync(bootedProjectManifestPath).mtimeMs;
+		return {
+			stale: bootedProjectManifestMtimeMs !== null && mtimeMs > bootedProjectManifestMtimeMs,
+			bootedAt: booted.bootedAt,
+			manifestModifiedAt: new Date(mtimeMs).toISOString()
+		};
+	} catch {
+		return {
+			stale: false,
+			bootedAt: booted.bootedAt,
+			manifestModifiedAt: null
+		};
+	}
+}
+/**
+* The resolved root the process booted from. Consumers must relativize
+* paths against *this* root, never a per-request argument, or a caller could
+* widen the root (e.g. `/`) and read the layout back through "relative" paths.
+*/
+function getBootedProjectRoot() {
+	return bootedProjectRoot;
+}
+/**
+* Boot the confined runtime once per process. A second call returns the
+* existing record without touching the registry.
+*/
+async function bootRuntime(options = {}) {
+	if (booted) return booted;
+	const projectRoot = resolve(options.projectRoot ?? process.cwd());
+	const diagnostics = [];
+	const manifests = [];
+	const projectManifestPath = PROJECT_MANIFEST_CANDIDATES.map((candidate) => join(projectRoot, candidate)).find((path) => existsSync(path));
+	const projectPackageName = readProjectPackageName(projectRoot);
+	if (!projectManifestPath) diagnostics.push({
+		severity: "warning",
+		code: "project_manifest_missing",
+		message: "No project manifest found (.smrt/manifest.json or dist/manifest.json); run the project build so the runtime manifest exists."
+	});
+	else {
+		const manifest = readManifest(projectManifestPath);
+		if (!manifest) diagnostics.push({
+			severity: "error",
+			code: "project_manifest_invalid",
+			message: `Project manifest at ${relativePath(projectRoot, projectManifestPath)} is not valid JSON.`
+		});
+		else manifests.push({
+			kind: "project",
+			packageName: typeof manifest.packageName === "string" ? manifest.packageName : projectPackageName,
+			path: relativePath(projectRoot, projectManifestPath),
+			objectCount: registerManifest(manifest, projectPackageName)
+		});
+	}
+	let dependencyNames = [];
+	try {
+		dependencyNames = discoverSmrtPackages({
+			baseDir: projectRoot,
+			noCache: true
+		});
+	} catch (error) {
+		diagnostics.push({
+			severity: "warning",
+			code: "dependency_discovery_failed",
+			message: `Installed SMRT package discovery failed: ${error instanceof Error ? error.message : "unknown error"}`
+		});
+	}
+	for (const dependency of dependencyNames.sort()) {
+		const manifestPath = resolveManifestPath(dependency, projectRoot);
+		if (!manifestPath) {
+			diagnostics.push({
+				severity: "info",
+				code: "dependency_manifest_missing",
+				message: `Installed SMRT package ${dependency} exposes no runtime manifest.`
+			});
+			continue;
+		}
+		const manifest = readManifest(manifestPath);
+		if (!manifest) {
+			diagnostics.push({
+				severity: "warning",
+				code: "dependency_manifest_invalid",
+				message: `Manifest for ${dependency} is not valid JSON.`
+			});
+			continue;
+		}
+		manifests.push({
+			kind: "dependency",
+			packageName: dependency,
+			path: relativePath(projectRoot, manifestPath),
+			objectCount: registerManifest(manifest, dependency)
+		});
+	}
+	bootedProjectRoot = projectRoot;
+	if (projectManifestPath) {
+		bootedProjectManifestPath = projectManifestPath;
+		try {
+			bootedProjectManifestMtimeMs = statSync(projectManifestPath).mtimeMs;
+		} catch {
+			bootedProjectManifestMtimeMs = null;
+		}
+	}
+	booted = {
+		provenance: DECLARED_PROVENANCE,
+		bootedAt: (options.now ?? /* @__PURE__ */ new Date()).toISOString(),
+		projectName: projectPackageName ?? basename(projectRoot),
+		manifests,
+		objectCount: manifests.reduce((sum, m) => sum + m.objectCount, 0),
+		diagnostics
+	};
+	return booted;
+}
+function readProjectPackageName(projectRoot) {
+	try {
+		const parsed = JSON.parse(readFileSync(join(projectRoot, "package.json"), "utf8"));
+		return typeof parsed.name === "string" && parsed.name ? parsed.name : null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region src/tools/runtime/connection.ts
+/**
+* Optional read-only dev-database connection resolution for runtime
+* diagnostics tools (#1824).
+*
+* Resolution order per call:
+*   1. explicit `dbUrl`/`dbType` tool arguments
+*   2. `SMRT_DEV_DB_URL` environment variable
+*   3. the project's cosmiconfig CLI section (`getPackageConfig('cli', ...)`
+*      from `@happyvertical/smrt-config`) → `database.{type,url}`
+*
+* No configured connection → `db: null` with `source: 'none'`; callers return
+* a successful static-only envelope. A connection is always opened lazily per
+* call and closed in the caller's `finally` — nothing is cached across calls
+* and the server never holds a database handle.
+*
+* Sensitive handling: connection strings are never logged or echoed. Every
+* surfaced URL passes through {@link redactConnectionString}; driver errors
+* are surfaced only through {@link safeErrorMessage}, which strips anything
+* that looks like a credential-bearing URL.
+*/
+var RUNTIME_DATABASE_TYPES = [
+	"sqlite",
+	"postgres",
+	"duckdb"
+];
+function isRuntimeDatabaseType(value) {
+	return RUNTIME_DATABASE_TYPES.includes(value);
+}
+/**
+* Sensitive query-parameter names. Matching normalizes the key (lowercase,
+* `_`/`-` stripped), so camelCase (`authToken`, `accessToken`) and hyphen
+* variants (`api-key`) are masked exactly like their snake_case forms.
+*/
+var SENSITIVE_QUERY_PARAMS = [
+	"access_token",
+	"apikey",
+	"api_key",
+	"auth",
+	"auth_token",
+	"connectionstring",
+	"connection_string",
+	"password",
+	"token"
+];
+function normalizeQueryParamName(key) {
+	return key.toLowerCase().replace(/[_-]/g, "");
+}
+var SENSITIVE_QUERY_PARAM_NAMES = new Set(SENSITIVE_QUERY_PARAMS.map(normalizeQueryParamName));
+var DEFAULT_CLI_DATABASE = { database: {
+	type: "sqlite",
+	url: ":memory:"
+} };
+/**
+* Redact a connection string so it can be shown to an agent without leaking
+* credentials. Mirrors the CLI's `redactConnectionString` (which is CLI
+* private); patterned identically so dev-mcp never depends on the CLI.
+*
+* Query-parameter masking normalizes each key (lowercase, `_`/`-` stripped),
+* so camelCase forms such as Turso/libsql's `?authToken=` mask exactly like
+* their snake_case forms. A final regex pass also masks `key=value` pairs
+* embedded in free text (driver error messages often quote the URL); it treats
+* the start of the string, `?`, `&`, `,`, `(`, and whitespace as the
+* preceding boundary.
+*/
+function redactConnectionString(value) {
+	let redacted = value;
+	try {
+		const url = new URL(value);
+		if (url.password) url.password = "***";
+		for (const key of [...url.searchParams.keys()]) if (SENSITIVE_QUERY_PARAM_NAMES.has(normalizeQueryParamName(key))) url.searchParams.set(key, "***");
+		redacted = url.toString();
+	} catch {
+		redacted = value.replace(/([a-z][a-z0-9+.-]*:\/\/[^:\s/@]+:)(?:[^@\s]|@(?=[^@\s]*@))+(@)/gi, "$1***$2");
+	}
+	redacted = redacted.replace(/(?:[A-Za-z]:)?(?:[\\/][^\s\\/'"`]+)+[\\/]([^\s\\/'"`]+\.(?:db|sqlite3?|duckdb))/g, "…/$1");
+	return redacted.replace(/((?:^|[?&,(\s])([a-z][a-z0-9_-]{0,30})=)([^&,\s)]+)/gi, (match, prefix, key) => SENSITIVE_QUERY_PARAM_NAMES.has(normalizeQueryParamName(key)) ? `${prefix}***` : match);
+}
+/**
+* Build a safe, redacted error message for a database failure. Connection
+* strings and raw driver error objects are never surfaced verbatim.
+*/
+function safeErrorMessage(error) {
+	return redactConnectionString(error instanceof Error ? error.message : String(error ?? "unknown error"));
+}
+/**
+* Normalize a type hint into an engine `getDatabase` accepts. Unknown values
+* throw a safe error (no URL is included) so the caller can surface a
+* diagnostic instead of silently opening the wrong adapter.
+*/
+function toRuntimeDatabaseType(value) {
+	const normalized = value.trim().toLowerCase();
+	if (isRuntimeDatabaseType(normalized)) return normalized;
+	throw new Error(`Unsupported runtime database type "${normalized}"; expected sqlite, postgres, or duckdb`);
+}
+/** Infer an engine hint from a URL scheme when no explicit type is given. */
+function inferDatabaseType(url, hint) {
+	if (hint && hint.trim().length > 0) return hint;
+	if (/^postgres(ql)?:/i.test(url)) return "postgres";
+	if (/^duckdb:/i.test(url)) return "duckdb";
+	return "sqlite";
+}
+/**
+* Normalize the accepted dev-database URL forms to what `getDatabase` opens.
+*
+* `@happyvertical/sql` understands `file:` URLs and bare paths for SQLite,
+* but not a `sqlite:` scheme; passing `sqlite:///abs/dev.db` through verbatim
+* made the driver treat the whole string as a relative filename and join it
+* to cwd. Accepted forms:
+*
+* - `sqlite:///abs/path.db`, `sqlite://rel/path.db`, `sqlite:path.db` →
+*   `file:` URL with the path resolved against cwd only when it is relative
+* - `file:` URLs, `postgres:`/`postgresql:`, `duckdb:` → unchanged
+* - a bare path → unchanged (the driver resolves it)
+*/
+/**
+* Whether a configured value means "in-memory, so not a runtime database":
+* `:memory:` as well as the `sqlite::memory:` / `sqlite://:memory:` spellings.
+*/
+function isMemoryDatabaseUrl(url) {
+	return /^(?:sqlite:(?:\/\/)?)?:memory:$/i.test(url.trim());
+}
+function normalizeDatabaseUrl(url) {
+	const match = /^sqlite:(?:\/\/)?(.*)$/i.exec(url.trim());
+	if (!match) return url.trim();
+	const path = match[1];
+	if (!path) return url.trim();
+	return pathToFileURL(path.startsWith("/") ? path : resolve(process.cwd(), path)).href;
+}
+/**
+* Resolve the dev-database connection for one tool call.
+*
+* Returns `db: null` (never throws) when no connection is configured; callers
+* must treat that as "no runtime database" and return a static-only envelope.
+* A thrown connect error is propagated to the caller, which converts it into
+* a diagnostic envelope — it must never reach the MCP transport.
+*/
+async function resolveRuntimeConnection(args = {}) {
+	const argUrl = args.dbUrl?.trim();
+	if (argUrl && !isMemoryDatabaseUrl(argUrl)) {
+		const databaseType = toRuntimeDatabaseType(inferDatabaseType(argUrl, args.dbType));
+		return {
+			db: await getDatabaseInstance({
+				type: databaseType,
+				url: normalizeDatabaseUrl(argUrl)
+			}),
+			source: "argument",
+			displayUrl: redactConnectionString(argUrl),
+			databaseType
+		};
+	}
+	const envUrl = process.env.SMRT_DEV_DB_URL?.trim();
+	if (envUrl && !isMemoryDatabaseUrl(envUrl)) {
+		const databaseType = toRuntimeDatabaseType(inferDatabaseType(envUrl, args.dbType));
+		return {
+			db: await getDatabaseInstance({
+				type: databaseType,
+				url: normalizeDatabaseUrl(envUrl)
+			}),
+			source: "environment",
+			displayUrl: redactConnectionString(envUrl),
+			databaseType
+		};
+	}
+	const config = await loadCliDatabaseConfig();
+	const configUrl = config?.database?.url?.trim();
+	if (configUrl && !isMemoryDatabaseUrl(configUrl)) {
+		const databaseType = toRuntimeDatabaseType(config.database?.type || inferDatabaseType(configUrl, args.dbType));
+		return {
+			db: await getDatabaseInstance({
+				type: databaseType,
+				url: normalizeDatabaseUrl(configUrl)
+			}),
+			source: "config",
+			displayUrl: redactConnectionString(configUrl),
+			databaseType
+		};
+	}
+	return {
+		db: null,
+		source: "none",
+		displayUrl: "",
+		databaseType: null
+	};
+}
+async function loadCliDatabaseConfig() {
+	try {
+		await loadConfig();
+		const database = getPackageConfig("cli", DEFAULT_CLI_DATABASE).database;
+		if (database && typeof database.url === "string") return { database };
+		return {};
+	} catch {
+		return {};
+	}
+}
+async function getDatabaseInstance(options) {
+	return getDatabase(options);
+}
+/**
+* Best-effort close of a resolved connection. Never throws; diagnostics must
+* not fail because cleanup hiccuped.
+*/
+async function closeRuntimeConnection(db) {
+	if (!db || typeof db !== "object") return;
+	const closeable = db;
+	const close = closeable.close ?? closeable.client?.end ?? closeable.client?.close;
+	if (typeof close !== "function") return;
+	try {
+		await close.call(closeable.close ? closeable : closeable.client);
+	} catch {}
+}
+//#endregion
+//#region src/tools/runtime/tools.ts
+/**
+* Runtime diagnostics tools (#1824): read-only views over a project's dev
+* database `_smrt_*` system tables, powered by the shared SELECT-only
+* system-diagnostics reader in `@happyvertical/smrt-core`.
+*
+* Contract:
+* - **Optional connection.** No configured connection returns a successful
+*   static-only envelope — the server always starts and static tools are
+*   unaffected. A live connection is opened lazily per call and closed in
+*   `finally`; nothing is cached across calls.
+* - **Read-only.** Every underlying statement is a bounded SELECT; the reader
+*   never selects sensitive columns (job payloads/results, schedule
+*   `agentConfig`/`methodArgs`, dispatch `payload`/`metadata`).
+* - **Provenance-labeled.** Live results carry `provenance: 'runtime (live DB)'`;
+*   static-only results carry `provenance: 'static'` — agents must never
+*   conflate runtime facts with declared/manifest facts.
+* - **Fail-safe.** A connect/read error becomes a diagnostic envelope; it must
+*   never reach the MCP transport and never includes raw driver text or URLs.
+*/
+/** Provenance labels separating runtime facts from static/declared facts. */
+var RUNTIME_PROVENANCE = "runtime (live DB)";
+var STATIC_PROVENANCE = "static";
+/**
+* Serialize resolve → read → close per connection target so overlapping tool
+* calls never close a shared cached handle out from under each other.
+*
+* `@happyvertical/sql`'s `getDatabase` returns a cached handle per URL (no
+* opt-out in its public API). `closeRuntimeConnection` only calls the handle's
+* own `close`/`end`, but the SDK wraps those so a close also evicts the handle
+* from its connection cache. Two concurrent diagnostics calls resolving the
+* same URL would therefore share one handle, with the first finisher closing
+* it mid-read for the second. A per-key promise chain keeps each call's
+* lifecycle private: every call resolves its own view of the connection,
+* performs its read, and only then closes — the next queued call re-resolves
+* a fresh handle.
+*
+* The key is a digest of the resolved target, never the raw URL, so a
+* credential-bearing connection string is not retained in this map.
+*/
+var runtimeReadQueues = /* @__PURE__ */ new Map();
+function connectionQueueKey(args) {
+	const target = args.dbUrl?.trim() || process.env.SMRT_DEV_DB_URL?.trim() || "cli.config";
+	return createHash("sha256").update(target).digest("hex");
+}
+async function enqueueRuntimeRead(key, operation) {
+	const run = (runtimeReadQueues.get(key) ?? Promise.resolve()).then(operation, operation);
+	const tail = run.catch(() => void 0);
+	runtimeReadQueues.set(key, tail);
+	tail.then(() => {
+		if (runtimeReadQueues.get(key) === tail) runtimeReadQueues.delete(key);
+	});
+	return run;
+}
+/**
+* Run one read against the optional runtime connection, mapping every outcome
+* to a successful MCP envelope:
+*
+* - no connection configured → static-only envelope (`connected: false`)
+* - connect failure → static envelope with a safe diagnostic
+* - read failure → connected envelope with a safe diagnostic
+* - success → live result under `provenance: 'runtime (live DB)'`; a
+*   category-unavailable reader result keeps its `available: false` data and
+*   surfaces its message as a diagnostic
+*/
+async function withRuntimeConnection(args, read, staticHint) {
+	return enqueueRuntimeRead(connectionQueueKey(args), () => runWithRuntimeConnection(args, read, staticHint));
+}
+async function runWithRuntimeConnection(args, read, staticHint) {
+	let resolved;
+	try {
+		resolved = await resolveRuntimeConnection(args);
+	} catch (error) {
+		return {
+			ok: true,
+			coverage: null,
+			diagnostics: [{
+				severity: "warning",
+				code: "runtime_connection_error",
+				message: safeErrorMessage(error)
+			}],
+			data: {
+				provenance: STATIC_PROVENANCE,
+				connected: false
+			}
+		};
+	}
+	if (!resolved.db) return {
+		ok: true,
+		coverage: null,
+		diagnostics: [{
+			severity: "info",
+			code: "runtime_connection_unavailable",
+			message: `No runtime dev database configured (set SMRT_DEV_DB_URL or cli.database); returning static-only result: ${staticHint}. Static tools are unaffected.`
+		}],
+		data: {
+			provenance: STATIC_PROVENANCE,
+			connected: false
+		}
+	};
+	const { db, source, displayUrl, databaseType } = resolved;
+	try {
+		const { data, diagnostics } = await read(db);
+		return {
+			ok: true,
+			coverage: null,
+			diagnostics,
+			data: {
+				provenance: RUNTIME_PROVENANCE,
+				connected: true,
+				connectionSource: source,
+				databaseType,
+				displayUrl,
+				...data
+			}
+		};
+	} catch (error) {
+		return {
+			ok: true,
+			coverage: null,
+			diagnostics: [{
+				severity: "warning",
+				code: "runtime_read_error",
+				message: safeErrorMessage(error)
+			}],
+			data: {
+				provenance: RUNTIME_PROVENANCE,
+				connected: true,
+				connectionSource: source,
+				databaseType,
+				displayUrl
+			}
+		};
+	} finally {
+		await closeRuntimeConnection(db);
+	}
+}
+/**
+* Stored error columns (`error_message`, `last_error`) are free text written
+* at failure time and routinely quote connection URLs or credentials. Every
+* string in a live result passes through {@link redactConnectionString}
+* before it reaches an MCP client; structure and non-string values are kept.
+*/
+function redactStrings(value) {
+	if (typeof value === "string") return redactConnectionString(value);
+	if (Array.isArray(value)) return value.map((item) => redactStrings(item));
+	if (value !== null && typeof value === "object") {
+		const out = {};
+		for (const [key, item] of Object.entries(value)) out[key] = redactStrings(item);
+		return out;
+	}
+	return value;
+}
+/** Convert a reader result into envelope data + diagnostics. */
+function toEnvelopeParts(rawResult) {
+	const result = redactStrings(rawResult);
+	if (result !== null && typeof result === "object" && "available" in result && result.available === false) {
+		const unavailable = result;
+		const { message, detail, ...rest } = unavailable;
+		return {
+			data: rest,
+			diagnostics: [{
+				severity: unavailable.reason === "retired" ? "info" : "warning",
+				code: `category_unavailable_${String(unavailable.reason).replace(/-/g, "_")}`,
+				message: detail ? `${String(message)} Cause: ${detail}` : String(message)
+			}]
+		};
+	}
+	const data = result;
+	const diagnostics = [];
+	const behind = Array.isArray(data.schemaBehind) ? data.schemaBehind : [];
+	for (const entry of behind) {
+		const columns = Array.isArray(entry.missingColumns) ? entry.missingColumns.map(String) : [];
+		if (columns.length === 0) continue;
+		diagnostics.push({
+			severity: "info",
+			code: "schema_behind",
+			message: `${String(entry.tableName ?? "table")} predates ${columns.join(", ")}; those fields are reported as null. Run db:migrate to bring the system tables current.`
+		});
+	}
+	return {
+		data,
+		diagnostics
+	};
+}
+function readToParts(read) {
+	return read.then((result) => toEnvelopeParts(result));
+}
+async function runtimeMigrationStatus(args = {}) {
+	const { limit, ...connectionArgs } = args;
+	return withRuntimeConnection(connectionArgs, (db) => readToParts(readMigrationStatus(db, { limit })), "no migration status — the manifest still reports the declared schema");
+}
+async function runtimeJobHealth(args = {}) {
+	const { limit, ...connectionArgs } = args;
+	return withRuntimeConnection(connectionArgs, (db) => readToParts(readJobHealth(db, { limit })), "no job health snapshot — the manifest still reports declared job queues");
+}
+async function runtimeScheduleHealth(args = {}) {
+	const { limit, ...connectionArgs } = args;
+	return withRuntimeConnection(connectionArgs, (db) => readToParts(readScheduleHealth(db, { limit })), "no schedule health snapshot — the manifest still reports declared schedules");
+}
+async function runtimeDispatchHealth(args = {}) {
+	const { limit, ...connectionArgs } = args;
+	return withRuntimeConnection(connectionArgs, (db) => readToParts(readDispatchHealth(db, { limit })), "no dispatch health snapshot — the manifest still reports declared dispatch topology");
+}
+async function runtimeRecentChanges(args = {}) {
+	const { since, tables, tenantId, limit, ...connectionArgs } = args;
+	return withRuntimeConnection(connectionArgs, (db) => readToParts(readRecentChanges(db, {
+		since,
+		tables,
+		tenantId,
+		limit
+	})), "no recent changes — static knowledge artifacts are unchanged");
+}
+async function runtimeRegistryDrift(args = {}) {
+	return withRuntimeConnection(args, (db) => readToParts(readRegistryDrift(db)), "no registry drift report — _smrt_registry is retired; declared objects come from the manifest");
+}
+//#endregion
+//#region src/tools/runtime/observation.ts
+/**
+* Level 2 read-only observation tools over the booted runtime (#1831).
+*
+* Three facts planes, labelled separately in every envelope:
+* - `declared (manifest)`: what the confined boot registered ({@link bootRuntime});
+* - `booted (registry)`: the in-process `ObjectRegistry` projected through the
+*   sanitized {@link snapshotRegistry} DTO;
+* - `runtime (live DB)`: the optional read-only connection, reused from Level 1.
+*
+* Nothing here mutates: no writes, no `do()`, no generated CRUD, no project
+* code execution. `runtime-schema-diff` only *introspects* the live schema.
+*/
+/** Row budget for `runtime-schema-diff` change lists. */
+var SCHEMA_DIFF_CHANGE_LIMIT = 200;
+function bootDiagnostics(boot) {
+	return boot.diagnostics.filter((d) => d.severity !== "info").map((d) => ({
+		severity: d.severity === "error" ? "warning" : d.severity,
+		code: `boot_${d.code}`,
+		message: d.message
+	}));
+}
+var bootPreambleSent = false;
+/**
+* The full manifest list is emitted once per process; later envelopes carry
+* only the identifying fields. Every runtime response re-embedding the same
+* multi-manifest block was pure repetition for an agent.
+*/
+function bootSummary(boot) {
+	const compact = {
+		provenance: boot.provenance,
+		bootedAt: boot.bootedAt,
+		projectName: boot.projectName,
+		objectCount: boot.objectCount,
+		manifestCount: boot.manifests.length
+	};
+	if (bootPreambleSent) return compact;
+	bootPreambleSent = true;
+	return {
+		...compact,
+		manifests: boot.manifests
+	};
+}
+function stalenessDiagnostics() {
+	const staleness = getBootStaleness();
+	if (!staleness.stale) return [];
+	return [{
+		severity: "warning",
+		code: "manifest_newer_than_boot",
+		message: `The project manifest changed at ${staleness.manifestModifiedAt} after this process booted at ${staleness.bootedAt}; restart the server to observe the rebuilt registry.`
+	}];
+}
+function objectKey(object) {
+	return object.qualifiedName ?? object.name;
+}
+/** `runtime-registry`: sanitized snapshot of the booted registry. */
+async function runtimeRegistry(args = {}) {
+	const boot = await bootRuntime({ projectRoot: args.projectPath });
+	const snapshot = snapshotRegistry({
+		projectRoot: getBootedProjectRoot() ?? void 0,
+		objects: args.objects,
+		detail: args.detail ?? Boolean(args.objects?.length)
+	});
+	const limit = Math.min(Math.max(Math.floor(args.limit ?? 50), 1), 500);
+	const cursor = typeof args.cursor === "string" && args.cursor.length > 0 ? args.cursor : null;
+	const all = snapshot.objects;
+	const afterCursor = cursor ? all.filter((object) => objectKey(object).localeCompare(cursor) > 0) : all;
+	const objects = afterCursor.slice(0, limit);
+	const nextCursor = afterCursor.length > objects.length && objects.length > 0 ? objectKey(objects[objects.length - 1]) : null;
+	return {
+		ok: true,
+		coverage: null,
+		diagnostics: [...bootDiagnostics(boot), ...stalenessDiagnostics()],
+		data: {
+			provenance: snapshot.provenance,
+			boot: bootSummary(boot),
+			page: {
+				returned: objects.length,
+				matched: all.length,
+				limit,
+				cursor,
+				nextCursor
+			},
+			snapshot: {
+				...snapshot,
+				objects
+			}
+		}
+	};
+}
+/** `runtime-object`: one object's sanitized definition plus its generated DDL. */
+async function runtimeObject(args) {
+	const boot = await bootRuntime({ projectRoot: args.projectPath });
+	const name = typeof args.name === "string" ? args.name.trim() : "";
+	const snapshot = snapshotRegistry({
+		projectRoot: getBootedProjectRoot() ?? void 0,
+		objects: name ? [name] : [],
+		detail: true
+	});
+	const diagnostics = [...bootDiagnostics(boot), ...stalenessDiagnostics()];
+	let object = snapshot.objects[0] ?? null;
+	if (snapshot.objects.length > 1) {
+		object = null;
+		diagnostics.push({
+			severity: "warning",
+			code: "object_ambiguous",
+			message: `${name} is registered by several packages; pass a qualified name: ${snapshot.objects.map((candidate) => candidate.qualifiedName ?? candidate.name).join(", ")}`
+		});
+	} else if (!object) diagnostics.push({
+		severity: "warning",
+		code: "object_not_found",
+		message: name ? `No booted object named ${name}; use runtime-registry to list names.` : "name is required."
+	});
+	let ddl = null;
+	if (object) try {
+		ddl = ObjectRegistry.getSchemaDDL(object.qualifiedName ?? object.name, args.engine) ?? null;
+	} catch (error) {
+		diagnostics.push({
+			severity: "warning",
+			code: "ddl_unavailable",
+			message: `Generated DDL unavailable: ${error instanceof Error ? error.message : "unknown error"}`
+		});
+	}
+	return {
+		ok: true,
+		coverage: null,
+		diagnostics,
+		data: {
+			provenance: snapshot.provenance,
+			boot: bootSummary(boot),
+			object,
+			ddl
+		}
+	};
+}
+/**
+* `runtime-schema-diff`: booted registry schemas versus the live database,
+* using the same comparer `db:diff`/`db:migrate` use. Introspection only —
+* drop/relax options are pinned off and nothing is executed.
+*/
+async function runtimeSchemaDiff(args = {}) {
+	const boot = await bootRuntime({ projectRoot: args.projectPath });
+	const envelope = await withRuntimeConnection(args, async (db) => {
+		const diff = await new SchemaComparer(db, {
+			includeDroppedTables: false,
+			includeDroppedColumns: false,
+			includeDroppedIndexes: false,
+			relaxColumns: false
+		}).compare(ObjectRegistry.getAllSchemasAsDefinitions());
+		const byType = {};
+		for (const change of diff.changes) {
+			const type = String(change.type ?? "unknown");
+			byType[type] = (byType[type] ?? 0) + 1;
+		}
+		const addedTables = diff.added_tables.map((t) => t.tableName);
+		if (addedTables.length > 0) byType.add_table = addedTables.length;
+		if (diff.dropped_tables.length > 0) byType.drop_table = diff.dropped_tables.length;
+		const changeCount = diff.changes.length + addedTables.length + diff.dropped_tables.length;
+		return {
+			data: {
+				boot: bootSummary(boot),
+				hasChanges: diff.has_changes,
+				addedTables,
+				droppedTables: diff.dropped_tables,
+				orphanTables: diff.orphan_tables ?? [],
+				changeCount,
+				columnChangeCount: diff.changes.length,
+				changesByType: byType,
+				changes: diff.changes.slice(0, SCHEMA_DIFF_CHANGE_LIMIT),
+				truncated: diff.changes.length > SCHEMA_DIFF_CHANGE_LIMIT
+			},
+			diagnostics: []
+		};
+	}, "booted registry schemas only; connect a dev database to diff against live tables");
+	envelope.diagnostics = [
+		...bootDiagnostics(boot),
+		...stalenessDiagnostics(),
+		...envelope.diagnostics
+	];
+	return envelope;
+}
+//#endregion
+export { STATIC_PROVENANCE as a, runtimeMigrationStatus as c, runtimeScheduleHealth as d, redactConnectionString as f, RUNTIME_PROVENANCE as i, runtimeRecentChanges as l, bootRuntime as m, runtimeRegistry as n, runtimeDispatchHealth as o, safeErrorMessage as p, runtimeSchemaDiff as r, runtimeJobHealth as s, runtimeObject as t, runtimeRegistryDrift as u };
+
+//# sourceMappingURL=observation-VJgHaPps.js.map