platformforge 0.1.0__py3-none-any.whl

platformforge/economy/qpt.py

@@ -0,0 +1,286 @@
+"""Quality-per-token (§30–§32 + cycle-2.1 §34–50) — measured, not claimed.
+
+Methodology: build a `ContextEnvelope` for the full context and one for the
+TokenSave-packed context, serialize BOTH with the same serializer, estimate
+tokens on exactly those bytes, then hand each envelope to the same judge.
+What is measured is what is evaluated — no off-envelope facts.
+
+Deterministic facts the local engine reads are the *working set*, not model
+spend: they land in `deterministic_input_bytes`/`deterministic_fact_count`,
+while `model_context_*` counts only bytes a model/agent would receive.
+
+Verdicts: `beneficial` (reduction > 0 AND all quality floors pass),
+`optimization_not_beneficial` (reduction exists but quality dropped below a
+floor — quality wins over economy), `no_reduction` (pack didn't shrink).
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from platformforge.economy.envelope import ContextEnvelope
+from platformforge.tokensave.budget import Budget
+from platformforge.tokensave.index import SearchIndex
+from platformforge.tokensave.packs import ContextPackBuilder
+
+DEFAULT_FLOORS = {"finding_recall": 0.98, "evidence_recall": 0.98,
+                  "precision": 0.9, "unresolved_recall": 1.0}
+
+
+def _pr(actual: set[str], predicted: set[str]) -> dict[str, Any]:
+    tp = len(actual & predicted)
+    return {
+        "recall": tp / len(actual) if actual else 1.0,
+        "precision": tp / len(predicted) if predicted else 1.0,
+        "tp": tp, "fn": len(actual - predicted), "fp": len(predicted - actual),
+    }
+
+
+def _default_judge(versions: dict[str, str] | None):
+    from platformforge.models import Fact
+    from platformforge.resources import data_path
+    from platformforge.rules import RuleEngine, load_catalog
+    eng = RuleEngine(load_catalog(data_path("rules", "catalog")),
+                     versions=versions)
+
+    def judge(env: ContextEnvelope) -> list[dict[str, Any]]:
+        out, _ = eng.evaluate([Fact.from_dict(f) for f in env.facts])
+        return [{"rule_id": f.rule_id, "status": f.status,
+                 "fact": ev} for f in out for ev in f.evidence]
+    return judge
+
+
+def quality_per_token(*, facts_full: list[dict[str, Any]],
+                      findings_full: list[dict[str, Any]],
+                      index: SearchIndex, task: str,
+                      budget: Budget | None = None,
+                      judge=None,
+                      floors: dict[str, float] | None = None,
+                      versions: dict[str, str] | None = None) -> dict[str, Any]:
+    """Compare full-context judgment vs packed-context judgment.
+
+    `judge(ContextEnvelope) -> list[finding-dicts]` — defaults to the rule
+    catalog evaluated over `env.facts` (versions-aware).
+    """
+    floors = floors or DEFAULT_FLOORS
+    judge_is_default = judge is None
+    judge = judge or _default_judge(versions)
+
+    # deterministic working set — local facts are not model spend (§38)
+    det = ContextEnvelope(kind="deterministic", facts=facts_full,
+                          metadata={"task": task, "variant": "working-set"})
+
+    # baseline = everything the pack could have received: every indexed file
+    # body + facts + findings (no duplication: files are raw content, facts
+    # are the extracted contract a pack would carry anyway)
+    all_files = [{"path": p, "content": index.read(p) or ""}
+                 for p in index.by_path("*")]
+    full = ContextEnvelope(kind="model", files=all_files,
+                           facts=facts_full, findings=findings_full,
+                           metadata={"task": task, "variant": "full"})
+    builder = ContextPackBuilder(index)
+    # retain_content → the envelope carries the EXACT bytes the pack
+    # delivers (truncated bodies, not re-read full files)
+    pack = builder.build(task, budget=budget, facts=facts_full,
+                         findings=findings_full, retain_content=True)
+    if pack["budget_decision"] == "refuse":
+        return {"task": task, "verdict": "refused",
+                "budget_decision": "refuse",
+                "reason": pack["budget_reason"],
+                "refusals": pack.get("refusals", [])}
+
+    # packed = what the pack actually delivers: delivered file bodies +
+    # facts/findings/rules/symbols/graph neighborhood it carries
+    packed = ContextEnvelope(
+        kind="model",
+        files=[{"path": f["path"], "content": f.get("content", "")}
+               for f in pack["relevant_files"]],
+        facts=list(pack.get("facts") or []),
+        findings=list(pack.get("findings") or []),
+        rules=list(pack.get("rules") or []),
+        graph={"neighborhood": pack.get("graph_neighborhood") or []},
+        metadata={"task": task, "variant": "tokensave",
+                  "symbols": pack.get("relevant_symbols") or [],
+                  "sources": pack.get("sources") or [],
+                  "pack_budget": pack.get("budget"),
+                  "budget_decision": pack.get("budget_decision")})
+
+    # measure BEFORE judging — a mutating judge must not shift the numbers
+    tokens_full, bytes_full = full.estimated_tokens, full.byte_size
+    tokens_pack, bytes_pack = packed.estimated_tokens, packed.byte_size
+
+    # same serializer + estimator for both sides; judge sees exactly the
+    # envelope that was measured
+    t0 = time.perf_counter()
+    full_res = judge(full)
+    t_full = time.perf_counter() - t0
+    t0 = time.perf_counter()
+    pack_res = judge(packed)
+    t_pack = time.perf_counter() - t0
+
+    def viol(rs): return {f["rule_id"] for f in rs if f.get("status") == "violated"}
+    def ev(rs):   return {f["fact"] for f in rs if f.get("status") == "violated"}
+    def unr(rs):  return {f["rule_id"] for f in rs if f.get("status") == "unresolved"}
+    def kept(rs): return {f["rule_id"] for f in rs
+                          if f.get("status") == "unresolved"}
+
+    fr = _pr(viol(full_res), viol(pack_res))
+    evr = _pr(ev(full_res), ev(pack_res))
+    # unresolved correctness: a baseline-unresolved rule must STAY
+    # unresolved — flipping to `violated` on less context is an overclaim,
+    # counted as lost (and as a false positive by `fr`).
+    unres_lost = sorted(unr(full_res) - kept(pack_res))
+    unres_recall = 1.0 - (len(unres_lost) / len(unr(full_res))
+                          if unr(full_res) else 0.0)
+
+    reduction = (1 - tokens_pack / tokens_full) if tokens_full else 0.0
+
+    floors_ok = {
+        "finding_recall": fr["recall"] >= floors["finding_recall"],
+        "evidence_recall": evr["recall"] >= floors["evidence_recall"],
+        "precision": fr["precision"] >= floors["precision"],
+        "unresolved_recall": unres_recall >= floors["unresolved_recall"],
+    }
+    if reduction <= 0:
+        verdict = "no_reduction"
+    elif all(floors_ok.values()):
+        verdict = "beneficial"
+    else:
+        verdict = "optimization_not_beneficial"
+
+    return {
+        "task": task,
+        "baseline": {
+            "model_context_bytes": bytes_full,
+            "estimated_tokens": tokens_full,
+            "facts": len(full.facts),
+            "judge_seconds": round(t_full, 6),
+            "findings_violated": sorted(viol(full_res)),
+            "findings_unresolved": sorted(unr(full_res)),
+        },
+        "optimized": {
+            "model_context_bytes": bytes_pack,
+            "estimated_tokens": tokens_pack,
+            "facts": len(packed.facts),
+            "judge_seconds": round(t_pack, 6),
+            "findings_violated": sorted(viol(pack_res)),
+            "findings_unresolved": sorted(unr(pack_res)),
+            "pack_refusals": pack.get("refusals") or [],
+        },
+        "deterministic": det.ledger_fields(),
+        "quality": {
+            "finding_recall": fr["recall"], "finding_precision": fr["precision"],
+            "evidence_recall": evr["recall"], "evidence_precision": evr["precision"],
+            "false_negatives": fr["fn"], "false_positives": fr["fp"],
+            "unresolved_recall": round(unres_recall, 4),
+            "unresolved_lost": unres_lost,
+            "floors": floors, "floors_ok": floors_ok,
+        },
+        "economy": {
+            "token_reduction": round(reduction, 4),
+            "byte_reduction": round(
+                1 - bytes_pack / bytes_full, 4) if bytes_full else 0.0,
+        },
+        # honesty label: the shipped judge reads env.facts only, and the
+        # pack carries facts as essential-complete — quality floors then
+        # measure payload integrity, not file-dependent judgment. A
+        # file-consuming judge (inject `judge=`) exercises the rest.
+        "quality_measurement": ("facts-only (files not judged)"
+                                if judge_is_default
+                                else "custom judge"),
+        "verdict": verdict,
+        # compat with pre-2.1 readers
+        "tokens_full_context": tokens_full, "tokens_packed": tokens_pack,
+        "token_reduction": round(reduction, 4),
+        "finding_recall": fr["recall"], "finding_precision": fr["precision"],
+        "evidence_recall": evr["recall"], "evidence_precision": evr["precision"],
+        "facts_full": len(facts_full), "facts_packed": len(packed.facts),
+        "floors": floors,
+        "quality_gate": "pass" if verdict == "beneficial" else "fail",
+    }
+
+
+# --- QPT v3: generalized quality-per-cost (economy spec §161–165) --------
+
+COST_DIMENSIONS = ("tokens", "bytes", "tool_calls", "model_calls",
+                   "agents", "provider_calls", "wall_time_s", "money")
+
+
+def quality_per_cost(qpt_result: dict[str, Any], *,
+                     optimized_usage: dict[str, Any] | None = None,
+                     baseline_usage: dict[str, Any] | None = None,
+                     money: dict[str, Any] | None = None) -> dict[str, Any]:
+    """QPT v3 — the same quality floors measured against every cost axis.
+
+    `qpt_result` is the output of `quality_per_token` (floors + verdict).
+    `baseline_usage`/`optimized_usage` carry the measured per-mode costs:
+    tokens, tool_calls, model_calls, agents, provider_calls, wall_time_s.
+    `money` is a ProviderCost dict from economy.pricing — optional, and
+    `unresolved` when pricing is missing (never a guessed dollar).
+
+    Every dimension is reported individually; the composite score is a
+    decomposable mean of per-dimension reduction ratios — it summarizes,
+    it never hides a dimension (§164). Quality floors still gate: no
+    cost win counts when a floor failed.
+    """
+    opt = optimized_usage or {}
+    base = baseline_usage or {}
+    dims: dict[str, Any] = {}
+
+    # tokens/bytes come from the measured envelopes inside qpt_result
+    bt = base.get("estimated_tokens",
+                  qpt_result.get("baseline", {}).get("estimated_tokens"))
+    ot = opt.get("estimated_tokens",
+                 qpt_result.get("optimized", {}).get("estimated_tokens"))
+    bb = base.get("bytes",
+                  qpt_result.get("baseline", {}).get("model_context_bytes"))
+    ob = opt.get("bytes",
+                 qpt_result.get("optimized", {}).get("model_context_bytes"))
+    for name, b, o in (("tokens", bt, ot), ("bytes", bb, ob)):
+        if b is not None and o is not None:
+            dims[name] = {"baseline": b, "optimized": o,
+                          "reduction": round(1 - o / b, 4) if b else 0.0}
+
+    for name in ("tool_calls", "model_calls", "agents",
+                 "provider_calls", "wall_time_s"):
+        b, o = base.get(name), opt.get(name)
+        if b is None and o is None:
+            dims[name] = {"state": "unresolved",
+                          "reason": "not measured"}
+        elif b is None or o is None:
+            dims[name] = {"state": "partial",
+                          "baseline": b, "optimized": o}
+        else:
+            dims[name] = {"baseline": b, "optimized": o,
+                          "reduction": round(1 - o / b, 4) if b else 0.0}
+
+    dims["money"] = money if money is not None else {
+        "state": "unresolved",
+        "reason": "PF-ECONOMY-PRICING-MISSING — no declared rate, "
+                  "no dollar claim"}
+
+    measured = [d["reduction"] for d in dims.values()
+                if isinstance(d, dict) and "reduction" in d]
+    quality = qpt_result.get("quality", {})
+    floors_ok = all(quality.get("floors_ok", {}).values()) \
+        if quality.get("floors_ok") else qpt_result.get("verdict") == "beneficial"
+
+    return {
+        "task": qpt_result.get("task"),
+        "verdict": qpt_result.get("verdict"),
+        "quality_floors_ok": floors_ok,
+        "dimensions": dims,
+        "composite": {
+            "cost_reduction_mean": (round(sum(measured) / len(measured), 4)
+                                    if measured else 0.0),
+            "decomposable": True,
+            "note": "mean over measured dims only; unresolved dims are "
+                    "excluded, not zeroed",
+        },
+        "honest_claim": ("no savings claim — quality floor failed"
+                         if not floors_ok else
+                         ("measured reduction across "
+                          f"{len(measured)} dimensions"
+                          if measured else "nothing measured")),
+    }

platformforge/economy/reconcile.py

@@ -0,0 +1,86 @@
+"""BudgetReconciliation (§81–88) — planned vs observed, per axis.
+
+Observed absent → `unresolved` (§85), never a fake zero. Savings claims
+require observed usage + declared pricing — "saved $X" without both is
+refused (§86, §293 north star). Historical mismatch feeds routing signal
+(§88) as data, never self-modifying policy (§153).
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+SCHEMA = "platformforge/reconciliation/v1"
+
+AXES = ("tokens", "context", "tools", "agents", "provider_calls",
+        "duration", "money")
+
+
+@dataclass
+class AxisRecon:
+    planned: float | None
+    observed: float | None
+    state: str              # ok|over|under|unresolved
+    error_pct: float | None = None   # §84 calibration error
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class BudgetReconciliation:
+    schema: str = SCHEMA
+    run_id: str = ""
+    axes: dict[str, AxisRecon] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"schema": self.schema, "run_id": self.run_id,
+                "axes": {k: v.to_dict() for k, v in self.axes.items()},
+                "calibrated_axes": [k for k, v in self.axes.items()
+                                    if v.state != "unresolved"],
+                "unresolved_axes": [k for k, v in self.axes.items()
+                                    if v.state == "unresolved"]}
+
+
+def reconcile(planned: dict[str, float | None],
+              observed: dict[str, float | None],
+              run_id: str = "", *,
+              tolerance_pct: float = 20.0) -> BudgetReconciliation:
+    """§82–87 — per-axis compare. `observed=None` means the axis was not
+    measured → unresolved, never treated as 0."""
+    rec = BudgetReconciliation(run_id=run_id)
+    for axis in AXES:
+        p = planned.get(axis)
+        o = observed.get(axis)
+        if p is None and o is None:
+            continue
+        if o is None:
+            rec.axes[axis] = AxisRecon(p, None, "unresolved")
+            continue
+        if p is None:
+            rec.axes[axis] = AxisRecon(None, o, "unresolved")
+            continue
+        err = ((o - p) / p * 100.0) if p else (100.0 if o else 0.0)
+        state = "ok" if abs(err) <= tolerance_pct else \
+            ("over" if err > 0 else "under")
+        rec.axes[axis] = AxisRecon(p, o, state, round(err, 1))
+    return rec
+
+
+def savings_claim(observed_spend: float | None,
+                  declared_pricing: bool) -> dict[str, Any]:
+    """§86/§293 — a $-savings claim needs observed spend AND declared
+    pricing; otherwise the honest answer is unresolved."""
+    if observed_spend is None:
+        return {"claim": "unresolved",
+                "reason": "no observed usage — cannot claim savings",
+                "code": "PF-ECONOMY-USAGE-UNOBSERVED"}
+    if not declared_pricing:
+        return {"claim": "unresolved",
+                "reason": "tokens observed but pricing absent — cost "
+                          "unresolved, not $0",
+                "code": "PF-ECONOMY-PRICING-MISSING",
+                "observed_spend": observed_spend}
+    return {"claim": "supported",
+            "observed_spend": observed_spend}

