ADR-001: Spec as Source of Truth
Status: Accepted | Date: 2026-02-10
Context
Fascia needs a canonical representation for backend systems. The central design question is whether runtime behavior should be driven by hand-written code, static configuration, or structured specifications.
Traditional platforms fall into two camps: code-generation tools that produce source files a developer can modify, and configuration-plus-code systems (like Kubernetes) where configuration describes what to run but code defines how it runs. Both approaches create a gap between what the system describes and what it actually does.
Fascia targets non-developers who build production backends. The representation must be understandable without programming knowledge, auditable without reading source code, and safe to modify without breaking invariants.
Decision
All runtime behavior is derived from structured, versioned specification files. Entity specs define business objects. Tool specs define executable operations. Policy specs define safety constraints. There is no "code behind" that can diverge from the spec.
Specifications are the single source of truth. The Executor reads compiled spec bundles and executes them deterministically. No runtime component interprets anything outside the spec.
Alternatives Considered
| Option | Pros | Cons |
|---|---|---|
| Spec-driven (chosen) | Deterministic, auditable, versionable, no code divergence | Limited flexibility for edge cases |
| Code generation | Flexible, traditional approach | Generated code can be modified, creating divergence between spec and reality |
| Configuration + code | Familiar pattern (e.g., Kubernetes) | Two sources of truth, hard to audit holistically |
Consequences
Positive
- Traceability -- Every runtime behavior is traceable to a specific spec version. You can answer "why did the system do X?" by inspecting the deployed spec.
- Static analysis -- Risk analysis, safety checks, and policy enforcement can be performed on specs without executing anything.
- Trivial rollback -- Reverting to a previous behavior means deploying a previous spec version. No code merge required.
- Non-developer access -- Business users can understand and modify system behavior through the visual design tools (Chat Studio, Flow Studio) that produce specs.
Negative
- Spec coverage gap -- Truly novel or unusual backend patterns that do not fit the spec model cannot be expressed. Every new capability requires extending the spec schema.
- Schema evolution overhead -- The spec schema itself must be carefully versioned. Breaking changes to the schema can invalidate existing customer specs.
Risks
- Spec schema evolution must be managed with backward compatibility guarantees to avoid breaking deployed systems.
- The "spec gap" -- situations where users need behavior the spec system does not yet support -- must be addressed through a clear extension roadmap and escape hatches in the full vision.