> ## Documentation Index
> Fetch the complete documentation index at: https://docs.manthan.systems/llms.txt
> Use this file to discover all available pages before exploring further.

# Policy Versioning

> How to safely update governance policies without breaking audit history

## The immutability guarantee

Once a policy version is signed and deployed, it is **immutable**. You cannot modify a signed policy - you create a new version instead.

This means every historical decision can always be re-evaluated against the exact policy version that governed it. The `policyVersion` in every attestation is a permanent, auditable reference.

## Version format

Versions use semver format: `1.0.0`, `1.0.1`, `2.0.0`.

The v-prefix format (`v1`, `v2`) is not supported and will be rejected by the policy compiler with error `POL-022`.

## Creating a new version

### Via the CLI

```bash theme={null}
npx parmana workspace upgrade my-policy
```

### Via the API

```typescript theme={null}
import { upgradePolicy } from "@parmanasystems/governance";

// Creates policies/my-policy/1.0.1/ from 1.0.0/
const newDir = upgradePolicy("my-policy");
```

Then edit `policy.json` in the new directory, compile, and sign:

```bash theme={null}
npx parmana policy compile ./policies/my-policy/1.0.1
npx parmana policy build   ./policies/my-policy/1.0.1
```

## Running multiple versions simultaneously

Multiple policy versions can coexist - old clients can continue using the previous version while new clients use the updated one:

```
policies/
  loan-approval/
    1.0.0/              ← still valid; old clients use this
      policy.json
      bundle.manifest.json
      bundle.sig
    1.0.1/              ← new clients use this
      policy.json
      bundle.manifest.json
      bundle.sig
```

Each execution specifies the version explicitly:

```typescript theme={null}
// Old client - still works
executeFromSignals({ policyId: "loan-approval", policyVersion: "1.0.0", signals });

// New client - uses updated policy
executeFromSignals({ policyId: "loan-approval", policyVersion: "1.0.1", signals });
```

## Rollback strategy

You cannot modify or roll back a deployed version. To revert to previous behavior:

1. Create a new version (e.g., `1.0.2`) with the old rules
2. Deploy `1.0.2`
3. Direct clients to use `1.0.2`

Keep all old versions. They remain valid indefinitely for verifying historical decisions - the attestation's `policyVersion` field identifies which rules governed each decision.

## What changes between versions

`upgradePolicy` copies the previous version's `policy.json` to the new directory and increments the patch version. You then edit the copy to make your changes. Common scenarios:

| Change type               | Version bump              | Notes                           |
| ------------------------- | ------------------------- | ------------------------------- |
| Rule threshold change     | patch (`1.0.0` → `1.0.1`) | Same signals schema             |
| New signal added          | minor or major            | Update `signalsSchema`          |
| Breaking rule restructure | major (`1.0.0` → `2.0.0`) | Existing clients need migration |

## Validating all versions

```typescript theme={null}
import { validatePolicy } from "@parmanasystems/governance";

const valid = validatePolicy("loan-approval", "./trust/root.pub");
// Returns true only when all version bundles are signed and their manifests are intact
```

## See also

* [Policies](/concepts/policies) - how policies are structured
* [Policy Schema Reference](/reference/policy-schema) - complete field reference
* [Write Your First Policy](/guides/first-policy) - create and sign a policy