Prompt Registry and Versioning

What it is

The store that holds released prompt artefacts, gives each one a stable identity, and controls which identity a running service resolves. It covers how a prompt is named, how a new revision is created and reviewed, how environments are pointed at revisions, how a revision is withdrawn, and how the identity that actually served a request is recorded. Authoring the text happens elsewhere; this is what happens to the text once more than one person and more than one environment depend on it.

Why it matters

A prompt has no interface, no type signature, and no compilation step, so nothing about a change to it is mechanically detectable. The only way to attribute a behavioural change to a wording change is to have recorded, on each request, exactly which revision was in force — and the only way to undo a bad change quickly is for the previous revision to still exist unmodified. A registry is the difference between "quality dropped on Tuesday" and "revision 41 shipped at 14:20 and revision 40 is still there".

Why a prompt revision is only half an identity

The behaviour a prompt produces is not a property of the prompt. It is a property of the pair: this text, read by that model build, with those inference settings. A revision that was evaluated and approved against one model build carries no guarantee under the next one, and a provider-side model update can change behaviour while every artefact in the registry is byte-identical. Pinning the model separately is the same mistake as pinning a library without its transitive dependencies: the registry must be able to express, and a request record must carry, the combination that actually ran. Model identity and its lifecycle are managed as their own concern — see Model Versioning — but the approved pairing is a registry fact, not a model fact.

Key decisions

• What the versioned unit is. Versioning one template leaves the examples, the output schema, and the inference settings free to change underneath it; versioning the whole bundle makes every revision heavier and every change a bundle release.
• Whether identity is a content hash or a declared version number. A hash is honest and unreadable; a declared number is readable and depends on humans to bump it, and the usual compatibility meaning of a major version does not apply to text with no API.
• Whether services resolve the registry at runtime or receive the artefact baked into their build. Runtime resolution makes a wording fix a configuration change and puts the registry on the critical path of every request.
• Whether an environment points at a moving alias or a pinned revision, and what a promotion does. An alias that moves under a running fleet means instances disagree about what they are serving for the length of a cache TTL.
• Who may publish, and whether publishing is reviewed. The faster the path from a text box to production, the more the registry's own change control becomes the product's only safeguard.
• Whether revisions are immutable once published, and what withdrawal means for a conversation already in flight under an older one.
• What is recorded on each request: the resolved identity, the model build, the settings, and ideally a digest of the fully rendered text, since the rendering may differ from the stored artefact.

Failure modes

• A request trace records the prompt name but not the revision, so a regression can be located in time and never attributed, and the investigation ends in a disagreement about whether anything changed.
• A wording change is made directly in a console with no review, no diff, and no second pair of eyes, and the first notification is a support ticket.
• A revision is edited in place rather than superseded, so the artefact that served last week's traffic no longer exists and the incident cannot be reconstructed.
• The registry is a hard runtime dependency with no local fallback; it has an outage and every service that renders a prompt fails at once, including the ones whose prompts had not changed in months.
• An alias is moved during a rolling deploy, half the fleet has the old revision cached, and an A/B comparison running at the same time silently measures a mixture.
• Revisions pile up without any being retired, and the set of artefacts in the registry is several times larger than the set anyone can account for, including copies with embedded customer data from a debugging session.
• The approved model pairing is recorded in a release ticket rather than in the registry, so a provider model update invalidates the approval and nothing in the system notices.

Related capabilities

• Prompt Templates — the artefacts this store holds revisions of
• Prompt A/B Testing — needs a stable revision identity on both arms
• Dynamic Prompt Assembly — resolves identities here when building a request
• Context Provenance — records which revision contributed which span
• Model Versioning — the other half of a reproducible behaviour

Applies: Production readiness · Design questions