platformforge 0.1.0__py3-none-any.whl

platformforge/knowledge/packs.py

@@ -0,0 +1,157 @@
+"""Knowledge packs — operational knowledge, not a provenance registry
+(cycle 2.1 §60–68).
+
+A pack is a YAML document under ``knowledge/<domain>/<id>.yaml``:
+
+```yaml
+schema: platformforge/knowledge/v1
+id: kubernetes-api-deprecations
+domain: kubernetes
+applies_to: {versions: [kubernetes]}
+sources: [kubernetes-docs]
+claims:
+  - id: k8s-dep-v122
+    statement: "..."
+    versions: {kubernetes: ">=1.22"}
+used_by:
+  rules: [PF-K8S-030]
+  analyzers: [k8s]
+```
+
+Consumption is checked, not asserted: ``contract_check`` resolves every
+``sources`` id against the source registry, every ``used_by.rules`` against
+the rule catalog, and every ``used_by.analyzers`` against the analyzer
+registry — a pack nothing consumes is dead weight (§63/§136). Each pack
+carries a ``content_hash`` (sha256 of the canonical claim set) so consumers
+detect drift when content changes (§68).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+SCHEMA = "platformforge/knowledge/v1"
+
+
+@dataclass(frozen=True)
+class Claim:
+    claim_id: str
+    statement: str
+    versions: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Pack:
+    pack_id: str
+    domain: str
+    applies_to: dict[str, Any]
+    sources: tuple[str, ...]
+    claims: tuple[Claim, ...]
+    used_by: dict[str, list[str]]
+    path: str = ""
+
+    @property
+    def content_hash(self) -> str:
+        """§68 — sha256 over the canonical claim set; drift detectable."""
+        blob = json.dumps({
+            "id": self.pack_id,
+            "claims": [{"id": c.claim_id, "statement": c.statement,
+                        "versions": c.versions} for c in self.claims],
+        }, sort_keys=True)
+        return hashlib.sha256(blob.encode()).hexdigest()[:16]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"id": self.pack_id, "domain": self.domain,
+                "path": self.path, "content_hash": self.content_hash,
+                "sources": list(self.sources),
+                "claims": [{"id": c.claim_id, "statement": c.statement,
+                            "versions": c.versions} for c in self.claims],
+                "used_by": self.used_by}
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any], path: str = "") -> Pack:
+        if d.get("schema") != SCHEMA:
+            raise ValueError(f"{path or d.get('id')}: schema must be "
+                             f"{SCHEMA}")
+        missing = [k for k in ("id", "domain", "sources", "claims")
+                   if k not in d]
+        if missing:
+            raise ValueError(f"{d.get('id', path)}: missing {missing}")
+        claims = tuple(Claim(str(c["id"]), str(c["statement"]),
+                             dict(c.get("versions") or {}))
+                       for c in d["claims"])
+        return cls(pack_id=str(d["id"]), domain=str(d["domain"]),
+                   applies_to=dict(d.get("applies_to") or {}),
+                   sources=tuple(str(s) for s in d["sources"]),
+                   claims=claims,
+                   used_by=dict(d.get("used_by") or {}), path=path)
+
+
+class PackRegistry:
+    def __init__(self, root: str | Path | None = None):
+        if root is None:
+            from platformforge.resources import data_path
+            root = data_path("knowledge")
+        self.root = Path(root)
+        self.packs: dict[str, Pack] = {}
+        if self.root.is_dir():
+            for f in sorted(self.root.rglob("*.yaml")):
+                if f.name == "sources.yaml":
+                    continue
+                d = yaml.safe_load(f.read_text())
+                if not isinstance(d, dict) or d.get("schema") != SCHEMA:
+                    continue
+                p = Pack.from_dict(d, path=str(f.relative_to(self.root)))
+                self.packs[p.pack_id] = p
+
+    @classmethod
+    def default(cls) -> PackRegistry:
+        return cls()
+
+    def for_rule(self, rule_id: str) -> list[Pack]:
+        return [p for p in self.packs.values()
+                if rule_id in (p.used_by.get("rules") or [])]
+
+    def for_analyzer(self, name: str) -> list[Pack]:
+        return [p for p in self.packs.values()
+                if name in (p.used_by.get("analyzers") or [])]
+
+    def contract_check(self) -> dict[str, Any]:
+        """Every pack consumed by something real: sources resolve against
+        the registry, rules against the catalog, analyzers against the lab
+        analyzer table."""
+        from platformforge.knowledge.registry import SourceRegistry
+        from platformforge.lab.runner import _ANALYZERS
+        from platformforge.resources import data_path
+        from platformforge.rules import load_catalog
+        sources = SourceRegistry.default().entries
+        rules = {r.rule_id
+                 for r in load_catalog(data_path("rules", "catalog"))}
+        problems: list[dict[str, Any]] = []
+        consumed = 0
+        for p in sorted(self.packs.values(), key=lambda x: x.pack_id):
+            bad_src = [s for s in p.sources if s not in sources]
+            bad_rules = [r for r in p.used_by.get("rules", [])
+                         if r not in rules]
+            bad_an = [a for a in p.used_by.get("analyzers", [])
+                      if a not in _ANALYZERS]
+            if not p.used_by.get("rules") and not p.used_by.get("analyzers"):
+                problems.append({"pack": p.pack_id, "issue": "unconsumed"})
+            else:
+                consumed += 1
+            for kind, ids in (("unknown_source", bad_src),
+                              ("unknown_rule", bad_rules),
+                              ("unknown_analyzer", bad_an)):
+                for i in ids:
+                    problems.append({"pack": p.pack_id, "issue": kind,
+                                     "ref": i})
+            if not p.claims:
+                problems.append({"pack": p.pack_id, "issue": "no_claims"})
+        return {"packs": len(self.packs), "consumed": consumed,
+                "problems": problems, "ok": not problems}

platformforge/knowledge/registry.py

@@ -0,0 +1,249 @@
+"""Source registry + knowledge freshness.
+
+Old documentation is never eternal truth. Every version-dependent claim cites
+a source entry; freshness is computed, not assumed.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from datetime import date, datetime, timezone
+
+UTC = timezone.utc  # datetime.UTC alias is 3.11+; keep 3.10 compatible
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from platformforge.models import FreshnessStatus
+
+FRESH_DAYS = 120       # verified within ~4 months
+STALE_DAYS = 365       # older than a year → stale by default
+
+# Closed vocabulary for `source_authority` — asserted by the CI gate.
+SOURCE_AUTHORITIES = ("official", "vendor-research", "first-party-sibling")
+
+
+@dataclass
+class SourceEntry:
+    id: str
+    source: str
+    source_authority: str = "unknown"
+    retrieved_at: str = ""
+    product: str = ""
+    version: str = ""
+    releases_tracked: list[str] = field(default_factory=list)
+    scope: str = ""
+    cloud: str = ""
+    deprecated: bool = False
+    superseded_by: str = ""
+    valid_from: str = ""
+    valid_until: str = ""
+    confidence: str = "medium"
+    notes: str = ""
+    aliases: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> SourceEntry:
+        known = {f for f in cls.__dataclass_fields__}
+        return cls(**{k: v for k, v in d.items() if k in known})
+
+    def freshness(self, today: date | None = None) -> str:
+        """current|fresh|stale|deprecated|superseded|conflicted|unresolved."""
+        today = today or datetime.now(UTC).date()
+        if self.deprecated:
+            return FreshnessStatus.DEPRECATED
+        if self.superseded_by:
+            return FreshnessStatus.SUPERSEDED
+        if self.valid_until and str(self.valid_until) < today.isoformat():
+            return FreshnessStatus.STALE
+        if self.valid_from and str(self.valid_from) > today.isoformat():
+            return FreshnessStatus.UNRESOLVED
+        if not self.retrieved_at:
+            return FreshnessStatus.UNRESOLVED
+        try:
+            days = (today - date.fromisoformat(str(self.retrieved_at)[:10])).days
+        except ValueError:
+            return FreshnessStatus.UNRESOLVED
+        if days <= FRESH_DAYS:
+            return FreshnessStatus.CURRENT if days <= 30 else FreshnessStatus.FRESH
+        return FreshnessStatus.STALE if days > STALE_DAYS else FreshnessStatus.FRESH
+
+
+class SourceRegistry:
+    def __init__(self, path: str | Path):
+        self.path = Path(path)
+        doc = yaml.safe_load(self.path.read_text())
+        self.schema = doc.get("schema", "")
+        self.entries: dict[str, SourceEntry] = {}
+        self.duplicate_ids: list[str] = []
+        for e in doc.get("sources", []):
+            if e["id"] in self.entries:
+                self.duplicate_ids.append(e["id"])
+                continue
+            self.entries[e["id"]] = SourceEntry.from_dict(e)
+
+    @classmethod
+    def default(cls) -> SourceRegistry:
+        from platformforge.resources import data_path
+        return cls(data_path("knowledge", "sources.yaml"))
+
+    def get(self, source_id: str) -> SourceEntry | None:
+        return self.entries.get(source_id)
+
+    def resolve(self, ref: str) -> SourceEntry | None:
+        """Canonical id, else explicit `aliases:` declared on an entry.
+        No inference — a ref that is neither is unresolvable."""
+        if ref in self.entries:
+            return self.entries[ref]
+        for e in self.entries.values():
+            if ref in e.aliases:
+                return e
+        return None
+
+    def check(self, today: date | None = None) -> list[dict[str, Any]]:
+        """Freshness report for every registered source."""
+        return [
+            {"id": e.id, "product": e.product, "version": e.version,
+             "retrieved_at": e.retrieved_at, "status": e.freshness(today),
+             "superseded_by": e.superseded_by}
+            for e in sorted(self.entries.values(), key=lambda x: x.id)
+        ]
+
+    def unresolved(self, today: date | None = None) -> list[str]:
+        return [r["id"] for r in self.check(today) if r["status"] in
+                (FreshnessStatus.UNRESOLVED, FreshnessStatus.CONFLICTED)]
+
+
+    # §46 — knowledge entry contract: these fields are mandatory for an
+    # entry to count as knowledge-backed.
+    REQUIRED = ("id", "source", "source_authority", "retrieved_at",
+                "confidence")
+
+    def contract_check(self) -> dict[str, Any]:
+        """§46 — report entries missing contract fields, duplicate ids,
+        and alias collisions (an alias owned by two entries resolves to
+        whichever loads first — silent wrong-linkage)."""
+        bad = {}
+        for e in self.entries.values():
+            missing = [f for f in self.REQUIRED
+                       if not getattr(e, f, None)]
+            if missing:
+                bad[e.id or "?"] = missing
+        alias_owner: dict[str, str] = {}
+        alias_collisions: dict[str, list[str]] = {}
+        for e in self.entries.values():
+            for a in e.aliases:
+                if a in alias_owner and alias_owner[a] != e.id:
+                    alias_collisions.setdefault(a, []).append(e.id)
+                else:
+                    alias_owner[a] = e.id
+        for a, owners in alias_collisions.items():
+            owners.insert(0, alias_owner[a])
+        ok = not bad and not self.duplicate_ids and not alias_collisions
+        return {"entries": len(self.entries), "invalid": bad,
+                "duplicate_ids": self.duplicate_ids,
+                "alias_collisions": alias_collisions,
+                "ok": ok}
+
+    def link_rules(self, *catalog_dirs: str | Path) -> dict[str, Any]:
+        """§44/§47 + cycle 2.1 — rule→source linkage by exact canonical id.
+
+        Every `sources:` entry on a rule must be a registered id (or an
+        entry's explicit `aliases:` member). No domain-suffix inference —
+        `k8s.io` must never silently match `gateway-api.sigs.k8s.io`.
+        Unresolvable refs are reported `unlinked`, not silently trusted.
+        """
+        from platformforge.rules import load_catalog
+        linked, unlinked, bad_refs = {}, [], []
+        for r in load_catalog(*catalog_dirs):
+            hits = [{"source": s,
+                     "entry": (self.resolve(s) or SourceEntry(
+                         id="", source="")).id or None}
+                    for s in r.sources]
+            if hits and all(h["entry"] for h in hits):
+                linked[r.rule_id] = [h["entry"] for h in hits]
+            else:
+                unlinked.append({"rule_id": r.rule_id, "sources": hits})
+            dangling = sorted(k for k in getattr(r, "source_refs", {})
+                              if k not in r.sources)
+            if dangling:
+                bad_refs.append({"rule_id": r.rule_id,
+                                 "source_refs": dangling})
+        return {"linked": linked, "unlinked": unlinked, "bad_refs": bad_refs,
+                "coverage": len(linked) / max(len(linked) + len(unlinked), 1)}
+
+    def drift_report(self, *catalog_dirs: str | Path,
+                     today: date | None = None) -> dict[str, Any]:
+        """§47 — knowledge drift: new major versions tracked but not
+        reflected, deprecated/superseded sources still cited, unavailable
+        sources, and rules whose backing sources went stale.
+
+        Never a bare "ok": every signal carries the entry/rule it
+        concerns and the reason."""
+        today = today or datetime.now(UTC).date()
+        link = self.link_rules(*catalog_dirs)
+        statuses = {r["id"]: r for r in self.check(today)}
+
+        signals: list[dict[str, Any]] = []
+        for e in sorted(self.entries.values(), key=lambda x: x.id):
+            st = statuses.get(e.id, {}).get("status", "unresolved")
+            if st in (FreshnessStatus.DEPRECATED,):
+                signals.append({"kind": "deprecated-source",
+                                "source": e.id,
+                                "reason": "entry marked deprecated"})
+            if st in (FreshnessStatus.SUPERSEDED,):
+                signals.append({"kind": "superseded-source",
+                                "source": e.id,
+                                "reason": f"superseded_by={e.superseded_by}"})
+            if st in (FreshnessStatus.STALE, FreshnessStatus.UNRESOLVED):
+                signals.append({"kind": "stale-source", "source": e.id,
+                                "reason": f"freshness={st}"})
+            if not e.source:
+                signals.append({"kind": "unavailable-source",
+                                "source": e.id,
+                                "reason": "no source locator"})
+            # new major version: releases_tracked majors newer than the
+            # entry's declared version → knowledge drift signal
+            def _maj(v: str) -> int | None:
+                import re
+                m = re.match(r"\s*v?(\d+)", str(v))
+                return int(m.group(1)) if m else None
+            cur = _maj(e.version)
+            newer = sorted({_maj(r) for r in e.releases_tracked
+                            if _maj(r) is not None and cur is not None
+                            and _maj(r) > cur})
+            for mj in newer:
+                signals.append({
+                    "kind": "new-major-version", "source": e.id,
+                    "reason": f"entry pinned to {e.version} but v{mj} "
+                              "is tracked — re-derive version-gated claims"})
+
+        # rules citing stale/deprecated/superseded sources
+        stale_ids = {s["source"] for s in signals
+                     if s["kind"] in ("deprecated-source",
+                                      "superseded-source", "stale-source")}
+        stale_rules = [
+            {"rule_id": rid, "sources": [s for s in srcs
+                                         if s in stale_ids]}
+            for rid, srcs in link["linked"].items()
+            if any(s in stale_ids for s in srcs)]
+        return {"linkage": link,
+                "signals": signals,
+                "stale_rule_refs": stale_rules,
+                "unresolved": [u["rule_id"] for u in link["unlinked"]],
+                "counts": {"signals": len(signals),
+                           "stale_rules": len(stale_rules),
+                           "unlinked": len(link["unlinked"])}}
+
+
+def knowledge_age_days(retrieved_at: str, today: date | None = None) -> int | None:
+    try:
+        return ((today or datetime.now(UTC).date()) - date.fromisoformat(str(retrieved_at)[:10])).days
+    except ValueError:
+        return None
+
+
+def now_iso() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())

