platformforge 0.1.0__py3-none-any.whl

platformforge/data/contracts/agent-run.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "platformforge/agent-run/v1",
+  "title": "PlatformForge AgentRunRecord — auditable agentic run",
+  "type": "object",
+  "required": ["schema", "run_id", "task_spec_hash", "verdict"],
+  "properties": {
+    "schema": {"const": "platformforge/agent-run/v1"},
+    "run_id": {"type": "string", "minLength": 1},
+    "task_spec_hash": {"type": "string", "minLength": 1},
+    "router_decision": {"type": "object"},
+    "agents": {"type": "array", "items": {"type": "string"}},
+    "handoffs": {"type": "array", "items": {"type": "object"}},
+    "budget": {"type": "object"},
+    "evidence": {"type": "array", "items": {"type": "string"}},
+    "debates": {"type": "array", "items": {"type": "string"}},
+    "gates": {"type": "array", "items": {"type": "string"}},
+    "verifier": {"type": "string"},
+    "verdict": {"type": "string", "enum": ["confirmed", "supported",
+                "candidate", "unresolved", "refuted", "unsupported",
+                "not-observed"]},
+    "checkpoint": {"type": "object"},
+    "started_at": {"type": "string"},
+    "finished_at": {"type": "string"}
+  },
+  "additionalProperties": false
+}

platformforge/data/contracts/agent-spec.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "platformforge/agent-spec/v1",
+  "title": "PlatformForge canonical agent contract (cycle5.1)",
+  "type": "object",
+  "required": ["schema", "name", "role", "domains", "when_to_enter",
+               "when_not_to_enter", "access", "write_scope",
+               "model_tier", "never"],
+  "properties": {
+    "schema": {"const": "platformforge/agent-spec/v1"},
+    "name": {"type": "string", "pattern": "^(platform|pf)-[a-z0-9-]+$"},
+    "role": {"type": "string", "enum": ["orchestrator", "planner",
+             "coordinator", "specialist", "executor", "reviewer",
+             "critic", "referee", "verifier", "guardian"]},
+    "domains": {"type": "array", "items": {"type": "string"}},
+    "mission": {"type": "string"},
+    "when_to_enter": {"type": "string", "minLength": 1},
+    "when_not_to_enter": {"type": "string", "minLength": 1},
+    "inputs": {"type": "array", "items": {"type": "string"}},
+    "outputs": {"type": "array", "items": {"type": "string"}},
+    "required_evidence": {"type": "array", "items": {"type": "string"}},
+    "allowed_verbs": {"type": "array", "items": {"type": "string"}},
+    "allowed_tools": {"type": "array", "items": {"type": "string"}},
+    "allowed_capabilities": {"type": "array", "items": {"type": "string"}},
+    "access": {"type": "string", "enum": ["read-only", "state-writer",
+               "workspace-writer", "governed-writer"]},
+    "write_scope": {"type": "string", "enum": ["none", "runs",
+                "artifacts", "governed"]},
+    "model_tier": {"type": "string", "enum": ["deterministic", "fast",
+                   "standard", "deep", "critical-review"]},
+    "max_context_budget": {"type": "integer", "minimum": 0},
+    "max_tool_calls": {"type": "integer", "minimum": 0},
+    "max_parallelism": {"type": "integer", "minimum": 1},
+    "delegates_to": {"type": "array", "items": {"type": "string"}},
+    "cannot_delegate_to": {"type": "array", "items": {"type": "string"}},
+    "reviewers": {"type": "array", "items": {"type": "string"}},
+    "verifier": {"type": "string"},
+    "escalation": {"type": "string"},
+    "done_when": {"type": "string"},
+    "never": {"type": "string", "minLength": 1}
+  },
+  "additionalProperties": false
+}

platformforge/data/contracts/capability.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "platformforge/capability/v1",
+  "title": "PlatformForge capability manifest entry",
+  "type": "object",
+  "required": ["id", "version", "inputs", "outputs", "risk", "required_evidence", "offline", "mutable", "cost_class"],
+  "properties": {
+    "id": {"type": "string", "pattern": "^platform\\.[a-z0-9_.-]+$"},
+    "version": {"type": "string"},
+    "description": {"type": "string"},
+    "inputs": {"type": "array", "items": {"type": "string"}},
+    "outputs": {"type": "array", "items": {"type": "string"}},
+    "risk": {"type": "string", "enum": ["read-only", "propose", "mutating"]},
+    "required_evidence": {"type": "array", "items": {"type": "string"}},
+    "offline": {"type": "boolean"},
+    "mutable": {"type": "boolean"},
+    "cost_class": {"type": "string", "enum": ["deterministic", "indexed", "local-model", "provider-model"]},
+    "agent_requirements": {"type": "array", "items": {"type": "string"}},
+    "cli": {"type": ["string", "null"]},
+    "mcp_tool": {"type": ["string", "null"]}
+  },
+  "additionalProperties": false
+}

