@nifrajs/cli 2.3.0 → 2.5.0

package/docs/types.json

@@ -128,13 +128,13 @@
     "name": "AdversarialContractOptions",
     "kind": "interface",
     "package": "@nifrajs/testing",
-    "signature": "export interface AdversarialContractOptions {\n    /** Base origin for generated requests. Default `http://nifra.contract`. */\n    readonly origin?: string;\n    /** Replayable seed used for deterministic witness generation. */\n    readonly seed?: number;\n    /** Known-good request values keyed by `\"METHOD /path\"`. Required for opaque Standard Schemas. */\n    readonly witnesses?: Readonly<Record<string, ContractWitness>>;\n    /** Select a subset of reflected routes. */\n    readonly include?: (route: ReflectedRoute) => boolean;\n    /** Execute every case against these targets. Default: the supplied app, named `in-process`. */\n    readonly runtimes?: readonly ContractRuntime[];\n    /** Maximum validator-proven mutations per body/query schema. Default 32. */\n    readonly maxMutationsPerInput?: number;\n    /** Maximum serialized witness size. Default 256 KiB. */\n    readonly maxWitnessBytes?: number;\n    /** Statuses that prove an invalid input was rejected. Default `[422]`. */\n    readonly expectedValidationStatuses?: readonly number[];\n    /**\n     * Attach auth, tenant, or runtime-specific state. Return a new Request; the input Request is already\n     * fresh for this case and runtime.\n     */\n    readonly prepareRequest?: (request: Request, context: ContractCaseContext) => Request | Promise<Request>;\n    /** Override rejection semantics (for apps with a custom validation response). */\n    readonly isRejected?: (response: Response, context: ContractCaseContext) => boolean | Promise<boolean>;\n    /** Validate a real successful response for every declared response schema. Default true. */\n    readonly validateResponses?: boolean;\n    /** Fail the report when a contracted target cannot be exercised. Default true. */\n    readonly requireCoverage?: boolean;\n    /** Greedily minimize an invalid input that unexpectedly reaches the app. Default true. */\n    readonly shrinkFailures?: boolean;\n    /** Cap shrink probes for one failure. Default 12. */\n    readonly maxShrinkAttempts?: number;\n    /** Replay only these stable case IDs. Coverage gaps are advisory when this is set. */\n    readonly only?: string | readonly string[];\n}"
+    "signature": "export interface AdversarialContractOptions {\n    /** Base origin for generated requests. Default `http://nifra.contract`. */\n    readonly origin?: string;\n    /** Replayable seed used for deterministic witness generation. */\n    readonly seed?: number;\n    /** Known-good request values keyed by `\"METHOD /path\"`. Required for opaque Standard Schemas. */\n    readonly witnesses?: Readonly<Record<string, ContractWitness>>;\n    /** Select a subset of reflected routes. */\n    readonly include?: (route: ReflectedRoute) => boolean;\n    /** Execute every case against these targets. Default: the supplied app, named `in-process`. */\n    readonly runtimes?: readonly ContractRuntime[];\n    /** Maximum validator-proven mutations per body/query schema. Default 32. */\n    readonly maxMutationsPerInput?: number;\n    /** Maximum serialized witness size. Default 256 KiB. */\n    readonly maxWitnessBytes?: number;\n    /** Statuses that prove an invalid input was rejected. Default `[422]`. */\n    readonly expectedValidationStatuses?: readonly number[];\n    /**\n     * Attach auth, tenant, or runtime-specific state. Return a new Request; the input Request is already\n     * fresh for this case and runtime.\n     */\n    readonly prepareRequest?: (request: Request, context: ContractCaseContext) => Request | Promise<Request>;\n    /** Override rejection semantics (for apps with a custom validation response). */\n    readonly isRejected?: (response: Response, context: ContractCaseContext) => boolean | Promise<boolean>;\n    /** Validate a real successful response for every declared response schema. Default true. */\n    readonly validateResponses?: boolean;\n    /** Fail the report when a contracted target cannot be exercised. Default true. */\n    readonly requireCoverage?: boolean;\n    /** Greedily minimize an invalid input that unexpectedly reaches the app. Default true. */\n    readonly shrinkFailures?: boolean;\n    /** Cap shrink probes for one failure. Default 12. */\n    readonly maxShrinkAttempts?: number;\n    /** Replay only these stable case IDs. Coverage gaps are advisory when this is set. */\n    readonly only?: string | readonly string[];\n    /**\n     * Derive an inspectable JSON Schema from a validator that carries none (zod/valibot/arktype expose a\n     * Standard Schema validator but no `.jsonSchema`). Called for any body/query schema whose `jsonSchema`\n     * is undefined; a non-undefined return turns on witness synthesis AND constraint-driven mutation\n     * generation for that route. Fail-safe: throwing or returning undefined leaves the schema opaque\n     * (NO_WITNESS, as today). Ready-made for zod: `import { zodJsonSchema } from \"@nifrajs/testing/zod\"`.\n     *\n     * Defaults to `@nifrajs/mock`'s `autoReflectJsonSchema`, which recognizes zod by its Standard Schema\n     * vendor tag and converts via `z.toJSONSchema` when zod is installed - so zod routes get witnesses and\n     * constraint-driven mutations with no wiring. Pass a hook to override, or `() => undefined` to force\n     * every opaque schema to stay opaque.\n     */\n    readonly reflectJsonSchema?: (schema: unknown) => JsonSchema | undefined;\n}"
   },
   {
     "name": "AdversarialContractReport",
     "kind": "interface",
     "package": "@nifrajs/testing",
-    "signature": "export interface AdversarialContractReport {\n    readonly ok: boolean;\n    readonly seed: number;\n    readonly routeCount: number;\n    readonly targetCount: number;\n    readonly runtimeCount: number;\n    readonly results: readonly AdversarialContractResult[];\n    readonly failures: readonly AdversarialContractResult[];\n    readonly gaps: readonly ContractCoverageGap[];\n    readonly counts: {\n        readonly passed: number;\n        readonly failed: number;\n        readonly gaps: number;\n    };\n}"
+    "signature": "export interface AdversarialContractReport {\n    readonly ok: boolean;\n    readonly seed: number;\n    readonly routeCount: number;\n    readonly targetCount: number;\n    readonly runtimeCount: number;\n    readonly results: readonly AdversarialContractResult[];\n    readonly failures: readonly AdversarialContractResult[];\n    readonly gaps: readonly ContractCoverageGap[];\n    /** Non-fatal notes about coverage that is legitimately absent (does not affect `ok`). */\n    readonly advisories: readonly string[];\n    readonly counts: {\n        readonly passed: number;\n        readonly failed: number;\n        readonly gaps: number;\n    };\n}"
   },
   {
     "name": "AdversarialContractResult",
@@ -523,6 +523,13 @@
     "signature": "export type AuthPlugin<P> = NifraPlugin & {\n    /** The verified principal for this request, or `null` (no/invalid token in `optional` mode). */\n    principal(request: Request): P | null;\n    /** The verified principal, or **throws a `401` `Response`** when absent. */\n    requirePrincipal(request: Request): P;\n};",
     "doc": "/**\n * A token-auth plugin (`bearer` / `apiKey`). Apply it with `app.use(auth)` - it rejects unauthorized\n * requests to **routes defined after it** with `401` (unless `optional`). Read the verified principal\n * inside a handler/loader via {@link AuthPlugin.principal} (nullable) or\n * {@link AuthPlugin.requirePrincipal} (throws `401` when absent). The principal is verified once per\n * request and cached, so reading it is free.\n *\n * `beforeHandle` is **order-scoped**: place `app.use(auth)` before the routes it should guard. Hold the\n * returned instance to read the principal (mirrors `@nifrajs/auth`'s `sessions.get(c)` and\n * `@nifrajs/better-auth`'s `getSession(auth, req)`):\n *\n * ```ts\n * const auth = bearer({ verify: (t) => lookupUser(t) }) // P = User (inferred)\n * const app = server().use(auth).get(\"/me\", (c) => auth.requirePrincipal(c.req))\n * ```\n */"
   },
