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-009: Template sets are feature-gated; default features ship the core only

Status

Accepted

Context

alkforge links alkgen for SSR (ADR-006). alktype is needed only by the codec (and future handler) template sets and their context builders; the SSR consumer inherits no BAST machinery. Family ADR-002's security posture treats consumer dependency surface as a standing constraint: pulling alktype into every alkgen consumer would widen cargo supply-chain surface for no benefit to SSR builds. The symmetric concern exists for the codegen sides only if the core itself grew optional platform deps, which ADR-003 forbids.

Decision

Default features ship the core only: registry construction, render entry point, error model, escape policies. No engine-owned template set, no alktype.
Engine-owned template sets are cargo features:
- bast-codegen: the BAST codec templates plus their context builders; pulls alktype.
- Future engine-owned sets land as additional features (naming per the set name; call-handlers may join bast-codegen or take its own, decided when OQ-04 resolves; the wgsl direction tracks OQ-05).
Consumer-owned sets (alkforge pages) need no feature: they ride the default core, registering their own assets (ADR-008).
Current dependency state vs target state: Cargo.toml on main lists alktype unconditionally today; moving alktype behind the feature is an implementation task of phase 3, not a further architecture decision.

Consequences

Positive: alkforge's dependency graph carries only the substrate (handlebars, serde_json, thiserror, serde); alkcall consumers explicitly opt into alktype, which matches whose problem it is.
Positive: the wasm-clean story per feature stays testable individually.
Negative: feature-combination testing multiplies; mitigation is a small fixed matrix in CI (core, core+bast-codegen, wasm build of both), not exhaustive.
Negative: a slight discoverability cost (codegen users must opt in); acceptable because each consumer type is homogeneous.

References

overview.md (dependencies table)
ADR-006 (SSR dependency weight), ADR-008 (ownership), ADR-003 (why the core carries no optional platform deps)
Family ADR-002 decision 5 (security posture)

2.4 KiB Raw Permalink Blame History