@parmanasystems/governance

Policy definition, compilation, validation, and bundle loading. This package owns the lifecycle of a governance policy from its source JSON file through compilation, schema validation, and bundle generation to runtime loading. Policies are immutable once bundled — upgradePolicy creates a new version rather than mutating an existing one.

Public API

/**
 * Create a new policy definition file at the given path.
 * Writes the policy JSON scaffold and sets up the directory structure.
 */
function createPolicy(options: {
  policyId: string;
  policyVersion: string;
  outputDir: string;
}): void

/**
 * Alternative policy builder that accepts an in-memory PolicyDefinition
 * and returns a compiled policy ready for generateBundle().
 */
function definePolicy(definition: PolicyDefinition): CompiledPolicy

/**
 * Compile a policy from its source directory.
 * Reads policy.json, validates the schema, resolves signal types and rule conditions.
 * Returns a PolicyCompileResult with success/error/warning details.
 */
function compilePolicy(policyPath: string): PolicyCompileResult

/**
 * Validate a compiled or raw policy for semantic correctness.
 * Checks signal schema consistency, rule condition references, and catch-all rules.
 */
function validatePolicy(policy: unknown): PolicyCompileResult

/**
 * Generate a signed bundle from the policy at `policyPath`.
 * Compiles the policy, writes artifacts to `outputDir`, runs generateManifest,
 * and optionally signs the manifest with `signer`.
 * Returns a BundleGenerationResult.
 */
function generateBundle(options: {
  policyPath: string;
  outputDir: string;
  signer?: (payload: string) => Promise<string>;
}): Promise<BundleGenerationResult>

/**
 * Create a new policy version by copying the previous version's source
 * into a new version directory.
 */
function upgradePolicy(options: {
  policyId: string;
  fromVersion: string;
  toVersion: string;
  policiesRoot: string;
}): void

/**
 * Load and verify a compiled policy bundle from disk at runtime.
 * Verifies the bundle manifest signature using `publicKey` before returning the policy.
 * Throws if the manifest signature is invalid.
 */
function loadPolicyBundle(bundlePath: string, publicKey: string): CompiledPolicy

/**
 * Load the JSON Schema validators for schema version `v1`.
 * Used internally by compilePolicy and validatePolicy.
 */
function loadSchemaRuntime(): SchemaRuntime

// ── Types ──────────────────────────────────────────────────────────────────

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

interface PolicyRule {
  id: string;
  condition: RuleCondition;
  outcome: {
    action: "approve" | "reject";
    requires_override: boolean;
    reason?: string;
  };
}

type RuleCondition = BaseCondition | AllCondition | AnyCondition

interface BaseCondition {
  signal: string;
  equals?: unknown;
  greater_than?: number;
  less_than?: number;
}

interface AllCondition { all: RuleCondition[] }
interface AnyCondition { any: RuleCondition[] }

// Legacy shape used by definePolicy():
interface DefinePolicyRule {
  id: string;
  condition: string;
  action: string;
}

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

interface RuntimeRequirements {
  supportedRuntimeVersions: string[];
  supportedSchemaVersions: string[];
}

interface PolicyCompileResult {
  success: boolean;
  errors: PolicyCompileError[];
  warnings: PolicyCompileWarning[];
}

interface PolicyCompileError { code: string; message: string }
interface PolicyCompileWarning { code: string; message: string }

Environment variables

None at the library level. When used through @parmanasystems/execution-runtime, the caller provides the policiesRootPath.

Package wiring

@parmanasystems/governance depends on @parmanasystems/canonical (for deterministic serialization) and @parmanasystems/bundle (for manifest generation). It is consumed by @parmanasystems/execution-runtime (loadPolicyBundle is called inside executeFromSignals) and by @parmanasystems/core (which re-exports createPolicy, upgradePolicy, validatePolicy, generateBundle). Build scripts use it through scripts/governance/build-policies.ts.