+  {
+    "name": "autoReflectJsonSchema",
+    "kind": "function",
+    "package": "@nifrajs/mock",
+    "signature": "export declare function autoReflectJsonSchema(schema: unknown): JsonSchema | undefined;",
+    "doc": "/**\n * Derive a JSON Schema from a zod Standard Schema, or `undefined` for anything else (non-zod vendors,\n * zod not installed, unconvertible schemas). Safe as an always-on default: it can only ever turn an\n * opaque schema inspectable, never change one that already carries JSON Schema metadata.\n */"
+  },
   {
     "name": "Await",
     "kind": "function",
@@ -931,6 +938,26 @@
     "signature": "export interface BuildClientViteOptions extends Omit<BuildClientOptions, \"plugins\"> {\n    /** Vite plugins for the app's client transforms (e.g. `react()`, `vue()`). */\n    readonly vitePlugins?: readonly unknown[];\n    /** Vite project root (default: the parent of `routesDir`). Manifest keys are relative to it. */\n    readonly root?: string;\n}",
     "doc": "/** Options for {@link buildClientVite} - the Bun {@link BuildClientOptions} minus Bun-plugin specifics,\n * plus the Vite plugin list the app injects for its transforms. */"
   },
+  {
+    "name": "buildCodeframe",
+    "kind": "function",
+    "package": "@nifrajs/web",
+    "signature": "export declare function buildCodeframe(file: string, line: number, column: number | undefined, read?: SourceReader, radius?: number): Codeframe | undefined;",
+    "doc": "/**\n * Build a source codeframe: `radius` lines either side of `line`, each tagged with its 1-based number\n * and whether it is the offending line. Returns undefined if the source can't be read or the line is\n * out of range - a diagnostic without a codeframe is still useful, so this never throws.\n */"
+  },
+  {
+    "name": "buildDiagnostic",
+    "kind": "function",
+    "package": "@nifrajs/web",
+    "signature": "export declare function buildDiagnostic(err: unknown, options?: BuildDiagnosticOptions): Diagnostic;",
+    "doc": "/**\n * Resolve any thrown value into a `Diagnostic`: parse the (already source-mapped) stack, locate the top\n * user frame, attach a codeframe, and classify the failure for a cause/fix. The caller is responsible\n * for running Vite's `ssrFixStacktrace` first so the frames point at real source.\n */"
+  },
+  {
+    "name": "BuildDiagnosticOptions",
+    "kind": "interface",
+    "package": "@nifrajs/web",
+    "signature": "export interface BuildDiagnosticOptions {\n    readonly request?: {\n        readonly method: string;\n        readonly url: string;\n    };\n    /** Project root; frames outside it are treated as non-user. Defaults to `process.cwd()`. */\n    readonly root?: string;\n    /** Injectable source reader (tests pass a fake; production reads the filesystem). */\n    readonly read?: SourceReader;\n}"
+  },
   {
     "name": "buildManifest",
     "kind": "function",
@@ -1718,6 +1745,13 @@
     "package": "@nifrajs/core",
     "signature": "export type ClassifiedSchema<S extends object> = S & {\n    readonly [CLASSIFICATION]: DataClassification;\n};"
   },
+  {
+    "name": "classify",
+    "kind": "function",
+    "package": "@nifrajs/web",
+    "signature": "export declare function classify(name: string, message: string): {\n    code: string;\n    cause?: string;\n    fix?: string;\n    docsAnchor?: string;\n};",
+    "doc": "/** Classify an error name+message against the catalog; falls back to the generic unhandled code. */"
+  },
   {
     "name": "CLAUDE_MD_PATH",
     "kind": "const",
@@ -1823,6 +1857,13 @@
     "package": "@nifrajs/web",
     "signature": "export interface CloudflareRouteRules {\n    readonly include: readonly string[];\n    readonly exclude: readonly string[];\n    /** Public files the budget could not name, so the build can say so instead of capping silently. */\n    readonly omitted: readonly string[];\n}"
   },
