Master Prompt Versioning: Why Published Versions Are Immutable and How That Protects You

Changing a prompt can change application behavior even when no TypeScript, API route, or database migration changes.

That makes prompt text production code in everything but file extension. It needs version identity, review, controlled release, and rollback.

CyWire treats each published master prompt version as an immutable snapshot. Improvements become a new version instead of silently modifying the artifact applications and buyers already rely on.

The Failure Caused by Editing in Place

Imagine a support classifier running prompt version 3. A developer changes one sentence to make escalations more sensitive. The edit looks harmless and replaces the existing prompt.

The next day, high-priority volume doubles.

The team now has basic questions it cannot answer confidently:

• Which exact instruction classified yesterday's tickets?
• Did the output schema change too?
• Which records came from the old behavior?
• Can the old prompt be restored exactly?
• Did buyers receive behavior they did not choose?

If version 3 was overwritten, the evidence is gone. A code commit may help, but only if the runtime artifact maps cleanly to that commit and every environment used it at the same time.

An immutable published version removes that ambiguity.

What Immutable Means on CyWire

Once a master prompt version is published globally or to the marketplace, that published snapshot is not edited in place.

A change to instruction, variables, output schema, constraints, or other behavior creates a new version. The earlier version remains a stable reference for the applications and generated records that used it.

Immutability does not mean a prompt can never improve. It means improvement has an identity.

Version the Whole Contract

A master prompt includes more than instruction text. Version changes may affect:

• compiled instructions;
• variable names, types, or required status;
• output properties and enums;
• quality and safety rules;
• constraints and edge behavior;
• examples used to clarify decisions;
• metadata that identifies the release.

Treating only full_prompt_text as versioned can create a hidden breaking change. An unchanged instruction with a renamed schema field still breaks the consumer.

Store Version Identity With Every Result

The generated object should carry or be stored beside the prompt identifier and version:

const built = await buildPrompt(masterPrompt, variables)
const output = await runModel(built)
const validated = validateOutput(output, built.outputSchema)

await saveResult({
  data: validated,
  masterPromptId: masterPrompt.id,
  masterPromptVersion: built.promptVersion,
})

This creates a direct answer when a result is questioned later: it came from this prompt snapshot, with this output contract.

Store model and provider identity too when reproducibility matters. Prompt version is necessary, but model behavior and provider settings can also change outcomes.

New Version Does Not Mean Automatic Upgrade

A newer version may improve one use case and change another. Applications should choose when to move.

A controlled upgrade looks like this:

1. Keep the current published version active.
2. Create and test a candidate version.
3. Run representative cases against both.
4. Compare structure, decisions, failure reasons, and downstream behavior.
5. Update the application to select the new version.
6. Monitor the release and retain the rollback path.

This is normal change management. AI does not make it optional.

Compatibility Questions Before Publishing

Review every new version for interface changes.

Variable Compatibility

• Was a required variable added?
• Was a variable renamed or removed?
• Did a value change meaning?
• Did accepted input type or format change?

Schema Compatibility

• Was a required output field added?
• Was a property renamed or removed?
• Did a type change?
• Did an enum lose or gain values?
• Did uncertainty behavior change?

Behavioral Compatibility

• Did a decision threshold change?
• Did a constraint become stricter?
• Did the workflow gain or lose a human-review state?
• Could the same input now trigger a different business action?

A schema-compatible change can still be behaviorally significant. Version review needs both code and domain owners.

Rollback Becomes Selection, Not Reconstruction

When published snapshots are immutable, rollback means selecting the previous known version.

Without snapshots, rollback means finding an old file, remembering which variables and schema belonged with it, rebuilding the artifact, and hoping nothing else changed. That is incident archaeology, not release control.

Rollback does not erase outputs generated by the newer version. Those records should remain attributed to the version that produced them.

Deprecation Is Not Deletion

A team may deprecate a version so new integrations stop selecting it. Historical records still need the reference.

Deprecation communicates lifecycle status. Deletion destroys traceability.

For regulated, audited, or high-impact workflows, retention requirements may extend beyond the prompt itself to test evidence, approval records, source references, and model configuration. Those requirements belong to the organization's governance policy.

What Marketplace Buyers Receive

A CyWire marketplace purchase is a licensed snapshot of the listed prompt version. The buyer's copy is independent; it is not a live pointer that a publisher can silently change later.

Future publisher versions are separate unless they are explicitly included. This protects the buyer from unexpected behavior changes and protects the meaning of the version they evaluated.

Buyers can adapt their owned copy for their application, then manage those changes under their own version control and testing process. The original purchased snapshot remains the starting reference.

Review the current terms on the CyWire license page before relying on a marketplace prompt in a commercial workflow.

Versioning and Quality Scores

A quality score belongs to the version that was tested. A score from version 3 does not automatically validate version 4.

Any behavior-changing version should be tested again. CyWire requires the current tested score to meet the 70-point threshold before global or marketplace publishing.

Read How CyWire Quality-Scores Every Master Prompt for the limits of that gate.

A Practical Release Record

For each version, keep enough context to answer:

Prompt family: supplier-incident-review
Published version: 4
Previous version: 3
Change: Added explicit conflicting-evidence state
Variables changed: none
Schema changed: evidence_status enum gained "conflicting"
Expected behavior: contradictory sources route to human review
Test status: passed approved case set
Application rollout: explicit selection required
Rollback: version 3 remains available

The record does not need ceremonial prose. It needs the facts another developer will need during an incident or upgrade.

The Human Reason for Immutability

Versioning is often described as audit infrastructure. It is also a kindness to the people maintaining the system.

The developer on call should not have to guess which prompt ran. The domain reviewer should not have to compare screenshots. The buyer should not wake up to changed behavior from an artifact they already evaluated.

Immutable versions preserve the answer.

Use the production-ready checklist before publishing a new version, and browse versioned prompt listings in the CyWire marketplace.