Configs and snapshots

This page is for the admin who authors the compliance posture each environment will serve, and for the approver who signs it off. By the end you will have a published, approved snapshot: a frozen list of frameworks, controls and operational rules that is ready to promote.

How it works

Nothing on this page changes what any environment serves. Authoring produces an approved snapshot and stops there; bindings, the promotion gate, waivers and rollback live on Promotion and gates. A draft can be edited freely, because editing it cannot reach production. Publishing turns a draft into a fixed artefact that can be reviewed, compared and pointed at.

The objects

This page owns these three objects; Promotion and gates owns bindings and waivers.

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.

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.

This page owns that distinction. Other pages link here. Keeping the two acts apart buys two things. A protected environment can require the second signal. So no one reaches production just by being able to publish. Also, when separation of duties is enabled for an organization, the publisher and the approver can be required to be different people. That is only expressible if the two acts are recorded separately.

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.

Author and publish a posture

1. Read the current draft, change it, and send the whole document back: an edit replaces the draft.
2. Resolve it to see the effective control list and coverage before saving anything.
3. Dry-run it against the environment you intend to change, to see the controls added and removed.
4. Publish it. Send an idempotency key if your client retries.
5. Have an approver approve the snapshot. Approval needs the approver capability or the owner role.
6. Promote it on Promotion and gates, after checking the promotion preview.

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 your current draft, resolves it, and writes an unchangeable snapshot. That snapshot records the resolved posture, the draft revision it came from, who published it, and the time. The status becomes 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 separation 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.

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.

What it does not do

• 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.

Who may do what

Any member can list and read configs, drafts and snapshots. Editing a draft, the resolve preview and the dry run need config:edit; publishing needs config:publish; approving needs the approver capability or the owner role. Two details are easy to get wrong:

• Creating a config needs project:manage, not config:edit. Someone who can edit every posture cannot necessarily add one.
• Coverage is visible at two levels. The resolve preview needs config:edit; the promotion preview, which also reports coverage, is open to any member.

The full table is on Access control.

What gets recorded

Publishing and approving each write a record in the audit trail. Editing a draft and creating a config write none. The snapshot itself also records its publisher, publication time, approver and approval time, and is never deleted.

Operating details

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, and how coverage attributes an uncovered clause.

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