+  {
+    "name": "Codeframe",
+    "kind": "interface",
+    "package": "@nifrajs/web",
+    "signature": "export interface Codeframe {\n    readonly file: string;\n    readonly line: number;\n    readonly column?: number | undefined;\n    readonly lines: ReadonlyArray<{\n        readonly number: number;\n        readonly text: string;\n        readonly caret: boolean;\n    }>;\n}",
+    "doc": "/** A source window around the offending line. `caret` marks the exact line the top frame points at. */"
+  },
   {
     "name": "Collection",
     "kind": "interface",
@@ -2316,7 +2357,7 @@
     "name": "CreateMcpServerOptions",
     "kind": "interface",
     "package": "@nifrajs/mcp",
-    "signature": "export interface CreateMcpServerOptions {\n    readonly name: string;\n    readonly version: string;\n    readonly tools?: readonly McpTool[];\n    /** MCP Apps widgets - their resources are registered and the UI capability is advertised. */\n    readonly widgets?: readonly McpWidget[];\n    /** Extra (non-widget) resources to expose. */\n    readonly resources?: readonly McpResource[];\n    readonly prompts?: readonly McpPrompt[];\n    /** GET health-page text. */\n    readonly health?: string;\n    /** Max JSON-RPC body size in bytes (default 1 MB). */\n    readonly maxBodyBytes?: number;\n}"
+    "signature": "export interface CreateMcpServerOptions {\n    readonly name: string;\n    readonly version: string;\n    readonly tools?: readonly McpTool[];\n    /** MCP Apps widgets - their resources are registered and the UI capability is advertised. */\n    readonly widgets?: readonly McpWidget[];\n    /** Extra (non-widget) resources to expose. */\n    readonly resources?: readonly McpResource[];\n    readonly prompts?: readonly McpPrompt[];\n    /** GET health-page text. */\n    readonly health?: string;\n    /** Max JSON-RPC body size in bytes (default 1 MB). */\n    readonly maxBodyBytes?: number;\n    /** Natural-language guidance for LLMs, surfaced in the modern `server/discover` result (2026-07-28). */\n    readonly instructions?: string;\n    /** Origin allowlist for the DNS-rebinding guard. Omit to allow any origin; set it to reject other\n     * browser origins with 403 (e.g. a hardened, non-public mount). */\n    readonly allowedOrigins?: readonly string[];\n}"
   },
   {
     "name": "createMemoryCausalityStore",
@@ -2931,8 +2972,7 @@
     "name": "devtools",
     "kind": "function",
     "package": "@nifrajs/devtools",
-    "signature": "export declare function devtools(options?: DevToolsOptions | undefined): import(\"@nifrajs/core/server\").NifraPlugin<import(\"@nifrajs/core/server\").AnyServer, import(\"@nifrajs/core/server\").AnyServer>;",
-    "doc": "/**\n * DevTools plugin. Its observation adapter projects the single request span into a\n * `DevToolsEvent`; its middleware only owns the secured SSE transport.\n * When configuring `tracing()` yourself, register it before this plugin so DevTools attaches to\n * that request owner.\n */"
+    "signature": "export declare function devtools(options?: DevToolsOptions | undefined): import(\"@nifrajs/core/server\").NifraPlugin<import(\"@nifrajs/core/server\").AnyServer, import(\"@nifrajs/core/server\").AnyServer>;"
   },
   {
     "name": "DevToolsClientOptions",
@@ -2960,6 +3000,34 @@
     "package": "@nifrajs/devtools",
     "signature": "export interface DevToolsOptions {\n    /** Maximum events to retain in the ring buffer (default 200). */\n    readonly maxEvents?: number | undefined;\n    /** Maximum simultaneous SSE connections (default 5). */\n    readonly maxConnections?: number | undefined;\n    /** SSE path (default `/_nifra/devtools`). */\n    readonly path?: string | undefined;\n    /** Explicit enable switch. Defaults to true only when `NODE_ENV === \"development\"`. */\n    readonly enabled?: boolean | undefined;\n    /** Permit non-loopback URL hosts. Default false. */\n    readonly allowRemote?: boolean | undefined;\n    /** Additional origins permitted to open the stream. Same-origin requests are always allowed. */\n    readonly allowedOrigins?: readonly string[] | undefined;\n    /** Optional request authorization for the stream. */\n    readonly authorize?: ((request: Request) => boolean | Promise<boolean>) | undefined;\n    /**\n     * Interval for SSE keep-alive comment frames, in milliseconds (default 15000). Pings stop\n     * idle proxies/dev tunnels from dropping the stream and evict dead connections so they no\n     * longer count against `maxConnections`.\n     */\n    readonly pingIntervalMs?: number | undefined;\n}"
   },
+  {
+    "name": "DevToolsQuery",
+    "kind": "interface",
+    "package": "@nifrajs/devtools",
+    "signature": "export interface DevToolsQuery {\n    readonly path?: string | undefined;\n    readonly limit?: number | undefined;\n}",
+    "doc": "/** Query for a DevTools state snapshot: an optional `path` prefix and a most-recent-`limit`. */"
+  },
+  {
+    "name": "Diagnostic",
+    "kind": "interface",
+    "package": "@nifrajs/web",
+    "signature": "export interface Diagnostic {\n    /** Stable, greppable identifier, e.g. `NIFRA_SERVER_ONLY_IN_CLIENT`. `NIFRA_UNHANDLED` when unrecognised. */\n    readonly code: string;\n    readonly name: string;\n    readonly message: string;\n    readonly request?: {\n        readonly method: string;\n        readonly url: string;\n    } | undefined;\n    readonly frames: readonly DiagnosticFrame[];\n    readonly codeframe?: Codeframe | undefined;\n    /** Plain-language \"why this happened\", when the failure is recognised. */\n    readonly cause?: string | undefined;\n    /** Plain-language \"do this\", when the failure is recognised. */\n    readonly fix?: string | undefined;\n    /** Docs section anchor for the code, e.g. `errors#server-only-in-client`. */\n    readonly docsAnchor?: string | undefined;\n}",
+    "doc": "/** The structured failure. Serialisable as-is to JSON for the agent surfaces. */"
+  },
+  {
+    "name": "DIAGNOSTIC_CATALOG",
+    "kind": "const",
+    "package": "@nifrajs/web",
+    "signature": "export declare const DIAGNOSTIC_CATALOG: readonly CatalogEntry[];",
+    "doc": "/**\n * The recognised-failure catalog. Seeded with the highest-signal nifra failures; extend it as new\n * classes of error earn a stable code. Order matters only in that the first match wins.\n */"
+  },
+  {
+    "name": "DiagnosticFrame",
+    "kind": "interface",
+    "package": "@nifrajs/web",
+    "signature": "export interface DiagnosticFrame {\n    readonly raw: string;\n    readonly file?: string;\n    readonly line?: number;\n    readonly column?: number;\n}",
+    "doc": "/** One parsed stack frame. `file`/`line`/`column` are present only when the frame could be located. */"
+  },
   {
     "name": "diffManifestRoutes",
     "kind": "function",
@@ -3526,6 +3594,20 @@
     "signature": "export interface Example {\n    readonly name: string;\n    /** The doc page's title, e.g. \"Nifra - Auth & sessions\". */\n    readonly topic: string;\n    /** The doc page slug, e.g. \"auth\" - a short, matchable tag. */\n    readonly slug: string;\n    readonly code: string;\n}",
     "doc": "/**\n * `nifra_example` - verified, copy-pasteable code examples for agents. The corpus is `examples.json`\n * (written into this package by `bun run gen:llms`): the same doc snippets `check:docs` typechecks\n * against the live `@nifrajs/*` API. So every example this returns is GUARANTEED to compile against the\n * installed version - the antidote to an agent hallucinating a framework API from stale training.\n *\n * Keyword-scored over each example's name/topic/slug (curated identifiers, heavily weighted) and its\n * code body. No query → a grouped index of what's available (the cheap discovery call).\n */"
   },
