pgc-runtime 2.0.0__py3-none-any.whl

runtime/examine/hint_engine.py

@@ -0,0 +1,245 @@
+"""
+hint_engine.py — Prescriptive fix hint generation.
+
+Governed by: Trace Examiner spec §G4
+
+Generates short, concrete, actionable fix hints from failure classification.
+Every hint references a specific artifact and field. No generic messages.
+Pure function — no external imports.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runtime.examine.classifier import ClassificationResult, FailureClass
+from runtime.examine.parser import ParsedTrace, TraceEventDict
+
+
+def _payload(event: TraceEventDict) -> dict[str, Any]:
+    return event.get("payload", {})
+
+
+def generate_hint(
+    trace: ParsedTrace,
+    result: ClassificationResult,
+    artifact_path: str | None,
+) -> str:
+    """
+    Generate a prescriptive fix hint from classification result.
+
+    Args:
+        trace: Parsed trace.
+        result: Classification result.
+        artifact_path: Resolved artifact path (may be None).
+
+    Returns:
+        Concrete, actionable fix hint string.
+    """
+    fc = result.failure_class
+    if fc is None:
+        return "No action required"
+
+    node_id = result.node_id or "unknown node"
+    error_code = result.error_code or ""
+    message = result.message
+
+    if fc == FailureClass.EXPRESSION_ERROR:
+        return _hint_expression_error(node_id, message, artifact_path)
+
+    if fc == FailureClass.SCHEMA_ERROR:
+        return _hint_schema_error(node_id, message, artifact_path)
+
+    if fc == FailureClass.BINDING_ERROR:
+        return _hint_binding_error(node_id, error_code, message, artifact_path)
+
+    if fc == FailureClass.CT_STRUCTURE_ERROR:
+        return _hint_ct_error(node_id, error_code, message, artifact_path, result)
+
+    if fc == FailureClass.CS_RUNTIME_ERROR:
+        return _hint_cs_error(node_id, message, artifact_path)
+
+    if fc == FailureClass.ADMISSION_ERROR:
+        return _hint_admission_error(trace, result, error_code, message, artifact_path)
+
+    if fc == FailureClass.GRAPH_STRUCTURE_ERROR:
+        return _hint_graph_error(trace, result, artifact_path)
+
+    if fc == FailureClass.BUSINESS_VIOLATION:
+        return f"Business violation at {node_id} — this is domain behavior, not a bug"
+
+    return f"Check {artifact_path or 'workflow artifacts'} for issues at {node_id}"
+
+
+def _hint_expression_error(
+    node_id: str, message: str, artifact_path: str | None
+) -> str:
+    """Hint for EXPRESSION_RESOLUTION_FAILED."""
+    # Try to extract the expression path from the message
+    # Message format is typically: "Cannot resolve $.payload.field_name"
+    expr = _extract_expression(message)
+    if expr:
+        field_name = expr.split(".")[-1] if "." in expr else expr
+        target = f" in {artifact_path}" if artifact_path else ""
+        return (
+            f"Add '{field_name}' to input payload or fix expression '{expr}' "
+            f"in input_bindings for node {node_id}{target}"
+        )
+    target = f" — check {artifact_path}" if artifact_path else ""
+    return f"Fix unresolved expression in input_bindings for node {node_id}{target}"
+
+
+def _hint_schema_error(
+    node_id: str, message: str, artifact_path: str | None
+) -> str:
+    """Hint for SCHEMA_VALIDATION_FAILED."""
+    target = f" in {artifact_path}" if artifact_path else ""
+    return f"Fix schema violation at node {node_id}{target}: {_truncate(message, 100)}"
+
+
+def _hint_binding_error(
+    node_id: str, error_code: str, message: str, artifact_path: str | None
+) -> str:
+    """Hint for BINDING_RESOLUTION_FAILED."""
+    target = f" in {artifact_path}" if artifact_path else ""
+    if "missing" in message.lower() or "not found" in message.lower():
+        return (
+            f"Add missing binding entry for {node_id}{target} — "
+            f"check runtime binding and CC pipeline bindings"
+        )
+    return f"Fix binding resolution for {node_id}{target}: {_truncate(message, 100)}"
+
+
+def _hint_ct_error(
+    node_id: str,
+    error_code: str,
+    message: str,
+    artifact_path: str | None,
+    result: ClassificationResult,
+) -> str:
+    """Hint for CT_* errors."""
+    target = f" — check {artifact_path}" if artifact_path else ""
+
+    if error_code == "CT_ARTIFACT_NOT_FOUND":
+        artifact_code = _extract_ct_code_from_result(result)
+        if artifact_code:
+            return f"CT artifact '{artifact_code}' not found{target}. Run build or check atom registration"
+        return f"CT artifact not found for {node_id}{target}. Run build or check atom registration"
+
+    if error_code == "CT_VALIDATION_FAILED":
+        return f"CT validation failed for {node_id}{target}: {_truncate(message, 100)}"
+
+    if error_code == "CT_EXECUTION_FAILED":
+        return f"CT execution failed at {node_id}{target}: {_truncate(message, 80)}"
+
+    if error_code == "CAPABILITY_NOT_FOUND":
+        return f"Capability contract '{node_id}' not found in loaded contracts{target}"
+
+    if error_code == "CAPABILITY_DISPATCH_FAILED":
+        return f"Capability dispatch failed for {node_id}{target}: {_truncate(message, 80)}"
+
+    return f"Transform error at {node_id}{target}: {_truncate(message, 80)}"
+
+
+def _hint_cs_error(
+    node_id: str, message: str, artifact_path: str | None
+) -> str:
+    """Hint for CS_EXECUTION_FAILED."""
+    target = f" — check runtime binding at {artifact_path}" if artifact_path else ""
+    return f"Side-effect execution failed at {node_id}{target}: {_truncate(message, 80)}"
+
+
+def _hint_admission_error(
+    trace: ParsedTrace,
+    result: ClassificationResult,
+    error_code: str,
+    message: str,
+    artifact_path: str | None,
+) -> str:
+    """Hint for ADMISSION_ERROR — missing binding field or admission denial."""
+    target = f" — see {artifact_path}" if artifact_path else ""
+
+    if error_code == "ADMISSION_BINDING_MISSING_FIELD":
+        # Extract the missing payload field from the structured message.
+        # Message format: "Admission binding for 'EV_...' references payload field 'field_name' ..."
+        import re
+        field_match = re.search(r"payload field '([^']+)'", message)
+        event_match = re.search(r"binding for '([^']+)'", message)
+        field = field_match.group(1) if field_match else "unknown"
+        event_code = event_match.group(1) if event_match else "unknown"
+
+        return (
+            f"Admission gate for {trace.workflow_code} requires '{field}' in payload{target}. "
+            f"Binding: {event_code} → payload.{field}. "
+            f"Ensure the caller forwards '{field}' from the upstream workflow that produced it "
+            f"(e.g. via output of the registration step)."
+        )
+
+    # Generic admission denial
+    return (
+        f"Admission denied for {trace.workflow_code}{target}. "
+        f"Check admission.requires conditions are satisfied before invoking this workflow. "
+        f"Detail: {_truncate(message, 100)}"
+    )
+
+
+def _hint_graph_error(
+    trace: ParsedTrace,
+    result: ClassificationResult,
+    artifact_path: str | None,
+) -> str:
+    """Hint for GRAPH_STRUCTURE_ERROR."""
+    target = f" in {artifact_path}" if artifact_path else ""
+    exit_reason = trace.exit_reason_code
+
+    if exit_reason == "NO_TRANSITION":
+        # Try to extract from/status from exit_condition message
+        condition = trace.exit_condition
+        return (
+            f"No transition edge found{target}. "
+            f"Add missing edge for the result_status in workflow spec. "
+            f"Detail: {_truncate(condition, 100)}"
+        )
+
+    if exit_reason == "NO_ENTRY_NODE":
+        return f"DAG has no entry node{target}. Check workflow spec node definitions"
+
+    if exit_reason == "NODE_NOT_FOUND":
+        return f"Referenced node missing from DAG{target}. Check edge targets in workflow spec"
+
+    return f"Graph structure error ({exit_reason}){target}"
+
+
+# --- Helpers ---
+
+
+def _extract_expression(message: str) -> str:
+    """Try to extract a $.path expression from an error message."""
+    # Look for $.payload.xxx or $.capability_result.xxx patterns
+    import re
+
+    match = re.search(r'(\$\.\w+(?:\.\w+)*)', message)
+    if match:
+        return match.group(1)
+    return ""
+
+
+def _extract_ct_code_from_result(result: ClassificationResult) -> str:
+    """Try to extract CT code from result details."""
+    if result.root_event is None:
+        return ""
+    p = _payload(result.root_event)
+    details = p.get("details", {})
+    if isinstance(details, dict) and "artifact_code" in details:
+        return details["artifact_code"]
+    node_id = p.get("node_id", "")
+    if node_id.startswith("CT_"):
+        return node_id
+    return ""
+
+
+def _truncate(s: str, max_len: int) -> str:
+    """Truncate string with ellipsis if too long."""
+    if len(s) <= max_len:
+        return s
+    return s[: max_len - 3] + "..."

runtime/examine/locator.py

@@ -0,0 +1,148 @@
+"""
+locator.py — Artifact path resolution for failing nodes.
+
+Governed by: Trace Examiner spec §G3
+
+Maps node_id / capability codes to artifact file paths via snapshot artifacts dir.
+
+Snapshot artifacts follow the naming convention: {namespace}__{CODE}.json
+Snapshot root is derived from the trace path by the caller (STRUCTURE layout convention):
+  trace_path = {workspace}/traces/{id}/{id}.jsonl
+  snapshot   = {workspace}/protocol_snapshot
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from runtime.examine.classifier import ClassificationResult, FailureClass
+from runtime.examine.parser import ParsedTrace, TraceEventDict
+
+
+def _payload(event: TraceEventDict) -> dict[str, Any]:
+    return event.get("payload", {})
+
+
+def _find_node_start(trace: ParsedTrace, node_id: str) -> TraceEventDict | None:
+    """Find node_start event for a given node_id."""
+    for event in trace.events:
+        if (
+            event.get("event_type") == "node_start"
+            and _payload(event).get("node_id") == node_id
+        ):
+            return event
+    return None
+
+
+def _artifacts_dir(snapshot_root: Path, artifact_type: str) -> Path | None:
+    """Return the snapshot artifacts dir for the given type, or None if missing."""
+    d = snapshot_root / "artifacts" / artifact_type
+    return d if d.is_dir() else None
+
+
+def _find_artifact(snapshot_root: Path, artifact_type: str, code: str) -> str | None:
+    """
+    Find an artifact file in the snapshot by code suffix match.
+
+    Snapshot artifacts: {namespace}__{CODE}.json (case-insensitive code match).
+    Returns the absolute path as a string, or None if not found.
+    """
+    d = _artifacts_dir(snapshot_root, artifact_type)
+    if d is None:
+        return None
+    suffix_lower = f"__{code.lower()}.json"
+    for artifact_path in d.glob("*.json"):
+        if artifact_path.name.lower().endswith(suffix_lower):
+            return str(artifact_path)
+    return None
+
+
+def locate_artifact(
+    trace: ParsedTrace,
+    result: ClassificationResult,
+    snapshot_root: Path | None = None,
+) -> str | None:
+    """
+    Resolve the failing artifact path from classification result.
+
+    Uses snapshot_root (derived from workspace layout) to find artifacts.
+    Returns the absolute path string, or None if unresolvable.
+
+    Args:
+        trace: Parsed trace.
+        result: Classification result from classifier.
+        snapshot_root: Path to the protocol_snapshot directory. If None,
+                       artifact resolution is skipped and None is returned.
+
+    Returns:
+        Absolute path to the failing artifact, or None.
+    """
+    if snapshot_root is None:
+        return None
+
+    node_id = result.node_id
+
+    # Admission errors fire before DAG entry — "ADMISSION" is a synthetic pre-node identifier.
+    # There is no node_start event for it; route directly to the workflow spec.
+    if result.failure_class == FailureClass.ADMISSION_ERROR:
+        return _find_artifact(snapshot_root, "workflows", trace.workflow_code)
+
+    if node_id is None:
+        # Graph structure errors — point to the workflow spec
+        if result.failure_class == FailureClass.GRAPH_STRUCTURE_ERROR:
+            return _find_artifact(snapshot_root, "workflows", trace.workflow_code)
+        return None
+
+    # Look up node_type from node_start event
+    node_start = _find_node_start(trace, node_id)
+    node_type = _payload(node_start).get("node_type", "") if node_start else ""
+
+    # Route to artifact based on node_type and failure class
+    if result.failure_class == FailureClass.EXPRESSION_ERROR:
+        return _find_artifact(snapshot_root, "workflows", trace.workflow_code)
+
+    if result.failure_class == FailureClass.BINDING_ERROR:
+        if node_id.startswith("CC_"):
+            return _find_artifact(snapshot_root, "capability_contracts", node_id)
+        return _find_artifact(snapshot_root, "workflows", trace.workflow_code)
+
+    if result.failure_class == FailureClass.CT_STRUCTURE_ERROR:
+        error_code = result.error_code
+        if error_code in ("CT_ARTIFACT_NOT_FOUND", "CT_VALIDATION_FAILED", "CT_EXECUTION_FAILED"):
+            artifact_code = _extract_ct_code(result)
+            if artifact_code:
+                return _find_artifact(snapshot_root, "capability_transforms", artifact_code)
+        if node_id.startswith("CC_"):
+            return _find_artifact(snapshot_root, "capability_contracts", node_id)
+        return _find_artifact(snapshot_root, "workflows", trace.workflow_code)
+
+    if result.failure_class == FailureClass.CS_RUNTIME_ERROR:
+        return _find_artifact(snapshot_root, "runtime_bindings", trace.workflow_code)
+
+    if result.failure_class == FailureClass.SCHEMA_ERROR:
+        if node_id.startswith("CC_"):
+            return _find_artifact(snapshot_root, "capability_contracts", node_id)
+        return _find_artifact(snapshot_root, "workflows", trace.workflow_code)
+
+    if node_type == "intent":
+        return _find_artifact(snapshot_root, "intents", node_id)
+
+    if node_type == "capability_contract":
+        return _find_artifact(snapshot_root, "capability_contracts", node_id)
+
+    return _find_artifact(snapshot_root, "workflows", trace.workflow_code)
+
+
+def _extract_ct_code(result: ClassificationResult) -> str | None:
+    """Try to extract CT code from error event details."""
+    if result.root_event is None:
+        return None
+    p = _payload(result.root_event)
+    details = p.get("details", {})
+    if isinstance(details, dict) and "artifact_code" in details:
+        return details["artifact_code"]
+    node_id = p.get("node_id", "")
+    if node_id.startswith("CT_"):
+        return node_id
+    return None

