Application IR: resolve local schema imports so one route contract can drive MCP, CLI argv, Apps, and generated types

[ScriptedAlchemy]

Problem

A real framework consumer, ScriptedAlchemy/cargo-hauler, has to duplicate a route schema because Agent Bundle's static CLI argv extraction cannot consume the same imported schema that MCP/runtime validation uses.

Concrete example: cargo-hauler/src/cli/status.tsx contains an inline z.object(...) solely because the compiler reports AB4814 when the route imports the canonical statusInputSchema from src/lib/protocol-schemas.ts. A test then exists to pin the duplicate CLI schema to the protocol schema.

Meanwhile src/mcp/hauler/tools/hauler_status.tsx can simply do:

export const inputSchema = statusInputSchema;
export const resultSchema = statusResultSchema;

The framework therefore turns one logical operation contract into two authored schemas plus a compatibility test.

This conflicts with #592's intended architecture: route discovery should produce one Application IR contract that downstream MCP, CLI, browser, test, and host projections consume.

Direction

Extend static route-contract extraction so local, statically analyzable schema imports are resolved rather than requiring the schema AST to be written inline in the route module.

This should be intentionally bounded. Do not execute arbitrary user modules during discovery.

A useful supported subset:

• relative imports only;
• exported z.object, z.enum, arrays/unions/optional/default/describe and other already-supported schema AST forms;
• const references whose initializer is itself statically analyzable;
• one or more local hops with cycle detection;
• deterministic diagnostics naming the unresolved symbol/path when analysis crosses the supported boundary.

The compiler should canonicalize the result into Application IR once. CLI argv projection, MCP JSON Schema, generated route types, Workbench, and tests should consume that same normalized schema representation.

Longer-term API

The important contract is not "make AB4814 more permissive". It is:

source schema
    ↓
canonical RouteContract IR
    ├─ MCP input/output schema
    ├─ CLI argv grammar
    ├─ generated route/client types
    ├─ Workbench editor
    └─ projection tests

The same mechanism should cover imported resultSchema, and should become the basis for the typed MCP App client requested separately rather than making Apps hand-copy protocol shapes.

Acceptance

• A CLI route may import { statusInputSchema } from '../../lib/protocol-schemas.js' and export it as inputSchema when the imported schema is statically analyzable.
• The generated argv grammar is identical to the inline form.
• MCP and CLI routes importing the same schema produce one canonical normalized contract in the application graph.
• Local enum/const references used by the schema are resolved without duplicating literals in the route file.
• Unsupported dynamic construction fails with a specific diagnostic containing the import/symbol chain, not a generic static-analysis failure.
• Cycles are deterministic and fail cleanly.
• No user module execution is required for discovery.
• cargo-hauler can delete its duplicated status CLI schema and the schema-compat pinning test.

Consumer evidence

• ScriptedAlchemy/cargo-hauler/src/cli/status.tsx
• ScriptedAlchemy/cargo-hauler/src/mcp/hauler/tools/hauler_status.tsx
• Meta-framework architecture: one application graph, capability-driven projections, one execution kernel #592

[ScriptedAlchemy]

Design: canonical RouteContract from statically resolved local schema imports

Posting before implementation so #594/#595/#596 can rely on the names. Vocabulary follows #592: today's CompiledRouteGraph (routes/types.ts) is the Application IR; this issue adds the first graph-level node that routes reference instead of carry — #592's RouteNode.input?: SchemaRef.

IR shape (packages/agent-bundle/src/routes/types.ts, exported from agent-bundle/routes)

/** Where a contract's schema is declared: the module and the binding whose
 *  initializer is the schema expression — the end of any alias chain. */
export interface RouteContractOrigin {
  readonly binding: string;   // 'statusInputSchema', or 'inputSchema' for a route-local literal
  readonly module: string;    // project-relative POSIX path, e.g. 'src/lib/protocol-schemas.ts'
}

/** Application IR (#592 §1): one canonical input contract, normalized once and
 *  shared by every route that binds the same declared schema. */
export interface RouteContract {
  readonly id: string;                  // `contract:<module>#<binding>`
  readonly input: RouteInputSchema;     // the bounded JSON Schema subset, deep-frozen
  readonly origin: RouteContractOrigin;
  readonly routes: readonly string[];   // sorted route ids bound to it
}

interface CompiledAgentRoute {
  /** Id of the RouteContract this route binds; absent when no static contract was extracted. */
  readonly contract?: string;
  /** Unchanged: the same frozen object as the contract's `input` (denormalized for every existing reader). */
  readonly inputSchema?: RouteInputSchema;
}

interface CompiledRouteGraph {
  /** Sorted by id; absent when no route has a static contract, so pre-#593 graphs digest unchanged. */
  readonly contracts?: readonly RouteContract[];
}

