phase-loop-runtime 0.4.0__tar.gz → 0.5.0__tar.gz

{phase_loop_runtime-0.4.0 → phase_loop_runtime-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phase-loop-runtime
-Version: 0.4.0
+Version: 0.5.0
 Summary: Harness-neutral phase-loop orchestration runtime and CLI
 Author: ViperJuice
 License-Expression: Apache-2.0

{phase_loop_runtime-0.4.0 → phase_loop_runtime-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "phase-loop-runtime"  # PyPI dist name; NOT "agent-harness" (an unrelated third-party PyPI project)
-version = "0.4.0"
+version = "0.5.0"
 description = "Harness-neutral phase-loop orchestration runtime and CLI"
 readme = "README.md"
 requires-python = ">=3.10"

{phase_loop_runtime-0.4.0 → phase_loop_runtime-0.5.0}/src/phase_loop_runtime/__init__.py

@@ -18,4 +18,4 @@ __all__ = [
     "state_ops",
 ]
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"

{phase_loop_runtime-0.4.0 → phase_loop_runtime-0.5.0}/src/phase_loop_runtime/cli.py

@@ -670,6 +670,28 @@ def build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Emit the ledger state as JSON.",
     )
+    outside_agent_sub = subparsers.add_parser(
+        "outside-agent-preflight",
+        help="Emit advisory metadata-only outside-agent preflight evidence.",
+    )
+    outside_agent_sub.add_argument("submission_file", metavar="submission-file")
+    outside_agent_sub.add_argument("--output", help="Path to write advisory evidence JSON.")
+    outside_agent_validate_sub = subparsers.add_parser(
+        "outside-agent-validate",
+        help="Emit governed-pipeline outside-agent validation verdict JSON.",
+    )
+    outside_agent_validate_sub.add_argument("submission_file", metavar="submission-file")
+    outside_agent_validate_sub.add_argument(
+        "--output",
+        required=True,
+        help="Path to write governed-pipeline validation verdict JSON.",
+    )
+    outside_agent_validate_sub.add_argument(
+        "--submitted-ref",
+        action="append",
+        default=[],
+        help="Repo-relative ref submitted to governed-pipeline; may be repeated.",
+    )
     # DECOUPLE SL-1: dotfiles-domain commands are added here, only when a profile
     # plugin is installed/opted-in. A clean wheel registers none.
     _register_profile_commands(subparsers)
@@ -751,6 +773,10 @@ def _main(parser: argparse.ArgumentParser, args: argparse.Namespace, command: st
         return _run_train_command(parser=parser, args=args)
     if command == "train-status":
         return _run_train_status_command(parser=parser, args=args)
+    if command == "outside-agent-preflight":
+        return _outside_agent_preflight_command(args=args)
+    if command == "outside-agent-validate":
+        return _outside_agent_validate_command(args=args)
     if command == "docs-audit":
         from . import docs_audit
 
@@ -1128,6 +1154,78 @@ def _main(parser: argparse.ArgumentParser, args: argparse.Namespace, command: st
     return _run_returncode(snapshot, results)
 
 
+def _outside_agent_preflight_command(args: argparse.Namespace) -> int:
+    from .conformance.outside_agent_advisory import (
+        build_malformed_outside_agent_advisory_evidence,
+        build_outside_agent_advisory_evidence,
+        digest_outside_agent_submission_bytes,
+        serialize_outside_agent_advisory_evidence,
+    )
+
+    submission_path = Path(args.submission_file)
+    try:
+        raw = submission_path.read_bytes()
+    except OSError as exc:
+        evidence = build_malformed_outside_agent_advisory_evidence(
+            input_digest=digest_outside_agent_submission_bytes(str(submission_path).encode("utf-8")),
+            message=f"outside-agent submission JSON could not be read: {exc.__class__.__name__}",
+        )
+    else:
+        try:
+            submission = json.loads(raw.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            evidence = build_malformed_outside_agent_advisory_evidence(
+                input_digest=digest_outside_agent_submission_bytes(raw),
+            )
+        else:
+            evidence = build_outside_agent_advisory_evidence(submission)
+
+    payload = serialize_outside_agent_advisory_evidence(evidence)
+    text = json.dumps(payload, indent=2, sort_keys=True) + "\n"
+    if args.output:
+        Path(args.output).write_text(text, encoding="utf-8")
+    print(text, end="")
+    return int(evidence.exit_code)
+
+
+def _outside_agent_validate_command(args: argparse.Namespace) -> int:
+    from .conformance.outside_agent_real import (
+        build_malformed_outside_agent_validation_verdict,
+        build_outside_agent_validation_verdict,
+    )
+    from .conformance.outside_agent_real_output import (
+        digest_outside_agent_validation_bytes,
+        serialize_outside_agent_validation_verdict,
+    )
+
+    submission_path = Path(args.submission_file)
+    try:
+        raw = submission_path.read_bytes()
+    except OSError as exc:
+        validation = build_malformed_outside_agent_validation_verdict(
+            input_digest=digest_outside_agent_validation_bytes(str(submission_path).encode("utf-8")),
+            message=f"outside-agent submission JSON could not be read: {exc.__class__.__name__}",
+        )
+    else:
+        try:
+            submission = json.loads(raw.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            validation = build_malformed_outside_agent_validation_verdict(
+                input_digest=digest_outside_agent_validation_bytes(raw),
+            )
+        else:
+            validation = build_outside_agent_validation_verdict(
+                submission,
+                submitted_refs=tuple(args.submitted_ref or ()),
+            )
+
+    payload = serialize_outside_agent_validation_verdict(validation)
+    text = json.dumps(payload, indent=2, sort_keys=True) + "\n"
+    Path(args.output).write_text(text, encoding="utf-8")
+    print(text, end="")
+    return int(validation.exit_code)
+
+
 def _parse_lane_ir_override(parser: argparse.ArgumentParser, args: argparse.Namespace, command: str) -> tuple[str, ...]:
     raw = getattr(args, "allow_lane_ir_override", None)
     if raw is None:

phase_loop_runtime-0.5.0/src/phase_loop_runtime/conformance/__init__.py

@@ -0,0 +1,79 @@
+"""``phase_loop_runtime.conformance`` -- the named conformance surface.
+
+This package preserves the existing public ``.consiliency/`` conformance
+imports while providing a namespace for outside-agent contract pin helpers.
+"""
+from __future__ import annotations
+
+from ..consiliency_gates import (
+    CONSILIENCY_GATES_ENV,
+    CONSILIENCY_GATES_MODES,
+    DEFAULT_CONSILIENCY_GATES_MODE,
+    resolve_consiliency_gates_mode,
+    scan_consiliency_gates,
+)
+from ..consiliency_ingest import evaluate_governance_scope
+from ..git_discipline import evaluate_git_discipline, self_heal_partition
+from .outside_agent_core import (
+    OutsideAgentBlocker,
+    OutsideAgentConformanceVerdict,
+    OutsideAgentEvidenceRef,
+    OutsideAgentSubmissionKind,
+    OutsideAgentVerdictStatus,
+    validate_outside_agent_submission,
+)
+from .outside_agent_advisory import (
+    OutsideAgentAdvisoryEvidence,
+    OutsideAgentAdvisoryExitCode,
+    build_outside_agent_advisory_evidence,
+    serialize_outside_agent_advisory_evidence,
+)
+from .outside_agent_imports import (
+    OutsideAgentContractError,
+    load_outside_agent_contract_pin,
+)
+from .outside_agent_pin import (
+    EXPECTED_OUTSIDE_AGENT_CONTRACT_PIN,
+    OutsideAgentContractPin,
+)
+from .outside_agent_real import (
+    OutsideAgentSubmittedRef,
+    OutsideAgentValidationExitCode,
+    OutsideAgentValidationVerdict,
+    build_outside_agent_validation_verdict,
+)
+from .outside_agent_real_output import (
+    digest_outside_agent_validation_bytes,
+    serialize_outside_agent_validation_verdict,
+)
+
+__all__ = [
+    "scan_consiliency_gates",
+    "resolve_consiliency_gates_mode",
+    "CONSILIENCY_GATES_ENV",
+    "CONSILIENCY_GATES_MODES",
+    "DEFAULT_CONSILIENCY_GATES_MODE",
+    "evaluate_git_discipline",
+    "self_heal_partition",
+    "evaluate_governance_scope",
+    "OutsideAgentBlocker",
+    "OutsideAgentConformanceVerdict",
+    "OutsideAgentEvidenceRef",
+    "OutsideAgentSubmissionKind",
+    "OutsideAgentVerdictStatus",
+    "validate_outside_agent_submission",
+    "OutsideAgentAdvisoryEvidence",
+    "OutsideAgentAdvisoryExitCode",
+    "build_outside_agent_advisory_evidence",
+    "serialize_outside_agent_advisory_evidence",
+    "OutsideAgentContractError",
+    "load_outside_agent_contract_pin",
+    "EXPECTED_OUTSIDE_AGENT_CONTRACT_PIN",
+    "OutsideAgentContractPin",
+    "OutsideAgentSubmittedRef",
+    "OutsideAgentValidationExitCode",
+    "OutsideAgentValidationVerdict",
+    "build_outside_agent_validation_verdict",
+    "digest_outside_agent_validation_bytes",
+    "serialize_outside_agent_validation_verdict",
+]

phase_loop_runtime-0.5.0/src/phase_loop_runtime/conformance/outside_agent_advisory.py

@@ -0,0 +1,208 @@
+"""Advisory outside-agent preflight evidence."""
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from enum import IntEnum
+from typing import Any, Mapping
+
+from .outside_agent_core import (
+    OutsideAgentBlocker,
+    OutsideAgentConformanceVerdict,
+    OutsideAgentVerdictStatus,
+    validate_outside_agent_submission,
+)
+from .outside_agent_pin import (
+    EXPECTED_OUTSIDE_AGENT_CONTRACT_PIN,
+    OutsideAgentContractPin,
+)
+
+
+_REDACTION_BLOCKER_CODES = frozenset(
+    {
+        "local_env_value_present",
+        "raw_log_present",
+        "raw_payload_present",
+        "secret_like_value_present",
+    }
+)
+_PROVENANCE_BLOCKER_CODES = frozenset(
+    {
+        "absolute_path_ref",
+        "digest_mismatch",
+        "missing_digest",
+        "path_traversal_ref",
+        "unsafe_source_ref",
+    }
+)
+
+
+class OutsideAgentAdvisoryExitCode(IntEnum):
+    PASS = 0
+    INTERNAL_ERROR = 1
+    MALFORMED_INPUT = 2
+    REDACTION_VIOLATION = 3
+    PROVENANCE_FAILURE = 4
+
+
+@dataclass(frozen=True)
+class OutsideAgentAdvisoryEvidence:
+    authority: str
+    classification: str
+    exit_code: OutsideAgentAdvisoryExitCode
+    verdict: OutsideAgentConformanceVerdict
+    metadata: Mapping[str, str] = field(default_factory=dict)
+
+
+def build_outside_agent_advisory_evidence(
+    submission: Any,
+    *,
+    contract_pin: OutsideAgentContractPin = EXPECTED_OUTSIDE_AGENT_CONTRACT_PIN,
+) -> OutsideAgentAdvisoryEvidence:
+    """Build deterministic advisory evidence without external I/O."""
+    if not isinstance(submission, Mapping):
+        verdict = _malformed_verdict(
+            input_digest=_digest_value(submission),
+            contract_pin=contract_pin,
+            blocker=OutsideAgentBlocker(
+                "malformed_input",
+                "outside-agent submission JSON must be an object",
+                ref="$",
+            ),
+        )
+        return _evidence_for_verdict(verdict)
+
+    verdict = validate_outside_agent_submission(submission, contract_pin=contract_pin)
+    return _evidence_for_verdict(verdict)
+
+
+def build_malformed_outside_agent_advisory_evidence(
+    *,
+    input_digest: str,
+    message: str = "outside-agent submission JSON could not be parsed",
+    contract_pin: OutsideAgentContractPin = EXPECTED_OUTSIDE_AGENT_CONTRACT_PIN,
+) -> OutsideAgentAdvisoryEvidence:
+    verdict = _malformed_verdict(
+        input_digest=input_digest,
+        contract_pin=contract_pin,
+        blocker=OutsideAgentBlocker("malformed_input", message, ref="$"),
+    )
+    return _evidence_for_verdict(verdict)
+
+
+def serialize_outside_agent_advisory_evidence(
+    evidence: OutsideAgentAdvisoryEvidence,
+) -> dict[str, Any]:
+    verdict = evidence.verdict
+    return {
+        "authority": evidence.authority,
+        "classification": evidence.classification,
+        "exit_code": int(evidence.exit_code),
+        "verdict_schema_version": verdict.verdict_schema_version,
+        "submission_kind": verdict.submission_kind.value if verdict.submission_kind else None,
+        "status": verdict.status.value,
+        "blockers": [
+            {"code": blocker.code, "message": blocker.message, "ref": blocker.ref}
+            for blocker in verdict.blockers
+        ],
+        "contract_pin": {
+            "schema_version": verdict.contract_pin.schema_version,
+            "verdict_schema_version": verdict.contract_pin.verdict_schema_version,
+            "contract_package": verdict.contract_pin.contract_package,
+            "contract_version": verdict.contract_pin.contract_version,
+            "contract_git_sha": verdict.contract_pin.contract_git_sha,
+            "vector_manifest_name": verdict.contract_pin.vector_manifest_name,
+            "vector_manifest_hash": verdict.contract_pin.vector_manifest_hash,
+            "source_owner": verdict.contract_pin.source_owner,
+            "redaction_posture": verdict.contract_pin.redaction_posture,
+        },
+        "input_digest": verdict.input_digest,
+        "provenance_refs": list(verdict.provenance_refs),
+        "evidence_refs": [
+            {"ref": ref.ref, "digest": ref.digest, "kind": ref.kind}
+            for ref in verdict.evidence_refs
+        ],
+        "redaction_posture": verdict.redaction_posture,
+        "metadata": dict(evidence.metadata),
+    }
+
+
+def digest_outside_agent_submission_bytes(value: bytes) -> str:
+    return hashlib.sha256(value).hexdigest()
+
+
+def _evidence_for_verdict(
+    verdict: OutsideAgentConformanceVerdict,
+) -> OutsideAgentAdvisoryEvidence:
+    exit_code = _exit_code_for_blockers(verdict.blockers)
+    return OutsideAgentAdvisoryEvidence(
+        authority="advisory",
+        classification=_classification_for_exit_code(exit_code),
+        exit_code=exit_code,
+        verdict=verdict,
+        metadata={"source": "outside_agent_advisory_preflight"},
+    )
+
+
+def _exit_code_for_blockers(
+    blockers: tuple[OutsideAgentBlocker, ...],
+) -> OutsideAgentAdvisoryExitCode:
+    if not blockers:
+        return OutsideAgentAdvisoryExitCode.PASS
+    codes = {blocker.code for blocker in blockers}
+    if codes & _REDACTION_BLOCKER_CODES:
+        return OutsideAgentAdvisoryExitCode.REDACTION_VIOLATION
+    if codes & _PROVENANCE_BLOCKER_CODES:
+        return OutsideAgentAdvisoryExitCode.PROVENANCE_FAILURE
+    return OutsideAgentAdvisoryExitCode.MALFORMED_INPUT
+
+
+def _classification_for_exit_code(exit_code: OutsideAgentAdvisoryExitCode) -> str:
+    return {
+        OutsideAgentAdvisoryExitCode.PASS: "clean_advisory_pass",
+        OutsideAgentAdvisoryExitCode.INTERNAL_ERROR: "internal_error",
+        OutsideAgentAdvisoryExitCode.MALFORMED_INPUT: "malformed_input",
+        OutsideAgentAdvisoryExitCode.REDACTION_VIOLATION: "redaction_violation",
+        OutsideAgentAdvisoryExitCode.PROVENANCE_FAILURE: "provenance_failure",
+    }[exit_code]
+
+
+def _malformed_verdict(
+    *,
+    input_digest: str,
+    contract_pin: OutsideAgentContractPin,
+    blocker: OutsideAgentBlocker,
+) -> OutsideAgentConformanceVerdict:
+    return OutsideAgentConformanceVerdict(
+        verdict_schema_version=contract_pin.verdict_schema_version,
+        submission_kind=None,
+        status=OutsideAgentVerdictStatus.BLOCKED,
+        blockers=(blocker,),
+        contract_pin=contract_pin,
+        input_digest=input_digest,
+        provenance_refs=(),
+        evidence_refs=(),
+        redaction_posture=contract_pin.redaction_posture,
+        metadata={"source_owner": contract_pin.source_owner},
+    )
+
+
+def _digest_value(value: Any) -> str:
+    encoded = json.dumps(
+        value,
+        sort_keys=True,
+        separators=(",", ":"),
+        default=str,
+    ).encode("utf-8")
+    return hashlib.sha256(encoded).hexdigest()
+
+
+__all__ = [
+    "OutsideAgentAdvisoryEvidence",
+    "OutsideAgentAdvisoryExitCode",
+    "build_malformed_outside_agent_advisory_evidence",
+    "build_outside_agent_advisory_evidence",
+    "digest_outside_agent_submission_bytes",
+    "serialize_outside_agent_advisory_evidence",
+]

phase_loop_runtime-0.5.0/src/phase_loop_runtime/conformance/outside_agent_core.py

@@ -0,0 +1,118 @@
+"""Deterministic outside-agent conformance verdict core."""
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Mapping
+
+from .outside_agent_pin import (
+    EXPECTED_OUTSIDE_AGENT_CONTRACT_PIN,
+    OutsideAgentContractPin,
+)
+
+
+class OutsideAgentSubmissionKind(str, Enum):
+    WORK_REQUEST = "work_request"
+    IMPLEMENTATION_SUBMISSION = "implementation_submission"
+    AMBIGUITY_REPORT = "ambiguity_report"
+
+
+class OutsideAgentVerdictStatus(str, Enum):
+    PASS = "pass"
+    BLOCKED = "blocked"
+
+
+@dataclass(frozen=True)
+class OutsideAgentBlocker:
+    code: str
+    message: str
+    ref: str | None = None
+
+
+@dataclass(frozen=True)
+class OutsideAgentEvidenceRef:
+    ref: str
+    digest: str
+    kind: str = "metadata"
+
+
+@dataclass(frozen=True)
+class OutsideAgentConformanceVerdict:
+    verdict_schema_version: str
+    submission_kind: OutsideAgentSubmissionKind | None
+    status: OutsideAgentVerdictStatus
+    blockers: tuple[OutsideAgentBlocker, ...]
+    contract_pin: OutsideAgentContractPin
+    input_digest: str
+    provenance_refs: tuple[str, ...]
+    evidence_refs: tuple[OutsideAgentEvidenceRef, ...]
+    redaction_posture: str = "metadata_only"
+    metadata: Mapping[str, str] = field(default_factory=dict)
+
+
+def validate_outside_agent_submission(
+    submission: Mapping[str, Any],
+    *,
+    contract_pin: OutsideAgentContractPin = EXPECTED_OUTSIDE_AGENT_CONTRACT_PIN,
+) -> OutsideAgentConformanceVerdict:
+    """Validate a metadata-only outside-agent submission without external I/O."""
+    from .outside_agent_provenance import validate_outside_agent_provenance
+    from .outside_agent_redaction import assert_outside_agent_metadata_only
+    from .outside_agent_schema import validate_outside_agent_submission_schema
+
+    input_digest = _digest_mapping(submission)
+    schema_result = validate_outside_agent_submission_schema(
+        submission, contract_pin=contract_pin
+    )
+    provenance_result = validate_outside_agent_provenance(submission)
+    redaction_blockers = assert_outside_agent_metadata_only(submission)
+
+    blockers = (
+        schema_result.blockers
+        + provenance_result.blockers
+        + tuple(redaction_blockers)
+    )
+    status = (
+        OutsideAgentVerdictStatus.BLOCKED
+        if blockers
+        else OutsideAgentVerdictStatus.PASS
+    )
+
+    evidence_refs = tuple(
+        OutsideAgentEvidenceRef(ref=ref.ref, digest=ref.digest, kind=ref.kind)
+        for ref in provenance_result.evidence_refs
+    )
+    return OutsideAgentConformanceVerdict(
+        verdict_schema_version=contract_pin.verdict_schema_version,
+        submission_kind=schema_result.submission_kind,
+        status=status,
+        blockers=blockers,
+        contract_pin=contract_pin,
+        input_digest=input_digest,
+        provenance_refs=provenance_result.provenance_refs,
+        evidence_refs=evidence_refs,
+        redaction_posture=contract_pin.redaction_posture,
+        metadata={"source_owner": contract_pin.source_owner},
+    )
+
+
+def _digest_mapping(value: Mapping[str, Any]) -> str:
+    encoded = json.dumps(
+        value,
+        sort_keys=True,
+        separators=(",", ":"),
+        default=str,
+    ).encode("utf-8")
+    return hashlib.sha256(encoded).hexdigest()
+
+
+__all__ = [
+    "OutsideAgentBlocker",
+    "OutsideAgentConformanceVerdict",
+    "OutsideAgentEvidenceRef",
+    "OutsideAgentSubmissionKind",
+    "OutsideAgentVerdictStatus",
+    "validate_outside_agent_submission",
+]