UMCP — Universal Measurement Contract Protocol

A contract-first validation framework for reproducible computational workflows.

UMCP validates that computational results conform to mathematical contracts — frozen evaluation rules that pin normalization, thresholds, and return conditions before any evidence is generated. Every run produces a three-valued verdict: CONFORMANT, NONCONFORMANT, or NON_EVALUABLE.

Built on Generative Collapse Dynamics (GCD), a measurement theory derived from a single axiom:

"Collapse is generative; only what returns is real."

Key Features

Installation

# Core (validation engine + kernel computation)
pip install umcp

# With interactive dashboard
pip install umcp[viz]

# With REST API server
pip install umcp[api]

# Everything (dev tools + dashboard + API)
pip install umcp[all]

Requires Python ≥ 3.11. Core dependencies: numpy, scipy, pyyaml, jsonschema.

Optional: C99 orchestration core and C++17 accelerator for 50–80× kernel speedup (builds from source, falls back to NumPy transparently).

Quick Start

Python API

import numpy as np
from umcp import compute_kernel, compute_full, validate

# 1. Compute kernel invariants from a trace vector
kernel = compute_kernel(
    c=np.array([0.95, 0.88, 0.92, 0.85]),   # 4-channel trace (values in [0,1])
    w=np.array([0.25, 0.25, 0.25, 0.25]),    # uniform weights (sum to 1.0)
    tau_R=5.0,                                 # return time
)

print(f"Fidelity (F):    {kernel.F:.4f}")      # What survives collapse
print(f"Drift (ω):       {kernel.omega:.4f}")  # What is lost (ω = 1 − F)
print(f"Entropy (S):     {kernel.S:.4f}")      # Bernoulli field entropy
print(f"Curvature (C):   {kernel.C:.4f}")      # Channel heterogeneity
print(f"Log-integrity:   {kernel.kappa:.4f}")   # ln(geometric mean)
print(f"Integrity (IC):  {kernel.IC:.4f}")      # Multiplicative coherence

# 2. Full computation with regime classification
result = compute_full([0.95, 0.88, 0.92, 0.85])
print(f"Regime: {result.regime}")  # STABLE, WATCH, or COLLAPSE

# 3. Validate a casepack against its contract
result = validate("casepacks/pedagogical/hello_world")
print(f"Status: {result.status}")           # CONFORMANT / NONCONFORMANT / NON_EVALUABLE
print(f"Errors: {result.error_count}")

CLI

# Validate a casepack
umcp validate casepacks/pedagogical/hello_world

# Strict mode (publication-grade)
umcp validate casepacks/pedagogical/hello_world --strict

# Quick kernel computation
umcp-calc -c 0.95,0.88,0.92,0.85

# Launch interactive dashboard (localhost:8501)
umcp-dashboard

# Start REST API server (localhost:8000)
umcp-api

The Kernel — Six Invariants

The kernel K maps any bounded trace vector c ∈ [0,1]ⁿ with weights w to six invariants:

Three structural identities hold by construction:

• F + ω = 1 — Duality identity (exact to machine precision)
• IC ≤ F — Integrity cannot exceed fidelity
• IC = exp(κ) — Log-integrity relation

These reduce 6 outputs to 3 effective degrees of freedom (F, κ, C).

Regime Classification

The kernel maps to three regimes via frozen threshold gates:

23 Scientific Domains

Each domain provides closure modules that map real-world data to trace vectors:

Validation Pipeline

umcp validate <target>
  → Schema validation (JSON Schema Draft 2020-12)
  → Semantic rule checks
  → Kernel identity verification (F + ω = 1, IC ≤ F, IC = exp(κ))
  → Regime classification
  → SHA-256 integrity check
  → Three-valued verdict → ledger append

Optional Dependencies

pip install umcp[viz]            # Streamlit dashboard + Plotly + Pandas
pip install umcp[api]            # FastAPI REST server
pip install umcp[communications] # Dashboard + API combined
pip install umcp[dev]            # pytest, ruff, mypy, pre-commit
pip install umcp[test]           # pytest + coverage
pip install umcp[cpp]            # pybind11 for C/C++ accelerator build
pip install umcp[all]            # Everything

C/C++ Stack (Optional)

The optional three-layer C → C++ → Python architecture provides a stable ABI and 50–80× kernel speedup. Falls back to NumPy transparently if not built.

# C99 orchestration core (standalone — 326 test assertions)
cd src/umcp_c && mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release && make -j$(nproc)
./test_umcp_c              # 166 kernel tests
./test_umcp_orchestration  # 160 orchestration tests

# Integrated C + C++ + pybind11 (760 total assertions)
cd src/umcp_cpp && mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release && make -j$(nproc)

Project Structure

src/umcp/               # Core Python validation engine
├── frozen_contract.py   # Frozen parameters (seam-derived)
├── kernel_optimized.py  # Lemma-based kernel with diagnostics
├── validator.py         # 16-file casepack validator
├── seam_optimized.py    # Seam budget computation
├── cli.py               # Full CLI (umcp validate, list, health, ...)
├── dashboard/           # 46-page Streamlit dashboard
├── fleet/               # Distributed validation (scheduler, workers, queue)
└── ...                  # 20+ modules total

src/umcp_c/             # C99 Orchestration Core (~1,900 lines)
├── include/umcp_c/      # 9 headers (kernel, contract, regime, trace, ledger, pipeline, ...)
├── src/                 # 8 source files
└── tests/               # 326 test assertions (166 kernel + 160 orchestration)

src/umcp_cpp/           # C++17 Accelerator (pybind11)
├── include/umcp/        # kernel, seam, integrity headers
├── bindings/            # Zero-copy NumPy bridge
└── tests/               # 434 Catch2 assertions

closures/                # 23 domain closure modules (245 .py files)
contracts/               # 23 versioned mathematical contracts (YAML)
casepacks/               # 3 self-contained validation packages
schemas/                 # 17 JSON Schema Draft 2020-12 definitions
canon/                   # 22 canonical anchor files

CLI Entry Points

Links

• Repository: github.com/calebpruett927/GENERATIVE-COLLAPSE-DYNAMICS
• Documentation: README (full)
• Kernel Specification: KERNEL_SPECIFICATION.md
• Master Catalogue: CATALOGUE.md — all 620+ formal objects
• Quick Start Tutorial: QUICKSTART_TUTORIAL.md
• Contributing: CONTRIBUTING.md
• Changelog: CHANGELOG.md
• Issues: GitHub Issues
• License: MIT