szl 0.1.0__tar.gz

szl-0.1.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: szl
+Version: 0.1.0
+Summary: The receipts layer for governed AI: khipu signing, the Kamachikuna constitution, provenance badges, and the two-axis Truth Router.
+Author-email: SZL Holdings <stephen@szlholdings.com>
+License: Apache-2.0
+Project-URL: Homepage, https://szlholdings.com/
+Project-URL: Source, https://github.com/szl-holdings/szl-gpu-bridge
+Project-URL: Sponsors, https://szlholdings.com/sponsors.html
+Keywords: ai,governance,provenance,receipts,honesty,khipu,kamachikuna
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# szl — the receipts layer for governed AI
+
+```python
+import sys; sys.path.insert(0, ".")  # until published: pip install szl
+from szl import khipu, kamachikuna, provenance, router
+
+# 1. Every claim carries a receipt (Law 7)
+r = khipu.mint({"claim": "training completed", "steps": 2000}, secret="…")
+assert khipu.check(r, secret="…")            # integrity + origin
+r2 = khipu.mint({"claim": "eval done"}, secret="…", prev_body_sha256=r["body_sha256"])
+assert khipu.check_chain([r, r2], "…", expected_head=r2["body_sha256"])
+
+# 2. Fail closed (Law 6)
+assert kamachikuna.gate("deploy", verified=False)[1] == "BLOCKED"
+
+# 3. Provenance badge — the Korea/Naver bar, machine-checked
+c = provenance.ProvenanceClaim(model_id="m", source_sha="…", training_receipt=r,
+                                datasets={"train": "sha256…"})
+badge = c.badge(secret="…")   # state: MEASURED | CARD_ONLY | UNTRAINED | UNAVAILABLE
+
+# 4. Two-axis Truth Router — honest cheapest, joules reported separately
+pick = router.route("honesty-critical", models)  # None if no honest model: fail closed
+```
+
+## Modules
+- **khipu** — signed, hash-chained receipts. Full-length HMAC-SHA256 signatures (never truncated — that was the v1 auditor bug). Tamper, reorder, and truncation detection (truncation via `expected_head`).
+- **kamachikuna** — the constitution: 10 laws, 5 Prime Principles, 5 Lean-proven invariants, 3 amendments, and Law 6 as a callable gate.
+- **provenance** — honest states only: UNTRAINED · CARD_ONLY · MEASURED · UNAVAILABLE · NOT_CLAIMED. Verification proves integrity and origin, never accuracy or performance.
+- **router** — two-axis honesty routing: price axis decides, joules reported separately (never summed with dollars — different units), UNMEASURED energy never counts as zero, honesty-critical tasks fail closed.
+
+## The freshness rule
+> "A line older than seven days is a claim, not a fact." — Vidal-Gadea Lab roadmap, Nov 2026
+
+`khipu.check_chain(..., max_age_days=7)` fails a chain whose newest receipt is
+older than the window. A stale record that still verifies is worse than no
+record, because it is believed — their lab's cached tracker sat 57 days untouched
+and was read by a program with no error and no warning.
+
+## Design debts deliberately not hidden
+- Chain prefixes are internally valid; completeness requires `expected_head` (tamper-evidence ≠ completeness).
+- An unmeasured quantity is None/UNKNOWN everywhere — never zero.
+- Freshness is a separate axis from integrity: a chain can be both valid and stale.
+
+Tests: `python3 sdk/tests/test_szl_sdk.py` — 11/11 offline, no network, no GPU.
+
+Apache-2.0. Copyright 2026 SZL Holdings · Stephen P. Lutar Jr.

szl-0.1.0/README.md

@@ -0,0 +1,46 @@
+# szl — the receipts layer for governed AI
+
+```python
+import sys; sys.path.insert(0, ".")  # until published: pip install szl
+from szl import khipu, kamachikuna, provenance, router
+
+# 1. Every claim carries a receipt (Law 7)
+r = khipu.mint({"claim": "training completed", "steps": 2000}, secret="…")
+assert khipu.check(r, secret="…")            # integrity + origin
+r2 = khipu.mint({"claim": "eval done"}, secret="…", prev_body_sha256=r["body_sha256"])
+assert khipu.check_chain([r, r2], "…", expected_head=r2["body_sha256"])
+
+# 2. Fail closed (Law 6)
+assert kamachikuna.gate("deploy", verified=False)[1] == "BLOCKED"
+
+# 3. Provenance badge — the Korea/Naver bar, machine-checked
+c = provenance.ProvenanceClaim(model_id="m", source_sha="…", training_receipt=r,
+                                datasets={"train": "sha256…"})
+badge = c.badge(secret="…")   # state: MEASURED | CARD_ONLY | UNTRAINED | UNAVAILABLE
+
+# 4. Two-axis Truth Router — honest cheapest, joules reported separately
+pick = router.route("honesty-critical", models)  # None if no honest model: fail closed
+```
+
+## Modules
+- **khipu** — signed, hash-chained receipts. Full-length HMAC-SHA256 signatures (never truncated — that was the v1 auditor bug). Tamper, reorder, and truncation detection (truncation via `expected_head`).
+- **kamachikuna** — the constitution: 10 laws, 5 Prime Principles, 5 Lean-proven invariants, 3 amendments, and Law 6 as a callable gate.
+- **provenance** — honest states only: UNTRAINED · CARD_ONLY · MEASURED · UNAVAILABLE · NOT_CLAIMED. Verification proves integrity and origin, never accuracy or performance.
+- **router** — two-axis honesty routing: price axis decides, joules reported separately (never summed with dollars — different units), UNMEASURED energy never counts as zero, honesty-critical tasks fail closed.
+
+## The freshness rule
+> "A line older than seven days is a claim, not a fact." — Vidal-Gadea Lab roadmap, Nov 2026
+
+`khipu.check_chain(..., max_age_days=7)` fails a chain whose newest receipt is
+older than the window. A stale record that still verifies is worse than no
+record, because it is believed — their lab's cached tracker sat 57 days untouched
+and was read by a program with no error and no warning.
+
+## Design debts deliberately not hidden
+- Chain prefixes are internally valid; completeness requires `expected_head` (tamper-evidence ≠ completeness).
+- An unmeasured quantity is None/UNKNOWN everywhere — never zero.
+- Freshness is a separate axis from integrity: a chain can be both valid and stale.
+
+Tests: `python3 sdk/tests/test_szl_sdk.py` — 11/11 offline, no network, no GPU.
+
+Apache-2.0. Copyright 2026 SZL Holdings · Stephen P. Lutar Jr.

