platformforge 0.1.0__py3-none-any.whl

platformforge/routing/__init__.py

@@ -0,0 +1,13 @@
+"""Adaptive routing — computed dispatch, never "call all agents"."""
+
+from platformforge.routing.router import (
+                                          DOMAIN_SPECIALIST,
+                                          TASK_COORDINATOR,
+                                          TaskSignal,
+                                          load_routes,
+                                          route,
+                                          validate_routing,
+)
+
+__all__ = ["DOMAIN_SPECIALIST", "TASK_COORDINATOR", "TaskSignal",
+           "load_routes", "route", "validate_routing"]

platformforge/routing/decision.py

@@ -0,0 +1,191 @@
+"""Routing control plane contracts (§138–160): RoutingRequest,
+RoutingDecision, profiles, RoutingScorecard, receipts, decision plane.
+
+Profiles (§142–146): economy | balanced | deep | strict | offline.
+Risk can raise the minimum profile (§147), never lower it. A profile
+change is policy — recorded in the routing receipt (§154) with policy
+version; champion/challenger promotion is human-gated (§153).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+SCHEMA_REQ = "platformforge/routing-request/v1"
+SCHEMA_DEC = "platformforge/routing-decision/v1"
+SCHEMA_SCORE = "platformforge/routing-scorecard/v1"
+ROUTING_POLICY_VERSION = "platformforge/routing/v2"
+
+PROFILES = ("economy", "balanced", "deep", "strict", "offline")
+PROFILE_ORDER = {p: i for i, p in enumerate(
+    ("offline", "economy", "balanced", "deep", "strict"))}
+
+# profile → envelope hints (§143–146). Offline forbids provider calls.
+PROFILE_DEFAULTS: dict[str, dict[str, Any]] = {
+    "economy": {"prefer": ["deterministic", "cache", "single-specialist"],
+                "context_bytes_soft": 6000, "max_agents": 1,
+                "provider_calls_hard": 0, "verification_floor": "V0-static"},
+    "balanced": {"prefer": ["deterministic", "single-specialist"],
+                 "context_bytes_soft": 16000, "max_agents": 3,
+                 "provider_calls_hard": 20,
+                 "verification_floor": "V1-contract"},
+    "deep": {"prefer": ["multi-specialist", "coordinated"],
+             "context_bytes_soft": 30000, "max_agents": 6,
+             "provider_calls_hard": 50,
+             "verification_floor": "V3-integration"},
+    "strict": {"prefer": ["critical-review"],
+               "context_bytes_soft": 40000, "max_agents": 8,
+               "provider_calls_hard": 100,
+               "verification_floor": "V4-runtime"},
+    "offline": {"prefer": ["deterministic"],
+                "context_bytes_soft": 16000, "max_agents": 1,
+                "provider_calls_hard": 0,
+                "verification_floor": "V1-contract"},
+}
+
+# §147 — risk floors: the cheapest profile a risk may run under.
+RISK_PROFILE_FLOOR = {"low": "economy", "medium": "balanced",
+                      "high": "deep", "critical": "strict"}
+
+
+@dataclass
+class RoutingRequest:
+    """§139 — what a task asks the routing control plane."""
+    schema: str = SCHEMA_REQ
+    task: str = ""
+    profile: str = "balanced"
+    risk: str = "low"
+    signal: dict[str, Any] = field(default_factory=dict)
+
+    def effective_profile(self) -> str:
+        """§147 — risk raises the floor; it never lowers it."""
+        floor = RISK_PROFILE_FLOOR.get(self.risk, "economy")
+        if PROFILE_ORDER[self.profile] < PROFILE_ORDER[floor]:
+            return floor
+        return self.profile
+
+
+@dataclass
+class RoutingDecision:
+    """§140–141 — the canonical routed decision."""
+    schema: str = SCHEMA_DEC
+    mode: str = "deterministic"
+    agents: list[str] = field(default_factory=list)
+    model_tier: str = "none"               # none|cheap|strong (host maps)
+    context_budget: int | None = None
+    tool_budget: int | None = None
+    provider_budget: int | None = None
+    verification_tier: str = "V0-static"
+    reason: str = ""
+    risk: str = "low"
+    profile: str = "balanced"
+    fallback: str = ""
+    policy_version: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class RoutingScorecard:
+    """§148–149 — measured scorecard per routed run."""
+    schema: str = SCHEMA_SCORE
+    run_id: str = ""
+    mode: str = ""
+    correctness: float | None = None
+    evidence: float | None = None
+    tokens: int | None = None
+    tools: int | None = None
+    latency_ms: float | None = None
+    agents: int = 0
+    provider_calls: int = 0
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def decide(request: RoutingRequest, *,
+           routes_path: str | Path | None = None) -> RoutingDecision:
+    """§139–141 — the ONLY producer of the canonical RoutingDecision.
+
+    Wraps the deterministic router (`routing/router.py::route`) and
+    applies the effective profile (risk raises the floor, never lowers).
+    EconomyEngine output is *advice* that may inform `request.signal` —
+    it is never a decision and never reaches orchestration. Hosts embed
+    `decision.to_dict()`; the orchestrator enforces the schema.
+    """
+    from platformforge.routing.router import TaskSignal, route
+    sig = TaskSignal.from_dict(request.signal or {})
+    routed = route(sig, routes_path)
+    profile = request.effective_profile()
+    defaults = PROFILE_DEFAULTS.get(profile, PROFILE_DEFAULTS["balanced"])
+    return RoutingDecision(
+        mode=routed.get("mode", "deterministic"),
+        agents=list(routed.get("agents")
+                    or routed.get("specialists") or []),
+        model_tier=routed.get("model_tier", "none"),
+        context_budget=defaults.get("context_bytes_soft"),
+        provider_budget=defaults.get("provider_calls_hard"),
+        verification_tier=defaults.get("verification_floor", "V0-static"),
+        reason="; ".join(routed.get("reasons", [])),
+        risk=request.risk, profile=profile,
+        fallback="; ".join(routed.get("fallbacks", [])),
+        policy_version=ROUTING_POLICY_VERSION)
+
+
+def receipt(request: RoutingRequest, decision: RoutingDecision,
+            estimated_budget: dict[str, Any]) -> dict[str, Any]:
+    """§154 — every routing decision records inputs + policy version +
+    decision + reason + estimated budget."""
+    body = {"request": request.signal, "profile": request.profile,
+            "decision": decision.to_dict()}
+    return {"schema": "platformforge/routing-receipt/v1",
+            "inputs_hash": hashlib.sha256(json.dumps(
+                body, sort_keys=True, default=str).encode()).hexdigest(),
+            "policy_version": decision.policy_version,
+            "decision": decision.to_dict(),
+            "reason": decision.reason,
+            "estimated_budget": estimated_budget,
+            "ts": time.time()}
+
+
+def promote_verdict(champion: dict[str, Any], challenger: dict[str, Any],
+                    *, human_approved: bool = False) -> dict[str, Any]:
+    """§150–153 — challenger promotes only when quality floor passes,
+    safety is unchanged AND economy is better — and always behind a
+    human review. Never self-modifying."""
+    quality_ok = challenger.get("quality_pass", False)
+    safety_ok = challenger.get("safety_unchanged", False)
+    economy_better = challenger.get("economy_better", False)
+    if not (quality_ok and safety_ok and economy_better):
+        return {"verdict": "rejected",
+                "reason": "challenger failed the gate: needs quality floor "
+                          "+ unchanged safety + better economy",
+                "champion_kept": True}
+    if not human_approved:
+        return {"verdict": "awaiting_human",
+                "reason": "challenger passed all gates — promotion still "
+                          "requires human review (§153)",
+                "champion_kept": True}
+    return {"verdict": "promotable", "champion": champion.get("id"),
+            "challenger": challenger.get("id")}
+
+
+def decision_receipt_link(cache_decision: dict[str, Any] | None,
+                          context_ref: str | None,
+                          routing_receipt: dict[str, Any],
+                          verification_plan: dict[str, Any] | None,
+                          budget_verdict: dict[str, Any] | None
+                          ) -> dict[str, Any]:
+    """§155–158 — one decision receipt links all plane decisions."""
+    return {"schema": "platformforge/decision-receipt/v1",
+            "cache": cache_decision, "context_ref": context_ref,
+            "routing": routing_receipt, "verification": verification_plan,
+            "budget": budget_verdict,
+            "policy_version": routing_receipt.get("policy_version", ""),
+            "ts": time.time()}

platformforge/routing/router.py

@@ -0,0 +1,328 @@
+"""Router V2 — adaptive routing as a full dispatch decision (§81–91).
+
+Route = f(task type, domains, complexity, risk, blast radius, security
+sensitivity, production, evidence completeness, coverage, freshness,
+expected provider cost, expected token cost, mutability, fleet scope,
+incident status). The table lives in rules/catalog/routing.yaml —
+data, not judgment.
+
+Output (§82): mode, coordinator, specialists, reviewers, verifier,
+execution DAG, budget, reasons, fallbacks — never just an agent list.
+
+Modes (§83): deterministic | single-specialist | multi-specialist |
+coordinated | debate | critical-review. Default is deterministic (§84);
+debate opens only on conflict / high risk+low confidence / explicit
+comparison (§88); critical-review is mandatory for production mutation,
+IAM, security, destructive data changes, large fleet optimization (§89).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+@dataclass
+class TaskSignal:
+    """§81 — the routing signals. v1 fields kept for compatibility."""
+    task_type: str = "analysis"        # lint|analysis|review|incident|architecture|change
+    domains: list[str] = field(default_factory=list)
+    complexity: str = "low"            # low|medium|high
+    risk: str = "low"                  # low|medium|high|critical
+    blast_radius: str = "local"        # local|service|platform|org
+    security_sensitive: bool = False
+    evidence_available: bool = True
+    production: bool = False
+    expected_cost: str = "low"             # provider cost: low|medium|high
+    evidence_completeness: float = 1.0     # 0-1 measured fraction
+    # --- v2 signals (§81) ------------------------------------------
+    coverage: float = 1.0                  # fraction of scope covered
+    freshness: str = "current"             # current|stale|unknown
+    expected_token_cost: str = "low"       # low|medium|high
+    mutability: str = "read"               # read|propose|mutate
+    fleet_scope: bool = False
+    incident_status: str = ""              # ""|active|mitigated
+    conflict: bool = False                 # specialists disagree (§88)
+    comparison: bool = False               # user asked to compare (§88)
+    destructive: bool = False              # destructive data change (§89)
+    optimization: bool = False             # optimization task (§89 fleet)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> TaskSignal:
+        return cls(**{k: v for k, v in d.items()
+                      if k in cls.__dataclass_fields__})
+
+
+# domain → canonical specialist. Declared data, audit-friendly.
+DOMAIN_SPECIALIST = {
+    "iac": "platform-iac-specialist", "terraform": "platform-iac-specialist",
+    "k8s": "platform-kubernetes-specialist",
+    "kubernetes": "platform-kubernetes-specialist",
+    "helm": "platform-kubernetes-specialist",
+    "gitops": "platform-gitops-specialist", "cicd": "platform-gitops-specialist",
+    "aws": "platform-aws-specialist", "cloud": "platform-aws-specialist",
+    "crossplane": "platform-crossplane-specialist",
+    "sre": "platform-sre-specialist", "slo": "platform-sre-specialist",
+    "incident": "platform-sre-specialist", "otel": "platform-sre-specialist",
+    "security": "platform-security-specialist",
+    "finops": "platform-finops-specialist", "cost": "platform-finops-specialist",
+    "graph": "platform-graph-specialist",
+    "fleet": "platform-fleet-specialist",
+    "policy": "platform-policy-specialist",
+    "governance": "platform-policy-specialist",
+    "capacity": "platform-capacity-specialist",
+    "reliability": "platform-capacity-specialist",
+    "product": "platform-product-specialist", "dx": "platform-product-specialist",
+    "ai": "platform-ai-infra-specialist", "gpu": "platform-ai-infra-specialist",
+    "federation": "platform-federation-specialist",
+}
+
+# coordinator per task shape (coordinators.py COORDINATOR_LOOPS echo)
+TASK_COORDINATOR = {
+    "incident": "platform-incident-coordinator",
+    "change": "platform-change-coordinator",
+    "fleet": "platform-fleet-coordinator",
+    "optimization": "platform-optimization-coordinator",
+    "product": "platform-product-coordinator",
+    "architecture": "platform-orchestrator",
+    "analysis": "platform-orchestrator",
+}
+
+BUILTIN_ROUTES: list[dict[str, Any]] = []  # table is canonical data now
+
+
+def _match(sig: TaskSignal, when: dict[str, Any]) -> bool:
+    for k, want in when.items():
+        have = getattr(sig, k, None)
+        if k == "domains":   # intersect, not equality
+            if not set(have or ()) & set(want or ()):
+                return False
+        elif isinstance(want, list):
+            if have not in want:
+                return False
+        elif have != want:
+            return False
+    return True
+
+
+def load_routes(path: str | Path | None = None) -> list[dict[str, Any]]:
+    from platformforge.resources import data_path
+    if path and Path(path).is_file():
+        doc = yaml.safe_load(Path(path).read_text()) or {}
+        return doc.get("routes", []) or []
+    default = data_path("rules", "catalog", "routing.yaml")
+    if default.is_file():
+        doc = yaml.safe_load(default.read_text()) or {}
+        return doc.get("routes", []) or []
+    return BUILTIN_ROUTES
+
+
+def _specialists_for(domains: list[str]) -> list[str]:
+    return [DOMAIN_SPECIALIST[d] for d in domains
+            if d in DOMAIN_SPECIALIST]
+
+
+def _needs_critical(signal: TaskSignal) -> bool:
+    """§89 — critical review is mandatory, not optional."""
+    return bool(
+        (signal.production and signal.mutability == "mutate")
+        or signal.destructive
+        or (signal.security_sensitive and signal.task_type == "change")
+        or (signal.optimization and signal.fleet_scope))
+
+
+def _needs_debate(signal: TaskSignal) -> bool:
+    """§88 — debate opens only on these; never by default."""
+    return bool(signal.conflict or signal.comparison
+                or (signal.risk in ("high", "critical")
+                    and signal.evidence_completeness < 0.5))
+
+
+def _budget(signal: TaskSignal, mode: str) -> str:
+    if mode == "deterministic":
+        return "tiny"
+    if mode in ("debate", "critical-review") or signal.risk == "critical":
+        return "critical" if signal.risk == "critical" else "deep"
+    if mode == "coordinated" or signal.fleet_scope:
+        return "deep"
+    if mode == "multi-specialist" or signal.complexity == "medium":
+        return "standard"
+    return "small"
+
+
+def _dag(mode: str, coordinator: str, specialists: list[str],
+         reviewers: list[str], verifier: str,
+         production: bool) -> list[dict[str, Any]]:
+    """Skeleton stage list for the decision — the orchestrator expands
+    it into the full loop DAG at prepare() time."""
+    if mode == "deterministic":
+        return []
+    dag: list[dict[str, Any]] = [{"stage": "extract",
+                                  "agent": "pf-extractor"}]
+    if coordinator:
+        dag.insert(0, {"stage": "dispatch", "agent": coordinator})
+    dag += [{"stage": f"specialist:{s}", "agent": s}
+            for s in specialists]
+    dag += [{"stage": f"review:{r}", "agent": r} for r in reviewers]
+    if production:
+        dag.append({"stage": "approval", "agent": "human-gate",
+                    "external": True})
+    dag.append({"stage": "verify", "agent": verifier})
+    return dag
+
+
+def route(signal: TaskSignal, routes_path: str | Path | None = None) -> dict[str, Any]:
+    """Compute the full dispatch decision (§82)."""
+    routes = load_routes(routes_path)
+    specialists: list[str] = []
+    reviewers: list[str] = []
+    coordinator = ""
+    reasons: list[str] = []
+    fallbacks: list[str] = ["playbook"]
+
+    # --- table rules (data) ------------------------------------------
+    for r in routes:
+        if _match(signal, r.get("when", {})):
+            for a in r.get("agents", []):
+                if a not in specialists:
+                    specialists.append(a)
+            for a in r.get("add_specialists", []):
+                if a not in specialists:
+                    specialists.append(a)
+            for a in r.get("add_reviewers", []):
+                if a not in reviewers:
+                    reviewers.append(a)
+            if r.get("coordinator") and not coordinator:
+                coordinator = r["coordinator"]
+            if r.get("reason"):
+                reasons.append(r["reason"])
+
+    # --- domain-derived specialists ----------------------------------
+    for s in _specialists_for(signal.domains):
+        if s not in specialists:
+            specialists.append(s)
+
+    # --- mode (policy, §83–89) -----------------------------------------
+    mode = "deterministic"
+    n = len(specialists)
+    if _needs_critical(signal):
+        mode = "critical-review"
+        coordinator = coordinator or "platform-change-coordinator"
+        for r in ("platform-operations-safety-reviewer",
+                  "platform-security-reviewer"):
+            if r not in reviewers:
+                reviewers.append(r)
+        reasons.append("critical-review mandatory: production/IAM/"
+                       "destructive/fleet-optimization (§89)")
+    elif _needs_debate(signal):
+        mode = "debate"
+        reasons.append("debate opened: conflict/comparison/high-risk "
+                       "low-confidence (§88)")
+    elif signal.fleet_scope or signal.task_type == "fleet":
+        mode = "coordinated"
+        coordinator = coordinator or "platform-fleet-coordinator"
+    elif signal.task_type in ("incident",) or signal.incident_status == "active":
+        mode = "coordinated"
+        coordinator = coordinator or "platform-incident-coordinator"
+    elif signal.complexity == "high" or n >= 3:
+        mode = "coordinated"
+        coordinator = coordinator or TASK_COORDINATOR.get(
+            signal.task_type, "platform-orchestrator")
+    elif n == 2:
+        mode = "multi-specialist"
+    elif n == 1 or (signal.domains and signal.task_type
+                    in ("analysis", "review")):
+        mode = "single-specialist"
+
+    if signal.task_type == "lint":
+        mode = "deterministic"
+        specialists, reviewers, coordinator = [], [], ""
+
+    # mandatory reviewers/verifier whenever agents run (§267)
+    verifier = ""
+    if mode != "deterministic":
+        verifier = "platform-verifier"
+        if "platform-evidence-reviewer" not in reviewers:
+            reviewers.insert(0, "platform-evidence-reviewer")
+        if signal.security_sensitive \
+                and "platform-security-reviewer" not in reviewers:
+            reviewers.append("platform-security-reviewer")
+            reasons.append("security-sensitive → security reviewer")
+
+    if mode == "debate":
+        reviewers.append("platform-debate-referee")
+    if not signal.evidence_available or signal.evidence_completeness < 0.5:
+        reasons.append("evidence incomplete — expect named unresolved, "
+                       "not guesses")
+    if signal.expected_cost == "high" or signal.expected_token_cost == "high":
+        reasons.append("high expected cost — deterministic-first "
+                       "mandated")
+    if signal.freshness in ("stale", "unknown"):
+        reasons.append(f"freshness={signal.freshness} — freshness "
+                       "evidence required")
+
+    agents = ([coordinator] if coordinator else []) + specialists \
+        + reviewers + ([verifier] if verifier else [])
+    return {
+        "mode": mode,
+        "coordinator": coordinator,
+        "specialists": specialists,
+        "reviewers": reviewers,
+        "verifier": verifier,
+        "dag": _dag(mode, coordinator, specialists, reviewers, verifier,
+                    signal.production),
+        "budget": _budget(signal, mode),
+        "reasons": reasons or [("deterministic-first: no rule forced "
+                                "an agentic mode")],
+        "fallbacks": fallbacks,
+        "agents": agents,          # §82 compat: flattened dispatch list
+        "signal": {k: getattr(signal, k)
+                   for k in signal.__dataclass_fields__},
+    }
+
+
+def validate_routing(routes_path: str | Path | None = None) -> dict[str, Any]:
+    """§91 — every agent referenced by routing.yaml AND by the
+    orchestration loops must resolve; unknown refs are drift, not
+    missing features. Also lints delegation edges in the roster."""
+    from platformforge.agents.orchestrator import load_loops
+    from platformforge.agents.roster import AGENTS, resolve
+    problems: list[str] = []
+    routes = load_routes(routes_path)
+    for i, r in enumerate(routes):
+        for key in ("agents", "add_specialists", "add_reviewers",
+                    "coordinator"):
+            ref = r.get(key)
+            refs = [ref] if isinstance(ref, str) else (ref or [])
+            for a in refs:
+                if isinstance(a, str) and resolve(a) is None:
+                    problems.append(
+                        f"route[{i}] {r.get('name', '?')} references "
+                        f"missing agent {a!r}")
+        when = r.get("when", {})
+        for f in when:
+            if f not in TaskSignal.__dataclass_fields__:
+                problems.append(f"route[{i}] {r.get('name', '?')} uses "
+                                f"unknown signal {f!r}")
+    for lname, loop in load_loops().items():
+        for st in loop.get("stages", []):
+            a = st.get("agent")
+            if a and a != "human-gate" and resolve(a) is None:
+                problems.append(f"loop {lname} stage {st.get('id')} "
+                                f"references missing agent {a!r}")
+    for a in AGENTS.values():
+        for ref in tuple(a.delegates_to) + tuple(a.reviewers) + \
+                ((a.verifier,) if a.verifier else ()):
+            if resolve(ref) is None:
+                problems.append(f"{a.name} references missing {ref!r}")
+        mode_err = a.role not in ("orchestrator", "planner",
+                                  "coordinator", "specialist",
+                                  "executor", "reviewer", "critic",
+                                  "referee", "verifier", "guardian")
+        if mode_err:
+            problems.append(f"{a.name} bad role {a.role!r}")
+    return {"ok": not problems, "problems": problems,
+            "routes": len(routes), "agents": len(AGENTS)}

