begin another attempt

Author: pavel-kirienko

CLAUDE.md

@@ -1,39 +1,47 @@
 # Instructions for AI agents
 
-This is a Python implementation of the Cyphal decentralized real-time publish-subscribe protocol. The key design goals are **simplicity** and **robustness**.
+This is a Python implementation of the Cyphal decentralized real-time publish-subscribe protocol.
+The key design goals are **simplicity** and **robustness**.
+Avoid overengineering and complexity; prefer straightforward solutions and explicit code.
 
-All features of the library MUST work on GNU/Linux, Windows, and macOS; the CI system must ensure that. Supported Python versions are starting from the oldest version specified in `pyproject.toml` up to the current latest stable Python.
+All features of the library MUST work on GNU/Linux, Windows, and macOS; the CI system must ensure that.
+Supported Python versions are starting from the oldest version specified in `pyproject.toml` up to the current
+latest stable Python.
 
-To get a better feel of the problem domain, peruse `reference/cy`, especially the formal models and the reference implementation in C.
+Rely on the Python type system as much as possible and avoid dynamic typing mechanisms;
+for example, always use type annotations, prefer dataclasses over dicts, etc.
 
-## Code layout
+To get a better feel of the problem domain, peruse `reference/cy`,
+especially the formal models and the reference implementation in C.
 
-Source is in `src/pycyphal/`, tests in `tests/`. The package is extremely compact by design and has very few modules:
+## Architecture and code layout
 
-- `_common.py` — Exception hierarchy, utilities, etc.
-- `_transport.py` — Abstract `Transport` interface defining subject broadcast and unicast operations. `SubjectWriter` interface. `TransportArrival` dataclass.
-- `_node.py` — Core `Node` implementation. Manages CRDT, gossip protocol, message routing, etc — all main functions of the protocol.
-- `_wire.py` — Wire protocol: message headers, subject ID computation, CRDT timestamp reconciliation.
-- `__init__.py` — Public API re-exports from the above modules.
-- Concrete transports:
-    - `udp.py` — Cyphal/UDP transport implementation.
+Source is in `src/pycyphal/`, tests in `tests/`. The package is extremely compact by design and has very few modules.
 
-Internal implementation modules use leading underscores. Keep public symbols explicit through `__init__.py`; keep private helpers in underscore-prefixed modules.
+Concrete transports are in top-level submodules:
+- `pycyphal.udp` — Cyphal/UDP transport implementation.
+- `pycyphal.can` (coming soon, not yet in the codebase) — Cyphal/CAN transport implementation.
 
-## Architecture
+The core must be dependency-free. Transports may introduce (optional) dependencies.
 
-The stack is layered: **Transport** (abstract I/O) → **Wire** (framing/headers) → **Node** (session logic). `Node` is the main user-facing class that ties everything together.
+Internal implementation modules use leading underscores.
+Keep public symbols explicit through `__init__.py`; keep private helpers in underscore-prefixed modules.
+The application is expected to `import pycyphal` only, without reaching out for any submodules directly;
+one exception applies to the transport modules mentioned above because the application will only import the transports
+that it needs.
 
-Key mechanisms in `Node`:
-- **CRDT**: Management of the distributed topic allocation table. Topics map to subject IDs via rapidhash; collisions are resolved by deterministic eviction.
-- **Gossip**: Periodic and urgent data exchange to keep CRDT consistent.
-- **Deduplication, Reordering, Reliable delivery** of user messages.
-
-Use `nox` to run the full test suite.
+Since the entirety of the library API is explicitly exposed through `pycyphal/__init__.py`,
+internally the library is free to use public visibility for all symbols/members that may require shared access
+between modules, even if they are not intended for external use.
+In particular, DO NOT access underscore-prefixed symbols from other modules/classes,
+but feel free to use non-underscore-prefixed symbols internally as needed, as there is no risk of API contamination.
 
 ## Reference design
 
-`reference/` contains git submodules with the reference implementations in C of the session layer (`cy/`) and  Cyphal/UDP transport layer (`libudpard/`).  These serve as the ultimate source of truth shall any wire-visible discrepancies be found.
+`reference/` contains git submodules with the reference implementations in C of the session layer (`cy/`)
+and transport layers (like `libudpard/` etc).
+These serve as the ultimate source of truth shall any wire-visible discrepancies be found.
+If there is a divergence between the references and this Python library, assume this Python library to be wrong.
 
 For parity audits or sync work against the reference, use the repo-local skill `$cyphal-parity-guard`.
 Expected usage patterns:
@@ -48,23 +56,22 @@ All I/O is async/await (pytest-asyncio with `asyncio_mode="auto"`).
 The code is fully type-annotated; frozen dataclasses for data.
 Dependencies intentionally kept to the bare minimum.
 
-For agent-authored commits, set `GIT_AUTHOR_NAME="Agent"` and `GIT_COMMITTER_NAME="Agent"`.
-
 ### Testing
 
-Mock transport/network in `tests/conftest.py`. Tests are ~10x the size of source code.
+Mock transport/network in `tests/conftest.py`.
+Tests are x10+ the size of source code and must provide full coverage of the core.
+Transport test coverage is more opportunistic.
 
 ### Logging
 
-Logging is required throughout the codebase; prefer many short messages.
-
-Avoid adding logging statements on code paths that immediately raise/enqueue/schedule an error as they are often redundant.
-Level policy:
+Logging is required throughout the codebase; prefer many short messages. Avoid adding logging statements on code
+paths that immediately raise/enqueue/schedule an error as they are often redundant.
+Follow `getLogger(__name__)` convention.
+Logging policy:
 
-- DEBUG for super detailed traces. Each DEBUG logging statement must occupy at most one line of code. Use abbreviations and formatting helpers.
+- DEBUG for super detailed traces. Each DEBUG logging statement must occupy at most one line of code.
+  Use abbreviations and formatting helpers.
 - INFO for anything not on the hot data path. Each INFO logging statement should take at most 2 lines of code.
 - WARNING for anything unusual. No LoC restriction.
 - ERROR for errors or anything unexpected. No LoC restriction.
 - CRITICAL for fatal or high-severity errors. No LoC restriction.
-
-Follow `getLogger(__name__)` convention.

pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 name = "pycyphal"
 dynamic = ["version"]
 requires-python = ">=3.11"
-dependencies = ["ifaddr"]
+dependencies = ["ifaddr"] # TODO: THE CORE MUST BE DEPENDENCY-FREE; move this into a udp optional dependency.
 authors = [
     { name = "Pavel Kirienko and OpenCyphal team", email = "pavel@opencyphal.org" },
 ]
@@ -47,7 +47,7 @@ Homepage = "https://opencyphal.org"
 Repository = "https://github.com/OpenCyphal/pycyphal"
 
 [tool.setuptools.dynamic]
-version = { attr = "pycyphal._version.__version__" }
+version = { attr = "pycyphal.__version__" }
 
 [project.optional-dependencies]
 test = ["pytest", "pytest-asyncio"]