platformforge 0.1.0__py3-none-any.whl

platformforge/distribution/models.py

@@ -0,0 +1,80 @@
+"""Versioned contracts for portable distribution."""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+DIST_SCHEMA = "platformforge/distribution-manifest/v1"
+INSTALL_PLAN_SCHEMA = "platformforge/install-plan/v1"
+INSTALL_RECEIPT_SCHEMA = "platformforge/install-receipt/v1"
+
+@dataclass(frozen=True)
+class ManagedAsset:
+    path: str
+    sha256: str
+    owner: str = "platformforge"
+    kind: str = "asset"
+
+@dataclass
+class DistributionManifest:
+    distribution_id: str
+    platformforge_version: str
+    source_sha: str = ""
+    profile: str = "agentic"
+    hosts: list[str] = field(default_factory=list)
+    capabilities: list[str] = field(default_factory=list)
+    assets: list[ManagedAsset] = field(default_factory=list)
+    offline: bool = True
+    schema: str = DIST_SCHEMA
+
+    def to_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        d["assets"] = [asdict(x) for x in self.assets]
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> DistributionManifest:
+        return cls(
+            distribution_id=d["distribution_id"],
+            platformforge_version=d["platformforge_version"],
+            source_sha=d.get("source_sha", ""),
+            profile=d.get("profile", "agentic"),
+            hosts=list(d.get("hosts", [])),
+            capabilities=list(d.get("capabilities", [])),
+            assets=[ManagedAsset(**x) for x in d.get("assets", [])],
+            offline=bool(d.get("offline", True)),
+            schema=d.get("schema", DIST_SCHEMA),
+        )
+
+@dataclass
+class InstallPlan:
+    target: str
+    profile: str
+    hosts: list[str]
+    creates: list[str] = field(default_factory=list)
+    identical: list[str] = field(default_factory=list)
+    managed_updates: list[str] = field(default_factory=list)
+    conflicts: list[str] = field(default_factory=list)
+    network_required: bool = False
+    schema: str = INSTALL_PLAN_SCHEMA
+
+    @property
+    def safe(self) -> bool:
+        return not self.conflicts
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self) | {"safe": self.safe}
+
+@dataclass
+class InstallReceipt:
+    distribution_id: str
+    platformforge_version: str
+    source_sha: str
+    target: str
+    profile: str
+    hosts: list[str]
+    files: dict[str, str]
+    schema: str = INSTALL_RECEIPT_SCHEMA
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)

platformforge/distribution/service.py