+  {
+    "name": "examplesAppTool",
+    "kind": "function",
+    "package": "@nifrajs/cli",
+    "signature": "export declare function examplesAppTool(loadExamples: () => Promise<Example[] | undefined>): McpTool;",
+    "doc": "/** The widget-backed tool. `loadExamples` is injected (disk on the CLI, cached fetch on the edge). */"
+  },
+  {
+    "name": "examplesWidget",
+    "kind": "const",
+    "package": "@nifrajs/cli",
+    "signature": "export declare const examplesWidget: import(\"@nifrajs/mcp\").McpWidget;",
+    "doc": "/** The widget: renders `structuredContent.examples` as a filterable list of example cards. */"
+  },
   {
     "name": "executeCapability",
     "kind": "function",
@@ -3732,6 +3814,27 @@
     "signature": "export interface FileType {\n    /** Detected MIME type, e.g. `\"image/png\"`. */\n    readonly mime: string;\n    /** Canonical extension (no dot), e.g. `\"png\"`. */\n    readonly ext: string;\n}",
     "doc": "/**\n * Magic-byte file-type detection - trust the bytes, not the `Content-Type` header (which a client\n * sets freely). Reads only the leading bytes; dependency-free + edge-safe. Covers the common upload\n * types; returns `null` for anything unrecognized (incl. text formats like SVG/CSV that have no magic\n * number - handle those explicitly if you accept them).\n */"
   },
+  {
+    "name": "filterDevToolsEvents",
+    "kind": "function",
+    "package": "@nifrajs/devtools",
+    "signature": "export declare function filterDevToolsEvents(events: readonly DevToolsEvent[], query?: DevToolsQuery): DevToolsEvent[];",
+    "doc": "/**\n * Filter a DevTools event buffer for a snapshot query - by `path` prefix and/or the most recent\n * `limit`. Pure, so the `/state` endpoint and its tests (and the `nifra_inspect` MCP tool that reads\n * that endpoint) share ONE definition of what a query returns.\n */"
+  },
+  {
+    "name": "findRoutePathLiteral",
+    "kind": "function",
+    "package": "@nifrajs/ts-plugin",
+    "signature": "export declare function findRoutePathLiteral(tsm: typeof ts, source: ts.SourceFile, position: number): {\n    text: string;\n    span: ts.TextSpan;\n} | undefined;",
+    "doc": "/**\n * If `position` sits on a string-literal route path (`\"/...\"`), return its text and the span INSIDE the\n * quotes (so the editor highlights the path, not the quotes). Exported for unit testing against a\n * `SourceFile` built with `ts.createSourceFile`.\n */"
+  },
+  {
+    "name": "findRoutesDir",
+    "kind": "function",
+    "package": "@nifrajs/ts-plugin",
+    "signature": "export declare function findRoutesDir(fromFile: string, exists?: (p: string) => boolean): string | undefined;",
+    "doc": "/** Walk up from a source file to the nearest directory that has a `routes/` folder - the app root. */"
+  },
   {
     "name": "fixedBackoff",
     "kind": "const",
@@ -4054,7 +4157,7 @@
     "kind": "function",
     "package": "@nifrajs/cli",
     "signature": "export declare function handleMcpHttp(request: Request): Promise<Response>;",
-    "doc": "/** The CLI HTTP handler: serves the disk-backed corpus tools. (`nifra docs-mcp` / `bun run` this file.) */"
+    "doc": "/** The CLI HTTP handler: serves the disk-backed corpus tools + registers the examples widget's `ui://`\n * resource so MCP Apps hosts can render `nifra_examples_app`. (`nifra docs-mcp` / `bun run` this file.) */"
   },
   {
     "name": "Handler",
@@ -4937,7 +5040,7 @@
     "name": "JsonRpcResponse",
     "kind": "type",
     "package": "@nifrajs/mcp",
-    "signature": "export type JsonRpcResponse = {\n    jsonrpc: \"2.0\";\n    id: JsonRpcId;\n    result: unknown;\n} | {\n    jsonrpc: \"2.0\";\n    id: JsonRpcId;\n    error: {\n        code: number;\n        message: string;\n    };\n};"
+    "signature": "export type JsonRpcResponse = {\n    jsonrpc: \"2.0\";\n    id: JsonRpcId;\n    result: unknown;\n} | {\n    jsonrpc: \"2.0\";\n    id: JsonRpcId;\n    error: {\n        code: number;\n        message: string;\n        data?: unknown;\n    };\n};"
   },
   {
     "name": "JsonSchema",
@@ -5071,6 +5174,13 @@
     "package": "@nifrajs/middleware",
     "signature": "export interface LanguageOptions<L extends readonly string[]> {\n    readonly supported: L;\n    readonly defaultLanguage: L[number];\n    /** Emit `Content-Language`. Default `true`. */\n    readonly header?: boolean;\n}"
   },
+  {
+    "name": "LAST_ERROR_PATH",
+    "kind": "const",
+    "package": "@nifrajs/web",
+    "signature": "export declare const LAST_ERROR_PATH = \"/__nifra/last-error\";",
+    "doc": "/** Shared endpoint name used by both dev pipelines and the agent-facing MCP tools. */"
+  },
   {
     "name": "LAYOUT_DATA_GLOBAL",
     "kind": "const",
@@ -5317,6 +5427,13 @@
     "signature": "export declare const MCP_CONFIG: McpConfig;",
     "doc": "/** The one canonical MCP config object both registries serialize - the anti-drift seam. */"
   },
