# Prompt & Configuration Registry — Architecture One-Pager

*Prompt & Configuration Registry · Solution Architecture v1.0 · open source, self-hosted on Kubernetes · Platform Architecture · 2026-09 · 21 views · 17 architecture decision records*

**The authoring plane and the resolution plane share nothing but an immutable signed bundle and a pointer to it.**

Every team that ships an AI feature discovers the same thing: the prompt is the product, and the prompt is not in a release. A support assistant answering millions of conversations is governed by a system prompt, a model choice, a tool list, a temperature and a refusal policy, all of which need to change faster than the service reading them ships. Teams arrive at the same place by different roads — a YAML file in the repo that is too slow, a database row edited by hand with no review and no history, or a feature-flag product bent into a shape it was not built for. Each of those failures is really the same failure: the thing that decides model behaviour has no release process, no history, no way to be reversed quickly, and no way to prove afterwards what it actually said.

Two planes and one seam. An authoring plane — console, CLI, Git sync, review, gates, approvals, audit — that is transactional, strongly consistent, human-paced and allowed to be unavailable. A resolution plane that lives inside ~300 application processes as a library, holds one verified bundle in memory, answers from it in under three milliseconds, and needs nothing from the control plane to keep doing so. Between them, a seam carrying exactly two things: an immutable, signed, content-addressed bundle, and a small linearisable pointer naming which bundle is current for a key in an environment. Evidence flows the other way and asynchronously: exposures into a columnar store that may drop them, promotions and approvals into a write-once ledger that may not.

## What it is, and what it is not

- **A release control plane for behaviour** — not a content management system for prompts, which is what it becomes when versioning is designed before promotion.
- **A system whose outage nobody notices** — not a highly available service in the request path, which is a more expensive way to be less reliable.
- **The place a past answer can be proved from** — not a place where a past answer can be reconstructed, if the history is intact and nobody edited anything.
- **A single mechanism run forwards and backwards** — not a promotion pipeline with an emergency rollback path beside it, exercised once a quarter.

## The decisions that are the architecture

1. **The resolution plane never reads the authoring store** (ADR-01) — Key, rule, variant, prompt and model are all read from a bundle already resident in the calling process. The control plane is never on the request path, which is what licenses its lower availability target and turns its outage into "no new releases" rather than "no AI features".
2. **Resolution is a library, not a service** (ADR-02) — Three SDKs compiled into the applications, rather than a sidecar or a central resolver. It buys sub-millisecond resolution and keeps user attributes inside the caller; it costs an upgrade cycle measured in the slowest team's release cadence.
3. **Availability failures fail static; integrity failures fail closed** (ADR-03) — A resolver that cannot reach anything serves its last verified bundle indefinitely. A resolver handed a bundle it cannot verify refuses it and keeps the previous one. Splitting the posture by cause rather than answering it once is the only version that survives an incident.
4. **Rollback is promotion, run backwards** (ADR-04) — Same mechanism, same artefacts, no approval gate, no separate path. The reverse operation is exercised daily instead of once under pressure, and the target of a rollback is an artefact that already exists and was already verified.
5. **The poll guarantees convergence; the notice only makes it fast** (ADR-05) — Push and poll both run, but only one of them is load-bearing. Losing the bus costs propagation latency and never correctness, which is what allows the bus to be a normal piece of infrastructure rather than a critical one.
6. **The unit of release is a whole-environment bundle** (ADR-07) — One signed artefact per key namespace and environment, with a 2 MB ceiling that fails the build rather than slowing the resolver. It buys atomic multi-key change and a single verification; it costs a rebuild for every change and an eventual namespace split.
7. **Assignment is a pure function of unit and salt** (ADR-09) — No assignment store, no lookup, no assignment service to be unavailable — and the same function recomputes the same answer offline, so an analyst reconstructing an experiment gets what the resolver got.
8. **The digest is what is retained, not the rendered prompt** (ADR-14) — Reproducibility is a property of content addressing, not of logging. Storing resolved variables would reproduce the exact prompt sent and would also make this platform a store of user content it has no business holding.
9. **A guardrail breach pages a human, it does not roll back** (ADR-15) — The signals that matter for AI behaviour lag minutes to hours and are noisy. Automating the revert on a noisy signal trades a bounded risk for an unbounded one: a good change reverted with nobody able to say why.

## Why this should still be right in ten years

A registry outlives the model it was built around, the SDK it was first written in, and probably the company's current opinion about prompting. These are the properties that should survive a change of model provider, a change of runtime, and whatever replaces the prompt as the unit of behaviour.

