The text-generation engine of the alk* stack: handlebars-rust templates rendered over serde-serializable contexts with strict, deterministic output. One crate, one purpose: register a template set, render its templates, get the same bytes every time.

Status: 0.1.0 publishes the core, proven fit for its first consumer, alkforge's server-side HTML rendering. The engine is consumer-blind: it owns no template sets and no assumptions about what the rendered text is. HTML, Rust, and WGSL are all the same shape to it.

The engine's contract

Strict mode is always on. A missing context variable is a typed error, never silently empty output. A silent gap in generated text becomes a bug in the consumer's build, far from its cause; the engine refuses to produce one.
One registry per template set. A TemplateSet is the unit: strict mode, the set's escaper, and its namespace for templates, partials, and helpers all live there. A partial's name is never a render target; the set tracks the difference and rejects a partial-as-target as a typed error.
Consumer-supplied templates register through the same machinery the engine would use. Template text arrives as &str (inline literals, include_str!, caller-built strings); there is no filesystem path anywhere in the API, so the core is wasm-clean by construction.
Typed errors, no panics. Malformed template text fails at registration; render failures (missing variable, unknown template, unknown helper) fail at render. Every failure maps to exactly one variant of the public Error enum (non-exhaustive; the substrate's detail stays reachable through the error's source chain). Template sets may add helpers, which must be pure: no time, no environment, no randomness, no I/O.
Deterministic, byte-identical output. Repeated renders and rebuilt registries produce the same bytes, and there is no hash-map iteration order that can leak into them. This is what makes consumer-side caching and checked-in generated artifacts safe.
Two sinks. render returns a String; render_to_write streams to any io::Write target. Both produce byte-identical output. The write sink is not atomic: a render that fails partway may leave earlier bytes in the target, and consumers that need atomicity buffer first.
Escaping is a per-set choice. EscapePolicy::Html keeps the substrate's HTML entity escaping on (with {{& }} as the deliberate per-expression opt-out); EscapePolicy::NoOp passes interpolations through verbatim for code generation, where output should be escaped at the source, not mangled by entity escaping.

Usage

use alkgen::{EscapePolicy, TemplateSet};
use serde_json::json;

let mut set = TemplateSet::new(EscapePolicy::Html);
set.register_template("page", "<h1>{{title}}</h1>{{> footer}}")?;
set.register_partial("footer", "<p>{{year}}</p>")?;

let ctx = json!({ "title": "Hello", "year": "2026" });
assert_eq!(set.render("page", &ctx)?, "<h1>Hello</h1><p>2026</p>");
# Ok::<(), alkgen::Error>(())

Integration patterns

How rendered text reaches its consumer; the render machinery is identical in every posture (see docs/architecture/emit.md, which ships in the package):

In-process SSR (the first real consumer: alkforge): link the crate, register your page templates and fragment partials, render on demand or behind your own cache. Determinism is what makes caching safe to add later. Render failure is a typed error your error-page mapping owns.
Build-time code generation: call the API from a build.rs script (there is no CLI in v1, by design), render each document, and write the files yourself: the engine returns text and owns nothing about file placement. For artifacts that get checked in, the family's hygiene convention applies at the emit layer: generated files start with an "Auto-generated by alkgen. DO NOT EDIT." banner and regeneration is diff-quiet because rendering is deterministic.
Render-to-compile (future): render shader or other target text and feed it to a downstream compiler, the alkminer-v1 ShaderBuilder shape. No new surface is required from the engine for this.

What 0.1.0 does not ship

Engine-owned template sets: the BAST codec set (binary readers/writers/validators for alkcall channels), protocol handler sets, and the WGSL set are future activations, each behind its own review; the bast-codegen cargo feature is declared but gates nothing. The ssr-html target is proven in-crate through consumer-shaped fixture sets that register through the same public API a real consumer uses. Your template sets are yours: register them from your crate through this API.

Design record

docs/architecture/ ships in the package: the component spec (core.md, emit.md), the activation queue (targets.md), and the decision records (ADR-001 through 010) this README summarizes.

License

Dual-licensed under MIT or Apache-2.0, at your option.