srr84/agent-data-layer

1"""Stub-convention self-test. Establishes that the @stub / Stub marker raises2NotImplementedError when reached and is detectable via is_stub(), so the later3no-stub-reachable CI check (AEP §6) has a marker to walk. No stub is on a production path at4M0; this only proves the convention.5 6New reader -> WALKTHROUGH.md (authored at a later milestone).7 8```text9spec traceability (audit map — safe to skip)10AEP §4 (the @stub / Stub-marker NotImplementedError convention), §6 (no-stub-reachable join bar)11```12"""13 14from __future__ import annotations15 16import pytest17 18from agent_data_layer.contracts.stub import Stub, is_stub, stub19 20 21def test_stub_base_raises_on_construction() -> None:22    """A Stub subclass raises NotImplementedError when reached (constructed)."""23 24    class _NotYetBuilt(Stub):25        pass26 27    with pytest.raises(NotImplementedError):28        _NotYetBuilt()29 30 31def test_stub_decorator_raises_when_called() -> None:32    """A @stub-decorated callable raises NotImplementedError when called."""33 34    @stub35    def not_yet_implemented(x: int) -> int:36        return x  # never reached37 38    with pytest.raises(NotImplementedError):39        not_yet_implemented(1)40 41 42def test_is_stub_detects_marker() -> None:43    """is_stub() flags a Stub subclass and a @stub callable; a plain function is not a stub."""44 45    class _S(Stub):46        pass47 48    @stub49    def tagged() -> None:50        return None51 52    def plain() -> None:53        return None54 55    assert is_stub(_S) is True56    assert is_stub(tagged) is True57    assert is_stub(plain) is False58 59 60def test_stub_decorator_preserves_name() -> None:61    """The wrapper keeps the original name so the AEP §6 walker can point at the real seam."""62 63    @stub64    def real_seam_name() -> None:65        return None66 67    assert real_seam_name.__name__ == "real_seam_name"68