- **The headline rule names no technology.** "The authoring plane and the resolution plane share nothing but an immutable signed bundle and a pointer" says nothing about prompts, models, Kubernetes, etcd or OCI. It is a statement about which dependencies may sit on a request, and it stays true through any replacement underneath it. It is also the property a future team would most easily discard — by adding one convenient lookup for one urgent feature — which is why the seam is drawn on view 07 and why the absent edges are annotated rather than merely missing.
- **Content addressing outlives the content.** A digest as the primary key of a version is not a prompt-engineering idea; it is the same idea that makes a container image, a Git commit and a package lockfile trustworthy. Whatever replaces free-text prompts — structured policies, learned adapters, tool manifests — will still need an identity that is its content, and the reproducibility claim will still rest on it.
- **The reverse operation must be the ordinary one.** Systems acquire an emergency path, and emergency paths rot because they are used once a quarter by someone who has never used them. Making rollback the same mechanism as promotion is a discipline rather than a mechanism, and it applies to any future operation that has a direction: if it has a special reverse, the reverse will be broken when it is needed.
- **Degrade a dimension, never availability.** Every dependency on view 16 gives up freshness, fidelity or the ability to change. None gives up availability except trust verification, which does so deliberately. That is the question to ask of every dependency added in the next decade: which dimension will its outage cost? A dependency with no answer does not belong on the resolution path.
- **Behaviour changes need governance whatever produces them.** Review, a named rationale, a second approver, an evidence-gated promotion and an immutable record are not prompt-specific. They exist because a change that alters what a system says to customers is a change someone will eventually be asked to account for. That obligation predates language models and will outlast them.

## Non-functional targets

The qualities that decide whether this design is the right one, each with the mechanism that delivers it and the view where it is drawn. Targets are stated assumptions from ask.md.

| Quality | Target | How it is met | View |
|---|---|---|---|
| Resolution latency | p50 ≤ 0.2 ms, p99 ≤ 3 ms | Every decision reads a bundle already resident in the calling process; no message leaves it before the answer is decided. | 12 |
| Resolution availability | ≥ 99.99% monthly, measured at the caller | Not delivered by redundancy: delivered by fail-static on the last verified bundle, plus a bundle baked into the container image for cold start. | 16 |
| Independence from the control plane | Zero resolution impact from a control-plane outage | Resolution reads an artefact and a pointer and nothing else; the authoring store has no downstream edge at all. | 07 |
| Propagation | 99% of resolvers within 10 s, 100% within 60 s | Notice over the bus for speed, 30 s poll as the guarantee; each resolver reports the digest it is serving, so coverage is measured and not inferred. | 14 |
| Rollback | Pointer moved ≤ 2 s; 99% of traffic reverted ≤ 30 s | Same pointer-write mechanism as promotion, no approval gate, against an artefact that already exists and was already verified. | 18 |
| Reproducibility | Any past answer recoverable for 7 years | Digest on every response; content-addressed immutable bundles with a versioned canonicaliser; WORM audit ledger. | 09 |
| Assignment stability | ≤ 0.1% of units change variant over an experiment | hash(unit, salt) mod 100 against declared weights — no store to drift, no fleet event that can rebucket. | 15 |
| Change safety | No promotion without a bound evaluation verdict and a second approver | Gates run against the sealed digest rather than the draft, and the verdict is recorded against that digest in the audit ledger. | 13 |
| Throughput | 40,000 resolutions/s per region, 3× burst for 120 s | Resolution scales with the calling fleet because it is inside it; the registry's own tier is sized for 200 promotions/day, not for the resolution rate. | 17 |
| Integrity | No unverified artefact is ever served | Sign at build with a sign-only role against a sealed key; verify at load against a published, versioned trust bundle; reject and keep the previous bundle on failure. | 21 |

## Scope

**In scope**

- Authoring, review, rationale and immutable versioning of prompts, model selections, decoding parameters, tool definitions, retrieval parameters and policy flags.
- Fragment composition and a declared variable schema, with validation, policy lint and secret scanning at build time.
- Environments with pointer-based promotion, configurable approval, atomic multi-key change and evidence gates including a bound evaluation verdict.
- Progressive rollout, deterministic variant assignment, exposure emission and an experiment readout with an uncertainty interval and a declared loss rate.
- One-action rollback to any previous version, a per-key kill switch and a last-ten serving history per key.
- A resolution library for Go, Python and TypeScript with a resident verified bundle, fail-static behaviour, safe defaults and a digest on every resolution.
- An append-only audit ledger of every promotion, approval, rollback and override, and a signed evidence export for a named digest.

**Explicitly out of scope**

- Model hosting and inference — the registry names a model and never calls one.
- The retrieval corpus and its indexing, which belongs to the RAG platform.
- Execution of evaluations: the registry consumes a verdict about a digest, it does not run the harness.
- The product's own user identity system; resolution context is assembled by the caller.
- Cross-experiment mutual exclusion with non-prompt experiments, deferred with its trigger recorded in ADR-10.
- Automatic guardrail rollback, deferred with its reasoning recorded in ADR-15.
- A writable multi-region control plane, deferred with the failure it accepts named in ADR-17.

