agent-tokenops 1.0.1__tar.gz → 2.0.0__tar.gz

{agent_tokenops-1.0.1/src/agent_tokenops.egg-info → agent_tokenops-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-tokenops
-Version: 1.0.1
+Version: 2.0.0
 Summary: Run-aware token governance for agents: budgets, policies and halts on Chronicle and the AgentPlane control plane
 Author: Susheem Koul, Tisha Chawla
 License-Expression: MIT
@@ -124,7 +124,8 @@ Wrap your model call once, then hand the wrapped version to your agent.
 
 ```python
 from tokenops import tokenops_run
-from tokenops.control import Halt, wrap_complete
+from tokenops.capabilities import wrap_complete
+from tokenops.framework import Halt
 from tokenops.providers import complete
 
 GOVERNANCE = {"governance": {
@@ -286,7 +287,9 @@ Only `src/tokenops/` is the installable package. Demos and benches stay under `e
 
 ```
 src/tokenops/              # installable package
-├── control/               # the governors: ledger, policies, wrap_complete, Chronicle hook
+├── framework/             # in-process machinery: ledger, policies, pricing, governor (no network)
+├── capabilities/          # tokenops_run, wrap_complete, the Chronicle hook
+├── interfaces/            # instrument_app, HTTP error mapping
 ├── repositories/          # the control-plane client and the background ledger writer
 ├── providers/             # OpenAI / Anthropic complete dispatch
 └── config/                # packaged default governance

{agent_tokenops-1.0.1 → agent_tokenops-2.0.0}/README.md

@@ -83,7 +83,8 @@ Wrap your model call once, then hand the wrapped version to your agent.
 
 ```python
 from tokenops import tokenops_run
-from tokenops.control import Halt, wrap_complete
+from tokenops.capabilities import wrap_complete
+from tokenops.framework import Halt
 from tokenops.providers import complete
 
 GOVERNANCE = {"governance": {
@@ -245,7 +246,9 @@ Only `src/tokenops/` is the installable package. Demos and benches stay under `e
 
 ```
 src/tokenops/              # installable package
-├── control/               # the governors: ledger, policies, wrap_complete, Chronicle hook
+├── framework/             # in-process machinery: ledger, policies, pricing, governor (no network)
+├── capabilities/          # tokenops_run, wrap_complete, the Chronicle hook
+├── interfaces/            # instrument_app, HTTP error mapping
 ├── repositories/          # the control-plane client and the background ledger writer
 ├── providers/             # OpenAI / Anthropic complete dispatch
 └── config/                # packaged default governance

{agent_tokenops-1.0.1 → agent_tokenops-2.0.0}/pyproject.toml

@@ -116,6 +116,7 @@ mypy_path = "src"
 packages = ["tokenops"]
 ignore_missing_imports = true
 warn_unused_configs = true
+warn_redundant_casts = true
 # Gradual typing: adapters are LangChain-heavy; tighten later.
 exclude = "(?x)(tokenops/adapters/)"
 
@@ -128,6 +129,30 @@ module = [
 ]
 follow_imports = "skip"
 
+# The layered packages are held to `mypy --strict`.
+[[tool.mypy.overrides]]
+module = [
+  "tokenops.framework",
+  "tokenops.framework.*",
+  "tokenops.capabilities",
+  "tokenops.capabilities.*",
+  "tokenops.interfaces",
+  "tokenops.interfaces.*",
+  "tokenops.repositories",
+  "tokenops.repositories.*",
+]
+# `strict = true` is not accepted per module, so the --strict flags are listed.
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+disallow_untyped_calls = true
+disallow_untyped_decorators = true
+disallow_any_generics = true
+check_untyped_defs = true
+no_implicit_optional = true
+warn_return_any = true
+warn_unused_ignores = true
+strict_equality = true
+
 [tool.setuptools.package-dir]
 "" = "src"
 

{agent_tokenops-1.0.1 → agent_tokenops-2.0.0/src/agent_tokenops.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-tokenops
-Version: 1.0.1
+Version: 2.0.0
 Summary: Run-aware token governance for agents: budgets, policies and halts on Chronicle and the AgentPlane control plane
 Author: Susheem Koul, Tisha Chawla
 License-Expression: MIT
@@ -124,7 +124,8 @@ Wrap your model call once, then hand the wrapped version to your agent.
 
 ```python
 from tokenops import tokenops_run
-from tokenops.control import Halt, wrap_complete
+from tokenops.capabilities import wrap_complete
+from tokenops.framework import Halt
 from tokenops.providers import complete
 
 GOVERNANCE = {"governance": {
@@ -286,7 +287,9 @@ Only `src/tokenops/` is the installable package. Demos and benches stay under `e
 
 ```
 src/tokenops/              # installable package
-├── control/               # the governors: ledger, policies, wrap_complete, Chronicle hook
+├── framework/             # in-process machinery: ledger, policies, pricing, governor (no network)
+├── capabilities/          # tokenops_run, wrap_complete, the Chronicle hook
+├── interfaces/            # instrument_app, HTTP error mapping
 ├── repositories/          # the control-plane client and the background ledger writer
 ├── providers/             # OpenAI / Anthropic complete dispatch
 └── config/                # packaged default governance

{agent_tokenops-1.0.1 → agent_tokenops-2.0.0}/src/agent_tokenops.egg-info/SOURCES.txt

@@ -13,42 +13,52 @@ src/tokenops/env.py
 src/tokenops/py.typed
 src/tokenops/adapters/__init__.py
 src/tokenops/adapters/langchain.py
+src/tokenops/capabilities/__init__.py
+src/tokenops/capabilities/chronicle_trace_utils.py
+src/tokenops/capabilities/complete_wrapper.py
+src/tokenops/capabilities/crossing.py
+src/tokenops/capabilities/ledger_writers.py
+src/tokenops/capabilities/run.py
+src/tokenops/capabilities/step_observation.py
+src/tokenops/capabilities/stream_wrapper.py
 src/tokenops/config/__init__.py
 src/tokenops/config/default.yaml
 src/tokenops/config/loader.py
-src/tokenops/control/__init__.py
-src/tokenops/control/attribution.py
-src/tokenops/control/boundary.py
-src/tokenops/control/chronicle_trace_utils.py
-src/tokenops/control/config.py
-src/tokenops/control/context.py
-src/tokenops/control/core.py
-src/tokenops/control/crossing.py
-src/tokenops/control/engine.py
-src/tokenops/control/http.py
-src/tokenops/control/instrument.py
-src/tokenops/control/integration.py
-src/tokenops/control/ledger.py
-src/tokenops/control/ledger_writers.py
-src/tokenops/control/models.py
-src/tokenops/control/policy_labels.py
-src/tokenops/control/pricing.py
-src/tokenops/control/request_context.py
-src/tokenops/control/run.py
-src/tokenops/control/usage.py
-src/tokenops/control/policies/__init__.py
-src/tokenops/control/policies/_util.py
-src/tokenops/control/policies/concurrency_cap.py
-src/tokenops/control/policies/context_compaction.py
-src/tokenops/control/policies/cost_budget.py
-src/tokenops/control/policies/cost_guard.py
-src/tokenops/control/policies/output_runaway.py
-src/tokenops/control/policies/pre_call_worst_case.py
-src/tokenops/control/policies/progress_guard.py
-src/tokenops/control/policies/step_cap.py
-src/tokenops/control/policies/time_budget.py
-src/tokenops/control/policies/tool_fix.py
-src/tokenops/control/policies/tool_output_cap.py
+src/tokenops/framework/__init__.py
+src/tokenops/framework/attribution.py
+src/tokenops/framework/boundary.py
+src/tokenops/framework/budget.py
+src/tokenops/framework/config.py
+src/tokenops/framework/context.py
+src/tokenops/framework/core.py
+src/tokenops/framework/engine.py
+src/tokenops/framework/ledger.py
+src/tokenops/framework/ledger_backend.py
+src/tokenops/framework/ledger_events.py
+src/tokenops/framework/ledger_types.py
+src/tokenops/framework/message_steering.py
+src/tokenops/framework/models.py
+src/tokenops/framework/observation_utils.py
+src/tokenops/framework/policy_labels.py
+src/tokenops/framework/pricing.py
+src/tokenops/framework/request_context.py
+src/tokenops/framework/usage.py
+src/tokenops/framework/policies/__init__.py
+src/tokenops/framework/policies/_util.py
+src/tokenops/framework/policies/concurrency_cap.py
+src/tokenops/framework/policies/context_compaction.py
+src/tokenops/framework/policies/cost_budget.py
+src/tokenops/framework/policies/cost_guard.py
+src/tokenops/framework/policies/output_runaway.py
+src/tokenops/framework/policies/pre_call_worst_case.py
+src/tokenops/framework/policies/progress_guard.py
+src/tokenops/framework/policies/step_cap.py
+src/tokenops/framework/policies/time_budget.py
+src/tokenops/framework/policies/tool_fix.py
+src/tokenops/framework/policies/tool_output_cap.py
+src/tokenops/interfaces/__init__.py
+src/tokenops/interfaces/http.py
+src/tokenops/interfaces/instrument.py
 src/tokenops/providers/__init__.py
 src/tokenops/providers/anthropic.py
 src/tokenops/providers/factory.py
@@ -77,10 +87,10 @@ tests/test_cost_guard.py
 tests/test_cross_process_budget_gating.py
 tests/test_crossing_hook.py
 tests/test_demo.py
-tests/test_deprecated_names.py
 tests/test_governance_event_names.py
 tests/test_httpx_instrumentation.py
 tests/test_integration.py
+tests/test_layering.py
 tests/test_ledger.py
 tests/test_llm_boundary_precall.py
 tests/test_output_runaway.py

{agent_tokenops-1.0.1 → agent_tokenops-2.0.0}/src/tokenops/__init__.py

@@ -11,38 +11,38 @@ def init() -> None:
     """Process bootstrap: install the Chronicle crossing hook (idempotent).
 
     Prefer calling this (or :meth:`ControlPlaneClient.from_env` /
-    :func:`~tokenops.control.instrument.instrument_app`) on agent startup so
-    callers need not remember :func:`~tokenops.control.crossing.install_crossing_hook`.
+    :func:`~tokenops.interfaces.instrument.instrument_app`) on agent startup so
+    callers need not remember :func:`~tokenops.capabilities.crossing.install_crossing_hook`.
     """
-    from tokenops.control.crossing import install_crossing_hook
+    from tokenops.capabilities.crossing import install_crossing_hook
 
     install_crossing_hook()
 
 
 # First-class SDK surface for agents / UIs talking to the plane.
-from tokenops.control.instrument import instrument_app as instrument_app
-from tokenops.control.ledger_writers import flush_ledger_writes as flush_ledger_writes
-from tokenops.control.request_context import (
+from tokenops.capabilities.ledger_writers import flush_ledger_writes as flush_ledger_writes
+from tokenops.capabilities.run import (
+    TokenOpsBound as TokenOpsBound,
+)
+from tokenops.capabilities.run import (
+    agentplane_run_scope as agentplane_run_scope,
+)
+from tokenops.capabilities.run import (
+    tokenops_run as tokenops_run,
+)
+from tokenops.framework.request_context import (
     RequestContext as RequestContext,
 )
-from tokenops.control.request_context import (
+from tokenops.framework.request_context import (
     bind_request_context as bind_request_context,
 )
-from tokenops.control.request_context import (
+from tokenops.framework.request_context import (
     clear_request_context as clear_request_context,
 )
-from tokenops.control.request_context import (
+from tokenops.framework.request_context import (
     current_request_context as current_request_context,
 )
-from tokenops.control.run import (
-    TokenOpsBound as TokenOpsBound,
-)
-from tokenops.control.run import (
-    agentplane_run_scope as agentplane_run_scope,
-)
-from tokenops.control.run import (
-    tokenops_run as tokenops_run,
-)
+from tokenops.interfaces.instrument import instrument_app as instrument_app
 from tokenops.repositories import ControlPlaneClient as ControlPlaneClient
 
 __all__ = [

{agent_tokenops-1.0.1 → agent_tokenops-2.0.0}/src/tokenops/_version.py

@@ -1,3 +1,3 @@
 """Single source of the package version (read by the build backend and at runtime)."""
 
-__version__ = "1.0.1"
+__version__ = "2.0.0"

agent_tokenops-2.0.0/src/tokenops/capabilities/__init__.py

@@ -0,0 +1,32 @@
+"""The capabilities layer: governed-run workflows.
+
+Opens runs (:func:`tokenops_run`), wraps model calls (:func:`wrap_complete`), and installs the
+Chronicle crossing hook that feeds the governor. Importing this package registers the hook on
+``chronicle.default_hooks`` for the whole process.
+"""
+
+from tokenops.capabilities.complete_wrapper import wrap_complete
+from tokenops.capabilities.crossing import install_crossing_hook, on_crossing
+from tokenops.capabilities.ledger_writers import flush_ledger_writes
+from tokenops.capabilities.run import TokenOpsBound, agentplane_run_scope, tokenops_run
+from tokenops.capabilities.step_observation import make_on_step, step_to_observation
+from tokenops.capabilities.stream_wrapper import wrap_stream
+from tokenops.framework.message_steering import apply_carry_to_messages, consume_carry
+
+# Process-wide: register the governor hook on chronicle.default_hooks (inherited by every session).
+install_crossing_hook()
+
+__all__ = [
+    "TokenOpsBound",
+    "agentplane_run_scope",
+    "apply_carry_to_messages",
+    "consume_carry",
+    "flush_ledger_writes",
+    "install_crossing_hook",
+    "make_on_step",
+    "on_crossing",
+    "step_to_observation",
+    "tokenops_run",
+    "wrap_complete",
+    "wrap_stream",
+]

{agent_tokenops-1.0.1/src/tokenops/control → agent_tokenops-2.0.0/src/tokenops/capabilities}/chronicle_trace_utils.py

@@ -2,7 +2,7 @@
 
 A run is a Chronicle trace: its only identifier is ``trace_id``. A hop arrives with the
 caller's ``traceparent`` and joins that trace; the entry hop starts a new one. This module is
-the single place that reads the active Chronicle span, so the rest of ``tokenops.control``
+the single place that reads the active Chronicle span, so the rest of TokenOps
 never touches Chronicle's session.
 
 ``chronicle.current_session`` (Chronicle 1.1) reads the active session without opening one;

agent_tokenops-2.0.0/src/tokenops/capabilities/complete_wrapper.py

@@ -0,0 +1,131 @@
+"""``wrap_complete``: govern a ``complete(provider, model, messages)`` entry point.
+
+Pre-call governance (MUTATE / HALT / RETRY) happens here; the dispatch itself goes through
+Chronicle ``wrap_llm`` so the LIVE record and ``on_crossing`` fire. The TokenOps crossing hook
+projects crossings into ``Governor.observe``: do not also ``emit_observation`` here, or the
+call is billed twice.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from chronicle import wrap_llm
+
+from tokenops.capabilities.crossing import (
+    install_crossing_hook,
+    reset_wrap_owns_precall,
+    wrap_owns_precall,
+)
+from tokenops.framework.core import Attribution, CallRequest
+from tokenops.framework.engine import ApplyControls, Governor
+from tokenops.framework.message_steering import (
+    compact_messages,
+    consume_carry,
+    estimate_input_tokens,
+)
+
+__all__ = ["DispatchFn", "policy_metadata", "tighten_cap", "wrap_complete"]
+
+#: A dispatch callable: (provider, model, messages, max_output_tokens) -> response.
+DispatchFn = Callable[..., object]
+
+_RETRY_BASE_CAP = 512
+
+
+def tighten_cap(cap: int | None) -> int:
+    """RETRY tightens the output cap each attempt (halve, floor 64)."""
+    return max(64, (cap or _RETRY_BASE_CAP) // 2)
+
+
+def policy_metadata(controls: ApplyControls) -> Callable[[object], dict[str, int]]:
+    """Envelope metadata for what a policy did to this call.
+
+    The plane stores no per-policy statistics (control-plane ADR 0009), so what a policy
+    achieved is recorded on the envelope instead: ``tokenops.compaction_tokens_before``,
+    ``..._tokens_after`` and ``..._tokens_saved`` when ``context_compaction`` rewrote the
+    prompt. Read after the dispatch returns, so ``controls.call`` is this call's.
+    """
+
+    def extract(_result: object) -> dict[str, int]:
+        call = getattr(controls, "call", None)
+        compaction = getattr(call, "compaction", None) if call is not None else None
+        if not compaction:
+            return {}
+        return {f"tokenops.compaction_{key}": int(value) for key, value in compaction.items()}
+
+    return extract
+
+
+def wrap_complete(
+    governor: Governor,
+    controls: ApplyControls,
+    attr: Attribution,
+    *,
+    provider: str,
+    model: str,
+    dispatch: DispatchFn,
+    est_input_fn: Callable[[object], int] | None = None,
+    service: str = "",
+    max_call_retries: int = 3,
+) -> Callable[[str, str, Any], object]:
+    """Wrap a ``complete(provider, model, messages)`` entry point for **pre_call** governance
+    and the **RETRY** actuator.
+
+    Dispatch is traced via Chronicle ``wrap_llm`` (LIVE envelope + ``on_crossing``).
+    TokenOps observes through the crossing hook, not a second ``emit_observation``.
+
+    After each traced dispatch, ``output_runaway`` may set ``controls.retry``; the call is
+    re-issued with a tighter output cap and raised frequency/presence penalties, bounded
+    by ``max_call_retries`` and by the policy's own retry budget (INJECT once exhausted).
+    """
+    install_crossing_hook()
+    estimate = est_input_fn or estimate_input_tokens
+    seg = f"trace:{attr.trace_id}"
+    boundary_id = f"{service or attr.agent}.chat"
+    traced = wrap_llm(
+        boundary_id, dispatch, provider=provider, extract_metadata=policy_metadata(controls)
+    )
+    controls.compaction_supported = True  # wrap_complete IS the prompt-assembly hook
+
+    def governed(p: str, m: str, messages: Any) -> object:
+        owns = wrap_owns_precall(True)
+        try:
+            controls.begin_call()
+            request = CallRequest(
+                attr=attr,
+                provider=provider,
+                model=m,
+                estimated_input_tokens=estimate(messages),
+                max_output_tokens=controls.call.max_output_tokens,
+            )
+            governor.pre_call(request)
+
+            use_model = controls.call.model_override or m
+            messages = consume_carry(controls, messages)
+            if controls.call.compact:  # deep prompt compaction
+                messages, compaction = compact_messages(messages, estimate=estimate)
+                controls.call.compaction = compaction
+
+            governor.ledger.admit(seg)
+            try:
+                cap = controls.call.max_output_tokens
+                penalties: dict[str, float] = {}
+                attempt = 0
+                while True:
+                    controls.retry = False
+                    # Chronicle records + on_crossing → Governor.observe (when bound)
+                    response = traced(p, use_model, messages, max_output_tokens=cap, **penalties)
+                    if controls.retry and attempt < max_call_retries:
+                        attempt += 1
+                        cap = tighten_cap(cap)
+                        penalties = {"frequency_penalty": 1.0, "presence_penalty": 0.6}
+                        continue
+                    return response
+            finally:
+                governor.ledger.complete(seg)
+        finally:
+            reset_wrap_owns_precall(owns)
+
+    return governed

{agent_tokenops-1.0.1/src/tokenops/control → agent_tokenops-2.0.0/src/tokenops/capabilities}/crossing.py

@@ -35,7 +35,7 @@ def reset_wrap_owns_precall(token: Any) -> None:
 
 
 def _service_name() -> str:
-    from tokenops.control.context import current_span
+    from tokenops.framework.context import current_span
 
     span = current_span()
     return span.service if span else "unknown"
@@ -57,8 +57,8 @@ def on_enter(info: CallInfo) -> dict[str, Any] | None:
     if _kind(info) != "llm" or _wrap_owns_precall.get():
         return None
 
-    from tokenops.control.context import current_governance, current_hop
-    from tokenops.control.core import CallRequest
+    from tokenops.framework.context import current_governance, current_hop
+    from tokenops.framework.core import CallRequest
 
     gov_ctx = current_governance()
     if gov_ctx is None or current_hop() is None:
@@ -111,7 +111,7 @@ def on_enter(info: CallInfo) -> dict[str, Any] | None:
 def on_leave(info: CallInfo) -> None:
     """Release inflight admit from :func:`on_enter` (success or failure)."""
     del info
-    from tokenops.control.context import current_governance
+    from tokenops.framework.context import current_governance
 
     seg = _inflight_seg.get()
     if not seg:
@@ -126,8 +126,8 @@ def on_leave(info: CallInfo) -> None:
 
 def on_crossing(info: CallInfo, result: Any) -> None:
     """Project crossing → Observation when a hop attribution + governance are bound."""
-    from tokenops.control.boundary import emit_observation, observation_from_crossing
-    from tokenops.control.context import current_governance, current_hop
+    from tokenops.framework.boundary import emit_observation, observation_from_crossing
+    from tokenops.framework.context import current_governance, current_hop
 
     if current_governance() is None or current_hop() is None:
         return

{agent_tokenops-1.0.1/src/tokenops/control → agent_tokenops-2.0.0/src/tokenops/capabilities}/ledger_writers.py

@@ -15,20 +15,15 @@ from tokenops.repositories import ControlPlaneClient, LedgerEventWriter
 _LOCK = threading.Lock()
 # Keeps the client referenced so its id() cannot be reused while its writer is alive.
 _WRITERS: dict[int, tuple[ControlPlaneClient, LedgerEventWriter]] = {}
-_ATEXIT_REGISTERED = False
 
 
 def writer_for(client: ControlPlaneClient) -> LedgerEventWriter:
     """The shared writer for ``client`` (created on first use)."""
-    global _ATEXIT_REGISTERED
     with _LOCK:
         entry = _WRITERS.get(id(client))
         if entry is None:
             entry = (client, LedgerEventWriter(client))
             _WRITERS[id(client)] = entry
-            if not _ATEXIT_REGISTERED:
-                atexit.register(flush_ledger_writes)
-                _ATEXIT_REGISTERED = True
         return entry[1]
 
 
@@ -37,3 +32,8 @@ def flush_ledger_writes(timeout: float = 5.0) -> bool:
     with _LOCK:
         writers = [w for _, w in _WRITERS.values()]
     return all([w.flush(timeout) for w in writers])
+
+
+# Registered once at import; a no-op until a writer exists, so a short script does not lose
+# its last spend.
+atexit.register(flush_ledger_writes)

{agent_tokenops-1.0.1/src/tokenops/control → agent_tokenops-2.0.0/src/tokenops/capabilities}/run.py

@@ -24,27 +24,27 @@ from contextlib import contextmanager
 from dataclasses import dataclass
 from typing import Any
 
-from tokenops.control.attribution import _build_attribution, merge_hop_dims
-from tokenops.control.chronicle_trace_utils import chronicle_span
-from tokenops.control.config import build_governance_stack, build_governor
-from tokenops.control.context import (
+from tokenops.capabilities.chronicle_trace_utils import chronicle_span
+from tokenops.capabilities.crossing import install_crossing_hook
+from tokenops.capabilities.ledger_writers import writer_for
+from tokenops.framework.attribution import _build_attribution, merge_hop_dims
+from tokenops.framework.config import build_governance_stack, build_governor
+from tokenops.framework.context import (
     SpanContext,
     _governance_scope,
     bind_hop,
     bind_span,
     run_scope,
 )
-from tokenops.control.context import (
+from tokenops.framework.context import (
     clear as clear_run_context,
 )
-from tokenops.control.core import Attribution
-from tokenops.control.crossing import install_crossing_hook
-from tokenops.control.engine import ApplyControls, Governor, PreviewControls
-from tokenops.control.ledger import PriceFn
-from tokenops.control.ledger_writers import writer_for
-from tokenops.control.models import GovernanceMode, HopAttribution, parse_governance_mode
-from tokenops.control.pricing import build_price_book
-from tokenops.control.request_context import current_request_context
+from tokenops.framework.core import Attribution
+from tokenops.framework.engine import ApplyControls, Governor, PreviewControls
+from tokenops.framework.ledger import PriceFn
+from tokenops.framework.models import GovernanceMode, HopAttribution, parse_governance_mode
+from tokenops.framework.pricing import build_price_book
+from tokenops.framework.request_context import current_request_context
 from tokenops.repositories import ControlPlaneClient
 
 logger = logging.getLogger("tokenops.run")
@@ -61,11 +61,6 @@ class TokenOpsBound:
     controls: ApplyControls | PreviewControls
     client: ControlPlaneClient | None
 
-    @property
-    def registration(self) -> HopAttribution:
-        """Deprecated alias of ``hop``."""
-        return self.hop
-
 
 def _resolve_ambient(
     *,
@@ -162,7 +157,7 @@ def tokenops_run(
 ) -> Iterator[TokenOpsBound]:
     """One hop under a governed trace: join the trace, bind span + governance.
 
-    Happy path (with :func:`~tokenops.control.instrument.instrument_app`)::
+    Happy path (with :func:`~tokenops.interfaces.instrument.instrument_app`)::
 
         with tokenops_run():
             ...