agent-lifecycle-kit 1.50.1__py3-none-any.whl

agent_lifecycle/neutrality/receipt.py

@@ -0,0 +1,135 @@
+"""Detached neutrality receipt generation and verification."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .authority import RECEIPT_DOMAIN
+from .canonical import canonical_bytes, load_json, sha256_hex
+from .ed25519 import fingerprint, verify
+from .errors import NeutralityError
+from .paths import stable_read_bytes
+
+
+def build_claims(
+    *,
+    operation: dict[str, Any],
+    report: dict[str, Any],
+    authority_digest: str,
+    primary_path: str,
+    receipt_path: str,
+    policy: dict[str, Any],
+    profile: dict[str, Any],
+) -> dict[str, Any]:
+    zero_counters = {
+        key: int(report["counters"].get(key, 0))
+        for key in [
+            "findings",
+            "skippedInputs",
+            "opaqueInputs",
+            "readRaces",
+            "incompleteScans",
+            "unsupportedArchives",
+            "archiveLimitBreaches",
+            "occupiedOutputConflicts",
+            "pathAliasConflicts",
+        ]
+    }
+    output_manifest = [
+        {
+            "publicationOrder": 1,
+            "role": "primary-artifact",
+            "path": primary_path,
+            "required": True,
+            "mustBeUnique": True,
+            "contentIdentityRule": "sha256",
+        },
+        {
+            "publicationOrder": 2,
+            "role": "detached-commit-receipt",
+            "path": receipt_path,
+            "required": True,
+            "mustBeUnique": True,
+            "contentIdentityRule": "canonical-signed-envelope",
+        },
+    ]
+    return {
+        "schemaVersion": "agent-neutrality-claims.v3",
+        "operation": operation,
+        "projectionSchemaVersion": "agent-neutrality-subject-projection.v2",
+        "profileDigest": sha256_hex(canonical_bytes(profile)),
+        "scopeProfileDigest": sha256_hex(canonical_bytes({"scope": report["scope"]})),
+        "archivePolicyDigest": sha256_hex(canonical_bytes(policy.get("archives", {}))),
+        "externalAuthorityContractDigest": sha256_hex(canonical_bytes({"contract": "AGENT_LIFECYCLE_NEUTRALITY_*"})),
+        "operationOutputManifestDigest": sha256_hex(canonical_bytes(output_manifest)),
+        "primaryArtifactManifestDigest": sha256_hex(canonical_bytes({"primary": primary_path})),
+        "workingTreeDigest": report["digests"]["workingTreeDigest"],
+        "gitObjectSetDigest": report["digests"]["gitObjectSetDigest"],
+        "subjectDigest": report["digests"]["subjectDigest"],
+        "authorityDigest": authority_digest,
+        "zeroCounters": zero_counters,
+    }
+
+
+def build_receipt(
+    *,
+    operation: dict[str, Any],
+    claims: dict[str, Any],
+    primary_sha256: str,
+    primary_bytes: int,
+    signer_fingerprint: str,
+    signature: str,
+) -> dict[str, Any]:
+    claims_digest = sha256_hex(canonical_bytes(claims))
+    return {
+        "schemaVersion": "agent-neutrality-detached-receipt.v3",
+        "operation": operation,
+        "claimsDigest": claims_digest,
+        "primaryArtifact": {"sha256": primary_sha256, "bytes": primary_bytes},
+        "signer": {"algorithm": "Ed25519", "fingerprint": signer_fingerprint},
+        "signature": signature,
+    }
+
+
+def verify_existing_receipt(
+    *,
+    receipt_path: Path,
+    primary_path: Path,
+    expected_operation: dict[str, Any] | None,
+    trust_root_path: Path,
+    expected_signer_fingerprint: str,
+) -> bool:
+    receipt = load_json(stable_read_bytes(receipt_path))
+    primary = stable_read_bytes(primary_path)
+    if receipt.get("schemaVersion") != "agent-neutrality-detached-receipt.v3":
+        return False
+    if expected_operation is not None and receipt.get("operation") != expected_operation:
+        return False
+    primary_identity = receipt.get("primaryArtifact")
+    if not isinstance(primary_identity, dict):
+        return False
+    if primary_identity.get("sha256") != sha256_hex(primary):
+        return False
+    if primary_identity.get("bytes") != len(primary):
+        return False
+    trust_root = load_json(stable_read_bytes(trust_root_path))
+    public_key = _public_key_for_fingerprint(trust_root, expected_signer_fingerprint)
+    claims_digest = receipt.get("claimsDigest")
+    signature = receipt.get("signature")
+    if not isinstance(claims_digest, str) or not isinstance(signature, str):
+        return False
+    return verify(public_key, RECEIPT_DOMAIN + claims_digest.encode("ascii"), bytes.fromhex(signature))
+
+
+def _public_key_for_fingerprint(trust_root: dict[str, Any], expected_fingerprint: str) -> bytes:
+    if trust_root.get("schemaVersion") != "agent-neutrality-trust-root.v1":
+        raise NeutralityError("unsupported trust root schemaVersion")
+    for signer in trust_root.get("authorizedSigners", []):
+        if not isinstance(signer, dict) or signer.get("fingerprint") != expected_fingerprint:
+            continue
+        public_key = bytes.fromhex(str(signer.get("publicKeyHex")))
+        if fingerprint(public_key) != expected_fingerprint:
+            raise NeutralityError("trust root signer fingerprint mismatch")
+        return public_key
+    raise NeutralityError("expected signer is not authorized by trust root")

agent_lifecycle/neutrality/scanner.py

@@ -0,0 +1,310 @@
+"""Repository neutrality scanner."""
+
+from __future__ import annotations
+
+import os
+import re
+import stat
+import subprocess
+import zipfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Iterable, Pattern
+
+from .canonical import canonical_bytes, sha256_hex
+from .errors import NeutralityError
+from .paths import stable_read_bytes, validate_output_paths, validate_repository_relative_path
+from .policy import NeutralityPolicy
+
+
+@dataclass(frozen=True)
+class NeutralityFinding:
+    source: str
+    ruleId: str
+    category: str
+
+    def to_json(self) -> dict[str, str]:
+        return {"source": self.source, "ruleId": self.ruleId, "category": self.category}
+
+
+@dataclass
+class NeutralityReport:
+    scope: str
+    findings: list[NeutralityFinding] = field(default_factory=list)
+    skipped_inputs: int = 0
+    opaque_inputs: int = 0
+    read_races: int = 0
+    incomplete_scans: int = 0
+    unsupported_archives: int = 0
+    archive_limit_breaches: int = 0
+    occupied_output_conflicts: int = 0
+    path_alias_conflicts: int = 0
+    scanned_files: int = 0
+    scanned_git_objects: int = 0
+    working_tree_digest: str = "0" * 64
+    git_object_set_digest: str = "0" * 64
+
+    def to_json(self, operation: dict[str, Any]) -> dict[str, Any]:
+        counters = {
+            "findings": len(self.findings),
+            "skippedInputs": self.skipped_inputs,
+            "opaqueInputs": self.opaque_inputs,
+            "readRaces": self.read_races,
+            "incompleteScans": self.incomplete_scans,
+            "unsupportedArchives": self.unsupported_archives,
+            "archiveLimitBreaches": self.archive_limit_breaches,
+            "occupiedOutputConflicts": self.occupied_output_conflicts,
+            "pathAliasConflicts": self.path_alias_conflicts,
+        }
+        subject = {
+            "scope": self.scope,
+            "counters": counters,
+            "workingTreeDigest": self.working_tree_digest,
+            "gitObjectSetDigest": self.git_object_set_digest,
+            "findingIds": [finding.ruleId for finding in self.findings],
+        }
+        return {
+            "schemaVersion": "agent-neutrality-report.v1",
+            "operation": operation,
+            "scope": self.scope,
+            "counters": counters,
+            "scanned": {
+                "files": self.scanned_files,
+                "gitObjects": self.scanned_git_objects,
+            },
+            "digests": {
+                "workingTreeDigest": self.working_tree_digest,
+                "gitObjectSetDigest": self.git_object_set_digest,
+                "subjectDigest": sha256_hex(canonical_bytes(subject)),
+            },
+            "findings": [finding.to_json() for finding in self.findings],
+        }
+
+
+@dataclass
+class ArchiveScanBudget:
+    archives: int = 0
+    entries: int = 0
+    expanded_bytes: int = 0
+
+
+def scan_repository(
+    *,
+    workspace_root: Path,
+    policy: NeutralityPolicy,
+    deny_literals: Iterable[str],
+    deny_regexes: Iterable[str],
+    scope: str,
+    output_paths: list[Path],
+) -> NeutralityReport:
+    report = NeutralityReport(scope=scope)
+    try:
+        normalized_outputs = validate_output_paths(output_paths)
+    except NeutralityError:
+        report.path_alias_conflicts += 1
+        normalized_outputs = []
+    for output_path in output_paths:
+        if (workspace_root / output_path).exists():
+            report.occupied_output_conflicts += 1
+
+    literal_rules = tuple(deny_literals) + policy.deny_literals
+    regex_rules = tuple(re.compile(value) for value in deny_regexes) + policy.deny_regexes
+    archive_budget = ArchiveScanBudget()
+
+    worktree_entries: list[dict[str, Any]] = []
+    for rel_path in _walk_repository_files(workspace_root, policy):
+        path = workspace_root / rel_path
+        try:
+            validate_repository_relative_path(rel_path)
+            data = stable_read_bytes(path, max_bytes=policy.max_file_bytes)
+        except NeutralityError:
+            report.read_races += 1
+            continue
+        report.scanned_files += 1
+        report.findings.extend(_match_data(rel_path, data, literal_rules, regex_rules))
+        _scan_archive(rel_path, data, policy, report, literal_rules, regex_rules, archive_budget, depth=1)
+        worktree_entries.append({"path": rel_path, "sha256": sha256_hex(data), "bytes": len(data)})
+
+    git_entries: list[dict[str, Any]] = []
+    if scope == "full-repository" and (workspace_root / ".git").exists():
+        for object_id, data in _git_objects(workspace_root, policy):
+            report.scanned_git_objects += 1
+            report.findings.extend(_match_data(f"git:{object_id}", data, literal_rules, regex_rules))
+            git_entries.append({"object": object_id, "sha256": sha256_hex(data), "bytes": len(data)})
+
+    report.working_tree_digest = sha256_hex(canonical_bytes({"files": worktree_entries, "outputs": normalized_outputs}))
+    report.git_object_set_digest = sha256_hex(canonical_bytes({"objects": git_entries}))
+    return report
+
+
+def _walk_repository_files(workspace_root: Path, policy: NeutralityPolicy) -> Iterable[str]:
+    for root, dirnames, filenames in os.walk(workspace_root):
+        root_path = Path(root)
+        rel_root = root_path.relative_to(workspace_root).as_posix()
+        dirnames[:] = [
+            dirname
+            for dirname in dirnames
+            if not _excluded(_join_rel(rel_root, dirname), policy.path_excludes)
+        ]
+        for filename in filenames:
+            rel_path = _join_rel(rel_root, filename)
+            if _excluded(rel_path, policy.path_excludes):
+                continue
+            mode = os.lstat(root_path / filename).st_mode
+            if stat.S_ISREG(mode):
+                yield rel_path
+
+
+def _join_rel(root: str, name: str) -> str:
+    return name if root == "." else f"{root}/{name}"
+
+
+def _excluded(path: str, excludes: tuple[Pattern[str], ...]) -> bool:
+    return any(pattern.search(path) for pattern in excludes)
+
+
+def _match_data(
+    source: str,
+    data: bytes,
+    literal_rules: tuple[str, ...],
+    regex_rules: tuple[Pattern[str], ...],
+) -> list[NeutralityFinding]:
+    findings: list[NeutralityFinding] = []
+    text = data.decode("utf-8", errors="ignore")
+    for index, literal in enumerate(literal_rules):
+        if literal and literal in text:
+            findings.append(NeutralityFinding(source=source, ruleId=f"literal:{index}", category="deny-literal"))
+    for index, pattern in enumerate(regex_rules):
+        if pattern.search(text):
+            findings.append(NeutralityFinding(source=source, ruleId=f"regex:{index}", category="deny-regex"))
+    return findings
+
+
+def _scan_archive(
+    source: str,
+    data: bytes,
+    policy: NeutralityPolicy,
+    report: NeutralityReport,
+    literal_rules: tuple[str, ...],
+    regex_rules: tuple[Pattern[str], ...],
+    archive_budget: ArchiveScanBudget,
+    *,
+    depth: int,
+) -> None:
+    if not data.startswith(b"PK\x03\x04"):
+        return
+    import io
+
+    if depth > policy.max_archive_nesting_depth:
+        report.archive_limit_breaches += 1
+        return
+    archive_budget.archives += 1
+    if archive_budget.archives > policy.max_archives_per_subject:
+        report.archive_limit_breaches += 1
+        return
+    if len(data) > policy.max_compressed_bytes_per_archive:
+        report.archive_limit_breaches += 1
+        return
+
+    try:
+        with zipfile.ZipFile(io.BytesIO(data)) as archive:
+            names: set[str] = set()
+            infos = archive.infolist()
+            if len(infos) > policy.max_archive_entries:
+                report.archive_limit_breaches += 1
+                return
+            expanded_bytes = sum(info.file_size for info in infos)
+            compressed_bytes = sum(info.compress_size for info in infos)
+            if expanded_bytes > policy.max_expanded_bytes_per_archive:
+                report.archive_limit_breaches += 1
+                return
+            if _ratio_exceeds(expanded_bytes, compressed_bytes, policy.max_compression_ratio):
+                report.archive_limit_breaches += 1
+                return
+            if archive_budget.entries + len(infos) > policy.max_entries_per_subject:
+                report.archive_limit_breaches += 1
+                return
+            if archive_budget.expanded_bytes + expanded_bytes > policy.max_expanded_bytes_per_subject:
+                report.archive_limit_breaches += 1
+                return
+            archive_budget.entries += len(infos)
+            archive_budget.expanded_bytes += expanded_bytes
+            for info in infos:
+                key = info.filename.casefold()
+                if key in names or info.filename.startswith("/") or ".." in Path(info.filename).parts:
+                    report.archive_limit_breaches += 1
+                    return
+                names.add(key)
+                if info.file_size > policy.max_expanded_entry_bytes:
+                    report.archive_limit_breaches += 1
+                    return
+                if _ratio_exceeds(info.file_size, info.compress_size, policy.max_compression_ratio):
+                    report.archive_limit_breaches += 1
+                    return
+                if info.is_dir():
+                    continue
+                content = archive.read(info, pwd=None)
+                report.findings.extend(_match_data(f"{source}!{info.filename}", content, literal_rules, regex_rules))
+                _scan_archive(
+                    f"{source}!{info.filename}",
+                    content,
+                    policy,
+                    report,
+                    literal_rules,
+                    regex_rules,
+                    archive_budget,
+                    depth=depth + 1,
+                )
+    except (zipfile.BadZipFile, RuntimeError):
+        report.unsupported_archives += 1
+
+
+def _ratio_exceeds(expanded_bytes: int, compressed_bytes: int, max_ratio: int) -> bool:
+    if expanded_bytes <= 0:
+        return False
+    if compressed_bytes <= 0:
+        return True
+    return expanded_bytes > compressed_bytes * max_ratio
+
+
+def _git_objects(workspace_root: Path, policy: NeutralityPolicy) -> Iterable[tuple[str, bytes]]:
+    try:
+        objects = subprocess.run(
+            ["git", "rev-list", "--objects", "--all", "--reflog"],
+            cwd=workspace_root,
+            check=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+        ).stdout.splitlines()
+    except (OSError, subprocess.CalledProcessError):
+        return
+    seen: set[str] = set()
+    for line in objects:
+        object_id = line.split(" ", 1)[0]
+        if object_id in seen:
+            continue
+        seen.add(object_id)
+        try:
+            size = int(
+                subprocess.run(
+                    ["git", "cat-file", "-s", object_id],
+                    cwd=workspace_root,
+                    check=True,
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.PIPE,
+                    text=True,
+                ).stdout.strip()
+            )
+            if size > policy.max_object_bytes:
+                continue
+            data = subprocess.run(
+                ["git", "cat-file", "-p", object_id],
+                cwd=workspace_root,
+                check=True,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+            ).stdout
+        except (OSError, subprocess.CalledProcessError, ValueError):
+            continue
+        yield object_id, data

agent_lifecycle/neutrality/test_runner.py

@@ -0,0 +1,116 @@
+"""Stdlib unittest runner for controller validation commands."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import unittest
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+if __package__ in (None, ""):
+    sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
+
+from agent_lifecycle.neutrality.canonical import load_json, write_json_create
+from agent_lifecycle.neutrality.errors import NeutralityError, write_neutrality_error
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="agent-lifecycle-unittest-runner")
+    parser.add_argument("--operation-request", required=True)
+    parser.add_argument("--start-directory", required=True)
+    parser.add_argument("--pattern", default="test*.py")
+    parser.add_argument("--report", required=True)
+    args = parser.parse_args(argv)
+
+    try:
+        _require_protocol_output(
+            request_path=args.operation_request,
+            output_path=args.report,
+            schema_version="agent-lifecycle-unittest-report.v1",
+        )
+        result = _run_suite(args.start_directory, args.pattern)
+        report = _build_report(args.operation_request, args.start_directory, args.pattern, result)
+        write_json_create(Path(args.report), report)
+        return 0 if report["verdict"] == "PASS" else 1
+    except NeutralityError as exc:
+        write_neutrality_error(exc, sys.stdout)
+        return 2
+
+
+def _run_suite(start_directory: str, pattern: str) -> unittest.TestResult:
+    loader = unittest.TestLoader()
+    suite = loader.discover(start_dir=start_directory, pattern=pattern)
+    runner = unittest.TextTestRunner(stream=sys.stderr, verbosity=1)
+    return runner.run(suite)
+
+
+def _build_report(
+    operation_request_path: str,
+    start_directory: str,
+    pattern: str,
+    result: unittest.TestResult,
+) -> dict[str, Any]:
+    request = load_json(Path(operation_request_path).read_bytes())
+    claims = request.get("claims")
+    if not isinstance(claims, dict):
+        raise NeutralityError("operation request claims are missing")
+    operation_keys = [
+        "runId",
+        "packageId",
+        "taskId",
+        "attempt",
+        "operationId",
+        "commandId",
+        "commandOperationId",
+        "planDigest",
+        "sourceRevision",
+        "projectionDigest",
+    ]
+    return {
+        "schemaVersion": "agent-lifecycle-unittest-report.v1",
+        "operation": {
+            "schemaVersion": "agent-local-unittest-operation.v1",
+            "requestClaimsDigest": request.get("claimsDigest"),
+            **{key: claims.get(key) for key in operation_keys},
+        },
+        "suite": {
+            "startDirectory": start_directory,
+            "pattern": pattern,
+            "testsRun": result.testsRun,
+            "failures": len(result.failures),
+            "errors": len(result.errors),
+            "skipped": len(result.skipped),
+            "expectedFailures": len(result.expectedFailures),
+            "unexpectedSuccesses": len(result.unexpectedSuccesses),
+        },
+        "verdict": "PASS" if result.wasSuccessful() else "FAIL",
+        "generatedAt": datetime.now(UTC).replace(microsecond=0).isoformat().replace("+00:00", "Z"),
+    }
+
+
+def _require_protocol_output(
+    *,
+    request_path: str,
+    output_path: str,
+    schema_version: str,
+) -> None:
+    request = load_json(Path(request_path).read_bytes())
+    claims = request.get("claims")
+    outputs = claims.get("protocolOutputs") if isinstance(claims, dict) else None
+    if not isinstance(outputs, list):
+        raise NeutralityError("operation request protocolOutputs are missing")
+    for item in outputs:
+        if (
+            isinstance(item, dict)
+            and item.get("path") == output_path
+            and item.get("schemaVersion") == schema_version
+            and item.get("createNoReplace") is True
+        ):
+            return
+    raise NeutralityError("report path is not authorized by operation request")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agent_lifecycle/planning/__init__.py

