@pramanasystems/governance

Policy lifecycle tooling for the PramanaSystems deterministic governance runtime.

Overview

@pramanasystems/governance provides the policy management layer — creating, validating, versioning, and bundling governance policies before they enter the deterministic execution runtime.

Installation

npm install @pramanasystems/governance

Policy structure

Policies live at policies/{policyId}/{version}/policy.json:

{
  "schemaVersion": "1.0.0",
  "signalsSchema": {
    "insurance_active": { "type": "boolean", "required": true },
    "risk_score":        { "type": "integer", "required": true },
    "claim_amount":      { "type": "integer", "required": false }
  },
  "rules": [
    {
      "id": "rule_low_risk",
      "condition": {
        "all": [
          { "signal": "insurance_active", "equals": true },
          { "signal": "risk_score", "less_than": 50 }
        ]
      },
      "outcome": {
        "action": "approve",
        "requires_override": false,
        "reason": "Low risk profile"
      }
    },
    {
      "id": "rule_high_risk",
      "condition": { "signal": "risk_score", "greater_than": 80 },
      "outcome": {
        "action": "reject",
        "requires_override": false,
        "reason": "Risk score too high"
      }
    }
  ]
}

Rules are evaluated in order. The first matching rule determines the outcome. If no rule matches, execution fails closed.

API

createPolicy(policyId: string): Promise<void>

Scaffolds a new policy directory at ./policies/{policyId}/v1/policy.json.

import { createPolicy } from "@pramanasystems/governance";
await createPolicy("fraud-detection");

definePolicy(options): PolicyDefinition

Builds a PolicyDefinition object in memory.

import { definePolicy } from "@pramanasystems/governance";

const policy = definePolicy({
  id:      "claims-approval",
  version: "v1",
  rules:   [...],
});

validatePolicy(policy): void

Validates policy structure. Throws on missing schemaVersion, invalid signalsSchema, missing rules, or malformed outcome fields.

import { validatePolicy } from "@pramanasystems/governance";
validatePolicy(policy);

upgradePolicy(policy, nextVersion): PolicyDefinition

Creates a new version of an existing policy.

import { upgradePolicy } from "@pramanasystems/governance";
const v2 = upgradePolicy(policyV1, "v2");

generateBundle(policyId, version, directory): Promise<BundleGenerationResult>

Generates bundle.manifest.json and signs it as bundle.sig.

import { generateBundle } from "@pramanasystems/governance";

const result = await generateBundle("claims-approval", "v1", "./policies/claims-approval/v1");
console.log(result.bundle_hash);   // SHA-256 of manifest
console.log(result.signature_path); // path to bundle.sig

verifyBundle(directory): Promise<boolean>

Verifies the bundle.manifest.json signature and hash integrity.

import { verifyBundle } from "@pramanasystems/governance";
const ok = await verifyBundle("./policies/claims-approval/v1");

Types

PolicyDefinition

interface PolicyDefinition {
  id: string;
  version: string;
  rules: PolicyRule[];
}

interface PolicyRule {
  id: string;
  condition: string;
  action: string;
}

BundleGenerationResult

interface BundleGenerationResult {
  success: boolean;
  manifest_path: string;
  signature_path: string;
  bundle_hash: string;
}

RuntimeRequirements

interface RuntimeRequirements {
  required_capabilities: string[];
  supported_runtime_versions: string[];
  supported_schema_versions: string[];
}

Included policies

The repository ships with example policies under policies/:

| Policy | Versions | Description | |---|---|---| | claims-approval | v1, v2 | Insurance claim approval with risk scoring | | patient-triage | v1 | Patient triage routing by severity | | fraud-detection | v1 | Transaction fraud detection | | claims-advanced | v1 | Advanced claims with multi-condition rules |

License

Apache-2.0