platformforge 0.1.0__py3-none-any.whl

platformforge/collect/detect.py

@@ -0,0 +1,254 @@
+"""Artifact-type detection + dispatch for `collect`.
+
+Signals are intentionally cheap and deterministic: filename patterns first,
+then document shape. Every file under the collected path is accounted for —
+`detected` or `undetected` — so nothing is silently dropped.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+_IGNORE = {".git", ".platformforge", ".venv", "node_modules",
+           "__pycache__", ".pytest-tmp", ".pytest_cache"}
+
+
+def _looks_k8s(doc: dict) -> bool:
+    return isinstance(doc.get("apiVersion"), str) and "kind" in doc
+
+
+def _shape_domain(path: Path, doc: Any) -> str | None:
+    """Document-shape heuristics, ordered most-specific first."""
+    if isinstance(doc, dict):
+        if _looks_k8s(doc):
+            if doc.get("kind") in ("Application", "AppProject",
+                                   "ApplicationSet") \
+                    and "argoproj.io" in str(doc.get("apiVersion")):
+                return "gitops"
+            if "toolkit.fluxcd.io" in str(doc.get("apiVersion")):
+                return "gitops"
+            api = str(doc.get("apiVersion", ""))
+            if "kyverno.io" in api or "policies.kyverno.io" in api or \
+                    "gatekeeper.sh" in api or \
+                    "admissionregistration.k8s.io" in api:
+                return "kyverno"
+            return "k8s"
+        if doc.get("format_version") or "terraform_version" in doc:
+            return "plan" if "planned_values" in doc else "state"
+        # AWS CLI dumps: top-level keys like Vpcs/Subnets/Roles/Accounts
+        if set(doc) & {"Vpcs", "Subnets", "InternetGateways", "NatGateways",
+                       "RouteTables", "SecurityGroups", "LoadBalancers",
+                       "HostedZones", "Roles", "Policies", "Users",
+                       "PolicyVersion", "Organization", "Accounts",
+                       "OrganizationalUnits", "Reservations", "Functions",
+                       "Clusters", "Buckets", "DBInstances", "QueueUrls",
+                       "Queues", "Topics", "TableNames"}:
+            return "cloud-aws"
+        if "flow" in doc and isinstance(doc.get("flow"), dict):
+            return "hubble"
+        if "Statement" in doc:
+            return "iam"
+        if doc.get("bomFormat") == "CycloneDX" \
+                or doc.get("spdxVersion"):
+            return "sbom"
+        if "predicateType" in doc or "provenance" in doc:
+            return "supply"
+        if any(k in doc for k in ("BillingAccountId", "ResourceId",
+                                  "ServiceName")) and "Charge" in str(doc)[:2000]:
+            return "finops"
+        # billing exports in JSON: OpenCost/Kubecost/CUR-as-JSON shapes
+        first_row = None
+        for key in ("rows", "data", "results", "items"):
+            if isinstance(doc.get(key), list) and doc[key]:
+                first_row = doc[key][0]
+                break
+        probe = first_row if isinstance(first_row, dict) else doc
+        if isinstance(probe, dict) and (
+                any(isinstance(k, str) and k.startswith("lineItem/")
+                    for k in probe)
+                or "UnblendedCost" in probe or "PreTaxCost" in probe
+                or "CostInBillingCurrency" in probe
+                or "totalCost" in probe
+                or ("cost" in probe and ("usage" in probe
+                                         or "labels" in probe))):
+            return "finops"
+    if isinstance(doc, dict) and isinstance(doc.get("items"), list) \
+            and all(_looks_k8s(i) for i in doc["items"]
+                    if isinstance(i, dict)):
+        return "k8s"
+    return None
+
+
+def detect_file(path: Path) -> str | None:
+    """Best-effort domain for a single artifact file."""
+    name = path.name.lower()
+    suffix = path.suffix.lower()
+    parts = {p.lower() for p in path.parts}
+    # path-shaped artifacts first — filename is the contract
+    if {".github", "workflows"} <= parts and suffix in (".yml", ".yaml"):
+        return "cicd-gha"
+    if name == ".gitlab-ci.yml":
+        return "gitlab-ci"
+    if name.startswith("dockerfile") or name.endswith(".dockerfile"):
+        return "dockerfile"
+    if name.startswith("catalog-info.") and suffix in (".yaml", ".yml"):
+        return "backstage"
+    if suffix == ".tf":
+        return "iac"
+    if name == "chart.yaml":
+        return "helm"
+    if name in ("kustomization.yaml", "kustomization.yml"):
+        return "kustomize"
+    if "hubble" in name or "flows" in name:
+        return "hubble"
+    if name in ("policy.json", "trust.json") or name.endswith(".policy.json"):
+        return "iam"
+    if name in ("sbom.json", "sbom.cdx.json") or "sbom" in name:
+        return "sbom"
+    if name in ("billing.json", "costs.json", "focus.csv", "billing.csv") \
+            or "billing" in name:
+        return "finops"
+    if name in ("supply.json", "provenance.json", "attestation.json") \
+            or "in-toto" in name:
+        return "supply"
+    if "sigstore" in name or "cosign" in name \
+            or name.endswith((".sig", ".bundle")):
+        return "cosign"
+    if name in ("slo.yaml", "slo.yml"):
+        return "slo"
+    if name in ("otel.yaml", "otel.yml") or "otel" in name:
+        return "otel"
+    if suffix == ".csv":
+        # billing exports by header shape, not filename
+        try:
+            header = path.open().readline()
+        except OSError:
+            return None
+        if "lineItem/" in header or "UnblendedCost" in header or \
+                "PreTaxCost" in header or "CostInBillingCurrency" in header \
+                or ("cost" in header.lower() and
+                    ("sku" in header.lower() or "usage" in header.lower())):
+            return "finops"
+        return None
+    if suffix not in (".json", ".yaml", ".yml"):
+        return None
+    try:
+        doc = json.loads(path.read_text()) if suffix == ".json" \
+            else yaml.safe_load(path.read_text())
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError,
+            yaml.YAMLError):
+        return None
+    if isinstance(doc, list):
+        doc = next((d for d in doc if isinstance(d, dict)), None)
+        if doc is None:
+            return None
+    return _shape_domain(path, doc)
+
+
+def collect(path: str | Path) -> dict[str, Any]:
+    """Walk path, detect artifact types, run matching analyzers, merge facts.
+
+    Returns {facts, detected: {domain: [files]}, undetected: [files]}.
+    Read-only: this never touches a provider.
+    """
+    root = Path(path)
+    files = ([root] if root.is_file() else
+             sorted(p for p in root.rglob("*")
+                    if p.is_file() and not _IGNORE.intersection(p.parts)))
+    detected: dict[str, list[str]] = {}
+    undetected: list[str] = []
+    buckets: dict[str, list[Path]] = {}
+    for f in files:
+        dom = detect_file(f)
+        if dom is None:
+            undetected.append(str(f))
+        else:
+            detected.setdefault(dom, []).append(str(f))
+            buckets.setdefault(dom, []).append(f)
+
+    facts: list[dict[str, Any]] = []
+    from platformforge import iac, security
+    from platformforge.finops import cost_facts
+    for dom, paths in buckets.items():
+        try:
+            if dom == "iac":
+                facts += iac.analyze_hcl(paths[0].parent)["facts"]
+            elif dom in ("plan", "state"):
+                fn = (iac.analyze_plan if dom == "plan" else
+                      iac.analyze_state)
+                for p in paths:
+                    facts += fn(str(p))["facts"]
+            elif dom == "iam":
+                for p in paths:
+                    facts += security.analyze_iam_policy(str(p))["facts"]
+            elif dom == "sbom":
+                facts += security.analyze_sbom(str(paths[0]))["facts"]
+            elif dom == "supply":
+                facts += security.analyze_supply(str(paths[0]))["facts"]
+            elif dom == "finops":
+                from platformforge.finops.costs import cost_facts_from_rows
+                from platformforge.finops.ingest import ingest_billing
+                ing = ingest_billing(str(paths[0]))
+                if ing["rows"]:
+                    facts += cost_facts_from_rows(
+                        ing["rows"], source=str(paths[0]))["facts"]
+                else:
+                    facts += cost_facts(str(paths[0]))["facts"]
+            elif dom == "cloud-aws":
+                from platformforge.cloud import analyze_aws_dump
+                for p in paths:
+                    facts += analyze_aws_dump(str(p))["facts"]
+            elif dom == "helm":
+                from platformforge.k8s.helm import analyze_helm
+                parent = paths[0].parent
+                facts += analyze_helm(parent)["facts"]
+            elif dom == "kustomize":
+                from platformforge.k8s.helm import analyze_kustomize
+                facts += analyze_kustomize(paths[0].parent)["facts"]
+            elif dom == "hubble":
+                from platformforge.k8s.hubble import analyze_hubble
+                for p in paths:
+                    facts += analyze_hubble(str(p))["facts"]
+            elif dom == "kyverno":
+                from platformforge.security.kyverno import analyze_kyverno
+                parent = paths[0].parent
+                facts += analyze_kyverno(parent)["facts"]
+            elif dom == "cosign":
+                from platformforge.security.cosign import analyze_cosign
+                for p in paths:
+                    facts += analyze_cosign(str(p))["facts"]
+            elif dom in ("k8s", "gitops"):
+                # dir-level domains: run once over the common parent
+                parent = paths[0].parent
+                mod = ("platformforge.k8s:analyze_k8s" if dom == "k8s"
+                       else "platformforge.cicd:analyze_gitops")
+                m, fn = mod.split(":")
+                import importlib
+                facts += getattr(importlib.import_module(m), fn)(parent)["facts"]
+            elif dom == "cicd-gha":
+                from platformforge.cicd import analyze_gha
+                for p in paths:
+                    facts += analyze_gha(p)["facts"]
+            elif dom == "gitlab-ci":
+                from platformforge.cicd import analyze_gitlab_ci
+                for p in paths:
+                    facts += analyze_gitlab_ci(p)["facts"]
+            elif dom == "dockerfile":
+                from platformforge.cicd import analyze_dockerfile
+                for p in paths:
+                    facts += analyze_dockerfile(p)["facts"]
+            elif dom == "backstage":
+                from platformforge.cicd import analyze_backstage
+                for p in paths:
+                    facts += analyze_backstage(p)["facts"]
+        except Exception as exc:  # noqa: BLE001 — analyzer failure degrades to undetected, not a crash
+            undetected.append(f"{dom}:{exc!r}")
+    # secrets is a baseline dir-scan over everything collected — dumps are
+    # exactly where leaked credentials surface
+    from platformforge.security import scan_secrets
+    facts += scan_secrets(root)["facts"]
+    return {"facts": facts, "detected": detected, "undetected": undetected}

platformforge/context/__init__.py

@@ -0,0 +1,10 @@
+"""Unified Context Gateway (§56–75) — single layer through which all
+model/agent context passes."""
+
+from platformforge.context.capsule import ContextCapsule
+from platformforge.context.gateway import ContextGateway, ContextRequest
+from platformforge.context.refs import ContextRef
+from platformforge.context.sufficiency import ContextSufficiencyResult, Sufficiency
+
+__all__ = ["ContextCapsule", "ContextGateway", "ContextRef",
+           "ContextRequest", "ContextSufficiencyResult", "Sufficiency"]

platformforge/context/capsule.py

@@ -0,0 +1,60 @@
+"""ContextCapsule (§60–61) — the bounded payload handed to a model/agent.
+
+Sections hold refs, not duplicated bytes (§62): facts/findings/rules are
+`fact://`/`finding://` pointers into the store; expandable detail lives
+behind `context://` refs resolved by `context expand` (§63–64)."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+SCHEMA = "platformforge/context-capsule/v1"
+
+SCOPES = ("repository", "resource", "cluster", "fleet", "incident",
+          "operation", "service")            # §68
+
+# §111 — compression/projection may never strip these from a capsule.
+ESSENTIAL_FIELDS = ("facts", "findings", "open_questions")
+
+
+@dataclass
+class ContextCapsule:
+    schema: str = SCHEMA
+    capsule_id: str = ""
+    summary: str = ""
+    task: str = ""
+    scope: str = "repository"
+    facts: list[Any] = field(default_factory=list)
+    findings: list[Any] = field(default_factory=list)
+    rules: list[str] = field(default_factory=list)
+    knowledge_refs: list[str] = field(default_factory=list)
+    graph_refs: list[str] = field(default_factory=list)
+    artifact_refs: list[str] = field(default_factory=list)
+    open_questions: list[str] = field(default_factory=list)
+    budget: dict[str, Any] = field(default_factory=dict)
+    expandable: dict[str, str] = field(default_factory=dict)
+    # section name → context:// uri with full detail (§62)
+
+    def __post_init__(self) -> None:
+        if self.scope not in SCOPES:
+            raise ValueError(f"scope {self.scope!r} not in {SCOPES}")
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    def serialize(self) -> bytes:
+        return json.dumps(self.to_dict(), sort_keys=True,
+                          separators=(",", ":"), default=str).encode()
+
+    @property
+    def byte_size(self) -> int:
+        return len(self.serialize())
+
+    def content_hash(self) -> str:
+        import hashlib
+        return hashlib.sha256(self.serialize()).hexdigest()
+
+    def ref(self) -> str:
+        return f"context://sha256/{self.content_hash()}"

