Configs and Snapshots

Where authoring ends

Nothing on this page changes what any environment serves. Authoring produces an approved snapshot and stops there. Bindings, the promotion gate, waivers, rollback and the audit trail all live on Promotion and gates.

That division is the point. A draft can be edited as carelessly as you like, because editing it cannot reach production. Publishing turns a draft into a fixed artefact that can be reviewed, compared, and pointed at. Only a separate promotion act makes it live.

The objects

A config starts with an empty draft at revision zero. It has no posture, no snapshots, and no effect on anything until you edit and publish it.

Editing a draft

Three properties of draft editing are worth knowing before you start, because each one surprises somebody:

An edit replaces the whole draft. A draft write is not a merge of the fields you sent into the fields already stored. It replaces the stored posture with the document you send. If you send only a frameworks list, you have also cleared the controls, forbidden entries and rules that were there. Read the current draft, change it, and send the whole thing back.

A draft is not validated when you save it. An unknown framework id, a control id that does not exist, a rule parameter of the wrong type — all of these save without complaint. They surface later, when you resolve or publish, as a rejected request. A stored draft is therefore not evidence that the posture is valid.

Concurrent edits are detected, not merged. Every write states which revision it expects to be replacing. If someone else changed the draft since you read it, your write is refused rather than silently overwriting theirs. You re-read and re-apply. Two people editing the same config will collide loudly; that is the intended behaviour.

Publishing

Publishing takes the draft as it currently stands, resolves it, and writes an immutable snapshot recording the resolved posture, the draft revision it came from, the publisher, and the publication time. Its status is published.

What publishing does not do:

• It does not check coverage. A posture that leaves framework clauses uncovered publishes normally.
• It does not check approval, protection, or segregation of duties. Those belong to approval and promotion.
• It does not change your draft's content. The draft stays exactly as it was and remains editable.

A publish that resolves cleanly always succeeds in producing a snapshot; a publish of an invalid draft is refused with the specific validation failure. Publishing is retry-safe when you supply an idempotency key — the exact semantics, including what happens when a key is reused, are in the operator section below.

What "resolved" means

A draft names frameworks. A snapshot names controls. Resolution is the step in between, and it happens once, at publication:

1. Frameworks expand. Each enabled framework contributes the set of control ids the catalog associates with it. Multiple frameworks are unioned, so a control required by two frameworks appears once.
2. Forbidden controls subtract. Anything in forbidden is removed from the framework-derived set. This is the only way to drop a control a framework brought in.
3. Explicit controls add. Anything in controls is added, whether or not a framework asked for it. A control cannot appear in both controls and forbidden; that combination is rejected rather than resolved to one or the other.
4. Operational rules are validated and filled. Each rule is checked against its catalog parameter schema, unknown parameters are rejected, type mismatches are rejected, and parameters you omitted that have catalog defaults are written into the snapshot with those defaults. A parameter with no default that you omitted is simply absent from the snapshot, not present-and-null.

The result stored in the snapshot is the list of enabled frameworks, a sorted list of effective control ids, and the fully-filled rules. Nothing in a snapshot is a reference to be looked up later — the control list is literal, so a later change to what a framework contains does not alter a snapshot that has already been published.

Coverage

Coverage answers one question: for each framework you enabled, how many of its clauses does your effective control set still cover, and which ones does it not?

It is a per-framework count, computed against that framework's own controls. A control that belongs to some other framework does not cover this one's clauses, even if it is in your effective set. So adding controls broadly does not raise coverage; only controls the catalog associates with that framework's clauses do.

Two things about coverage that matter more than the number itself:

Coverage is not frozen into the snapshot. It is recomputed, on demand, from the snapshot's stored control list against the catalog as it exists when you ask. The snapshot's content cannot change, but the coverage verdict reported for it can — a catalog update that adds controls or clauses to a framework changes the answer for snapshots published before it. Treat a coverage result as a reading taken at a moment, not as a property of the snapshot.

A posture with no frameworks enabled has nothing to be uncovered. Coverage is computed per enabled framework, so a draft that enables none produces an empty coverage result, and an empty result contains no uncovered clauses. An empty or framework-free posture therefore publishes, approves, and satisfies every coverage condition the promotion gate can apply. If your intent is that production always enforces something, coverage will not tell you when it does not — check that the frameworks you expect are actually enabled.

The three previews

Three read-only surfaces answer three different questions. None of them writes anything.

One trap in reading a dry run. If the target environment has no binding yet, the comparison runs against an empty posture, so every control in your draft appears under "added" and nothing appears under "removed". That output is correct, but it looks identical to the output you get from naming an environment that does not exist — the environment name in a dry-run request is not checked against the three real environment names. A full-add diff means either "this environment is unbound" or "you mistyped the environment". Confirm which before drawing a conclusion from it.

Why publish and approve are separate

Publishing is a statement about the artefact: this posture is finished and will not change. Approving is a statement about a person: someone accountable looked at it.

Keeping them apart buys two things. A protected environment can require the second signal, so no one reaches production merely by being able to publish. And when segregation of duties is enabled for an organization, the publisher and the approver can be required to be different people — which is only expressible if the two acts are recorded separately.

What authoring does not do

Worth knowing before you build a process on top of it:

• There is no unpublish and no snapshot delete. A snapshot you published by mistake stays in the list. Publish a corrected one and use that.
• Approval is one-way. There is no reject state and no way to return an approved snapshot to published. If an approval was wrong, the remedy is to publish and approve a replacement, not to withdraw the old one.
• A config cannot be deleted or archived. Configs accumulate. Naming them well matters more than it looks like it should, and nothing enforces that two configs have distinct names or slugs.
• Nothing schedules or automates publication. Publishing, approving and promoting are all explicit acts by a caller.

Operating the authoring flow

The rest of this page is the operator's half: the exact optimistic-locking and idempotency behaviour and the statuses each failure returns, the precise scope of snapshot immutability, which resolution inputs are validated against the catalog and which are trusted, how coverage attributes an uncovered clause, and the permission each authoring action requires.

Related

• Promotion and gates — bindings, the promotion gate, waivers, rollback, audit
• Projects and environments — project structure and environment protection
• Access control — the full permission model