platformforge/data/contracts/change-event.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "platformforge/change-event/v1",
+  "title": "PlatformForge ChangeEvent",
+  "type": "object",
+  "required": ["schema", "event_id", "timestamp", "source", "action"],
+  "properties": {
+    "schema": {"const": "platformforge/change-event/v1"},
+    "event_id": {"type": "string", "minLength": 1},
+    "timestamp": {"type": "string", "minLength": 1},
+    "source": {"type": "string", "minLength": 1},
+    "actor": {"type": "string"},
+    "action": {"type": "string", "minLength": 1},
+    "resource_ids": {"type": "array", "items": {"type": "string"}},
+    "account": {"type": "string"},
+    "region": {"type": "string"},
+    "request": {"type": "object"},
+    "result": {"type": "string"},
+    "evidence": {"type": "object"}
+  },
+  "additionalProperties": true
+}

platformforge/data/contracts/change-intent.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "platformforge/change-intent/v1",
+  "title": "ChangeIntent",
+  "type": "object",
+  "required": ["schema", "intent_id", "reason", "target", "evidence", "owner"],
+  "properties": {
+    "schema": {"const": "platformforge/change-intent/v1"},
+    "intent_id": {"type": "string", "pattern": "^[a-z][a-z0-9_-]{0,63}$"},
+    "created_at": {"type": "string", "format": "date-time"},
+    "reason": {
+      "type": "object",
+      "required": ["type"],
+      "properties": {
+        "type": {"enum": ["finding", "incident", "drift", "recommendation",
+                          "request", "maintenance", "security", "cost",
+                          "other"]},
+        "finding_ids": {"type": "array", "items": {"type": "string"}},
+        "incident_ids": {"type": "array", "items": {"type": "string"}},
+        "drift_ids": {"type": "array", "items": {"type": "string"}},
+        "recommendation_ids": {"type": "array", "items": {"type": "string"}},
+        "detail": {"type": "string"}
+      }
+    },
+    "target": {
+      "type": "object",
+      "properties": {
+        "canonical_resource_ids": {"type": "array", "items": {"type": "string"}},
+        "graph_nodes": {"type": "array", "items": {"type": "string"}}
+      }
+    },
+    "source_of_truth": {
+      "type": "object",
+      "properties": {
+        "type": {"enum": ["gitops", "terraform", "tofu", "crossplane",
+                          "helm", "declarative-config", "provider-api",
+                          "manual", "unknown"]},
+        "repository": {"type": "string"},
+        "path": {"type": "string"},
+        "ref": {"type": "string"},
+        "confidence": {"enum": ["high", "medium", "low", "unknown"]},
+        "evidence": {"type": "array", "items": {"type": "string"}}
+      }
+    },
+    "desired_change": {"type": "object"},
+    "evidence": {
+      "type": "object",
+      "properties": {
+        "fact_ids": {"type": "array", "items": {"type": "string"}},
+        "observation_ids": {"type": "array", "items": {"type": "string"}},
+        "finding_ids": {"type": "array", "items": {"type": "string"}},
+        "incident_ids": {"type": "array", "items": {"type": "string"}},
+        "drift_ids": {"type": "array", "items": {"type": "string"}}
+      }
+    },
+    "risk_context": {"type": "object"},
+    "expected_outcome": {"type": "string"},
+    "owner": {"type": "string", "minLength": 1},
+    "requested_by": {"type": "string"},
+    "expires_at": {"type": "string", "format": "date-time"}
+  }
+}

