platformforge 0.1.0__py3-none-any.whl

platformforge/fleet/query.py

@@ -0,0 +1,154 @@
+"""Cycle 5 Phase B — fleet questions (§27).
+
+Each question is a deterministic graph query over the federated org
+graph; answers carry node ids + fact evidence, and the caller gets the
+snapshot coverage alongside — never an org-wide claim from a partial
+fleet (§374/§391).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from platformforge.fleet.orggraph import layer_of
+from platformforge.graph.model import Graph
+
+# question id → human label (§27)
+FLEET_QUESTIONS = {
+    "public-services": "all services with public exposure",
+    "critical-services": "services marked critical (declared evidence)",
+    "unsupported-k8s": "workloads on unsupported kubernetes versions",
+    "wildcard-iam": "IAM roles/principals with wildcard permissions",
+    "unowned": "resources without an owning team",
+    "no-slo": "services without an SLO definition",
+    "outside-golden-path": "services not using a golden path",
+    "idle-high-cost": "high-cost workloads flagged idle/underused",
+    "cross-env-deps": "dependencies that cross environment boundaries",
+}
+
+
+def fleet_query(graph: Graph, question: str) -> dict[str, Any]:
+    fn = _QUESTIONS.get(question)
+    if fn is None:
+        raise ValueError(f"unknown fleet question: {question}")
+    hits = fn(graph)
+    return {"question": question, "count": len(hits), "items": hits}
+
+
+def _fact_ids(n) -> list[str]:
+    return list(n.source_fact_ids)
+
+
+def _public_services(g: Graph) -> list[dict[str, Any]]:
+    out = []
+    for n in g.nodes.values():
+        if n.kind in ("service", "workload") and (
+                n.attrs.get("exposure") == "public"
+                or n.attrs.get("public") is True):
+            out.append({"node_id": n.node_id, "layer": layer_of(n.kind),
+                        "fact_ids": _fact_ids(n)})
+    # ingress/load-balancer exposure counts as public too
+    for e in g.edges.values():
+        if e.kind == "exposes" and e.src in g.nodes:
+            src = g.nodes[e.src]
+            if src.kind in ("service", "workload") and all(
+                    h["node_id"] != src.node_id for h in out):
+                out.append({"node_id": src.node_id,
+                            "layer": layer_of(src.kind),
+                            "fact_ids": list(e.source_fact_ids)})
+    return out
+
+
+def _critical_services(g: Graph) -> list[dict[str, Any]]:
+    return [{"node_id": n.node_id, "criticality": n.attrs["criticality"],
+             "fact_ids": _fact_ids(n)}
+            for n in g.nodes.values()
+            if n.kind in ("service", "workload")
+            and n.attrs.get("criticality") in ("critical", "high")]
+
+
+def _unsupported_k8s(g: Graph) -> list[dict[str, Any]]:
+    return [{"node_id": n.node_id, "version": n.attrs.get("k8s_version"),
+             "fact_ids": _fact_ids(n)}
+            for n in g.nodes.values()
+            if n.attrs.get("supported") is False
+            or n.attrs.get("k8s_support") == "unsupported"]
+
+
+def _wildcard_iam(g: Graph) -> list[dict[str, Any]]:
+    return [{"node_id": n.node_id, "fact_ids": _fact_ids(n)}
+            for n in g.nodes.values()
+            if n.kind in ("iam_principal", "role", "policy")
+            and n.attrs.get("wildcard") is True]
+
+
+def _unowned(g: Graph) -> list[dict[str, Any]]:
+    owned = {e.dst for e in g.edges.values() if e.kind == "owns"}
+    owned |= {e.src for e in g.edges.values() if e.kind == "owns"}
+    return [{"node_id": n.node_id, "layer": layer_of(n.kind)}
+            for n in g.nodes.values()
+            if n.kind in ("service", "workload", "repository",
+                          "database", "cluster")
+            and n.node_id not in owned]
+
+
+def _no_slo(g: Graph) -> list[dict[str, Any]]:
+    slo_targets = {e.src for e in g.edges.values()
+                   if g.nodes.get(e.dst) and
+                   g.nodes[e.dst].kind == "slo"}
+    has_slo_attr = {n.node_id for n in g.nodes.values()
+                    if n.attrs.get("slo")}
+    return [{"node_id": n.node_id, "fact_ids": _fact_ids(n)}
+            for n in g.nodes.values()
+            if n.kind in ("service", "workload")
+            and n.node_id not in slo_targets | has_slo_attr]
+
+
+def _outside_golden_path(g: Graph) -> list[dict[str, Any]]:
+    on_path = {e.src for e in g.edges.values()
+               if e.kind == "uses_golden_path"}
+    services = {n.node_id for n in g.nodes.values()
+                if n.kind in ("service", "workload")}
+    return [{"node_id": nid} for nid in sorted(services - on_path)]
+
+
+def _idle_high_cost(g: Graph) -> list[dict[str, Any]]:
+    out = []
+    for n in g.nodes.values():
+        idle = n.attrs.get("idle") or n.attrs.get("underused")
+        cost = n.attrs.get("cost_monthly") or n.attrs.get("cost_usd")
+        if idle and isinstance(cost, (int, float)) and cost > 0:
+            out.append({"node_id": n.node_id, "cost_monthly": cost,
+                        "idle_signal": n.attrs.get("idle_signal", "obs"),
+                        "fact_ids": _fact_ids(n)})
+    return sorted(out, key=lambda h: -h["cost_monthly"])
+
+
+def _cross_env_deps(g: Graph) -> list[dict[str, Any]]:
+    out = []
+    for e in g.edges.values():
+        if e.kind not in ("depends_on", "calls", "reads", "writes",
+                          "consumes"):
+            continue
+        a, b = g.nodes.get(e.src), g.nodes.get(e.dst)
+        if not a or not b:
+            continue
+        ea, eb = a.attrs.get("environment"), b.attrs.get("environment")
+        if ea and eb and ea != eb:
+            out.append({"from": e.src, "to": e.dst, "kind": e.kind,
+                        "envs": [ea, eb],
+                        "fact_ids": list(e.source_fact_ids)})
+    return out
+
+
+_QUESTIONS = {
+    "public-services": _public_services,
+    "critical-services": _critical_services,
+    "unsupported-k8s": _unsupported_k8s,
+    "wildcard-iam": _wildcard_iam,
+    "unowned": _unowned,
+    "no-slo": _no_slo,
+    "outside-golden-path": _outside_golden_path,
+    "idle-high-cost": _idle_high_cost,
+    "cross-env-deps": _cross_env_deps,
+}

platformforge/forge/__init__.py

@@ -0,0 +1,9 @@
+"""The Forge interoperability — capability manifest, delegation contracts,
+A2A envelope, result receipts, evidence transfer."""
+
+from platformforge.forge.collect import collect_manifest, discover, ingest_facts
+from platformforge.forge.delegate import Delegation, build_envelope, verify_envelope
+from platformforge.forge.manifest import capability_manifest
+
+__all__ = ["Delegation", "build_envelope", "capability_manifest",
+           "collect_manifest", "discover", "ingest_facts", "verify_envelope"]

platformforge/forge/collect.py

@@ -0,0 +1,88 @@
+"""Sibling-Forge ingress — §82–83. Read-only: invokes a sibling forge's
+own CLI if installed, or reads its emitted manifest/facts files.
+Never shells out to providers; sibling forges are offline-first too."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from platformforge.models.base import stable_id
+
+KNOWN_FORGES = {
+    "api-forge": {"cli": "apiforge", "manifest_cmd": ["capability", "manifest"]},
+    "spark-forge-aws": {"cli": "sparkforge-aws",
+                        "manifest_cmd": ["capability", "manifest"]},
+    "platform-forge": {"cli": "platformforge",
+                       "manifest_cmd": ["forge", "manifest"]},
+}
+
+
+def discover(root: str | Path) -> dict[str, Any]:
+    """Find sibling forge repos under a directory — marker: pyproject name
+    or an AGENTS.md declaring the forge."""
+    root = Path(root)
+    found = []
+    for d in sorted(root.iterdir()):
+        if not d.is_dir():
+            continue
+        py = d / "pyproject.toml"
+        if py.exists():
+            head = py.read_text(errors="replace")[:2000]
+            for fname in KNOWN_FORGES:
+                if f'name = "{fname.replace("-", "")}"' in head or \
+                        fname in head:
+                    found.append({"forge": fname, "path": str(d),
+                                  "marker": "pyproject"})
+                    break
+    return {"root": str(root), "forges": found}
+
+
+def collect_manifest(forge_root: str | Path,
+                     timeout: int = 30) -> dict[str, Any]:
+    """Run the sibling's own capability manifest via its CLI if available;
+    else refuse with the unlock path — we never guess a manifest."""
+    root = Path(forge_root)
+    py = root / "pyproject.toml"
+    if not py.exists():
+        return {"refusal": "platform.forge.unresolved",
+                "detail": f"{root} is not a forge root (no pyproject.toml)",
+                "unlock": "point --path at a forge repository"}
+    cli = None
+    for name, spec in KNOWN_FORGES.items():
+        if name in py.read_text(errors="replace")[:2000]:
+            cli = shutil.which(spec["cli"])
+            if cli:
+                r = subprocess.run([cli, *spec["manifest_cmd"], "--format",
+                                    "json"],
+                                   capture_output=True, text=True,
+                                   timeout=timeout, check=False, cwd=root)
+                if r.returncode == 0:
+                    try:
+                        manifest = json.loads(r.stdout)
+                    except json.JSONDecodeError:
+                        manifest = {"raw": r.stdout[:4000]}
+                    return {"forge": name, "manifest": manifest,
+                            "fact_id": stable_id("PF-FORG", name, str(root)),
+                            "source": "cli"}
+            return {"forge": name, "refusal": "platform.forge.cli_missing",
+                    "detail": f"{spec['cli']} not on PATH",
+                    "unlock": f"pip install -e {root}"}
+    return {"refusal": "platform.forge.unknown",
+            "detail": f"{root.name} is not a recognized sibling forge",
+            "unlock": "extend KNOWN_FORGES with its CLI + manifest verb"}
+
+
+def ingest_facts(facts_doc: dict[str, Any], forge: str) -> dict[str, Any]:
+    """Wrap another forge's fact dicts — they stay tier-3+ evidence with a
+    provenance marker; we never claim their evidence as ours."""
+    facts = []
+    for f in facts_doc.get("facts", []):
+        f = dict(f)
+        f.setdefault("attrs", {})["external_forge"] = forge
+        f.setdefault("tier", 3)
+        facts.append(f)
+    return {"facts": facts, "count": len(facts), "forge": forge}