+  {
+    "name": "MCP_ERROR",
+    "kind": "const",
+    "package": "@nifrajs/mcp",
+    "signature": "export declare const MCP_ERROR: {\n    readonly HEADER_MISMATCH: -32020;\n    readonly UNSUPPORTED_VERSION: -32022;\n};",
+    "doc": "/** MCP-reserved JSON-RPC error codes (2026-07-28 error-code policy carves out -32020..-32099 for the spec). */"
+  },
   {
     "name": "MCP_JSON_PATH",
     "kind": "const",
@@ -5375,13 +5492,13 @@
     "name": "McpHttpOptions",
     "kind": "interface",
     "package": "@nifrajs/cli",
-    "signature": "export interface McpHttpOptions {\n    /** Maximum JSON-RPC request body size in bytes. Default 1 MB. */\n    readonly maxBodyBytes?: number;\n    /** Resources / prompts / the MCP Apps UI extension served alongside the tools. */\n    readonly features?: McpServerFeatures;\n    /** Shown on the GET health page so each host can describe itself. */\n    readonly health?: string;\n}"
+    "signature": "export interface McpHttpOptions {\n    /** Maximum JSON-RPC request body size in bytes. Default 1 MB. */\n    readonly maxBodyBytes?: number;\n    /** Resources / prompts / the MCP Apps UI extension served alongside the tools. */\n    readonly features?: McpServerFeatures;\n    /** Shown on the GET health page so each host can describe itself. */\n    readonly health?: string;\n    /**\n     * Origin allowlist for the DNS-rebinding guard. Omit (the default) to allow any origin - the right\n     * choice for a public, unauthenticated docs server that can't enumerate its browser clients' origins.\n     * Set it (e.g. a localhost origin for a hardened local host) to reject any other browser origin with 403.\n     */\n    readonly allowedOrigins?: readonly string[];\n}"
   },
   {
     "name": "McpHttpOptions",
     "kind": "interface",
     "package": "@nifrajs/mcp",
-    "signature": "export interface McpHttpOptions {\n    /** Maximum JSON-RPC request body size in bytes. Default 1 MB. */\n    readonly maxBodyBytes?: number;\n    /** Resources / prompts / the MCP Apps UI extension served alongside the tools. */\n    readonly features?: McpServerFeatures;\n    /** Shown on the GET health page so each host can describe itself. */\n    readonly health?: string;\n}"
+    "signature": "export interface McpHttpOptions {\n    /** Maximum JSON-RPC request body size in bytes. Default 1 MB. */\n    readonly maxBodyBytes?: number;\n    /** Resources / prompts / the MCP Apps UI extension served alongside the tools. */\n    readonly features?: McpServerFeatures;\n    /** Shown on the GET health page so each host can describe itself. */\n    readonly health?: string;\n    /**\n     * Origin allowlist for the DNS-rebinding guard. Omit (the default) to allow any origin - the right\n     * choice for a public, unauthenticated docs server that can't enumerate its browser clients' origins.\n     * Set it (e.g. a localhost origin for a hardened local host) to reject any other browser origin with 403.\n     */\n    readonly allowedOrigins?: readonly string[];\n}"
   },
   {
     "name": "mcpJson",
@@ -5465,7 +5582,7 @@
     "name": "McpServerFeatures",
     "kind": "interface",
     "package": "@nifrajs/mcp",
-    "signature": "export interface McpServerFeatures {\n    readonly resources?: readonly McpResource[];\n    readonly prompts?: readonly McpPrompt[];\n    /** Advertise the MCP Apps UI extension in `initialize`. Present when the server serves `ui://` widgets;\n     * `mimeTypes` defaults to `[UI_MIME]`. */\n    readonly ui?: {\n        readonly mimeTypes?: readonly string[];\n    };\n}"
+    "signature": "export interface McpServerFeatures {\n    readonly resources?: readonly McpResource[];\n    readonly prompts?: readonly McpPrompt[];\n    /** Advertise the MCP Apps UI extension in `initialize`. Present when the server serves `ui://` widgets;\n     * `mimeTypes` defaults to `[UI_MIME]`. */\n    readonly ui?: {\n        readonly mimeTypes?: readonly string[];\n    };\n    /** Natural-language guidance for LLMs on how to use this server. Surfaced in the modern\n     * `server/discover` result (2026-07-28); legacy `initialize` does not carry it. */\n    readonly instructions?: string;\n}"
   },
   {
     "name": "McpTool",
@@ -5831,7 +5948,21 @@
     "name": "MockServerOptions",
     "kind": "interface",
     "package": "@nifrajs/mock",
-    "signature": "export interface MockServerOptions {\n    /** Seed for deterministic mock generation. */\n    readonly seed?: number | undefined;\n    /** Log mock requests to console. */\n    readonly verbose?: boolean | undefined;\n}"
+    "signature": "export interface MockServerOptions {\n    /** Seed for deterministic mock generation. */\n    readonly seed?: number | undefined;\n    /** Log mock requests to console. */\n    readonly verbose?: boolean | undefined;\n    /**\n     * Derive a JSON Schema from a response validator that carries none (zod/valibot expose a Standard Schema\n     * validator but no `.jsonSchema`), so their routes mock real data instead of `{}`. Fail-safe: throwing or\n     * returning undefined falls back to `{}`, as today. Ready-made for zod: `@nifrajs/testing/zod`.\n     *\n     * Defaults to {@link autoReflectJsonSchema}, which recognizes zod by its Standard Schema vendor tag and\n     * converts via `z.toJSONSchema` when zod is installed - so zod routes mock real data with no wiring.\n     * Pass a hook to override, or `() => undefined` to force every opaque schema back to `{}`.\n     */\n    readonly reflectJsonSchema?: (schema: unknown) => JsonSchema | undefined;\n}"
+  },
+  {
+    "name": "MODERN_PROTOCOL_VERSION",
+    "kind": "const",
+    "package": "@nifrajs/mcp",
+    "signature": "export declare const MODERN_PROTOCOL_VERSION = \"2026-07-28\";",
+    "doc": "/** The stateless per-request revision (2026-07-28+). A request carrying its version in `_meta`\n * (`io.modelcontextprotocol/protocolVersion`) is served in modern mode; an `initialize` request stays\n * legacy. This server is dual-era: `handleRpc` answers both on the same dispatch, per request. */"
+  },
+  {
+    "name": "modernVersionOf",
+    "kind": "function",
+    "package": "@nifrajs/mcp",
+    "signature": "export declare function modernVersionOf(params: Record<string, unknown> | undefined): string | undefined;",
+    "doc": "/** The protocol version a modern (2026-07-28+) request declares in `_meta`, or `undefined` for a legacy\n * request. Its presence is what puts the dispatch in modern mode for that one request. */"
   },
   {
     "name": "mountIslands",
@@ -6542,6 +6673,13 @@
     "package": "@nifrajs/content",
     "signature": "export interface ParseEntryOptions<S extends StandardSchemaV1> {\n    readonly raw: string;\n    readonly slug: string;\n    /** Standard Schema validating the frontmatter - a typo'd/missing field throws (a build-time failure,\n     * never a broken page). */\n    readonly schema: S;\n}"
   },
