alkdev/alkgen

0 Fork 0

Files

T

glm-5.3-flash ee4053e3e2 docs(release): rewrite README on the shipped framing; CHANGELOG 0.1.0; package exclude fix

- README: the engine contract (strict mode, set-per-registry,
  consumer-supplied text, typed errors, determinism, two sinks,
  per-set escaping), the three integration postures (emit.md A/B/C),
  an explicit what-0.1.0-does-not-ship section, no stale codegen/alktype
  references
- CHANGELOG: Keep a Changelog 0.1.0 entry itemized against the actual
  surface, with the error-evolution policy recorded
- Cargo.toml: exclude docs/plans/ and tasks/ from the package

2026-11-07 06:07:28 +00:00

3.4 KiB

Raw Permalink Blame History

Changelog

All notable changes to this crate are documented here. The format is based on Keep a Changelog, and this crate adheres to Semantic Versioning.

0.1.0 - 2026-11-07

Initial release: the text-generation core of the alk* stack (ADR-001), proven fit for its first consumer, alkforge's server-side HTML rendering. The engine is consumer-blind: no engine-owned template sets ship in 0.1.0; consumer-supplied template and partial text registers through the same machinery the engine would use (ADR-008).

Added

TemplateSet: one registry per template set (ADR-002 decision 6), constructed over an EscapePolicy with strict mode forced on (never parameterizable). Typed fallible registration of templates and partials (register_template, register_partial; malformed text is rejected at registration with the substrate's parse error reachable through the source chain), a helper registration seam for set-owned custom helpers (purity is a documented convention, not runtime enforcement), set-level bookkeeping distinguishing render targets from partials (is_template; rendering a partial's name or an unknown name fails typed before the substrate is consulted), and the two render entry points: render (String sink) and render_to_write (io::Write sink, streaming, not atomic by contract).
EscapePolicy: the escaper as an explicit per-set choice (ADR-005). Html keeps the substrate's entity escaping on ({{& }} as the per-expression opt-out); NoOp passes interpolations through verbatim for code-shaped sets.
Error: the crate's one public error enum, non-exhaustive by policy (see below), with exactly two variants and no catch-all: Registration (substrate TemplateError behind it) and Render (substrate RenderError behind it). Every engine-owned failure path maps to exactly one variant; no input the API accepts reaches a panic path.
The bast-codegen cargo feature, declared and gating nothing (ADR-009): the manifest posture for the future engine-owned codec set, verified not to pull alktype or any other dependency.

Guarantees

Rendering is synchronous, pure, and deterministic (ADR-003): repeated renders, rebuilt registries, and both sinks produce byte-identical output for the same registry contents and context, pinned by tests across registration orders and fresh contexts.
Strict mode (ADR-002): a missing context variable (top-level or nested in {{#each}}/{{#if}} branches) is a typed Error::Render in both sinks, never silently empty output. The write sink's no-atomicity on failure is stated by tests (partially written bytes stay; buffering is the consumer's tool for atomicity).
Wasm-clean by construction: no filesystem, no threads, no time, no environment access anywhere in the library; the wasm32-unknown-unknown release build is a standing verification gate.

Error evolution policy

The Error enum is #[non_exhaustive]: its documented evolution is additive (a context-build error arm lands with the first engine-owned template set), and non-exhaustiveness keeps that addition non-breaking for downstream match sites. EscapePolicy stays exhaustive: ADR-005 fixes the policy set at two and the expected consumer interaction is construction, not matching.