@@ -0,0 +1,47 @@
+"""Agent-ready plan validation primitives."""
+
+from agent_lifecycle.planning.acceptance_markdown import validate_acceptance_checklist
+from agent_lifecycle.planning.continuity import (
+    build_plan_snapshot,
+    reconcile_plan_snapshot,
+    render_plan_handoff,
+    require_reconciliation_pass,
+    require_repository_references_pass,
+    validate_repository_references,
+)
+from agent_lifecycle.planning.completeness import (
+    build_plan_completeness_profile,
+    load_plan_completeness_profile,
+    require_plan_completeness_pass,
+    validate_plan_completeness,
+    validate_plan_completeness_profile,
+)
+from agent_lifecycle.planning.tiering import resolve_sdd_tier
+from agent_lifecycle.planning.templates import (
+    build_task_template_library,
+    render_task_template,
+    require_task_template_validation_pass,
+    validate_task_template_library,
+)
+from agent_lifecycle.planning.validation import validate_plan_manifest
+
+__all__ = [
+    "build_plan_snapshot",
+    "build_plan_completeness_profile",
+    "build_task_template_library",
+    "load_plan_completeness_profile",
+    "reconcile_plan_snapshot",
+    "render_task_template",
+    "render_plan_handoff",
+    "require_reconciliation_pass",
+    "require_repository_references_pass",
+    "require_plan_completeness_pass",
+    "require_task_template_validation_pass",
+    "resolve_sdd_tier",
+    "validate_acceptance_checklist",
+    "validate_plan_completeness",
+    "validate_plan_completeness_profile",
+    "validate_plan_manifest",
+    "validate_repository_references",
+    "validate_task_template_library",
+]