feat: MGTP minimal deterministic decision artefact demo

.github/workflows/ci.yml

@@ -27,3 +27,7 @@ jobs:
       - name: Run tests
         run: |
           pytest -q
+
+      - name: Run decision artefact demo (check mode)
+        run: |
+          python examples/minimal_decision_demo.py

.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+*.egg-info/
+dist/
+build/

README.md

@@ -110,6 +110,46 @@ Deterministic, hash-bound commit authority gate — stdlib-only, no network, no
 - **CI:** [`commit_gate_ci.yml`](https://github.com/LalaSkye/constraint-workshop/actions/workflows/commit_gate_ci.yml) (Python 3.10/3.11/3.12 matrix)
 - **Proof:** Determinism + drift-fail validated across Python 3.10/3.11/3.12.
 
+## Deterministic Decision Artefact Demo
+
+Proves: same inputs → same bytes → same hash → replay works.
+
+### Input parameters
+
+| Field | Value |
+|-------|-------|
+| `actor_id` | `demo-actor` |
+| `action_class` | `FILE` |
+| `context.description` | `minimal demo commit` |
+| `authority_scope.project` | `demo-project` |
+| `invariant_hash` | `0000…0000` (64 zeros) |
+| Ruleset | allowlist: `demo-actor / FILE / demo-project` |
+
+### Output artefact
+
+```
+verdict        : ALLOW
+decision_hash  : fab8740c920489154038063620e1453460e1ea1549d0cb1f0cb2dca0ce860360
+canonical_bytes (base64, first 64 chars):
+eyJhcnRlZmFjdF92ZXJzaW9uIjoiMC4xIiwiZGVjaXNpb25faGFzaCI6ImZhYj…
+```
+
+Full base64 stored in [`tests/fixtures/golden_canonical_bytes.b64`](tests/fixtures/golden_canonical_bytes.b64).
+
+### Reproduce
+
+```bash
+python examples/minimal_decision_demo.py
+```
+
+### Replay test
+
+```bash
+pytest tests/test_replay_decision.py -v
+```
+
+---
+
 ## Scope boundaries
 
 `/prometheus` is an **observability-only island**. It must not be imported by any execution path, gate, or pipeline code. It observes and reports; it cannot allow, hold, deny, or silence anything.

examples/minimal_decision_demo.py

@@ -0,0 +1,67 @@
+"""Minimal MGTP decision artefact demonstration.
+
+Proves:
+  1) Deterministic canonicalisation — same inputs produce identical bytes.
+  2) Stable decision_hash       — sha256 of canonical request+verdict+reasons.
+  3) Replayable reconstruction  — stored bytes can be reloaded and re-verified.
+
+No randomness.  Fixed inputs.  Fixed timestamp (excluded from hash).
+Run with: python examples/minimal_decision_demo.py
+"""
+
+import base64
+import sys
+from pathlib import Path
+
+# Resolve commit_gate package from repository layout
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "commit_gate" / "src"))
+
+from commit_gate.canonicalise import canonicalise
+from commit_gate.engine import evaluate
+
+# ---------------------------------------------------------------------------
+# Fixed, deterministic inputs (no randomness, no live timestamps)
+# ---------------------------------------------------------------------------
+
+REQUEST = {
+    "actor_id": "demo-actor",
+    "action_class": "FILE",
+    "context": {"description": "minimal demo commit"},
+    "authority_scope": {"project": "demo-project"},
+    "invariant_hash": "0000000000000000000000000000000000000000000000000000000000000000",
+}
+
+RULESET = {
+    "allowlist": [
+        {
+            "actor_id": "demo-actor",
+            "action_class": "FILE",
+            "scope_match": {"project": "demo-project"},
+        }
+    ],
+    "denylist": [],
+    "escalation": [],
+}
+
+# ---------------------------------------------------------------------------
+# Evaluate and serialise
+# ---------------------------------------------------------------------------
+
+result = evaluate(REQUEST, RULESET)
+canonical_bytes = canonicalise(result)
+canonical_b64 = base64.b64encode(canonical_bytes).decode("ascii")
+
+# ---------------------------------------------------------------------------
+# Output — regulator-readable
+# ---------------------------------------------------------------------------
+
+print("=== MGTP Minimal Decision Artefact Demo ===")
+print()
+print(f"verdict        : {result['verdict']}")
+print(f"reasons        : {result['reasons']}")
+print(f"artefact_version: {result['artefact_version']}")
+print(f"request_hash   : {result['request_hash']}")
+print(f"decision_hash  : {result['decision_hash']}")
+print()
+print(f"canonical_bytes (base64):")
+print(canonical_b64)

