Ontogen as shared codegen substrate — evaluate convergence with the zod contract client
Status: open/proposed
Summary
Section titled “Summary”Open/proposed — this ADR frames a convergence evaluation, not a committed migration. It exists so the shared-codegen question is decided deliberately as pumice integrates, rather than by drift.
- Pumice (D-0016-pumice-app-integration) brings ontogen — a Rust
code-generation pipeline (
rust-ontogen, already an external crate) that emits a dual HTTP + Tauri-IPC transport plus a typed TS client from one Rust API definition. See Context. - This monorepo independently solves an adjacent problem: it generates
packages/ts/dashboard-clientfrom a zod contract viagen-client.ts(D-0013-dashboard-app,T-JZL4). Two apps, two “typed client from a schema” pipelines. See Context. - The question: should the workspace standardize on ontogen as the shared codegen substrate, keep the two pipelines separate, or extract a common contract seam? This ADR lays out the options and a recommendation to evaluate, gated on the pumice co-tenant landing. See Decision.
- Ontogen’s dual HTTP+IPC transport also directly answers
T-CKC1’s open “sidecar-HTTP vs Tauriinvoke” question — pumice already ships both from one definition. See Why.
Context
Section titled “Context”Two schema-driven client generators now live (or will live) in the workspace:
| Pipeline | Input | Output | Owner |
|---|---|---|---|
ontogen (rust-ontogen) | Rust API/schema (src-tauri/src/schema, api/v1) | Axum HTTP transport + Tauri IPC transport + TS client/types | apps/pumice (D-0016-pumice-app-integration) |
gen-client.ts | zod contract (plugin/lib/services/dashboard/contract.ts) | packages/ts/dashboard-client typed request/response module | apps/dashboard (T-JZL4) |
Both turn a single source-of-truth schema into a typed client and enforce
drift via a check gate (T-R9WT for ontogen; dashboard-client:check for
the zod path). They are conceptually the same capability with different source
languages (Rust vs TypeScript/zod) and different transport targets.
Decision
Section titled “Decision”This ADR does not commit a migration. It records the convergence question, frames the options, and recommends the sequencing.
Recommended
Section titled “Recommended”- Evaluate convergence after the pumice co-tenant lands (Phase 1 of M-0014-pumice-desktop-app-integration), not before — the two pipelines should coexist while pumice stabilizes.
- Treat ontogen’s dual HTTP+IPC transport as the reference answer to
T-CKC1’s transport question — a Tauri app can expose the same API over HTTP (browser/dev) and IPC (native) from one definition, superseding the sidecar-vs-invokedichotomy that task debated. - Do not fold the zod
dashboard-clientinto ontogen speculatively. Only converge if a concrete need appears (a shared entity model across pumice and the dashboard, or a second Tauri app), consistent with S-0001-co-locate-first-promote-when-shared.
Deferred to the evaluation
Section titled “Deferred to the evaluation”- Whether the substrate’s schema source-of-truth is Rust (ontogen) or TypeScript/zod when the two must share a model, and which direction the adapter seam (S-0008-apps-consume-substrate-through-published-surfaces) runs.
- Two generators is fine until they must agree. Divergent pipelines cost nothing while pumice and the dashboard share no data model. The cost appears only when an entity must be typed identically on both sides — that is the trigger to converge, not “there are two generators.”
- Ontogen is the more capable pipeline where it applies: it already emits Rust transport and TS client from one definition, and it is the load-bearing substrate for a real app. The zod path is lighter and TS-native. Which is “primary” depends on where the shared schema’s source of truth should live — an evaluation, not a foregone conclusion.
- It unblocks
T-CKC1. That task left the desktop data transport open; pumice’s shipped HTTP+IPC dual transport is a working reference, worth studying beforeapps/desktopre-litigates it.
Options considered
Section titled “Options considered”| Option | Shape | Verdict |
|---|---|---|
| Evaluate, coexist for now (recommended) | Keep both; converge on a concrete trigger | Defers risk; matches S-0001 |
| Standardize on ontogen now | Migrate dashboard-client to an ontogen-generated client | Premature; no shared model yet; large |
| Keep permanently separate | Two pipelines forever | Fine until a shared entity model forces a choice |
Consequences
Section titled “Consequences”- No code changes land from this ADR; it gates a future evaluation task under M-0014-pumice-desktop-app-integration Phase 2.
T-Z5MK(the convergence/adapter-seam task) is the natural home for the evaluation’s outcome once a concrete shared-model trigger appears.- If convergence is later chosen, the direction is governed by S-0008-apps-consume-substrate-through-published-surfaces.
Open questions
Section titled “Open questions”- Schema source-of-truth on convergence — Rust (ontogen) or TS/zod.
- Does the dashboard benefit from ontogen independently (richer transport / admin-layer generation), or is the zod path sufficient for its needs?
- Ontogen is already externalized (
rust-ontogen, git dep) — this ADR is about workspace standardization, not extracting ontogen (that is done). - Filename follows D-0002-entity-identifier-shape:
D-0017-prefix, slugontogen-shared-codegen-convergence. Hand-authored.