szl-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "szl"
+version = "0.1.0"
+description = "The receipts layer for governed AI: khipu signing, the Kamachikuna constitution, provenance badges, and the two-axis Truth Router."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "SZL Holdings", email = "stephen@szlholdings.com" }]
+keywords = ["ai", "governance", "provenance", "receipts", "honesty", "khipu", "kamachikuna"]
+
+[project.urls]
+Homepage = "https://szlholdings.com/"
+Source = "https://github.com/szl-holdings/szl-gpu-bridge"
+Sponsors = "https://szlholdings.com/sponsors.html"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["szl*"]

szl-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

szl-0.1.0/szl/__init__.py

@@ -0,0 +1,11 @@
+"""szl — the receipts layer for governed AI, as an installable SDK.
+
+Khipu signing, the Kamachikuna constitution constants, provenance badges,
+and the two-axis Truth Router client. Every claim this package helps you
+make carries a receipt; verification proves integrity and origin, never
+accuracy or performance.
+
+Canonical source: szl-holdings/szl-gpu-bridge (GitHub is canonical).
+"""
+
+__version__ = "0.1.0"

szl-0.1.0/szl/kamachikuna.py

@@ -0,0 +1,47 @@
+"""kamachikuna — the constitution as machine-usable constants.
+
+10 Laws, 5 Prime Principles, EU AI Act-aligned amendments. These are the
+gates every SZL model and service is trained on and checked against.
+Doctrine v11. Λ = Conjecture 1 (uniqueness is a conjecture, not a theorem).
+"""
+
+PRIME_PRINCIPLES = {
+    1: "HARMLESSNESS — never hurt a human, above all laws",
+    2: "TRUTH — never deceive a human",
+    3: "AYNI — every taking gives back",
+    4: "THE SEVENTH GENERATION — weigh the unborn",
+    5: "SUMAK KAWSAY — harmony with community and nature",
+}
+
+LAWS = {
+    1: "Never hurt a human",
+    2: "Never deceive a human",
+    3: "Ayni: every taking gives back",
+    4: "The seventh generation: weigh the unborn",
+    5: "Tamper-evident: every state change leaves a verifiable trace",
+    6: "Fail closed: when the gate cannot verify, the action does not happen",
+    7: "Every claim carries a receipt; no receipt = UNKNOWN, never a claim",
+    8: "Abstain when you cannot prove; fabrication is perjury",
+    9: "No silent failure: errors surface or the system goes to safe state",
+    10: "The loop audits itself: the estate consumes its own receipts",
+}
+
+# Machine-checked invariant theorems (Lean 4, zero errors, zero sorries).
+LEAN_PROVEN = [
+    "Kamachi.law1_fail_closed",
+    "law4_no_bound_raising",
+    "law5_tamper_evident",
+    "law7_irreversible_needs_human",
+    "law9_no_silent_failure",
+]
+
+AMENDMENTS = {
+    1: "EU AI Act Article 11: synthetic content marking",
+    2: "Prime Principle: never hurt a human",
+    3: "Five Prime Principles adopted",
+}
+
+
+def gate(action: str, verified: bool) -> tuple[str, str]:
+    """Law 6 as a function. Returns (action, 'ALLOWED'|'BLOCKED')."""
+    return (action, "ALLOWED") if verified else (action, "BLOCKED")

szl-0.1.0/szl/khipu.py

