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

agent_lifecycle/neutrality/ed25519.py

@@ -0,0 +1,124 @@
+"""Small pure-Python Ed25519 implementation for local portability.
+
+The code follows the formulas from RFC 8032 and intentionally exposes only the
+operations required by the lifecycle receipts.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+P = 2**255 - 19
+Q = 2**252 + 27742317777372353535851937790883648493
+D = -121665 * pow(121666, P - 2, P) % P
+I = pow(2, (P - 1) // 4, P)
+
+
+def _x_recover(y: int) -> int:
+    xx = (y * y - 1) * pow(D * y * y + 1, P - 2, P)
+    x = pow(xx, (P + 3) // 8, P)
+    if (x * x - xx) % P != 0:
+        x = (x * I) % P
+    if x % 2 != 0:
+        x = P - x
+    return x
+
+
+B = (_x_recover(4 * pow(5, P - 2, P) % P), 4 * pow(5, P - 2, P) % P)
+
+
+def _is_on_curve(point: tuple[int, int]) -> bool:
+    x, y = point
+    return (-x * x + y * y - 1 - D * x * x * y * y) % P == 0
+
+
+def _point_add(left: tuple[int, int], right: tuple[int, int]) -> tuple[int, int]:
+    x1, y1 = left
+    x2, y2 = right
+    denominator = pow(1 + D * x1 * x2 * y1 * y2, P - 2, P)
+    x3 = (x1 * y2 + x2 * y1) * denominator % P
+    denominator = pow(1 - D * x1 * x2 * y1 * y2, P - 2, P)
+    y3 = (y1 * y2 + x1 * x2) * denominator % P
+    return x3, y3
+
+
+def _scalar_mult(point: tuple[int, int], scalar: int) -> tuple[int, int]:
+    if scalar == 0:
+        return 0, 1
+    half = _scalar_mult(point, scalar // 2)
+    doubled = _point_add(half, half)
+    if scalar & 1:
+        return _point_add(doubled, point)
+    return doubled
+
+
+def _encode_int(value: int) -> bytes:
+    return value.to_bytes(32, "little")
+
+
+def _encode_point(point: tuple[int, int]) -> bytes:
+    x, y = point
+    encoded = bytearray(_encode_int(y))
+    encoded[31] |= (x & 1) << 7
+    return bytes(encoded)
+
+
+def _decode_point(data: bytes) -> tuple[int, int]:
+    if len(data) != 32:
+        raise ValueError("encoded point must be 32 bytes")
+    y = int.from_bytes(data, "little") & ((1 << 255) - 1)
+    x = _x_recover(y)
+    if (x & 1) != (data[31] >> 7):
+        x = P - x
+    point = (x, y)
+    if not _is_on_curve(point):
+        raise ValueError("decoded point is not on curve")
+    return point
+
+
+def _hint(data: bytes) -> int:
+    return int.from_bytes(hashlib.sha512(data).digest(), "little")
+
+
+def _secret_scalar(seed: bytes) -> tuple[int, bytes]:
+    if len(seed) != 32:
+        raise ValueError("Ed25519 seed must be 32 bytes")
+    digest = hashlib.sha512(seed).digest()
+    scalar = int.from_bytes(digest[:32], "little")
+    scalar &= (1 << 254) - 8
+    scalar |= 1 << 254
+    return scalar, digest[32:]
+
+
+def publickey_from_seed(seed: bytes) -> bytes:
+    scalar, _prefix = _secret_scalar(seed)
+    return _encode_point(_scalar_mult(B, scalar))
+
+
+def sign(seed: bytes, message: bytes) -> bytes:
+    scalar, prefix = _secret_scalar(seed)
+    public_key = publickey_from_seed(seed)
+    r = _hint(prefix + message) % Q
+    encoded_r = _encode_point(_scalar_mult(B, r))
+    h = _hint(encoded_r + public_key + message) % Q
+    s = (r + h * scalar) % Q
+    return encoded_r + _encode_int(s)
+
+
+def verify(public_key: bytes, message: bytes, signature: bytes) -> bool:
+    if len(public_key) != 32 or len(signature) != 64:
+        return False
+    try:
+        point_a = _decode_point(public_key)
+        point_r = _decode_point(signature[:32])
+    except ValueError:
+        return False
+    s = int.from_bytes(signature[32:], "little")
+    if s >= Q:
+        return False
+    h = _hint(signature[:32] + public_key + message) % Q
+    return _scalar_mult(B, s) == _point_add(point_r, _scalar_mult(point_a, h))
+
+
+def fingerprint(public_key: bytes) -> str:
+    return "ed25519:" + hashlib.sha256(public_key).hexdigest()

agent_lifecycle/neutrality/errors.py

@@ -0,0 +1,89 @@
+"""Neutrality-specific exceptions."""
+
+from __future__ import annotations
+
+from typing import Any, TextIO
+
+from agent_lifecycle.contracts.canonical import canonical_bytes
+from agent_lifecycle.contracts.errors import LifecycleError
+
+_CODE_RULES: tuple[tuple[str, str], ...] = (
+    ("signing key is required", "neutrality-signing-key-required"),
+    ("signing key fingerprint does not match", "neutrality-signing-key-mismatch"),
+    ("signing key public key is not authorized", "neutrality-signing-key-unauthorized"),
+    ("missing signature", "neutrality-authority-missing-signature"),
+    ("unsupported signature algorithm", "neutrality-unsupported-signature-algorithm"),
+    ("signer fingerprint mismatch", "neutrality-authority-signer-mismatch"),
+    ("gate receipt signature verification failed", "neutrality-gate-signature-invalid"),
+    ("deny authority signature verification failed", "neutrality-authority-signature-invalid"),
+    ("signature verification failed", "neutrality-signature-invalid"),
+    ("authorizedsigners must be a list", "neutrality-trust-root-invalid"),
+    ("trust root signer public key does not match", "neutrality-trust-root-signer-mismatch"),
+    ("expected signer is not authorized", "neutrality-signer-unauthorized"),
+    ("unsupported trust root schemaversion", "neutrality-trust-root-schema-unsupported"),
+    ("unsupported neutrality policy schemaversion", "neutrality-policy-schema-unsupported"),
+    ("expected agent-neutrality", "neutrality-authority-schema-mismatch"),
+    ("expiresat must be after issuedat", "neutrality-authority-invalid-window"),
+    ("validity window is too wide", "neutrality-authority-invalid-window"),
+    ("issuedat is in the future", "neutrality-authority-not-yet-valid"),
+    ("authority is stale", "neutrality-authority-stale"),
+    ("timestamps must include timezone", "neutrality-timestamp-invalid"),
+    ("must be a non-empty string", "neutrality-field-invalid"),
+    ("must be an object", "neutrality-field-invalid"),
+    ("must be a list of strings", "neutrality-field-invalid"),
+    ("must be a positive integer", "neutrality-field-invalid"),
+    ("external authority paths must be absolute", "neutrality-external-authority-path-invalid"),
+    ("external authority path is inside a forbidden root", "neutrality-external-authority-forbidden-root"),
+    ("external authority path must not be a symlink", "neutrality-external-authority-symlink"),
+    ("external authority path must be a regular file", "neutrality-external-authority-not-regular"),
+    ("external authority path must not have multiple hard links", "neutrality-external-authority-hard-link"),
+    ("not a regular file", "neutrality-input-not-regular"),
+    ("file exceeds max bytes", "neutrality-input-too-large"),
+    ("read exceeds max bytes", "neutrality-input-too-large"),
+    ("stable read identity changed", "neutrality-stable-read-race"),
+    ("invalid repository-relative path", "neutrality-repository-path-invalid"),
+    ("repository-relative path is too long", "neutrality-repository-path-invalid"),
+    ("output path alias conflict", "neutrality-output-alias-conflict"),
+    ("operation request claims are missing", "neutrality-operation-request-invalid"),
+    ("operation request protocoloutputs are missing", "neutrality-operation-request-invalid"),
+    ("report path is not authorized", "neutrality-output-not-authorized"),
+    ("requested report path is not authorized", "neutrality-output-not-authorized"),
+    ("existing output paths do not match", "neutrality-output-occupied"),
+    ("operation output path is occupied", "neutrality-output-occupied"),
+    ("neutrality findings are non-zero", "neutrality-findings-nonzero"),
+    ("neutrality scan counters are non-zero", "neutrality-counters-nonzero"),
+    ("neutrality gate counters are non-zero", "neutrality-counters-nonzero"),
+    ("receipt verification failed", "neutrality-receipt-verification-failed"),
+    ("gate receipt path is already occupied", "neutrality-gate-receipt-occupied"),
+    ("gate receipt generatedat is missing", "neutrality-gate-generated-at-missing"),
+    ("gate receipt attestation is missing", "neutrality-gate-attestation-missing"),
+    ("gate receipt attestation binding mismatch", "neutrality-gate-attestation-mismatch"),
+    ("gate receipt", "neutrality-gate-binding-mismatch"),
+    ("operation output must match receipt", "neutrality-gate-output-mismatch"),
+    ("gate receipt must be repository-relative", "neutrality-gate-receipt-path-invalid"),
+    ("gate receipt escapes workspace", "neutrality-gate-receipt-path-invalid"),
+    ("operation outputs must be repository-relative", "neutrality-output-path-invalid"),
+    ("operation output escapes workspace", "neutrality-output-path-invalid"),
+    ("required environment variable is not set", "neutrality-env-missing"),
+    ("invalid json", "neutrality-invalid-json"),
+    ("expected object", "neutrality-json-object-required"),
+)
+
+
+class NeutralityError(LifecycleError):
+    """A fail-closed neutrality contract violation."""
+
+    def __init__(self, message: str, *, code: str | None = None, details: dict[str, Any] | None = None):
+        super().__init__(code or neutrality_error_code(message), message, details or {})
+
+
+def neutrality_error_code(message: str) -> str:
+    normalized = message.casefold()
+    for marker, code in _CODE_RULES:
+        if marker in normalized:
+            return code
+    return "neutrality-contract-violation"
+
+
+def write_neutrality_error(exc: NeutralityError, stream: TextIO) -> None:
+    stream.write(canonical_bytes(exc.to_json()).decode("utf-8") + "\n")

agent_lifecycle/neutrality/gate.py

@@ -0,0 +1,269 @@
+"""Controller-gate compatibility wrapper for neutrality scans."""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import os
+import re
+import sys
+from dataclasses import replace
+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.authority import RECEIPT_DOMAIN, load_authority_bundle
+from agent_lifecycle.neutrality.canonical import canonical_bytes, load_json, sha256_hex, write_json_create
+from agent_lifecycle.neutrality.ed25519 import verify as verify_signature
+from agent_lifecycle.neutrality.errors import NeutralityError, write_neutrality_error
+from agent_lifecycle.neutrality.paths import resolve_repository_relative_root
+from agent_lifecycle.neutrality.policy import load_policy
+from agent_lifecycle.neutrality.scanner import scan_repository
+
+POLICY_PATH = "policy/neutrality.policy.json"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "produce":
+            return _produce(args)
+        if args.command == "verify":
+            return _verify(args)
+    except NeutralityError as exc:
+        write_neutrality_error(exc, sys.stdout)
+        return 2
+    return 2
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="agent-lifecycle-neutrality-gate")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    for command in ("produce", "verify"):
+        gate = subparsers.add_parser(command)
+        gate.add_argument("--profile", required=True)
+        gate.add_argument("--scope", required=True, choices=["current-tree-complete", "full-repository"])
+        gate.add_argument("--gate-id", required=True)
+        gate.add_argument("--run-id", required=True)
+        gate.add_argument("--package-id", required=True)
+        gate.add_argument("--task-id", required=True)
+        gate.add_argument("--attempt", required=True, type=int)
+        gate.add_argument("--phase", required=True)
+        gate.add_argument("--operation-id", required=True)
+        gate.add_argument("--plan-digest", required=True)
+        gate.add_argument("--source-revision", required=True)
+        gate.add_argument("--workspace-root", required=True)
+        gate.add_argument("--artifact-root", default="plans/standalone-v1")
+        gate.add_argument("--operation-output", required=True)
+        gate.add_argument("--receipt", required=True)
+    return parser
+
+
+def _produce(args: argparse.Namespace) -> int:
+    workspace_root = Path(args.workspace_root).resolve()
+    receipt_path = _receipt_path(workspace_root, args)
+    if receipt_path.exists():
+        raise NeutralityError("gate receipt path is already occupied")
+    authority = _authority(workspace_root, args, signing=True)
+    report = _scan(workspace_root, args, authority)
+    _require_zero(report)
+    generated_at = datetime.now(UTC).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+    claims = _claims(args, report, authority.authority_digest, generated_at)
+    claims_digest = sha256_hex(canonical_bytes(claims))
+    receipt = {
+        "schemaVersion": "agent-controller-gate-receipt.v1",
+        "gateId": args.gate_id,
+        "runId": args.run_id,
+        "packageId": args.package_id,
+        "taskId": args.task_id,
+        "attempt": args.attempt,
+        "phase": args.phase,
+        "operationId": args.operation_id,
+        "planDigest": args.plan_digest,
+        "sourceRevision": args.source_revision,
+        "verdict": "PASS",
+        "generatedAt": generated_at,
+        "attestation": {
+            "schemaVersion": "agent-controller-gate-attestation.v1",
+            "algorithm": "Ed25519",
+            "claimsDigest": claims_digest,
+            "subjectDigest": report["digests"]["subjectDigest"],
+            "scopeDigest": claims["scopeDigest"],
+            "authorityDigest": authority.authority_digest,
+            "signerFingerprint": _digest_fingerprint(authority.signer_fingerprint),
+            "signature": base64.b64encode(
+                bytes.fromhex(authority.sign_claims_digest(claims_digest))
+            ).decode("ascii"),
+        },
+    }
+    write_json_create(receipt_path, receipt)
+    print(f"neutrality-gate: wrote {receipt_path.relative_to(workspace_root)}")
+    return 0
+
+
+def _verify(args: argparse.Namespace) -> int:
+    workspace_root = Path(args.workspace_root).resolve()
+    receipt_path = _receipt_path(workspace_root, args)
+    receipt = load_json(receipt_path.read_bytes())
+    expected = {
+        "schemaVersion": "agent-controller-gate-receipt.v1",
+        "gateId": args.gate_id,
+        "runId": args.run_id,
+        "packageId": args.package_id,
+        "taskId": args.task_id,
+        "attempt": args.attempt,
+        "phase": args.phase,
+        "operationId": args.operation_id,
+        "planDigest": args.plan_digest,
+        "sourceRevision": args.source_revision,
+        "verdict": "PASS",
+    }
+    for key, value in expected.items():
+        if receipt.get(key) != value:
+            raise NeutralityError(f"gate receipt {key} binding mismatch")
+    generated_at = receipt.get("generatedAt")
+    if not isinstance(generated_at, str) or not generated_at:
+        raise NeutralityError("gate receipt generatedAt is missing")
+    authority = _authority(workspace_root, args, signing=False)
+    report = _scan(workspace_root, args, authority)
+    _require_zero(report)
+    claims = _claims(args, report, authority.authority_digest, generated_at)
+    claims_digest = sha256_hex(canonical_bytes(claims))
+    attestation = receipt.get("attestation")
+    if not isinstance(attestation, dict):
+        raise NeutralityError("gate receipt attestation is missing")
+    if (
+        attestation.get("claimsDigest") != claims_digest
+        or attestation.get("subjectDigest") != report["digests"]["subjectDigest"]
+        or attestation.get("scopeDigest") != claims["scopeDigest"]
+        or attestation.get("authorityDigest") != authority.authority_digest
+        or attestation.get("signerFingerprint") != _digest_fingerprint(authority.signer_fingerprint)
+    ):
+        raise NeutralityError("gate receipt attestation binding mismatch")
+    signature = base64.b64decode(str(attestation.get("signature")), validate=True)
+    if not verify_signature(
+        bytes.fromhex(authority.signer_public_key_hex),
+        RECEIPT_DOMAIN + claims_digest.encode("ascii"),
+        signature,
+    ):
+        raise NeutralityError("gate receipt signature verification failed")
+    print("neutrality-gate: receipt verified")
+    return 0
+
+
+def _authority(workspace_root: Path, args: argparse.Namespace, *, signing: bool):
+    return load_authority_bundle(
+        deny_authority_path=Path(_env("AGENT_LIFECYCLE_NEUTRALITY_DENY_AUTHORITY")),
+        trust_root_path=Path(_env("AGENT_LIFECYCLE_NEUTRALITY_TRUST_ROOT")),
+        signing_key_path=(
+            Path(_env("AGENT_LIFECYCLE_NEUTRALITY_SIGNING_KEY")) if signing else None
+        ),
+        expected_signer_fingerprint=_env("AGENT_LIFECYCLE_NEUTRALITY_SIGNER_FINGERPRINT"),
+        workspace_root=workspace_root,
+        artifact_root=_artifact_root(workspace_root, args.artifact_root),
+    )
+
+
+def _scan(workspace_root: Path, args: argparse.Namespace, authority) -> dict[str, Any]:
+    policy = load_policy(workspace_root / POLICY_PATH)
+    receipt_path = _receipt_path(workspace_root, args).relative_to(workspace_root).as_posix()
+    policy = replace(
+        policy,
+        path_excludes=policy.path_excludes + (re.compile(f"^{re.escape(receipt_path)}$"),),
+    )
+    profile = load_json((workspace_root / args.profile).read_bytes())
+    report = scan_repository(
+        workspace_root=workspace_root,
+        policy=policy,
+        deny_literals=authority.deny_literals,
+        deny_regexes=authority.deny_regexes,
+        scope=args.scope,
+        output_paths=[],
+    ).to_json(
+        {
+            "schemaVersion": "agent-neutrality-gate-operation.v1",
+            "gateId": args.gate_id,
+            "runId": args.run_id,
+            "packageId": args.package_id,
+            "taskId": args.task_id,
+            "attempt": args.attempt,
+            "phase": args.phase,
+            "operationId": args.operation_id,
+            "planDigest": args.plan_digest,
+            "sourceRevision": args.source_revision,
+            "profileDigest": sha256_hex(canonical_bytes(profile)),
+        }
+    )
+    return report
+
+
+def _claims(
+    args: argparse.Namespace,
+    report: dict[str, Any],
+    authority_digest: str,
+    generated_at: str,
+) -> dict[str, Any]:
+    return {
+        "schemaVersion": "agent-neutrality-controller-gate-claims.v1",
+        "gateId": args.gate_id,
+        "runId": args.run_id,
+        "packageId": args.package_id,
+        "taskId": args.task_id,
+        "attempt": args.attempt,
+        "phase": args.phase,
+        "operationId": args.operation_id,
+        "planDigest": args.plan_digest,
+        "sourceRevision": args.source_revision,
+        "scope": report["scope"],
+        "scopeDigest": sha256_hex(canonical_bytes({"scope": report["scope"]})),
+        "subjectDigest": report["digests"]["subjectDigest"],
+        "workingTreeDigest": report["digests"]["workingTreeDigest"],
+        "gitObjectSetDigest": report["digests"]["gitObjectSetDigest"],
+        "zeroCounters": report["counters"],
+        "authorityDigest": authority_digest,
+        "receiptPath": args.receipt,
+        "generatedAt": generated_at,
+        "verdict": "PASS",
+    }
+
+
+def _require_zero(report: dict[str, Any]) -> None:
+    if any(int(value) != 0 for value in report["counters"].values()):
+        raise NeutralityError("neutrality gate counters are non-zero")
+
+
+def _receipt_path(workspace_root: Path, args: argparse.Namespace) -> Path:
+    if args.operation_output != args.receipt:
+        raise NeutralityError("operation output must match receipt for controller gate v1")
+    path = Path(args.receipt)
+    if path.is_absolute():
+        raise NeutralityError("gate receipt must be repository-relative")
+    resolved = (workspace_root / path).resolve()
+    if not resolved.is_relative_to(workspace_root):
+        raise NeutralityError("gate receipt escapes workspace")
+    return resolved
+
+
+def _artifact_root(workspace_root: Path, value: str) -> Path:
+    return resolve_repository_relative_root(workspace_root, value, label="artifact root")
+
+
+def _digest_fingerprint(value: str) -> str:
+    if value.startswith("ed25519:"):
+        return value.split(":", 1)[1]
+    return value
+
+
+def _env(name: str) -> str:
+    value = os.environ.get(name)
+    if not value:
+        raise NeutralityError(f"required environment variable is not set: {name}")
+    return value
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agent_lifecycle/neutrality/paths.py

@@ -0,0 +1,92 @@
+"""Portable path and stable-read checks."""
+
+from __future__ import annotations
+
+import os
+import stat
+from pathlib import Path
+
+from .errors import NeutralityError
+
+
+def ensure_external_regular_file(
+    path: Path,
+    *,
+    workspace_root: Path,
+    artifact_root: Path,
+    release_root: Path | None = None,
+) -> Path:
+    if not path.is_absolute():
+        raise NeutralityError("external authority paths must be absolute")
+    resolved = path.resolve(strict=True)
+    roots = [workspace_root.resolve(), artifact_root.resolve()]
+    git_root = workspace_root / ".git"
+    if git_root.exists():
+        roots.append(git_root.resolve())
+    if release_root is not None:
+        roots.append(release_root.resolve())
+    for root in roots:
+        if resolved == root or resolved.is_relative_to(root):
+            raise NeutralityError("external authority path is inside a forbidden root")
+    first = os.lstat(resolved)
+    if stat.S_ISLNK(first.st_mode):
+        raise NeutralityError("external authority path must not be a symlink")
+    if not stat.S_ISREG(first.st_mode):
+        raise NeutralityError("external authority path must be a regular file")
+    if first.st_nlink > 1:
+        raise NeutralityError("external authority path must not have multiple hard links")
+    return resolved
+
+
+def stable_read_bytes(path: Path, *, max_bytes: int | None = None) -> bytes:
+    before = os.stat(path, follow_symlinks=False)
+    if not stat.S_ISREG(before.st_mode):
+        raise NeutralityError(f"not a regular file: {path}")
+    if max_bytes is not None and before.st_size > max_bytes:
+        raise NeutralityError(f"file exceeds max bytes: {path}")
+    with path.open("rb") as handle:
+        data = handle.read()
+    after = os.stat(path, follow_symlinks=False)
+    identity_before = (before.st_dev, before.st_ino, before.st_mode, before.st_size, before.st_mtime_ns)
+    identity_after = (after.st_dev, after.st_ino, after.st_mode, after.st_size, after.st_mtime_ns)
+    if identity_before != identity_after:
+        raise NeutralityError(f"stable read identity changed: {path}")
+    if max_bytes is not None and len(data) > max_bytes:
+        raise NeutralityError(f"read exceeds max bytes: {path}")
+    return data
+
+
+def validate_repository_relative_path(path: str) -> None:
+    if not path or path.startswith("/") or "\\" in path or "\x00" in path:
+        raise NeutralityError(f"invalid repository-relative path: {path}")
+    parts = path.split("/")
+    if any(part in ("", ".", "..") for part in parts):
+        raise NeutralityError(f"invalid repository-relative path: {path}")
+    if any(part.endswith(".") or part.endswith(" ") for part in parts):
+        raise NeutralityError(f"invalid repository-relative path: {path}")
+    if len(path.encode("utf-8")) > 4096:
+        raise NeutralityError(f"repository-relative path is too long: {path}")
+
+
+def validate_output_paths(output_paths: list[Path]) -> list[str]:
+    seen: dict[str, str] = {}
+    normalized: list[str] = []
+    for path in output_paths:
+        path_text = path.as_posix()
+        validate_repository_relative_path(path_text)
+        key = path_text.casefold()
+        if key in seen:
+            raise NeutralityError(f"output path alias conflict: {seen[key]} vs {path_text}")
+        seen[key] = path_text
+        normalized.append(path_text)
+    return normalized
+
+
+def resolve_repository_relative_root(workspace_root: Path, value: str, *, label: str) -> Path:
+    path = Path(value)
+    if path.is_absolute():
+        raise NeutralityError(f"{label} must be repository-relative")
+    resolved = (workspace_root / path).resolve()
+    if not resolved.is_relative_to(workspace_root):
+        raise NeutralityError(f"{label} escapes workspace")
+    return resolved

agent_lifecycle/neutrality/policy.py

@@ -0,0 +1,76 @@
+"""Neutrality policy loading."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Pattern
+
+from .canonical import load_json
+from .errors import NeutralityError
+
+
+@dataclass(frozen=True)
+class NeutralityPolicy:
+    raw: dict[str, Any]
+    path_excludes: tuple[Pattern[str], ...]
+    deny_literals: tuple[str, ...]
+    deny_regexes: tuple[Pattern[str], ...]
+    max_file_bytes: int
+    max_object_bytes: int
+    max_archive_nesting_depth: int
+    max_archives_per_subject: int
+    max_archive_entries: int
+    max_entries_per_subject: int
+    max_compressed_bytes_per_archive: int
+    max_expanded_bytes_per_archive: int
+    max_expanded_entry_bytes: int
+    max_expanded_bytes_per_subject: int
+    max_compression_ratio: int
+
+
+def load_policy(path: Path) -> NeutralityPolicy:
+    document = load_json(path.read_bytes())
+    if document.get("schemaVersion") != "agent-lifecycle-neutrality-policy.v1":
+        raise NeutralityError("unsupported neutrality policy schemaVersion")
+    scan = _object(document, "scan")
+    archives = _object(document, "archives")
+    return NeutralityPolicy(
+        raw=document,
+        path_excludes=tuple(re.compile(value) for value in _string_list(document, "pathExcludes")),
+        deny_literals=tuple(_string_list(document, "denyLiterals")),
+        deny_regexes=tuple(re.compile(value) for value in _string_list(document, "denyRegexes")),
+        max_file_bytes=_positive_int(scan, "maxFileBytes", 16_777_216),
+        max_object_bytes=_positive_int(scan, "maxObjectBytes", 16_777_216),
+        max_archive_nesting_depth=_positive_int(archives, "maxArchiveNestingDepth", 4),
+        max_archives_per_subject=_positive_int(archives, "maxArchivesPerSubject", 1_000),
+        max_archive_entries=_positive_int(archives, "maxEntriesPerArchive", 10_000),
+        max_entries_per_subject=_positive_int(archives, "maxEntriesPerSubject", 100_000),
+        max_compressed_bytes_per_archive=_positive_int(archives, "maxCompressedBytesPerArchive", 536_870_912),
+        max_expanded_bytes_per_archive=_positive_int(archives, "maxExpandedBytesPerArchive", 2_147_483_648),
+        max_expanded_entry_bytes=_positive_int(archives, "maxExpandedBytesPerEntry", 268_435_456),
+        max_expanded_bytes_per_subject=_positive_int(archives, "maxExpandedBytesPerSubject", 4_294_967_296),
+        max_compression_ratio=_positive_int(archives, "maxCompressionRatio", 100),
+    )
+
+
+def _string_list(document: dict[str, Any], key: str) -> list[str]:
+    value = document.get(key, [])
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        raise NeutralityError(f"{key} must be a list of strings")
+    return value
+
+
+def _object(document: dict[str, Any], key: str) -> dict[str, Any]:
+    value = document.get(key, {})
+    if not isinstance(value, dict):
+        raise NeutralityError(f"{key} must be an object")
+    return value
+
+
+def _positive_int(document: dict[str, Any], key: str, default: int) -> int:
+    value = document.get(key, default)
+    if not isinstance(value, int) or isinstance(value, bool) or value < 1:
+        raise NeutralityError(f"{key} must be a positive integer")
+    return value