platformforge 0.1.0__py3-none-any.whl

platformforge/freeze/manifest.py

@@ -0,0 +1,167 @@
+"""§4 — FREEZE-MANIFEST generated from live registries. Every entry is
+computed, so the manifest can't silently drift from the code."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+SCHEMA = "platformforge/freeze-manifest/v1"
+CONTRACTS = Path(__file__).resolve().parents[2] / "contracts"
+
+
+def _cli_verbs() -> list[str]:
+    from platformforge.cli.main import build_parser
+    p = build_parser()
+    sub = next(a for a in p._actions if hasattr(a, "choices") and a.choices)
+    return sorted(sub.choices)
+
+
+def _mcp_tools() -> list[str]:
+    from platformforge.mcp.registry import tool_descriptors
+    return sorted(t["name"] for t in tool_descriptors())
+
+
+def _capabilities() -> dict[str, Any]:
+    from platformforge.mcp.registry import CAPABILITIES
+    contracts = [c.contract() for c in CAPABILITIES.values()]
+    return {"count": len(contracts),
+            "ids": sorted(c.get("name", c.get("id", "?")) for c in contracts)}
+
+
+def _schemas() -> dict[str, Any]:
+    files = sorted(p.name for p in CONTRACTS.glob("*.schema.json"))
+    return {"count": len(files), "files": files}
+
+
+def _agents() -> dict[str, Any]:
+    from platformforge.agents.roster import AGENTS
+    by_role: dict[str, int] = {}
+    for a in AGENTS.values():
+        by_role[a.role] = by_role.get(a.role, 0) + 1
+    return {"count": len(AGENTS), "by_role": by_role,
+            "names": sorted(AGENTS)}
+
+
+def _knowledge_packs() -> dict[str, Any]:
+    kroot = Path(__file__).resolve().parents[2] / "knowledge"
+    packs = sorted(p.name for p in kroot.iterdir() if p.is_dir())
+    srcs = 0
+    import yaml
+    sf = kroot / "sources.yaml"
+    if sf.exists():
+        srcs = len(yaml.safe_load(sf.read_text()) or {})
+    return {"packs": packs, "sources": srcs}
+
+
+STABILITY = {
+    # §4 — honest stability labels, not aspirational ones
+    "stable": [
+        "fact/finding/graph contracts", "judge rule engine",
+        "graphfy query surface", "change sandbox review",
+        "tokensave/economy", "lab + evals harness", "MCP server",
+    ],
+    "experimental": [
+        "agentic runtime (router v2, coordinators, debate)",
+        "fleet analytics + optimization engine", "federation export",
+        "ai platform awareness", "connected live collectors",
+    ],
+    "internal": [
+        "sdd lifecycle machinery", "forge interop envelope",
+        "freeze governance (this module)",
+    ],
+}
+
+KNOWN_GAPS = [
+    "agent benchmarks are router projections, not measured model spends",
+    "analytics store is single-node SQLite (no concurrent writers)",
+    "graph scale beyond 10k nodes / 500k edges is unsupported-on-host here",
+    "no production evidence — nothing is production-validated",
+    "connected (AWS/k8s) validation requires host credentials — offline by default",
+]
+
+PRODUCTION_UNVALIDATED = [
+    "every capability — no production telemetry exists in this repo",
+]
+
+
+def build_manifest() -> dict[str, Any]:
+    import platform
+    import subprocess
+    sha = subprocess.run(["git", "rev-parse", "HEAD"], check=False,
+                         capture_output=True, text=True).stdout.strip()
+    existing = Path("docs/freeze/FREEZE-MANIFEST.md")
+    if existing.is_file():
+        import re
+        prev = re.search(r"freeze_start_sha: `([0-9a-f]{40})`",
+                         existing.read_text())
+        if prev:
+            sha = prev.group(1)
+    return {
+        "schema": SCHEMA,
+        "freeze_start_sha": sha,
+        "python": platform.python_version(),
+        "lifecycle": ["open-development", "freeze-candidate",
+                      "architecture-frozen", "dogfooding",
+                      "release-candidate", "stable"],
+        "lifecycle_state": "dogfooding",
+        "public_schemas": _schemas(),
+        "cli_surfaces": _cli_verbs(),
+        "mcp_surfaces": _mcp_tools(),
+        "capabilities": _capabilities(),
+        "agent_contracts": _agents(),
+        "knowledge_packs": _knowledge_packs(),
+        "stability": STABILITY,
+        "known_gaps": KNOWN_GAPS,
+        "production_unvalidated_claims": PRODUCTION_UNVALIDATED,
+        "supported_runtimes": ["python 3.10", "python 3.11",
+                               "python 3.12", "python 3.13"],
+    }
+
+
+def render_markdown(m: dict[str, Any]) -> str:
+    a = m["agent_contracts"]
+    lines = [
+        "# FREEZE-MANIFEST",
+        "",
+        "Generated from live registries — `platformforge freeze manifest`.",
+        "",
+        f"- freeze_start_sha: `{m['freeze_start_sha']}`",
+        (f"- lifecycle state: **{m['lifecycle_state']}** "
+         f"({' → '.join(m['lifecycle'])})"),
+        (f"- python: {m['python']} (supported: "
+         f"{', '.join(m['supported_runtimes'])})"),
+        "",
+        "## Surfaces",
+        "",
+        (f"- public schemas: {m['public_schemas']['count']} "
+         f"(contracts/*.schema.json)"),
+        (f"- CLI verbs: {len(m['cli_surfaces'])} — "
+         f"{', '.join(m['cli_surfaces'])}"),
+        f"- MCP tools: {len(m['mcp_surfaces'])}",
+        f"- capabilities: {m['capabilities']['count']}",
+        (f"- agents: {a['count']} "
+         f"({', '.join(f'{r}:{n}' for r, n in sorted(a['by_role'].items()))})"),
+        (f"- knowledge packs: {', '.join(m['knowledge_packs']['packs'])} "
+         f"({m['knowledge_packs']['sources']} registered sources)"),
+        "",
+        "## Stability labels",
+        "",
+    ]
+    for k, v in m["stability"].items():
+        lines += [f"**{k}**", ""] + [f"- {x}" for x in v] + [""]
+    lines += ["## Known gaps", ""]
+    lines += [f"- {x}" for x in m["known_gaps"]]
+    lines += ["", "## Production-unvalidated claims", ""]
+    lines += [f"- {x}" for x in m["production_unvalidated_claims"]]
+    return "\n".join(lines) + "\n"
+
+
+def write_manifest(path: str | Path) -> dict[str, Any]:
+    m = build_manifest()
+    Path(path).write_text(render_markdown(m), encoding="utf-8")
+    return m
+
+
+if __name__ == "__main__":  # pragma: no cover
+    print(json.dumps(build_manifest(), indent=2, sort_keys=True))

platformforge/freeze/snapshots.py

@@ -0,0 +1,108 @@
+"""§7/§196 — contract snapshots + breaking-change detection.
+
+Snapshot = {name: {id: sha256}} over contracts/, CLI verbs, MCP tools,
+capabilities, agent roster. `check` diffs current vs stored and reports
+drift as added/removed/changed. Knowledge version bumps are allowlisted.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import subprocess
+from pathlib import Path
+from typing import Any
+
+SNAP_DIR = Path("docs/freeze/snapshots")
+
+# changes in these snapshot families are informational, not breaking
+ALLOWLIST = ("knowledge",)
+
+
+def _h(s: str | bytes) -> str:
+    return hashlib.sha256(s if isinstance(s, bytes) else s.encode()).hexdigest()
+
+
+def build_snapshots(repo: str | Path = ".") -> dict[str, Any]:
+    repo = Path(repo)
+    snaps: dict[str, Any] = {}
+
+    # schemas — hash of each file's content
+    snaps["schemas"] = {
+        p.name: _h(p.read_bytes())
+        for p in sorted((repo / "contracts").glob("*.schema.json"))
+    }
+
+    from platformforge.cli.main import build_parser
+    p = build_parser()
+    sub = next(a for a in p._actions if hasattr(a, "choices") and a.choices)
+    snaps["cli"] = {v: _h(v) for v in sorted(sub.choices)}
+
+    from platformforge.mcp.registry import tool_descriptors
+    snaps["mcp"] = {t["name"]: _h(t["name"]) for t in tool_descriptors()}
+
+    from platformforge.mcp.registry import CAPABILITIES
+    snaps["capabilities"] = {
+        c.name: _h(json.dumps(c.contract(), sort_keys=True, default=str))
+        for c in CAPABILITIES.values()
+    }
+
+    from platformforge.agents.roster import AGENTS
+    snaps["agents"] = {
+        n: _h(json.dumps(
+            {f: getattr(a, f) for f in a.__dataclass_fields__
+             if isinstance(getattr(a, f), (str, int, bool, list, tuple))
+             } | {"role": a.role}, sort_keys=True, default=str))
+        for n, a in sorted(AGENTS.items())
+    }
+
+    # knowledge packs — allowlisted (version bumps expected, not breaking)
+    kroot = repo / "knowledge"
+    snaps["knowledge"] = {
+        str(p.relative_to(kroot)): _h(p.read_bytes())
+        for p in sorted(kroot.rglob("*.yaml")) + sorted(kroot.rglob("*.md"))
+    } if kroot.exists() else {}
+
+    return snaps
+
+
+def write_snapshots(repo: str | Path = ".", out: str | Path = SNAP_DIR) -> Path:
+    out = Path(out)
+    out.mkdir(parents=True, exist_ok=True)
+    sha = subprocess.run(["git", "rev-parse", "HEAD"], check=False,
+                         capture_output=True, text=True).stdout.strip()
+    for name, entries in build_snapshots(repo).items():
+        (out / f"{name}.json").write_text(json.dumps(
+            {"schema": "platformforge/freeze-snapshot/v1",
+             "family": name, "sha": sha, "entries": entries},
+            indent=2, sort_keys=True) + "\n")
+    return out
+
+
+def check_snapshots(repo: str | Path = ".", snap_dir: str | Path = SNAP_DIR
+                    ) -> dict[str, Any]:
+    """Returns {'breaking': [...], 'allowed': [...], 'missing': [...]} —
+    breaking = changed/removed non-allowlisted entries."""
+    snap_dir = Path(snap_dir)
+    current = build_snapshots(repo)
+    breaking: list[str] = []
+    allowed: list[str] = []
+    missing: list[str] = []
+    for name, entries in current.items():
+        f = snap_dir / f"{name}.json"
+        if not f.exists():
+            missing.append(name)
+            continue
+        old = json.loads(f.read_text())["entries"]
+        for k, h in entries.items():
+            tag = f"{name}:{k}"
+            if k not in old:
+                (allowed if name in ALLOWLIST else breaking).append(f"added {tag}")
+            elif old[k] != h:
+                (allowed if name in ALLOWLIST else breaking).append(f"changed {tag}")
+        for k in old:
+            if k not in entries:
+                (allowed if name in ALLOWLIST else breaking).append(f"removed {name}:{k}")
+    verdict = "pass" if not breaking else "fail"
+    return {"schema": "platformforge/freeze-check/v1",
+            "verdict": verdict, "breaking": breaking,
+            "allowed": allowed, "missing": missing}