+  {
+    "name": "parseFrames",
+    "kind": "function",
+    "package": "@nifrajs/web",
+    "signature": "export declare function parseFrames(stack: string): DiagnosticFrame[];",
+    "doc": "/**\n * Parse a V8/Node stack into structured frames. Handles the `at fn (path:line:col)`, bare\n * `at path:line:col`, and `at async fn (...)` shapes; a frame that doesn't match keeps its raw text\n * with no location (so nothing is silently dropped).\n */"
+  },
   {
     "name": "parseFrontmatter",
     "kind": "function",
@@ -6918,8 +7056,8 @@
     "name": "PROTOCOL_VERSION",
     "kind": "const",
     "package": "@nifrajs/mcp",
-    "signature": "export declare const PROTOCOL_VERSION = \"2024-11-05\";",
-    "doc": "/**\n * The pure MCP (Model Context Protocol) JSON-RPC dispatch - no I/O, no `Bun.*`, no side effects, so it\n * unit-tests cleanly. A transport (stdio in `@nifrajs/cli`'s `mcp.ts`, Streamable-HTTP in {@link ./http.ts})\n * wires this to a byte stream; the tools/resources are injected, so the protocol logic is exercised\n * without spawning or reading streams.\n *\n * Beyond base MCP this also implements the server half of **MCP Apps (SEP-1865)** - interactive `ui://`\n * widgets: a tool links a UI resource via `_meta.ui.resourceUri`, `tools/call` returns `structuredContent`\n * for the widget to render, and `initialize` advertises the `io.modelcontextprotocol/ui` extension. All of\n * it is additive - a tool whose handler returns a plain `string` behaves exactly as before.\n */"
+    "signature": "export declare const PROTOCOL_VERSION = \"2025-06-18\";",
+    "doc": "/** The protocol revision this server advertises by default. A handshake-era version - the HTTP transport\n * still uses `initialize`; current clients reach it through their backward-compatibility fallback.\n * `initialize` echoes the client's own requested version instead when it's one this server also speaks\n * ({@link SUPPORTED_PROTOCOL_VERSIONS}). */"
   },
   {
     "name": "PublicDirCache",
@@ -6933,7 +7071,7 @@
     "kind": "function",
     "package": "@nifrajs/cli",
     "signature": "export declare function publicDocsTools(): McpTool[];",
-    "doc": "/** The two project-independent tools, reading the package's bundled corpus from disk (CLI use). */"
+    "doc": "/** The project-independent tools, reading the package's bundled corpus from disk (CLI use): the text\n * docs tools plus the `nifra_examples_app` MCP Apps widget tool. */"
   },
   {
     "name": "publicEnvDefines",
@@ -7601,6 +7739,13 @@
     "signature": "export declare function resolvePublicPath(root: string, pathname: string): string | undefined;",
     "doc": "/**\n * Resolve a URL pathname to an absolute path **confined** to `root`, or `undefined` if it escapes.\n *\n * This is a user-path-to-filesystem sink, which makes it the one part of this feature with a security\n * consequence. Decode first (`%2e%2e%2f` is `../`), then normalize, then verify the result is still\n * under `root` by prefix - checking the *resolved* path rather than scanning the input for `..`,\n * because a blocklist over encodings is exactly the kind of check that gets bypassed.\n */"
   },
+  {
+    "name": "resolveRouteFile",
+    "kind": "function",
+    "package": "@nifrajs/ts-plugin",
+    "signature": "export declare function resolveRouteFile(path: string, routes: readonly RouteLocation[]): string | undefined;",
+    "doc": "/**\n * Resolve a route path literal to the first route whose pattern matches it. Query/hash are ignored\n * (a link's `?tab=x` does not change which route file serves it). Returns the route's `file`, or\n * undefined when the value is not a path or matches no route.\n */"
+  },
   {
     "name": "respondMcpHttp",
     "kind": "function",
@@ -7613,7 +7758,7 @@
     "kind": "function",
     "package": "@nifrajs/mcp",
     "signature": "export declare function respondMcpHttp(request: Request, tools: McpTool[], serverInfo: {\n    name: string;\n    version: string;\n}, options?: McpHttpOptions): Promise<Response>;",
-    "doc": "/**\n * Handle one MCP request over HTTP against the given `tools`/`features`. POST a JSON-RPC body → JSON-RPC\n * response; GET → a plain-text health page; OPTIONS → CORS preflight. Never throws - a bad body becomes a\n * JSON-RPC parse error. The dispatch is the shared, transport-agnostic {@link handleRpc}.\n */"
+    "doc": "/**\n * Handle one MCP request over HTTP against the given `tools`/`features`. POST a JSON-RPC body → JSON-RPC\n * response; GET → a plain-text health page; OPTIONS → CORS preflight. Never throws - a bad body becomes a\n * JSON-RPC parse error. Dual-era: a modern (2026-07-28) POST that mirrors its method/name/version into\n * headers is validated against the body before dispatch and gets spec HTTP statuses; legacy requests are\n * served unchanged. The dispatch is the shared, transport-agnostic {@link handleRpc}.\n */"
   },
   {
     "name": "responseCache",
@@ -7920,6 +8065,13 @@
     "signature": "export interface RouteLike {\n    readonly method: string;\n    readonly path: string;\n    readonly schema?: {\n        readonly body?: unknown;\n        readonly query?: unknown;\n        readonly response?: unknown;\n    } | undefined;\n}",
     "doc": "/** A registered route as seen by {@link buildOpenApiDocument} - structurally a `@nifrajs/core`\n * `RouteDescriptor` (so `app.routes()` is passed straight through). */"
   },
