platformforge 0.1.0__py3-none-any.whl

platformforge/security/iam.py

@@ -0,0 +1,112 @@
+"""IAM policy → identity graph facts. Statements decompose into
+can_access / assumes edges; wildcards and admin grants are flags for rules."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from platformforge.models.base import stable_id
+
+
+def _stmts(doc: dict[str, Any]) -> list[dict[str, Any]]:
+    out = doc.get("Statement") or []
+    return [s for s in out if isinstance(s, dict)]
+
+
+def _policy_kind(doc: dict[str, Any], stmts: list[dict[str, Any]]) -> str:
+    """§100 — classify the policy shape: trust / identity / resource /
+    SCP / permission boundary / session. Detection is structural, never
+    guessed from filename."""
+    for s in stmts:
+        acts = s.get("Action") or []
+        acts = [acts] if isinstance(acts, str) else acts
+        if "sts:AssumeRole" in acts or "sts:AssumeRoleWithSAML" in acts \
+                or "sts:AssumeRoleWithWebIdentity" in acts:
+            return "trust"
+    if doc.get("PolicyType") == "SCP" or \
+            any("aws:SourceOrgID" in str(s.get("Condition", {}))
+                or s.get("Sid", "").startswith("SCP") for s in stmts):
+        return "scp"
+    if doc.get("PolicyType") == "PermissionsBoundary" or \
+            doc.get("PermissionsBoundary"):
+        return "permission_boundary"
+    if any("Principal" in s for s in stmts):
+        return "resource"
+    return "identity"
+
+
+def analyze_iam_policy(path: str | Path) -> dict[str, Any]:
+    doc = json.loads(Path(path).read_text())
+    name = doc.get("PolicyName") or doc.get("Id") or Path(path).stem
+    stmts = _stmts(doc)
+    ptype = _policy_kind(doc, stmts)
+    edges, principals, resources = [], [], []
+    wildcard_actions = wildcard_resources = public_principals = 0
+    admin = False
+    federated: list[str] = []   # OIDC/SAML providers seen in trust
+    chain_targets: list[str] = []  # roles this policy can assume
+    for s in stmts:
+        effect = s.get("Effect", "Allow")
+        if effect != "Allow":
+            continue
+        actions = s.get("Action") or []
+        actions = [actions] if isinstance(actions, str) else actions
+        res = s.get("Resource") or []
+        res = [res] if isinstance(res, str) else res
+        pr = s.get("Principal") or {}
+        pr_list = []
+        if isinstance(pr, dict):
+            for ptype_k, v in pr.items():
+                vals = v if isinstance(v, list) else [v]
+                for pv in vals:
+                    pr_list.append(pv)
+                    if ptype_k == "Federated":
+                        federated.append(pv)   # OIDC/SAML provider ARN
+        elif isinstance(pr, str):
+            pr_list.append(pr)
+        pr_list = [p if p != "*" else "wildcard-principal" for p in pr_list]
+        public_principals += pr_list.count("wildcard-principal")
+        if "*" in actions or "iam:*" in actions \
+                or ("iam:PassRole" in actions and "*" in res):
+            admin = True
+        wildcard_actions += sum(1 for a in actions if a.endswith("*"))
+        wildcard_resources += sum(1 for r in res if r == "*")
+        principals += pr_list
+        resources += res
+        for p in pr_list:
+            for r in res:
+                dst = r.split(":")[-1][:48] if r != "*" else "wildcard"
+                edges.append({"src_kind": "iam_principal", "src": p,
+                              "dst_kind": "policy", "dst": dst,
+                              "kind": "can_access",
+                              "attrs": {"actions": actions,
+                                        "effect": effect}})
+        for a in actions:
+            if a == "sts:AssumeRole":
+                for r in res:
+                    chain_targets.append(r)
+                    for p in pr_list:
+                        edges.append({"src_kind": "iam_principal", "src": p,
+                                      "dst_kind": "role", "dst": r,
+                                      "kind": "assumes"})
+    attrs = {"policy_name": name, "policy_type": ptype,
+             "statement_count": len(stmts),
+             "principals": sorted(set(principals)),
+             "federated_providers": sorted(set(federated)),
+             "assumable_roles": sorted(set(chain_targets)),
+             "wildcard_actions": wildcard_actions,
+             "wildcard_resources": wildcard_resources,
+             "public_principals": public_principals,
+             "admin_grant": admin,
+             "graph": {"nodes": [{"kind": "policy", "label": name}] +
+                       [{"kind": "iam_principal", "label": p}
+                        for p in sorted(set(principals))] +
+                       [{"kind": "role", "label": r}
+                        for r in sorted(set(chain_targets))],
+                      "edges": edges}}
+    return {"facts": [{"fact_id": stable_id("PF-SEC", "iam", str(path)),
+                       "kind": "security.iam_policy", "source": str(path),
+                       "location": name, "tier": 3, "attrs": attrs}],
+            "counts": {"statements": len(stmts), "edges": len(edges)}}

platformforge/security/identity.py

@@ -0,0 +1,84 @@
+"""§100–101 IAM v2 — identity paths over the graph.
+
+Four questions Graphfy must answer:
+
+  who can become this role?
+  who can access this resource?
+  what workloads use this identity?
+  blast radius of compromising it?
+
+Paths are evidence: every hop cites fact_ids. "No path found" is
+reported, never "no risk" — absence of evidence is named as such.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from platformforge.graph.model import Graph
+
+_ASSUME = {"assumes", "impersonates", "can_access"}
+_WILDCARD = {"wildcard-principal", "wildcard", "*"}
+
+
+def _targets(graph: Graph, name: str, kind: str | None = None) -> set[str]:
+    """Resolve a user-supplied name to node-id candidates: exact id,
+    kind-prefixed id, and any node whose id ends with /name."""
+    cands = {name}
+    if kind:
+        cands.add(f"{kind}/{name}")
+    cands |= {nid for nid in graph.nodes
+              if nid == name or nid.endswith(f"/{name}")}
+    return cands
+
+
+def who_can_become(graph: Graph, role: str) -> dict[str, Any]:
+    """Principals with an `assumes`/`impersonates` edge into `role`."""
+    targets = _targets(graph, role, "role")
+    hits = []
+    for e in graph.edges.values():
+        if e.dst in targets and e.kind in ("assumes", "impersonates"):
+            hits.append({"principal": e.src,
+                         "via": e.kind, "fact_ids": e.source_fact_ids})
+    return {"role": role, "can_become": hits,
+            "count": len(hits),
+            "status": "measured" if hits else "no-path-found"}
+
+
+def who_can_access(graph: Graph, resource: str) -> dict[str, Any]:
+    """Principals/policies with can_access into the resource."""
+    targets = _targets(graph, resource)
+    hits = []
+    for e in graph.edges.values():
+        if e.dst in targets and e.kind in _ASSUME:
+            hits.append({"principal": e.src, "via": e.kind,
+                         "fact_ids": e.source_fact_ids})
+    return {"resource": resource, "can_access": hits, "count": len(hits),
+            "status": "measured" if hits else "no-path-found"}
+
+
+def workloads_using_identity(graph: Graph, identity: str) -> dict[str, Any]:
+    """Workloads with `assumes`/`uses_secret` into the identity."""
+    targets = _targets(graph, identity)
+    hits = []
+    for e in graph.edges.values():
+        if e.dst in targets and \
+                e.kind in ("assumes", "uses_secret") and \
+                e.src.startswith(("workload/", "pod/")):
+            hits.append({"workload": e.src, "via": e.kind,
+                         "fact_ids": e.source_fact_ids})
+    return {"identity": identity, "workloads": hits, "count": len(hits),
+            "status": "measured" if hits else "no-path-found"}
+
+
+def compromise_blast(graph: Graph, identity: str) -> dict[str, Any]:
+    """Blast radius if `identity` is compromised — everything reachable
+    via assumes/can_access/uses_secret downstream."""
+    from platformforge.graph.query import blast_radius
+    targets = _targets(graph, identity)
+    nid = next(iter(targets & set(graph.nodes)), identity)
+    br = blast_radius(graph, nid)
+    return {"identity": identity, "blast": br,
+            "status": "measured" if br["nodes"] else "no-path-found",
+            "note": "compromise blast = transitive reachability; "
+                    "not a likelihood estimate"}

