forge: ship REAL trained surrogate v1 for szl-ouroboros (model.joblib + receipt + scripts; honest card + provenance)

MODEL_PROVENANCE.json

@@ -3,10 +3,23 @@
   "model": {
     "id": "SZLHOLDINGS/szl-ouroboros",
     "repository_type": "model",
-    "artifact_kind": "kernel-code-and-configuration",
-    "trained_weights_present": false,
-    "stdlib_only": true,
-    "torch_required": false
+    "artifact_kind": "kernel-code-and-configuration + trained surrogate (model.joblib)",
+    "trained_weights_present": true,
+    "stdlib_only": false,
+    "torch_required": false,
+    "surrogate": {
+      "file": "model.joblib",
+      "sha256": "6c4067810eb508dfb61f3cfaf84b6db81cf2f7c78286f02e786205e0b014ac65",
+      "role": "loop-tax regressor (predicts kernel-derived overheadMs) \u2014 kernel remains sole ground truth",
+      "fidelity_MEASURED": {
+        "held_out_MAE_ms": 15.5853,
+        "held_out_R2": 0.9822,
+        "held_out_target_std_ms": 191.079
+      },
+      "receipt": "TRAINING_RECEIPT.json",
+      "reverify": "python scripts/eval.py"
+    },
+    "stdlib_only_note": "kernel package itself stays stdlib-only; the OPTIONAL surrogate needs sklearn+joblib"
   },
   "source_of_record": {
     "state": "VERIFIED_HF_SOURCE_OF_RECORD",
@@ -25,20 +38,22 @@
     "falsifiability": "arithmetic is falsifiable (a wrong split flips the asserts); an unmeasured wall yields overheadMs=None (UNAVAILABLE, not fabricated); a missing latency raises; a budget violation is surfaced"
   },
   "lambda": {
-    "status": "Conjecture 1 (open) — uniqueness unproven",
+    "status": "Conjecture 1 (open) \u2014 uniqueness unproven",
     "touched_by_this_artifact": false
   },
   "claims": {
-    "trained_model": "NOT_CLAIMED",
+    "trained_model": "CLAIMED \u2014 sklearn HistGradientBoostingRegressor, MEASURED, receipted",
     "reproducible_build": "NOT_CLAIMED",
-    "weights_present": "NONE"
+    "weights_present": "model.joblib (sklearn surrogate; kernel stays weightless)"
   },
   "limits": [
-    "modelMs and peakAttemptMs are MEASURED (upstream wall windows); overheadMs, serializationTaxMs and deadHopMs are DERIVED arithmetic on those measurements — never new claims.",
-    "serializationTaxMs is a COUNTERFACTUAL (what a perfectly-parallel loop could save), never a realized saving — Alloy's loop is strictly sequential.",
-    "deadHopMs is an upper bound only — Alloy does not prefetch.",
-    "overheadMs is UNAVAILABLE (None) when the run wall was not measured — never fabricated.",
+    "The trained surrogate APPROXIMATES the kernel's DERIVED overheadMs from trace shape; it does NOT replace the kernel's exact arithmetic, which remains authoritative.",
+    "Runs with an unmeasured wall (overheadMs=None / UNAVAILABLE) are dropped from training \u2014 never fabricated.",
+    "modelMs and peakAttemptMs are MEASURED (upstream wall windows); overheadMs, serializationTaxMs and deadHopMs are DERIVED arithmetic on those measurements \u2014 never new claims.",
+    "serializationTaxMs is a COUNTERFACTUAL (what a perfectly-parallel loop could save), never a realized saving \u2014 Alloy's loop is strictly sequential.",
+    "deadHopMs is an upper bound only \u2014 Alloy does not prefetch.",
+    "overheadMs is UNAVAILABLE (None) when the run wall was not measured \u2014 never fabricated.",
     "No .bin, .safetensors, .pt, .pth, .onnx, or .gguf weight artifact is present.",
-    "Loop-tax accounting does not prove or upgrade Λ, which remains Conjecture 1 (open)."
+    "Loop-tax accounting does not prove or upgrade \u039b, which remains Conjecture 1 (open)."
   ]
-}
+}

README.md

@@ -6,8 +6,12 @@ tags:
 - ouroboros
 - loop-tax
 - provenance
+- sklearn
+- surrogate
+- tabular-regression
 - doi:10.5281/zenodo.19944926
 library_name: kernels
+pipeline_tag: tabular-regression
 license: apache-2.0
 szl-governance:
   verdict: ADVISORY