platformforge/knowledge/select.py

@@ -0,0 +1,127 @@
+"""Knowledge economy (§208–215) — load only the relevant packs.
+
+Selector inputs: task, domain, version, risk (§209). A pack declares
+applicability (`applies_to`); PackApplicability is the verdict (§210).
+Pack budget caps how many packs a task loads — never the whole registry
+(§211). Stale packs are flagged `review_needed`, not silently trusted
+(§212). Search tiers are lexical/graph — no embeddings required (§213–214).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import asdict, dataclass
+from typing import Any
+
+
+@dataclass
+class PackApplicability:
+    """§210 — why a pack does or doesn't apply to a task."""
+    pack_id: str
+    applicable: bool
+    reason: str
+    freshness: str = "unknown"       # current|stale|unresolved
+    score: int = 0
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def select_packs(packs: list[Any], *, domain: str = "",
+                 versions: dict[str, str] | None = None,
+                 risk: str = "low", max_packs: int = 8,
+                 freshness_of=None) -> dict[str, Any]:
+    """§209–212 — select applicable packs within budget.
+
+    `packs` are knowledge.packs.Pack-like objects exposing
+    `pack_id/domain/applies_to/claims`. `freshness_of` maps a pack's
+    source ids to a freshness state (defaults: unknown → review_needed
+    for high risk).
+    """
+    versions = versions or {}
+    verdicts: list[PackApplicability] = []
+    for p in packs:
+        score, reasons = 0, []
+        if domain and getattr(p, "domain", "") == domain:
+            score += 2
+            reasons.append("domain match")
+        applies = getattr(p, "applies_to", {}) or {}
+        ok_versions = True
+        for prod, want in (applies.get("versions") or {}).items():
+            # applies_to.versions lists products the pack covers; the
+            # task's detected version for that product decides fit.
+            want = str(want)
+            have = versions.get(prod, "")
+            if prod in versions and _version_ok(have, want):
+                score += 2
+                reasons.append(f"{prod} {have} matches {want}")
+            elif prod not in versions:
+                pass                       # pack covers more than needed
+        if domain and getattr(p, "domain", "") and \
+                p.domain != domain:
+            ok_versions = False
+            reasons.append("domain mismatch")
+        verdicts.append(PackApplicability(
+            pack_id=getattr(p, "pack_id", "?"),
+            applicable=ok_versions and score > 0,
+            reason="; ".join(reasons) or "no applicability signal",
+            score=score))
+
+    applicable = sorted((v for v in verdicts if v.applicable),
+                        key=lambda v: -v.score)
+    selected: list[PackApplicability] = []
+    for v in applicable[:max_packs]:
+        fr = freshness_of(v.pack_id) if freshness_of else "unknown"
+        v.freshness = fr
+        if fr in ("stale", "unresolved") and risk in ("high", "critical"):
+            v.reason += "; review_needed (stale pack under high risk)"
+        selected.append(v)
+    return {"selected": [v.to_dict() for v in selected],
+            "skipped": [v.to_dict() for v in verdicts
+                        if not v.applicable],
+            "budget": max_packs,
+            "overflow": max(0, len(applicable) - max_packs)}
+
+
+def _version_ok(have: str, want: str) -> bool:
+    """Minimal semver-ish range check (>=X.Y, >X.Y, ==X.Y, bare prefix)."""
+    m = re.match(r"^\s*(>=|>|<=|<|==)?\s*([\d.]+)", want)
+    if not m:
+        return have == want
+    op, target = m.groups()
+    h = [int(x) for x in have.split(".") if x.isdigit()]
+    t = [int(x) for x in target.split(".") if x.isdigit()]
+    n = max(len(h), len(t))
+    h += [0] * (n - len(h)); t += [0] * (n - len(t))
+    if op in (None, "=="):
+        return h == t
+    if op == ">=":
+        return h >= t
+    if op == ">":
+        return h > t
+    if op == "<=":
+        return h <= t
+    return h < t
+
+
+def search_knowledge(packs: list[Any], query: str,
+                     *, tier2_graph=None) -> dict[str, Any]:
+    """§213–214 — tiered search, no embeddings.
+
+    Tier 0: exact id/ref match. Tier 1: lexical substring/FTS over pack
+    id+domain+claims. Tier 2: caller-supplied graph expansion hook."""
+    q = query.lower()
+    t0 = [p for p in packs if getattr(p, "pack_id", "") == query]
+    if t0:
+        return {"tier": 0, "packs": t0}
+    t1 = [p for p in packs if q in getattr(p, "pack_id", "").lower()
+          or q in getattr(p, "domain", "").lower()
+          or any(q in c.statement.lower()
+                 for c in getattr(p, "claims", ()))]
+    if t1:
+        return {"tier": 1, "packs": t1}
+    if tier2_graph is not None:
+        expanded = tier2_graph(query)
+        return {"tier": 2, "packs": expanded}
+    return {"tier": 2, "packs": [], "note": "no lexical match; "
+            "tier-2 graph expansion unavailable"}

