Metadata-Version: 2.4
Name: governance-ledger
Version: 0.1.1
Summary: Deterministic governance ledger, provenance, and policy translation for CRI-CORE.
Author: Waveframe Labs
License: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cricore-contract-compiler
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

---
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:

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

## Quickstart

Run the full first-pass operator workflow:

```powershell
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

```text
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
```

```mermaid
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
```

```mermaid
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:

```text
Only managers may approve transfers.
```

Structured output:

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

Separation of duties:

```text
Proposer and approver must be separate.
```

Structured output:

```json
{
  "authority": {
    "separation_of_duties": true
  }
}
```

Transfer threshold:

```text
Transfers above $1M require manager approval.
```

Structured output:

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

## Review Artifacts

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

```json
{
  "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:

```text
Transfers require reasonable approval timing.
```

This becomes:

```json
{
  "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

```python
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:

```text
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:

```powershell
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:

```powershell
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:

```powershell
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:

```powershell
governance-ledger check generated
```

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

Published contracts can be listed:

```powershell
governance-ledger list contracts
```

Any JSON artifact can be inspected:

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

## Documentation

- [GOVERNANCE_OBJECT_MODEL.md](GOVERNANCE_OBJECT_MODEL.md)
- [LIFECYCLE.md](LIFECYCLE.md)
- [PROVENANCE.md](PROVENANCE.md)
- [NON_GOALS.md](NON_GOALS.md)
- [schemas/](schemas/)