runtime/examine/parser.py

@@ -0,0 +1,223 @@
+"""
+parser.py — JSONL trace loader with strict field validation.
+
+Governed by: STRUCTURE_TRACE_SCHEMA_V0
+
+Reads a completed trace JSONL file and returns a ParsedTrace.
+Validates required fields per schema — rejects malformed events.
+Imports only json and pathlib — no execution/machine imports.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+# Type alias — raw dict from JSONL line
+TraceEventDict = dict[str, Any]
+
+# ─── Required fields per SCHEMA_TRACE_EVENT_V0 ───
+# Duplicated as constants (spec §6: no imports from execution/machine/)
+
+# Version pin — examiner rejects traces produced by incompatible schema versions.
+# Increment when execution_start or workflow_complete payload shape changes.
+_EXPECTED_TRACE_SCHEMA_VERSION = "TRACE_SCHEMA_V0"
+
+# Every event must have these top-level fields
+_REQUIRED_TOP_LEVEL = ("event_type", "timestamp", "execution_id", "sequence")
+
+# Per-event-type required payload fields (from schema allOf conditionals)
+_REQUIRED_PAYLOAD: dict[str, tuple[str, ...]] = {
+    "execution_start": ("workflow_code", "trace_schema_version"),
+    "node_start": ("node_id", "node_type"),
+    "node_end": ("node_id", "status", "duration_ms"),
+    "workflow_complete": ("status", "duration_ms", "exit_condition", "exit_reason_code"),
+    "capability_dispatch": ("cc_code", "node_id"),
+    "transform_start": ("artifact_code",),
+    "transform_end": ("artifact_code", "duration_ms"),
+    "context_snapshot": ("context_hash", "sequence"),
+    "error": ("error_code", "message", "node_category"),
+}
+
+
+@dataclass
+class ParsedTrace:
+    """
+    Structured representation of a completed trace.
+
+    Extracted from JSONL trace file after execution.
+    """
+
+    execution_id: str
+    workflow_code: str
+    trace_schema_version: str  # from execution_start.payload.trace_schema_version
+    events: list[TraceEventDict]
+    status: str  # from workflow_complete.payload.status
+    exit_reason_code: str  # from workflow_complete.payload.exit_reason_code
+    exit_condition: str  # from workflow_complete.payload.exit_condition
+
+    # Convenience: pre-indexed subsets
+    error_events: list[TraceEventDict] = field(default_factory=list)
+    node_end_events: list[TraceEventDict] = field(default_factory=list)
+    capability_dispatch_events: list[TraceEventDict] = field(default_factory=list)
+    workflow_complete_event: TraceEventDict | None = None
+
+
+class TraceParseError(Exception):
+    """Raised when a trace file cannot be parsed or contains invalid events."""
+
+    pass
+
+
+def _validate_event(event: TraceEventDict, line_num: int, trace_path: Path) -> None:
+    """
+    Validate required fields on a single trace event.
+
+    Checks:
+      1. Top-level required fields (event_type, timestamp, execution_id, sequence)
+      2. Per-event-type required payload fields from SCHEMA_TRACE_EVENT_V0
+
+    Raises:
+        TraceParseError on missing required field.
+    """
+    # Top-level required fields
+    for field_name in _REQUIRED_TOP_LEVEL:
+        if field_name not in event:
+            raise TraceParseError(
+                f"Event at line {line_num} missing required field '{field_name}' "
+                f"in {trace_path}"
+            )
+
+    # Per-event-type payload validation
+    event_type = event["event_type"]
+    required_payload_fields = _REQUIRED_PAYLOAD.get(event_type)
+    if required_payload_fields is not None:
+        payload = event.get("payload")
+        if payload is None:
+            raise TraceParseError(
+                f"Event '{event_type}' at line {line_num} missing 'payload' "
+                f"in {trace_path}"
+            )
+        for field_name in required_payload_fields:
+            if field_name not in payload:
+                raise TraceParseError(
+                    f"Event '{event_type}' at line {line_num} missing required "
+                    f"payload field '{field_name}' in {trace_path}"
+                )
+
+
+def parse_trace(trace_path: Path) -> ParsedTrace:
+    """
+    Parse a JSONL trace file into a ParsedTrace.
+
+    Args:
+        trace_path: Path to the .jsonl trace file.
+
+    Returns:
+        ParsedTrace with all events loaded and indexed.
+
+    Raises:
+        TraceParseError: If trace is missing, empty, or structurally invalid.
+    """
+    if not trace_path.exists():
+        raise TraceParseError(f"Trace file not found: {trace_path}")
+
+    events: list[TraceEventDict] = []
+    error_events: list[TraceEventDict] = []
+    node_end_events: list[TraceEventDict] = []
+    capability_dispatch_events: list[TraceEventDict] = []
+    workflow_complete_event: TraceEventDict | None = None
+
+    with open(trace_path, "r", encoding="utf-8") as f:
+        for line_num, line in enumerate(f, start=1):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                event = json.loads(line)
+            except json.JSONDecodeError as e:
+                raise TraceParseError(
+                    f"Invalid JSON at line {line_num} in {trace_path}: {e}"
+                )
+
+            _validate_event(event, line_num, trace_path)
+            events.append(event)
+
+            event_type = event.get("event_type")
+            if event_type == "error":
+                error_events.append(event)
+            elif event_type == "node_end":
+                node_end_events.append(event)
+            elif event_type == "capability_dispatch":
+                capability_dispatch_events.append(event)
+            elif event_type == "workflow_complete":
+                workflow_complete_event = event
+
+    if not events:
+        raise TraceParseError(f"Empty trace file: {trace_path}")
+
+    # Enforce monotonic sequence ordering (spec §5: earliest by sequence wins)
+    # Events must be in sequence order for deterministic classification.
+    # If file order doesn't match sequence order, sort explicitly.
+    sequences = [e.get("sequence", 0) for e in events]
+    if sequences != sorted(sequences):
+        events.sort(key=lambda e: e.get("sequence", 0))
+        # Re-index after sort
+        error_events = [e for e in events if e.get("event_type") == "error"]
+        node_end_events = [e for e in events if e.get("event_type") == "node_end"]
+        capability_dispatch_events = [e for e in events if e.get("event_type") == "capability_dispatch"]
+
+    # Extract execution_id from first event
+    execution_id = events[0].get("execution_id", "")
+    if not execution_id:
+        raise TraceParseError(f"First event missing execution_id in {trace_path}")
+
+    # Extract workflow_code and trace_schema_version from execution_start
+    workflow_code = ""
+    trace_schema_version = ""
+    for event in events:
+        if event.get("event_type") == "execution_start":
+            payload = event.get("payload", {})
+            workflow_code = payload.get("workflow_code", "")
+            trace_schema_version = payload.get("trace_schema_version", "")
+            break
+
+    if not workflow_code:
+        raise TraceParseError(f"No execution_start event with workflow_code in {trace_path}")
+
+    if trace_schema_version != _EXPECTED_TRACE_SCHEMA_VERSION:
+        raise TraceParseError(
+            f"Trace schema version mismatch in {trace_path}: "
+            f"expected '{_EXPECTED_TRACE_SCHEMA_VERSION}', got '{trace_schema_version}'"
+        )
+
+    # Extract final status from workflow_complete
+    if workflow_complete_event is None:
+        raise TraceParseError(f"No workflow_complete event in {trace_path}")
+
+    wc_payload = workflow_complete_event.get("payload", {})
+    status = wc_payload.get("status", "")
+    exit_reason_code = wc_payload.get("exit_reason_code", "")
+    exit_condition = wc_payload.get("exit_condition", "")
+
+    if not status:
+        raise TraceParseError(f"workflow_complete missing status in {trace_path}")
+    if not exit_reason_code:
+        raise TraceParseError(f"workflow_complete missing exit_reason_code in {trace_path}")
+
+    return ParsedTrace(
+        execution_id=execution_id,
+        workflow_code=workflow_code,
+        trace_schema_version=trace_schema_version,
+        events=events,
+        status=status,
+        exit_reason_code=exit_reason_code,
+        exit_condition=exit_condition,
+        error_events=error_events,
+        node_end_events=node_end_events,
+        capability_dispatch_events=capability_dispatch_events,
+        workflow_complete_event=workflow_complete_event,
+    )