[P2] Make generated-route typing reliable for clean checks and every consuming TS project, rather than an existence check in one program

[ScriptedAlchemy]

User problem

The basic promise is that an authored route gives the browser, providers and tests current types. Today that promise depends on a prior build/dev/validate command and on correctly including .agent-bundle/routes.d.ts in the actual consuming TypeScript program. A successful unrelated project can mask a missing augmentation.

Audited 14c9822bc6c01d8ff2788454d0e1dc7861bc3816; source review, no fresh TypeScript invocation. This is a focused authoring follow-up, not a claim that generated typing is unimplemented.

Concrete evidence

• routes/typegen-program.ts returns no diagnostic if the file is absent, or if any one directly referenced program includes it. For a solution containing tsconfig.node.json and tsconfig.app.json, the node project can include the declaration while the browser project does not; AB4834 then reports no problem even though App route IDs/results fall back to weaker types in the browser program. Nested references are not traversed.
• MCP starter package scripts expose plain tsc as typecheck; the larger check script happens to run build first. The generated file is intentionally gitignored.
• typegen.ts already owns atomic publication. Reuse that implementation and the canonical graph; no second route parser is required.

Required simplification

Provide one documented reliable entry for generating current contracts before an isolated typecheck, using existing validation/type generation where sufficient. A lightweight explicit command or shared template script is acceptable; a second compiler is not. Do not force a full production bundle just to learn route IDs. Update the starter so the documented typecheck is correct from a clean checkout and after route changes, not merely after some other workflow warmed generated output.

Make the inclusion diagnostic correspond to the program that actually consumes the framework's augmented contracts. Do not require generated types in unrelated build-only projects. If automatic consumption detection would require invasive source analysis, allow the relevant tsconfig selections explicitly and validate those; do not claim global type safety from an existential check over references.

Acceptance

• Clean project: the documented typecheck creates current declarations or stops with an actionable prerequisite error; it must not silently succeed with weakened route types.
• Add/rename/delete a route and change its schema/provider keys; the next check sees the new contract without restarting a dev server.
• Solution-style root with separate browser/server configs: inclusion in the server project cannot hide exclusion from the browser consumer.
• Nested references, extends, excluded declarations and case-sensitive paths are tested; unrelated projects are not forced to import framework types.
• Invalid route ID/input/result access is tested as a negative compile case in the actual App program.
• Failed generation never replaces a valid declaration with partial content; stale output is not described as fresh.
• Static-only plugins remain free of unnecessary route declarations/runtime dependencies.

Document dev, build, typecheck and CI behavior once. Delete consumer-specific shell existence probes when the supported path is adopted. Do not silently edit all user tsconfigs, run user tool/provider code for metadata, or impose a TypeScript major upgrade to solve a generation-order problem.

[ScriptedAlchemy]

Separate correctness axis found during the continuation: #752

I traced the actual generated contract at 14c9822bc6c01d8ff2788454d0e1dc7861bc3816 and filed #752: caller input is currently derived from the schema's _output, so an otherwise valid defaulted input can be rejected by the App client's TypeScript contract. That is different from this issue's declaration freshness and TS-program inclusion.

Keep the fixes independent but prove them together: a clean generated project with z.object({ limit: z.number().default(10) }) must allow client.call(id, {}) in the actual browser program, while the handler still receives a required numeric limit. The check should also fail for a wrong route ID or wrong required input. A fresh declaration with the wrong input semantics and a correct declaration omitted from the consuming program are both insufficient.

Reuse the existing graph/type-only imports/atomic writer. Do not execute route modules to obtain types, ship server imports to the browser, silence the program with skipLibCheck or replace it with a test-only handwritten AppRegister. Static-only projects should remain unaffected. No local TypeScript run was executed in this audit; the new issue identifies the source chain and required regression cases.