Skip to main content

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.

​
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

npx parmana workspace upgrade my-policy

​
Via the API

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: 
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: 
// 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 typeVersion bumpNotes
Rule threshold changepatch (1.0.0 → 1.0.1)Same signals schema
New signal addedminor or majorUpdate signalsSchema
Breaking rule restructuremajor (1.0.0 → 2.0.0)Existing clients need migration

​
Validating all versions

import { validatePolicy } from "@parmanasystems/governance";

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

​
See also