@heretek-ai/epistemic-swarm 0.7.13 → 0.7.15

package/runner/schemas.py

@@ -0,0 +1,270 @@
+#!/usr/bin/env python3
+"""Canonical IUMBTEMS contracts, as data.
+
+These are the single source of truth for the on-disk formats (Heretek-AI/IUMBTEMS#6
+item 2.1: the agent had to reverse-engineer the contract). `scripts/gen_schemas.py`
+renders them to `schemas/*.schema.json`; `runner/schema_validate.py` enforces them
+warn-on-load. Keep this module in sync with what the runner actually reads and
+writes — a test asserts the generated files match.
+"""
+
+from typing import Any, Dict
+
+_DRAFT = "http://json-schema.org/draft-07/schema#"
+
+CLAIM: Dict[str, Any] = {
+    "type": "object",
+    "required": ["claim_id", "statement"],
+    "properties": {
+        "claim_id": {"type": "string"},
+        "tag": {
+            "type": "string",
+            "enum": ["VERIFIED", "INFERRED", "HYPOTHESIS", "NEGATIVE_KNOWLEDGE"],
+        },
+        "statement": {"type": "string"},
+        "source_hash": {"type": "string"},
+        "source_url": {"type": "string"},
+        "verbatim_quote": {"type": "string"},
+        "severity": {"type": "string"},
+    },
+}
+
+INFERENCE: Dict[str, Any] = {
+    "type": "object",
+    "required": ["inference_id", "statement"],
+    "properties": {
+        "inference_id": {"type": "string"},
+        "tag": {"type": "string"},
+        "statement": {"type": "string"},
+        "parent_claims": {"type": "array", "items": {"type": "string"}},
+        "deductive_logic": {"type": "string"},
+        "falsification": {"type": "string"},
+    },
+}
+
+HYPOTHESIS: Dict[str, Any] = {
+    "type": "object",
+    "required": ["statement"],
+    "properties": {
+        "hypothesis_id": {"type": "string"},
+        "claim_id": {"type": "string"},
+        "tag": {"type": "string"},
+        "statement": {"type": "string"},
+        "falsification": {"type": "string"},
+    },
+}
+
+NEGATIVE_KNOWLEDGE: Dict[str, Any] = {
+    "type": "object",
+    "required": ["query", "finding"],
+    "properties": {
+        "query": {"type": "string"},
+        "finding": {"type": "string"},
+    },
+}
+
+CANDIDATE_REPO: Dict[str, Any] = {
+    "type": "object",
+    "required": ["name"],
+    "properties": {
+        "repo_id": {"type": "string"},
+        "name": {"type": "string"},
+        "url": {"type": "string"},
+        "source_hash": {"type": "string"},
+        "verbatim_quote": {"type": "string"},
+        "license": {"type": "string"},
+        "license_risk": {
+            "type": "string",
+            "enum": ["SAFE", "COPYLEFT_WARNING", "PROHIBITIVE"],
+        },
+        "harvest_policy": {
+            "type": "string",
+            "enum": ["depend-or-vendor", "clean-room-rebuild-only"],
+        },
+        "verdicts": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "required": ["feature", "verdict"],
+                "properties": {
+                    "feature": {"type": "string"},
+                    "verdict": {
+                        "type": "string",
+                        "enum": ["depend", "vendor", "clean-room-rebuild", "skip"],
+                    },
+                    "reason": {"type": "string"},
+                    "verbatim_quote": {"type": "string"},
+                    "effort": {"type": "string"},
+                    "impact": {"type": "integer"},
+                    "differentiation": {"type": "integer"},
+                },
+            },
+        },
+        "warnings": {"type": "array", "items": {"type": "string"}},
+        "attribution": {"type": "object"},
+    },
+}
+
+_COMMON_DOSSIER: Dict[str, Any] = {
+    "scope_id": {"type": "string"},
+    "agent": {"type": "string"},
+    "mode": {"type": "string"},
+    "timestamp": {"type": "string"},
+    "negative_knowledge": {"type": "array", "items": NEGATIVE_KNOWLEDGE},
+    "candidate_repositories": {"type": "array", "items": CANDIDATE_REPO},
+}
+
+
+def _dossier(role: str, extra: Dict[str, Any]) -> Dict[str, Any]:
+    props = dict(_COMMON_DOSSIER)
+    props.update(extra)
+    return {
+        "$schema": _DRAFT,
+        "title": f"{role}_dossier",
+        "type": "object",
+        "required": ["scope_id"],
+        "properties": props,
+    }
+
+
+ALPHA_DOSSIER = _dossier(
+    "alpha",
+    {
+        "affirmative_claims": {"type": "array", "items": CLAIM},
+        "inferred_implications": {"type": "array", "items": INFERENCE},
+    },
+)
+
+BETA_DOSSIER = _dossier(
+    "beta",
+    {
+        "falsification_claims": {"type": "array", "items": CLAIM},
+        "methodological_critiques": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "target_assertion": {"type": "string"},
+                    "critique": {"type": "string"},
+                    "evidence_hash": {"type": "string"},
+                },
+            },
+        },
+        "hypotheses": {"type": "array", "items": HYPOTHESIS},
+    },
+)
+
+AUDIT_REPORT: Dict[str, Any] = {
+    "$schema": _DRAFT,
+    "title": "audit_report",
+    "type": "object",
+    "required": ["scope_id", "summary"],
+    "properties": {
+        "auditor": {"type": "string"},
+        "scope_id": {"type": "string"},
+        "audited_at": {"type": "string"},
+        "summary": {
+            "type": "object",
+            "required": [
+                "verified_passed",
+                "unverified_rejected",
+                "divergence_score",
+                "verdict",
+            ],
+            "properties": {
+                "total_claims_audited": {"type": "integer"},
+                "verified_passed": {"type": "integer"},
+                "unverified_rejected": {"type": "integer"},
+                "negative_knowledge_count": {"type": "integer"},
+                "epistemic_score": {"type": "number"},
+                "divergence_score": {"type": "number"},
+                "mode": {"type": ["string", "null"]},
+                "blocking_findings": {"type": "integer"},
+                "verdict": {"type": "string"},
+            },
+        },
+        "alpha_claims_audit": {"type": "array"},
+        "beta_claims_audit": {"type": "array"},
+        "divergence_matrix": {"type": "array"},
+        "harvest_findings": {"type": "array"},
+        "degradation": {"type": "object"},
+    },
+}
+
+SCOPE_MANIFEST: Dict[str, Any] = {
+    "$schema": _DRAFT,
+    "title": "scope_manifest",
+    "type": "object",
+    "required": ["scope_id", "status"],
+    "properties": {
+        "scope_id": {"type": "string"},
+        "title": {"type": "string"},
+        "objective": {"type": "string"},
+        "dependencies": {"type": "array", "items": {"type": "string"}},
+        "status": {"type": "string"},
+        "alpha_completed": {"type": "boolean"},
+        "beta_completed": {"type": "boolean"},
+        "audit_completed": {"type": "boolean"},
+        "created_at": {"type": "string"},
+        "outputs": {"type": "array"},
+        # Agent-authored (renamed on load); allowed but never authoritative.
+        "self_reported_epistemic_audit": {"type": "object"},
+    },
+}
+
+MANIFEST: Dict[str, Any] = {
+    "$schema": _DRAFT,
+    "title": "manifest",
+    "type": "object",
+    "required": ["session_id", "objective", "status", "scopes"],
+    "properties": {
+        "session_id": {"type": "string"},
+        "objective": {"type": "string"},
+        "status": {"type": "string"},
+        "created_at": {"type": "string"},
+        "updated_at": {"type": "string"},
+        "plugin_version": {"type": "string"},
+        "backend": {"type": "string"},
+        "preflight": {"type": "object"},
+        "scopes": {"type": "array"},
+        "telemetry": {"type": "object"},
+    },
+}
+
+FRONTIER: Dict[str, Any] = {
+    "$schema": _DRAFT,
+    "title": "frontier",
+    "type": "object",
+    "required": ["objective"],
+    "properties": {
+        "objective": {"type": "string"},
+        "is_complete": {"type": "boolean"},
+        # Nodes are keyed by node_id (see skills/grilling/socratic_tree.py).
+        "nodes": {
+            "type": "object",
+            "additionalProperties": {
+                "type": "object",
+                "required": ["node_id", "question"],
+                "properties": {
+                    "node_id": {"type": "string"},
+                    "title": {"type": "string"},
+                    "question": {"type": "string"},
+                    "recommended": {"type": "string"},
+                    "options": {"type": "array", "items": {"type": "string"}},
+                    "prerequisites": {"type": "array", "items": {"type": "string"}},
+                    "settled_answer": {"type": ["string", "null"]},
+                },
+            },
+        },
+        "settled_constraints": {"type": "object"},
+    },
+}
+
+SCHEMAS: Dict[str, Dict[str, Any]] = {
+    "alpha_dossier": ALPHA_DOSSIER,
+    "beta_dossier": BETA_DOSSIER,
+    "audit_report": AUDIT_REPORT,
+    "manifest": MANIFEST,
+    "scope_manifest": SCOPE_MANIFEST,
+    "frontier": FRONTIER,
+}

