@hunter-harness/workflow-harness 0.3.1 → 0.4.1

package/harness/bundles/general/pi/scripts/harness_migration_head.py

@@ -0,0 +1,220 @@
+#!/usr/bin/env python3
+"""Migration head single-source consistency check (Wave-2 H-7).
+
+Canonical file (default ``.harness/config/migration-head.json``)::
+
+    {
+      "schemaVersion": 1,
+      "head": "005_example",
+      "sources": [
+        {"path": "backend/app/config.py", "pattern": "EXPECTED_ALEMBIC_HEAD\\s*=\\s*[\\\"']([^\\\"']+)[\\\"']"},
+        {"path": "integration/manifest.json", "jsonPointer": "/migrationHead"}
+      ]
+    }
+
+Each source must resolve to the same ``head`` value. This harness repo may not
+ship alembic; consumer projects declare the canonical file and run::
+
+    python harness_migration_head.py check --project . --json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+DEFAULT_REL = ".harness/config/migration-head.json"
+
+
+def emit_json(payload: dict[str, Any], *, as_json: bool) -> None:
+    if as_json:
+        sys.stdout.write(json.dumps(payload, ensure_ascii=False, indent=2) + "\n")
+    else:
+        code = payload.get("code") or ("OK" if payload.get("ok") else "FAIL")
+        sys.stdout.write(f"{code}\n")
+
+
+def emit_error(code: str, message: str, *, as_json: bool, extra: dict[str, Any] | None = None) -> int:
+    payload: dict[str, Any] = {"ok": False, "code": code, "message": message}
+    if extra:
+        payload.update(extra)
+    stream = sys.stdout if as_json else sys.stderr
+    if as_json:
+        stream.write(json.dumps(payload, ensure_ascii=False, indent=2) + "\n")
+    else:
+        stream.write(f"{code}: {message}\n")
+    return 1
+
+
+def _read_json_pointer(data: Any, pointer: str) -> Any:
+    if not pointer.startswith("/"):
+        raise ValueError(f"jsonPointer must start with /: {pointer}")
+    cur = data
+    for part in pointer.lstrip("/").split("/"):
+        part = part.replace("~1", "/").replace("~0", "~")
+        if isinstance(cur, dict) and part in cur:
+            cur = cur[part]
+        else:
+            raise KeyError(pointer)
+    return cur
+
+
+def _extract_source(project: Path, source: dict[str, Any]) -> str:
+    rel = str(source.get("path") or "").strip().replace("\\", "/")
+    if not rel or rel.startswith("/") or ".." in rel.split("/"):
+        raise ValueError(f"invalid source path: {rel}")
+    target = (project / rel).resolve()
+    try:
+        target.relative_to(project.resolve())
+    except ValueError as exc:
+        raise ValueError(f"source escapes project: {rel}") from exc
+    if not target.is_file():
+        raise FileNotFoundError(rel)
+    text = target.read_text(encoding="utf-8-sig")
+    if "jsonPointer" in source and source["jsonPointer"]:
+        data = json.loads(text)
+        value = _read_json_pointer(data, str(source["jsonPointer"]))
+        if value is None or (isinstance(value, str) and not value.strip()):
+            raise ValueError(f"empty value at {source['jsonPointer']} in {rel}")
+        return str(value).strip()
+    pattern = str(source.get("pattern") or "").strip()
+    if not pattern:
+        raise ValueError(f"source {rel} requires pattern or jsonPointer")
+    match = re.search(pattern, text, flags=re.MULTILINE)
+    if not match:
+        raise ValueError(f"pattern did not match in {rel}")
+    return str(match.group(1) if match.lastindex else match.group(0)).strip()
+
+
+def check_migration_head(
+    project: Path,
+    *,
+    config_rel: str = DEFAULT_REL,
+) -> dict[str, Any]:
+    project = project.resolve()
+    config_path = (project / config_rel).resolve()
+    try:
+        config_path.relative_to(project)
+    except ValueError:
+        return {
+            "ok": False,
+            "code": "MIGRATION_HEAD_CONFIG_ESCAPE",
+            "message": f"config path escapes project: {config_rel}",
+        }
+    if not config_path.is_file():
+        return {
+            "ok": False,
+            "code": "MIGRATION_HEAD_MISSING",
+            "message": f"canonical migration-head file missing: {config_rel}",
+            "configPath": str(config_path),
+        }
+    try:
+        data = json.loads(config_path.read_text(encoding="utf-8-sig"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return {
+            "ok": False,
+            "code": "MIGRATION_HEAD_UNREADABLE",
+            "message": str(exc),
+            "configPath": str(config_path),
+        }
+    if not isinstance(data, dict) or data.get("schemaVersion") != 1:
+        return {
+            "ok": False,
+            "code": "MIGRATION_HEAD_SCHEMA_INVALID",
+            "message": "migration-head.json must be schemaVersion 1 object",
+            "configPath": str(config_path),
+        }
+    head = str(data.get("head") or "").strip()
+    sources = data.get("sources")
+    if not head:
+        return {
+            "ok": False,
+            "code": "MIGRATION_HEAD_EMPTY",
+            "message": "head must be a non-empty string",
+            "configPath": str(config_path),
+        }
+    if not isinstance(sources, list) or not sources:
+        return {
+            "ok": False,
+            "code": "MIGRATION_HEAD_SOURCES_EMPTY",
+            "message": "sources must be a non-empty array",
+            "configPath": str(config_path),
+        }
+
+    observed: list[dict[str, Any]] = []
+    drifts: list[dict[str, Any]] = []
+    for index, source in enumerate(sources):
+        if not isinstance(source, dict):
+            return {
+                "ok": False,
+                "code": "MIGRATION_HEAD_SOURCE_INVALID",
+                "message": f"sources[{index}] must be an object",
+            }
+        try:
+            value = _extract_source(project, source)
+        except (OSError, ValueError, KeyError, json.JSONDecodeError) as exc:
+            return {
+                "ok": False,
+                "code": "MIGRATION_HEAD_SOURCE_UNREADABLE",
+                "message": str(exc),
+                "index": index,
+                "path": source.get("path"),
+            }
+        item = {"path": source.get("path"), "value": value}
+        observed.append(item)
+        if value != head:
+            drifts.append({**item, "expected": head})
+
+    if drifts:
+        return {
+            "ok": False,
+            "code": "MIGRATION_HEAD_DRIFT",
+            "message": "one or more sources disagree with canonical head",
+            "head": head,
+            "drifts": drifts,
+            "observed": observed,
+            "configPath": str(config_path),
+        }
+    return {
+        "ok": True,
+        "code": "MIGRATION_HEAD_OK",
+        "head": head,
+        "observed": observed,
+        "configPath": str(config_path),
+        "sourceCount": len(observed),
+    }
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="harness_migration_head.py")
+    sub = parser.add_subparsers(dest="command", required=True)
+    check = sub.add_parser("check", help="verify sources match canonical head")
+    check.add_argument("--project", required=True)
+    check.add_argument("--config", default=DEFAULT_REL)
+    check.add_argument("--json", action="store_true")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    as_json = bool(getattr(args, "json", False))
+    if args.command == "check":
+        result = check_migration_head(Path(args.project), config_rel=str(args.config))
+        if not result.get("ok"):
+            return emit_error(
+                str(result.get("code") or "MIGRATION_HEAD_FAIL"),
+                str(result.get("message") or "check failed"),
+                as_json=as_json,
+                extra={k: v for k, v in result.items() if k not in {"ok", "code", "message"}},
+            )
+        emit_json(result, as_json=as_json)
+        return 0
+    return emit_error("UNKNOWN_COMMAND", f"unknown command: {args.command}", as_json=as_json)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/harness/bundles/general/pi/scripts/harness_orchestration.py

@@ -0,0 +1,344 @@
+#!/usr/bin/env python3
+"""Compose environment, identity, verification, and progress decisions.
+
+The planner is deliberately side-effect free. It consumes already-produced
+receipts and declarations; provider operations and managed test execution stay
+in their existing lifecycle modules.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import fnmatch
+import json
+import sys
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+try:
+    import harness_efficiency
+    import harness_verification
+except ImportError:  # pragma: no cover - supports direct source loading
+    SCRIPTS_DIR = Path(__file__).resolve().parent
+    if str(SCRIPTS_DIR) not in sys.path:
+        sys.path.insert(0, str(SCRIPTS_DIR))
+    import harness_efficiency
+    import harness_verification
+
+
+SCHEMA_VERSION = 1
+VALID_ENVIRONMENT_MODES = {"change-session", "ephemeral"}
+
+
+def _timestamp(value: Any) -> dt.datetime | None:
+    if isinstance(value, dt.datetime):
+        parsed = value
+    elif value:
+        try:
+            parsed = dt.datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+        except (TypeError, ValueError):
+            return None
+    else:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=dt.timezone.utc)
+    return parsed.astimezone(dt.timezone.utc)
+
+
+def _targets(raw: Any) -> list[dict[str, Any]]:
+    if isinstance(raw, dict):
+        return [
+            {**dict(value), "id": str(value.get("id") or key)}
+            for key, value in sorted(raw.items())
+            if isinstance(value, dict)
+        ]
+    if isinstance(raw, list):
+        return [
+            dict(value)
+            for value in raw
+            if isinstance(value, dict) and str(value.get("id") or "").strip()
+        ]
+    return []
+
+
+def _record(reason_code: str, explanation: str, *, target_id: str = "", path: str = "") -> dict[str, Any]:
+    result = {
+        "reasonCode": reason_code,
+        "explanation": explanation,
+    }
+    if target_id:
+        result["targetId"] = target_id
+    if path:
+        result["path"] = path
+    return result
+
+
+def build_invalidation_records(payload: dict[str, Any]) -> list[dict[str, Any]]:
+    changed = sorted(
+        {str(path).replace("\\", "/") for path in payload.get("changedFiles", []) if str(path).strip()}
+    )
+    records: list[dict[str, Any]] = []
+    targets = _targets(payload.get("targets", []))
+    for target in sorted(targets, key=lambda item: str(item.get("id") or "")):
+        target_id = str(target.get("id") or "")
+        patterns = [str(pattern) for pattern in target.get("inputs", [])]
+        for path in changed:
+            if any(fnmatch.fnmatch(path, pattern) for pattern in patterns):
+                records.append(
+                    _record(
+                        "PRODUCT_INPUT_CHANGED",
+                        f"Changed path {path} matches verification input for {target_id}.",
+                        target_id=target_id,
+                        path=path,
+                    )
+                )
+
+    product_identity = str(payload.get("productIdentity") or "").strip()
+    frozen_identity = str(payload.get("frozenIdentity") or "").strip()
+    for target in sorted(targets, key=lambda item: str(item.get("id") or "")):
+        if target.get("requiresFrozenIdentity") is True and product_identity and frozen_identity and product_identity != frozen_identity:
+            records.append(
+                _record(
+                    "FROZEN_IDENTITY_DRIFT",
+                    "Current product identity differs from the frozen identity required by the target.",
+                    target_id=str(target.get("id") or ""),
+                )
+            )
+    graph_identity = str(payload.get("verificationGraphIdentity") or "").strip()
+    previous_graph = str(payload.get("previousVerificationGraphIdentity") or "").strip()
+    if graph_identity and previous_graph and graph_identity != previous_graph:
+        records.append(
+            _record(
+                "VERIFICATION_GRAPH_CHANGED",
+                "The declared verification graph identity changed since the previous plan.",
+            )
+        )
+    environment = payload.get("environment")
+    environment_hash = str(environment.get("environmentHash") or "").strip() if isinstance(environment, dict) else ""
+    previous_environment = str(payload.get("previousEnvironmentIdentity") or "").strip()
+    if environment_hash and previous_environment and environment_hash != previous_environment:
+        records.append(
+            _record(
+                "ENVIRONMENT_IDENTITY_CHANGED",
+                "The current environment identity differs from the previous environment session.",
+            )
+        )
+    return sorted(
+        records,
+        key=lambda item: (
+            str(item.get("reasonCode") or ""),
+            str(item.get("targetId") or ""),
+            str(item.get("path") or ""),
+        ),
+    )
+
+
+def validate_environment_contract(payload: dict[str, Any]) -> dict[str, Any]:
+    environment = payload.get("environment")
+    if not isinstance(environment, dict) or environment.get("required") is False:
+        return {
+            "ok": True,
+            "decision": "NOT_REQUIRED",
+            "reasonCode": "ENVIRONMENT_NOT_REQUIRED",
+            "explanation": "This orchestration payload does not require a managed environment session.",
+        }
+    mode = str(environment.get("mode") or "").strip()
+    if mode not in VALID_ENVIRONMENT_MODES:
+        return {
+            "ok": False,
+            "decision": "BLOCKED",
+            "reasonCode": "ENVIRONMENT_SESSION_MODE_INVALID",
+            "explanation": "Environment mode must be change-session or ephemeral.",
+        }
+    lease = environment.get("lease")
+    if not isinstance(lease, dict):
+        return {
+            "ok": False,
+            "decision": "BLOCKED",
+            "reasonCode": "ENVIRONMENT_LEASE_REQUIRED",
+            "explanation": "A typed active environment lease is required before verification.",
+            "mode": mode,
+        }
+    change_id = str(payload.get("changeId") or "").strip()
+    expected_hash = str(environment.get("environmentHash") or "").strip()
+    expected_content = str(environment.get("contentFingerprint") or "").strip()
+    if lease.get("status") != "ACTIVE":
+        return {
+            "ok": False,
+            "decision": "BLOCKED",
+            "reasonCode": "ENVIRONMENT_LEASE_INACTIVE",
+            "explanation": "The environment lease is not active.",
+            "mode": mode,
+        }
+    if str(lease.get("changeId") or "") != change_id:
+        return {
+            "ok": False,
+            "decision": "BLOCKED",
+            "reasonCode": "ENVIRONMENT_LEASE_CROSS_CHANGE",
+            "explanation": "The environment lease is owned by a different change.",
+            "mode": mode,
+        }
+    if str(lease.get("mode") or mode) != mode:
+        return {
+            "ok": False,
+            "decision": "BLOCKED",
+            "reasonCode": "ENVIRONMENT_SESSION_MODE_MISMATCH",
+            "explanation": "The lease mode does not match the requested session mode.",
+            "mode": mode,
+        }
+    if expected_hash and str(lease.get("environmentHash") or "") != expected_hash:
+        return {
+            "ok": False,
+            "decision": "BLOCKED",
+            "reasonCode": "ENVIRONMENT_IDENTITY_MISMATCH",
+            "explanation": "The active lease environment identity does not match the requested identity.",
+            "mode": mode,
+        }
+    if expected_content and str(lease.get("contentFingerprint") or "") != expected_content:
+        return {
+            "ok": False,
+            "decision": "BLOCKED",
+            "reasonCode": "ENVIRONMENT_CONTENT_IDENTITY_MISMATCH",
+            "explanation": "The active lease content fingerprint does not match the typed receipt.",
+            "mode": mode,
+        }
+    expires_at = _timestamp(lease.get("expiresAt"))
+    if expires_at is None or expires_at <= dt.datetime.now(dt.timezone.utc):
+        return {
+            "ok": False,
+            "decision": "RESET_REQUIRED",
+            "reasonCode": "ENVIRONMENT_LEASE_EXPIRED",
+            "explanation": "The environment lease has expired and must be reacquired before verification.",
+            "mode": mode,
+        }
+    if lease.get("ownerVerified") is not True:
+        return {
+            "ok": False,
+            "decision": "BLOCKED",
+            "reasonCode": "ENVIRONMENT_OWNER_UNVERIFIED",
+            "explanation": "The recorded lease owner cannot be verified for this execution.",
+            "mode": mode,
+        }
+    required = {
+        str(item).strip()
+        for item in environment.get("requiredFields", [])
+        if str(item).strip()
+    }
+    resolved = environment.get("resolvedFields")
+    resolved = resolved if isinstance(resolved, dict) else {}
+    missing = sorted(field for field in required if not str(resolved.get(field) or "").strip())
+    if missing:
+        return {
+            "ok": False,
+            "decision": "BLOCKED",
+            "reasonCode": "VERIFICATION_ENVIRONMENT_INCOMPLETE",
+            "explanation": "Required dynamic environment identities are missing from the receipt.",
+            "missing": missing,
+            "mode": mode,
+        }
+    decision = "REUSE_ELIGIBLE" if environment.get("reuseEligible") is True else "READY"
+    reason = "ENVIRONMENT_REUSE_ELIGIBLE" if decision == "REUSE_ELIGIBLE" else "ENVIRONMENT_READY"
+    return {
+        "ok": True,
+        "decision": decision,
+        "reasonCode": reason,
+        "explanation": (
+            "The active environment lease and typed content identity are valid for reuse."
+            if decision == "REUSE_ELIGIBLE"
+            else "The active environment lease, owner, TTL, content identity, and required fields are valid."
+        ),
+        "mode": mode,
+        "environmentHash": expected_hash,
+        "contentFingerprint": expected_content,
+    }
+
+
+def _budget_state(payload: dict[str, Any]) -> dict[str, Any]:
+    budget = payload.get("budget")
+    if not isinstance(budget, dict):
+        return {"state": "NO_BUDGET", "maxDurationSeconds": None}
+    raw = budget.get("maxDurationSeconds") or budget.get("budgetSeconds")
+    try:
+        seconds = float(raw)
+    except (TypeError, ValueError):
+        seconds = 0
+    if seconds <= 0:
+        return {"state": "NO_BUDGET", "maxDurationSeconds": None}
+    return {
+        "state": str(budget.get("state") or "WITHIN_BUDGET").upper(),
+        "maxDurationSeconds": int(seconds),
+    }
+
+
+def build_orchestration_plan(payload: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(payload, dict):
+        return {"ok": False, "code": "ORCHESTRATION_PAYLOAD_INVALID"}
+    targets = _targets(payload.get("targets", []))
+    if not targets:
+        return {"ok": False, "code": "VERIFICATION_TARGETS_REQUIRED"}
+    selection = harness_verification.select_verifications(payload)
+    selected = selection.get("selected") if isinstance(selection, dict) else []
+    schedule_payload = dict(payload)
+    schedule_payload["targets"] = selected if selected else targets
+    verification = harness_verification.schedule_verifications(schedule_payload)
+    environment = validate_environment_contract(payload)
+    invalidations = build_invalidation_records(payload)
+    progress_sessions = payload.get("progressSessions")
+    progress = []
+    if isinstance(progress_sessions, list):
+        progress = [
+            harness_efficiency.classify_progress(item)
+            for item in progress_sessions
+            if isinstance(item, dict)
+        ]
+    decision_counts = dict(
+        sorted(Counter(item.get("decision") for item in verification.get("plan", [])).items())
+    )
+    ok = bool(verification.get("ok")) and bool(environment.get("ok"))
+    return {
+        "schemaVersion": SCHEMA_VERSION,
+        "ok": ok,
+        "code": "ORCHESTRATION_PLAN_READY" if ok else "ORCHESTRATION_PLAN_BLOCKED",
+        "changeId": str(payload.get("changeId") or ""),
+        "productIdentity": str(payload.get("productIdentity") or ""),
+        "frozenIdentity": str(payload.get("frozenIdentity") or ""),
+        "selection": selection,
+        "invalidations": invalidations,
+        "environment": environment,
+        "verification": verification,
+        "decisionCounts": decision_counts,
+        "budget": _budget_state(payload),
+        "progress": progress,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="harness_orchestration.py")
+    sub = parser.add_subparsers(dest="command", required=True)
+    plan = sub.add_parser("plan")
+    plan.add_argument("--input", required=True)
+    plan.add_argument("--out")
+    plan.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+    if args.command != "plan":
+        return 2
+    try:
+        payload = json.loads(Path(args.input).read_text(encoding="utf-8-sig"))
+    except (OSError, json.JSONDecodeError) as exc:
+        result = {"ok": False, "code": "ORCHESTRATION_INPUT_INVALID", "error": str(exc)}
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 1
+    result = build_orchestration_plan(payload)
+    text = json.dumps(result, ensure_ascii=False, indent=2, sort_keys=True) + "\n"
+    if args.out:
+        output = Path(args.out)
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(text, encoding="utf-8", newline="\n")
+    print(text, end="")
+    return 0 if result.get("ok") else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())