"""Canonical implementation delivery adoption boundary.

The caller owns the authenticated transport and all push/readback invariants.
This module only gates that transport on fresh delegation evidence.
"""
from __future__ import annotations

import re

_SHA40 = re.compile(r"^[0-9a-f]{40}$")


class AdoptionError(ValueError):
    pass


def require_adoption(declaration, *, expected_source, expected_stage):
    try:
        import sys
        from pathlib import Path
        repo_root = Path(__file__).resolve().parents[6]
        if str(repo_root) not in sys.path:
            sys.path.insert(0, str(repo_root))
        from harness.lib.delegation_adoption import require_adoption as checker
    except Exception as exc:
        raise AdoptionError("delegation adoption unavailable") from exc
    try:
        return checker(declaration, expected_source=expected_source, expected_stage=expected_stage)
    except Exception as exc:
        raise AdoptionError("delegation adoption rejected") from exc


def deliver(adapter, *, head, declaration):
    if not callable(adapter):
        raise AdoptionError("trusted delivery adapter required")
    if type(head) is not str or not _SHA40.fullmatch(head):
        raise AdoptionError("invalid delivery head")
    # Keep this immediately before the external-write callback: evidence must be fresh.
    require_adoption(declaration, expected_source={"kind": "git_tree", "revision": head},
                     expected_stage="implementation-delivery")
    return adapter()