platformforge/rtk/__init__.py

@@ -0,0 +1,9 @@
+"""RTK — first-party command-output intelligence.
+
+Tools dump thousands of lines; agents consume the compact form. Raw output is
+preserved in the artifact store, expandable on demand.
+"""
+
+from platformforge.rtk.compact import CompactResult, compact_output, detect_command
+
+__all__ = ["CompactResult", "compact_output", "detect_command"]

platformforge/rtk/compact.py

@@ -0,0 +1,127 @@
+"""RTK compaction — turn raw command output into a bounded structure.
+
+The agent consumes the compact result; raw output is preserved out-of-context
+in the artifact store and can be expanded by id/section/line range.
+"""
+
+from __future__ import annotations
+
+import json
+import shlex
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+from platformforge.core.store import ArtifactStore, ref
+from platformforge.rtk.parsers import PARSERS, fallback
+
+MAX_INTERESTING = 200
+MAX_LINES_INLINE = 400
+
+
+@dataclass
+class CompactResult:
+    command: str
+    exit_code: int = 0
+    summary: dict[str, Any] = field(default_factory=dict)
+    errors: list[Any] = field(default_factory=list)
+    warnings: list[Any] = field(default_factory=list)
+    changed: list[Any] = field(default_factory=list)
+    interesting: list[Any] = field(default_factory=list)
+    omitted: int = 0
+    raw_artifact: str = ""
+    truncated: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def detect_command(command: str) -> str:
+    """Map an argv string to a parser key — longest prefix wins."""
+    toks = shlex.split(command) if isinstance(command, str) else list(command)
+    if not toks:
+        return ""
+    base = Path(toks[0]).name
+    candidates = [" ".join([base] + toks[1:i]) for i in
+                  range(min(3, len(toks)), 0, -1)]
+    for cand in candidates:
+        if cand in PARSERS:
+            return cand
+    if base in PARSERS:
+        return base
+    return ""
+
+
+def compact_output(command: str, output: str, exit_code: int = 0,
+                   store: ArtifactStore | None = None,
+                   max_inline_lines: int = MAX_LINES_INLINE) -> CompactResult:
+    lines = output.splitlines()
+    raw_ref = ""
+    if store is not None:
+        from platformforge.core.redaction import redact_text
+        sha = store.put_text(redact_text(output),
+                             meta={"command": command})
+        raw_ref = ref(sha)
+
+    key = detect_command(command)
+    parser = PARSERS.get(key, fallback)
+    parts = parser(lines)
+
+    omitted = max(0, len(lines) - max_inline_lines)
+    res = CompactResult(
+        command=command, exit_code=exit_code,
+        summary=parts.get("summary", {}),
+        errors=parts.get("errors", [])[:MAX_INTERESTING],
+        warnings=parts.get("warnings", [])[:MAX_INTERESTING],
+        changed=parts.get("changed", [])[:MAX_INTERESTING],
+        interesting=parts.get("interesting", [])[:MAX_INTERESTING],
+        omitted=omitted, raw_artifact=raw_ref,
+        truncated=len(lines) > max_inline_lines,
+    )
+    if res.truncated and not res.raw_artifact:
+        res.summary["truncated_note"] = (
+            "output truncated; rerun with a store to keep raw artifact")
+    return res
+
+
+def tool_economy_receipt(command: str, res: CompactResult,
+                         raw_bytes: int | None = None,
+                         expanded_bytes: int = 0) -> dict[str, Any]:
+    """§110 — measured tool economy: what the raw was, what the model
+    consumed, what expand-on-demand pulled."""
+    return {"schema": "platformforge/tool-economy-receipt/v1",
+            "command": command,
+            "raw_bytes": raw_bytes,
+            "compact_bytes": len(compact_json(res).encode()),
+            "expanded_bytes": expanded_bytes,
+            "raw_artifact": res.raw_artifact or None,
+            "truncated": res.truncated,
+            "note": "compact is the default surface; raw preserved as "
+                    "artifact; expand on demand (§107–109)"}
+
+
+def expand(store: ArtifactStore, raw_artifact: str,
+           start: int | None = None, end: int | None = None,
+           pattern: str | None = None) -> dict[str, Any]:
+    """Lazy expansion of the preserved raw output."""
+    sha = raw_artifact.removeprefix("artifact://sha256/")
+    text = store.get_text(sha)
+    if text is None:
+        return {"error": "artifact not found", "artifact": raw_artifact}
+    from platformforge.core.redaction import redact_text
+    lines = redact_text(text).splitlines()  # defense in depth on read-back
+    if pattern:
+        import re
+        rx = re.compile(pattern)
+        hits = [i for i, l in enumerate(lines) if rx.search(l)]
+        win = sorted({j for i in hits for j in
+                      range(max(0, i - 2), min(len(lines), i + 3))})
+        return {"lines": [f"{j + 1}: {lines[j]}" for j in win],
+                "total": len(lines)}
+    s, e = start or 0, end if end is not None else len(lines)
+    return {"lines": [f"{i + 1}: {l}" for i, l in
+                      enumerate(lines[s:e], start=s)], "total": len(lines)}
+
+
+def compact_json(res: CompactResult) -> str:
+    return json.dumps(res.to_dict(), indent=2, default=str)