platformforge/data/contracts/change-plan.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "platformforge/change-plan/v1",
+  "title": "ChangePlan — DAG of typed steps + ExpectedDelta",
+  "type": "object",
+  "required": ["schema", "plan_id", "intent_id", "steps", "expected_delta"],
+  "properties": {
+    "schema": {"const": "platformforge/change-plan/v1"},
+    "plan_id": {"type": "string", "pattern": "^[a-z][a-z0-9_-]{0,63}$"},
+    "intent_id": {"type": "string"},
+    "created_at": {"type": "string", "format": "date-time"},
+    "affected_resources": {"type": "array", "items": {"type": "string"}},
+    "source_changes": {"type": "array", "items": {"type": "object"}},
+    "steps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["step_id", "action"],
+        "properties": {
+          "step_id": {"type": "string"},
+          "action": {"type": "string",
+                     "description": "typed action — e.g. git.apply_patch, terraform.plan; never shell.run"},
+          "description": {"type": "string"},
+          "depends_on": {"type": "array", "items": {"type": "string"}},
+          "params": {"type": "object"},
+          "validation": {"type": "array", "items": {"type": "string"}}
+        }
+      }
+    },
+    "expected_delta": {
+      "type": "object",
+      "properties": {
+        "adds": {"type": "object"},
+        "removes": {"type": "object"},
+        "changes": {"type": "object"},
+        "unknown_dimensions": {"type": "array", "items": {"type": "string"}}
+      }
+    },
+    "validation": {"type": "array", "items": {"type": "string"}},
+    "rollback_requirements": {"type": "array", "items": {"type": "string"}},
+    "notes": {"type": "string"}
+  }
+}

platformforge/data/contracts/collector-receipt.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "platformforge/collector-receipt/v1",
+  "title": "PlatformForge Collector Receipt",
+  "type": "object",
+  "required": ["schema", "collector", "collector_version", "provider",
+               "started_at", "scope"],
+  "properties": {
+    "schema": {"const": "platformforge/collector-receipt/v1"},
+    "collector": {"type": "string", "minLength": 1},
+    "collector_version": {"type": "string", "minLength": 1},
+    "provider": {"type": "string", "minLength": 1},
+    "started_at": {"type": "string"},
+    "completed_at": {"type": "string"},
+    "scope": {"type": "object"},
+    "api_calls": {"type": "integer"},
+    "pages": {"type": "integer"},
+    "objects": {"type": "integer"},
+    "bytes": {"type": "integer"},
+    "throttles": {"type": "integer"},
+    "retries": {"type": "integer"},
+    "cache_hits": {"type": "integer"},
+    "errors": {"type": "array", "items": {"type": "string"}},
+    "permission_denied": {"type": "array"},
+    "unsupported": {"type": "array"},
+    "cursor": {"type": "string"},
+    "metadata_only": {"type": "boolean"},
+    "fallback": {"type": "string"},
+    "coverage": {"type": "object"},
+    "freshness": {"type": "object"},
+    "budget_outcome": {"enum": ["complete", "reduced_scope", "sampled",
+                                "refused"]},
+    "duration_s": {"type": "number"}
+  },
+  "additionalProperties": true
+}

platformforge/data/contracts/context-pack.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "platformforge/context-pack/v1",
+  "title": "TokenSave context pack — minimal context for a task",
+  "type": "object",
+  "required": ["task", "budget"],
+  "properties": {
+    "task": {"type": "object"},
+    "relevant_files": {"type": "array", "items": {"type": "string"}},
+    "relevant_symbols": {"type": "array", "items": {"type": "string"}},
+    "facts": {"type": "array"},
+    "findings": {"type": "array"},
+    "graph_neighborhood": {"type": "array"},
+    "rules": {"type": "array", "items": {"type": "string"}},
+    "sources": {"type": "array", "items": {"type": "string"}},
+    "budget": {
+      "type": "object",
+      "properties": {
+        "input_budget": {"type": ["integer", "null"]},
+        "output_budget": {"type": ["integer", "null"]},
+        "reasoning_budget": {"type": ["integer", "null"]},
+        "tool_budget": {"type": ["integer", "null"]}
+      }
+    },
+    "packed_bytes": {"type": "integer"},
+    "refusals": {"type": "array"}
+  },
+  "additionalProperties": true
+}