platformforge/graph/__init__.py

@@ -0,0 +1,39 @@
+"""Graphfy — the platform graph. Facts in, provenanced graph out."""
+
+from platformforge.graph.build import GraphBuilder
+from platformforge.graph.diff import SEMANTIC_CATEGORIES, diff
+from platformforge.graph.model import Edge, Graph, Node, node_id
+from platformforge.graph.persist import (
+                                         SOURCE_TYPES,
+                                         load,
+                                         load_snapshot,
+                                         save,
+                                         snapshot_meta,
+                                         snapshot_meta_of,
+                                         snapshots,
+)
+from platformforge.graph.query import blast_radius, cycles, dependencies, dependents, gaps, neighbors, paths
+
+__all__ = [
+                                         "SEMANTIC_CATEGORIES",
+                                         "SOURCE_TYPES",
+                                         "Edge",
+                                         "Graph",
+                                         "GraphBuilder",
+                                         "Node",
+                                         "blast_radius",
+                                         "cycles",
+                                         "dependencies",
+                                         "dependents",
+                                         "diff",
+                                         "gaps",
+                                         "load",
+                                         "load_snapshot",
+                                         "neighbors",
+                                         "node_id",
+                                         "paths",
+                                         "save",
+                                         "snapshot_meta",
+                                         "snapshot_meta_of",
+                                         "snapshots",
+]

