From 79c2794a99f2838abb756eb39a1254cb0207f0d5 Mon Sep 17 00:00:00 2001 From: "glm-5.3-flash" Date: Tue, 8 Sep 2026 08:58:50 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20phase-0=20=E2=80=94=20OQ-GN-01=20resolv?= =?UTF-8?q?ed:=20dev=20tool,=20static=20files,=20module=20output?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - clarification: alkcall is a library others build on; alkgen branches 1+2 are a dev tool generating static files into downstream projects (protocol crates alktty/alktunnels/sftp, cloud integrations vast.ai/ runpod) from provided schemas (BAST or jsonschema/openapi) - OQ-GN-01 resolved: module-level output for v1; fragments out (defeats dev-tool purpose), crate generation out for v1 (composed from modules later if asked). Residue: file partitioning policy - OQ-GN-06 reframed: generated files land in projects that don't depend on alktype today, so dependency footprint is consumer's choice, not wire-shaped; leaning self-contained, POC decides - branch 2 reframed: static counterpart of alkhttp from_* adapters --- docs/research/phase-0.md | 89 +++++++++++++++++++++++++--------------- 1 file changed, 57 insertions(+), 32 deletions(-) diff --git a/docs/research/phase-0.md b/docs/research/phase-0.md index 6ff3ec2..d091edd 100644 --- a/docs/research/phase-0.md +++ b/docs/research/phase-0.md @@ -13,16 +13,19 @@ approach."* It is the input to Phase 1 (Architecture). Drafted 2026-09-08 from the initial setup discussion and a survey of the four relevant references (below). The crate is the codegen engine -of the alk* stack: handlebars-rust templates rendered over alktype -BAST documents, producing code artifacts. Three branches, roughly in +of the alk* stack: a dev tool generating static files into downstream +projects from schema documents — handlebars-rust templates rendered +over alktype BAST documents (branch 1) or jsonschema/openapi documents +(branch 2), producing code artifacts. Three branches, roughly in timeline order: -1. **BAST readers/writers/validators** — generate the binary - read/write/validate code alkcall's channels consume, from alktype - BAST documents. The primary v1 target. -2. **Call-protocol handlers** — generate handlers in the shape of - alkhttp's `from_openapi` / `from_jsonschema` adapters for alkcall's - call protocol (JSON RPC). Second. +1. **BAST readers/writers/validators** — from alktype BAST + documents, generate static binary read/write/validate code + integrating with alkcall's channels. The primary v1 target. +2. **Call-protocol handlers** — generate the boilerplate for + call-protocol (JSON RPC) integration, from jsonschema/openapi + (or BAST) inputs — the static counterpart of alkhttp's + `from_openapi` / `from_jsonschema` adapters. Second. 3. **Template-JIT core** — an alkminer-v1-shaped render-then-compile cache with partials. Far down the timeline; influences only how general the core template layer must be. Not a v1 requirement. @@ -33,8 +36,8 @@ timeline order: provides the BAST document model (`Schema`/`Definitions` builder types, `AlkTypeKind`, `OffsetMap`, `PackedLayout`, `read_plan`, `validation_plan`); alkgen owns template assets, context building, - registry construction, and rendering. Output is code text (Rust for - v1). + registry construction, and rendering. Output is static code files + generated into downstream projects (dev-tool model — OQ-GN-01). - **wasm-clean is validated, not assumed.** The skeleton (alktype 0.3.0 + handlebars 6.4 + serde_json preserve_order + thiserror) compiles to `wasm32-unknown-unknown` release as-is. handlebars-rust @@ -123,23 +126,32 @@ Numbered OQ-GN-01.. for reference and promotion to ### OQ-GN-01: What is alkgen's primary unit of output — a crate, a module, a fragment? -Options in increasing size: +**Resolved 2026-09-08 (setup discussion): static files generated into +a consumer project.** The clarification that resolved it: alkcall is +a *library* others build on, and alkgen's branches 1 and 2 are a +*dev tool* — it generates boilerplate into some downstream project +(protocol crates like alktty/alktunnels/sftp, cloud-provider +integrations like vast.ai/runpod), not into alkcall itself. Both +branches take a provided schema document (BAST or jsonschema/ +openapi) and emit static files. -- **Fragment**: a function or impl block rendered per type/document; - the consumer assembles files/crates (most composable; the consumer - owns imports/module layout). -- **Module**: a self-contained `.rs` file (readers.rs, writers.rs, - validators.rs) with banner + use statements (typebox-rs - `generate_module` precedent; alkcall consumes a file directly). -- **Crate**: a full Cargo.toml + src tree generated into the - consumer's workspace (most turnkey; heaviest maintenance burden). +- **Fragment** is out — the consumer assembling fragments by hand + defeats the dev-tool purpose. +- **Crate** is out for v1 — generating a whole Cargo project is + trivially composed from modules later if a consumer asks, and + would bake build-layout decisions (workspace placement, dep + versions) into the generator prematurely. +- **Module-level output is the v1 shape**: one document → one or + more self-contained `.rs` files (banner + use statements + + impls), dropped into the consumer's `src/` tree. Matches + typebox-rs `generate_module` and how generated protocol files + would sit in e.g. an alktunnels-style crate. -Half-hunch: module-level output with fragment-level API (render one -document → one module file), because alkcall's channels want a -drop-in file and crate generation is trivially composed from -modules later. But this is a wire-shaped decision (generated file -layout is stable once a consumer exists) — needs alkcall-side -discussion before Phase 1. +Residue for Phase 1: file partitioning policy (one file per +document vs per-type files; where the reader/writer/validator +split lands), and whether generated files are regenerated wholesale +(overwrite) or support partial regeneration. These are spec-shape +tasks, not research questions. ### OQ-GN-02: Interpretation depth — render from BAST directly, or from alktype's plans? @@ -233,11 +245,18 @@ before Phase 1 ADR — likely the first POC if any. ### OQ-GN-06: Does branch 1 output depend on alktype at all? -Related to OQ-GN-05: if generated code is self-contained (a), it -should not `use alktype` at all — alkgen becomes a build-time dev- -dependency of consumers. If delegating (b/c), generated code links -alktype at runtime. Wire-shaped decision (imports in generated -files are stable once consumed). +Related to OQ-GN-05. Reframed 2026-09-08 by the dev-tool model +(OQ-GN-01 resolution): generated files land in *downstream projects* +which do not currently depend on alktype — so a self-contained (a) +output makes the generated module dependency-free, while a +delegating (b/c) output adds alktype as a runtime dep of the +consumer project. That is a real cost the consumer weighs, but no +longer wire-shaped in the old sense: the consumer's Cargo.toml is +their file, regenerated output can bump deps without a wire break. +The decision now rides mostly on OQ-GN-05's performance trade (every +runtime call into alktype keeps the compiled path interpreter- +shaped) plus consumer taste on dependency footprint. Leaning (a) +self-contained for branch 1; the reader POC decides. ### OQ-GN-07: Validation strategy in generated code @@ -316,13 +335,19 @@ is a place the compiled path stays interpreter-shaped. alkhttp adapters (§Prior art) - [x] Branch scope framed — readers/writers/validators first, handlers second, JIT later (§opening) -- [ ] OQ-GN-01 (output unit) — resolved with alkcall-side input +- [x] OQ-GN-01 (output unit) — resolved 2026-09-08: static files + generated into downstream projects (dev-tool model); module- + level output for v1, fragments and crate-generation out. + Residue: file partitioning policy (Phase 1 spec task) - [x] OQ-GN-02/03 (context source, duplication cut) — direction set 2026-09-08: plan-driven contexts (plans for offsets/sizes, BAST for descriptive metadata); duplication resolved as posture. Residue: exact plan→context projection (Phase 1 spec task) +- [ ] OQ-GN-04 (language scope) — low-stakes; core language-agnostic, + Rust-only templates for v1 (half-hunch, acceptable to defer) - [ ] OQ-GN-05/06 (delegation boundary, dependency shape) — the - reader-POC cluster + reader-POC cluster; leaning self-contained output (a), POC + decides - [ ] OQ-GN-07 (validation strategy) — resolve with or after OQ-GN-05 - [ ] OQ-GN-08 (POC decision) — run POC 1 or record why analysis