platformforge/forge/delegate.py

@@ -0,0 +1,77 @@
+"""Delegation + A2A envelope — cross-forge task handoff with receipts.
+
+Envelope: {envelope, from_forge, to_forge, task, inputs(refs), budget,
+evidence_requirements, deadline_s?, reply_to}. Receipts prove the result;
+evidence transfers as fact dicts + artifact refs, never prose."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from platformforge.models.base import stable_id
+
+
+@dataclass
+class Delegation:
+    from_forge: str
+    to_forge: str
+    task: str
+    inputs: dict[str, Any] = field(default_factory=dict)
+    budget: dict[str, Any] = field(default_factory=dict)
+    evidence_requirements: list[str] = field(default_factory=list)
+    deadline_s: int | None = None
+
+    def validate(self) -> list[str]:
+        errs = []
+        if not self.task:
+            errs.append("task required")
+        if self.deadline_s is not None and self.deadline_s <= 0:
+            errs.append("deadline_s must be positive")
+        if self.budget and "max_tokens" in self.budget \
+                and self.budget["max_tokens"] <= 0:
+            errs.append("max_tokens must be positive")
+        return errs
+
+
+def build_envelope(d: Delegation) -> dict[str, Any]:
+    errs = d.validate()
+    if errs:
+        return {"refusal": "platform.delegation.invalid", "errors": errs}
+    return {
+        "envelope": "platformforge/a2a-envelope/v1",
+        "delegation_id": stable_id("PF-DLG", d.from_forge, d.to_forge,
+                                   d.task, str(time.time_ns())),
+        "from_forge": d.from_forge, "to_forge": d.to_forge,
+        "task": d.task, "inputs": d.inputs, "budget": d.budget,
+        "evidence_requirements": d.evidence_requirements,
+        "deadline_s": d.deadline_s,
+        "created_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+    }
+
+
+def verify_envelope(env: dict[str, Any]) -> dict[str, Any]:
+    """Accept/reject an incoming A2A envelope. Missing fields → named gaps."""
+    missing = [k for k in ("envelope", "from_forge", "to_forge", "task",
+                           "delegation_id") if not env.get(k)]
+    ok = not missing and env["envelope"] == "platformforge/a2a-envelope/v1"
+    return {"accepted": ok, "missing": missing,
+            "refusal": None if ok else "platform.envelope.invalid"}
+
+
+def result_receipt(env: dict[str, Any], result: dict[str, Any],
+                   evidence: list[dict[str, Any]] | None = None) -> dict[str, Any]:
+    """Receipt a completed delegation — evidence transfers as facts/refs."""
+    return {
+        "receipt": "platformforge/result-receipt/v1",
+        "delegation_id": env.get("delegation_id"),
+        "from_forge": env.get("to_forge"),   # responder
+        "to_forge": env.get("from_forge"),
+        "status": "completed",
+        "result": result,
+        "evidence_facts": evidence or [],
+        "unresolved": result.get("unresolved", []),
+        "receipt_id": stable_id("PF-RCPT", str(env.get("delegation_id")),
+                                str(time.time_ns())),
+    }

platformforge/forge/manifest.py

@@ -0,0 +1,106 @@
+"""Capability manifest — what this forge can do, for sibling forges and
+orchestrators. Generated from the code, never hand-maintained."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from platformforge.graph.vocab import EDGE_KINDS, NODE_KINDS
+from platformforge.mcp.registry import CAPABILITIES
+from platformforge.resources import data_path
+from platformforge.rules import load_catalog
+
+_REPO = data_path()
+
+
+def capability_manifest(repo: str | Path | None = None) -> dict[str, Any]:
+    root = Path(repo) if repo else _REPO
+    rules = load_catalog(root / "rules" / "catalog")
+    try:
+        head = subprocess.run(["git", "-C", str(root), "rev-parse", "--short",
+                               "HEAD"], capture_output=True, text=True,
+                              check=False).stdout.strip()
+    except OSError:
+        head = "unknown"
+    from platformforge.ops.registry import delegation_contract, ops_capabilities
+    return {
+        "manifest": "platformforge/capability-manifest/v4",
+        "forge": "platform-forge",
+        "version": "0.1.0",
+        "commit": head,
+        "modes": {"offline": True, "read_only": True,
+                  "cloud_mutation": False,
+                  "governed_mutation": True},
+        # §138 — interop fields a sibling forge can negotiate against
+        "quality_level": "self-eval",   # no external audit claimed
+        "maturity": "beta",
+        "required_evidence": {"findings": "evidence_fact_ids non-empty",
+                              "tiers": "0-5 only — T6/T7 cannot be facts"},
+        "cost_characteristics": {
+            c.name: c.cost_class for c in CAPABILITIES.values()},
+        "risk": {c.name: c.risk for c in CAPABILITIES.values()},
+        "operations": ops_capabilities(),
+        "cross_forge": delegation_contract(),
+        # cycle5 — enterprise intelligence surface (bounded summaries)
+        "fleet": {"contracts": ["platformforge/fleet/v1",
+                                "platformforge/fleet-snapshot/v1",
+                                "platformforge/node-manifest/v1",
+                                "platformforge/federation-summary/v1"],
+                  "questions": ["public-services", "critical-services",
+                                "unsupported-k8s", "wildcard-iam",
+                                "unowned", "no-slo",
+                                "outside-golden-path", "idle-high-cost",
+                                "cross-env-deps"],
+                  "layers": ["organization", "platform-product",
+                             "application", "infrastructure",
+                             "runtime", "operations", "cost", "policy"]},
+        "analytics": {"windows": ["24h", "7d", "30d", "90d", "custom"],
+                      "engines": ["history", "policy-intelligence",
+                                  "golden-path", "capacity",
+                                  "reliability", "finops-v4",
+                                  "measurement"],
+                      "guarantees": ["deterministic-aggregates",
+                                     "unknown-never-zero",
+                                     "coverage-first-class"]},
+        "optimization": {"output": "OptimizationRecommendation",
+                         "boundary": "ChangeIntent only — never "
+                                     "executes (§211)",
+                         "pipeline": ["evidence", "pattern",
+                                      "opportunity", "recommendation",
+                                      "change-intent", "ops"]},
+        "ai_platform": {"awareness": ["gpu", "accelerator",
+                                      "model_serving", "inference",
+                                      "training", "vector_store"],
+                        "unit_economics": "denominator-required",
+                        "boundary": "platform-level only — no AI Forge"},
+        "domains": sorted({r.domain for r in rules if r.domain} |
+                          {"iac", "k8s", "gitops", "cicd", "sre", "finops",
+                           "security", "product", "graph", "live"}),
+        "supported_versions": _supported_versions(),
+        "tools": sorted(CAPABILITIES),
+        "capabilities_v2": [c.contract() for c in CAPABILITIES.values()],
+        "rule_count": len(rules),
+        "rules": sorted(r.rule_id for r in rules),
+        "graph_vocab": {"node_kinds": sorted(NODE_KINDS),
+                        "edge_kinds": sorted(EDGE_KINDS)},
+        "evidence_tiers": 8,
+        "contracts": sorted(p.stem.replace(".schema", "")
+                            for p in (root / "contracts").glob("*.schema.json")),
+    }
+
+
+def _supported_versions() -> dict[str, str]:
+    """§139/§144 — versions the knowledge registry has evidence for.
+    Absence of a product here means 'unresolved', not 'unsupported'."""
+    try:
+        from platformforge.knowledge.registry import SourceRegistry
+        reg = SourceRegistry.default()
+    except (OSError, ValueError):
+        return {}
+    out: dict[str, str] = {}
+    for e in reg.entries.values():
+        if e.product and e.version:
+            out.setdefault(e.product, e.version)
+    return dict(sorted(out.items()))

