its-magic 0.1.2-35 → 0.1.2-37

package/template/scripts/intake_evidence_validate.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""
+Validate intake_evidence JSON bundles (US-0078 / DEC-0060).
+
+Used by PO workflow preflight and CI fixtures.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+_SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+_REPO_ROOT = os.path.normpath(os.path.join(_SCRIPT_DIR, ".."))
+if _SCRIPT_DIR not in sys.path:
+    sys.path.insert(0, _SCRIPT_DIR)
+
+import intake_evidence_lib  # noqa: E402
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description="Validate intake_evidence JSON (US-0078).")
+    p.add_argument("--file", help="Path to JSON file containing one intake_evidence object.")
+    p.add_argument(
+        "--stdin",
+        action="store_true",
+        help="Read JSON object from stdin.",
+    )
+    p.add_argument(
+        "--self-test",
+        action="store_true",
+        help="Run library sanity checks and exit.",
+    )
+    args = p.parse_args()
+
+    if args.self_test:
+        intake_evidence_lib.self_test()
+        print("[INTAKE_EVIDENCE_SELF_TEST_OK]")
+        return 0
+
+    raw = ""
+    if args.file:
+        with open(os.path.abspath(args.file), encoding="utf-8") as f:
+            raw = f.read()
+    elif args.stdin:
+        raw = sys.stdin.read()
+    else:
+        print("error: specify --file, --stdin, or --self-test", file=sys.stderr)
+        return 2
+
+    try:
+        bundle = json.loads(raw)
+    except json.JSONDecodeError as e:
+        print(f"error: invalid JSON: {e}", file=sys.stderr)
+        return 2
+
+    if not isinstance(bundle, dict):
+        print("error: root must be a JSON object", file=sys.stderr)
+        return 2
+
+    r = intake_evidence_lib.validate_intake_evidence(bundle)
+    if r.ok:
+        print("[INTAKE_EVIDENCE_VALIDATION_OK]")
+        return 0
+
+    print(intake_evidence_lib.format_blocked_message(r), file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/template/scripts/token_cost_compare.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+"""Compare two token-cost run JSON records for AC-2 (same run_class_hash, 50% cache read)."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+_SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+if _SCRIPT_DIR not in sys.path:
+    sys.path.insert(0, _SCRIPT_DIR)
+
+import token_cost_lib  # noqa: E402
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("baseline", type=Path, help="JSON file with run_class_hash + totals")
+    p.add_argument("target", type=Path, help="JSON file with run_class_hash + totals")
+    p.add_argument(
+        "--reduction-fraction",
+        type=float,
+        default=0.5,
+        help="Required fractional reduction in cache_read_tokens (default 0.5)",
+    )
+    args = p.parse_args()
+    base = json.loads(args.baseline.read_text(encoding="utf-8"))
+    tgt = json.loads(args.target.read_text(encoding="utf-8"))
+    ok, msg = token_cost_lib.compare_cache_read_reduction(
+        base, tgt, reduction_fraction=args.reduction_fraction
+    )
+    print(msg)
+    return 0 if ok else 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/template/scripts/token_cost_lib.py

@@ -0,0 +1,108 @@
+"""Token-cost run class, metrics, and AC-2 comparability helpers (US-0080 / DEC-0062)."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any, Mapping
+
+# Canonical metric keys (DEC-0062 §1) — totals / per-phase rows
+METRIC_KEYS = (
+    "cache_read_tokens",
+    "input_tokens",
+    "output_tokens",
+    "phase_call_count",
+    "cache_creation_tokens",
+    "orchestrator_call_estimate",
+)
+
+REQUIRED_TOTAL_KEYS = (
+    "cache_read_tokens",
+    "input_tokens",
+    "output_tokens",
+)
+
+
+def canonical_json_dumps(obj: Mapping[str, Any]) -> str:
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"))
+
+
+def compute_run_class_hash(run_class: Mapping[str, Any]) -> str:
+    """SHA-256 hex (lowercase) of canonical JSON for DEC-0062 §2 tuple."""
+    payload = canonical_json_dumps(run_class)
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def compute_strict_proof_hash(
+    orchestrator_run_id: str,
+    runtime_proof_id: str,
+    phase_id: str,
+    role: str,
+    proof_issued_at: str,
+    proof_ttl_seconds: int,
+) -> str:
+    """DEC-0038-style sorted-key JSON SHA-256 over the strict-proof tuple fields."""
+    obj = {
+        "orchestrator_run_id": orchestrator_run_id,
+        "runtime_proof_id": runtime_proof_id,
+        "phase_id": phase_id,
+        "role": role,
+        "proof_issued_at": proof_issued_at,
+        "proof_ttl_seconds": int(proof_ttl_seconds),
+    }
+    return hashlib.sha256(canonical_json_dumps(obj).encode("utf-8")).hexdigest()
+
+
+def validate_run_totals(row: Mapping[str, Any]) -> list[str]:
+    """Return diagnostic strings for invalid totals; empty if OK."""
+    errs: list[str] = []
+    for k in REQUIRED_TOTAL_KEYS:
+        if k not in row:
+            errs.append(f"missing_metric:{k}")
+            continue
+        v = row[k]
+        if not isinstance(v, int) or v < 0:
+            errs.append(f"invalid_non_negative_int:{k}")
+    if "metric_source" not in row or not str(row.get("metric_source", "")).strip():
+        errs.append("missing_metric_source")
+    return errs
+
+
+def compare_cache_read_reduction(
+    baseline: Mapping[str, Any],
+    target: Mapping[str, Any],
+    *,
+    reduction_fraction: float = 0.5,
+) -> tuple[bool, str]:
+    """
+    AC-2: target must achieve >= reduction_fraction lower cache_read_tokens
+    vs baseline when run_class_hash matches. Otherwise TOKEN_COST_RUN_CLASS_MISMATCH.
+    """
+    hb = baseline.get("run_class_hash")
+    ht = target.get("run_class_hash")
+    if not isinstance(hb, str) or not isinstance(ht, str) or hb != ht:
+        return False, "TOKEN_COST_RUN_CLASS_MISMATCH: run_class_hash differs or missing"
+
+    tb = baseline.get("totals") or {}
+    tt = target.get("totals") or {}
+    if not isinstance(tb, Mapping) or not isinstance(tt, Mapping):
+        return False, "TOKEN_COST_RUN_CLASS_MISMATCH: totals object missing"
+
+    br = tb.get("cache_read_tokens")
+    tr = tt.get("cache_read_tokens")
+    if not isinstance(br, int) or not isinstance(tr, int) or br < 0 or tr < 0:
+        return False, "TOKEN_COST_RUN_CLASS_MISMATCH: invalid cache_read_tokens"
+
+    if br == 0:
+        if tr == 0:
+            return True, "ok: baseline and target zero cache_read_tokens"
+        return False, "TOKEN_COST_RUN_CLASS_MISMATCH: baseline zero but target non-zero"
+
+    max_target = int(br * (1.0 - reduction_fraction))
+    if tr > max_target:
+        return (
+            False,
+            f"TOKEN_COST_RUN_CLASS_MISMATCH: cache_read_tokens {tr} exceeds "
+            f"50% reduction threshold (baseline {br}, max_target {max_target})",
+        )
+    return True, "ok: cache_read_tokens meets 50% reduction vs baseline"