Versions

A policy is a sequence of numbered versions. Each version is one complete policy document with a digest (sha256:…) that fingerprints it. Exactly one version, or none, is active at a time: the Gateway reads the active version on every call.

Versions are immutable. Once saved, a version's document, digest and number never change and the version is never deleted. Every change to a policy is therefore a new version, and the full history stays readable.

Version statuses

K-Block enforces these rules for every change, whether it comes from the dashboard or the API: no member and no API key can delete a version, change a stored document or digest, change a superseded version, or turn an active version back into a draft.

A superseded version can never be activated again (409 INVALID_STATE). To bring its document back, roll back to it: K-Block creates an exact copy as a new version and activates it. See Roll back.

Where versions come from

Each version records how it was created. The Versions tab shows this as a badge and a sentence.

Versions are numbered in order: the next version is always the highest number plus one. Rollbacks and emergency stops also create new numbers, so v9 can be a copy of v4. The Versions tab then shows v9 = restore of v4 and a same as v4 badge, because both have the same digest.

The API can also create a draft that is an exact copy of an earlier version (POST …/versions with restore_version_id), without activating it. The dashboard has no button for this.

Create a new version

To change a policy, open the version you want to start from, edit, and save:

1. Open a version in the editor

   On the Versions tab, select Open on any version. The Editor tab loads its document. The editor opens on the active version by default.

2. Edit and validate

   Change the JSON and select Validate on server. See Rules, amounts and currencies.

3. Save

   Add an optional note and select Save as new version. The new draft records which version it was based on ("edited from v7").

If an identical draft already exists, saving is refused with 409 DRAFT_EXISTS: work with that draft instead. An organization can hold at most 5000 policy versions, and 64 MiB of stored policy documents, across all its policies (409 POLICY_VERSION_LIMIT). Drafts count too and cannot be deleted, so avoid saving throwaway versions. Rollbacks and emergency stops are never refused by this limit, but the versions they create count towards it.

The active version

The summary at the top of the policy page shows the active version (Active v7), when and by whom it was activated, and its digest. Other states:

• No active version: every call of its agents is denied: nothing was activated yet. The Gateway refuses every call of the policy's agents with NO_POLICY.
• Emergency stop v12: the active version is an emergency stop. See Emergency stop.

Only activation, rollback and emergency stop change the active version. Each takes effect on the next call of every agent assigned to the policy. See Activate, roll out and roll back.

Compare versions

On the Versions tab, select Diff vs active on any version other than the active one. The diff has two parts:

• Decisions that change: for each of your enabled tools, the calls (and amount ranges) that the two versions decide differently, for example "issue_refund, more than 100 and up to 1000 USD: allow (refund-auto) becomes require approval (refund-approval)". This is computed from the documents and your tools, not from recorded calls. It is followed by Rule changes: rules added, removed, changed or reordered, and a changed default.
• Document changes, line by line: a text diff of the two JSON documents. It is not shown when either document has more than 2000 lines.

The activation sheet shows the same diff against the active version before you confirm. To see how a version would have decided your agents' recorded calls, use the Simulate tab; see Test and simulate.

The same comparison is available from the Cloud API: GET /orgs/:orgId/policies/:id/diff?from=<version-id>&to=<version-id>.

Read the history

The Versions tab lists every version, newest first. For each version it shows:

• the number, status and origin badge, and badges for shadow · not enforced, same as v… and revision 2 (the document uses rule descriptions or guards);
• a provenance sentence, such as v1 from template support-refunds@1, edited from v3, v10 = v8 with denials as approvals or Emergency stop: denies every call;
• the note given when it was saved;
• who created it and when, and who activated it and when;
• its digest, with a copy button.

Every change is also recorded in the audit log: policy.created, policy.version_created, policy.activated (with what triggered it: activation, shadow promotion, rollback or emergency stop), policy.rolled_back, policy.emergency_stopped, policy.shadow_started, policy.shadow_stopped, policy.examples_updated, policy.simulation_saved and policy.disclosure_changed. Each activation also sends a policy.activated webhook to endpoints subscribed to it.

Evidence bundle

Owners and admins can export a policy's history as one JSON file: on the policy page, open the menu next to the header buttons and select Download evidence (90 days). It contains the policy's versions, its policy.* audit events, saved simulations, the observe windows of the agents assigned to it now, and decision counts per version. Through the API (GET /orgs/:orgId/policies/:id/evidence?from=…&to=…, signed-in owners and admins only, never API keys), the window can be up to 400 days.

Limitations

• Policies, versions and drafts cannot be deleted, and policies cannot be renamed.
• The policy page loads at most the 200 newest versions. If the active version is older than the 200 newest, the page can wrongly show No active version and rollback targets beyond that range are not listed, although the Gateway still uses the active version.
• A policy created through the API together with its first document records policy.created but no separate policy.version_created event for v1.

Next steps