platformforge/freeze/__init__.py

@@ -0,0 +1,22 @@
+"""Freeze governance (prompt_evo_freezing §4–6).
+
+Manifest is *generated* from live registries (contracts dir, capability
+registry, CLI parser, MCP tools, agent roster) — never hand-maintained.
+"""
+
+from platformforge.freeze.exceptions import FeatureException, exception_errors
+from platformforge.freeze.manifest import build_manifest
+from platformforge.freeze.snapshots import (
+    build_snapshots,
+    check_snapshots,
+    write_snapshots,
+)
+
+__all__ = [
+    "FeatureException",
+    "build_manifest",
+    "build_snapshots",
+    "check_snapshots",
+    "exception_errors",
+    "write_snapshots",
+]

platformforge/freeze/exceptions.py

@@ -0,0 +1,56 @@
+"""FeatureException — the only door for new capability during freeze
+(§6). A request that cannot prove a real-world blocker is refused."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+REQUIRED = (
+    "id", "requested_capability", "reason", "real_world_blocker",
+    "existing_capability_insufficient", "alternatives_considered",
+    "architectural_impact", "schema_impact", "agent_impact",
+    "operations_impact", "decision",
+)
+DECISIONS = ("approved", "rejected", "deferred")
+
+
+@dataclass(frozen=True)
+class FeatureException:
+    id: str = ""
+    requested_capability: str = ""
+    reason: str = ""
+    real_world_blocker: str = ""
+    existing_capability_insufficient: str = ""
+    alternatives_considered: tuple[str, ...] = ()
+    architectural_impact: str = "none"
+    schema_impact: str = "none"
+    agent_impact: str = "none"
+    operations_impact: str = "none"
+    decision: str = "rejected"
+    decided_by: str = ""
+    evidence: tuple[str, ...] = ()
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        d = {k: getattr(self, k) for k in REQUIRED}
+        d["alternatives_considered"] = list(self.alternatives_considered)
+        d["decided_by"] = self.decided_by
+        d["evidence"] = list(self.evidence)
+        d["schema"] = "platformforge/feature-exception/v1"
+        return d
+
+
+def exception_errors(d: dict[str, Any]) -> list[str]:
+    """§6 — every field required; decision must be in the closed set;
+    approval requires a named real_world_blocker + evidence."""
+    errs = [f"missing field: {k}" for k in REQUIRED if not d.get(k)]
+    if d.get("decision") and d["decision"] not in DECISIONS:
+        errs.append(f"decision {d['decision']!r} not in {DECISIONS}")
+    if d.get("decision") == "approved":
+        if not d.get("real_world_blocker"):
+            errs.append("approved exception without real_world_blocker")
+        if not d.get("evidence"):
+            errs.append("approved exception without evidence")
+        if d.get("architectural_impact") in ("", "unknown"):
+            errs.append("approved exception with unassessed architectural_impact")
+    return errs