tests/fixtures/golden_canonical_bytes.b64

@@ -0,0 +1 @@
+eyJhcnRlZmFjdF92ZXJzaW9uIjoiMC4xIiwiZGVjaXNpb25faGFzaCI6ImZhYjg3NDBjOTIwNDg5MTU0MDM4MDYzNjIwZTE0NTM0NjBlMWVhMTU0OWQwY2IxZjBjYjJkY2EwY2U4NjAzNjAiLCJyZWFzb25zIjpbImFsbG93bGlzdF9tYXRjaCJdLCJyZXF1ZXN0X2hhc2giOiJiYTEzN2RkNjM2YjNiNzZiZGI2YmRlZmQzNjc0YjQwMTkxMDY1NGU3YmY3MWFiNDEwNjYwMDg3NTU2ZWE0MmUwIiwidmVyZGljdCI6IkFMTE9XIn0=

tests/test_replay_decision.py

@@ -0,0 +1,72 @@
+"""Replay test: proves stored golden canonical bytes are byte-identical on re-evaluation.
+
+T-REPLAY-1: canonical_bytes from fixed inputs == stored golden bytes.
+T-REPLAY-2: decision_hash derived from re-evaluation == hash in golden bytes.
+
+Fails if any single byte differs.
+"""
+
+import base64
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "commit_gate" / "src"))
+
+from commit_gate.canonicalise import canonicalise
+from commit_gate.engine import evaluate
+
+FIXTURES_DIR = Path(__file__).resolve().parent / "fixtures"
+
+# Fixed inputs — must exactly match examples/minimal_decision_demo.py
+REQUEST = {
+    "actor_id": "demo-actor",
+    "action_class": "FILE",
+    "context": {"description": "minimal demo commit"},
+    "authority_scope": {"project": "demo-project"},
+    "invariant_hash": "0000000000000000000000000000000000000000000000000000000000000000",
+}
+
+RULESET = {
+    "allowlist": [
+        {
+            "actor_id": "demo-actor",
+            "action_class": "FILE",
+            "scope_match": {"project": "demo-project"},
+        }
+    ],
+    "denylist": [],
+    "escalation": [],
+}
+
+
+def _load_golden_bytes():
+    b64_text = (FIXTURES_DIR / "golden_canonical_bytes.b64").read_text().strip()
+    return base64.b64decode(b64_text)
+
+
+def test_t_replay_1_canonical_bytes_identical():
+    """T-REPLAY-1: Re-evaluating fixed inputs produces byte-identical canonical bytes."""
+    golden = _load_golden_bytes()
+    result = evaluate(REQUEST, RULESET)
+    actual = canonicalise(result)
+    assert actual == golden, (
+        f"Canonical bytes differ from golden fixture.\n"
+        f"Expected: {golden!r}\n"
+        f"Got:      {actual!r}"
+    )
+
+
+def test_t_replay_2_decision_hash_stable():
+    """T-REPLAY-2: decision_hash in re-evaluated result matches hash in golden bytes."""
+    import json
+
+    golden = _load_golden_bytes()
+    golden_dict = json.loads(golden.decode("utf-8"))
+    golden_hash = golden_dict["decision_hash"]
+
+    result = evaluate(REQUEST, RULESET)
+    assert result["decision_hash"] == golden_hash, (
+        f"decision_hash mismatch.\n"
+        f"Expected: {golden_hash}\n"
+        f"Got:      {result['decision_hash']}"
+    )