governance-ledger 0.1.1

Deterministic governance ledger, provenance, and policy translation for CRI-CORE.

---

title: "Governance-Ledger" document_type: "overview" system: "Governance-Ledger" component: "core" version: "0.1.1" status: "draft"

created: "2026-05-08" updated: "2026-05-10"

authors:

• "Waveframe Labs"

maintainers:

• "Waveframe Labs"

license: "Apache-2.0"

repository: "https://github.com/Waveframe-Labs/Governance-Ledger"

summary: > Conceptual entry point for Governance-Ledger, including purpose, boundaries, architecture, supported primitives, and basic usage.

related_components:

• "CRI-CORE"
• "Waveframe Guard"
• "Proposal Normalizer"
• "CRI-CORE Contract Compiler"

related_documents:

• "GOVERNANCE_OBJECT_MODEL.md"
• "LIFECYCLE.md"
• "PROVENANCE.md"
• "NON_GOALS.md"

governance_primitives:

• "review_artifact"
• "lifecycle_transition"
• "deployment_provenance"
• "snapshot"
• "rollback"
• "governance_diff"

determinism: deterministic_ids: true canonical_hashing: true mutable_history: false

provenance: review_lineage: true deployment_traceability: true rollback_traceability: true snapshot_integrity: true

ai_assisted: "partial"

notes: > Governance-Ledger is deterministic infrastructure for governance state evolution, not an autonomous policy reasoning system.

Governance-Ledger

Governance-Ledger is a deterministic governance operationalization layer for transforming human governance text into traceable, reviewable, executable governance artifacts compatible with CRI-CORE enforcement systems.

Why This Exists

Modern AI systems can generate probabilistic proposals, but execution authority must remain deterministic.

Governance-Ledger operationalizes organizational governance into reviewable, versioned contract artifacts used by runtime enforcement systems such as Waveframe Guard and CRI-CORE.

Setup

Create a virtual environment and install the release package:

python -m venv venv
.\venv\Scripts\Activate.ps1
pip install governance-ledger

Quickstart

Run the full first-pass operator workflow:

governance-ledger run policies
governance-ledger check generated
governance-ledger approve reviews/finance_policy.review.json --actor governance-team
governance-ledger publish reviews/finance_policy.review.json
governance-ledger list contracts

The generated publication manifest and contracts/index.json store artifact paths in POSIX style, for example contracts/finance-policy-0.1.0.contract.json, even on Windows.

Governance Ecosystem

• Governance-Ledger: governance operationalization.
• CRI-CORE Contract Compiler: canonical runtime contract semantics.
• Waveframe Guard: runtime SDK integration.
• Proposal Normalizer: canonical proposal assembly.
• CRI-CORE: deterministic admissibility enforcement.

Policy language enters as text. Governance-Ledger extracts supported primitives, surfaces unsupported language as warnings, tracks lifecycle state, links compiled contracts, records deployment lineage, and creates snapshots for audit and rollback.

What It Does

• Extraction of supported governance constraints.
• Structured review artifacts with source text attribution.
• Authoring validation with explicit warnings.
• Lifecycle transitions for review, approval, compilation, and deployment.
• Lightweight compiled contract linkage by identity, version, and hash.
• Deployment traceability.
• Snapshots of governance state.
• Rollback from snapshots without erasing history.
• Governance diffs across review versions, warnings, and deployments.

What It Is Not

Governance-Ledger is not:

• An AI governance engine.
• Autonomous policy reasoning.
• Runtime enforcement.
• Semantic governance inference.
• Legal interpretation AI.
• A replacement for human governance ownership.
• A runtime admissibility evaluator.
• A system that executes mutations.

It does not infer unsupported governance meaning. If language is unsupported or ambiguous, it becomes a warning instead of hidden structure.

Architecture

Policy Text
    |
    v
Extraction
    |
    v
Review Artifact
    |
    v
Validation Warnings
    |
    v
Lifecycle Approval
    |
    v
Compiled Contract Linkage
    |
    v
Deployment Provenance
    |
    v
Snapshot / Rollback
    |
    v
CRI-CORE Enforcement Compatibility

flowchart TD
    A["Policy Text"] --> B["Extraction"]
    B --> C["Review Artifact"]
    C --> D["Validation Warnings"]
    D --> E["Lifecycle Approval"]
    E --> F["Compiled Contract Linkage"]
    F --> G["Deployment Provenance"]
    G --> H["Snapshot"]
    H --> I["Rollback Lineage"]
    F --> J["CRI-CORE Enforcement Compatibility"]
    G --> J

