alkdev/alkgen

0 Fork 0

Files

T

glm-5.3-flash a91ea2ec89 docs(architecture): phase 1 base: text-generation core specs, ADRs 001-010, OQ tracker

- overview.md, core.md, emit.md, targets.md: modular spec set for the
  generalized engine (contexts + templates + partials -> text), with
  the three targets (ssr-html, bast-rust-codecs, call-handlers,
  wgsl-jit) as template sets plus emit postures
- ADRs 001-010: one core/template-set split, handlebars 6.4 strict
  substrate, sync/wasm/deterministic posture, typed contexts with
  builders, per-registry escaper, SSR library posture, typed direct
  codecs output contract, template-set ownership, feature gating,
  library-only v1
- open-questions.md: OQ-01..OQ-08 centralized tracker carrying phase-0
  residue (GN-01/02/07/09) with three deferred(scope) entries plus a
  resolved disposition for phase-0 OQ-GN-04
- tasks/architecture/: external-trigger tracker tasks paired with the
  deferred OQs (taskgraph validate passes)
- phase-0.md checklist dispositioned for OQ-GN-04; AGENTS.md lifecycle
  updated to phase 1

Verification: taskgraph validate (4 tasks OK), cargo fmt --check,
cargo test, em-dash grep clean; architecture-reviewer pass returned
zero critical issues

2026-11-06 08:18:43 +00:00

2.4 KiB

Raw Permalink Blame History

ADR-010: alkgen is library-only; build-script integration is a documented pattern, no CLI

Status

Accepted

Context

Phase 0 demoted the dev-tool identity (ADR-001), and OQ-GN-01 resolved the output unit as module-level files generated into a downstream project. The reader POC validated the integration shape end-to-end as a build script (build.rs calling schema plus templates plus context builder, emitting into OUT_DIR or the source tree; finding F-4). An open surface remained: whether alkgen should also ship a CLI generator binary (a sibling to codegen CLIs in other template tooling).

Decision

alkgen v1 is library-only. Posture-A consumers integrate by calling the library from their build scripts; the build.rs pattern is documented usage, not a binary. No CLI ships in v1.

Rationale for recording the negative:

Every current integration point is either in-process (alkforge, posture B) or a build script on repo code (codec consumers, posture A); a CLI adds packaging, argument, and workspace-layout decisions the crate does not need to make yet.
The dev-tool identity is demoted; a CLI is the strongest form of re-promoting it, and would pull workspace-layout questions (where generated files land, how regeneration is triggered) into alkgen that belong to consumers.
If a consumer wants a CLI later, the library API supports one by composition, and adding a binary to the same crate is additive.

Consequences

Positive: no argument grammar, no output-path policy, no process model to stabilize; the API surface stays a Rust surface.
Positive: build scripts get exactly the schema-to-source-tree semantics they need (the POC shape), including OUT_DIR integration that a CLI cannot replicate cleanly.
Negative: non-Rust or non-cargo consumers have no entry point; if such a consumer ever appears (none exists in the family today), that is the moment to revisit this decision via ADR.
Negative: "documented pattern" means examples in docs; the pattern must be maintained as the API evolves (a doc cost, not a design cost).

References

emit.md (posture A integration shape)
ADR-001 (dev-tool demotion), ADR-009 (feature surface)
Phase-0 OQ-GN-01; reader POC findings F-4 and the POC structure note (docs/research/reader-poc-summary.md)

2.4 KiB Raw Permalink Blame History