platformforge/lab/__init__.py

@@ -0,0 +1,5 @@
+"""Forge Lab — bundled scenarios for evals, demos, regression detection."""
+
+from platformforge.lab.runner import SCENARIOS_DIR, list_scenarios, run
+
+__all__ = ["SCENARIOS_DIR", "list_scenarios", "run"]

platformforge/lab/chaos.py

@@ -0,0 +1,71 @@
+"""Chaos lab (§93) — deterministic fault injection *on the graph*.
+
+Offline by construction: a fault removes or degrades nodes in a built
+graph, then blast_radius computes the impacted set. Results are declared
+simulations (`environment: simulation`), never live fault injection.
+
+Production targets are refused unless the caller passes allow_prod — the
+boundary is explicit, not implicit.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from platformforge.graph.model import Graph
+from platformforge.graph.query import blast_radius
+
+FAULTS = ("pod_kill", "latency_injection", "dependency_unavailable",
+          "dns_failure", "network_loss", "node_unavailable")
+
+# faults that degrade edges (dependencies stay, SLO risk rises)
+_DEGRADE = {"latency_injection", "network_loss"}
+
+
+def chaos(g: Graph, fault: str, target: str,
+          allow_prod: bool = False) -> dict[str, Any]:
+    if fault not in FAULTS:
+        return {"refusal": "platform.chaos.unknown_fault",
+                "known": list(FAULTS)}
+    node = g.nodes.get(target)
+    if node is None:
+        return {"refusal": "platform.chaos.unknown_node", "node": target}
+    if node.attrs.get("env") == "production" and not allow_prod:
+        return {"refusal": "platform.chaos.production_default",
+                "node": target,
+                "unlock": "re-run with allow_prod=True in a controlled env"}
+
+    blast = blast_radius(g, target)
+    degraded = sorted(blast["nodes"])
+    impact = {"fault": fault, "target": target,
+              "environment": "simulation",
+              "mode": ("degraded" if fault in _DEGRADE else "removed"),
+              "impacted_total": blast["impacted_total"],
+              "impacted_by_class": blast["by_class"],
+              "degraded_nodes": degraded,
+              "unresolved": [
+                  ("post-fault recovery behavior is not observable from "
+                   "static artifacts")]}
+    return {"chaos": "platformforge.chaos/v1", **impact}
+
+
+def run_scenario(path: str | Path,
+                 allow_prod: bool = False) -> dict[str, Any]:
+    """chaos.yaml: {fault, target, facts} → simulation against fixture graph."""
+    d = Path(path)
+    spec = yaml.safe_load((d / "chaos.yaml").read_text())
+    facts_doc = yaml.safe_load((d / spec.get("facts", "facts.json"))
+                               .read_text())
+    from platformforge.graph import GraphBuilder
+    g = GraphBuilder().from_facts(
+        facts_doc.get("facts", facts_doc if isinstance(facts_doc, list)
+                      else [])).graph
+    out = chaos(g, spec["fault"], spec["target"], allow_prod=allow_prod)
+    expected = spec.get("expected_impacted")
+    if expected is not None and "degraded_nodes" in out:
+        out["expected_match"] = \
+            sorted(expected) == out["degraded_nodes"]
+    return out