@@ -27,7 +31,7 @@ szl-governance:
 
 </div>
 
-> **⬛ No `.safetensors`/`.bin`/`.pt`/`.gguf` — governance kernel repo.** Not a trained model, NO weights. Pure-Python, **stdlib-only** offline replay of the live Alloy surface — it reconstructs the a11oy agent-loop trace and its **loop-tax** decomposition from a run's provider-attempt windows. Nothing beyond sums, max and subtraction. **Λ is not touched here and stays Conjecture 1 (open).**
+> **🟩 Kernel + REAL trained surrogate.** The governance kernel (pure-Python, **stdlib-only**) is UNCHANGED and remains the sole ground truth — it reconstructs the a11oy agent-loop trace and its **loop-tax** decomposition from a run's provider-attempt windows (sums, max, subtraction only). Since **surrogate v1** this repo ALSO ships `model.joblib` — a real trained sklearn regressor that predicts the kernel's DERIVED `overheadMs` from trace observables, with **MEASURED** held-out **MAE 15.59 ms** / **R² 0.9822** (target std 191.1 ms). The surrogate never replaces the kernel's exact arithmetic. **Λ is not touched here and stays Conjecture 1 (open).**
 
 > **Kernel Hub migration (verified 2026-07-15):** `get_kernel(...)` resolves the first-class [Kernel Hub repo](https://huggingface.co/kernels/SZLHOLDINGS/szl-ouroboros); `main` and `v1` pin verified revision `756678f0bf096bde25054336c8e1ff78a9eb9172`.
 
@@ -75,6 +79,38 @@ Mirrors the live a11oy loop-tax accounting (`backbone.ts` — `buildLoopTrace`,
 
 Apache-2.0 · © 2026 SZL Holdings · Stephen P. Lutar · ORCID [0009-0001-0110-4173](https://orcid.org/0009-0001-0110-4173).
 
+
+## Trained loop-tax regressor v1 (MEASURED — see `TRAINING_RECEIPT.json`)
+
+A real sklearn `HistGradientBoostingRegressor` trained on **11,841 runs**
+generated as bounded agent loops and **labeled by this kernel itself**: the target is
+`ou.loop_tax(attempts, wall_ms)["overheadMs"]` — the kernel's own DERIVED
+`max(0, wall − modelMs)` (seed 20260721;
+40 runs re-audited by full kernel replay).
+Runs with an **unmeasured wall** (`overheadMs` honestly `None`/UNAVAILABLE) are **dropped,
+never fabricated**. Features are observable trace fields only (per-attempt latencies + ok
+flags + run wall + budget).
+
+| metric | value |
+|---|---|
+| held-out MAE (ms) | **15.5853** |
+| held-out R² | **0.9822** |
+| target std (ms) | 191.0790 |
+
+R² is the **fidelity of the surrogate to the kernel's DERIVED `overheadMs`** — a fast
+approximation of the loop-tax derivation, not a new measurement. The kernel's exact
+arithmetic remains authoritative; `serializationTaxMs` stays a **counterfactual, never a
+realized saving**. Λ untouched = Conjecture 1.
+
+```python
+import joblib
+reg = joblib.load("model.joblib")   # feature spec: TRAINING_RECEIPT.json data.features
+```
+
+Re-verify everything: `python scripts/eval.py` (sha256-checks the shipped model against the
+receipt, regenerates the seeded dataset via the in-repo kernel, retrains, and compares R²
+within ±0.02).
+
 ---
 
 <sub><b>SZL Holdings honesty footer.</b> Λ = Conjecture 1 (advisory, never a theorem). locked-proven = exactly 8 {F1,F4,F7,F11,F12,F18,F19,F22}. Honesty labels: MEASURED / REPORTED / MODELED / HEURISTIC / UNKNOWN / UNAVAILABLE. Trust never 100% (ceiling 0.97). serializationTax is a counterfactual, never a saving. <a href="https://a-11-oy.com">a-11-oy.com</a> · <a href="https://huggingface.co/SZLHOLDINGS">huggingface.co/SZLHOLDINGS</a></sub>

TRAINING_RECEIPT.json

@@ -0,0 +1,65 @@
+{
+  "artifact": "SZLHOLDINGS/szl-ouroboros surrogate v1",
+  "role": "loop-tax regressor (predicts kernel-derived overheadMs from trace observables) \u2014 kernel remains ground truth",
+  "generator": {
+    "script": "scripts/forge.py",
+    "seed": 20260721,
+    "kernel_version": "0.1.0",
+    "kernel_labelled": true,
+    "kernel_replay_audited_runs": 40,
+    "target": "overheadMs",
+    "target_source": "ou.loop_tax(attempts, wall_ms)['overheadMs'] (DERIVED = max(0, wall - modelMs))",
+    "unavailable_policy": "runs with unmeasured wall (overheadMs=None) are DROPPED, never fabricated"
+  },
+  "data": {
+    "rows": 11841,
+    "runs_generated": 14000,
+    "rows_after_dropping_unavailable": 11841,
+    "split": "80/20 random",
+    "features": [
+      "n_attempts",
+      "wall_ms",
+      "sum_latency",
+      "max_latency",
+      "min_latency",
+      "mean_latency",
+      "std_latency",
+      "median_latency",
+      "served_hop_index",
+      "n_failed_before_served",
+      "n_ok",
+      "n_missing_model",
+      "max_budget",
+      "aborted"
+    ],
+    "target_units": "milliseconds",
+    "target_mean_ms": 379.68,
+    "target_std_ms": 188.66,
+    "feature_policy": "observable trace fields only (per-attempt latencies + ok flags + wall + budget); target is the kernel's own DERIVED arithmetic"
+  },
+  "model": {
+    "type": "sklearn.HistGradientBoostingRegressor",
+    "params": {
+      "max_iter": 400,
+      "early_stopping": true,
+      "random_state": 20260721
+    },
+    "file": "model.joblib",
+    "sha256": "6c4067810eb508dfb61f3cfaf84b6db81cf2f7c78286f02e786205e0b014ac65"
+  },
+  "metrics_MEASURED": {
+    "held_out_MAE_ms": 15.5853,
+    "held_out_R2": 0.9822,
+    "held_out_target_std_ms": 191.079,
+    "interpretation": "R2 is fidelity of the surrogate to the kernel's DERIVED overheadMs; the kernel's exact arithmetic remains authoritative"
+  },
+  "environment": {
+    "python": "3.12.12",
+    "sklearn": "1.9.0",
+    "numpy": "2.5.1",
+    "host": "replit 2-vCPU container",
+    "wall_seconds": 1.0
+  },
+  "honesty": "Every number above is MEASURED by this run. The surrogate approximates the kernel's loop-tax derivation from trace shape; it never replaces the kernel's exact arithmetic. serializationTax stays a counterfactual. \u039b untouched = Conjecture 1.",
+  "trained_at_utc": "2026-07-21T02:53:08Z"
+}

model.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6c4067810eb508dfb61f3cfaf84b6db81cf2f7c78286f02e786205e0b014ac65
+size 834152

scripts/eval.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+"""Re-verify the szl-ouroboros surrogate: sha256 the shipped model against
+TRAINING_RECEIPT.json, then deterministically regenerate the seeded dataset via
+scripts/forge.py (kernel resolved from this repo's own build/ dir) and compare
+re-measured R² to the receipt (tolerance 0.02). Run from repo root:
+python scripts/eval.py"""
+import hashlib, json, subprocess, sys, tempfile, os, shutil
+root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+receipt = json.load(open(f"{root}/TRAINING_RECEIPT.json"))
+got = hashlib.sha256(open(f"{root}/model.joblib", "rb").read()).hexdigest()
+want = receipt["model"]["sha256"]
+print(f"model.joblib sha256 {'MATCHES receipt' if got==want else 'MISMATCH — refuse'}: {got[:16]}…")
+if got != want: sys.exit(1)
+with tempfile.TemporaryDirectory() as td:
+    os.makedirs(f"{td}/repo/scripts")
+    os.symlink(f"{root}/build", f"{td}/repo/build")
+    shutil.copy(f"{root}/scripts/forge.py", f"{td}/repo/scripts/forge.py")
+    out = subprocess.run([sys.executable, f"{td}/repo/scripts/forge.py"],
+                         capture_output=True, text=True)
+    print(out.stdout[-500:] if out.returncode == 0 else out.stderr[-500:])
+    if out.returncode: sys.exit(1)
+    re_receipt = json.load(open(f"{td}/repo/scripts/TRAINING_RECEIPT.json"))
+    d = abs(re_receipt["metrics_MEASURED"]["held_out_R2"]
+            - receipt["metrics_MEASURED"]["held_out_R2"])
+    print(f"re-measured R² delta vs receipt: {d:.4f} ({'OK ≤0.02' if d<=0.02 else 'FAIL'})")
+    sys.exit(0 if d <= 0.02 else 1)

scripts/forge.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""Forge a REAL trained surrogate for szl-ouroboros.
+Kernel = ground truth. Surrogate = a loop-tax REGRESSOR: given the observable
+attempt-window trace of a bounded agent loop (per-attempt latencies, ok flags,
+run wall), predict the kernel's DERIVED `overheadMs` loop-tax field. The label
+is computed by the REAL kernel (`loop_tax`), so the target is definitionally the
+kernel's own arithmetic; the regressor's job is to reproduce that derivation from
+trace observables — its skill (MAE / R²) is MEASURED against held-out kernel labels.
+A sample of traces is re-audited by full kernel replay. Seeded, receipted."""
+import json, os, random, sys, time, hashlib, platform
+_here = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if os.path.isdir(os.path.join(_here, "build", "torch-universal")):
+    sys.path.insert(0, os.path.join(_here, "build", "torch-universal"))  # in-repo run
+else:
+    sys.path.insert(0, "/tmp/kernel-probe/szl-ouroboros/build/torch-universal")  # forge-dev run
+import szl_ouroboros as ou
+import numpy as np
+from sklearn.ensemble import HistGradientBoostingRegressor
+from sklearn.model_selection import train_test_split
+from sklearn.metrics import mean_absolute_error, r2_score
+import joblib
+
+SEED = 20260721
+random.seed(SEED); np.random.seed(SEED)
+T0 = time.time()
+
+EXITS = ou.LOOP_EXITS  # ("converged","budgetExhausted","aborted","error")
+EXIT_IX = {e: i for i, e in enumerate(EXITS)}
+
+def make_run(run_id):
+    """Generate one realistic bounded-loop run. wall_ms is modeled as
+    modelMs + a genuine orchestration overhead + noise, so overheadMs is NOT a
+    trivial constant. Returns (attempts, wall_ms, aborted)."""
+    max_budget = random.randint(1, 6)
+    n = random.randint(1, max_budget)
+    aborted = random.random() < 0.08
+    demo = random.random() < 0.06  # demo run: no model call
+    if demo:
+        return [], (None if random.random() < 0.3 else float(random.randint(5, 120))), aborted
+    served_at = None
+    if not aborted and random.random() < 0.85:
+        served_at = random.randrange(n)  # a hop that succeeds
+    attempts = []
+    for i in range(n):
+        lat = float(random.randint(30, 1500))
+        ok = (i == served_at)
+        attempts.append({"provider": random.choice(["sovereign", "own", "fallback"]),
+                         "model": random.choice(["own-metal", "khipu-1.5b", None]),
+                         "ok": ok, "latency_ms": lat,
+                         "node": random.choice(["tower", "laptop", "node-a"])})
+    model_ms = sum(a["latency_ms"] for a in attempts)
+    # genuine orchestration overhead: energy-meter samples + self-verify pass
+    true_overhead = random.uniform(20, 600) + 0.05 * model_ms
+    wall = model_ms + true_overhead + random.gauss(0, 15)
+    wall = max(wall, model_ms)  # sequential loop: wall >= modelMs
+    if random.random() < 0.15:
+        wall = None  # unmeasured wall -> overheadMs UNAVAILABLE (dropped from training)
+    return attempts, (None if wall is None else float(wall)), aborted
+
+def features(attempts, wall_ms, max_budget, aborted):
+    lats = [float(a["latency_ms"]) for a in attempts]
+    n = len(lats)
+    la = np.array(lats) if lats else np.array([0.0])
+    served_ix = next((i for i, a in enumerate(attempts) if a.get("ok")), -1)
+    n_failed_before = served_ix if served_ix >= 0 else n
+    return [
+        float(n),
+        float(wall_ms) if wall_ms is not None else -1.0,
+        float(la.sum()), float(la.max()), float(la.min()), float(la.mean()),
+        float(la.std()), float(np.median(la)),
+        float(served_ix), float(n_failed_before),
+        float(sum(1 for a in attempts if a.get("ok"))),
+        float(sum(1 for a in attempts if a.get("model") is None)),
+        float(max_budget), float(aborted),
+    ]
+
+FEATURE_NAMES = ["n_attempts", "wall_ms", "sum_latency", "max_latency", "min_latency",
+                 "mean_latency", "std_latency", "median_latency", "served_hop_index",
+                 "n_failed_before_served", "n_ok", "n_missing_model", "max_budget", "aborted"]
+
+# ---- generate (target = kernel-derived overheadMs; drop UNAVAILABLE rows) ----
+N_RUNS = 14000
+X, y, audited = [], [], 0
+audit_bank = []
+for rid in range(N_RUNS):
+    attempts, wall_ms, aborted = make_run(rid)
+    max_budget = max(len(attempts), random.randint(len(attempts), len(attempts) + 3)) or 1
+    tax = ou.loop_tax(attempts, wall_ms)     # REAL kernel computation == ground truth
+    overhead = tax["overheadMs"]
+    if overhead is None:                     # wall unmeasured -> honestly UNAVAILABLE
+        continue
+    X.append(features(attempts, wall_ms, max_budget, aborted))
+    y.append(float(overhead))
+    if len(audit_bank) < 40:
+        audit_bank.append((attempts, wall_ms, overhead))
+
+# kernel-replay audit
+for attempts, wall_ms, recorded in audit_bank:
+    replay = ou.loop_tax(attempts, wall_ms)["overheadMs"]
+    assert abs(replay - recorded) <= 1e-9, f"kernel replay disagreement: {replay} != {recorded}"
+    audited += 1
+
+X = np.array(X, dtype=np.float64); y = np.array(y, dtype=np.float64)
+Xtr, Xte, ytr, yte = train_test_split(X, y, test_size=0.2, random_state=SEED)
+reg = HistGradientBoostingRegressor(random_state=SEED, max_iter=400, early_stopping=True)
+reg.fit(Xtr, ytr)
+pred = reg.predict(Xte)
+mae = float(mean_absolute_error(yte, pred))
+r2 = float(r2_score(yte, pred))
+target_std = float(np.std(yte))
+
+out_dir = os.path.dirname(os.path.abspath(__file__))
+joblib.dump(reg, f"{out_dir}/model.joblib")
+model_sha = hashlib.sha256(open(f"{out_dir}/model.joblib", "rb").read()).hexdigest()
+receipt = {
+  "artifact": "SZLHOLDINGS/szl-ouroboros surrogate v1",
+  "role": "loop-tax regressor (predicts kernel-derived overheadMs from trace observables) — kernel remains ground truth",
+  "generator": {"script": "scripts/forge.py", "seed": SEED, "kernel_version": ou.__version__,
+                 "kernel_labelled": True, "kernel_replay_audited_runs": audited,
+                 "target": "overheadMs", "target_source": "ou.loop_tax(attempts, wall_ms)['overheadMs'] (DERIVED = max(0, wall - modelMs))",
+                 "unavailable_policy": "runs with unmeasured wall (overheadMs=None) are DROPPED, never fabricated"},
+  "data": {"rows": int(len(y)), "runs_generated": N_RUNS, "rows_after_dropping_unavailable": int(len(y)),
+            "split": "80/20 random", "features": FEATURE_NAMES,
+            "target_units": "milliseconds", "target_mean_ms": round(float(np.mean(y)), 2),
+            "target_std_ms": round(float(np.std(y)), 2),
+            "feature_policy": "observable trace fields only (per-attempt latencies + ok flags + wall + budget); target is the kernel's own DERIVED arithmetic"},
+  "model": {"type": "sklearn.HistGradientBoostingRegressor",
+             "params": {"max_iter": 400, "early_stopping": True, "random_state": SEED},
+             "file": "model.joblib", "sha256": model_sha},
+  "metrics_MEASURED": {"held_out_MAE_ms": round(mae, 4), "held_out_R2": round(r2, 4),
+                        "held_out_target_std_ms": round(target_std, 4),
+                        "interpretation": "R2 is fidelity of the surrogate to the kernel's DERIVED overheadMs; the kernel's exact arithmetic remains authoritative"},
+  "environment": {"python": platform.python_version(), "sklearn": __import__("sklearn").__version__,
+                   "numpy": np.__version__, "host": "replit 2-vCPU container", "wall_seconds": round(time.time()-T0, 1)},
+  "honesty": "Every number above is MEASURED by this run. The surrogate approximates the kernel's loop-tax derivation from trace shape; it never replaces the kernel's exact arithmetic. serializationTax stays a counterfactual. Λ untouched = Conjecture 1.",
+  "trained_at_utc": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+}
+with open(f"{out_dir}/TRAINING_RECEIPT.json", "w") as f: json.dump(receipt, f, indent=2)
+print(json.dumps(receipt["metrics_MEASURED"], indent=2))
+print(f"rows={len(y)} audited={audited} wall={receipt['environment']['wall_seconds']}s")