+  {
+    "name": "RouteLocation",
+    "kind": "interface",
+    "package": "@nifrajs/ts-plugin",
+    "signature": "export interface RouteLocation {\n    readonly pattern: string;\n    readonly file: string;\n}",
+    "doc": "/** A route as the plugin needs it: its URL pattern and the source file that serves it. */"
+  },
   {
     "name": "RouteManifest",
     "kind": "interface",
@@ -7999,8 +8151,7 @@
     "name": "RouterContext",
     "kind": "const",
     "package": "@nifrajs/web-react",
-    "signature": "export declare const RouterContext: import(\"react\").Context<RouterContextValue>;",
-    "doc": "/** Router context. The default ({} params, \"\" path, {} search) is what a component sees when rendered\n * outside a nifra route tree (the hooks stay defined, no throw, so a stray `useParams` degrades\n * gracefully). */"
+    "signature": "export declare const RouterContext: import(\"react\").Context<RouterContextValue>;"
   },
   {
     "name": "RouterContextValue",
@@ -8074,7 +8225,7 @@
     "name": "rpcError",
     "kind": "const",
     "package": "@nifrajs/mcp",
-    "signature": "export declare const rpcError: (id: JsonRpcId, code: number, message: string) => JsonRpcResponse;"
+    "signature": "export declare const rpcError: (id: JsonRpcId, code: number, message: string, data?: unknown) => JsonRpcResponse;"
   },
   {
     "name": "rpcResult",
@@ -8374,15 +8525,13 @@
     "name": "SearchContext",
     "kind": "const",
     "package": "@nifrajs/web-preact",
-    "signature": "export declare const SearchContext: import(\"preact\").Context<Record<string, unknown>>;",
-    "doc": "/** The current route's validated search, provided by `compose` on SSR + client mount alike (derived from\n * the URL via the shared `searchOfChain`). `{}` outside a nifra route tree. Read via {@link useSearch}. */"
+    "signature": "export declare const SearchContext: import(\"preact\").Context<Record<string, unknown>>;"
   },
   {
     "name": "SearchContext",
     "kind": "const",
     "package": "@nifrajs/web-solid",
-    "signature": "export declare const SearchContext: import(\"solid-js\").Context<Accessor<Record<string, unknown>> | undefined>;",
-    "doc": "/** The current route's validated search accessor, provided by `compose` on SSR + client mount alike\n * (derived from the URL via the shared `searchOfChain`). Read via {@link useSearch}. */"
+    "signature": "export declare const SearchContext: Context<Accessor<Record<string, unknown>> | undefined>;"
   },
   {
     "name": "searchOf",
@@ -9130,6 +9279,20 @@
     "signature": "export declare function solidSvgComponentBunPlugin(generate: \"dom\" | \"ssr\"): BunPlugin;",
     "doc": "/** The Solid SVG-component plugin. `generate` selects the Solid `\"dom\"`/`\"ssr\"` output, matching\n * `solidBunPlugin`. A plain `import \"./icon.svg\"` (asset URL) is untouched - only `?component` matches. */"
   },
+  {
+    "name": "sortRoutesBySpecificity",
+    "kind": "function",
+    "package": "@nifrajs/core",
+    "signature": "export declare function sortRoutesBySpecificity<T extends {\n    readonly pattern: CompiledRoutePattern;\n}>(routes: T[]): T[];",
+    "doc": "/**\n * Sort compiled routes most-specific-first - a static segment beats a dynamic one, the order the router\n * resolves a path in. The single home for that precedence: the web router, the mock server, and the\n * editor plugin all order routes through this one comparator, so which file a path resolves to can never\n * diverge between runtime, client, and editor. Sorts in place and returns the same array.\n */"
+  },
+  {
+    "name": "SourceReader",
+    "kind": "type",
+    "package": "@nifrajs/web",
+    "signature": "export type SourceReader = (file: string) => string | undefined;",
+    "doc": "/** Reads a source file's text, or returns undefined if it cannot (missing, binary, permission). */"
+  },
   {
     "name": "SpanStatus",
     "kind": "type",
@@ -9855,6 +10018,13 @@
     "signature": "export declare class TopicRegistry {\n    private readonly topics;\n    private readonly memberships;\n    subscribe(topic: string, ws: NifraWebSocket): void;\n    unsubscribe(topic: string, ws: NifraWebSocket): void;\n    /** Drop every subscription for a connection - called on close so a registry never leaks dead sockets. */\n    unsubscribeAll(ws: NifraWebSocket): void;\n    /** Send `data` to every connection subscribed to `topic`. Per-socket send errors are isolated. */\n    publish(topic: string, data: string | ArrayBufferView | ArrayBuffer): void;\n}",
     "doc": "/**\n * In-process pub/sub for `ws.subscribe(topic)` + `app.publish(topic, data)`. **Single-instance only** -\n * topics live in this process's memory, so a multi-instance deploy (multiple servers behind a load\n * balancer) needs an external fan-out (Redis pub/sub, a Cloudflare Durable Object, NATS, …) bridged to\n * `app.publish`. The same registry instance is shared by an app's connections and its `publish`.\n */"
   },
