poseres 0.1.0__py3-none-any.whl

poseres-0.1.0.dist-info/METADATA

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: poseres
+Version: 0.1.0
+Summary: Pose Resolution Architecture — validation harness and batched in-memory core
+Author: Daan Gerits
+License: MIT
+Project-URL: Homepage, https://github.com/impire-io/poseres
+Project-URL: Source, https://github.com/impire-io/poseres
+Project-URL: Bug Tracker, https://github.com/impire-io/poseres/issues
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.4
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# PRA — Pose Resolution Architecture
+
+An in-memory, batched, deterministic core (PRA-01) and the validation harness
+(PRA-02) that runs the acceptance suite **T1–T6** plus the investigatory
+**T-SCALE**, emitting an honest, reproducible PASS/FAIL verdict per test.
+
+See `specs/001-validation-harness/` for the spec, plan, and contracts, and
+`design/` for the architecture documents. The behavioral oracle is
+`design/validate/pra_sim_v4.py`.
+
+## Quickstart
+
+**Fastest — install from PyPI with [`uv`](https://docs.astral.sh/uv/):**
+
+```bash
+uvx --from poseres pra-validate suite
+```
+
+No Python version juggling, no venv to manage. `uv` fetches Python 3.13 automatically if you don't have it.
+
+**From source:**
+
+```bash
+git clone https://github.com/impire-io/poseres.git
+cd pra
+python3.13 -m venv .venv
+source .venv/bin/activate          # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"            # numpy + pytest + ruff
+
+pra-validate suite                 # 8 seeds, true_dim=3, checkpoints 18/30/50
+pra-validate suite --json out/report.json
+pra-validate determinism --seed 1  # byte-identical re-run check
+pra-validate scale --true-dims 20,35,50
+pra-validate scan --true-dim 20 --hidden-sizes 12,32,64   # diagnostic dimension scan
+pra-validate agency                # curious vs random (T7) + value-signal telemetry
+
+ruff format --check . && ruff check . && pytest -q
+```
+
+Independent seeds run in parallel worker processes by default (`--workers`,
+0 = one per seed up to the CPU count) — parallelism never changes results
+(byte-identical to sequential; each run keeps its own seeded, single-threaded
+pipeline). The full default suite runs in ~20s on a 14-core machine.
+
+`suite` emits, for each of **T1–T6**, the measured aggregate (mean ± std), the
+exact pass criterion, and PASS/FAIL. **T4** is shown as the full per-seed `best_dim`
+spread at every horizon checkpoint and PASSes only if the within-one-of-true
+majority holds at *every* checkpoint — it can never pass on a lucky single horizon.
+**T5** PASSes only when the population genuinely self-limits (no seed strictly
+growing over its final third), not merely because it hit a cap. A single-seed run is
+labelled **FOR DEBUGGING ONLY**. Exit code is 0 even when a test FAILs (a FAIL is
+data, not a CLI error) unless `--strict` is passed.
+
+## Governing principle — honest summary
+
+Where a tidy report and a faithful one conflict, the faithful one wins (FR-008): a
+failing test is shown as FAIL *with the numbers that explain it*; a test needing a
+spread is never reported by its mean alone; a seed that errors is surfaced and the
+aggregate flagged incomplete, never silently dropped; too few samples reads
+"not available", never a fabricated number. Two runs of a seed produce
+byte-identical telemetry (single seeded RNG, fixed draw order, single-threaded BLAS).
+
+## Layout
+
+```
+src/pra/
+  config.py            # every PRA-01 §8 parameter + validation
+  world/event_source.py# EventSource seam + SensorimotorWorld (nonlinear, hidden latent)
+  core/                # contracts, bus, scorer, policies, the batched FrameGroup kernel, engine
+  motivation/          # Drive seam: curiosity (learning progress + novelty), weighted drive set
+  action/              # Policy seam: pinned random baseline + one-step curiosity lookahead
+  persistence/         # snapshot/restore: versioned blob + atomic SnapshotStore (opt-in)
+  anatomy/             # body: sensors/actuators, fixed-order composition, runtime tools
+  telemetry/recorder.py# deterministic per-seed summary
+  harness/             # acceptance (T1-T7/T-SCALE), runner, report, cli, scale, scan, agency
+tests/                 # unit (incl. batched-vs-reference proof) / contract (5 seams) / integration
+```
+
+## Behavioral oracle
+
+`design/validate/pra_sim_v4.py` is the validated reference run. The batched core
+reproduces its T1–T6 trajectory at the default config (the per-frame-vs-batched
+equivalence is enforced by `tests/unit/test_batched_equivalence.py`) at roughly 40×
+the speed. The full default suite (8 seeds × predictive + ablation × 50 cycles)
+completes in well under a minute.

poseres-0.1.0.dist-info/RECORD

@@ -0,0 +1,37 @@
+poseres-0.1.0.dist-info/licenses/LICENSE,sha256=2TJLWeXZgjoZoyQn14F9IKVTYFWSN5TNABdaTbevirk,1068
+pra/__init__.py,sha256=VgfH2mN3NC_Q8Qh354D0cCEt3bv9SURVArHY3WupGlo,852
+pra/config.py,sha256=65umA2SKg6ZSjnhbOl16M9NTSGFGVSo2lT5C3WPigRc,10219
+pra/action/__init__.py,sha256=xSTczHw4xega8s6fBJmCQQoKHNewi4siuF9HJgwsAw8,77
+pra/action/policy.py,sha256=0FeMAYFaL8zFAJeOM2h7wStnCZ2ReSi4XjsEQoYwC7g,3784
+pra/anatomy/__init__.py,sha256=2oym5Doy3SGt6nBm3BtFrFlns46LBN25NFeq5q8TRrw,87
+pra/anatomy/body.py,sha256=1krAGEjdcexuQNuSh4W2fAJwXIu2QtO-FPaE-IMq56o,8722
+pra/core/__init__.py,sha256=2glkRw3R0f6HCB93PKRAr_Ix9muqryjH2A-ayvHsrOQ,23
+pra/core/bus.py,sha256=FvksrC1Is8E3THKlYco4zLjX1L9JbnOydKxWgjL4DAc,2899
+pra/core/contracts.py,sha256=9ujNBGPZOf-SuWuQSqihDSjqqYYeWl6hl9qMaCHkE1M,3078
+pra/core/engine.py,sha256=zrqmr0Pe7MECkfWqVD-r0ohbOef1nojckAShCEveFe0,22288
+pra/core/frame.py,sha256=E-YnQWYfV9hFcgWgM5i5zU8eF8UQt5Uc_-pYiUWRfKY,22707
+pra/core/policies.py,sha256=YRBQwJ4xbnSB1eJ38wI9UnbSVSmaQIizvBUZzf7Uryk,5415
+pra/core/scorer.py,sha256=MdnwFq_KRKzNZ5wAijbdoCviq0XeGlj5cFI7-wNzwuc,2086
+pra/harness/__init__.py,sha256=kOeRN008vQTuaAhAVkEVnnH37rfRKgLLfuvyDCTSgvw,26
+pra/harness/acceptance.py,sha256=2iXDQvSEpLcM3srJz9p8xKdepgxSQi55sk-vJkYYEbU,11533
+pra/harness/agency.py,sha256=PJPo2T2f8nKjvwdiAxdxCM9BwIgtCppgm2a6JVw3JgA,3356
+pra/harness/cli.py,sha256=TNWYdL2U8einiLs_ypf1eFkak8Pr0LNpsXrdOwmG0N4,9515
+pra/harness/report.py,sha256=u3mimAzPzC8bipPuiHZVcdVQChxN2dCpLDDX0fNAofU,11275
+pra/harness/runner.py,sha256=m6DYbPUUdWuzXRCO3TpbvJ4uxuj895J-JdP1HyZ_SSc,6090
+pra/harness/scale.py,sha256=t0hFpIORQBYdxO8AmsGgg2_QFu7jRG-EMzesRK--9X4,3450
+pra/harness/scan.py,sha256=tI2NqBzV4fuC-etdlsW15I5gMcs5rHJtIt0rlxHe5Ew,6805
+pra/motivation/__init__.py,sha256=UTEQitGfIA-2zzsRm10mfbPZMRbUYlKHpZPEyG9JYks,89
+pra/motivation/context.py,sha256=-8HitQDLb_ZGWj5YNLWBwEutlIYbm_V3GsKk-cQP4KI,864
+pra/motivation/drive.py,sha256=GpclfY2bpsz-kozVZKJnIfu8ilJRNvpDCuuKBgJsuEk,7869
+pra/persistence/__init__.py,sha256=e1Oa3duMZvd-MLERvd2begHGPl6WuUSVuV4B0qT5xoM,84
+pra/persistence/snapshot.py,sha256=0aoixV5hfhcrdHCbZkYqopyA98Vmheo6yE-oMm8LIME,8035
+pra/persistence/store.py,sha256=1pDW2HH7jYr1BKLyJ8jjK_pYs3UpVn7VX3DPVq9Lud8,4250
+pra/telemetry/__init__.py,sha256=y_mFAGPqwgVhMcEiiolzekOljXzk-LnRejbPNcmvix0,28
+pra/telemetry/recorder.py,sha256=_uKYhJxkc4ly9jtFrDU-IwICd0NDuDW2Ek-6C6aWs9g,5896
+pra/world/__init__.py,sha256=VBvm1OgaNMZ_ZIZkADuQuNNpnhQMWORHnzIN8pr-8qc,24
+pra/world/event_source.py,sha256=1rpzg4KWqMMhb_0uagVBL2MWQABRhYNGoZwNm738IjY,4182
+poseres-0.1.0.dist-info/METADATA,sha256=InZpH9zV8FTAwgIltpXEaBT6F5PQOxCG5nGVPGd4ZN8,4776
+poseres-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+poseres-0.1.0.dist-info/entry_points.txt,sha256=lGENmtLfYkWBegh7Eo9Qi4DwftVN4qx2N3O9bVIDJKw,54
+poseres-0.1.0.dist-info/top_level.txt,sha256=Ap6zJD_aM-94A7oOusQX4WWF1D4Dv0HHmwjAFAqjZoc,4
+poseres-0.1.0.dist-info/RECORD,,

poseres-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

poseres-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pra-validate = pra.harness.cli:main

poseres-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daan Gerits
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

poseres-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pra

pra/__init__.py

@@ -0,0 +1,26 @@
+"""Pose Resolution Architecture (PRA).
+
+A single in-memory, batched, deterministic core (PRA-01) plus the validation
+harness (PRA-02) that runs the acceptance suite T1-T6 and the investigatory
+T-SCALE.
+
+Determinism (FR-010, SC-007, PRA-01 §7.1) requires a fixed float-accumulation
+order. We pin every BLAS backend to a single thread *before* numpy is imported
+anywhere in the process, so reductions are byte-stable across runs on one
+machine. This module is imported before any ``pra`` submodule pulls in numpy.
+"""
+
+import os as _os
+
+# Pin BLAS threading before numpy is first imported (PRA-01 §7.1, research R3).
+for _var in (
+    "OMP_NUM_THREADS",
+    "OPENBLAS_NUM_THREADS",
+    "MKL_NUM_THREADS",
+    "VECLIB_MAXIMUM_THREADS",
+    "NUMEXPR_NUM_THREADS",
+):
+    _os.environ.setdefault(_var, "1")
+
+__all__ = ["__version__"]
+__version__ = "0.1.0"

pra/action/__init__.py

@@ -0,0 +1 @@
+"""Action component (design Doc 05 §4): policy seam -> action selection."""

pra/action/policy.py

@@ -0,0 +1,98 @@
+"""Policies: action selection (Doc 05 §4).
+
+The Policy seam replaces the engine's inline random action draw. The default
+``RandomPolicy`` reproduces that draw EXACTLY — one ``rng.integers(n_actions)``
+per step, nothing else — so every existing mode (the validated T1-T6 suite,
+determinism, scale, scan) consumes an identical RNG stream and stays
+byte-identical to the validated build (FR-008, research R1).
+
+``CuriosityLookaheadPolicy`` is the shipped directed default (Doc 05 §4.2/§4.3):
+ε-gate first; uniformly random when exploring, when no best frame exists, or
+when the best frame is younger than the maturity bar; otherwise a one-step
+lookahead — predict each candidate action's outcome with the best frame's
+transition model, decode it, value it via the drive set — choosing the argmax
+with ties broken by the lowest action index (no further draws). Policies are
+stateless across steps; all randomness comes from the run's single seeded
+generator in this fixed order (FR-007).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+import numpy as np
+
+from pra.config import Config
+
+__all__ = ["PolicyContext", "Policy", "RandomPolicy", "CuriosityLookaheadPolicy", "PolicyParams"]
+
+
+@dataclass(frozen=True)
+class PolicyContext:
+    """The read-only view a policy selects from (data-model §3)."""
+
+    observation: np.ndarray
+    n_actions: int
+    best_frame_age: int | None  # None when no frame exists
+    predict_decoded: Callable[[int], np.ndarray | None]  # best-frame one-step, decoded
+    drive_value_of: Callable[[np.ndarray], float]  # drive set valued at a hypothetical obs
+
+
+@runtime_checkable
+class Policy(Protocol):
+    def select_action(self, context: PolicyContext, rng: np.random.Generator) -> int: ...
+
+
+class RandomPolicy:
+    """The pinned validation baseline: exactly the validated engine's inline draw."""
+
+    def select_action(self, context: PolicyContext, rng: np.random.Generator) -> int:
+        return int(rng.integers(context.n_actions))
+
+
+@dataclass(frozen=True)
+class PolicyParams:
+    exploration_epsilon: float
+    lookahead_min_age_cycles: int
+
+    @classmethod
+    def from_config(cls, config: Config) -> PolicyParams:
+        return cls(
+            exploration_epsilon=config.exploration_epsilon,
+            lookahead_min_age_cycles=config.lookahead_min_age_cycles,
+        )
+
+
+class CuriosityLookaheadPolicy:
+    """One-step curiosity lookahead with ε-exploration and a cold-start gate."""
+
+    def __init__(self, params: PolicyParams):
+        self.params = params
+        self.last_was_directed = False  # telemetry only; overwritten every step
+
+    def select_action(self, context: PolicyContext, rng: np.random.Generator) -> int:
+        # Fixed draw order (research R3): one uniform for the ε-gate, then one
+        # integer draw only on the random path. Exploit draws nothing further.
+        explore = rng.random() < self.params.exploration_epsilon
+        immature = (
+            context.best_frame_age is None
+            or context.best_frame_age < self.params.lookahead_min_age_cycles
+        )
+        if explore or immature:
+            self.last_was_directed = False
+            return int(rng.integers(context.n_actions))
+
+        best_action = 0
+        best_value = -np.inf
+        for action in range(context.n_actions):  # ascending: lowest index wins ties
+            predicted = context.predict_decoded(action)
+            if predicted is None:
+                continue
+            value = context.drive_value_of(predicted)
+            if value > best_value:
+                best_value = value
+                best_action = action
+        self.last_was_directed = True
+        return best_action

pra/anatomy/__init__.py

@@ -0,0 +1 @@
+"""Anatomy component (design Doc 02): sensors, actuators, the composed body, tools."""

pra/anatomy/body.py

@@ -0,0 +1,239 @@
+"""The body: sensors, actuators, fixed-order composition, tools (Doc 02 §2–§5).
+
+The anatomy is configurable and meaning-free: the system sees observations as
+vectors (the fixed-order concatenation of all active sensors) and emits actions
+as indices into the fixed-order disjoint union of all active actuators. The
+declared order is semantic — changing it changes the meaning of every
+observation dimension (Doc 02 §3.3).
+
+The :class:`Body` satisfies the existing ``EventSource`` seam
+(``reset``/``step``/``obs_dim``/``n_actions``), so it mounts wherever the
+synthetic world mounts today — with 1:1 delegation for a world-only body, which
+is what makes world-through-body runs byte-identical to the direct connection
+(feature 004 research R1). Tool registrations are queued and take effect only
+when the Engine calls :meth:`Body.apply_pending_tools` at a slow-loop boundary
+(C4, Doc 02 §5.2); the only feedback path from an action is subsequent
+observations (actuators return nothing, Doc 02 §4.2).
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+import numpy as np
+
+__all__ = [
+    "Sensor",
+    "Actuator",
+    "AnatomyError",
+    "Body",
+    "WorldSensor",
+    "WorldActuator",
+    "ConstantSensor",
+]
+
+
+class AnatomyError(ValueError):
+    """A body-contract violation (wrong width, duplicate id, invalid routing)."""
+
+
+@runtime_checkable
+class Sensor(Protocol):
+    def id(self) -> str: ...
+    def width(self) -> int: ...
+    def read(self) -> np.ndarray: ...
+
+
+@runtime_checkable
+class Actuator(Protocol):
+    def id(self) -> str: ...
+    def action_count(self) -> int: ...
+    def apply(self, local_action_index: int) -> None: ...
+
+
+class WorldSensor:
+    """Mounts the synthetic world's observation as one sensor. The world emits
+    on reset/step; this sensor exposes the cached emission (width = obs_dim)."""
+
+    def __init__(self, world, sensor_id: str = "world"):
+        self._world = world
+        self._id = sensor_id
+        self.last: np.ndarray | None = None
+
+    def id(self) -> str:
+        return self._id
+
+    def width(self) -> int:
+        return int(self._world.obs_dim)
+
+    def read(self) -> np.ndarray:
+        if self.last is None:
+            raise AnatomyError(f"sensor '{self._id}' read before the first emission")
+        return self.last
+
+
+class WorldActuator:
+    """Mounts the synthetic world's action space; applying steps the world and
+    feeds the paired WorldSensor's cache. Returns nothing (Doc 02 §4.2)."""
+
+    def __init__(self, world, sensor: WorldSensor, actuator_id: str = "world"):
+        self._world = world
+        self._sensor = sensor
+        self._id = actuator_id
+
+    def id(self) -> str:
+        return self._id
+
+    def action_count(self) -> int:
+        return int(self._world.n_actions)
+
+    def apply(self, local_action_index: int) -> None:
+        self._sensor.last = self._world.step(local_action_index)
+
+
+class ConstantSensor:
+    """A fixed-vector sensor (no RNG) — the tool-demo and test part."""
+
+    def __init__(self, sensor_id: str, values):
+        self._id = sensor_id
+        self._values = np.asarray(values, dtype=np.float64)
+
+    def id(self) -> str:
+        return self._id
+
+    def width(self) -> int:
+        return int(self._values.shape[0])
+
+    def read(self) -> np.ndarray:
+        return self._values
+
+
+class Body:
+    """Fixed-order composition of sensors and actuators around an environment.
+
+    EventSource-compatible: ``reset()`` begins an episode on the environment
+    (the world sensor caches the first emission) and composes the observation;
+    ``step(a)`` routes the global index to ``(actuator, local)`` and composes
+    all sensors' reads. ``obs_dim``/``n_actions`` are derived from the active
+    parts and change only when :meth:`apply_pending_tools` applies queued
+    registrations at a slow-loop boundary.
+    """
+
+    def __init__(self, environment, sensors: list, actuators: list):
+        if not sensors or not actuators:
+            raise AnatomyError("a body needs at least one sensor and one actuator")
+        self._environment = environment
+        self._sensors: list = []
+        self._actuators: list = []
+        self._pending: list[tuple[str, object]] = []
+        for s in sensors:
+            self._add_sensor(s)
+        for a in actuators:
+            self._add_actuator(a)
+
+    # ---- derived anatomy (Doc 02 §3.3 / §4.2) ---------------------------------
+    @property
+    def obs_dim(self) -> int:
+        return sum(s.width() for s in self._sensors)
+
+    @property
+    def n_actions(self) -> int:
+        return sum(a.action_count() for a in self._actuators)
+
+    # ---- EventSource surface --------------------------------------------------
+    def reset(self) -> np.ndarray:
+        first = self._environment.reset()
+        for s in self._sensors:
+            if isinstance(s, WorldSensor):
+                s.last = first
+        return self._compose()
+
+    def step(self, action: int) -> np.ndarray:
+        actuator, local = self.route(action)
+        actuator.apply(local)
+        return self._compose()
+
+    # ---- composition & routing ------------------------------------------------
+    def _compose(self) -> np.ndarray:
+        parts = []
+        for s in self._sensors:
+            value = np.asarray(s.read(), dtype=np.float64)
+            if value.shape != (s.width(),):
+                raise AnatomyError(
+                    f"sensor '{s.id()}' returned shape {value.shape}, declared width {s.width()}"
+                )
+            parts.append(value)
+        return parts[0] if len(parts) == 1 else np.concatenate(parts)
+
+    def route(self, action: int) -> tuple[object, int]:
+        """Global index -> (actuator, local index), by fixed declared order."""
+        if not 0 <= action < self.n_actions:
+            raise AnatomyError(f"action {action} outside [0, {self.n_actions})")
+        offset = 0
+        for a in self._actuators:
+            count = a.action_count()
+            if action < offset + count:
+                return a, action - offset
+            offset += count
+        raise AnatomyError("unreachable: routing table exhausted")  # pragma: no cover
+
+    # ---- ToolRegistry (Doc 02 §5): queued, applied at the slow loop ------------
+    def register_sensor(self, sensor) -> str:
+        self._check_new_id(sensor.id())
+        self._pending.append(("sensor", sensor))
+        return sensor.id()
+
+    def register_actuator(self, actuator) -> str:
+        self._check_new_id(actuator.id())
+        self._pending.append(("actuator", actuator))
+        return actuator.id()
+
+    def deregister(self, tool_id: str) -> None:
+        self._pending.append(("deregister", tool_id))
+
+    def list_tools(self) -> list[tuple[str, str]]:
+        return [(s.id(), "sensor") for s in self._sensors] + [
+            (a.id(), "actuator") for a in self._actuators
+        ]
+
+    def apply_pending_tools(self) -> tuple[int, int] | None:
+        """Apply queued registrations (slow loop only, C4). Returns the new
+        ``(obs_dim, n_actions)`` iff anything changed, else None."""
+        if not self._pending:
+            return None
+        for kind, item in self._pending:
+            if kind == "sensor":
+                self._add_sensor(item)
+            elif kind == "actuator":
+                self._add_actuator(item)
+            else:
+                self._remove(item)
+        self._pending.clear()
+        return self.obs_dim, self.n_actions
+
+    # ---- internals --------------------------------------------------------------
+    def _check_new_id(self, tool_id: str) -> None:
+        active = {i for i, _ in self.list_tools()}
+        queued = {(item.id() if kind != "deregister" else item) for kind, item in self._pending}
+        if tool_id in active or tool_id in queued:
+            raise AnatomyError(f"duplicate tool id '{tool_id}'")
+
+    def _add_sensor(self, sensor) -> None:
+        if sensor.width() < 1:
+            raise AnatomyError(f"sensor '{sensor.id()}' declares width < 1")
+        self._sensors.append(sensor)
+
+    def _add_actuator(self, actuator) -> None:
+        if actuator.action_count() < 1:
+            raise AnatomyError(f"actuator '{actuator.id()}' declares no actions")
+        self._actuators.append(actuator)
+
+    def _remove(self, tool_id: str) -> None:
+        for group, kind in ((self._sensors, "sensor"), (self._actuators, "actuator")):
+            for part in group:
+                if part.id() == tool_id:
+                    if len(group) == 1:
+                        raise AnatomyError(f"cannot deregister the last {kind} ('{tool_id}')")
+                    group.remove(part)
+                    return
+        raise AnatomyError(f"no tool with id '{tool_id}'")