Why decisions happened.
Observability records what happened. Explainability projects why decisions were made — directly from the canonical authorities, not paraphrased from logs. Five canonical explainers (API surface, project runtime, authored publication, access, read plan) feed a typed projection that travels with every result. Reason codes are first-class, not strings.
Projected from canonical state. Never log-scraped.
Anti-pattern #77 is absolute: log-scraping to reconstruct an explanation is forbidden. Each explainer reads the same canonical state the runtime reads — same compiler, same resolver, same engine — and projects a typed reason.
IApiSurfaceExplainer
Why a route exists, what it dispatches, which capability grants gate it. Same descriptor graph that compiles REST, GraphQL, gRPC — just queried for explanation.
IProjectRuntimeExplainer
Why this provider binding resolved. Which ancestor contributed it. Which envelope rule shaped it. Same compiler, queried for the why.
IAuthoredPublicationExplainer
Why this publication version is in effect. The lineage from source commit → contract version → publication. The carry-forward chain across surfaces.
IAccessExplainer
Why this read was allowed or denied. Which row filter applied. Which field mask intervened. Same AccessEngine, same evaluation — projected as a typed decision record.
IReadPlanExplainer
Why this read plan was chosen. Which capability gated which strategy. Which provider compiled native vs. runtime. The compile pipeline IS the explain pipeline (anti-pattern #78).
Typed reason codes
ExplanationReasonCodes is a typed slot per surface. Not a free-form string. Stable codes operators can alarm on, dashboards can group by, agents can read deterministically.
Observability and Explainability are never confused.
No Explainability type references Vadyl.Observability. No reason code is reconstructed from a log line. The compile pipelines do the explaining; the runtime pipelines do the operating; both consume the same canonical state. Two peer planes — pinned by structural tests so the boundary cannot drift.
Surface · Runtime · Publication · Access · ReadPlan
Stable, alarmable, groupable
Anti-pattern #77 absolute
Compile pipeline IS explain pipeline
Stop guessing why production decided what it did.
Ask the explainer. The reason is already canonical — Vadyl just projects it. No log archaeology. No paraphrased best-guess. The truth, with a stable code.