Contract introspection: manifest export, docs generation, and contract-diff tooling

[btravers]

Motivation

oRPC (and tRPC/OpenAPI ecosystems generally) get enormous leverage from making contracts introspectable: oRPC generates OpenAPI 3.1 from a contract or router, falling back to Standard JSON Schema when no dedicated converter matches. There is no AsyncAPI-for-Temporal equivalent — nothing in the Temporal ecosystem answers "what runs on this task queue?" without reading source.

Since temporal-contract already builds on Standard Schema (~standard), most of the machinery is available: schemas can be converted to JSON Schema via each library's converter (Zod/Valibot/ArkType all offer one), and the contract shape itself is a plain serializable object.

Proposal

A new package (e.g. @temporal-contract/introspection) providing:

1. Manifest export — toManifest(contract) producing a stable JSON document: task queue, workflows (input/output/signals/queries/updates/search attributes), activities (global + workflow-local), typed error taxonomy (errors maps with JSON-schema payloads and nonRetryable flags), and contract-level defaultOptions. Pluggable schema→JSON-Schema converters keyed on ~standard.vendor, with a Standard JSON Schema fallback (same pattern as oRPC's JsonSchemaConverter interface).

2. Docs generation — render the manifest as markdown (or a VitePress data source) so a contract published across team boundaries carries human-readable documentation: the "catalog page" for a task queue.

3. Contract diff — compare two manifests and classify changes by Temporal-specific risk. This is the killer app: contract evolution in Temporal is more dangerous than in HTTP because running workflows replay old histories. Classifications like:

   • input schema narrowed → breaks new starts from old clients
   • output schema changed → breaks in-flight handle.result() consumers
   • activity removed/renamed → breaks in-flight workflows on replay
   • error nonRetryable flipped → silent retry-semantics change
   • defaultOptions timeout changes → operational change, warn

   Usable in CI: temporal-contract diff old.json new.json --fail-on breaking.

Notes

• Depends on nothing Temporal-side; pure contract-package consumer.
• The typed-errors feature (errors maps) makes the error taxonomy part of the manifest for free.
• Prior art: oRPC OpenAPIGenerator (https://v2.orpc.dev/docs/openapi/specification), Standard JSON Schema fallback behavior.

🤖 Generated with Claude Code