platformforge/security/kyverno.py

@@ -0,0 +1,106 @@
+"""§96–97 Kyverno + admission policy analysis — version-aware.
+
+Legacy `Policy`/`ClusterPolicy` vs modern CEL-based types
+(`ValidatingPolicy`, `MutatingPolicy`, `GeneratingPolicy`,
+`ImageValidatingPolicy`, `PolicyException`). Whether a type is
+deprecated depends on the Kyverno version — without a declared version
+the finding is `version_unresolved`, never a guess.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from platformforge.models.base import stable_id
+
+KYVERNO_KINDS = {"Policy", "ClusterPolicy", "ValidatingPolicy",
+                 "MutatingPolicy", "GeneratingPolicy",
+                 "ImageValidatingPolicy", "PolicyException",
+                 "CleanupPolicy", "ValidatingAdmissionPolicy",
+                 "ValidatingAdmissionPolicyBinding"}
+
+# legacy kinds whose deprecation depends on declared engine version
+LEGACY_KINDS = {"Policy", "ClusterPolicy"}
+CEL_KINDS = {"ValidatingPolicy", "MutatingPolicy", "GeneratingPolicy",
+             "ImageValidatingPolicy", "ValidatingAdmissionPolicy",
+             "ValidatingAdmissionPolicyBinding"}
+
+_GATEKEEPER_TMPL = {"ConstraintTemplate", "Constraint"}
+
+
+def analyze_kyverno(path: str | Path,
+                    kyverno_version: str | None = None) -> dict[str, Any]:
+    root = Path(path)
+    files = (sorted(root.rglob("*.yaml")) + sorted(root.rglob("*.yml"))) \
+        if root.is_dir() else [root]
+    facts: list[dict[str, Any]] = []
+    unresolved: list[dict[str, Any]] = []
+    for f in files:
+        try:
+            docs = list(yaml.safe_load_all(f.read_text()))
+        except (OSError, yaml.YAMLError):
+            continue
+        for doc in docs:
+            if not isinstance(doc, dict):
+                continue
+            kind, api = doc.get("kind", ""), str(doc.get("apiVersion", ""))
+            meta = doc.get("metadata") or {}
+            name = meta.get("name", "?")
+            loc = f"{f}::{name}"
+
+            if "kyverno.io" in api or "policies.kyverno.io" in api \
+                    or kind in KYVERNO_KINDS - _GATEKEEPER_TMPL:
+                spec = doc.get("spec") or {}
+                rules = spec.get("rules") or []
+                mode = spec.get("validationFailureAction") or \
+                    spec.get("failurePolicy")
+                is_legacy = kind in LEGACY_KINDS
+                attrs = {"policy_kind": kind, "api": api,
+                         "rules": len(rules),
+                         "failure_action": mode,
+                         "background": spec.get("background"),
+                         "legacy_type": is_legacy,
+                         "cel_type": kind in CEL_KINDS,
+                         "kyverno_version": kyverno_version}
+                if is_legacy and kyverno_version is None:
+                    unresolved.append({
+                        "capability": "kyverno-version-check",
+                        "location": loc,
+                        "reason": "legacy kind without declared kyverno "
+                                  "version — deprecation is version-bound",
+                        "unlock": "pass kyverno_version to analyze_kyverno"})
+                if is_legacy and kyverno_version:
+                    try:
+                        major = int(str(kyverno_version).lstrip("v")
+                                    .split(".")[0])
+                        attrs["legacy_deprecated"] = major >= 2 \
+                            or (major == 1 and
+                                int(str(kyverno_version)
+                                    .split(".")[1]) >= 13)
+                    except (ValueError, IndexError):
+                        attrs["legacy_deprecated"] = None
+                facts.append({
+                    "fact_id": stable_id("PF-KYV", kind, loc),
+                    "kind": "kyverno.policy", "source": str(f),
+                    "location": loc, "tier": 3, "attrs": {
+                        **attrs, "graph": {
+                            "nodes": [{"kind": "admission_policy",
+                                       "label": name}], "edges": []}}})
+            elif kind in _GATEKEEPER_TMPL or \
+                    "templates.gatekeeper.sh" in api or \
+                    "constraints.gatekeeper.sh" in api:
+                facts.append({
+                    "fact_id": stable_id("PF-GK", kind, loc),
+                    "kind": "gatekeeper.constraint", "source": str(f),
+                    "location": loc, "tier": 3,
+                    "attrs": {"gatekeeper_kind": kind, "api": api,
+                              "rego": bool(doc.get("spec", {})
+                                           .get("targets")),
+                              "graph": {"nodes": [{"kind": "admission_policy",
+                                                   "label": name}],
+                                        "edges": []}}})
+    return {"facts": facts, "unresolved": unresolved,
+            "counts": {"facts": len(facts)}}

platformforge/security/sbom.py

@@ -0,0 +1,59 @@
+"""SBOM ingest — CycloneDX and SPDX JSON → component facts. Optional offline
+CVE match against a caller-provided vuln list (never a network call)."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from platformforge.models.base import stable_id
+
+
+def analyze_sbom(path: str | Path,
+                 vuln_db: dict[str, list[str]] | None = None) -> dict[str, Any]:
+    """vuln_db: {"name@version": ["CVE-..."]} supplied by caller — offline."""
+    doc = json.loads(Path(path).read_text())
+    comps: list[dict[str, Any]] = []
+    fmt = "unknown"
+    if doc.get("bomFormat") == "CycloneDX":
+        fmt = "cyclonedx"
+        for c in doc.get("components") or []:
+            comps.append({"name": c.get("name"), "version": c.get("version"),
+                          "type": c.get("type"),
+                          "licenses": [l.get("license", {}).get("id")
+                                       or l.get("license", {}).get("name")
+                                       for l in c.get("licenses") or []],
+                          "purl": c.get("purl"),
+                          "supplier": (c.get("supplier") or {}).get("name")})
+    elif doc.get("spdxVersion"):
+        fmt = "spdx"
+        for p in doc.get("packages") or []:
+            comps.append({"name": p.get("name"), "version": p.get("versionInfo"),
+                          "type": p.get("primaryPackagePurpose"),
+                          "licenses": [p.get("licenseConcluded")]
+                          if p.get("licenseConcluded") else [],
+                          "supplier": p.get("supplier")})
+    vulns: dict[str, list[str]] = {}
+    for c in comps:
+        key = f"{c['name']}@{c['version']}"
+        if vuln_db and key in vuln_db:
+            vulns[key] = vuln_db[key]
+    copyleft = [c["name"] for c in comps
+                if any(l and ("GPL" in l or "AGPL" in l or "SSPL" in l)
+                       for l in c.get("licenses", []))]
+    no_license = [c["name"] for c in comps if not c.get("licenses")]
+    facts = [{"fact_id": stable_id("PF-SEC", "sbom", str(path)),
+              "kind": "security.sbom", "source": str(path), "tier": 3,
+              "location": str(path),
+              "attrs": {"format": fmt, "component_count": len(comps),
+                        "components": comps[:500],  # bounded
+                        "truncated": len(comps) > 500,
+                        "vulnerabilities": vulns,
+                        "vuln_count": sum(len(v) for v in vulns.values()),
+                        "copyleft_components": copyleft,
+                        "unlicensed_components": no_license,
+                        "graph": {
+                            "nodes": [{"kind": "sbom", "label": str(path)}],
+                            "edges": []}}}]
+    return {"facts": facts, "counts": {"components": len(comps)}}