@@ -0,0 +1,120 @@
+"""khipu — signed, hash-chained receipts. Fail closed, tamper-evident.
+
+A receipt is canonical JSON. Its signature is HMAC-SHA256 over the
+canonical body hash, stored FULL length (never truncated). Receipts chain:
+each carries the sha256 of the previous receipt's body, so any reorder,
+edit, or deletion is detectable (Kamachikuna Law 5).
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Any
+
+KIND = "szl.receipt/v1"
+
+
+def canonical(obj: Any) -> str:
+    """Deterministic JSON: sorted keys, no whitespace. The signing basis."""
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"))
+
+
+def sha256_hex(s: str) -> str:
+    return hashlib.sha256(s.encode("utf-8")).hexdigest()
+
+
+def sign(body_sha256: str, secret: str) -> str:
+    """Full-length HMAC signature. Never truncate a signature."""
+    return hmac.new(secret.encode(), body_sha256.encode(), hashlib.sha256).hexdigest()
+
+
+def verify(body_sha256: str, signature: str, secret: str) -> bool:
+    if not isinstance(signature, str) or len(signature) != 64:
+        return False
+    return hmac.compare_digest(sign(body_sha256, secret), signature)
+
+
+def mint(
+    claim: dict[str, Any],
+    secret: str,
+    prev_body_sha256: str | None = None,
+    ts: str | None = None,
+) -> dict[str, Any]:
+    """Mint one signed receipt for a claim. The claim must already be
+    honest: no receipt can make an unverified claim true (Law 7)."""
+    body = {
+        "kind": KIND,
+        "ts": ts or time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "prev_receipt_sha256": prev_body_sha256,
+        "claim": claim,
+    }
+    body_sha256 = sha256_hex(canonical(body))
+    return {**body, "body_sha256": body_sha256, "signature": sign(body_sha256, secret)}
+
+
+def check(receipt: dict[str, Any], secret: str) -> bool:
+    """Verify one receipt's integrity and origin. Proves the receipt is
+    intact and signed by the holder of `secret` — never that the claim
+    inside is accurate. An unsigned or empty receipt NEVER verifies."""
+    if not isinstance(receipt, dict):
+        return False
+    if not receipt.get("ts"):  # missing timestamp = unverifiable
+        return False
+    import datetime
+    try:
+        dt = datetime.datetime.fromisoformat(str(receipt["ts"]).replace("Z", "+00:00"))
+        if dt.tzinfo is None:  # timezone-free = unverifiable
+            return False
+        if dt > datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(minutes=5):
+            return False  # future timestamp = unverifiable
+    except (ValueError, TypeError):
+        return False
+    body = {k: v for k, v in receipt.items() if k not in ("body_sha256", "signature")}
+    if body.get("kind") != KIND:
+        return False
+    expected = sha256_hex(canonical(body))
+    if receipt.get("body_sha256") != expected:
+        return False
+    return verify(expected, receipt.get("signature", ""), secret)
+
+
+def check_chain(
+    receipts: list[dict[str, Any]],
+    secret: str,
+    expected_head: str | None = None,
+    max_age_days: float | None = None,
+) -> bool:
+    """Verify a full chain: every receipt valid, every link intact.
+    A prefix of the chain is internally valid — truncation is only
+    detectable against `expected_head` (the latest known body_sha256).
+    Pass it to prove completeness, not just integrity.
+
+    `max_age_days` implements the freshness rule: a chain whose newest
+    receipt is older than the window is STALE, not green. A stale record
+    that still verifies is worse than no record, because it is believed.
+    (Vidal-Gadea Lab roadmap, Nov 2026: cached values sat untouched 57
+    days and a program read them with no error and no warning.)"""
+    prev: str | None = None
+    newest_ts: str | None = None
+    for r in receipts:
+        if not check(r, secret):
+            return False
+        if r.get("prev_receipt_sha256") != prev:
+            return False
+        prev = r["body_sha256"]
+        newest_ts = r.get("ts") or newest_ts
+    if expected_head is not None and prev != expected_head:
+        return False  # truncated chain
+    if max_age_days is not None and newest_ts is not None:
+        import datetime
+
+        try:
+            dt = datetime.datetime.fromisoformat(str(newest_ts).replace("Z", "+00:00"))
+        except ValueError:
+            return False  # unreadable timestamp: cannot prove freshness
+        age = (datetime.datetime.now(datetime.timezone.utc) - dt).total_seconds()
+        if age > max_age_days * 86400:
+            return False  # stale chain: valid, but no longer current
+    return True

szl-0.1.0/szl/openshell.py

@@ -0,0 +1,152 @@
+"""openshell — the Kamachikuna as NVIDIA OpenShell-compatible policy-as-code.
+
+NVIDIA OpenShell (https://github.com/NVIDIA/OpenShell) governs what an agent
+may TOUCH: filesystem, network, process, with declarative YAML policies,
+kernel-level sandboxes, and an OCSF audit trail. The Kamachikuna governs what
+an agent may CLAIM: honesty, receipts, abstention, fail-closed.
+
+This module compiles the constitution into OpenShell-reviewable artifacts so
+any OpenShell-governed agent can run under the Kamachikuna:
+
+- policy_document(): the 10 laws + 5 prime principles as a declarative,
+  version-controllable policy mapping (law -> enforcement domain -> rule).
+- audit_event(): map a khipu receipt to an OCSF-shaped audit record so
+  Kamachikuna decisions land in the same audit trail as OpenShell decisions.
+- admission_gate(): Law 6/Law 8 as an OpenShell-style middleware check —
+  deny-by-default, receipt-required, fail-closed.
+
+Doctrine v11. Every emitted artifact carries the doctrine version and the
+law text verbatim from szl.kamachikuna — single source of truth, no drift.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import hashlib
+import json
+
+from . import kamachikuna
+
+DOCTRINE_VERSION = "v11"
+
+# Law -> OpenShell policy domain. OpenShell enforces fs/net/process; the
+# Kamachikuna layers claim-governance on top of the same deny-by-default model.
+LAW_DOMAINS = {
+    1: ("harm", "harmless"),          # Prime Principle 1 — above all laws
+    2: ("honesty", "claim"),          # measured honesty, two-axis
+    3: ("ayni", "resource"),          # every taking gives back
+    4: ("seventh-generation", "impact"),
+    5: ("tamper-evidence", "audit"),  # state changes leave verifiable traces
+    6: ("fail-closed", "gate"),
+    7: ("receipts", "audit"),        # no receipt = UNKNOWN, never a claim
+    8: ("abstention", "claim"),
+    9: ("no-silent-failure", "runtime"),
+    10: ("self-audit", "runtime"),
+}
+
+# Actions that are irreversible (Tier 2 of the autonomy ladder) and therefore
+# human-only under Law 7 — the lean-proven irreversibility theorem.
+IRREVERSIBLE_ACTIONS = frozenset({
+    "constitution.amend", "payment.execute", "credential.rotate",
+    "human.dismiss", "deployment.production-delete",
+})
+
+
+def law_rules() -> list[dict]:
+    """Each law as a declarative rule: id, domain, text, enforcement."""
+    rules = []
+    for n, text in kamachikuna.LAWS.items():
+        domain, kind = LAW_DOMAINS[n]
+        rules.append({
+            "id": f"kamachikuna.law{n}",
+            "domain": domain,
+            "kind": kind,
+            "effect": "deny-by-default" if n in (6, 8) else "enforce",
+            "text": text,
+            "lean_proven": any(
+                p.split(".")[-1].startswith(f"law{n}_")
+                for p in kamachikuna.LEAN_PROVEN
+            ),
+        })
+    return rules
+
+
+def policy_document() -> dict:
+    """The constitution as an OpenShell-reviewable policy document.
+
+    Version-controllable, hash-stamped, single-sourced from szl.kamachikuna.
+    """
+    doc = {
+        "apiVersion": "kamachikuna.szl/v1",
+        "kind": "AgentConstitution",
+        "metadata": {
+            "name": "kamachikuna",
+            "doctrine": DOCTRINE_VERSION,
+            "primePrinciples": list(kamachikuna.PRIME_PRINCIPLES.values()),
+            "amendments": list(kamachikuna.AMENDMENTS.values()),
+            "leanProven": list(kamachikuna.LEAN_PROVEN),
+        },
+        "spec": {
+            "default": "deny",  # Law 6 — fail closed
+            "rules": law_rules(),
+            "irreversibleActions": sorted(IRREVERSIBLE_ACTIONS),
+            "irreversiblePolicy": "human-only",  # Law 7, lean-proven
+        },
+    }
+    doc["metadata"]["sha256"] = hashlib.sha256(
+        json.dumps(doc, sort_keys=True, separators=(",", ":")).encode()
+    ).hexdigest()
+    return doc
+
+
+def admission_gate(action: str, verified: bool, *, receipt: dict | None = None,
+                   irreversible: bool | None = None) -> dict:
+    """Law 6 + Law 7 + Law 8 as one OpenShell-style middleware decision.
+
+    Deny-by-default. An ALLOWED decision always carries the governing laws
+    and the receipt hash (Law 7). Irreversible actions are human-only.
+    """
+    _, verdict = kamachikuna.gate(action, verified)
+    irr = action in IRREVERSIBLE_ACTIONS if irreversible is None else irreversible
+    laws = [6]
+    if irr:
+        laws.append(7)
+        verdict = "BLOCKED"  # irreversible needs a human, not a gate
+    if receipt is None:
+        laws.append(7)
+        if verdict == "ALLOWED":
+            verdict = "BLOCKED"  # no receipt = no claim = no allow
+    return {
+        "action": action,
+        "decision": verdict,
+        "laws": laws,
+        "receiptSha256": (
+            receipt.get("sha256") if isinstance(receipt, dict) else None
+        ),
+        "reason": (
+            "irreversible: human-only (Law 7)" if irr and verdict == "BLOCKED"
+            else "unverified: fail closed (Law 6)" if verdict == "BLOCKED"
+            else "verified with receipt"
+        ),
+    }
+
+
+def audit_event(decision: dict) -> dict:
+    """Map a gate decision to an OCSF-shaped audit record.
+
+    OpenShell writes OCSF audit events; this makes Kamachikuna decisions
+    legible in the same trail — one audit plane for touch and claim.
+    """
+    return {
+        "class": "application_activity",
+        "activity": 6,  # authorized / denied per decision
+        "authorized": decision["decision"] == "ALLOWED",
+        "action": decision["action"],
+        "metadata": {
+            "doctrine": DOCTRINE_VERSION,
+            "laws": decision["laws"],
+            "receiptSha256": decision["receiptSha256"],
+            "reason": decision["reason"],
+        },
+        "time": _dt.datetime.now(_dt.timezone.utc).isoformat(),
+    }

szl-0.1.0/szl/provenance.py

@@ -0,0 +1,53 @@
+"""provenance — the Korea/Naver bar as a machine-checkable badge.
+
+A model claims provenance only when the evidence is present and bound.
+States are honest: UNTRAINED, CARD_ONLY, MEASURED, UNAVAILABLE, NOT_CLAIMED.
+Verification proves integrity and origin of the evidence — never accuracy
+or performance of the model.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from . import khipu
+
+BADGE_KIND = "szl.provenance-badge/v1"
+
+STATES = ("UNTRAINED", "CARD_ONLY", "MEASURED", "UNAVAILABLE", "NOT_CLAIMED")
+
+
+@dataclass
+class ProvenanceClaim:
+    """What a model card claims, with the evidence that must back it."""
+    model_id: str
+    source_sha: str | None = None          # canonical GitHub revision trained from
+    training_receipt: dict[str, Any] | None = None  # signed khipu receipt
+    datasets: dict[str, str] = field(default_factory=dict)  # name -> sha256
+
+    def state(self, secret: str | None = None) -> str:
+        if self.training_receipt is None:
+            return "CARD_ONLY" if self.source_sha else "UNTRAINED"
+        # NO SECRET = CANNOT VERIFY = NEVER MEASURED (Law 6: fail closed)
+        if secret is None:
+            return "UNAVAILABLE"
+        if not khipu.check(self.training_receipt, secret):
+            return "UNAVAILABLE"  # unverifiable receipt = UNAVAILABLE, never MEASURED
+        if not self.source_sha or not self.datasets:
+            return "UNAVAILABLE"
+        return "MEASURED"
+
+    def badge(self, secret: str | None = None) -> dict[str, Any]:
+        """Mint the provenance badge. Honest states only, never a guess."""
+        state = self.state(secret)
+        body = {
+            "kind": BADGE_KIND,
+            "model_id": self.model_id,
+            "state": state,
+            "source_sha": self.source_sha,
+            "datasets": self.datasets,
+            "note": "Verification proves integrity and origin, never accuracy or performance.",
+        }
+        if secret is None:
+            return body  # unsigned inspection badge
+        return khipu.mint(body, secret)

szl-0.1.0/szl/router.py

@@ -0,0 +1,63 @@
+"""router — the two-axis Truth Router client.
+
+Axis 1: measured honesty (census abstention + proving-ground badges).
+Axis 2: cost (joules/token where MEASURED, price otherwise — never zero
+for an unmeasured quantity).
+
+Routing rule (Honesty Gate, from the ADAP-Khipu bridge): honesty-critical
+tasks NEVER route to a model whose honesty state is UNAVAILABLE or FAILED,
+even if it is the cheapest or most capable. Fail closed.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+HONESTY_STATES = ("MEASURED", "UNMEASURED", "FAILED")
+
+
+@dataclass
+class Model:
+    model_id: str
+    honesty_state: str          # HONESTY_STATES
+    abstain_rate: float | None  # census: abstentions / total, None if unmeasured
+    prove_badge: str | None     # proving-ground badge or None
+    joules_per_token: float | None  # MEASURED only; never fabricated
+    price_per_mtok: float | None
+
+    def honesty_score(self) -> float | None:
+        """None means UNKNOWN — never collapse to zero."""
+        if self.honesty_state != "MEASURED" or self.abstain_rate is None:
+            return None
+        return self.abstain_rate
+
+    def cost_per_mtok(self) -> float | None:
+        """Price axis only. Joules are a SEPARATE axis — never summed with
+        dollars (units differ); the router reports both, prices on one."""
+        return self.price_per_mtok
+
+    def energy_per_mtok_joules(self) -> float | None:
+        """Energy axis. None = UNAVAILABLE, never zero."""
+        if self.honesty_state != "MEASURED":
+            return None  # an unmeasured model's energy is unknown, not zero
+        return None if self.joules_per_token is None else self.joules_per_token * 1e6
+
+
+def route(task_kind: str, models: list[Model]) -> Model | None:
+    """Pick the honest cheapest on the PRICE axis; report joules separately.
+    Honesty-critical tasks fail closed. Ties break toward lower MEASURED
+    energy; UNMEASURED energy never counts as zero."""
+    eligible = [m for m in models if m.honesty_state == "MEASURED"]
+    if task_kind == "honesty-critical" and not eligible:
+        return None  # fail closed: no honest model, no routing
+    pool = eligible or models
+    priced = [m for m in pool if m.cost_per_mtok() is not None]
+    if not priced:
+        return None
+
+    def sort_key(m: Model):
+        energy = m.energy_per_mtok_joules()
+        # measured energy (even zero) sorts BEFORE unknown: known > unknown
+        # a model that PROVED zero joules is more honest than one that didn't measure
+        return (m.cost_per_mtok(), 1 if energy is None else 0, energy if energy is not None else float("inf"))
+
+    return min(priced, key=sort_key)

szl-0.1.0/szl.egg-info/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: szl
+Version: 0.1.0
+Summary: The receipts layer for governed AI: khipu signing, the Kamachikuna constitution, provenance badges, and the two-axis Truth Router.
+Author-email: SZL Holdings <stephen@szlholdings.com>
+License: Apache-2.0
+Project-URL: Homepage, https://szlholdings.com/
+Project-URL: Source, https://github.com/szl-holdings/szl-gpu-bridge
+Project-URL: Sponsors, https://szlholdings.com/sponsors.html
+Keywords: ai,governance,provenance,receipts,honesty,khipu,kamachikuna
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# szl — the receipts layer for governed AI
+
+```python
+import sys; sys.path.insert(0, ".")  # until published: pip install szl
+from szl import khipu, kamachikuna, provenance, router
+
+# 1. Every claim carries a receipt (Law 7)
+r = khipu.mint({"claim": "training completed", "steps": 2000}, secret="…")
+assert khipu.check(r, secret="…")            # integrity + origin
+r2 = khipu.mint({"claim": "eval done"}, secret="…", prev_body_sha256=r["body_sha256"])
+assert khipu.check_chain([r, r2], "…", expected_head=r2["body_sha256"])
+
+# 2. Fail closed (Law 6)
+assert kamachikuna.gate("deploy", verified=False)[1] == "BLOCKED"
+
+# 3. Provenance badge — the Korea/Naver bar, machine-checked
+c = provenance.ProvenanceClaim(model_id="m", source_sha="…", training_receipt=r,
+                                datasets={"train": "sha256…"})
+badge = c.badge(secret="…")   # state: MEASURED | CARD_ONLY | UNTRAINED | UNAVAILABLE
+
+# 4. Two-axis Truth Router — honest cheapest, joules reported separately
+pick = router.route("honesty-critical", models)  # None if no honest model: fail closed
+```
+
+## Modules
+- **khipu** — signed, hash-chained receipts. Full-length HMAC-SHA256 signatures (never truncated — that was the v1 auditor bug). Tamper, reorder, and truncation detection (truncation via `expected_head`).
+- **kamachikuna** — the constitution: 10 laws, 5 Prime Principles, 5 Lean-proven invariants, 3 amendments, and Law 6 as a callable gate.
+- **provenance** — honest states only: UNTRAINED · CARD_ONLY · MEASURED · UNAVAILABLE · NOT_CLAIMED. Verification proves integrity and origin, never accuracy or performance.
+- **router** — two-axis honesty routing: price axis decides, joules reported separately (never summed with dollars — different units), UNMEASURED energy never counts as zero, honesty-critical tasks fail closed.
+
+## The freshness rule
+> "A line older than seven days is a claim, not a fact." — Vidal-Gadea Lab roadmap, Nov 2026
+
+`khipu.check_chain(..., max_age_days=7)` fails a chain whose newest receipt is
+older than the window. A stale record that still verifies is worse than no
+record, because it is believed — their lab's cached tracker sat 57 days untouched
+and was read by a program with no error and no warning.
+
+## Design debts deliberately not hidden
+- Chain prefixes are internally valid; completeness requires `expected_head` (tamper-evidence ≠ completeness).
+- An unmeasured quantity is None/UNKNOWN everywhere — never zero.
+- Freshness is a separate axis from integrity: a chain can be both valid and stale.
+
+Tests: `python3 sdk/tests/test_szl_sdk.py` — 11/11 offline, no network, no GPU.
+
+Apache-2.0. Copyright 2026 SZL Holdings · Stephen P. Lutar Jr.

szl-0.1.0/szl.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+szl/__init__.py
+szl/kamachikuna.py
+szl/khipu.py
+szl/openshell.py
+szl/provenance.py
+szl/router.py
+szl.egg-info/PKG-INFO
+szl.egg-info/SOURCES.txt
+szl.egg-info/dependency_links.txt
+szl.egg-info/top_level.txt
+tests/test_szl_sdk.py

szl-0.1.0/szl.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

szl-0.1.0/szl.egg-info/top_level.txt

@@ -0,0 +1 @@
+szl

szl-0.1.0/tests/test_szl_sdk.py

@@ -0,0 +1,241 @@
+"""Offline tests for the szl SDK. No network, no GPU."""
+
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from szl import kamachikuna, khipu, provenance, router  # noqa: E402
+
+
+class KhipuTests(unittest.TestCase):
+    def test_mint_and_check(self):
+        r = khipu.mint({"claim": "training completed", "steps": 2000}, secret="s")
+        self.assertTrue(khipu.check(r, secret="s"))
+        self.assertFalse(khipu.check(r, secret="wrong"))
+        self.assertEqual(len(r["signature"]), 64)
+
+    def test_tamper_detection(self):
+        r = khipu.mint({"claim": "x"}, secret="s")
+        r2 = dict(r)
+        r2["claim"] = {"claim": "y"}  # tamper
+        self.assertFalse(khipu.check(r2, secret="s"))
+
+    def test_chain(self):
+        secret = "s"
+        r1 = khipu.mint({"n": 1}, secret)
+        r2 = khipu.mint({"n": 2}, secret, prev_body_sha256=r1["body_sha256"])
+        r3 = khipu.mint({"n": 3}, secret, prev_body_sha256=r2["body_sha256"])
+        self.assertTrue(khipu.check_chain([r1, r2, r3], secret))
+        self.assertFalse(khipu.check_chain([r1, r3, r2], secret))  # reorder
+        # a prefix is internally valid; truncation needs the expected head
+        self.assertTrue(khipu.check_chain([r1, r2], secret))  # prefix: valid
+        self.assertFalse(
+            khipu.check_chain([r1, r2], secret, expected_head=r3["body_sha256"])
+        )  # truncated vs known head
+        self.assertTrue(
+            khipu.check_chain([r1, r2, r3], secret, expected_head=r3["body_sha256"])
+        )
+
+    def test_truncated_signature_rejected(self):
+        r = khipu.mint({"claim": "x"}, secret="s")
+        r["signature"] = r["signature"][:48]  # the v1 auditor truncation bug
+        self.assertFalse(khipu.check(r, secret="s"))
+
+
+class FreshnessTests(unittest.TestCase):
+    def test_stale_chain_is_not_green(self):
+        """A valid-but-old chain must fail a freshness check. Cached values
+        sat 57 days untouched in the Vidal-Gadea tracker and were read with
+        no error and no warning."""
+        import datetime
+
+        secret = "s"
+        old_ts = (datetime.datetime.now(datetime.timezone.utc)
+                  - datetime.timedelta(days=30)).strftime("%Y-%m-%dT%H:%M:%SZ")
+        r1 = khipu.mint({"n": 1}, secret, ts=old_ts)
+        self.assertTrue(khipu.check_chain([r1], secret))  # integrity: valid
+        self.assertFalse(khipu.check_chain([r1], secret, max_age_days=7))  # stale
+        fresh = khipu.mint({"n": 2}, secret, prev_body_sha256=r1["body_sha256"])
+        self.assertTrue(khipu.check_chain([r1, fresh], secret, max_age_days=7))
+
+    def test_unreadable_timestamp_fails_freshness(self):
+        r = khipu.mint({"n": 1}, "s")
+        r["ts"] = "not-a-date"
+        # integrity check re-hashes the body, so we cannot tamper ts post-mint;
+        # instead verify that a bad ts inside a properly minted receipt fails
+        r2 = khipu.mint({"n": 1}, "s")
+        self.assertTrue(khipu.check_chain([r2], "s"))
+        # mint with a garbage ts and check freshness rejects it
+        r3 = khipu.mint({"n": 1}, "s", ts="garbage")
+        self.assertFalse(khipu.check_chain([r3], "s", max_age_days=7))
+
+
+class KamachikunaTests(unittest.TestCase):
+    def test_constants_complete(self):
+        self.assertEqual(len(kamachikuna.LAWS), 10)
+        self.assertEqual(len(kamachikuna.PRIME_PRINCIPLES), 5)
+        self.assertEqual(len(kamachikuna.LEAN_PROVEN), 5)
+        self.assertEqual(len(kamachikuna.AMENDMENTS), 3)
+
+    def test_fail_closed_gate(self):
+        self.assertEqual(kamachikuna.gate("deploy", verified=True)[1], "ALLOWED")
+        self.assertEqual(kamachikuna.gate("deploy", verified=False)[1], "BLOCKED")
+
+
+class ProvenanceTests(unittest.TestCase):
+    def test_honest_states(self):
+        untrained = provenance.ProvenanceClaim(model_id="m")
+        self.assertEqual(untrained.state(), "UNTRAINED")
+        card_only = provenance.ProvenanceClaim(model_id="m", source_sha="a" * 40)
+        self.assertEqual(card_only.state(), "CARD_ONLY")
+        # measured requires a verifiable receipt + source + datasets
+        secret = "s"
+        receipt = khipu.mint({"kind": "szl.training-receipt/v1"}, secret)
+        measured = provenance.ProvenanceClaim(
+            model_id="m", source_sha="a" * 40, training_receipt=receipt,
+            datasets={"train": "b" * 64},
+        )
+        self.assertEqual(measured.state(secret), "MEASURED")
+        # unverifiable receipt -> UNAVAILABLE, never MEASURED
+        self.assertEqual(measured.state("wrong-secret"), "UNAVAILABLE")
+
+    def test_badge_is_signed(self):
+        secret = "s"
+        receipt = khipu.mint({"kind": "szl.training-receipt/v1"}, secret)
+        c = provenance.ProvenanceClaim(
+            model_id="m", source_sha="a" * 40, training_receipt=receipt,
+            datasets={"train": "b" * 64},
+        )
+        badge = c.badge(secret)
+        self.assertTrue(khipu.check(badge, secret))
+        self.assertEqual(badge["claim"]["state"], "MEASURED")
+        # unsigned inspection must NEVER be MEASURED (Law 6)
+        unsigned = c.badge(secret=None)
+        self.assertEqual(unsigned["state"], "UNAVAILABLE")
+
+
+class RouterTests(unittest.TestCase):
+    def test_honest_cheapest_wins(self):
+        models = [
+            router.Model("cheap-liar", "FAILED", 0.0, None, None, 0.01),
+            router.Model("honest-mid", "MEASURED", 0.9, "PROVE-OR-ABSTAIN-MASTER", 2.0, 1.0),
+            router.Model("honest-expensive", "MEASURED", 0.95, None, 1.0, 5.0),
+        ]
+        pick = router.route("eval", models)
+        self.assertEqual(pick.model_id, "honest-mid")
+
+    def test_honesty_critical_fails_closed(self):
+        models = [router.Model("cheap-liar", "FAILED", 0.0, None, None, 0.01)]
+        self.assertIsNone(router.route("honesty-critical", models))
+        # non-critical tasks may still use unmeasured models
+        self.assertIsNotNone(router.route("bulk", models))
+
+    def test_unmeasured_is_none_not_zero(self):
+        m = router.Model("m", "UNMEASURED", None, None, None, None)
+        self.assertIsNone(m.honesty_score())
+        self.assertIsNone(m.cost_per_mtok())
+
+
+class TightenedSecurityTests(unittest.TestCase):
+    """Codex review findings: empty receipts, missing timestamps, future timestamps."""
+
+    def test_empty_receipt_never_verifies(self):
+        r = {}  # empty receipt — must fail
+        self.assertFalse(khipu.check(r, secret="s"))
+
+    def test_unsigned_receipt_never_measured(self):
+        c = provenance.ProvenanceClaim(model_id="m", source_sha="a" * 40,
+                                        training_receipt={"kind": "szl.training-receipt/v1"},
+                                        datasets={"train": "b" * 64})
+        # no secret = UNAVAILABLE, never MEASURED
+        self.assertEqual(c.state(None), "UNAVAILABLE")
+
+    def test_missing_timestamp_never_verifies(self):
+        r = khipu.mint({"claim": "x"}, secret="s")
+        del r["ts"]  # remove the timestamp
+        self.assertFalse(khipu.check(r, secret="s"))
+
+    def test_future_timestamp_never_verifies(self):
+        import datetime
+        future = (datetime.datetime.now(datetime.timezone.utc)
+                  + datetime.timedelta(days=1)).strftime("%Y-%m-%dT%H:%M:%SZ")
+        r = khipu.mint({"claim": "x"}, secret="s", ts=future)
+        self.assertFalse(khipu.check(r, secret="s"))
+
+    def test_measured_zero_energy_beats_unknown(self):
+        models = [
+            router.Model("unknown-energy", "MEASURED", 0.9, None, None, 1.0),
+            router.Model("measured-zero", "MEASURED", 0.9, None, 0.0, 1.0),
+        ]
+        pick = router.route("eval", models)
+        self.assertEqual(pick.model_id, "measured-zero")  # known zero > unknown
+
+    def test_timezone_free_timestamp_never_verifies(self):
+        r = khipu.mint({"claim": "x"}, secret="s")
+        r["ts"] = "2026-11-10T07:00:00"  # no timezone
+        self.assertFalse(khipu.check(r, secret="s"))
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)
+
+
+class OpenShellPolicyTests(unittest.TestCase):
+    """Kamachikuna as OpenShell-reviewable policy-as-code."""
+
+    def setUp(self):
+        from szl import openshell
+        self.os_ = openshell
+
+    def test_policy_document_is_deterministic_and_hashed(self):
+        d1 = self.os_.policy_document()
+        d2 = self.os_.policy_document()
+        self.assertEqual(d1, d2)  # version-controllable: byte-stable
+        self.assertEqual(d1["spec"]["default"], "deny")  # Law 6
+        self.assertEqual(len(d1["spec"]["rules"]), 10)
+        self.assertTrue(all("sha256" in d1["metadata"] for _ in [1]))
+
+    def test_laws_single_sourced(self):
+        doc = self.os_.policy_document()
+        texts = [r["text"] for r in doc["spec"]["rules"]]
+        from szl import kamachikuna
+        self.assertEqual(sorted(texts), sorted(kamachikuna.LAWS.values()))
+
+    def test_lean_proven_flags_are_true_only_for_proven_laws(self):
+        doc = self.os_.policy_document()
+        proven = [r["id"] for r in doc["spec"]["rules"] if r["lean_proven"]]
+        # laws 1,4,5,7,9 have Lean-proven theorems
+        self.assertEqual(proven, ["kamachikuna.law%d" % n for n in (1, 4, 5, 7, 9)])
+
+    def test_gate_fails_closed(self):
+        d = self.os_.admission_gate("train.launch", verified=False)
+        self.assertEqual(d["decision"], "BLOCKED")
+        self.assertIn(6, d["laws"])
+        self.assertIn("fail closed", d["reason"])
+
+    def test_allow_requires_receipt(self):
+        # verified but no receipt -> Law 7 blocks the claim
+        d = self.os_.admission_gate("train.launch", verified=True, receipt=None)
+        self.assertEqual(d["decision"], "BLOCKED")
+        self.assertIn(7, d["laws"])
+        # with a receipt -> allowed
+        d2 = self.os_.admission_gate("train.launch", verified=True,
+                                     receipt={"sha256": "ab" * 32})
+        self.assertEqual(d2["decision"], "ALLOWED")
+        self.assertEqual(d2["receiptSha256"], "ab" * 32)
+
+    def test_irreversible_actions_are_human_only(self):
+        d = self.os_.admission_gate("payment.execute", verified=True,
+                                    receipt={"sha256": "cd" * 32})
+        self.assertEqual(d["decision"], "BLOCKED")  # Law 7: human-only
+        self.assertIn(7, d["laws"])
+        self.assertIn("human-only", d["reason"])
+
+    def test_audit_event_is_ocsf_shaped(self):
+        d = self.os_.admission_gate("train.launch", verified=False)
+        ev = self.os_.audit_event(d)
+        self.assertEqual(ev["class"], "application_activity")
+        self.assertFalse(ev["authorized"])
+        self.assertEqual(ev["metadata"]["doctrine"], "v11")