platformforge/data/contracts/debate.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "platformforge/debate/v1",
+  "title": "PlatformForge Debate — bounded evidence-based disagreement",
+  "type": "object",
+  "required": ["schema", "debate_id", "question", "outcome"],
+  "properties": {
+    "schema": {"const": "platformforge/debate/v1"},
+    "debate_id": {"type": "string", "minLength": 1},
+    "question": {"type": "string", "minLength": 1},
+    "positions": {"type": "array", "items": {"type": "object",
+        "required": ["agent", "claim"],
+        "properties": {
+          "agent": {"type": "string"},
+          "claim": {"type": "string"},
+          "evidence": {"type": "array", "items": {"type": "string"}},
+          "evidence_tier": {"type": "integer", "minimum": 0,
+                            "maximum": 7},
+          "freshness": {"type": "string"},
+          "round": {"type": "integer", "minimum": 0}}}},
+    "max_participants": {"type": "integer", "minimum": 2, "maximum": 8},
+    "max_rounds": {"type": "integer", "minimum": 1, "maximum": 3},
+    "round": {"type": "integer", "minimum": 0},
+    "outcome": {"type": "string", "enum": ["open", "winner", "tied",
+                "unresolved"]},
+    "winner": {"type": "string"},
+    "axes": {"type": "array", "items": {"type": "string"}},
+    "receipt": {"type": "object"}
+  },
+  "additionalProperties": false
+}

platformforge/data/contracts/distribution-manifest-v1.schema.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "platformforge/distribution-manifest/v1",
+  "type": "object",
+  "required": [
+    "schema",
+    "distribution_id",
+    "platformforge_version",
+    "profile",
+    "hosts",
+    "assets",
+    "offline"
+  ],
+  "properties": {
+    "schema": {
+      "const": "platformforge/distribution-manifest/v1"
+    },
+    "distribution_id": {
+      "type": "string",
+      "pattern": "^sha256:"
+    },
+    "platformforge_version": {
+      "type": "string"
+    },
+    "source_sha": {
+      "type": "string"
+    },
+    "profile": {
+      "type": "string"
+    },
+    "hosts": {
+      "type": "array",
+      "items": {
+        "enum": [
+          "agents",
+          "claude",
+          "codex",
+          "devin"
+        ]
+      }
+    },
+    "capabilities": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "offline": {
+      "type": "boolean"
+    },
+    "assets": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "path",
+          "sha256",
+          "owner",
+          "kind"
+        ],
+        "properties": {
+          "path": {
+            "type": "string"
+          },
+          "sha256": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$"
+          },
+          "owner": {
+            "const": "platformforge"
+          },
+          "kind": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

platformforge/data/contracts/drift-event.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "platformforge/drift-event/v1",
+  "title": "PlatformForge DriftEvent",
+  "type": "object",
+  "required": ["schema", "drift_id", "resource_id", "drift_class"],
+  "properties": {
+    "schema": {"const": "platformforge/drift-event/v1"},
+    "drift_id": {"type": "string", "minLength": 1},
+    "resource_id": {"type": "string", "minLength": 1},
+    "drift_class": {"type": "string"},
+    "before": {"type": "object"},
+    "after": {"type": "object"},
+    "facts": {"type": "array", "items": {"type": "string"}},
+    "change_event": {"type": "string"},
+    "risk": {"type": "string"},
+    "owner": {"type": "string"},
+    "observed_at": {"type": "string"}
+  },
+  "additionalProperties": true
+}

platformforge/data/contracts/fact.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "platformforge/fact/v1",
+  "title": "PlatformForge Fact",
+  "type": "object",
+  "required": ["fact_id", "kind", "source", "location", "observed", "tier"],
+  "properties": {
+    "fact_id": {"type": "string", "pattern": "^PF-[A-Z0-9]+-[0-9]+$"},
+    "kind": {"type": "string", "minLength": 1},
+    "source": {"type": "string", "minLength": 1},
+    "location": {"type": "string", "minLength": 1},
+    "observed": {"type": "boolean"},
+    "tier": {"type": "integer", "minimum": 0, "maximum": 7},
+    "attrs": {"type": "object", "additionalProperties": true},
+    "measures": {"type": "object", "additionalProperties": {"type": ["number", "string", "boolean", "null"]}},
+    "provenance": {
+      "type": "object",
+      "properties": {
+        "tool": {"type": "string"},
+        "tool_version": {"type": "string"},
+        "extracted_at": {"type": "string"},
+        "source_sha256": {"type": "string", "pattern": "^[0-9a-f]{64}$"}
+      }
+    },
+    "freshness": {
+      "type": "object",
+      "properties": {
+        "status": {"type": "string", "enum": ["current", "fresh", "stale", "deprecated", "superseded", "conflicted", "unresolved"]},
+        "valid_from": {"type": ["string", "null"]},
+        "valid_until": {"type": ["string", "null"]}
+      }
+    }
+  },
+  "additionalProperties": false
+}