platformforge/graph/backend.py

@@ -0,0 +1,174 @@
+"""Cycle 5 §32–35 — pluggable graph storage.
+
+`GraphBackend` is a narrow contract: put/get/del nodes & edges,
+iterate, count. `MemoryBackend` preserves today's behaviour;
+`SQLiteBackend` gives a local indexed baseline for larger graphs.
+An external graph DB would be an adapter implementing the same
+contract — never hardwired (§35).
+
+The canonical representation stays provider-neutral `Graph`
+(document dicts); backends are storage detail.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from platformforge.graph.model import Edge, Graph, Node
+
+
+class GraphBackend(ABC):
+    @abstractmethod
+    def put_graph(self, graph: Graph, name: str = "default") -> None: ...
+    @abstractmethod
+    def get_graph(self, name: str = "default") -> Graph: ...
+    @abstractmethod
+    def counts(self, name: str = "default") -> dict[str, int]: ...
+    @abstractmethod
+    def neighbors(self, node_id: str, name: str = "default",
+                  direction: str = "both") -> list[Edge]: ...
+    @abstractmethod
+    def close(self) -> None: ...
+
+
+class MemoryBackend(GraphBackend):
+    """Default: same in-process dict storage as today."""
+
+    def __init__(self):
+        self._graphs: dict[str, Graph] = {}
+
+    def put_graph(self, graph: Graph, name: str = "default") -> None:
+        self._graphs[name] = graph
+
+    def get_graph(self, name: str = "default") -> Graph:
+        return self._graphs.get(name, Graph())
+
+    def counts(self, name: str = "default") -> dict[str, int]:
+        g = self.get_graph(name)
+        return {"nodes": len(g.nodes), "edges": len(g.edges)}
+
+    def neighbors(self, node_id: str, name: str = "default",
+                  direction: str = "both") -> list[Edge]:
+        g = self.get_graph(name)
+        out = []
+        for e in g.edges.values():
+            if direction in ("out", "both") and e.src == node_id or direction in ("in", "both") and e.dst == node_id:
+                out.append(e)
+        return out
+
+    def close(self) -> None:
+        pass
+
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS nodes (
+  graph TEXT NOT NULL, node_id TEXT NOT NULL, kind TEXT NOT NULL,
+  label TEXT NOT NULL, doc TEXT NOT NULL,
+  PRIMARY KEY (graph, node_id));
+CREATE INDEX IF NOT EXISTS idx_nodes_kind ON nodes(graph, kind);
+CREATE TABLE IF NOT EXISTS edges (
+  graph TEXT NOT NULL, eid TEXT NOT NULL, src TEXT NOT NULL,
+  dst TEXT NOT NULL, kind TEXT NOT NULL, doc TEXT NOT NULL,
+  PRIMARY KEY (graph, eid));
+CREATE INDEX IF NOT EXISTS idx_edges_src ON edges(graph, src);
+CREATE INDEX IF NOT EXISTS idx_edges_dst ON edges(graph, dst);
+CREATE INDEX IF NOT EXISTS idx_edges_kind ON edges(graph, kind);
+CREATE TABLE IF NOT EXISTS meta (
+  graph TEXT PRIMARY KEY, doc TEXT NOT NULL);
+"""
+
+
+class SQLiteBackend(GraphBackend):
+    """Local indexed baseline (§34). One file per store; graphs are
+    namespaced rows. Adjacency queries hit indexes, not full scans
+    (§31)."""
+
+    def __init__(self, path: str | Path):
+        self._db = sqlite3.connect(str(path))
+        self._db.executescript(_SCHEMA)
+        self._db.commit()
+
+    def put_graph(self, graph: Graph, name: str = "default") -> None:
+        cur = self._db.cursor()
+        cur.execute("DELETE FROM nodes WHERE graph=?", (name,))
+        cur.execute("DELETE FROM edges WHERE graph=?", (name,))
+        cur.executemany(
+            "INSERT INTO nodes VALUES (?,?,?,?,?)",
+            [(name, n.node_id, n.kind, n.label,
+              json.dumps(n.to_dict(), sort_keys=True))
+             for n in graph.nodes.values()])
+        cur.executemany(
+            "INSERT INTO edges VALUES (?,?,?,?,?,?)",
+            [(name, e.eid, e.src, e.dst, e.kind,
+              json.dumps(e.to_dict(), sort_keys=True))
+             for e in graph.edges.values()])
+        cur.execute(
+            "INSERT OR REPLACE INTO meta VALUES (?,?)",
+            (name, json.dumps(graph.meta, sort_keys=True)))
+        self._db.commit()
+
+    def get_graph(self, name: str = "default") -> Graph:
+        g = Graph()
+        row = self._db.execute(
+            "SELECT doc FROM meta WHERE graph=?", (name,)).fetchone()
+        if row:
+            g.meta.update(json.loads(row[0]))
+        for (doc,) in self._db.execute(
+                "SELECT doc FROM nodes WHERE graph=?", (name,)):
+            n = json.loads(doc)
+            g.nodes[n["node_id"]] = Node(
+                node_id=n["node_id"], kind=n["kind"], label=n["label"],
+                attrs=n.get("attrs", {}),
+                source_fact_ids=tuple(n.get("source_fact_ids", ())))
+        for (doc,) in self._db.execute(
+                "SELECT doc FROM edges WHERE graph=?", (name,)):
+            e = json.loads(doc)
+            edge = Edge(src=e["from"], dst=e["to"], kind=e["kind"],
+                        provenance=e.get("provenance", "declared"),
+                        confidence=e.get("confidence", 1.0),
+                        source_fact_ids=tuple(e.get("source_fact_ids", ())),
+                        attrs=e.get("attrs", {}),
+                        evidence=tuple(e.get("evidence", ())),
+                        temporal=e.get("temporal", {}))
+            g.edges[edge.eid] = edge
+        return g
+
+    def counts(self, name: str = "default") -> dict[str, int]:
+        n = self._db.execute(
+            "SELECT COUNT(*) FROM nodes WHERE graph=?", (name,)).fetchone()
+        e = self._db.execute(
+            "SELECT COUNT(*) FROM edges WHERE graph=?", (name,)).fetchone()
+        return {"nodes": n[0], "edges": e[0]}
+
+    def neighbors(self, node_id: str, name: str = "default",
+                  direction: str = "both") -> list[Edge]:
+        clauses = {"out": "src=?", "in": "dst=?", "both": "(src=? OR dst=?)"}
+        params = [name, node_id] if direction != "both" else \
+            [name, node_id, node_id]
+        out = []
+        for (doc,) in self._db.execute(
+                f"SELECT doc FROM edges WHERE graph=? AND "
+                f"{clauses[direction]}", params):
+            e = json.loads(doc)
+            out.append(Edge(src=e["from"], dst=e["to"], kind=e["kind"],
+                            provenance=e.get("provenance", "declared"),
+                            confidence=e.get("confidence", 1.0),
+                            source_fact_ids=tuple(
+                                e.get("source_fact_ids", ())),
+                            attrs=e.get("attrs", {}),
+                            evidence=tuple(e.get("evidence", ())),
+                            temporal=e.get("temporal", {})))
+        return out
+
+    def close(self) -> None:
+        self._db.close()
+
+
+def open_backend(spec: str | None = None) -> GraphBackend:
+    """`memory` (default) or `sqlite:<path>`."""
+    if spec and spec.startswith("sqlite:"):
+        return SQLiteBackend(spec.split(":", 1)[1])
+    return MemoryBackend()