failproofai 1.0.1 → 1.0.2-beta.0

package/.next/standalone/sdk/python/tests/test_wire_format.py

@@ -0,0 +1,279 @@
+"""The bytes on disk are the product. This file freezes them.
+
+Everything downstream — the daemon that uploads the batch, the ingest handler
+that promotes fields into indexed columns, the dedup key computed over the
+whole payload — consumes exactly the JSON this module produces, and none of it
+is generated from a shared schema. There is no build step that would notice a
+renamed key, no type that spans the boundary, and no non-2xx response when a
+field goes missing: ingest returns 200 and the column is simply NULL.
+
+So the assertions here are deliberately literal. A golden line per event type,
+compared byte for byte, including key ORDER — because `dedup.rs` hashes the
+canonical form of the payload, and a reordering that looks cosmetic here stops
+retried batches collapsing against rows already stored, which shows up as
+silent duplicate events rather than an error.
+
+If one of these fails, the question is never "how do I update the golden". It
+is "what did I just change about the wire format, and who else has to change
+with me".
+"""
+import json
+from dataclasses import dataclass, fields as dataclass_fields
+from datetime import date, datetime, timezone
+from decimal import Decimal
+from enum import Enum
+from pathlib import Path
+from uuid import UUID
+
+import pytest
+
+from failproofai_sdk import _schema
+
+TS = "2026-01-02T03:04:05.678901Z"
+BASE = dict(timestamp=TS, session_id="sess-1", agent_id="agent-1")
+
+# Every event type, fully populated, serialized exactly as `_writer` serializes it.
+GOLDEN = {
+    "tool_use": '{"timestamp": "2026-01-02T03:04:05.678901Z", "session_id": "sess-1", "agent_id": "agent-1", "type": "tool_use", "tool_name": "bash", "tool_call_id": "tc-1", "environment": "prod", "input": {"cmd": "ls"}}',
+    "tool_result": '{"timestamp": "2026-01-02T03:04:05.678901Z", "session_id": "sess-1", "agent_id": "agent-1", "type": "tool_result", "tool_name": "bash", "tool_call_id": "tc-1", "environment": "prod", "output": "ok", "duration_ms": 12}',
+    "model_request": '{"timestamp": "2026-01-02T03:04:05.678901Z", "session_id": "sess-1", "agent_id": "agent-1", "type": "model_request", "environment": "prod", "model": "claude-opus-5", "messages": [{"role": "user"}], "system": "sys", "tools": [{"name": "t"}], "request_id": "req-1"}',
+    "model_response": '{"timestamp": "2026-01-02T03:04:05.678901Z", "session_id": "sess-1", "agent_id": "agent-1", "type": "model_response", "environment": "prod", "model": "claude-opus-5", "stop_reason": "end_turn", "input_tokens": 10, "output_tokens": 20, "content": "hi", "role": "assistant", "request_id": "req-1"}',
+    "agent_start": '{"timestamp": "2026-01-02T03:04:05.678901Z", "session_id": "sess-1", "agent_id": "agent-1", "type": "agent_start", "environment": "prod", "goal": "do it", "parent_id": "p-1"}',
+    "agent_end": '{"timestamp": "2026-01-02T03:04:05.678901Z", "session_id": "sess-1", "agent_id": "agent-1", "type": "agent_end", "environment": "prod", "outcome": "success", "summary": "done"}',
+    "agent_pause": '{"timestamp": "2026-01-02T03:04:05.678901Z", "session_id": "sess-1", "agent_id": "agent-1", "type": "agent_pause", "pause_id": "p-1", "environment": "prod", "reason": "quota", "user_id": "u-1"}',
+    "agent_resume": '{"timestamp": "2026-01-02T03:04:05.678901Z", "session_id": "sess-1", "agent_id": "agent-1", "type": "agent_resume", "pause_id": "p-1", "environment": "prod", "duration_ms": 34, "reason": "ok", "user_id": "u-1"}',
+    "hook_triggered": '{"timestamp": "2026-01-02T03:04:05.678901Z", "session_id": "sess-1", "agent_id": "agent-1", "type": "hook_triggered", "hook_name": "pre", "hook_id": "h-1", "environment": "prod", "trigger_event": "PreToolUse", "input": {"a": 1}}',
+    "hook_completed": '{"timestamp": "2026-01-02T03:04:05.678901Z", "session_id": "sess-1", "agent_id": "agent-1", "type": "hook_completed", "hook_name": "pre", "hook_id": "h-1", "environment": "prod", "outcome": "allow", "output": "o", "duration_ms": 56}',
+    "error": '{"timestamp": "2026-01-02T03:04:05.678901Z", "session_id": "sess-1", "agent_id": "agent-1", "type": "error", "error_type": "ValueError", "message": "boom", "environment": "prod", "traceback": "tb"}',
+    "human_wait": '{"timestamp": "2026-01-02T03:04:05.678901Z", "session_id": "sess-1", "agent_id": "agent-1", "type": "human_wait", "input_id": "i-1", "environment": "prod", "prompt": "ok?", "options": ["y", "n"], "reason": "approval"}',
+    "human_input": '{"timestamp": "2026-01-02T03:04:05.678901Z", "session_id": "sess-1", "agent_id": "agent-1", "type": "human_input", "input_id": "i-1", "environment": "prod", "response": "y", "duration_ms": 78}',
+    "human_pause": '{"timestamp": "2026-01-02T03:04:05.678901Z", "session_id": "sess-1", "agent_id": "agent-1", "type": "human_pause", "environment": "prod", "reason": "lunch", "user_id": "u-1"}',
+    "human_interrupt": '{"timestamp": "2026-01-02T03:04:05.678901Z", "session_id": "sess-1", "agent_id": "agent-1", "type": "human_interrupt", "environment": "prod", "reason": "stop", "user_id": "u-1", "at_step": "3"}',
+}
+
+
+def _events():
+    """One fully-populated instance of every event dataclass."""
+    s = _schema
+    return {
+        "tool_use": s.ToolUseEvent(**BASE, tool_name="bash", tool_call_id="tc-1", input={"cmd": "ls"}),
+        "tool_result": s.ToolResultEvent(**BASE, tool_name="bash", tool_call_id="tc-1", output="ok", error=None, duration_ms=12),
+        "model_request": s.ModelRequestEvent(**BASE, model="claude-opus-5", messages=[{"role": "user"}], system="sys", tools=[{"name": "t"}], request_id="req-1"),
+        "model_response": s.ModelResponseEvent(**BASE, model="claude-opus-5", stop_reason="end_turn", input_tokens=10, output_tokens=20, content="hi", role="assistant", request_id="req-1"),
+        "agent_start": s.AgentStartEvent(**BASE, goal="do it", parent_id="p-1"),
+        "agent_end": s.AgentEndEvent(**BASE, outcome="success", summary="done"),
+        "agent_pause": s.AgentPauseEvent(**BASE, pause_id="p-1", reason="quota", user_id="u-1"),
+        "agent_resume": s.AgentResumeEvent(**BASE, pause_id="p-1", duration_ms=34, reason="ok", user_id="u-1"),
+        "hook_triggered": s.HookTriggeredEvent(**BASE, hook_name="pre", hook_id="h-1", trigger_event="PreToolUse", input={"a": 1}),
+        "hook_completed": s.HookCompletedEvent(**BASE, hook_name="pre", hook_id="h-1", outcome="allow", output="o", error=None, duration_ms=56),
+        "error": s.ErrorEvent(**BASE, error_type="ValueError", message="boom", traceback="tb"),
+        "human_wait": s.HumanWaitEvent(**BASE, input_id="i-1", prompt="ok?", options=["y", "n"], reason="approval"),
+        "human_input": s.HumanInputEvent(**BASE, input_id="i-1", response="y", duration_ms=78),
+        "human_pause": s.HumanPauseEvent(**BASE, reason="lunch", user_id="u-1"),
+        "human_interrupt": s.HumanInterruptEvent(**BASE, reason="stop", user_id="u-1", at_step="3"),
+    }
+
+
+@pytest.fixture(autouse=True)
+def _fixed_environment(monkeypatch):
+    """Pin `environment`, which every event stamps from module state."""
+    monkeypatch.setenv("AGENTEYE_ENVIRONMENT", "prod")
+    from failproofai_sdk import _environment
+
+    monkeypatch.setattr(_environment, "_environment", None)
+
+
+@pytest.mark.parametrize("event_type", sorted(GOLDEN))
+def test_serialized_line_is_byte_for_byte_frozen(event_type):
+    """Key names, key ORDER, and value encoding — all of it is the contract."""
+    event = _events()[event_type]
+    # Exactly how `_writer._write_batch` serializes: default=str, no sort_keys.
+    line = json.dumps(event.to_dict(), default=str)
+    assert line == GOLDEN[event_type]
+
+
+def test_every_schema_dataclass_has_a_golden():
+    """A new event type must arrive with its wire format frozen, not after.
+
+    Without this, adding a dataclass and forgetting the golden leaves the new
+    type's bytes unpinned — and the parametrized test above passes, because it
+    iterates the goldens rather than the schema.
+    """
+    import dataclasses
+    import inspect
+
+    declared = {
+        name
+        for name, obj in inspect.getmembers(_schema, inspect.isclass)
+        if dataclasses.is_dataclass(obj) and name.endswith("Event")
+    }
+    covered = {type(e).__name__ for e in _events().values()}
+    assert declared == covered, (
+        f"schema dataclasses without a golden line: {sorted(declared - covered)}. "
+        "Add the event to _events() and GOLDEN before shipping it — the wire "
+        "format is the one thing nothing downstream will tell you about."
+    )
+    assert len(GOLDEN) == len(declared)
+
+
+def test_type_string_matches_the_key_it_is_registered_under():
+    """`type` is a free string at ingest — no enum, no allowlist, anywhere.
+
+    A typo ingests with HTTP 200 and `accepted: 1`, then never matches a filter.
+    This is the only place that spelling is checked.
+    """
+    for event_type, event in _events().items():
+        assert event.to_dict()["type"] == event_type
+
+
+def test_none_valued_fields_are_omitted_not_serialized_as_null():
+    """Absent means absent. `null` would overwrite a promoted column with NULL."""
+    event = _schema.ToolResultEvent(
+        **BASE, tool_name="bash", tool_call_id="tc-1", output=None, error=None, duration_ms=None
+    )
+    payload = event.to_dict()
+    for absent in ("output", "error", "duration_ms"):
+        assert absent not in payload
+    assert "null" not in json.dumps(payload)
+
+
+def test_the_five_always_present_keys_are_always_present():
+    """ingest.rs rejects a line missing any of the first four; the fifth is filtered on."""
+    for event in _events().values():
+        payload = event.to_dict()
+        for required in ("timestamp", "session_id", "agent_id", "type", "environment"):
+            assert required in payload, f"{type(event).__name__} is missing {required}"
+
+
+def test_every_declared_field_appears_in_its_golden():
+    """A golden that omits a field does not freeze that field.
+
+    `_events()` claims "one fully-populated instance of every event dataclass"
+    and left `request_id` unset on both model events — a real field, emitted by
+    all four framework adapters, and the one `_schema.py` singles out as
+    "appended LAST in `_build`'s ordered list … `test_wire_format.py` freezes
+    those bytes, and the dedup key hashes them". Its key name and its POSITION
+    were unpinned, so reordering it would have changed the content hash of every
+    `model_request` carrying one — retried batches stop collapsing against rows
+    already stored, and duplicates appear — with this whole file green.
+
+    `test_every_schema_dataclass_has_a_golden` compares dataclass NAMES only, so
+    it cannot see this.
+    """
+    missing = []
+    for name, event in _events().items():
+        payload = json.loads(GOLDEN[name])
+        for f in dataclass_fields(event):
+            if f.name in {"extra_fields", "timestamp", "session_id", "agent_id"}:
+                continue
+            if getattr(event, f.name) is None:
+                continue
+            if f.name not in payload:
+                missing.append(f"{name}.{f.name}")
+    assert not missing, (
+        "these fields are set on the fixture but absent from the frozen golden, "
+        f"so their name and position on the wire are unpinned: {sorted(missing)}"
+    )
+
+
+def test_custom_fields_are_merged_last_and_overwrite_a_schema_key_in_place():
+    """Extras land last — and an extra that COLLIDES overwrites the declared value.
+
+    Named for what `_build` actually does. It used to be called
+    `..._cannot_shadow_a_schema_key` and only ever passed two novel names, so the
+    invariant its name promised was never exercised and is false: `_build` ends
+    with `result.update(extra)`, so an extra wins its slot outright.
+
+    `integrations/_core.guard_extras` (via `FORBIDDEN_EXTRAS`) is the sole
+    mitigation and covers only the ADAPTER path; a direct `event.*` call with a
+    colliding custom field reaches this. Frozen here so the behaviour is at least
+    known, and so tightening it later is a deliberate change with a test to
+    update rather than a surprise.
+    """
+    event = _schema.AgentStartEvent(**BASE, goal="g", extra_fields={"trace_id": "abc", "cost": 0.5})
+    payload = event.to_dict()
+    assert payload["trace_id"] == "abc"
+    assert payload["cost"] == 0.5
+    # Insertion order: schema keys first, extras appended.
+    assert list(payload)[-2:] == ["trace_id", "cost"]
+
+    # The collision case, which the old name denied could happen.
+    shadowed = _schema.ToolUseEvent(
+        **BASE, tool_name="bash", tool_call_id="tc-1", extra_fields={"tool_name": 12345}
+    ).to_dict()
+    assert shadowed["tool_name"] == 12345, (
+        "if this now keeps the declared value, `_build` was tightened — update "
+        "this test and say so; the change is a good one"
+    )
+
+
+class _Colour(Enum):
+    RED = "red"
+
+
+@dataclass
+class _Unserializable:
+    x: int
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        datetime(2026, 1, 2, 3, 4, 5, tzinfo=timezone.utc),
+        date(2026, 1, 2),
+        UUID("12345678-1234-5678-1234-567812345678"),
+        Decimal("1.25"),
+        Path("/tmp/x"),
+        _Colour.RED,
+        _Unserializable(x=1),
+        {1, 2, 3},
+        b"bytes",
+    ],
+)
+def test_unserializable_payload_values_are_coerced_never_dropped(value):
+    """`default=str` exists so one exotic value cannot kill the whole batch.
+
+    The writer serializes a batch as a single string. Without the coercion, one
+    `Decimal` in one event raises inside `_write_batch`, the batch is requeued,
+    and the next flush raises on the same value — the queue never drains again
+    and every subsequent event in the process is lost too.
+    """
+    event = _schema.AgentStartEvent(**BASE, extra_fields={"v": value})
+    line = json.dumps(event.to_dict(), default=str)
+    assert json.loads(line)["v"] == str(value)
+
+
+def test_duration_ms_is_serialized_as_an_integer():
+    """A float here silently NULLs the column: the server's `as_u64()` drops it."""
+    for name in ("tool_result", "agent_resume", "hook_completed", "human_input"):
+        payload = _events()[name].to_dict()
+        assert isinstance(payload["duration_ms"], int)
+        assert not isinstance(payload["duration_ms"], bool)
+        assert "." not in json.dumps(payload["duration_ms"])
+
+
+def test_a_batch_is_newline_delimited_with_a_trailing_newline():
+    """The daemon splits on newlines and POSTs the bytes verbatim as x-ndjson."""
+    events = [e.to_dict() for e in list(_events().values())[:3]]
+    content = "\n".join(json.dumps(e, default=str) for e in events) + "\n"
+
+    assert content.endswith("\n")
+    lines = content.split("\n")[:-1]
+    assert len(lines) == 3
+    for line in lines:
+        assert "\n" not in line
+        json.loads(line)
+
+
+def test_no_payload_value_can_smuggle_a_newline_into_the_batch():
+    """One raw newline in a value would split one event into two malformed lines.
+
+    `json.dumps` escapes it, and ingest counts unparseable lines as `skipped`
+    while still returning 200 — so a regression here is silent partial loss.
+    """
+    event = _schema.ErrorEvent(
+        **BASE, error_type="E", message="line one\nline two\r\nline three", traceback=None
+    )
+    line = json.dumps(event.to_dict(), default=str)
+    assert "\n" not in line
+    assert json.loads(line)["message"] == "line one\nline two\r\nline three"