@@ -0,0 +1,225 @@
+"""Plan-first, ownership-aware portable install lifecycle."""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from collections.abc import Iterable
+from pathlib import Path
+
+from platformforge import __version__
+from platformforge.agents.mirrors import expected as expected_agent_mirrors
+from platformforge.distribution.models import (
+    DistributionManifest,
+    InstallPlan,
+    InstallReceipt,
+    ManagedAsset,
+)
+from platformforge.resources import data_path
+from platformforge.workspace.service import ensure_workspace
+
+PF_DIR = ".platformforge"
+INSTALL_RECEIPT = "install-receipt.json"
+DIST_MANIFEST = "distribution-manifest.json"
+HOSTS = ("agents", "claude", "codex", "devin")
+
+def _sha(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+def _safe_target(root: Path, rel: str) -> Path:
+    if Path(rel).is_absolute() or ".." in Path(rel).parts:
+        raise ValueError("PF-DIST-PATH-ESCAPE")
+    root = root.resolve()
+    dest = (root / rel).resolve()
+    if dest != root and root not in dest.parents:
+        raise ValueError("PF-DIST-PATH-ESCAPE")
+    return dest
+
+def _host_prefix(host: str) -> str:
+    return {"agents": ".agents/agents/", "claude": ".claude/agents/",
+            "codex": ".codex/agents/", "devin": ".devin/agents/"}[host]
+
+def portable_assets(hosts: Iterable[str]) -> dict[str, bytes]:
+    hosts = tuple(dict.fromkeys(hosts))
+    bad = set(hosts) - set(HOSTS)
+    if bad:
+        raise ValueError("PF-DIST-UNKNOWN-HOST:" + ",".join(sorted(bad)))
+    rendered = expected_agent_mirrors(Path("."))
+    out: dict[str, bytes] = {}
+    prefixes = tuple(_host_prefix(h) for h in hosts)
+    for rel, text in rendered.items():
+        if rel.startswith(prefixes):
+            out[rel] = text.encode()
+    # Portable domain skills are package data. Codex consumes the generic
+    # .agents skill surface alongside .codex/agents; Claude/Devin receive
+    # their native skill directories. One canonical skill body is copied.
+    skill_root = data_path("portable_skills")
+    if skill_root.is_dir():
+        for skill_dir in sorted(skill_root.iterdir()):
+            skill_file = skill_dir / "SKILL.md"
+            if not skill_file.is_file():
+                continue
+            body = skill_file.read_bytes()
+            if "agents" in hosts or "codex" in hosts:
+                out[f".agents/skills/{skill_dir.name}/SKILL.md"] = body
+            if "claude" in hosts:
+                out[f".claude/skills/{skill_dir.name}/SKILL.md"] = body
+            if "devin" in hosts:
+                out[f".devin/skills/{skill_dir.name}/SKILL.md"] = body
+
+    # Workspace-local MCP hint: never edits global host config.
+    out[f"{PF_DIR}/mcp.json"] = json.dumps({
+        "schema": "platformforge/mcp-bootstrap/v1",
+        "command": ["platformforge-mcp"],
+        "scope": "workspace-local",
+    }, indent=2, sort_keys=True).encode() + b"\n"
+    return out
+
+def _distribution(profile: str, hosts: list[str], assets: dict[str, bytes],
+                  source_sha: str = "") -> DistributionManifest:
+    records = [ManagedAsset(path=p, sha256=_sha(b),
+                            kind="host-mirror" if "/agents/" in p else "config")
+               for p, b in sorted(assets.items())]
+    semantic = json.dumps({
+        "version": __version__, "profile": profile, "hosts": hosts,
+        "assets": [(x.path, x.sha256) for x in records],
+    }, sort_keys=True).encode()
+    return DistributionManifest(
+        distribution_id="sha256:" + _sha(semantic),
+        platformforge_version=__version__,
+        source_sha=source_sha,
+        profile=profile,
+        hosts=hosts,
+        capabilities=["platform.inspect", "platform.graph", "platform.judge",
+                      "platform.route", "platform.mcp"],
+        assets=records,
+        offline=True,
+    )
+
+def plan_install(
+    target: str | Path,
+    profile: str = "agentic",
+    hosts: list[str] | None = None,
+) -> tuple[InstallPlan, DistributionManifest, dict[str, bytes]]:
+    root = Path(target).resolve()
+    hosts = hosts or ["agents"]
+    assets = portable_assets(hosts)
+    manifest = _distribution(profile, hosts, assets)
+    receipt_path = root / PF_DIR / INSTALL_RECEIPT
+    old = {}
+    if receipt_path.is_file():
+        try:
+            old = json.loads(receipt_path.read_text()).get("files", {})
+        except (OSError, ValueError):
+            old = {}
+    creates, identical, managed_updates, conflicts = [], [], [], []
+    for rel, data in sorted(assets.items()):
+        dest = _safe_target(root, rel)
+        want = _sha(data)
+        if not dest.exists():
+            creates.append(rel)
+            continue
+        current = _sha(dest.read_bytes())
+        if current == want:
+            identical.append(rel)
+        elif old.get(rel) == current:
+            managed_updates.append(rel)
+        else:
+            conflicts.append(rel)
+    return InstallPlan(str(root), profile, hosts, creates, identical,
+                       managed_updates, conflicts, network_required=False), manifest, assets
+
+def apply_install(target: str | Path, profile: str = "agentic",
+                  hosts: list[str] | None = None, dry_run: bool = False) -> dict:
+    plan, manifest, assets = plan_install(target, profile, hosts)
+    if dry_run:
+        return {"plan": plan.to_dict(), "distribution": manifest.to_dict()}
+    if not plan.safe:
+        return {"refusal": "PF-DIST-CONFLICT", "conflicts": plan.conflicts,
+                "unlock": "preserve/rename modified files or choose another host"}
+    root = Path(target).resolve()
+    staged: list[tuple[Path, Path]] = []
+    try:
+        for rel in plan.creates + plan.managed_updates:
+            dest = _safe_target(root, rel)
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            tmp = dest.with_name(dest.name + ".platformforge-stage")
+            tmp.write_bytes(assets[rel])
+            if _sha(tmp.read_bytes()) != _sha(assets[rel]):
+                raise OSError("PF-DIST-STAGE-HASH")
+            staged.append((tmp, dest))
+        for tmp, dest in staged:
+            os.replace(tmp, dest)
+        ws = ensure_workspace(root, profile=profile, hosts=plan.hosts)
+        pf = root / PF_DIR
+        manifest_path = pf / DIST_MANIFEST
+        manifest_path.write_text(json.dumps(manifest.to_dict(), indent=2, sort_keys=True) + "\n")
+        files = {rel: _sha(_safe_target(root, rel).read_bytes()) for rel in assets}
+        receipt = InstallReceipt(
+            manifest.distribution_id, __version__, manifest.source_sha,
+            str(root), profile, plan.hosts, files,
+        )
+        (pf / INSTALL_RECEIPT).write_text(json.dumps(receipt.to_dict(), indent=2, sort_keys=True) + "\n")
+        return {"status": "committed", "plan": plan.to_dict(),
+                "workspace": ws.to_dict(), "receipt": receipt.to_dict()}
+    except Exception:
+        for tmp, _ in staged:
+            tmp.unlink(missing_ok=True)
+        raise
+
+def uninstall(target: str | Path, purge: bool = False) -> dict:
+    root = Path(target).resolve()
+    receipt_path = root / PF_DIR / INSTALL_RECEIPT
+    if not receipt_path.is_file():
+        return {"refusal": "PF-DIST-NOT-INSTALLED"}
+    rec = json.loads(receipt_path.read_text())
+    removed, preserved = [], []
+    for rel, installed_hash in rec.get("files", {}).items():
+        dest = _safe_target(root, rel)
+        if not dest.exists():
+            continue
+        if _sha(dest.read_bytes()) == installed_hash:
+            dest.unlink()
+            removed.append(rel)
+        else:
+            preserved.append(rel)
+    for name in (DIST_MANIFEST, INSTALL_RECEIPT):
+        (root / PF_DIR / name).unlink(missing_ok=True)
+    if purge:
+        ws = root / PF_DIR / "workspace.json"
+        ws.unlink(missing_ok=True)
+    return {"status": "uninstalled", "removed": removed,
+            "preserved_modified": preserved, "purged": purge}
+
+def upgrade(target: str | Path, profile: str | None = None,
+            hosts: list[str] | None = None, dry_run: bool = False) -> dict:
+    root = Path(target).resolve()
+    recp = root / PF_DIR / INSTALL_RECEIPT
+    if not recp.is_file():
+        return {"refusal": "PF-DIST-NOT-INSTALLED",
+                "unlock": "platformforge install ."}
+    old = json.loads(recp.read_text())
+    profile = profile or old.get("profile", "agentic")
+    hosts = hosts or list(old.get("hosts", ["agents"]))
+    return apply_install(root, profile=profile, hosts=hosts, dry_run=dry_run)
+
+def doctor(target: str | Path) -> dict:
+    root = Path(target).resolve()
+    pf = root / PF_DIR
+    recp, manp = pf / INSTALL_RECEIPT, pf / DIST_MANIFEST
+    checks = {"workspace": (pf / "workspace.json").is_file(),
+              "receipt": recp.is_file(), "manifest": manp.is_file()}
+    drift, missing = [], []
+    if recp.is_file():
+        rec = json.loads(recp.read_text())
+        checks["version_match"] = rec.get("platformforge_version") == __version__
+        for rel, expected_hash in rec.get("files", {}).items():
+            p = _safe_target(root, rel)
+            if not p.is_file():
+                missing.append(rel)
+            elif _sha(p.read_bytes()) != expected_hash:
+                drift.append(rel)
+    checks["assets"] = not missing and not drift
+    state = "healthy" if all(checks.values()) else "warning"
+    return {"state": state, "checks": checks, "missing": missing,
+            "drift": drift, "workspace_local": True}

platformforge/economy/__init__.py

@@ -0,0 +1,27 @@
+"""Economy engine — cheap deterministic work first, expensive probabilistic
+work last, everything ledgered."""
+
+from platformforge.economy.budget import BudgetEnvelope, Limit
+from platformforge.economy.engine import COST_ORDER, EconomyEngine
+from platformforge.economy.ledger import (
+    EconomyLedger,
+    ProviderCallEntry,
+    TokenAccounting,
+    ToolUsageEntry,
+    unified_view,
+)
+from platformforge.economy.plan import EconomyPlan, PlanSection
+
+__all__ = [
+    "COST_ORDER",
+    "BudgetEnvelope",
+    "EconomyEngine",
+    "EconomyLedger",
+    "EconomyPlan",
+    "Limit",
+    "PlanSection",
+    "ProviderCallEntry",
+    "TokenAccounting",
+    "ToolUsageEntry",
+    "unified_view",
+]

platformforge/economy/bench.py

@@ -0,0 +1,66 @@
+"""QPT benchmark suite (cycle 2.1 §43–46) — fixed task corpus.
+
+Each case dir carries `case.yaml` (id, task, domain, budget, versions) and a
+`fixture/`. Every task runs the SAME pipeline: analyze → facts → index →
+full vs TokenSave-packed envelopes → same judge, same rules, same versions.
+Emits per-task receipts plus an aggregate verdict; a machine-readable
+receipt is written when `out` is given.
+"""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from platformforge.economy.qpt import quality_per_token
+from platformforge.tokensave.budget import Budget
+from platformforge.tokensave.index import SearchIndex
+
+
+def _analyze(domain: str, fixture: Path):
+    from platformforge.lab.runner import _ANALYZERS, _resolve
+    fn = _resolve(_ANALYZERS[domain])
+    return fn(fixture)
+
+
+def run_qpt_bench(bench_dir: str | Path | None = None) -> dict[str, Any]:
+    from platformforge.resources import data_path
+    root = Path(bench_dir) if bench_dir else data_path("evals", "qpt-bench")
+    results: list[dict[str, Any]] = []
+    for case_dir in sorted(p for p in root.iterdir() if p.is_dir()):
+        case = yaml.safe_load((case_dir / "case.yaml").read_text()) or {}
+        fixture = case_dir / case.get("fixture", "fixture")
+        out = _analyze(case["domain"], fixture)
+        facts = out.get("facts", [])
+        with tempfile.TemporaryDirectory() as td, SearchIndex(Path(td) / "i.db") as idx:
+            idx.index_workspace(fixture)
+            rep = quality_per_token(
+                facts_full=facts, findings_full=[],
+                index=idx, task=case.get("task", case_dir.name),
+                versions=case.get("versions"),
+                budget=Budget(input_budget=case.get("budget", 50_000)))
+        results.append({"id": case.get("id", case_dir.name),
+                        "task": case.get("task"),
+                        "domain": case["domain"],
+                        "facts": len(facts),
+                        "verdict": rep.get("verdict"),
+                        "token_reduction": rep.get("economy", rep)
+                            .get("token_reduction"),
+                        "quality": rep.get("quality"),
+                        "receipt": rep})
+    agg = {
+        "tasks": len(results),
+        "verdicts": {v: sum(1 for r in results if r["verdict"] == v)
+                     for v in ("beneficial", "no_reduction",
+                               "optimization_not_beneficial", "refused")},
+        "min_finding_recall": min(
+            (r["quality"]["finding_recall"] for r in results if r["quality"]),
+            default=None),
+        "min_evidence_recall": min(
+            (r["quality"]["evidence_recall"] for r in results if r["quality"]),
+            default=None),
+    }
+    return {"cases": results, "aggregate": agg}

platformforge/economy/budget.py

@@ -0,0 +1,198 @@
+"""BudgetEnvelope (§12–24) — the canonical spend contract.
+
+Eleven dimensions (§13), each with an independent soft/hard limit
+(§14–16). A hard-limit overrun is never silent — the verdict carries
+PF-ECONOMY-BUDGET-EXHAUSTED plus the action the caller must take
+(§17–18). `protected_items` name what a reduce-scope action may never
+drop (§19); VERIFY/SECURITY/CONTRACT phases cannot be budget-removed
+(§23).
+
+The envelope is the single contract — TokenSave's `check_input_budget`
+implements the context dimension's reduce/refuse/escalate detail; the
+envelope is where every dimension (incl. provider calls, fanout,
+wall time, money) is governed together.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+SCHEMA = "platformforge/budget-envelope/v1"
+
+DIMENSIONS = ("context_bytes", "input_tokens", "output_tokens",
+              "model_calls", "tool_calls", "provider_calls", "agents",
+              "fanout", "parallelism", "wall_time", "money")
+
+# §21/§22 — pipeline phases + the SDD phases they map to.
+PHASES = ("discover", "analyze", "review", "debate", "verify", "report")
+SDD_PHASES = ("DISCOVER", "DEFINE", "DESIGN", "CONTRACT", "PLAN",
+              "BUILD", "REVIEW", "VERIFY", "SHIP")
+PROTECTED_PHASES = ("VERIFY", "SECURITY", "CONTRACT")  # §23
+
+ROLES = ("specialist", "reviewer", "critic", "referee", "verifier")
+
+# §19 — reduce-scope may never drop these.
+PROTECTED_ITEMS = ("critical_evidence", "unresolved_markers",
+                   "security_findings", "policy_failures",
+                   "rollback_info", "acceptance_criteria")
+
+# §18 — what a run does when budget is insufficient.
+ACTIONS = ("reduce_scope", "reuse_cache", "switch_deterministic",
+           "request_escalation", "return_partial", "refuse")
+
+EXHAUSTED = "PF-ECONOMY-BUDGET-EXHAUSTED"
+
+
+@dataclass
+class Limit:
+    """soft = target (may escalate via policy); hard = never exceeded."""
+    soft: float | None = None
+    hard: float | None = None
+
+    @classmethod
+    def from_dict(cls, d: Any) -> Limit:
+        if isinstance(d, (int, float)):
+            return cls(hard=float(d))
+        return cls(soft=d.get("soft"), hard=d.get("hard"))
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"soft": self.soft, "hard": self.hard}
+
+
+@dataclass
+class BudgetVerdict:
+    decision: str                  # ok|soft_exceeded|hard_exceeded
+    dimension: str = ""
+    spent: float = 0.0
+    limit: float | None = None
+    action: str = ""               # §18 action for the caller
+    code: str = ""
+    detail: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class BudgetEnvelope:
+    """§12 — canonical contract. `limits` keys ⊆ DIMENSIONS."""
+    schema: str = SCHEMA
+    limits: dict[str, Limit] = field(default_factory=dict)
+    phase_budgets: dict[str, dict[str, Limit]] = field(default_factory=dict)
+    role_budgets: dict[str, dict[str, Limit]] = field(default_factory=dict)
+    protected_items: list[str] = field(
+        default_factory=lambda: list(PROTECTED_ITEMS))
+    overrun_action: str = "refuse"     # §18 default
+    soft_policy: str = "warn"          # warn|escalate — soft may be crossed
+    created_at: float = field(default_factory=time.time)
+
+    def __post_init__(self) -> None:
+        bad = set(self.limits) - set(DIMENSIONS)
+        if bad:
+            raise ValueError(f"unknown budget dimensions {sorted(bad)}")
+        for p in self.phase_budgets:
+            if p not in PHASES and p not in SDD_PHASES:
+                raise ValueError(f"unknown phase {p!r}")
+            bad = set(self.phase_budgets[p]) - set(DIMENSIONS)
+            if bad:
+                raise ValueError(f"phase {p}: unknown dims {sorted(bad)}")
+        for r in self.role_budgets:
+            if r not in ROLES:
+                raise ValueError(f"unknown role {r!r}")
+            bad = set(self.role_budgets[r]) - set(DIMENSIONS)
+            if bad:
+                raise ValueError(f"role {r}: unknown dims {sorted(bad)}")
+        bad = set(self.protected_items) - set(PROTECTED_ITEMS)
+        if bad:
+            raise ValueError(
+                f"protected_items not in {PROTECTED_ITEMS}: {sorted(bad)}")
+        if self.overrun_action not in ACTIONS:
+            raise ValueError(
+                f"overrun_action {self.overrun_action!r} not in {ACTIONS}")
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> BudgetEnvelope:
+        out = dict(d)
+        out["limits"] = {k: Limit.from_dict(v)
+                         for k, v in out.get("limits", {}).items()}
+        for grp in ("phase_budgets", "role_budgets"):
+            out[grp] = {k: {dk: Limit.from_dict(dv)
+                            for dk, dv in v.items()}
+                        for k, v in out.get(grp, {}).items()}
+        return cls(**{k: v for k, v in out.items()
+                      if k in cls.__dataclass_fields__})
+
+    def to_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        d["limits"] = {k: v.to_dict() for k, v in self.limits.items()}
+        d["phase_budgets"] = {p: {k: v.to_dict() for k, v in lim.items()}
+                              for p, lim in self.phase_budgets.items()}
+        d["role_budgets"] = {r: {k: v.to_dict() for k, v in lim.items()}
+                             for r, lim in self.role_budgets.items()}
+        return d
+
+    def _effective(self, dimension: str, phase: str = "",
+                   role: str = "") -> Limit:
+        """Narrowest applicable limit: role > phase > envelope default."""
+        cand = [self.limits.get(dimension, Limit())]
+        if phase and phase in self.phase_budgets and \
+                dimension in self.phase_budgets[phase]:
+            cand.append(self.phase_budgets[phase][dimension])
+        if role and role in self.role_budgets and \
+                dimension in self.role_budgets[role]:
+            cand.append(self.role_budgets[role][dimension])
+        soft = min((c.soft for c in cand if c.soft is not None),
+                   default=None)
+        hard = min((c.hard for c in cand if c.hard is not None),
+                   default=None)
+        return Limit(soft=soft, hard=hard)
+
+    def check(self, dimension: str, proposed_spend: float,
+              *, phase: str = "", role: str = "") -> BudgetVerdict:
+        """§15–17 — hard is never exceeded; soft crosses with a verdict,
+        never silently."""
+        lim = self._effective(dimension, phase, role)
+        if lim.hard is not None and proposed_spend > lim.hard:
+            return BudgetVerdict(
+                "hard_exceeded", dimension, proposed_spend, lim.hard,
+                action=self.overrun_action, code=EXHAUSTED,
+                detail=f"{dimension} hard limit {lim.hard} "
+                       f"< proposed {proposed_spend}; action="
+                       f"{self.overrun_action}")
+        if lim.soft is not None and proposed_spend > lim.soft:
+            return BudgetVerdict(
+                "soft_exceeded", dimension, proposed_spend, lim.soft,
+                action=self.soft_policy,
+                detail=f"{dimension} soft limit {lim.soft} exceeded "
+                       f"(policy={self.soft_policy})")
+        return BudgetVerdict("ok", dimension, proposed_spend,
+                             lim.hard if lim.hard is not None else lim.soft)
+
+    def reducible(self, item: str) -> bool:
+        """§19 — protected items are never droppable for savings."""
+        return item not in self.protected_items
+
+    def phase_removable(self, phase: str) -> bool:
+        """§23 — protected phases cannot be removed for cost."""
+        return phase.upper() not in PROTECTED_PHASES
+
+
+DEFAULT_PHASE_SPLIT = {
+    "DISCOVER": 0.15, "DEFINE": 0.10, "DESIGN": 0.15, "CONTRACT": 0.05,
+    "PLAN": 0.10, "BUILD": 0.15, "REVIEW": 0.10, "VERIFY": 0.15,
+    "SHIP": 0.05,
+}
+
+
+def phase_budgets(total: float, dimension: str = "input_tokens",
+                  split: dict[str, float] | None = None
+                  ) -> dict[str, dict[str, Limit]]:
+    """§22 — split a dimension total across SDD phases; protected phases
+    keep their floor and are never zeroed by this helper."""
+    split = split or DEFAULT_PHASE_SPLIT
+    out: dict[str, dict[str, Limit]] = {}
+    for phase, frac in split.items():
+        out[phase] = {dimension: Limit(soft=round(total * frac, 3))}
+    return out