specromancy-engine 0.1.3__py3-none-any.whl

specromancy_engine/schema_validation.py

@@ -0,0 +1,178 @@
+"""Definition and value validation for the supported JSON schema subset.
+
+This module is independent of configuration loading and artifact validation.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+
+SUPPORTED_SCHEMA_KEYWORDS = frozenset(
+    {"type", "required", "properties", "items", "enum", "pattern", "additionalProperties"}
+)
+SUPPORTED_JSON_TYPES = frozenset(
+    {"object", "array", "string", "number", "integer", "boolean", "null"}
+)
+
+
+class SchemaDefinitionError(ValueError):
+    """A schema uses syntax outside the deliberately small supported subset."""
+
+    def __init__(self, message: str, *, location: str = "$") -> None:
+        super().__init__(message)
+        self.location = location
+
+
+def load_json_schema(path: Path) -> dict[str, Any]:
+    """Load and validate a project-owned subset JSON schema."""
+
+    try:
+        value = json.loads(
+            path.read_text(encoding="utf-8"),
+            parse_constant=lambda value: (_ for _ in ()).throw(
+                ValueError(f"invalid JSON constant {value}")
+            ),
+        )
+    except (OSError, UnicodeError, ValueError) as exc:
+        raise SchemaDefinitionError(f"schema is not readable JSON: {exc}") from exc
+    validate_schema_definition(value)
+    return value
+
+
+def validate_schema_definition(schema: Any, *, location: str = "$") -> None:
+    """Reject unsupported or malformed schema definitions recursively."""
+
+    if not isinstance(schema, Mapping):
+        raise SchemaDefinitionError("schema must be an object", location=location)
+    unknown = sorted(set(schema) - SUPPORTED_SCHEMA_KEYWORDS)
+    if unknown:
+        raise SchemaDefinitionError(
+            f"unsupported schema keyword {unknown[0]!r}", location=location
+        )
+    schema_type = schema.get("type")
+    if schema_type is not None and schema_type not in SUPPORTED_JSON_TYPES:
+        raise SchemaDefinitionError(
+            f"unsupported schema type {schema_type!r}", location=f"{location}.type"
+        )
+    required = schema.get("required")
+    if required is not None and (
+        not isinstance(required, list)
+        or any(not isinstance(item, str) or not item for item in required)
+        or len(set(required)) != len(required)
+    ):
+        raise SchemaDefinitionError(
+            "required must be a unique list of non-empty strings",
+            location=f"{location}.required",
+        )
+    properties = schema.get("properties")
+    if properties is not None:
+        if not isinstance(properties, Mapping) or any(
+            not isinstance(name, str) for name in properties
+        ):
+            raise SchemaDefinitionError(
+                "properties must be an object", location=f"{location}.properties"
+            )
+        for name, child in properties.items():
+            validate_schema_definition(child, location=f"{location}.properties.{name}")
+    if "items" in schema:
+        validate_schema_definition(schema["items"], location=f"{location}.items")
+    enum = schema.get("enum")
+    if enum is not None:
+        if not isinstance(enum, list) or not enum:
+            raise SchemaDefinitionError(
+                "enum must be a non-empty array", location=f"{location}.enum"
+            )
+        try:
+            json.dumps(enum, allow_nan=False)
+        except (TypeError, ValueError) as exc:
+            raise SchemaDefinitionError(
+                "enum values must be JSON values", location=f"{location}.enum"
+            ) from exc
+    pattern = schema.get("pattern")
+    if pattern is not None:
+        if not isinstance(pattern, str):
+            raise SchemaDefinitionError(
+                "pattern must be a string", location=f"{location}.pattern"
+            )
+        try:
+            re.compile(pattern)
+        except re.error as exc:
+            raise SchemaDefinitionError(
+                f"pattern is invalid: {exc}", location=f"{location}.pattern"
+            ) from exc
+    additional = schema.get("additionalProperties")
+    if additional is not None and not isinstance(additional, bool):
+        if not isinstance(additional, Mapping):
+            raise SchemaDefinitionError(
+                "additionalProperties must be a boolean or schema",
+                location=f"{location}.additionalProperties",
+            )
+        validate_schema_definition(
+            additional, location=f"{location}.additionalProperties"
+        )
+
+
+def _validate_json_value(
+    value: Any,
+    schema: Mapping[str, Any],
+    location: str,
+    errors: list[dict[str, str]],
+) -> None:
+    expected = schema.get("type")
+    if expected is not None and not _matches_type(value, expected):
+        errors.append({"path": location, "message": f"expected {expected}"})
+        return
+    if "enum" in schema and not any(
+        type(value) is type(item) and value == item for item in schema["enum"]
+    ):
+        errors.append({"path": location, "message": "value is not in enum"})
+    if "pattern" in schema and isinstance(value, str) and re.search(schema["pattern"], value) is None:
+        errors.append({"path": location, "message": "string does not match pattern"})
+    if isinstance(value, dict):
+        properties = schema.get("properties", {})
+        for name in schema.get("required", []):
+            if name not in value:
+                errors.append(
+                    {"path": location, "message": f"missing required property {name!r}"}
+                )
+        additional = schema.get("additionalProperties", True)
+        extra_names = sorted(set(value) - set(properties))
+        if additional is False:
+            for name in extra_names:
+                errors.append(
+                    {"path": f"{location}.{name}", "message": "additional property is not allowed"}
+                )
+        elif isinstance(additional, Mapping):
+            for name in extra_names:
+                _validate_json_value(
+                    value[name], additional, f"{location}.{name}", errors
+                )
+        for name, child_schema in properties.items():
+            if name in value:
+                _validate_json_value(value[name], child_schema, f"{location}.{name}", errors)
+    if isinstance(value, list) and "items" in schema:
+        for index, item in enumerate(value):
+            _validate_json_value(item, schema["items"], f"{location}[{index}]", errors)
+
+
+def _matches_type(value: Any, expected: str) -> bool:
+    if expected == "null":
+        return value is None
+    if expected == "boolean":
+        return isinstance(value, bool)
+    if expected == "integer":
+        return isinstance(value, int) and not isinstance(value, bool)
+    if expected == "number":
+        return isinstance(value, (int, float)) and not isinstance(value, bool)
+    if expected == "string":
+        return isinstance(value, str)
+    if expected == "array":
+        return isinstance(value, list)
+    if expected == "object":
+        return isinstance(value, dict)
+    return False

specromancy_engine/schemas/event.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://specromancy.dev/schemas/event.schema.json",
+  "title": "Specromancy audit event",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "sequence",
+    "timestamp",
+    "run_id",
+    "visit_number",
+    "type",
+    "payload",
+    "manifest_revision",
+    "manifest_hash"
+  ],
+  "properties": {
+    "schema_version": {"const": 1},
+    "sequence": {"type": "integer", "minimum": 1},
+    "timestamp": {"type": "string", "pattern": "Z$"},
+    "run_id": {
+      "type": "string",
+      "pattern": "^[0-9]{8}T[0-9]{6}Z-[0-9a-f]{8}$"
+    },
+    "visit_number": {
+      "oneOf": [{"type": "null"}, {"type": "integer", "minimum": 1}]
+    },
+    "type": {"type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"},
+    "payload": {"type": "object"},
+    "manifest_revision": {"type": "integer", "minimum": 1},
+    "manifest_hash": {"type": "string", "pattern": "^[0-9a-f]{64}$"}
+  }
+}

specromancy_engine/schemas/pipeline.schema.json

@@ -0,0 +1,154 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://specromancy.dev/schemas/pipeline.schema.json",
+  "title": "Specromancy pipeline",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "id",
+    "version",
+    "start",
+    "terminal_outcomes",
+    "artifact_pattern",
+    "phases"
+  ],
+  "properties": {
+    "schema_version": {"const": 1},
+    "id": {"$ref": "#/$defs/identifier"},
+    "version": {"type": "integer", "minimum": 1},
+    "start": {"$ref": "#/$defs/identifier"},
+    "terminal_outcomes": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {"$ref": "#/$defs/identifier"}
+    },
+    "artifact_pattern": {"type": "string", "minLength": 1},
+    "allow_non_git": {"type": "boolean"},
+    "phases": {
+      "type": "array",
+      "minItems": 1,
+      "items": {"$ref": "#/$defs/phase"}
+    }
+  },
+  "$defs": {
+    "identifier": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+    },
+    "stringList": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {"type": "string", "minLength": 1}
+    },
+    "validator": {
+      "oneOf": [
+        {"enum": ["markdown", "json", "file"]},
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type"],
+          "properties": {
+            "type": {"enum": ["markdown", "json", "file"]},
+            "required_headings": {"$ref": "#/$defs/stringList"},
+            "heading_occurrence": {"enum": ["exactly-once", "at-least-once"]},
+            "path": {"type": "string", "minLength": 1},
+            "schema": {"type": "string", "minLength": 1}
+          }
+        }
+      ]
+    },
+    "command": {
+      "oneOf": [
+        {
+          "type": "array",
+          "minItems": 1,
+          "items": {"type": "string", "minLength": 1}
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["argv"],
+          "properties": {
+            "argv": {
+              "type": "array",
+              "minItems": 1,
+              "items": {"type": "string", "minLength": 1}
+            },
+            "timeout_seconds": {"type": "number", "exclusiveMinimum": 0},
+            "required": {"type": "boolean"}
+          }
+        }
+      ]
+    },
+    "transition": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["outcome"],
+      "properties": {
+        "outcome": {"$ref": "#/$defs/identifier"},
+        "target": {"$ref": "#/$defs/identifier"},
+        "max_traversals": {"type": "integer", "minimum": 1},
+        "pause": {"type": "boolean"}
+      }
+    },
+    "phase": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "skill",
+        "inputs",
+        "output_name",
+        "mutation",
+        "completion_criteria",
+        "validator",
+        "approval_conditions",
+        "stop_conditions",
+        "transitions"
+      ],
+      "properties": {
+        "id": {"$ref": "#/$defs/identifier"},
+        "skill": {"$ref": "#/$defs/identifier"},
+        "inputs": {"$ref": "#/$defs/stringList"},
+        "output_name": {"type": "string", "minLength": 1},
+        "output_template": {"type": "string", "minLength": 1},
+        "mutation": {"enum": ["read-only", "repository-write", "allowlist"]},
+        "allowlist": {"$ref": "#/$defs/stringList"},
+        "mutation_allowlist": {"$ref": "#/$defs/stringList"},
+        "completion_criteria": {
+          "allOf": [{"$ref": "#/$defs/stringList"}, {"minItems": 1}]
+        },
+        "validator": {"$ref": "#/$defs/validator"},
+        "validator_path": {"type": "string", "minLength": 1},
+        "required_headings": {"$ref": "#/$defs/stringList"},
+        "heading_occurrence": {"enum": ["exactly-once", "at-least-once"]},
+        "commands": {
+          "type": "array",
+          "items": {"$ref": "#/$defs/command"}
+        },
+        "validation_commands": {
+          "type": "array",
+          "items": {"$ref": "#/$defs/command"}
+        },
+        "approval_conditions": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {"$ref": "#/$defs/identifier"}
+        },
+        "stop_conditions": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {"$ref": "#/$defs/identifier"}
+        },
+        "transitions": {
+          "type": "array",
+          "minItems": 1,
+          "items": {"$ref": "#/$defs/transition"}
+        },
+        "max_visits": {"type": "integer", "minimum": 1}
+      }
+    }
+  }
+}

specromancy_engine/schemas/pipelines.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Specromancy pipeline registry",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "pipelines"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "const": 1,
+      "type": "integer"
+    },
+    "pipelines": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "path"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+          },
+          "path": {
+            "type": "string",
+            "pattern": "^pipelines/(?:[A-Za-z0-9_-]+/)*[A-Za-z0-9_-]+\\.toml$"
+          }
+        }
+      }
+    }
+  }
+}

specromancy_engine/schemas/run.schema.json

@@ -0,0 +1,152 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://specromancy.dev/schemas/run.schema.json",
+  "title": "Specromancy run manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "revision",
+    "run_id",
+    "pipeline",
+    "status",
+    "current_visit",
+    "request",
+    "git",
+    "created_at",
+    "updated_at",
+    "visits",
+    "approvals",
+    "terminal_result",
+    "block_reason"
+  ],
+  "properties": {
+    "schema_version": {"const": 1},
+    "revision": {"type": "integer", "minimum": 1},
+    "run_id": {"$ref": "#/$defs/runId"},
+    "pipeline": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "version", "path", "sha256"],
+      "properties": {
+        "id": {"type": "string", "minLength": 1},
+        "version": {"type": "integer", "minimum": 1},
+        "path": {"$ref": "#/$defs/path"},
+        "sha256": {"$ref": "#/$defs/hash"}
+      }
+    },
+    "status": {"$ref": "#/$defs/status"},
+    "current_visit": {
+      "oneOf": [{"type": "null"}, {"type": "integer", "minimum": 1}]
+    },
+    "request": {"$ref": "#/$defs/sealedArtifact"},
+    "git": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["base", "head"],
+      "properties": {"base": {}, "head": {}}
+    },
+    "created_at": {"$ref": "#/$defs/timestamp"},
+    "updated_at": {"$ref": "#/$defs/timestamp"},
+    "visits": {"type": "array", "items": {"$ref": "#/$defs/visit"}},
+    "approvals": {"type": "array", "items": {"type": "object"}},
+    "terminal_result": {},
+    "block_reason": {}
+  },
+  "$defs": {
+    "runId": {
+      "type": "string",
+      "pattern": "^[0-9]{8}T[0-9]{6}Z-[0-9a-f]{8}$"
+    },
+    "hash": {"type": "string", "pattern": "^[0-9a-f]{64}$"},
+    "path": {"type": "string", "minLength": 1, "pattern": "^(?!/)(?!.*(?:^|/)\\.{1,2}(?:/|$))(?!.*\\\\).+$"},
+    "timestamp": {"type": "string", "pattern": "Z$"},
+    "status": {
+      "enum": ["active", "awaiting-agent", "awaiting-approval", "paused", "completed", "failed", "blocked"]
+    },
+    "visitStatus": {
+      "enum": ["pending", "active", "awaiting-approval", "completed", "failed", "blocked"]
+    },
+    "sealedArtifact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "sha256"],
+      "properties": {
+        "path": {"$ref": "#/$defs/path"},
+        "sha256": {"$ref": "#/$defs/hash"}
+      }
+    },
+    "inputArtifact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["reference", "path", "sha256"],
+      "properties": {
+        "reference": {"type": "string", "minLength": 1},
+        "path": {"$ref": "#/$defs/path"},
+        "sha256": {"$ref": "#/$defs/hash"}
+      }
+    },
+    "outputArtifact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "sha256"],
+      "properties": {
+        "path": {"$ref": "#/$defs/path"},
+        "sha256": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/hash"}]}
+      }
+    },
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "sha256"],
+      "properties": {
+        "path": {"$ref": "#/$defs/path"},
+        "sha256": {"$ref": "#/$defs/hash"}
+      }
+    },
+    "visit": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "phase_id",
+        "ordinal",
+        "attempt",
+        "status",
+        "inputs",
+        "output",
+        "mutation_policy",
+        "mutation_baseline",
+        "mutation_result",
+        "validation_checks",
+        "command_results",
+        "chosen_outcome",
+        "transition_target",
+        "skill",
+        "template",
+        "started_at",
+        "completed_at",
+        "deviations"
+      ],
+      "properties": {
+        "phase_id": {"type": "string", "minLength": 1},
+        "ordinal": {"type": "integer", "minimum": 1},
+        "attempt": {"type": "integer", "minimum": 1},
+        "status": {"$ref": "#/$defs/visitStatus"},
+        "inputs": {"type": "array", "items": {"$ref": "#/$defs/inputArtifact"}},
+        "output": {"$ref": "#/$defs/outputArtifact"},
+        "mutation_policy": {"enum": ["read-only", "repository-write", "allowlist"]},
+        "mutation_baseline": {},
+        "mutation_result": {},
+        "validation_checks": {"type": "array"},
+        "command_results": {"type": "array"},
+        "chosen_outcome": {"oneOf": [{"type": "null"}, {"type": "string"}]},
+        "transition_target": {"oneOf": [{"type": "null"}, {"type": "string"}]},
+        "skill": {"$ref": "#/$defs/provenance"},
+        "template": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/provenance"}]},
+        "started_at": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/timestamp"}]},
+        "completed_at": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/timestamp"}]},
+        "deviations": {"type": "array"}
+      }
+    }
+  }
+}

specromancy_engine/status.py

@@ -0,0 +1,106 @@
+"""Read-only status projection for persisted runs."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._config.config_models import PipelineConfig
+from ._runs.run_records import RunRecord, VisitRecord, current_visit, latest_approval
+
+
+STATUS_SCHEMA_VERSION = 1
+
+
+def build_status(
+    manifest: RunRecord,
+    pipeline: PipelineConfig | None,
+    *,
+    warnings: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    current = _current_visit(manifest)
+    completed = [
+        {
+            "visit_id": visit["ordinal"],
+            "phase": visit["phase_id"],
+            "outcome": visit["chosen_outcome"],
+            "output": visit["output"],
+        }
+        for visit in manifest["visits"]
+        if visit["status"] == "completed"
+    ]
+    pending_approval = latest_approval(manifest, "pending")
+    return {
+        "schema_version": STATUS_SCHEMA_VERSION,
+        "run_id": manifest["run_id"],
+        "pipeline": {
+            **manifest["pipeline"],
+            "current_sha256": pipeline.config_hash if pipeline is not None else None,
+        },
+        "status": manifest["status"],
+        "current": (
+            {
+                "visit_id": current["ordinal"],
+                "phase": current["phase_id"],
+                "status": current["status"],
+                "output": current["output"],
+            }
+            if current is not None
+            else None
+        ),
+        "completed_visits": completed,
+        "pending_approval": pending_approval,
+        "block": manifest["block_reason"],
+        "terminal_result": manifest["terminal_result"],
+        "next_command": next_command(manifest),
+        "warnings": list(warnings or []),
+    }
+
+
+def next_command(manifest: RunRecord) -> list[str] | None:
+    run_id = manifest["run_id"]
+    current = _current_visit(manifest)
+    if manifest["status"] == "awaiting-agent" and current is not None:
+        return ["specromancy", "phase", run_id, current["phase_id"]]
+    if manifest["status"] == "active" and current is not None:
+        return ["specromancy", "validate", run_id, current["phase_id"]]
+    if manifest["status"] == "awaiting-approval" and current is not None:
+        pending = latest_approval(
+            manifest, "pending", visit_number=current["ordinal"]
+        )
+        if pending:
+            return ["specromancy", "approve", run_id, current["phase_id"]]
+        return ["specromancy", "request-approval", run_id]
+    if manifest["status"] == "paused":
+        return ["specromancy", "resume", run_id]
+    if manifest["status"] == "blocked":
+        return ["specromancy", "status", run_id]
+    return None
+
+
+def render_status(status: dict[str, Any]) -> str:
+    current = status["current"]
+    lines = [
+        f"Run: {status['run_id']}",
+        f"Pipeline: {status['pipeline']['id']} v{status['pipeline']['version']}",
+        f"Status: {status['status']}",
+    ]
+    if current is not None:
+        lines.append(
+            f"Current: visit {current['visit_id']} / {current['phase']} / {current['status']}"
+        )
+    lines.append(f"Completed visits: {len(status['completed_visits'])}")
+    if status["pending_approval"] is not None:
+        lines.append(
+            f"Approval: {status['pending_approval'].get('reason', 'pending')}"
+        )
+    if status["block"] is not None:
+        lines.append(f"Block: {status['block']}")
+    if status["next_command"] is not None:
+        lines.append("Next: " + " ".join(status["next_command"]))
+    for warning in status["warnings"]:
+        lines.append(f"Warning: {warning['message']}")
+    return "\n".join(lines)
+
+
+def _current_visit(manifest: RunRecord) -> VisitRecord | None:
+    return current_visit(manifest)