platformforge/context/gateway.py

@@ -0,0 +1,227 @@
+"""ContextGateway (§56–75) — the single context layer.
+
+Pipeline (§58): task → scope → search → graph expansion → evidence
+selection → dedup → budget → pack → redaction → ContextRef.
+
+Every model/agent entry goes through `build()`; the capsule it returns is
+the minimal sufficient context, not the maximal available one (§297).
+Essential evidence that cannot fit the budget is a refusal
+(PF-CONTEXT-ESSENTIAL) — never silently truncated (§235 eval).
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from platformforge.context.capsule import ContextCapsule
+from platformforge.context.refs import ContextRef
+from platformforge.context.sufficiency import ContextSufficiencyResult, Sufficiency, assess
+from platformforge.economy.cache import CacheStore
+from platformforge.economy.ledger import EconomyLedger, ToolUsageEntry
+
+REFUSAL_ESSENTIAL = "PF-CONTEXT-ESSENTIAL"
+
+# §70–73 — which capsule sections each role receives.
+ROLE_SECTIONS: dict[str, tuple[str, ...]] = {
+    "specialist": ("summary", "task", "scope", "facts", "findings",
+                   "rules", "knowledge_refs", "graph_refs",
+                   "artifact_refs", "open_questions"),
+    "reviewer": ("summary", "task", "scope", "findings", "rules",
+                 "open_questions"),
+    "verifier": ("summary", "task", "findings", "rules",
+                 "open_questions"),        # §71: criteria+evidence+outputs
+    "critic": ("summary", "task", "open_questions"),  # §72 assumptions
+    "referee": ("summary", "task", "open_questions"),
+    "planner": ("summary", "task", "scope", "open_questions",
+                "knowledge_refs"),
+}
+
+
+@dataclass
+class ContextRequest:
+    task: str
+    scope: str = "repository"
+    budget_bytes: int | None = None          # soft context budget
+    essential_bytes: int | None = None       # §235 — must-fit floor
+    required_sections: list[str] = field(default_factory=list)
+    role: str = "specialist"
+    query: str = ""
+    facts: list[dict[str, Any]] = field(default_factory=list)
+    findings: list[dict[str, Any]] = field(default_factory=list)
+    rules: list[str] = field(default_factory=list)
+    knowledge_refs: list[str] = field(default_factory=list)
+    graph_refs: list[str] = field(default_factory=list)
+    artifact_refs: list[str] = field(default_factory=list)
+    open_questions: list[str] = field(default_factory=list)
+    deps: dict[str, str] = field(default_factory=dict)
+
+
+class ContextGateway:
+    def __init__(self, root: str | Path):
+        self.root = Path(root)
+        self.cache = CacheStore(root)
+        self.ledger = EconomyLedger(root)
+        self._store = self.root / ".platformforge" / "context-store"
+        self._store.mkdir(parents=True, exist_ok=True)
+
+    # -- build (pipeline §58) ------------------------------------------
+    def build(self, req: ContextRequest) -> dict[str, Any]:
+        t0 = time.monotonic()
+        # 1–2. task + scope are inputs; 3–4. search/graph expansion is the
+        # caller's job (facts/findings arrive already extracted — the
+        # gateway assembles, it does not analyze).
+        # 5. evidence selection: essential sections first, dedup (§6).
+        facts = _dedup(req.facts, key=lambda f: f.get("fact_id",
+                                                      json.dumps(f,
+                                                                 sort_keys=True,
+                                                                 default=str)))
+        findings = _dedup(req.findings, key=lambda f: f.get(
+            "finding_id", f.get("rule_id", json.dumps(f, sort_keys=True,
+                                                    default=str))))
+
+        capsule = ContextCapsule(
+            summary=f"{req.task} ({req.scope})",
+            task=req.task, scope=req.scope,
+            facts=facts, findings=findings, rules=req.rules,
+            knowledge_refs=req.knowledge_refs, graph_refs=req.graph_refs,
+            artifact_refs=req.artifact_refs,
+            open_questions=req.open_questions,
+            budget={"budget_bytes": req.budget_bytes,
+                    "essential_bytes": req.essential_bytes})
+
+        # 7. budget — essential evidence must fit or the capsule refuses
+        size = capsule.byte_size
+        if req.essential_bytes is not None and \
+                req.budget_bytes is not None and \
+                req.essential_bytes > req.budget_bytes:
+            self.ledger.record(ToolUsageEntry(
+                tool="context.build", output_bytes=size,
+                duration_ms=(time.monotonic() - t0) * 1000,
+                task=req.task))
+            return {"refusal": REFUSAL_ESSENTIAL,
+                    "reason": f"essential {req.essential_bytes}B > "
+                              f"budget {req.budget_bytes}B — narrow scope "
+                              "or raise budget; never truncate evidence",
+                    "sufficiency": ContextSufficiencyResult(
+                        Sufficiency.INSUFFICIENT,
+                        ["essential-evidence"],
+                        "budget smaller than essential floor").to_dict()}
+
+        # 8. redaction — secrets never persist into the store (§224)
+        self._persist(capsule)
+
+        # 9. ContextRef + sufficiency + cache receipt
+        ref = capsule.ref()
+        suff = assess(required=req.required_sections,
+                      present=[s for s in ("facts", "findings", "rules",
+                                           "knowledge_refs",
+                                           "graph_refs")
+                               if getattr(capsule, s)])
+        self.ledger.record(ToolUsageEntry(
+            tool="context.build", output_bytes=size,
+            duration_ms=(time.monotonic() - t0) * 1000,
+            task=req.task))
+        return {"capsule": capsule.to_dict(), "ref": ref,
+                "bytes": size, "sufficiency": suff.to_dict(),
+                "expandable": capsule.expandable}
+
+    # -- lazy refs (§63–64) ---------------------------------------------
+    def _persist(self, capsule: ContextCapsule) -> None:
+        # §224 — redact before persistence (the capsule holds refs; the
+        # payload sections may still carry sensitive text from callers)
+        blob = _redact(capsule.to_dict())
+        (self._store / f"{capsule.content_hash()}.json").write_text(
+            json.dumps(blob, sort_keys=True, default=str))
+
+    def inspect(self, ref: str) -> dict[str, Any]:
+        """Resolve a `context://sha256/<hash>` ref to its stored capsule."""
+        digest = ContextRef.parse(ref).digest
+        p = self._store / f"{digest}.json"
+        if not p.exists():
+            return {"refusal": "PF-CONTEXT-REF-UNKNOWN",
+                    "reason": f"no stored capsule for {ref}",
+                    "unlock": "rebuild the context that minted the ref"}
+        return json.loads(p.read_text())
+
+    def expand(self, ref: str, section: str = "") -> dict[str, Any]:
+        """§63–64 — lazy expansion: return only the requested section
+        (or the full capsule when section is empty)."""
+        cap = self.inspect(ref)
+        if "refusal" in cap:
+            return cap
+        if section:
+            if section not in cap:
+                return {"refusal": "PF-CONTEXT-SECTION-UNKNOWN",
+                        "reason": f"capsule has no section {section!r}",
+                        "sections": sorted(k for k in cap
+                                           if not k.startswith("_"))}
+            return {"ref": ref, "section": section,
+                    "content": cap[section]}
+        return {"ref": ref, "capsule": cap}
+
+    def delta(self, base_ref: str, capsule: ContextCapsule
+              ) -> dict[str, Any]:
+        """§74 — baseline + delta: emit only the sections that changed vs
+        the stored baseline capsule. Unchanged sections ship as the ref."""
+        base = self.inspect(base_ref)
+        if "refusal" in base:
+            return base
+        delta: dict[str, Any] = {}
+        reused: list[str] = []
+        for k, v in capsule.to_dict().items():
+            if k in ("schema",):
+                continue
+            if base.get(k) != v:
+                delta[k] = v
+            else:
+                reused.append(k)
+        self._persist(capsule)
+        return {"baseline_ref": base_ref, "delta_ref": capsule.ref(),
+                "delta": delta, "reused_sections": reused,
+                "delta_bytes": len(json.dumps(delta, default=str)),
+                "full_bytes": capsule.byte_size}
+
+    # -- role-specific (§70–73) -----------------------------------------
+    def for_role(self, ref: str, role: str) -> dict[str, Any]:
+        """Project a stored capsule to the sections a role receives.
+        Verifier gets criteria+evidence+outputs — not the transcript."""
+        if role not in ROLE_SECTIONS:
+            return {"refusal": "PF-CONTEXT-ROLE-UNKNOWN",
+                    "reason": f"role {role!r} not in "
+                              f"{sorted(ROLE_SECTIONS)}"}
+        cap = self.inspect(ref)
+        if "refusal" in cap:
+            return cap
+        return {"role": role, "ref": ref,
+                "context": {s: cap.get(s) for s in ROLE_SECTIONS[role]}}
+
+
+def _dedup(items: list[dict[str, Any]], key) -> list[dict[str, Any]]:
+    seen, out = set(), []
+    for it in items:
+        k = key(it)
+        if k in seen:
+            continue
+        seen.add(k)
+        out.append(it)
+    return out
+
+
+_SECRET_KEYS = ("password", "secret", "token", "api_key", "private_key",
+                "credential")
+
+
+def _redact(obj: Any) -> Any:
+    """§224 — boundary redaction before capsule persistence. Values whose
+    key looks secret-shaped are replaced, never stored."""
+    if isinstance(obj, dict):
+        return {k: ("[REDACTED]" if any(s in str(k).lower()
+                                        for s in _SECRET_KEYS)
+                    else _redact(v)) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_redact(v) for v in obj]
+    return obj

platformforge/context/refs.py

@@ -0,0 +1,49 @@
+"""Pointer-based context refs (§59, §62) — `context://sha256/<hash>` and
+the typed evidence/fact/graph pointers. Agents receive refs and expand on
+demand (§63–64) instead of receiving duplicated content."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from typing import Any
+
+REF_SCHEMES = ("context", "evidence", "fact", "graph", "artifact",
+               "knowledge", "finding")
+
+
+def _hash(payload: Any) -> str:
+    body = json.dumps(payload, sort_keys=True, separators=(",", ":"),
+                      default=str).encode()
+    return hashlib.sha256(body).hexdigest()
+
+
+@dataclass(frozen=True)
+class ContextRef:
+    """§59 — a content-addressed pointer. `uri` is the wire form."""
+    scheme: str                      # REF_SCHEMES
+    digest: str
+    hint: str = ""                   # what the ref points at (for budgets)
+
+    def __post_init__(self) -> None:
+        if self.scheme not in REF_SCHEMES:
+            raise ValueError(f"unknown ref scheme {self.scheme!r}")
+        if len(self.digest) != 64:
+            raise ValueError("ref digest must be sha256 (64 hex)")
+
+    @property
+    def uri(self) -> str:
+        return f"{self.scheme}://sha256/{self.digest}"
+
+    @classmethod
+    def of(cls, scheme: str, payload: Any, hint: str = "") -> ContextRef:
+        return cls(scheme=scheme, digest=_hash(payload), hint=hint)
+
+    @classmethod
+    def parse(cls, uri: str) -> ContextRef:
+        scheme, _, rest = uri.partition("://")
+        algo, _, digest = rest.partition("/")
+        if algo != "sha256":
+            raise ValueError(f"unsupported ref algo {algo!r}")
+        return cls(scheme=scheme, digest=digest)