package/.next/standalone/sdk/python/tests/test_zero_dependencies.py

@@ -0,0 +1,378 @@
+"""This SDK imports nothing outside the standard library, and must not start.
+
+It is installed into other people's agent processes. Every dependency we declare
+becomes a version constraint on their application, and a resolver conflict we
+cause is one they have to solve — in the observability library, which is the last
+place anyone wants to spend an afternoon. "Zero dependencies" is the reason it is
+safe to add to an existing project without thinking, so it is a promise rather
+than a coincidence, and a promise needs a test.
+
+The framework adapters under `integrations/` are the one exception, and they do
+not weaken the promise. Each one imports the framework it adapts — there is no
+other way to subclass its callback base class — but they are reached ONLY through
+`instrument()`, which resolves them by string through `importlib.import_module`
+at call time. So `import failproofai_sdk` still touches nothing outside the
+standard library, and an adapter's import can only run in a process where that
+framework was already installed and imported. Both halves of that are asserted
+below, the second by launching a fresh interpreter rather than by reading source.
+
+The declaration and the code are checked separately because they fail
+separately: a stray `import httpx` in a rarely-taken branch is an ImportError in
+the user's process at exactly the wrong moment, and an unused `dependencies`
+entry drags a package into every install for nothing. CI proves the third case
+the source cannot — that the built wheel really installs with `--no-deps`.
+"""
+
+from __future__ import annotations
+
+import ast
+import sys
+
+import pytest
+from pathlib import Path
+
+try:  # Python 3.11+
+    import tomllib
+except ModuleNotFoundError:  # 3.10 — `tomli` is the same parser, from the dev extra
+    # Deliberately not a skip. The manifest assertions below are the enforcement
+    # of the zero-dependency promise, and a promise that stops being checked on
+    # the oldest interpreter we advertise is checked where it matters least.
+    # `tomli` is a TEST dependency; `[project.dependencies]` stays empty, which
+    # is the thing actually being promised.
+    import tomli as tomllib
+
+import failproofai_sdk
+
+PKG = Path(failproofai_sdk.__file__).resolve().parent
+ROOT = PKG.parent
+PYPROJECT = ROOT / "pyproject.toml"
+
+#: Everything the package is allowed to import: the standard library, itself, and
+#: nothing else. `sys.stdlib_module_names` is the interpreter's own list, so this
+#: stays correct across versions instead of being a hand-maintained allowlist.
+ALLOWED = set(sys.stdlib_module_names) | {"failproofai_sdk"}
+
+
+#: Adapters are allowed to import the framework they adapt. Nothing else is, and
+#: this set is deliberately explicit rather than "anything under integrations/":
+#: a new file added there gets scanned like core code until it is named here.
+ADAPTER_IMPORTS = {
+    "langchain.py": {"langchain_core", "langgraph"},
+    "crewai.py": {"crewai"},
+    "llama_index.py": {"llama_index", "llama_index_instrumentation", "pydantic"},
+    "pydantic_ai.py": {"pydantic_ai"},
+}
+
+#: Framework top-level names that must never appear in `sys.modules` after a bare
+#: `import failproofai_sdk`.
+FRAMEWORK_ROOTS = {
+    "langchain", "langchain_core", "langgraph", "crewai",
+    "llama_index", "llama_index_instrumentation", "pydantic", "pydantic_ai",
+}
+
+
+def _module_sources() -> list[Path]:
+    return sorted(p for p in PKG.rglob("*.py") if "__pycache__" not in p.parts)
+
+
+def _allowed_for(path: Path) -> set[str]:
+    """What this module may import beyond the standard library."""
+    if path.parent.name == "integrations":
+        return ALLOWED | ADAPTER_IMPORTS.get(path.name, set())
+    return ALLOWED
+
+
+def _imported_top_level_modules(path: Path) -> set[str]:
+    tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+    modules: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                modules.add(alias.name.split(".")[0])
+        elif isinstance(node, ast.ImportFrom):
+            # A relative import (`from . import x`) has level > 0 and no external
+            # module to check.
+            if node.level == 0 and node.module:
+                modules.add(node.module.split(".")[0])
+    return modules
+
+
+def test_the_package_imports_only_the_standard_library():
+    """Including imports inside functions, which `ast.walk` reaches too.
+
+    `_environment.get_environment` really does `import os` inside the function
+    body, so a check that only read module-level imports would miss a whole class
+    of dependency — the deferred one somebody adds to keep import time down.
+    """
+    offenders: dict[str, set[str]] = {}
+    for path in _module_sources():
+        external = _imported_top_level_modules(path) - _allowed_for(path)
+        if external:
+            offenders[path.name] = external
+
+    assert not offenders, (
+        f"the SDK imports non-stdlib modules: {offenders}. This package is "
+        "installed into other people's agent processes, where every dependency "
+        "we add is a constraint they have to satisfy. If one is genuinely "
+        "unavoidable, it needs a deliberate decision and a `dependencies` entry — "
+        "not an import that fails at runtime in a branch CI never took."
+    )
+
+
+def test_the_scan_found_the_modules_it_was_meant_to_scan():
+    """Guards against the check above passing because it read nothing."""
+    names = {p.name for p in _module_sources()}
+    assert {"_writer.py", "_events.py", "_schema.py", "_resolver.py"} <= names, (
+        f"the package walk found only {sorted(names)}"
+    )
+
+
+def test_no_runtime_dependencies_are_declared():
+    """The manifest half of the same promise."""
+    manifest = tomllib.loads(PYPROJECT.read_text(encoding="utf-8"))
+    declared = manifest["project"].get("dependencies", [])
+    assert declared == [], (
+        f"pyproject declares runtime dependencies: {declared}. Installing this "
+        "SDK must not pull anything in."
+    )
+
+
+#: The only distributions the dev extra may name, each with the reason it is there.
+#: This is an allowlist rather than a count, because the failure it prevents is a
+#: convenience library drifting in — anything here is one `--extra dev` away from a
+#: user's environment, and none of it is covered by the zero-dependency promise.
+ALLOWED_DEV_DEPENDENCIES = {
+    "pytest": "the test runner",
+    "pytest-asyncio": "the adapters are half-async; their scopes are exercised "
+                      "under `async with`, which needs an async test runner",
+    "tomli": "tomllib's backport; Python 3.10 has no stdlib TOML parser, and "
+             "test_zero_dependencies.py must not stop checking the manifest there",
+}
+
+#: Extras that exist only to pull a FRAMEWORK in, mapped to the distribution each
+#: is allowed to name. The adapter code always ships in the base wheel and lazy-
+#: imports, so these gate nothing on our side — they are a convenience for users
+#: who do not already have the framework.
+FRAMEWORK_EXTRAS = {
+    "langchain": {"langchain-core"},
+    "langgraph": {"langgraph"},
+    "crewai": {"crewai", "onnxruntime"},
+    "llamaindex": {"llama-index-core"},
+    "pydantic-ai": {"pydantic-ai-slim"},
+}
+
+
+def _named(spec: str) -> str:
+    """"crewai>=1.13,<2; python_version < '3.11'" -> "crewai"."""
+    head = spec.split(";")[0].strip().split("[")[0]
+    for op in ("===", "~=", "!=", ">=", "<=", "==", ">", "<"):
+        head = head.split(op)[0]
+    return head.strip()
+
+
+def test_dev_dependencies_are_test_only_and_stay_out_of_the_install():
+    """`[project.optional-dependencies].dev` never reaches a plain install."""
+    manifest = tomllib.loads(PYPROJECT.read_text(encoding="utf-8"))
+    extras = manifest["project"].get("optional-dependencies", {})
+    assert set(extras) == {"dev"} | set(FRAMEWORK_EXTRAS), (
+        f"unexpected extras: {sorted(set(extras) - {'dev'} - set(FRAMEWORK_EXTRAS))}"
+    )
+
+    named = {_named(spec) for spec in extras["dev"]}
+    unexpected = named - set(ALLOWED_DEV_DEPENDENCIES)
+    assert not unexpected, (
+        f"the dev extra grew beyond the test tooling: {sorted(unexpected)}. Each "
+        "entry needs a reason in ALLOWED_DEV_DEPENDENCIES, because anything here "
+        "is one `--extra dev` away from a user's environment."
+    )
+
+
+def test_the_package_declares_itself_typed():
+    """`py.typed` must ship, or the annotations are invisible to a type checker."""
+    assert (PKG / "py.typed").is_file()
+    manifest = tomllib.loads(PYPROJECT.read_text(encoding="utf-8"))
+    package_data = manifest["tool"]["setuptools"]["package-data"]
+    assert "py.typed" in package_data["failproofai_sdk"], (
+        "py.typed exists on disk but is not in [tool.setuptools.package-data], so "
+        "it is absent from the built wheel — where it is the only thing that "
+        "makes the type hints count."
+    )
+
+
+def test_importing_the_package_does_not_touch_the_network_or_the_filesystem_eagerly():
+    """Import must be cheap and side-effect-light beyond starting the flush thread.
+
+    Constructing `EventWriter` at module scope already starts a daemon thread,
+    which is a documented cost. Creating directories or reading config at import
+    time would be a further one, paid by every process that imports the package
+    whether or not it emits anything.
+    """
+    # EVERY module, not just `__init__.py`. This read one file and asserted on
+    # `ast.Assign` nodes only — and `__init__.py` has none: the writer and the
+    # namespace moved to `_runtime.py`, whose own docstring says so. So the set
+    # was always empty and `set() <= {...}` could not fail, while the two things
+    # it claimed to guard — import-time work added in `_runtime.py` or any other
+    # imported module, and a bare expression statement like `os.makedirs(...)`,
+    # which is an `ast.Expr` and not an `ast.Assign` — were both invisible to it.
+    # Negative-controlled: a planted `mkdir` + `open()` in `_runtime.py` used to
+    # leave the whole file green.
+    # Each of these is module-level work that IS intended, and each is here
+    # deliberately rather than by a pattern that would also admit a `mkdir`:
+    #
+    #   EventWriter / EventNamespace  the documented cost — starts the flush thread
+    #   count                         `itertools.count()` for the batch sequence
+    #   register                      `atexit.register(_flush_all_at_exit)`
+    #   _Auto                         a sentinel object
+    #   getLogger / frozenset / tuple pure, no I/O
+    #
+    # Adding to this list is the deliberate act. Anything NOT here — a `mkdir`,
+    # an `open`, a config read, a request — is paid by every process that
+    # imports this package, in someone else's agent, whether or not they ever
+    # emit an event.
+    allowed = {
+        "EventWriter",
+        "EventNamespace",
+        "count",
+        "register",
+        "_Auto",
+        "getLogger",
+        "frozenset",
+        "tuple",
+    }
+    offenders: list[str] = []
+    for module in sorted(PKG.glob("*.py")):
+        tree = ast.parse(module.read_text(encoding="utf-8"))
+        for node in tree.body:
+            if isinstance(node, ast.Assign) and isinstance(node.value, ast.Call):
+                call = node.value
+            elif isinstance(node, ast.Expr) and isinstance(node.value, ast.Call):
+                call = node.value
+            else:
+                continue
+            func = call.func
+            name = (
+                func.id
+                if isinstance(func, ast.Name)
+                else (func.attr if isinstance(func, ast.Attribute) else None)
+            )
+            if name is None or name in allowed:
+                continue
+            offenders.append(f"{module.name}:{node.lineno}: {name}()")
+
+    assert not offenders, (
+        "module-level work runs at `import failproofai_sdk`, in someone else's "
+        "agent process, whether or not they ever emit an event:\n  "
+        + "\n  ".join(offenders)
+    )
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# The adapters exist, so laziness is now the load-bearing half
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def test_importing_the_package_loads_no_framework():
+    """The promise, asserted at runtime instead of inferred from the source.
+
+    `integrations/` may import frameworks; what must stay true is that nothing
+    reaches it unless the caller asks. A fresh interpreter is used because this
+    test process has already imported half of everything — checking `sys.modules`
+    in-process would pass on the strength of nobody having imported LangChain yet.
+    """
+    import json
+    import subprocess
+
+    probe = (
+        "import json, sys; import failproofai_sdk; "
+        f"roots = {sorted(FRAMEWORK_ROOTS)!r}; "
+        "print(json.dumps(sorted({m.split('.')[0] for m in sys.modules} & set(roots))))"
+    )
+    result = subprocess.run(
+        [sys.executable, "-c", probe], capture_output=True, text=True, cwd=str(ROOT), timeout=60
+    )
+    assert result.returncode == 0, result.stderr
+    loaded = json.loads(result.stdout.strip())
+    assert loaded == [], (
+        f"`import failproofai_sdk` pulled in {loaded}. The adapters must stay behind "
+        "`instrument()`, which resolves them by string at call time — an eager "
+        "import here is an ImportError in every process that has not installed "
+        "that framework."
+    )
+
+
+def test_the_adapter_registry_holds_strings_not_modules():
+    """`_REGISTRY` maps a name to a dotted path; importing it here would defeat it."""
+    from failproofai_sdk.integrations import _REGISTRY
+
+    assert _REGISTRY, "the adapter registry is empty"
+    for name, target in _REGISTRY.items():
+        assert isinstance(target, str), f"{name} maps to {type(target).__name__}, not a path"
+        assert target.startswith("failproofai_sdk.integrations."), target
+
+
+def test_instrument_on_a_bare_interpreter_installs_nothing_and_does_not_raise():
+    """The realistic first call: no framework installed, `instrument()` anyway.
+
+    It must return an empty result rather than raising — an observability call
+    that explodes because the user has not installed LangChain is worse than one
+    that does nothing.
+    """
+    import subprocess
+
+    probe = (
+        "import failproofai_sdk as f; r = f.instrument(); "
+        "assert r == () or r == [], r; print('ok')"
+    )
+    result = subprocess.run(
+        [sys.executable, "-c", probe], capture_output=True, text=True, cwd=str(ROOT), timeout=60
+    )
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip() == "ok"
+
+
+@pytest.mark.parametrize("extra", sorted(FRAMEWORK_EXTRAS), ids=sorted(FRAMEWORK_EXTRAS))
+def test_a_framework_extra_names_only_its_own_framework(extra):
+    """Each one pulls in a framework and nothing else.
+
+    An extra that quietly added a runtime library would put it in the
+    environment of everyone who typed `failproofai-sdk[langchain]`, which is the
+    zero-dependency promise leaking out through a side door.
+    """
+    manifest = tomllib.loads(PYPROJECT.read_text(encoding="utf-8"))
+    specs = manifest["project"]["optional-dependencies"][extra]
+    assert specs, f"the {extra} extra is empty"
+    assert {_named(s) for s in specs} == FRAMEWORK_EXTRAS[extra]
+
+
+def test_no_extra_refers_back_to_this_package():
+    """A self-referential extra is how a package installs something else over itself.
+
+    On public PyPI `agenteye` is the CLI, which is what made this a real hazard
+    in the SDK's previous home: `agenteye[langchain]` would have pulled the CLI
+    in on top of the SDK. The name is different here; the shape of the mistake is
+    not, and there is deliberately no `[all]` either — an extra that installs
+    four agent frameworks at once is a resolver problem handed to somebody who
+    wanted a telemetry library.
+    """
+    manifest = tomllib.loads(PYPROJECT.read_text(encoding="utf-8"))
+    extras = manifest["project"]["optional-dependencies"]
+    assert "all" not in extras
+    for name, specs in extras.items():
+        for spec in specs:
+            assert _named(spec) not in {"failproofai-sdk", "failproofai_sdk", "agenteye"}, (
+                f"the {name} extra refers back to this package: {spec!r}"
+            )
+
+
+def test_every_framework_extra_has_an_upper_bound():
+    """A ceiling on each, or a clean build a year from now silently stops working.
+
+    The adapters subclass framework callback bases. A new major shifts that API,
+    the adapter stops receiving events, and it raises nothing while doing so —
+    the failure is an empty dashboard, not a traceback.
+    """
+    manifest = tomllib.loads(PYPROJECT.read_text(encoding="utf-8"))
+    extras = manifest["project"]["optional-dependencies"]
+    for name in FRAMEWORK_EXTRAS:
+        for spec in extras[name]:
+            assert "<" in spec, f"{name}: {spec!r} has no upper bound"