@parmanasystems/governance 1.69.0 → 1.71.2

package/README.md

@@ -1,472 +1,111 @@
 # @parmanasystems/governance
 
-Governance lifecycle infrastructure for deterministic policy versioning, validation, bundling, and release management.
+Policy lifecycle management — create, upgrade, validate, and bundle governance policies.
 
 [![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.
+`@parmanasystems/governance` handles the full policy authoring lifecycle: scaffolding new policies, creating immutable version upgrades, validating policy schemas, and packaging policies into signed bundles for deployment.
 
 ---
 
-# 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:
+## Install
 
-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:
+```bash
+npm install @parmanasystems/governance
+```
 
-executing governed decisions
-independently verifying attestations
-deploying HTTP runtimes
-integrating applications over HTTP
+---
 
-In those cases use:
+## Usage
 
-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
+```typescript
 import {
   createPolicy,
   validatePolicy,
   generateBundle,
+  definePolicy,
 } from "@parmanasystems/governance";
 
-await createPolicy(
-  "claims-approval"
-);
-
-await validatePolicy(
-  "./policies/claims-approval/v1/policy.json"
-);
-
-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
-
-Policies define governed input structure explicitly.
-
-Example:
-
-{
-  "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
-    }
-  },
-
-  "rules": [
+// Scaffold a new policy at ./policies/loan-approval/v1/policy.json
+const dir = createPolicy("loan-approval");
+console.log(dir); // "./policies/loan-approval/v1"
 
+// Define a policy in memory
+const policy = definePolicy({
+  id:      "loan-approval",
+  version: "v1",
+  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:        "high-score",
+      condition: "credit_score >= 700 && requested_usd <= 100000",
+      action:    "approve",
     },
-
     {
-      "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 deterministically in order.
-
-The first matching rule determines the governed outcome.
-
-If no rule matches, evaluation fails closed.
-
-Governance Lifecycle APIs
-createPolicy
-
-Scaffolds a governance policy directory.
-
-import {
-  createPolicy
-} from "@parmanasystems/governance";
-
-await createPolicy(
-  "fraud-detection"
-);
-definePolicy
-
-Creates a policy definition in memory.
-
-import {
-  definePolicy
-} from "@parmanasystems/governance";
-
-const policy =
-  definePolicy({
-
-    id:
-      "claims-approval",
-
-    version:
-      "v1",
-
-    rules: [],
-  });
-validatePolicy
-
-Validates governance structure.
-
-Checks:
-
-schemaVersion
-signalsSchema
-rules
-outcomes
-deterministic structure
-import {
-  validatePolicy
-} from "@parmanasystems/governance";
+      id:        "default-reject",
+      condition: "true",
+      action:    "reject",
+    },
+  ],
+});
 
+// Validate before bundling
 validatePolicy(policy);
-upgradePolicy
-
-Creates immutable next-version governance lineage.
 
-import {
-  upgradePolicy
-} from "@parmanasystems/governance";
+// Package into a signed bundle
+const result = await generateBundle({
+  policyPath: "./policies/loan-approval/v1",
+  outputPath: "./dist/bundles/loan-approval",
+});
 
-const v2 =
-  upgradePolicy(
-    policyV1,
-    "v2"
-  );
-generateBundle
+console.log(result.success);     // true
+console.log(result.bundle_hash); // SHA-256 commitment
+```
 
-Generates deterministic governance bundles.
+### Upgrade an existing policy
 
-Produces:
+```typescript
+import { upgradePolicy } from "@parmanasystems/governance";
 
-bundle.manifest.json
-bundle.sig
-import {
-  generateBundle
-} from "@parmanasystems/governance";
+// Creates ./policies/loan-approval/v2/ from ./policies/loan-approval/v1/
+const newDir = upgradePolicy("loan-approval");
+```
 
-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:
+---
 
-interface RuntimeRequirements {
+## Exports
 
-  required_capabilities:
-    string[];
+### Functions
 
-  supported_runtime_versions:
-    string[];
+| Export | Description |
+|---|---|
+| `createPolicy` | Scaffold a new policy directory at `./policies/<id>/v1/` with a skeleton `policy.json` |
+| `upgradePolicy` | Create the next version directory from the current latest version |
+| `validatePolicy` | Validate a policy definition against the governance schema; throws on invalid input |
+| `generateBundle` | Package a policy directory into a content-addressed, signed bundle |
+| `definePolicy` | Construct a typed `PolicyDefinition` in memory |
 
-  supported_schema_versions:
-    string[];
-}
+### Types
 
-This enables deterministic compatibility enforcement.
+| Export | Description |
+|---|---|
+| `PolicyDefinition` | In-memory policy with `id`, `version`, and ordered `rules` |
+| `PolicyRule` | Single rule: `id`, `condition` expression, and `action` |
+| `BundleGenerationResult` | Result of `generateBundle` — success flag, paths, and `bundle_hash` |
+| `RuntimeRequirements` | Runtime capability and version constraints embedded in bundles |
 
-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:
+## Documentation
 
-immutable policy lineage
-deterministic governance structure
-fail-closed validation
-signed governance artifacts
-reproducible governance releases
-canonical manifest integrity
-runtime compatibility enforcement
+Full docs: [parmanasystems.mintlify.app](https://parmanasystems.mintlify.app)
+Package page: [parmanasystems.mintlify.app/packages/governance](https://parmanasystems.mintlify.app/packages/governance)
 
-Governance artifacts are designed to be:
+---
 
-portable
-reproducible
-independently verifiable
-Most Important Principle
-Governance policies are immutable, reproducible infrastructure artifacts with deterministic lineage.
-License
+## License
 
-Apache-2.0
+Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parmanasystems/governance",
-  "version": "1.69.0",
+  "version": "1.71.2",
   "private": false,
   "type": "module",
   "scripts": {
@@ -18,9 +18,9 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@parmanasystems/bundle": "^1.69.0",
-    "@parmanasystems/crypto": "^1.69.0",
-    "@parmanasystems/contracts": "^1.69.0"
+    "@parmanasystems/bundle": "^1.71.2",
+    "@parmanasystems/crypto": "^1.71.2",
+    "@parmanasystems/contracts": "^1.71.2"
   },
   "description": "Deterministic governance lifecycle and policy infrastructure for parmanasystems.",
   "license": "Apache-2.0",
@@ -28,7 +28,7 @@
     "type": "git",
     "url": "https://github.com/pavancharak/parmanasystems-core.git"
   },
-  "homepage": "https://github.com/pavancharak/parmanasystems-core",
+  "homepage": "https://parmanasystems.mintlify.app",
   "bugs": {
     "url": "https://github.com/pavancharak/parmanasystems-core/issues"
   },