Architecture
Scarab is ports-and-adapters in two planes: config loading and templated content. Both are generic — scarab never names a consumer's types.
The config plane
ConfigSource<T> ──load()──▶ T (the port)
▲ ▲
│ impl │ consumer's serde model
scarab-config-file MyConfig, TamiasConfig, …
│ dispatches by extension
ConfigFormat<T> ──parse/render──▶ text (syntax port)
▲
scarab-config-toml / scarab-config-yamlscarab-configis pure: traits, theDiscoveryspec, path helpers, and the JSON merge half (merge_value/apply_overrides) — no I/O, no formats, no models.scarab-config-fileis the discovery impl every org repo copy-pasted:FileSourcepicks the first matching file;LayeredFileSourcemerges every dir's file plus explicit/override layers into oneT. Both dispatch by extension across a format list.scarab-config-toml/-yamlown only syntax — serde parse/render over anyT. Formats are separate crates so a consumer can carry just the syntax it wants. Layered loading parses each layer asserde_json::Valuethrough the same blanket impls, soTitself never needsSerialize.
Generic-over-T is the load-bearing decision: one FileSource serves myco, tamias, tarsi, and every future repo because the model stays in the consumer. The trait objects (&dyn ConfigFormat<T>) keep formats heterogeneous without generics exploding at the call site.
Discovery is a spec, not a search loop — FileSource interprets it, and env/remote ConfigSource impls can reuse the same vocabulary (env_var, dirs, preference order) without inheriting file semantics.
The template plane
tamias pack (type: template)
│ tamias.yaml `template:` table
▼
scarab-template ── PackTemplate/TemplateFile/TemplateEngine (pure)
│
▼
tamias-driver-template ── verbs, vars, state file (the ops impl)
│
▼
scarab-template-minijinja ── the one engine impl (v1)scarab-templateholds the pack model and path safety — pure domain, engine-agnostic.merge_contextdefines layer precedence;safe_into/safe_srcdefine what "inside the target" means.template.extendscomposes packs: tamias materializes each ancestor's payload at.scarab-parent/, and the driver renders the chain ancestor-first so children override parents onintoconflicts — inheritance without a fetch capability in the driver.tamias-driver-templateis where I/O lives: manifest loading, chain walking, var resolution (ancestor defaults → pack defaults → auto → file → env → args), render+write, digest state. It implements the tamias driver contract, so packs distribute through tamias like every other content type — no bespoke install path.scarab-template-minijinjais deliberately the only engine: minijinja is small, sandboxed by construction, and its/{% %}syntax covers config-file templating without a plugin system. The port exists so a second syntax family can land without touching the model or the driver.
Why the split
Config and templates share a shape — declared inputs in, files out — but not a mechanism. Config is read: find a file, parse to a typed model. Templates are write: render declared sources to declared targets with a variable context. Keeping them as separate ports means a consumer can adopt one without the other, and each plane's invariants (discovery order vs. path safety + digest state) stay local.
Invariants worth knowing
- Formats prefer YAML. Within a directory,
yaml→yml→toml; across dirs, earlier dirs win regardless of format. - Named paths fail loudly. An explicit/
$*_CONFIGpath that misses is an error; discovery candidates skip silently. - Templates can't escape.
../absolute/empty targets are rejected at validation, before any write. - Uninstall is digest-exact. Only files still matching their recorded sha256 are removed; user edits are preserved and reported.
- Layers merge as JSON, not as
T.LayeredFileSourcefoldsserde_json::Valuetrees — objects key-wise, scalars/arrays replace — before one final deserialize, so merge semantics stay format- and model-agnostic. - Secrets stay names. Config surfaces carry secret names, never values — cuora owns the values.
Where it sits
Scarab is a library in the org's layering — below the engines, consumed through tamias. The stack is tamias (package & content manager) → engines (myco, kuda, mimus, sepia, sturn, hypha, tarsi, cicada, cypera, peregrin) → orchestration (peregrin campaigns) → surfaces (pavo, MCP fronts).
Scarab doesn't run anywhere itself: engines call scarab-config to load their <name>.yaml/.toml, and tamias distributes type: template packs that tamias-driver-template renders. It sits beside the engines as shared expertise — the config port every engine agrees on, the template mechanism every pack shares.