platformforge/context/sufficiency.py

@@ -0,0 +1,50 @@
+"""Context sufficiency (§65–67) and quality (§69)."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+class Sufficiency:
+    SUFFICIENT = "sufficient"
+    PARTIAL = "partial"
+    INSUFFICIENT = "insufficient"     # §67 — never answer with confidence
+
+
+@dataclass
+class ContextSufficiencyResult:
+    state: str                       # Sufficiency.*
+    missing: list[str] = field(default_factory=list)
+    reason: str = ""
+    coverage: dict[str, float] = field(default_factory=dict)
+
+    def confident(self) -> bool:
+        """§67 — insufficient context forbids confident answers."""
+        return self.state == Sufficiency.SUFFICIENT
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def assess(*, required: list[str], present: list[str],
+           essential_fit: bool = True) -> ContextSufficiencyResult:
+    """Sufficiency = did the needed evidence sections make the pack?
+
+    `essential_fit=False` means the budget could not hold essential
+    evidence → insufficient (never silently truncated, §235)."""
+    missing = [r for r in required if r not in present]
+    if not essential_fit:
+        return ContextSufficiencyResult(
+            Sufficiency.INSUFFICIENT, missing or ["essential-evidence"],
+            "essential evidence does not fit the context budget",
+            coverage={"evidence": (len(present) /
+                                   max(1, len(present) + len(missing)))})
+    if missing:
+        return ContextSufficiencyResult(
+            Sufficiency.PARTIAL, missing,
+            f"missing sections: {missing}",
+            coverage={"evidence": len(present) /
+                      max(1, len(present) + len(missing))})
+    return ContextSufficiencyResult(
+        Sufficiency.SUFFICIENT, coverage={"evidence": 1.0})

platformforge/core/__init__.py

@@ -0,0 +1 @@
+"""Deterministic core: hashing, artifact store, receipts, redaction, workspace."""