Decisions
ADR-lite: the load-bearing decisions, each with the alternative it beat and the consequence it carries. Design history lives in the org ledger — proposal P-017 (supersedes P-015).
Generic over T, never a consumer's model
Decision: ConfigSource<T>/ConfigFormat<T> are generic over the consumer's serde model — scarab never names a Config type.
- Alternative: a scarab-owned universal config schema.
- Consequence: one
FileSourceserves myco, tamias, tarsi, and every future repo; each consumer keeps only its serde model. Cost: trait objects at the call site to keep generics from exploding.
Discovery is a spec, not a search loop
Decision: Discovery declares env_var, dirs, format preference, explicit-path handling; FileSource interprets it.
- Alternative: hard-coded per-repo search logic (the
gen-*.py/copy-paste status quo). - Consequence: env/remote
ConfigSourceimpls reuse the same vocabulary without inheriting file semantics.
Formats are separate crates
Decision: scarab-config-toml and -yaml own only syntax; scarab-config stays pure (traits, Discovery, merge helpers).
- Alternative: one crate with all formats baked in.
- Consequence: a consumer carries just the syntax it wants; the port stays I/O-free and unit-testable.
Config and templates are separate planes
Decision: config is read (find, parse, model); templates are write (render sources to targets with a var context) — two ports, two invariants.
- Alternative: one unified "content" port.
- Consequence: a consumer adopts one plane without the other; discovery order vs. path-safety+digest invariants stay local.
MiniJinja is the only engine (v1)
Decision: scarab-template-minijinja is deliberately the sole TemplateEngine impl — sandboxed by construction.
- Alternative: a plugin system for template syntax.
- Consequence:
/{% %}covers config-file templating without attack surface; the port exists so a second syntax family can land without touching model or driver.
Uninstall is digest-exact
Decision: the driver records sha256 per written file; uninstall removes only files still matching.
- Alternative: remove everything the pack declared.
- Consequence: user edits survive uninstall and are reported — templated files are owned only until touched.
Secrets stay names
Decision: config surfaces and template vars carry secret names, never values; cuora owns resolution.
- Alternative: templated secret injection.
- Consequence: packs are safe to distribute and review; the boundary is convention plus cuora owning the values.