@parmanasystems/governance 1.56.0 → 1.59.0

package/README.md

@@ -1,49 +1,288 @@
 # @parmanasystems/governance
 
-Policy lifecycle tooling for the parmanasystems deterministic governance runtime.
+Governance lifecycle infrastructure for deterministic policy versioning, validation, bundling, and release management.
 
 [![npm](https://img.shields.io/npm/v/@parmanasystems/governance)](https://www.npmjs.com/package/@parmanasystems/governance)
 
-## Overview
+---
+
+# Overview
+
+`@parmanasystems/governance` provides the governance lifecycle layer for Parmana Systems.
+
+It manages:
+
+- policy creation
+- policy validation
+- immutable policy lineage
+- governance versioning
+- deterministic governance bundles
+- signed governance artifacts
+- reproducible governance releases
+
+Governance policies are treated as immutable, reproducible infrastructure artifacts.
+
+---
+
+# Mental Model
+
+```txt id="9b6j2m"
+Author Policy
+    ↓
+Validate Policy
+    ↓
+Generate Bundle
+    ↓
+Sign Bundle
+    ↓
+Release Governance Artifact
+    ↓
+Execute Governed Decisions
+    ↓
+Independent Verification
+
+The governance layer defines how policies become reproducible, portable, and verifiable governance infrastructure.
+
+What this package does
+
+The governance package handles:
+
+policy scaffolding
+policy validation
+policy version upgrades
+governance bundle generation
+deterministic manifest generation
+governance artifact signing
+immutable policy lineage management
+governance release reproducibility
+
+Policies are versioned governance artifacts with deterministic provenance.
+
+When to use this package
+
+Use this package when:
+
+creating governance policies
+versioning deterministic governance logic
+validating governance structure
+generating signed governance bundles
+implementing governed release workflows
+managing immutable governance lineage
+building governance authoring pipelines
+
+Do NOT use this package when:
+
+executing governed decisions
+independently verifying attestations
+deploying HTTP runtimes
+integrating applications over HTTP
+
+In those cases use:
+
+Package	Responsibility
+@parmanasystems/execution	governed execution
+@parmanasystems/verifier	independent verification
+@parmanasystems/server	deployable runtime
+@parmanasystems/sdk-client	HTTP integration
+Features
+Immutable governance versioning
+Deterministic policy validation
+Signed governance bundles
+Canonical manifest generation
+Runtime compatibility requirements
+Portable governance artifacts
+Governance provenance lineage
+Deterministic governance releases
+Fail-closed governance validation
+Installation
+npm install @parmanasystems/governance
+Quick Start
+import {
+  createPolicy,
+  validatePolicy,
+  generateBundle,
+} from "@parmanasystems/governance";
 
-`@parmanasystems/governance` provides the policy management layer — creating, validating, versioning, and bundling governance policies before they enter the deterministic execution runtime.
+await createPolicy(
+  "claims-approval"
+);
 
-## Installation
+await validatePolicy(
+  "./policies/claims-approval/v1/policy.json"
+);
 
-```bash
-npm install @parmanasystems/governance
-```
+const bundle =
+  await generateBundle(
+    "claims-approval",
+    "v1",
+    "./policies/claims-approval/v1"
+  );
+
+console.log(
+  bundle.bundle_hash
+);
+Core Concepts
+Immutable Policy Lineage
+
+Policies are immutable governance artifacts.
+
+Example lineage:
+
+claims-approval/
+  v1/
+  v2/
+  v3/
+
+Older policy versions remain immutable after release.
+
+New governance behavior requires new versions.
+
+This ensures:
+
+reproducibility
+auditability
+deterministic governance lineage
+historical governance integrity
+signalsSchema
 
-## Policy structure
+Policies define governed input structure explicitly.
 
-Policies live at `policies/{policyId}/{version}/policy.json`:
+Example:
 
-```json
 {
+  "signalsSchema": {
+    "risk_score": {
+      "type": "integer",
+      "required": true
+    }
+  }
+}
+
+Signals are:
+
+typed
+deterministic
+explicitly governed
+schema validated
+Governance Bundles
+
+Governance bundles package deterministic governance artifacts.
+
+Bundles include:
+
+policy definition
+canonical manifest
+governance hashes
+signatures
+provenance metadata
+
+Bundles are:
+
+deterministic
+portable
+reproducible
+independently verifiable
+Bundle Provenance
+
+Governance provenance includes:
+
+deterministic hashes
+canonical manifests
+cryptographic signatures
+runtime compatibility lineage
+
+This enables:
+
+reproducible releases
+independent verification
+governance auditability
+portable governance validation
+Fail-Closed Governance
+
+Governance validation is fail-closed.
+
+Invalid governance artifacts reject execution.
+
+Validation failures include:
+
+malformed policies
+invalid schemas
+invalid rule structure
+compatibility violations
+signature failures
+Policy Structure
+
+Policies live at:
+
+policies/{policyId}/{version}/policy.json
+
+Example:
+
+policies/
+  claims-approval/
+    v1/
+      policy.json
+Example Policy
+{
+  "policyId": "claims-approval",
+
+  "version": "v1",
+
   "schemaVersion": "1.0.0",
+
   "signalsSchema": {
-    "insurance_active": { "type": "boolean", "required": true },
-    "risk_score":        { "type": "integer", "required": true },
-    "claim_amount":      { "type": "integer", "required": false }
+
+    "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 }
+
+          {
+            "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 },
+
+      "condition": {
+        "signal": "risk_score",
+        "greater_than": 80
+      },
+
       "outcome": {
         "action": "reject",
         "requires_override": false,
@@ -52,124 +291,182 @@ Policies live at `policies/{policyId}/{version}/policy.json`:
     }
   ]
 }
-```
-
-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>`
+Rules are evaluated deterministically in order.
 
-Scaffolds a new policy directory at `./policies/{policyId}/v1/policy.json`.
+The first matching rule determines the governed outcome.
 
-```typescript
-import { createPolicy } from "@parmanasystems/governance";
-await createPolicy("fraud-detection");
-```
+If no rule matches, evaluation fails closed.
 
-### `definePolicy(options): PolicyDefinition`
+Governance Lifecycle APIs
+createPolicy
 
-Builds a `PolicyDefinition` object in memory.
+Scaffolds a governance policy directory.
 
-```typescript
-import { definePolicy } from "@parmanasystems/governance";
+import {
+  createPolicy
+} from "@parmanasystems/governance";
 
-const policy = definePolicy({
-  id:      "claims-approval",
-  version: "v1",
-  rules:   [...],
-});
-```
+await createPolicy(
+  "fraud-detection"
+);
+definePolicy
 
-### `validatePolicy(policy): void`
+Creates a policy definition in memory.
 
-Validates policy structure. Throws on missing `schemaVersion`, invalid `signalsSchema`, missing `rules`, or malformed `outcome` fields.
+import {
+  definePolicy
+} from "@parmanasystems/governance";
 
-```typescript
-import { validatePolicy } from "@parmanasystems/governance";
-validatePolicy(policy);
-```
-
-### `upgradePolicy(policy, nextVersion): PolicyDefinition`
-
-Creates a new version of an existing policy.
-
-```typescript
-import { upgradePolicy } from "@parmanasystems/governance";
-const v2 = upgradePolicy(policyV1, "v2");
-```
-
-### `generateBundle(policyId, version, directory): Promise<BundleGenerationResult>`
-
-Generates `bundle.manifest.json` and signs it as `bundle.sig`.
-
-```typescript
-import { generateBundle } from "@parmanasystems/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>`
+const policy =
+  definePolicy({
 
-Verifies the `bundle.manifest.json` signature and hash integrity.
+    id:
+      "claims-approval",
 
-```typescript
-import { verifyBundle } from "@parmanasystems/governance";
-const ok = await verifyBundle("./policies/claims-approval/v1");
-```
+    version:
+      "v1",
 
-## Types
+    rules: [],
+  });
+validatePolicy
 
-### PolicyDefinition
+Validates governance structure.
 
-```typescript
-interface PolicyDefinition {
-  id: string;
-  version: string;
-  rules: PolicyRule[];
-}
-
-interface PolicyRule {
-  id: string;
-  condition: string;
-  action: string;
-}
-```
+Checks:
 
-### BundleGenerationResult
-
-```typescript
-interface BundleGenerationResult {
-  success: boolean;
-  manifest_path: string;
-  signature_path: string;
-  bundle_hash: string;
-}
-```
+schemaVersion
+signalsSchema
+rules
+outcomes
+deterministic structure
+import {
+  validatePolicy
+} from "@parmanasystems/governance";
 
-### RuntimeRequirements
+validatePolicy(policy);
+upgradePolicy
+
+Creates immutable next-version governance lineage.
+
+import {
+  upgradePolicy
+} from "@parmanasystems/governance";
+
+const v2 =
+  upgradePolicy(
+    policyV1,
+    "v2"
+  );
+generateBundle
+
+Generates deterministic governance bundles.
+
+Produces:
+
+bundle.manifest.json
+bundle.sig
+import {
+  generateBundle
+} from "@parmanasystems/governance";
+
+const result =
+  await generateBundle(
+    "claims-approval",
+    "v1",
+    "./policies/claims-approval/v1"
+  );
+
+console.log(
+  result.bundle_hash
+);
+verifyBundle
+
+Verifies governance bundle integrity.
+
+Checks:
+
+signatures
+hashes
+manifest integrity
+import {
+  verifyBundle
+} from "@parmanasystems/governance";
+
+const valid =
+  await verifyBundle(
+    "./policies/claims-approval/v1"
+  );
+Governance Bundle Structure
+claims-approval/
+  v1/
+    policy.json
+    bundle.manifest.json
+    bundle.sig
+Runtime Requirements
+
+Governance bundles may specify runtime compatibility requirements.
+
+Example:
 
-```typescript
 interface RuntimeRequirements {
-  required_capabilities: string[];
-  supported_runtime_versions: string[];
-  supported_schema_versions: string[];
-}
-```
 
-## Included policies
+  required_capabilities:
+    string[];
 
-The repository ships with example policies under `policies/`:
+  supported_runtime_versions:
+    string[];
 
-| 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
+  supported_schema_versions:
+    string[];
+}
 
-Apache-2.0
+This enables deterministic compatibility enforcement.
+
+Included Example Policies
+Policy	Versions	Description
+claims-approval	v1, v2	insurance claims governance
+patient-triage	v1	healthcare triage routing
+fraud-detection	v1	transaction fraud governance
+claims-advanced	v1	advanced multi-condition evaluation
+Recommended Architecture
+Governance Authoring
+        ↓
+Policy Validation
+        ↓
+Governance Bundle
+        ↓
+Signed Governance Artifact
+        ↓
+Governed Runtime Execution
+        ↓
+Independent Verification
+Relationship to Other Parmana Packages
+Package	Responsibility
+@parmanasystems/governance	governance lifecycle
+@parmanasystems/execution	governed execution
+@parmanasystems/verifier	independent verification
+@parmanasystems/bundle	canonical governance artifacts
+@parmanasystems/server	deployable runtime
+Security Model
+
+The governance layer enforces:
+
+immutable policy lineage
+deterministic governance structure
+fail-closed validation
+signed governance artifacts
+reproducible governance releases
+canonical manifest integrity
+runtime compatibility enforcement
+
+Governance artifacts are designed to be:
+
+portable
+reproducible
+independently verifiable
+Most Important Principle
+Governance policies are immutable, reproducible infrastructure artifacts with deterministic lineage.
+License
+
+Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parmanasystems/governance",
-  "version": "1.56.0",
+  "version": "1.59.0",
   "private": false,
   "type": "module",
   "scripts": {
@@ -18,9 +18,9 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@parmanasystems/bundle": "^1.56.0",
-    "@parmanasystems/crypto": "^1.56.0",
-    "@parmanasystems/contracts": "^1.56.0"
+    "@parmanasystems/bundle": "^1.59.0",
+    "@parmanasystems/crypto": "^1.59.0",
+    "@parmanasystems/contracts": "^1.59.0"
   },
   "description": "Deterministic governance lifecycle and policy infrastructure for parmanasystems.",
   "license": "Apache-2.0",