platformforge/security/scan.py

@@ -0,0 +1,63 @@
+"""Secret scanning — detect credential patterns in files. Reports locations
+and pattern labels only; values are never emitted (redaction markers only)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from platformforge.core.redaction import PATTERNS
+from platformforge.models.base import stable_id
+
+# Dogfood RW-5: tool/test caches (.pytest-tmp holds generated keys,
+# .tokensave/.rtk hold binaries) — scanning them produces pure noise.
+_SKIP_DIRS = {".git", ".venv", "node_modules", ".platformforge",
+              "__pycache__", "dist", ".pytest-tmp", ".pytest_cache",
+              ".mypy_cache", ".ruff_cache", ".rtk", ".tokensave"}
+_SKIP_EXT = {".png", ".jpg", ".jpeg", ".gif", ".zip", ".gz", ".whl",
+             ".so", ".pyc", ".jar", ".exe", ".dll", ".dylib", ".bin",
+             ".db", ".sqlite", ".sqlite3"}
+
+
+def scan_secrets(path: str | Path, max_files: int = 5000) -> dict[str, Any]:
+    root = Path(path)
+    eligible = [] if root.is_file() else [
+        p for p in sorted(root.rglob("*"))
+        if p.is_file() and p.suffix.lower() not in _SKIP_EXT
+        and not any(part in _SKIP_DIRS for part in p.parts)]
+    files = [root] if root.is_file() else eligible[:max_files]
+    truncated = bool(eligible) and len(eligible) > max_files
+    facts: list[dict[str, Any]] = []
+    hits_total = 0
+    for f in files:
+        try:
+            text = f.read_text(errors="replace")
+        except OSError:
+            continue
+        hits = []
+        for lineno, line in enumerate(text.splitlines(), 1):
+            for label, pat in PATTERNS:
+                if pat.search(line):
+                    hits.append({"line": lineno, "label": label})
+        # multi-line patterns (private keys) never match per-line —
+        # run them against the whole file body.
+        for label, pat in PATTERNS:
+            if "[\\s\\S]" not in pat.pattern:
+                continue
+            for m in pat.finditer(text):
+                lineno = text.count("\n", 0, m.start()) + 1
+                hit = {"line": lineno, "label": label}
+                if hit not in hits:
+                    hits.append(hit)
+        if hits:
+            hits_total += len(hits)
+            facts.append({"fact_id": stable_id("PF-SEC", "scan", str(f)),
+                          "kind": "security.secret_leak",
+                          "source": str(root), "location": str(f),
+                          "tier": 2,
+                          "attrs": {"hits": hits, "hit_count": len(hits)}})
+    return {"facts": facts,
+            "counts": {"files_scanned": len(files), "files_with_hits":
+                       len(facts), "hits": hits_total},
+            "truncated": truncated,
+            "note": "values never emitted — labels and line numbers only"}

platformforge/security/slsa.py

@@ -0,0 +1,86 @@
+"""§98 SLSA — real assessment: requirement / evidence / status / gap.
+
+No level is claimed without evidence. Each SLSA build-track requirement
+maps to observable artifact fields (builder id, provenance, hermetic
+flags, base64 digests, signatures); absent evidence → `gap`, present →
+`met`, partial → `partial`. `slsa_level` is only set when every
+requirement of that level is `met` — never inferred.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# SLSA v1.0 build-track requirements → fields that satisfy them
+REQUIREMENTS = {
+    "L1": {
+        "provenance_exists": "provenance document present",
+        "build_id": "build invocation identifier present",
+    },
+    "L2": {
+        "hosted_builder": "builder runs on hosted/ephemeral service",
+        "signed_provenance": "provenance signed",
+    },
+    "L3": {
+        "hardened_builder": "builder isolation declared",
+        "non_forgeable": "provenance non-forgeable (OIDC/sigstore)",
+        "base_images_pinned": "base images pinned by digest",
+    },
+}
+
+
+def _has(doc: dict[str, Any], *paths: str) -> bool:
+    for p in paths:
+        node: Any = doc
+        for part in p.split("."):
+            if not isinstance(node, dict) or part not in node:
+                break
+            node = node[part]
+        else:
+            if node not in (None, "", [], {}):
+                return True
+    return False
+
+
+def slsa_assess(provenance_doc: dict[str, Any] | None,
+                evidence: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Assess an in-toto/SLSA provenance document (or nothing)."""
+    ev = evidence or {}
+    if not provenance_doc:
+        return {"slsa_level": None, "status": "unresolved",
+                "reason": "no provenance document supplied",
+                "requirements": {}}
+    pred = provenance_doc.get("predicate") or {}
+    checks = {
+        "provenance_exists": True,
+        "build_id": _has(provenance_doc, "predicate.buildDefinition",
+                         "predicate.invocation") or
+                    _has(pred, "buildDefinition"),
+        "hosted_builder": bool(ev.get("hosted_builder")) or
+            _has(pred, "runDetails.builder.id"),
+        "signed_provenance": bool(ev.get("signed")) or
+            bool(provenance_doc.get("signatures")),
+        "hardened_builder": bool(ev.get("hardened_builder")),
+        "non_forgeable": bool(ev.get("non_forgeable")) or
+            _has(pred, "runDetails.builder.componentSource",
+                 "metadata.integrity"),
+        "base_images_pinned": bool(ev.get("base_images_pinned")) or
+            bool(pred.get("materials")),
+    }
+    levels = {}
+    for lv, reqs in REQUIREMENTS.items():
+        rows = []
+        for req, desc in reqs.items():
+            met = checks.get(req, False)
+            rows.append({"requirement": req, "description": desc,
+                         "status": "met" if met else "gap",
+                         "evidence": ev.get(req)})
+        levels[lv] = {"requirements": rows,
+                      "met": all(r["status"] == "met" for r in rows)}
+    attained = next((lv for lv in ("L3", "L2", "L1")
+                     if levels[lv]["met"]), None)
+    return {"slsa_level": attained,
+            "status": "assessed" if attained else "below-L1",
+            "levels": levels,
+            "note": "level = all requirements met; a gap at any level "
+                    "is reported, not smoothed over"}

platformforge/security/supply.py

@@ -0,0 +1,62 @@
+"""Supply chain — artifact digest pinning, SLSA/in-toto attestation shape,
+unsigned-image detection. Offline: verifies declared metadata, not sigs."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from platformforge.models.base import stable_id
+
+_DIGEST_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
+
+
+def analyze_supply(path: str | Path) -> dict[str, Any]:
+    """Input: JSON doc {artifacts: [{name, image, digest, slsa_provenance?,
+    signed?}], ...} or a single SLSA/in-toto attestation doc."""
+    doc = json.loads(Path(path).read_text())
+    facts: list[dict[str, Any]] = []
+
+    # in-toto / SLSA attestation document
+    if doc.get("_type") == "https://in-toto.io/Statement/v1" \
+            or "predicateType" in doc or "subject" in doc:
+        subj = doc.get("subject") or []
+        ptype = doc.get("predicateType", "")
+        facts.append({"fact_id": stable_id("PF-SEC", "attestation", str(path)),
+                      "kind": "security.attestation", "source": str(path),
+                      "location": str(path), "tier": 2,
+                      "attrs": {
+                          "predicate_type": ptype,
+                          "is_slsa": "slsa" in ptype,
+                          "subjects": len(subj),
+                          "subject_digests_valid": all(
+                              _DIGEST_RE.match(
+                                  (s.get("digest") or {}).get("sha256", ""))
+                              for s in subj) if subj else False,
+                          "materials": len(
+                              (doc.get("predicate") or {})
+                              .get("materials") or []),
+                          "note": "shape verified; signature NOT verified "
+                                  "offline"}})
+        return {"facts": facts, "counts": {"facts": 1}}
+
+    # artifact inventory doc
+    for a in doc.get("artifacts") or []:
+        img = a.get("image") or a.get("name") or "?"
+        digest = a.get("digest") or ""
+        pinned = bool(_DIGEST_RE.match(digest)) or "@sha256:" in str(img)
+        facts.append({
+            "fact_id": stable_id("PF-SEC", "artifact", str(path), img),
+            "kind": "security.artifact", "source": str(path),
+            "location": img, "tier": 3,
+            "attrs": {"image": img, "digest_pinned": pinned,
+                      "signed": bool(a.get("signed")),
+                      "slsa_provenance": bool(a.get("slsa_provenance")),
+                      "sbom_ref": a.get("sbom"),
+                      "graph": {
+                          "nodes": [{"kind": "container_image",
+                                     "label": img}],
+                          "edges": []}}})
+    return {"facts": facts, "counts": {"facts": len(facts)}}

platformforge/tokensave/__init__.py

@@ -0,0 +1,20 @@
+"""TokenSave — first-party input/context economy.
+
+Content addressing + incremental context + FTS5 index + context packs +
+budgets + ledger. No embeddings required; no external service required.
+"""
+
+from platformforge.tokensave.budget import Budget, BudgetVerdict
+from platformforge.tokensave.estimate import estimate_tokens
+from platformforge.tokensave.index import SearchIndex
+from platformforge.tokensave.ledger import TokenLedger
+from platformforge.tokensave.packs import ContextPackBuilder
+
+__all__ = [
+           "Budget",
+           "BudgetVerdict",
+           "ContextPackBuilder",
+           "SearchIndex",
+           "TokenLedger",
+           "estimate_tokens",
+]

platformforge/tokensave/budget.py

@@ -0,0 +1,62 @@
+"""Token budgets — insufficient budget is a named verdict, never silent
+evidence sacrifice."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class Budget:
+    input_budget: int | None = None
+    output_budget: int | None = None
+    reasoning_budget: int | None = None
+    tool_budget: int | None = None
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Budget:
+        return cls(**{k: d.get(k) for k in cls.__dataclass_fields__})
+
+    def to_dict(self) -> dict[str, Any]:
+        return {k: getattr(self, k) for k in self.__dataclass_fields__}
+
+
+class BudgetVerdict:
+    def __init__(self, decision: str, detail: str = "", reduced_scope=None):
+        self.decision = decision  # ok | refuse | reduce_scope | escalate
+        self.detail = detail
+        self.reduced_scope = reduced_scope
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"decision": self.decision, "detail": self.detail,
+                "reduced_scope": self.reduced_scope}
+
+
+def check_input_budget(budget: Budget, estimated_tokens: int,
+                       min_essential: int = 0,
+                       can_escalate: bool = False) -> BudgetVerdict:
+    """min_essential = tokens needed for essential evidence — below that, refuse
+    rather than silently drop evidence.
+
+    Canonical decisions (§26–§29): ok | reduced_scope | escalate | refuse.
+    `escalate` means the essential evidence does not fit but the caller
+    permits spending beyond the declared budget — recorded, never silent."""
+    if budget.input_budget is None:
+        return BudgetVerdict("ok")
+    if estimated_tokens <= budget.input_budget:
+        return BudgetVerdict("ok")
+    if min_essential and budget.input_budget >= min_essential:
+        return BudgetVerdict("reduced_scope",
+                             f"budget {budget.input_budget} < needed {estimated_tokens}; "
+                             f"keeping essential evidence ({min_essential})")
+    if can_escalate:
+        return BudgetVerdict("escalate",
+                             f"budget {budget.input_budget} < essential "
+                             f"{min_essential or estimated_tokens}; "
+                             "escalating beyond declared budget")
+    return BudgetVerdict("refuse",
+                         f"budget {budget.input_budget} < needed {estimated_tokens}; "
+                         "refusing rather than dropping essential evidence — "
+                         "raise budget or narrow scope",
+                         reduced_scope="PF-BUDGET-ESSENTIAL")