platformforge/economy/verifyplan.py

@@ -0,0 +1,107 @@
+"""Selective verification (§97–104) — VerificationPlanner.
+
+Impact-based, not test-skipping (§103): select the verification tiers the
+change's scope/risk/graph-impact/security require, record selected AND
+skipped with reasons in the verification ledger (§104). Risk floors
+(§100) cap how low a risky change may verify; security changes always
+include the security check (§101); the verification floor cannot be
+lowered by budget pressure (§19/§246).
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+SCHEMA = "platformforge/verification-plan/v1"
+
+TIERS = ("V0-static", "V1-contract", "V2-unit", "V3-integration",
+         "V4-runtime", "V5-production-evidence")
+
+TIER_ORDER = {t: i for i, t in enumerate(TIERS)}
+
+# §100 — risk floors: the cheapest tier a risk class may stop at.
+RISK_FLOORS = {"low": "V0-static", "medium": "V1-contract",
+               "high": "V3-integration", "critical": "V4-runtime"}
+
+SEC_CHECK = "security-verification"   # §101 — always present if touched
+
+
+@dataclass
+class VerificationPlan:
+    schema: str = SCHEMA
+    risk: str = "low"
+    security_sensitive: bool = False
+    floor: str = "V0-static"
+    selected: list[str] = field(default_factory=list)
+    skipped: list[str] = field(default_factory=list)
+    checks: list[str] = field(default_factory=list)
+    reasons: dict[str, str] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+class VerificationPlanner:
+    """Select tiers + checks from change signal; write the ledger."""
+
+    def __init__(self, root: str | Path | None = None):
+        self.root = Path(root) if root else None
+
+    def plan(self, *, risk: str = "low", security_sensitive: bool = False,
+             change_scope: str = "local", impacted_nodes: int = 0,
+             touches_security: bool = False,
+             runtime_change: bool = False,
+             available_checks: list[str] | None = None,
+             budget_pressure: bool = False) -> VerificationPlan:
+        floor = RISK_FLOORS.get(risk, "V0-static")
+
+        # graph-aware selection (§102): large blast raises the floor
+        if impacted_nodes > 100 and TIER_ORDER[floor] < TIER_ORDER[
+                "V2-unit"]:
+            floor = "V2-unit"
+        if change_scope in ("platform", "org") and TIER_ORDER[floor] < \
+                TIER_ORDER["V3-integration"]:
+            floor = "V3-integration"
+        if runtime_change and TIER_ORDER[floor] < TIER_ORDER[
+                "V4-runtime"]:
+            floor = "V4-runtime"
+
+        # budget may never lower the floor (§246 property)
+        selected = TIERS[:TIER_ORDER[floor] + 1]
+        skipped = TIERS[TIER_ORDER[floor] + 1:]
+
+        checks: list[str] = []
+        reasons: dict[str, str] = {
+            "floor": f"risk={risk} → floor {floor}"}
+        if touches_security or security_sensitive:
+            checks.append(SEC_CHECK)
+            reasons[SEC_CHECK] = "§101 — security change always verifies security"
+        if budget_pressure:
+            reasons["budget"] = ("budget pressure recorded — floor "
+                                 "unchanged (verification floor is "
+                                 "protected)")
+
+        plan = VerificationPlan(risk=risk,
+                                security_sensitive=security_sensitive
+                                or touches_security,
+                                floor=floor, selected=list(selected),
+                                skipped=list(skipped), checks=checks,
+                                reasons=reasons)
+        self._record(plan)
+        return plan
+
+    def _record(self, plan: VerificationPlan) -> None:
+        """§104 — verification ledger: selected, skipped, why."""
+        if not self.root:
+            return
+        d = self.root / ".platformforge" / "ledger"
+        d.mkdir(parents=True, exist_ok=True)
+        row = {"schema": SCHEMA, "ts": time.time(),
+               "selected": plan.selected, "skipped": plan.skipped,
+               "checks": plan.checks, "reasons": plan.reasons}
+        with open(d / "verification.jsonl", "a") as fh:
+            fh.write(json.dumps(row, sort_keys=True) + "\n")

platformforge/economy/waste.py

@@ -0,0 +1,123 @@
+"""EconomyWasteDetector (§112–116) — reads the ledgers and reports waste
+as findings. Recommendations only — never auto-fixes routing (§115)."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+WASTE_TYPES = ("duplicate_context", "duplicate_tool_call",
+               "repeated_graph_build", "unused_agent", "overrouting",
+               "repeated_provider_call", "unused_expansion",
+               "cache_bypass", "oversized_context",
+               "unnecessary_verification")
+
+
+@dataclass
+class WasteFinding:
+    """§114 — the output shape."""
+    waste_type: str
+    estimated_impact: str            # low|medium|high — never fake bytes
+    evidence: dict[str, Any] = field(default_factory=dict)
+    confidence: str = "medium"
+    recommended_fix: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+class EconomyWasteDetector:
+    """Scans `.platformforge/ledger/*.jsonl` and reports waste."""
+
+    def __init__(self, root: str | Path):
+        self.root = Path(root)
+
+    def _read(self, name: str) -> list[dict[str, Any]]:
+        import json
+        p = self.root / ".platformforge" / "ledger" / name
+        if not p.exists():
+            return []
+        return [json.loads(l) for l in p.read_text().splitlines()
+                if l.strip()]
+
+    def detect(self) -> dict[str, Any]:
+        findings: list[WasteFinding] = []
+
+        tokens = self._read("tokens.jsonl")
+        econ = self._read("economy.jsonl")
+        runs = self._read("agent-runs.jsonl")
+
+        # duplicate tool call: same tool+input_bytes hash row repeated
+        tool_rows = [e for e in econ if e.get("entry_type") == "tool"]
+        seen_tool: dict[str, int] = {}
+        for e in tool_rows:
+            k = f"{e.get('tool')}:{e.get('input_bytes')}:{e.get('run_id')}"
+            seen_tool[k] = seen_tool.get(k, 0) + 1
+        dups = {k: n for k, n in seen_tool.items() if n > 1}
+        if dups:
+            findings.append(WasteFinding(
+                "duplicate_tool_call", "medium",
+                {"calls": dups}, "high",
+                "route through the cache layer or dedup identical calls"))
+
+        # repeated provider call
+        prov = [e for e in econ if e.get("entry_type") == "provider"]
+        by_coll: dict[str, int] = {}
+        for e in prov:
+            k = f"{e.get('collector')}:{e.get('service')}"
+            by_coll[k] = by_coll.get(k, 0) + e.get("api_calls", 0)
+        if prov and all(e.get("cache_hits", 0) == 0 for e in prov) \
+                and any(n > 50 for n in by_coll.values()):
+            findings.append(WasteFinding(
+                "repeated_provider_call", "high",
+                {"calls_by_service": by_coll}, "medium",
+                "enable provider call caching or widen observation reuse"))
+
+        # cache bypass: token rows that delivered but never reused
+        delivered = sum(e.get("context_delivered", 0) for e in tokens)
+        reused = sum(e.get("context_reused", 0) for e in tokens)
+        if len(tokens) >= 5 and delivered and reused == 0:
+            findings.append(WasteFinding(
+                "cache_bypass", "high",
+                {"operations": len(tokens), "delivered": delivered,
+                 "reused": 0}, "medium",
+                "route context builds through CacheStore"))
+
+        # overrouting: runs with fanout>1 for deterministic task types
+        over = [r for r in runs
+                if r.get("mode") in ("multi-specialist", "coordinated")
+                and r.get("extra", {}).get("task_type") in
+                ("lint", "inventory", "policy", "diff")]
+        if over:
+            findings.append(WasteFinding(
+                "overrouting", "medium",
+                {"runs": [r.get("run_id") for r in over]}, "medium",
+                "simple tasks route deterministic/single-specialist "
+                "(§123)"))
+
+        # oversized context: delivered > 32k est tokens repeatedly
+        big = [e for e in tokens
+               if (e.get("context_delivered") or 0) > 32000]
+        if len(big) >= 3:
+            findings.append(WasteFinding(
+                "oversized_context", "medium",
+                {"deliveries_over_32k": len(big)}, "medium",
+                "tighten context budget or use delta context (§74)"))
+
+        # unused expansion: tool expanded_bytes>0 but output small
+        unused_exp = [e for e in tool_rows
+                      if e.get("expanded_bytes", 0) > 0
+                      and e.get("output_bytes", 0) < 200]
+        if unused_exp:
+            findings.append(WasteFinding(
+                "unused_expansion", "low",
+                {"entries": len(unused_exp)}, "low",
+                "expand-on-demand may have fetched unneeded detail"))
+
+        return {"waste_findings": [f.to_dict() for f in findings],
+                "scanned": {"token_rows": len(tokens),
+                            "economy_rows": len(econ),
+                            "agent_runs": len(runs)},
+                "note": "recommendations only — routing is never "
+                        "auto-modified (§115)"}

platformforge/evals/__init__.py

@@ -0,0 +1,16 @@
+"""Eval framework (§94–95) — typed cases over fixtures, graded offline.
+
+Case types (§94): unit, integration, golden, contract, property,
+metamorphic, regression, recall, precision, token_economy,
+graph_correctness, routing, security.
+
+§95 variants per finding: positive | negative | boundary | unresolved |
+version — declared in `variant` and checked against the expectation kind
+(positive must fire, negative must not, boundary states the edge,
+unresolved expects the finding absent AND the fact unresolved, version
+pairs a rule constraint with a fixture version).
+"""
+
+from platformforge.evals.runner import EVAL_TYPES, VARIANTS, run_all, run_case
+
+__all__ = ["EVAL_TYPES", "VARIANTS", "run_all", "run_case"]