Metadata-Version: 2.4
Name: cricore-contract-compiler
Version: 0.3.0
Summary: Deterministic compiler for governance policies into CRI-CORE contract artifacts.
Author-email: Waveframe Labs <swright@waveframelabs.org>
License: Apache-2.0
Project-URL: Homepage, https://waveframelabs.org
Project-URL: Source, https://github.com/Waveframe-Labs/cricore-contract-compiler
Project-URL: Issues, https://github.com/Waveframe-Labs/cricore-contract-compiler/issues
Keywords: governance,policy compiler,ai governance,compliance,contracts
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jsonschema>=4
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: jsonschema>=4; extra == "dev"
Dynamic: license-file

---
title: "CRI-CORE Contract Compiler - Repository Overview"
filetype: "documentation"
type: "overview"
domain: "governance-tooling"
version: "0.3.0"
doi: "TBD-0.3.0"
status: "Stable (Protocol-Aligned)"
created: "2026-03-11"
updated: "2026-05-03"

author:
  name: "Waveframe Labs"
  email: "swright@waveframelabs.org"

maintainer:
  name: "Waveframe Labs"
  url: "https://waveframelabs.org"

license: "Apache-2.0"

ai_assisted: "partial"
---

# CRI-CORE Contract Compiler

The CRI-CORE Contract Compiler is a deterministic compiler for governance
policies into CRI-CORE contract artifacts.

It bridges governance design and runtime enforcement by converting a
human-authored JSON policy into a stable, machine-readable compiled contract.
The compiled contract is a required input to CRI-CORE and defines the
governance constraints evaluated at the execution boundary.

The compiler does not execute governance logic, make runtime decisions, or
enforce policy. Its role is limited to producing reproducible contract
artifacts with a stable structure and deterministic hash.

## Installation

Install from PyPI:

```bash
pip install cricore-contract-compiler
```

Requires Python 3.9 or later.

## CLI Usage

Compile a governance policy into a compiled contract artifact:

```bash
cricore-compile-policy policy.json compiled_contract.json
```

The output is a deterministic JSON artifact that includes compiler metadata,
compiled governance requirements, invariants, and a contract hash.

## Python Usage

The compiler can also be used programmatically:

```python
from compiler.compile_policy import compile_policy

policy = {
    "contract_id": "finance-policy",
    "contract_version": "0.3.0",
    "authority": {
        "required_roles": ["proposer", "reviewer"]
    },
    "approvals": {
        "thresholds": [
            {
                "field": "amount",
                "operator": ">",
                "value": 1000,
                "requires_role": "approver"
            }
        ]
    },
    "artifacts": {
        "required": ["proposal", "approval"]
    },
    "stages": {
        "allowed_transitions": [
            {"from": "proposed", "to": "approved"}
        ]
    },
    "constraints": [
        {
            "type": "separation_of_duties",
            "roles": ["proposer", "reviewer"]
        }
    ]
}

compiled_contract = compile_policy(policy)
```

## Policy Input

Policies are JSON objects with a required contract identity:

```json
{
  "contract_id": "finance-policy",
  "contract_version": "0.3.0"
}
```

The compiler currently recognizes these optional sections:

- `authority.required_roles`: list of role names required by the contract.
- `approvals.thresholds`: list of threshold-based approval requirements.
- `artifacts.required`: list of required governance artifact names.
- `stages.allowed_transitions`: list of allowed lifecycle transition objects.
- `constraints`: list of explicit structural constraints.

`contract_version` must follow semantic version format: `X.Y.Z`.

## Compiled Output

The compiled contract always includes these top-level sections:

```json
{
  "contract_id": "finance-policy",
  "contract_version": "0.3.0",
  "authority_requirements": {},
  "approval_requirements": {},
  "artifact_requirements": {},
  "stage_requirements": {},
  "invariants": {},
  "contract_hash": "..."
}
```

The required core identity fields of every compiled contract are:

- `contract_id`
- `contract_version`
- `contract_hash`

These are the only identity fields emitted by the compiler. The compiler does
not emit aliases such as `id` or `version`.