platformforge/data/contracts/finding.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "platformforge/finding/v1",
+  "title": "PlatformForge Finding — a judgment over facts",
+  "type": "object",
+  "required": ["finding_id", "rule_id", "severity", "status", "evidence"],
+  "properties": {
+    "finding_id": {"type": "string", "pattern": "^PF-F-[0-9]+$"},
+    "rule_id": {"type": "string", "pattern": "^PF-[A-Z0-9]+(-[A-Z0-9]+)*-[0-9]+$"},
+    "severity": {"type": "string", "enum": ["info", "low", "medium", "high", "critical"]},
+    "status": {"type": "string", "enum": ["violated", "passed", "unresolved", "not-applicable"]},
+    "title": {"type": "string"},
+    "message": {"type": "string"},
+    "location": {"type": "string"},
+    "evidence": {"type": "array", "items": {"type": "string"}, "minItems": 1},
+    "attrs": {"type": "object", "additionalProperties": true}
+  },
+  "additionalProperties": false,
+  "description": "A finding with empty evidence is invalid by construction."
+}

platformforge/data/contracts/graph-v2.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "platformforge/graph/v2",
+  "title": "PlatformForge Graph v2 — multi-layer edge evidence + temporal",
+  "type": "object",
+  "required": ["schema", "nodes", "edges"],
+  "properties": {
+    "schema": {"const": "platformforge/graph/v2"},
+    "migrated_from": {"type": "string"},
+    "migrated_at": {"type": "string"},
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["node_id", "kind", "label"],
+        "properties": {
+          "node_id": {"type": "string"},
+          "kind": {"type": "string"},
+          "label": {"type": "string"},
+          "attrs": {"type": "object"},
+          "source_fact_ids": {"type": "array", "items": {"type": "string"}}
+        }
+      }
+    },
+    "edges": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["from", "to", "kind", "provenance", "confidence"],
+        "properties": {
+          "from": {"type": "string"},
+          "to": {"type": "string"},
+          "kind": {"type": "string"},
+          "provenance": {"type": "string", "enum": ["observed", "planned", "declared", "inferred"]},
+          "confidence": {"type": "number", "minimum": 0, "maximum": 1},
+          "source_fact_ids": {"type": "array", "items": {"type": "string"}},
+          "evidence": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["provenance"],
+              "properties": {
+                "provenance": {"type": "string", "enum": ["observed", "planned", "declared", "inferred"]},
+                "source_type": {"type": "string"},
+                "fact_ids": {"type": "array", "items": {"type": "string"}},
+                "observed_at": {"type": "string"}
+              }
+            }
+          },
+          "temporal": {
+            "type": "object",
+            "properties": {
+              "first_seen": {"type": "string"},
+              "last_seen": {"type": "string"},
+              "window_start": {"type": "string"},
+              "window_end": {"type": "string"},
+              "sample_count": {"type": "integer", "minimum": 0},
+              "expired": {"type": "boolean"}
+            }
+          },
+          "attrs": {"type": "object"}
+        }
+      }
+    }
+  },
+  "additionalProperties": false
+}

platformforge/data/contracts/graph.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "platformforge/graph/v1",
+  "title": "PlatformForge Graph — nodes and provenanced edges",
+  "type": "object",
+  "required": ["schema", "nodes", "edges"],
+  "properties": {
+    "schema": {"const": "platformforge/graph/v1"},
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["node_id", "kind", "label"],
+        "properties": {
+          "node_id": {"type": "string"},
+          "kind": {"type": "string"},
+          "label": {"type": "string"},
+          "attrs": {"type": "object"},
+          "source_fact_ids": {"type": "array", "items": {"type": "string"}}
+        }
+      }
+    },
+    "edges": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["from", "to", "kind", "provenance", "confidence"],
+        "properties": {
+          "from": {"type": "string"},
+          "to": {"type": "string"},
+          "kind": {"type": "string"},
+          "provenance": {"type": "string", "enum": ["observed", "planned", "declared", "inferred"]},
+          "confidence": {"type": "number", "minimum": 0, "maximum": 1},
+          "source_fact_ids": {"type": "array", "items": {"type": "string"}}
+        }
+      }
+    }
+  },
+  "additionalProperties": false
+}