"""Append-only ClaimGuard binding for the superseded Single-Host child Task.""" from __future__ import annotations from datetime import datetime, timezone import hashlib import json import re import sqlite3 from typing import Any, Callable, Mapping from aios_task_lineage_supersession_initial_projection import ( PROJECTION_RECEIPT_SCHEMA, PROJECTION_TABLE, SOURCE_BUSINESS_EXECUTION_DIGEST, ) SOURCE_TASK_ID = "TASK-SINGLEHOST-TRUSTROOT-P0-20260904" CHILD_TASK_ID = SOURCE_TASK_ID + "-S1" WORKER_ID = "p0-task-principal-v15-20260830" REPOSITORY = "aios/aios" TARGET_BRANCH = "agent/single-host-trust-root-p0-20260904" GENERATION = 1 EXTERNAL_JOB_ID = "job-4e10f92a6a5742518a9f1d8745c845ab" BINDING_SCHEMA = "aios.task-claim-guard-binding.v2" RECEIPT_SCHEMA = "aios.task-claim-guard-binding-receipt.v2" HEX64 = re.compile(r"^[0-9a-f]{64}$") class ClaimGuardBindingError(RuntimeError): def __init__(self, code: str, http_status: int = 409): super().__init__(code) self.code = code self.http_status = int(http_status) def _fail(code: str, status: int = 409) -> None: raise ClaimGuardBindingError(code, status) def canonical_json(value: Any) -> str: return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"), allow_nan=False) def _sha_text(value: str) -> str: return hashlib.sha256(value.encode("utf-8")).hexdigest() def _sha_json(value: Any) -> str: return _sha_text(canonical_json(value)) def _now() -> str: return datetime.now(timezone.utc).isoformat() def _row_dict(row: Any) -> dict[str, Any]: if row is None: return {} if hasattr(row, "keys"): return {str(key): row[key] for key in row.keys()} _fail("TASK_ROW_MAPPING_UNAVAILABLE", 500) def _json(raw: Any, code: str) -> Any: if not isinstance(raw, str): _fail(code) try: return json.loads(raw) except (TypeError, ValueError) as exc: raise ClaimGuardBindingError(code) from exc def _default_policy_factory(value: Mapping[str, Any]): try: from aios_single_host_operational_authority import OperationalPolicy except ImportError as exc: raise ClaimGuardBindingError("OPERATIONAL_POLICY_RUNTIME_UNAVAILABLE", 503) from exc return OperationalPolicy.from_mapping(value) def _policy_value(policy: Any, name: str) -> Any: try: return getattr(policy, name) except AttributeError as exc: raise ClaimGuardBindingError("OPERATIONAL_POLICY_FIELDS_INVALID") from exc def _load_projection_evidence(connection, relation) -> dict[str, Any]: try: row = connection.execute( f"SELECT * FROM {PROJECTION_TABLE} WHERE task_id=? AND source_task_id=? " "AND supersession_ordinal=?", (CHILD_TASK_ID, SOURCE_TASK_ID, 1), ).fetchone() except sqlite3.OperationalError as exc: raise ClaimGuardBindingError( "FORMAL_CHILD_INITIAL_PROJECTION_SCHEMA_UNAVAILABLE", 503 ) from exc if row is None: _fail("FORMAL_CHILD_INITIAL_PROJECTION_REQUIRED") value = _row_dict(row) receipt = _json(value.get("receipt_json"), "CHILD_PROJECTION_RECEIPT_INVALID") canonical_digest = value.get("canonical_child_execution_digest") source_digest = value.get("source_business_execution_digest") exact = { "task_id": CHILD_TASK_ID, "source_task_id": SOURCE_TASK_ID, "supersession_ordinal": 1, "source_business_execution_digest": SOURCE_BUSINESS_EXECUTION_DIGEST, "external_job_id": EXTERNAL_JOB_ID, "repository": REPOSITORY, "target_branch": TARGET_BRANCH, "generation": GENERATION, "owner_decision_sha256": relation["owner_decision_sha256"], } if any(value.get(key) != expected for key, expected in exact.items()): _fail("CHILD_PROJECTION_LINEAGE_MISMATCH") if ( not isinstance(canonical_digest, str) or HEX64.fullmatch(canonical_digest) is None or canonical_digest == SOURCE_BUSINESS_EXECUTION_DIGEST or source_digest != SOURCE_BUSINESS_EXECUTION_DIGEST or _sha_text(value["receipt_json"]) != value.get("receipt_sha256") or not isinstance(receipt, Mapping) or receipt.get("schema") != PROJECTION_RECEIPT_SCHEMA or receipt.get("canonical_child_execution_digest") != canonical_digest or receipt.get("source_business_execution_digest") != source_digest or receipt.get("owner_supersession_decision_sha256") != relation["owner_decision_sha256"] ): _fail("CHILD_PROJECTION_RECEIPT_MISMATCH") return { **value, "canonical_child_execution_digest": canonical_digest, "source_business_execution_digest": source_digest, } def install_child_binding( connection, *, policy: Mapping[str, Any], runtime_id: str, runtime_observation_digest: str, task_contract_version: str, policy_factory: Callable[[Mapping[str, Any]], Any] = _default_policy_factory, now: str | None = None, ) -> dict[str, Any]: """Generate and persist the only permitted child binding from current DB state.""" if not isinstance(policy, Mapping): _fail("OPERATIONAL_POLICY_INVALID") if not isinstance(runtime_id, str) or not runtime_id or len(runtime_id) > 512: _fail("RUNTIME_ID_INVALID") if not isinstance(runtime_observation_digest, str) or HEX64.fullmatch(runtime_observation_digest) is None: _fail("RUNTIME_OBSERVATION_DIGEST_INVALID") if not isinstance(task_contract_version, str) or not task_contract_version or len(task_contract_version) > 128: _fail("TASK_CONTRACT_VERSION_INVALID") relation = connection.execute( "SELECT * FROM task_lineage_supersessions WHERE source_task_id=? AND supersession_ordinal=1 AND child_task_id=?", (SOURCE_TASK_ID, CHILD_TASK_ID), ).fetchone() if relation is None: _fail("FORMAL_SUPERSESSION_REQUIRED") projection = _load_projection_evidence(connection, relation) canonical_execution_digest = projection["canonical_child_execution_digest"] task_row = connection.execute("SELECT * FROM tasks WHERE task_id=?", (CHILD_TASK_ID,)).fetchone() if task_row is None: _fail("CHILD_TASK_NOT_FOUND", 404) task = _row_dict(task_row) if ( task.get("status") != "QUEUED" or int(task.get("revision", -1)) < 2 or int(task.get("attempt", -1)) != 0 or task.get("claimed_by") is not None or task.get("lease_token_hash") is not None or task.get("lease_expires_at") is not None or task.get("result_json") is not None or task.get("verification_json") is not None ): _fail("CHILD_PROJECTED_CLAIMABLE_STATE_REQUIRED") event_rows = connection.execute( "SELECT event_type,payload_json FROM events WHERE task_id=? ORDER BY event_id", (CHILD_TASK_ID,), ).fetchall() if [row[0] for row in event_rows] != [ "TASK_CREATED", "TASK_INITIAL_EXECUTION_PROJECTION_AUTHORIZED", ]: _fail("CANONICAL_INITIAL_PROJECTION_REQUIRED") projection_event = _json( event_rows[-1][1], "CANONICAL_INITIAL_PROJECTION_EVENT_INVALID" ) if ( projection_event.get("source_business_execution_digest") != SOURCE_BUSINESS_EXECUTION_DIGEST or projection_event.get("canonical_child_execution_digest") != canonical_execution_digest or projection_event.get("owner_supersession_decision_sha256") != relation["owner_decision_sha256"] or _sha_json(projection_event) != projection["projection_event_sha256"] ): _fail("CANONICAL_INITIAL_PROJECTION_EVENT_MISMATCH") metadata_raw = task.get("metadata_json") capabilities_raw = task.get("required_capabilities_json") metadata = _json(metadata_raw, "CHILD_METADATA_INVALID") capabilities = _json(capabilities_raw, "CHILD_CAPABILITIES_INVALID") if ( _sha_text(metadata_raw) != projection["metadata_sha256"] or _sha_text(capabilities_raw) != projection["required_capabilities_sha256"] ): _fail("CHILD_PROJECTION_TASK_DIGEST_MISMATCH") if not isinstance(metadata, Mapping) or not isinstance(capabilities, list) or not capabilities: _fail("CHILD_PROJECTION_INVALID") if any(not isinstance(value, str) or not value for value in capabilities) or len(set(capabilities)) != len(capabilities): _fail("CHILD_CAPABILITIES_INVALID") execution = metadata.get("execution") if not isinstance(execution, Mapping): _fail("CHILD_EXECUTION_PROJECTION_MISSING") exact_execution = { "task_id": CHILD_TASK_ID, "repository": REPOSITORY, "target_branch": TARGET_BRANCH, "generation": GENERATION, "execution_digest": canonical_execution_digest, "job_id": EXTERNAL_JOB_ID, } if any(execution.get(key) != value for key, value in exact_execution.items()): _fail("CHILD_EXECUTION_BINDING_MISMATCH") parsed_policy = policy_factory(dict(policy)) if hasattr(parsed_policy, "validate"): parsed_policy.validate() policy_exact = { "task_id": CHILD_TASK_ID, "repository": REPOSITORY, "target_branch": TARGET_BRANCH, "generation": GENERATION, "execution_plan_sha256": canonical_execution_digest, "external_job_identity": EXTERNAL_JOB_ID, } if any(_policy_value(parsed_policy, key) != value for key, value in policy_exact.items()): _fail("OPERATIONAL_POLICY_SCOPE_MISMATCH") if tuple(_policy_value(parsed_policy, "allowed_worker_ids")) != (WORKER_ID,): _fail("OPERATIONAL_POLICY_WORKER_MISMATCH") expected_oid = execution.get("expected_branch_oid", execution.get("base_oid")) if expected_oid is not None and _policy_value(parsed_policy, "base_oid") != expected_oid: _fail("OPERATIONAL_POLICY_BASE_OID_MISMATCH") policy_json = canonical_json(dict(policy)) policy_sha = _sha_text(policy_json) policy_digest = str(_policy_value(parsed_policy, "digest")) if policy_digest != policy_sha: _fail("OPERATIONAL_POLICY_DIGEST_MISMATCH") binding = { "schema": BINDING_SCHEMA, "task_id": CHILD_TASK_ID, "source_task_id": SOURCE_TASK_ID, "supersession_ordinal": 1, "expected_revision": int(task["revision"]), "metadata_sha256": _sha_text(metadata_raw), "required_capabilities_sha256": _sha_json(sorted(capabilities)), "worker_id": WORKER_ID, "execution_digest": canonical_execution_digest, "canonical_child_execution_digest": canonical_execution_digest, "source_business_execution_digest": SOURCE_BUSINESS_EXECUTION_DIGEST, "repository": REPOSITORY, "target_branch": TARGET_BRANCH, "generation": GENERATION, "external_job_id": EXTERNAL_JOB_ID, "policy_sha256": policy_sha, "policy_digest": policy_digest, "runtime_id": runtime_id, "runtime_observation_digest": runtime_observation_digest, "task_contract_version": task_contract_version, "owner_supersession_decision_sha256": relation["owner_decision_sha256"], } binding_json = canonical_json(binding) binding_sha = _sha_text(binding_json) binding_id = "sha256:" + binding_sha existing = connection.execute( "SELECT binding_sha256 FROM task_claim_guard_bindings_v2 WHERE task_id=?", (CHILD_TASK_ID,) ).fetchone() if existing is not None: if existing[0] != binding_sha: _fail("CLAIM_GUARD_BINDING_ALREADY_EXISTS") receipt = connection.execute( "SELECT receipt_json FROM task_claim_guard_binding_receipts_v2 WHERE binding_id=?", (binding_id,) ).fetchone() if receipt is None: _fail("CLAIM_GUARD_BINDING_RECEIPT_MISSING", 500) return {**json.loads(receipt[0]), "idempotent": True} created_at = now or _now() connection.execute( """INSERT INTO task_claim_guard_bindings_v2( binding_id,task_id,source_task_id,supersession_ordinal,expected_revision, metadata_sha256,required_capabilities_sha256,worker_id,execution_digest, repository,target_branch,generation,policy_json,policy_sha256,binding_json, binding_sha256,created_at) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)""", (binding_id, CHILD_TASK_ID, SOURCE_TASK_ID, 1, binding["expected_revision"], binding["metadata_sha256"], binding["required_capabilities_sha256"], WORKER_ID, canonical_execution_digest, REPOSITORY, TARGET_BRANCH, GENERATION, policy_json, policy_sha, binding_json, binding_sha, created_at), ) receipt = { "schema": RECEIPT_SCHEMA, "status": "BOUND", "binding_id": binding_id, "binding_sha256": binding_sha, "task_id": CHILD_TASK_ID, "expected_revision": binding["expected_revision"], "metadata_sha256": binding["metadata_sha256"], "worker_id": WORKER_ID, "execution_digest": canonical_execution_digest, "canonical_child_execution_digest": canonical_execution_digest, "source_business_execution_digest": SOURCE_BUSINESS_EXECUTION_DIGEST, "repository": REPOSITORY, "target_branch": TARGET_BRANCH, "generation": GENERATION, "owner_supersession_decision_sha256": relation["owner_decision_sha256"], } receipt_sha = _sha_json(receipt) receipt_id = "sha256:" + receipt_sha connection.execute( "INSERT INTO task_claim_guard_binding_receipts_v2 VALUES(?,?,?,?,?,?)", (receipt_id, binding_id, CHILD_TASK_ID, canonical_json(receipt), receipt_sha, created_at), ) return {**receipt, "receipt_id": receipt_id, "receipt_sha256": receipt_sha, "idempotent": False} def _load_child_binding(connection) -> tuple[dict[str, Any], dict[str, Any]]: row = connection.execute( "SELECT * FROM task_claim_guard_bindings_v2 WHERE task_id=?", (CHILD_TASK_ID,) ).fetchone() if row is None: _fail("CHILD_CLAIM_GUARD_BINDING_MISSING") value = _row_dict(row) binding = _json(value["binding_json"], "CLAIM_GUARD_BINDING_INVALID") policy = _json(value["policy_json"], "OPERATIONAL_POLICY_INVALID") relation = connection.execute( "SELECT * FROM task_lineage_supersessions WHERE source_task_id=? " "AND supersession_ordinal=1 AND child_task_id=?", (SOURCE_TASK_ID, CHILD_TASK_ID), ).fetchone() if relation is None: _fail("FORMAL_SUPERSESSION_REQUIRED") projection = _load_projection_evidence(connection, relation) canonical_execution_digest = projection["canonical_child_execution_digest"] if ( _sha_text(value["binding_json"]) != value["binding_sha256"] or binding.get("schema") != BINDING_SCHEMA or value.get("execution_digest") != canonical_execution_digest or binding.get("execution_digest") != canonical_execution_digest or binding.get("canonical_child_execution_digest") != canonical_execution_digest or binding.get("source_business_execution_digest") != SOURCE_BUSINESS_EXECUTION_DIGEST or binding.get("owner_supersession_decision_sha256") != relation["owner_decision_sha256"] or policy.get("execution_plan_sha256") != canonical_execution_digest ): _fail("CLAIM_GUARD_BINDING_DIGEST_MISMATCH") task = connection.execute("SELECT * FROM tasks WHERE task_id=?", (CHILD_TASK_ID,)).fetchone() task = _row_dict(task) if ( task.get("status") != "QUEUED" or int(task.get("revision", -1)) != int(binding["expected_revision"]) or int(task.get("attempt", -1)) != 0 or task.get("claimed_by") is not None or task.get("lease_token_hash") is not None or task.get("lease_expires_at") is not None or _sha_text(task.get("metadata_json", "")) != binding["metadata_sha256"] or task.get("result_json") is not None or task.get("verification_json") is not None ): _fail("CHILD_CLAIM_GUARD_TASK_CAS_MISMATCH") return binding, policy def _run_child_guard(connection, binding, policy_value, agent_id): try: from aios_single_host_operational_authority import OperationalPolicy, OperationalVerifier from aios_singlehost_claim_guard_stage1 import _LiveReader, REGISTRY_PATH from aios_task_claim_guard import ClaimGuard, ClaimGuardError as CoreError except ImportError as exc: raise ClaimGuardBindingError("CLAIM_GUARD_RUNTIME_UNAVAILABLE", 503) from exc policy = OperationalPolicy.from_mapping(policy_value) cfg = { "task_id": CHILD_TASK_ID, "expected_claim_revision": binding["expected_revision"], "task_metadata_sha256": binding["metadata_sha256"], "required_capabilities_sha256": binding["required_capabilities_sha256"], "task_contract_version": binding["task_contract_version"], "worker_id": WORKER_ID, "policy_digest": binding["policy_digest"], "runtime_id": binding["runtime_id"], "runtime_observation_digest": binding["runtime_observation_digest"], } reader = _LiveReader(connection, policy, cfg, now=int(datetime.now(timezone.utc).timestamp())) try: ClaimGuard(policy, OperationalVerifier(REGISTRY_PATH, require_root_owner=True)).validate_in_transaction( reader, task_id=CHILD_TASK_ID, expected_revision=int(binding["expected_revision"]), worker_id=agent_id, ) except CoreError as exc: raise ClaimGuardBindingError(exc.code) from exc def enforce_claim_guard(connection, *, task_id: str, agent_id: str) -> None: """Exact two-lineage dispatcher; unrelated Tasks retain their prior behavior.""" if task_id == SOURCE_TASK_ID: try: from aios_singlehost_claim_guard_stage1 import enforce_claim_guard as frozen_guard except ImportError as exc: raise ClaimGuardBindingError("FROZEN_SOURCE_CLAIM_GUARD_UNAVAILABLE", 503) from exc frozen_guard(connection, task_id=task_id, agent_id=agent_id) return if task_id != CHILD_TASK_ID: return if agent_id != WORKER_ID: _fail("WORKER_ID_MISMATCH", 403) binding, policy = _load_child_binding(connection) _run_child_guard(connection, binding, policy, agent_id)