The compiler maps policy fields into compiled contract fields as follows:

- `policy.authority.required_roles` becomes `authority_requirements.required_roles`.
- `policy.approvals.thresholds` becomes `approval_requirements.thresholds`.
- `policy.artifacts.required` becomes `artifact_requirements.required_artifacts`.
- `policy.stages.allowed_transitions` becomes `stage_requirements.allowed_transitions`.
- `constraints[type="separation_of_duties"]` becomes `invariants.separation_of_duties`.

Empty compiled sections remain present as empty objects to keep the contract
shape stable for downstream validation and hashing.

## Contract Identity Guarantee

The compiler produces a deterministic contract identity composed of:

- `contract_id`
- `contract_version`
- `contract_hash`

The `contract_hash` is computed from the canonical compiled contract structure
using sorted JSON serialization.

For identical policy inputs, the compiler guarantees identical contract hashes.

This identity is used by downstream systems (e.g., CRI-CORE) to verify that a
proposal references the exact contract used for evaluation. Mismatches result
in enforcement failure.

## Contract Pass-Through Requirement

Compiled contracts must be passed through downstream systems without
modification.

In particular:

- Contract identity fields (`contract_id`, `contract_version`, `contract_hash`)
  must not be altered.
- Downstream components must not recompute or overwrite the contract hash.

CRI-CORE enforces this at evaluation time. Any mismatch between a proposal's
declared contract hash and the compiled contract hash will result in a blocked
decision.

## Determinism

Compiled contracts are hashed with SHA-256 after canonicalizing the compiled
structure using sorted JSON keys.

This ensures:

- identical policy inputs produce identical compiled outputs
- identical compiled outputs produce identical contract hashes

This determinism is required for reproducible enforcement and contract identity
verification in CRI-CORE.

Written artifacts also include `_compiler` metadata:

```json
{
  "_compiler": {
    "tool": "cricore-contract-compiler",
    "version": "0.2.0",
    "contract_hash": "..."
  }
}
```

## Validation

The compiler performs minimal compile-time validation for:

- Policy root type.
- Required `contract_id`.
- Required semantic `contract_version`.
- `authority.required_roles` as a list of strings.
- `approvals.thresholds` as a list of threshold objects.
- `artifacts.required` as a list of strings.
- `stages.allowed_transitions` as a list of transition objects.
- Separation-of-duties constraints with at least two roles.

The JSON schema in `schema/policy.schema.json` defines the supported policy
surface. Runtime enforcement remains outside this package.

## Position in the Governance Pipeline

```text
Governance Policy
        |
Contract Compiler
        |
Compiled Contract
        |
Proposal Normalizer
        |
CRI-CORE Kernel
        |
Commit Decision
```

The compiler sits upstream of CRI-CORE runtime enforcement. It produces the
structural contract artifact that downstream systems can evaluate.

## Role in the Execution Protocol

The compiler is responsible for defining governance constraints in a
deterministic, machine-readable form.

Within the CRI-CORE execution model:

- The compiler defines contract identity and constraints
- The proposal normalizer constructs canonical proposals referencing the contract
- CRI-CORE evaluates whether the proposed action is admissible

The compiler does not participate in runtime evaluation.
It defines the contract that runtime enforcement depends on.

## Non-Responsibilities

The compiler does not:

- Execute governance validation.
- Interpret policy semantics beyond structural compilation.
- Perform runtime decision logic.
- Enforce governance rules.
- Modify or interpret proposal data at runtime.

All runtime enforcement is handled by CRI-CORE or other downstream systems.

## Forward Compatibility

Compiled contracts may include additional sections beyond those currently
enforced by CRI-CORE (e.g., approval requirements, artifact requirements,
stage constraints, invariants).

These fields are preserved for forward compatibility and may be enforced by
future versions of the execution pipeline.

## Project Status

Version `0.3.0` aligns the compiler with the CRI-CORE structured execution model,
ensuring deterministic contract identity, stable output structure, and compatibility
with downstream proposal normalization and enforcement.

## License

Apache-2.0

Copyright 2026 Waveframe Labs.