package/runner/state_machine.py

@@ -44,6 +44,36 @@ class ScopeStatus(str, Enum):
 
 
 MANIFEST_FILENAME = "manifest.json"
+RUNS_DIRNAME = "runs"
+LATEST_POINTER = "latest.json"
+
+
+def run_scoped_enabled() -> bool:
+    """Opt-in run-scoped layout (`.research/runs/<id>/`). Default: flat.
+
+    The capability ships behind `IUMBTEMS_RUN_SCOPED=1` rather than flipped by
+    default: it changes every artifact path and deserves a live end-to-end run
+    before it becomes the default (see issue #6 item 3.9).
+    """
+    return os.environ.get("IUMBTEMS_RUN_SCOPED", "").strip().lower() in (
+        "1",
+        "true",
+        "yes",
+        "on",
+    )
+
+
+def latest_run_dir(workspace: Path) -> Optional[Path]:
+    """The run dir a `latest.json` pointer refers to, if any."""
+    try:
+        data = json.loads((workspace / LATEST_POINTER).read_text(encoding="utf-8"))
+        run_id = data.get("run_id")
+    except (OSError, ValueError):
+        return None
+    if not run_id:
+        return None
+    candidate = workspace / RUNS_DIRNAME / str(run_id)
+    return candidate if candidate.is_dir() else None
 
 
 def manifest_name_for_mode(mode: Optional[str]) -> str:
@@ -68,19 +98,29 @@ def resolve_manifest_path(base_dir, mode: Optional[str] = None) -> Path:
 def find_any_manifest(base_dir) -> Optional[Path]:
     """Newest manifest in the workspace, preferring the canonical name.
 
-    Lets mode-agnostic readers (e.g. PCRB export) find whichever session last
-    wrote a manifest.
+    Understands both layouts: flat (`manifest.json`, `manifest.<mode>.json`) and
+    run-scoped (`runs/<id>/manifest*.json`, resolved via `latest.json`).
     """
     base = Path(os.path.realpath(str(base_dir)))
+    candidates = []
     canonical = base / MANIFEST_FILENAME
     if canonical.exists():
         return canonical
-    candidates = sorted(
-        base.glob("manifest.*.json"),
-        key=lambda p: p.stat().st_mtime,
-        reverse=True,
-    )
-    return candidates[0] if candidates else None
+    candidates.extend(base.glob("manifest.*.json"))
+
+    run_dir = latest_run_dir(base)
+    if run_dir is not None:
+        run_manifest = run_dir / MANIFEST_FILENAME
+        if run_manifest.exists():
+            return run_manifest
+        candidates.extend(run_dir.glob("manifest.*.json"))
+    if (base / RUNS_DIRNAME).is_dir():
+        candidates.extend((base / RUNS_DIRNAME).glob("*/manifest*.json"))
+
+    existing = [c for c in candidates if c.exists()]
+    if not existing:
+        return None
+    return max(existing, key=lambda p: p.stat().st_mtime)
 
 
 @contextmanager
@@ -122,8 +162,26 @@ def _atomic_write_json(path: Path, data: Any) -> None:
 
 
 class ResearchStateMachine:
-    def __init__(self, base_dir: Optional[Path] = None, mode: Optional[str] = None):
-        self.base_dir = Path(os.path.realpath(str(base_dir or ".research")))
+    def __init__(
+        self,
+        base_dir: Optional[Path] = None,
+        mode: Optional[str] = None,
+        run_scoped: Optional[bool] = None,
+        run_id: Optional[str] = None,
+    ):
+        workspace = Path(os.path.realpath(str(base_dir or ".research")))
+        if run_scoped is None:
+            run_scoped = run_scoped_enabled()
+        self.workspace = workspace
+        self.run_scoped = bool(run_scoped)
+        if self.run_scoped:
+            self.run_id = run_id or (
+                f"{mode or 'run'}-{datetime.now(timezone.utc).strftime('%Y%m%d-%H%M%S')}"
+            )
+            self.base_dir = workspace / RUNS_DIRNAME / self.run_id
+        else:
+            self.run_id = None
+            self.base_dir = workspace
         self.scratchpads_dir = self.base_dir / "scratchpads"
         self.sources_dir = self.base_dir / "sources"
         self.manifest_file = self.base_dir / manifest_name_for_mode(mode)
@@ -133,6 +191,16 @@ class ResearchStateMachine:
         # Ensure directories exist
         self.scratchpads_dir.mkdir(parents=True, exist_ok=True)
         self.sources_dir.mkdir(parents=True, exist_ok=True)
+        if self.run_scoped:
+            self._write_latest_pointer(mode)
+
+    def _write_latest_pointer(self, mode: Optional[str]) -> None:
+        try:
+            (self.workspace / LATEST_POINTER).write_text(
+                json.dumps({"run_id": self.run_id, "mode": mode}), encoding="utf-8"
+            )
+        except OSError:
+            pass
 
     def init_session(
         self, objective: str, session_id: Optional[str] = None
@@ -162,6 +230,24 @@ class ResearchStateMachine:
         self.save_global_manifest(manifest)
         return manifest
 
+    def record_preflight(
+        self, report: Dict[str, Any], backend: Optional[str] = None
+    ) -> None:
+        """Persist the preflight report + plugin version into the manifest."""
+        with self._lock, _file_lock(self._lock_file):
+            try:
+                manifest = self._read_manifest_unlocked()
+            except FileNotFoundError:
+                # Dry runs / pre-orchestration: keep the report rather than fail.
+                manifest = {"preflight": report}
+            manifest["preflight"] = report
+            version = report.get("plugin_version")
+            if version:
+                manifest["plugin_version"] = version
+            if backend:
+                manifest["backend"] = backend
+            self._write_manifest_unlocked(manifest)
+
     def _read_manifest_unlocked(self) -> Dict[str, Any]:
         if not self.manifest_file.exists():
             raise FileNotFoundError(