stateDiagram-v2
    [*] --> pending
    pending --> reviewed
    pending --> rejected
    reviewed --> approved
    reviewed --> rejected
    approved --> compiled
    compiled --> deployed
    rejected --> [*]
    deployed --> [*]

Governance-Ledger produces upstream governance objects. The canonical CRI-CORE compiler remains the authority for compiled contract semantics.

Generated policy artifacts use the canonical CRI-CORE compiler ingestion schema. Ledger does not maintain a separate runtime governance dialect or fallback compiler mode.

Supported v0.1 Primitives

Role requirement:

Only managers may approve transfers.

Structured output:

{
  "authority": {
    "required_roles": ["manager"]
  }
}

Separation of duties:

Proposer and approver must be separate.

Structured output:

{
  "authority": {
    "separation_of_duties": true
  }
}

Transfer threshold:

Transfers above $1M require manager approval.

Structured output:

{
  "approvals": {
    "thresholds": [
      {
        "field": "amount",
        "operator": ">",
        "value": 1000000,
        "requires_role": "manager"
      }
    ]
  }
}

Review Artifacts

Review artifacts explain what was detected and where it came from:

{
  "review_id": "review-001",
  "created_at": "2026-05-07T20:14:00Z",
  "source_document": "finance_policy.txt",
  "review_status": "pending",
  "detected_constraints": [
    {
      "type": "required_role",
      "value": "manager",
      "source_text": "require manager approval"
    }
  ],
  "warnings": []
}

Why Unsupported Governance Becomes Warnings

Unsupported governance language must not silently disappear, and it must not be guessed into executable structure.

For example:

Transfers require reasonable approval timing.

This becomes:

{
  "warnings": [
    {
      "type": "unsupported_constraint",
      "text": "reasonable approval timing"
    }
  ]
}

That preserves auditability. A human reviewer can decide whether to rewrite, approve, reject, or extend the deterministic extraction rules.

Basic Usage

from governance_ledger import (
    attach_compiled_contract,
    attach_deployment,
    create_snapshot,
    extract_constraints,
    review_constraints,
    transition_review_status,
)

text = """
Transfers above $1M require manager approval.
Proposer and approver must be separate.
"""

policy = extract_constraints(text)
review = review_constraints(text, source_document="finance_policy.txt")

review = transition_review_status(review, "reviewed", actor="governance-team")
review = transition_review_status(review, "approved", actor="governance-team")

review = attach_compiled_contract(
    review,
    {
        "contract_id": "finance-core",
        "contract_version": "1.0.0",
        "contract_hash": "abc123",
    },
    actor="compiler-service",
)

review = attach_deployment(
    review,
    environment="production",
    runtime="waveframe-guard",
    deployed_by="ops-team",
    enforcement_engine_version="0.12.0",
)

snapshot = create_snapshot(review)

Operational Workflow

Primary repository layout:

policies/     source governance text
generated/    extraction and validation drafts
reviews/      pending, approved, and deployed review artifacts
contracts/    runtime contract artifacts only
snapshots/    deterministic governance snapshots

Draft generation reads policy text from policies/ and writes machine-generated constraints plus pending review artifacts:

governance-ledger run policies/

Draft output:

• generated/<policy>.generated.json
• generated/<policy>.validation.json
• reviews/<policy>.review.json

Draft generation also validates extracted policy JSON against the canonical CRI-CORE compiler ingestion schema. Schema errors are emitted into generated/<policy>.validation.json with severity == "error".

Draft generation does not approve, compile, deploy, publish, or create runtime contracts.

Human approval is explicit:

governance-ledger approve reviews/finance_policy.review.json --actor governance-team

Publishing requires an approved review and generated policy JSON that passes compiler-ingestion schema validation:

governance-ledger publish reviews/finance_policy.review.json

Publish output:

• contracts/<contract-id>-<version>.contract.json
• contracts/<policy>.publication_manifest.json
• contracts/index.json
• reviews/<policy>.deployed.review.json
• snapshots/<snapshot-id>.json

Runtime contracts should only exist in contracts/. They should not be written to generated/, reviews/, or policies/.

Files in contracts/ are immutable publication outputs. Publishing is idempotent when the existing content is identical, but Governance-Ledger refuses to overwrite an existing contract or publication manifest with different content.

Generated validation artifacts include warning severity. CI can block publication workflows with:

governance-ledger check generated

The check fails when any generated validation artifact contains severity == "error".

Published contracts can be listed:

governance-ledger list contracts

Any JSON artifact can be inspected:

governance-ledger show contracts/finance-policy-0.1.0.contract.json

Documentation

• GOVERNANCE_OBJECT_MODEL.md
• LIFECYCLE.md
• PROVENANCE.md
• NON_GOALS.md
• schemas/