Versioning & cloning

Outcome

You manage companion-guide changes safely — new versions clone from the current active version, the editor never destroys what is live, and activations happen by date so the cutover is auditable.

Prerequisites

A guide registered against a trading partner. Familiarity with rule types (7.2 — Rule types & applicator).

What versioning does and does not do

The companion-guide model deliberately has no DRAFT lifecycle. Every version is an immutable snapshot. New work happens by cloning an existing version, editing the clone, and activating the clone with an effective_from date.

Action	Effect
Clone	Creates a new version with the same rule set; not yet effective.
Edit	Mutates the clone in place; the previously-active version is untouched.
Activate	Sets effective_from to a date you pick; the clone becomes the active version starting at that date.
Supersede	Implicit — when a new version's effective_from arrives, the previous active version becomes archived (its effective_to is set automatically).

Effective-date overlaps are advisory — the resolver picks the latest effective_from whose window covers today. The editor warns on overlaps so you can decide what you intended.

Steps to ship a guide change

1. Open the active version at /companion-guides/:guideId. Note the version number.

2. Click Clone version. The CloneVersionModal asks for:

   Field	Notes
   New version label	Free text; commonly the calendar quarter (2026Q3) or a payer-side change ID.
   Effective from	The date the clone should activate. Cannot be earlier than today.
   Effective to	Optional; if blank, the clone runs until the next clone supersedes it.
   Rule set	Pre-filled from the active version; you can prune at clone time.

3. The clone opens in the editor with the same UI as a fresh guide (see 7.1). Edit rules.

4. Use Live preview against representative samples — pick at least one of each shape your tenant produces (commercial professional, state-Medicaid institutional, etc.).

5. Click Activate. The clone's effective_from is committed; the prior version's effective_to is set to the day before.

Steps to roll back

If a fresh activation produces bad output:

1. Open the prior version (visible in the version list with status archived).

2. Click Reactivate. The dialog asks for a new effective_from — typically today, so the old rules resume immediately. The audit log captures the operator and reason.

3. The bad version becomes archived again. Iterate on a fresh clone when you are ready to retry.

The platform never deletes versions — every clone, edit, and activation is recorded with the operator, timestamp, and (for activations) the specific effective_from chosen.

Steps to inspect a historical activation

1. Open the guide → Versions tab. Each row shows version label, operator, effective_from, effective_to, and an arrow to its rule set.

2. Click into any version to see its rule list and run Live preview against any sample.

3. Compare two versions with Diff (select two checkboxes → click Diff). The diff is shown rule-by-rule with adds / changes / removes highlighted.

Validation

Check	Expected
Cloned version starts inactive	Yes — effective_from is the future date you set.
Activation sets the prior effective_to automatically	Yes.
Old transactions are not retroactively re-applied	Correct — guides apply at generate / parse time.
Diff between versions reads cleanly	Yes — adds in green, removes in red, changes side-by-side.

Troubleshooting

Symptom	Cause	Fix
Activation blocked: "another version covers this window"	Effective windows overlap	Edit one version's effective_to to clear the overlap.
Clone shows zero rules	Cloned a version that itself was empty	Confirm the source version; if you meant a different source, clone from that one.
Activate succeeds but new transactions still use the old version	effective_from is later than today	Wait, or reactivate with today's date.
Operator cannot reactivate	Missing edi.companion-guide.activate scope	Ask a tenant admin or platform support.

Next

7.4 — State examples (Ohio MITS)