+  {
+    "name": "topUserFrame",
+    "kind": "function",
+    "package": "@nifrajs/web",
+    "signature": "export declare function topUserFrame(frames: readonly DiagnosticFrame[], root: string | undefined): DiagnosticFrame | undefined;",
+    "doc": "/** The first frame that points at the user's own source - what the codeframe should show. */"
+  },
   {
     "name": "TraceContext",
     "kind": "type",
@@ -10048,8 +10218,7 @@
     "name": "UnsupportedMockSchemaError",
     "kind": "class",
     "package": "@nifrajs/mock",
-    "signature": "export declare class UnsupportedMockSchemaError extends Error {\n    readonly keyword: string;\n    constructor(keyword: string, message: string);\n}",
-    "doc": "/**\n * `@nifrajs/mock` - contract-based mock server.\n *\n * Reads a Nifra app's registered routes and their Standard Schema / JSON Schema\n * response definitions, then generates fake responses from supported JSON Schema keywords. Use it\n * for frontend-first development, agent testing, or CI smoke tests.\n */"
+    "signature": "export declare class UnsupportedMockSchemaError extends Error {\n    readonly keyword: string;\n    constructor(keyword: string, message: string);\n}"
   },
   {
     "name": "UploadResult",
@@ -10631,14 +10800,14 @@
     "name": "VERSION",
     "kind": "const",
     "package": "@nifrajs/core",
-    "signature": "export declare const VERSION: \"2.3.0\";",
+    "signature": "export declare const VERSION: \"2.5.0\";",
     "doc": "/**\n * Current package version. A hardcoded literal on purpose - core runs on the edge (no fs), so it can't\n * read its own package.json at runtime. `scripts/version.ts` rewrites it on every release bump and\n * `check:publish` asserts it equals `@nifrajs/core`'s package version.\n */"
   },
   {
     "name": "VERSION",
     "kind": "const",
     "package": "nifra",
-    "signature": "export declare const VERSION: \"2.3.0\";",
+    "signature": "export declare const VERSION: \"2.5.0\";",
     "doc": "/**\n * Current package version. A hardcoded literal on purpose - core runs on the edge (no fs), so it can't\n * read its own package.json at runtime. `scripts/version.ts` rewrites it on every release bump and\n * `check:publish` asserts it equals `@nifrajs/core`'s package version.\n */"
   },
   {
@@ -10933,5 +11102,12 @@
     "package": "@nifrajs/client",
     "signature": "export interface WsHandle<In, Out> {\n    /** Send one typed frame (JSON-encoded). Queued until the socket opens, so it never throws. */\n    send(message: In): void;\n    /** Async-iterate incoming typed frames. Ends when the socket closes (or `signal` aborts). */\n    messages(options?: {\n        signal?: AbortSignal;\n    }): AsyncIterableIterator<Out>;\n    /** Callback form of {@link messages}; returns an unsubscribe. */\n    onMessage(callback: (message: Out) => void): () => void;\n    /** Resolves when the socket is open (rejects on a connect failure). */\n    readonly opened: Promise<void>;\n    close(code?: number, reason?: string): void;\n    /** The underlying socket, for anything off the typed contract (binary frames, bufferedAmount…). */\n    readonly raw: WebSocket;\n}",
     "doc": "/**\n * A live typed WebSocket connection to an `app.ws()` route. `send` accepts the route's\n * `messageSchema` input type (validated server-side at the trust boundary); received frames are\n * typed from its `sendSchema` and JSON-parsed. Binary frames are not part of the typed contract\n * and are ignored by `messages()`/`onMessage` - use `raw` for them.\n */"
+  },
+  {
+    "name": "zodJsonSchema",
+    "kind": "function",
+    "package": "@nifrajs/testing",
+    "signature": "export declare function zodJsonSchema(schema: unknown): JsonSchema | undefined;",
+    "doc": "/**\n * Convert a zod schema to a JSON Schema the mock/mutation generators understand, or `undefined` when the\n * value is not a convertible zod schema. Options chosen for this consumer:\n *   - target \"draft-7\" → the keyword set `@nifrajs/mock` + the laboratory's `candidateMutations` read\n *   - io \"input\"       → the request-side constraints a hostile payload must violate (pre-transform)\n *   - reused \"inline\"  → no `$ref`/`$defs`; the mock generator fails closed on `$ref`\n *\n * Fail-safe: a non-zod value, or an unconvertible schema, returns `undefined` → the schema stays opaque\n * (NO_WITNESS / `{}`), exactly as before this bridge existed.\n */"
   }
 ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/cli",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "The nifra CLI - zero-config dev/build/start for a nifra app (`nifra dev`, `nifra build`, `nifra start`).",
   "keywords": [
     "bun",
@@ -41,14 +41,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@nifrajs/client": "2.3.0",
-    "@nifrajs/core": "2.3.0",
-    "@nifrajs/mcp": "2.3.0",
-    "@nifrajs/runner": "2.3.0",
-    "@nifrajs/schema": "2.3.0",
-    "@nifrajs/testing": "2.3.0",
-    "@nifrajs/web": "2.3.0",
-    "create-nifra": "2.3.0"
+    "@nifrajs/client": "2.5.0",
+    "@nifrajs/core": "2.5.0",
+    "@nifrajs/mcp": "2.5.0",
+    "@nifrajs/runner": "2.5.0",
+    "@nifrajs/schema": "2.5.0",
+    "@nifrajs/testing": "2.5.0",
+    "@nifrajs/web": "2.5.0",
+    "create-nifra": "2.5.0"
   },
   "repository": {
     "type": "git",

package/src/check.ts

@@ -1204,6 +1204,7 @@ export interface CheckDiagnostic {
     | "response-route"
     | "undeclared-dependency"
     | "duplicate-install"
+    | "stale-workspace-dist"
     | "server-manifest-drift"
     | "manifest-drift"
     | "capability-assurance"
@@ -1709,10 +1710,14 @@ export async function collectCheckResult(
     }
     for (const finding of dr.duplicateInstalls) {
       const copies = finding.copies.map((copy) => `${copy.version} at ${copy.path}`).join("; ")
+      const identityHint =
+        finding.package === "@nifrajs/core"
+          ? " (a second @nifrajs/core collapses `typeof backend` to `any` at `.merge()` - usually that error's root cause)"
+          : ""
       diagnostics.push({
         rule: "duplicate-install",
         severity: "error",
-        message: `${finding.package} resolves to multiple physical copies (${copies}) - module identity is unsafe`,
+        message: `${finding.package} resolves to multiple physical copies (${copies}) - module identity is unsafe${identityHint}`,
         fix: "align dependency ranges and reinstall from the workspace root",
         suggestion: {
           kind: "manual",
@@ -1725,6 +1730,28 @@ export async function collectCheckResult(
         },
       })
     }
+    // Advisory (never fails the gate): while actively editing a linked package its dist is always
+    // momentarily behind. The finding earns its keep when a dev server is about to start against it -
+    // Bun reads live `src` while Vite's SSR runner reads the artifact, so a stale one 500s inside
+    // framework/shared-package code and reads exactly like an upstream regression.
+    for (const f of dr.staleDists) {
+      diagnostics.push({
+        rule: "stale-workspace-dist",
+        severity: "warning",
+        message: f.missing
+          ? `${f.package} was never built - ${f.distFile} is missing, but its export map serves it to Vite SSR/node consumers while Bun reads src - rebuild ${f.package}`
+          : `${f.package} has a stale build artifact - ${f.distFile} is ${f.behindSeconds}s older than ${f.sourceFile}, and Vite SSR/node consumers read the artifact while Bun reads src - rebuild ${f.package}`,
+        fix: `rebuild ${f.package}`,
+        suggestion: {
+          kind: "manual",
+          title: `Rebuild ${f.package}`,
+          steps: [
+            `Run the package's build (usually \`bun run build\` in its directory) so ${f.distFile} matches its source again.`,
+            "Only workspace-linked installs drift; npm tarballs are immutable and never flagged.",
+          ],
+        },
+      })
+    }
   }
   // #7: a committed server-manifest.ts that drifted from routes/ - name the exact missing/extra routes.
   for (const f of manifestDrift) {
@@ -1944,6 +1971,7 @@ export async function runCheck(
     ["response-route", "route returns a raw Response (typed client → data: never)"],
     ["undeclared-dependency", "undeclared dependency in package.json"],
     ["duplicate-install", "duplicate identity-sensitive dependency install"],
+    ["stale-workspace-dist", "workspace-linked dist older than its source"],
     ["server-manifest-drift", "server-manifest.ts drifted from routes/"],
     ["manifest-drift", "versioned trust manifest drift"],
     ["capability-assurance", "effect/capability assurance"],
@@ -1951,7 +1979,7 @@ export async function runCheck(
     ["check-config", "nifra.check.json"],
   ] as const) {
     const ds = counts(rule)
-    if (rule === "response-route") {
+    if (rule === "response-route" || rule === "stale-workspace-dist") {
       // Advisory: surfaced with ⚠, never folded into pass/fail.
       console.log(ds.length === 0 ? `✓ ${label}: none` : `⚠ ${label}: ${ds.length} (advisory)`)
     } else if (rule !== "typecheck") {