• Identity is the declaration site, not the content. tool:hauler/hauler_status and cli:status both importing statusInputSchema bind contract:src/lib/protocol-schemas.ts#statusInputSchema — one node, two routes. Two textually equal but separately declared schemas stay two contracts (they are two authored things that may diverge). A route-local literal is its own contract (contract:src/cli/status.tsx#inputSchema).
• Canonicalize once, consume everywhere. The extractor produces one deep-frozen RouteInputSchema per contract; route.inputSchema, the CLI argv grammar (CompiledCliOption[]), the route manifest the Workbench reads, inspect --routes, and the graph digest all read that object. No consumer re-parses.
• Digest. routeIdentity gains contract only when the origin module differs from the route module (an imported schema is new information; an inline one already digests through inputSchema), so existing graphs keep their recorded digests.
• Result schemas. The contract carries the input side. resultSchema may be imported the same way today: the contract scan (AB4810/AB4815) only requires the named export, TypeScript resolves typeof route.resultSchema through the import for the generated route types, and the runtime validates with the real zod object. No static result projection is added here (no consumer needs one yet; MCP Apps: generated typed client + shared bridge runtime from route contracts #594 generates types from the same typeof chain).

Static resolution (no user-module execution)

New leaf routes/module-scope.ts, shared by config-extract.ts (its one-hop string-const resolution is rewired onto it — extract-and-rewire in one change) and input-schema.ts:

• A module's scope = its top-level const bindings (exported or not), named imports, and the names known to be non-const (let/var, destructuring, functions, classes, default/namespace imports).
• A reference resolves through: a local const → its initializer; a named import from a relative specifier that resolves inside the project root (same moduleCandidates order as every other static scan: .js→.ts/.tsx, extensionless → .ts/.tsx/index.*) → that module's export const <importedName>; alias chains (export const a = b) follow across any number of hops; each visited module#binding is recorded so a cycle is detected deterministically.
• Reference positions the schema grammar accepts: the inputSchema initializer itself; a property initializer; the root of a chain (requestStatusSchema.optional() appends to the resolved chain); z.array(<ref>); z.enum(<ref>) where the ref is an as const array of string literals; z.object(<ref>) where the ref is an object literal; .default(<ref>) where the ref is a static literal. The zod grammar itself is unchanged (z.object/strictObject, scalar bases, z.array, optional/default/describe, validation-only refinements) — this issue widens where a schema may be declared, not what it may contain.
• Grammar violations inside a resolved schema stay AB4814, with the position qualified by the declaring module (z.object at src/lib/protocol-schemas.ts:12:5).

Diagnostics (new rows in docs/diagnostics.md; the reference page renders from it)

Code	Severity	Trigger
AB4838	error	A CLI route's inputSchema references a binding the static resolver cannot follow. The message names the import/symbol chain and the boundary crossed: inputSchema → statusInputSchema (src/lib/protocol-schemas.ts) → requestStatuses, imported from "@shared/protocol", which is not a relative module path — likewise a module outside the project, an unreadable/missing module, a missing export const, a let/var/destructured/function/class binding, a default or namespace import, or a dynamic initializer (call, spread, template with substitutions).
AB4839	error	The reference chain is cyclic (a → b → a); the message prints the cycle.

Severity: both are errors only where the static contract is load-bearing — CLI routes, whose argv grammar cannot exist without it (the command does not compile, exactly like AB4814 today). For MCP tool/resource/prompt, script, and event routes the static contract stays optional as it is today (the runtime derives MCP JSON Schema from the real zod object), so an unresolvable schema there emits nothing — making it an error would break every project that legitimately imports a schema from a package. #596's CLI projection on an MCP tool makes the contract load-bearing for that tool and inherits these codes.

What #596 builds on

RouteContract.input is the canonical input grammar a CLI projection maps from; RouteContract.id is what a projected command references; origin is what inspect/Workbench print. The projection never re-derives the schema.

Not in scope

Widening the zod grammar (unions, nested objects, transforms), static result-schema projection, executing modules, non-relative specifiers (package schemas keep working at runtime; they are simply not statically visible).

[ScriptedAlchemy]

Resolved by #603, squash-merged to main as c9546b4. Landed: static resolution of relative inputSchema/config const imports (routes/module-scope.ts), the canonical RouteContract node (contract:<module>#<binding>) on CompiledRouteGraph.contracts / route.contract, argv grammar + MCP schema + manifest + Workbench projected from it, AB4838/AB4839, docs en+zh, and the cargo-hauler dry-run in the PR body. #596 (CLI surface projections) continues from here: design comment at #596 (comment).