## What a four-week prototype should prove

Four of this architecture's claims are cheap to test and expensive to be wrong about. A prototype that proves these can be built on; one that skips them is a demonstration of storing text in a database, which is the easy half.

1. Fail-static, honestly: run a representative service against the registry, then take the entire control plane away for four hours — authoring, pointer store, bus and artefact store — and confirm the service keeps answering, that a pod restarted mid-outage comes up serving from its baked-in bundle, and that polling resumes on recovery without a restart. This is the claim everything else rests on.
2. The bundle ceiling against a real catalogue: build bundles from a realistic key namespace and measure compressed size and resolver memory. If 2 MB is exceeded at a plausible catalogue size, the whole-bundle decision in ADR-07 has to be reopened before any SDK is written.
3. Propagation end to end: promote under load and measure the time to 99% and 100% of resolvers reporting the new digest, with the bus deliberately partitioned for one run so the poll is proved to be the guarantee rather than the backup nobody tested.
4. Assignment stability across a fleet event: assign a large population, then scale the fleet up and down, roll the SDK, and change the rollout weights, measuring how many units changed variant. The ≤ 0.1% claim is what every experiment result depends on.

- Control plane down: authoring, gates and promotion unavailable for four hours; confirm zero resolution impact, that staleness is exported and alerts at 15 minutes, and that no resolver falls back to a default it did not need.
- Corrupt artefact: serve a bundle with an invalid signature and confirm the resolver rejects it, retains the previous bundle, raises a high-severity alert, and does not fail a single request (ADR-03).
- Bus partition: cut NATS for an hour under a stream of promotions and confirm every resolver converges on the 30 s poll, with the convergence metric showing the degraded propagation time rather than a false green (ADR-05).
- Cold start with nothing: start a new pod with no cache and the artefact store unreachable, and confirm it serves the image-baked bundle and reports degraded rather than erroring or serving an empty configuration.
- Three-in-the-morning rollback: page someone who has never seen the key, and time them from alert to 99% of traffic reverted using only what view 05 says the platform provides. Anything above 30 s is a finding about the interface, not about the person.
- Signing key rotation: rotate with the trust bundle deliberately distributed late and confirm the failure is a refusal to accept new artefacts rather than a refusal to serve — then run it correctly and confirm a clean overlap (ADR-12).
- Exposure saturation: throttle the exposure pipeline until events drop and confirm resolution latency is unchanged, the drop count is recorded, and the experiment readout declares its loss rate rather than quietly reporting a result (ADR-16).

## Open risks, carried rather than hidden

| Risk | If it lands | Response |
|---|---|---|
| SDK upgrade lag makes a targeting bug unfixable at speed | Resolution logic lives in ~300 applications the platform does not deploy. A bug in rule evaluation or assignment is fixed at the pace of the slowest team's release cadence, which may be months — and during that window the fleet behaves inconsistently in a way no pointer change can correct. | ADR-02 records the sidecar alternative and the condition that flips it: the first targeting-logic defect that cannot be worked around by a configuration change. Until then, the mitigation is a shared conformance suite every SDK must pass, and keeping rule semantics small enough that they rarely change. |
| The 2 MB bundle ceiling is exceeded sooner than assumed | Long prompts and many keys add up faster than anyone expects. Past the ceiling the choice is a slower resolver, a larger memory footprint across the whole application fleet, or a namespace split that breaks the atomic multi-key promotion the bundle was chosen for. | Measure it in the prototype against a realistic catalogue rather than a sample. The ceiling is enforced at build time so the failure is a failed build rather than a degraded fleet, and ADR-07 names per-key artefacts as the fallback with the atomicity cost stated. |
| Prompt authoring is an injection surface with wide reach | Someone with authoring rights on a key can change what a model is instructed to do across an entire product, and the change is text rather than code, so it is reviewed by whoever happens to be available rather than by someone reading it adversarially. | Authoring, approval and promotion are separate grants (ADR-11); every promotion into a protected environment needs a second approver, and high-risk keys need one from the owning group. Policy lint blocks the removal of a safety setting without explicit acknowledgement. None of this is sufficient on its own, and the audit ledger is the compensating control. |
| Reproducibility is claimed more strongly than the retention supports | Storing only the digest reproduces the configuration, not the answer. An auditor asking "what exactly was sent to the model?" will not be satisfied by a prompt template plus a variable schema, and the gap will be discovered during the audit rather than before it. | ADR-14 states the boundary explicitly — behavioural equivalence, not byte-exactness — and puts the retention ladder in the record so the trade against privacy obligation is a decision rather than an omission. If the obligation turns out to be byte-exactness, that is a retention and privacy programme, not a registry feature. |

The reasoning behind every component and technology choice is in the [Architecture Decision Record](decision-record): 17 records across 5 areas, each with the alternatives that lost and what the choice costs.