Release v3.1.0

v3.1.0 changes

BREAKING

• Samples: All runnable endpoint, multi-PLC, and configuration-driven samples require an explicit destination port and transport instead of defaulting to 1025/TCP.
• Library: Split scalar read_one / relay_read_one from count-required list reads; count=1 now returns a list and all range reads reject implicit multi-request splitting.
• Library: Renamed sparse read_many / relay_read_many to read_devices / relay_read_devices so contiguous and sparse semantics are not overloaded.
• Library: Removed public chunking helpers and the atomic_transfer option. Dword and float arrays now require one protocol request and reject boundary or limit overflow before communication.
• Library: Removed FR write/commit combination, range commit, wait/poll helpers, and raw FR-register methods. FR work-area writes and one-block commits are separate operations.
• Library: FR work-area word values require actual integers in 0..65535; negative, overflowing, Boolean, fractional, and string values are rejected before transport instead of being coerced or masked.
• Library: Generic bit/byte/word/dword writes reject masking and coercion; sequence writes use one request or fail before transport, and empty collections are invalid.
• Library: Added ToyopucOperationOutcomeUnknownError for state-changing requests that may have reached the PLC before timeout, disconnect, or cancellation.
• Library: UDP sockets are connected to the configured PLC endpoint. A fixed-local-port UDP client becomes terminal after an uncertain post-send failure because Computerlink cannot identify stale same-endpoint responses.
• Library: Relay reads retry the retry-required outer response when configured; relay writes remain non-retryable after send.
• Library: Retries now apply to pre-send connection failures and approved reads only; async cancellation interrupts the synchronous worker and waits for it to finish before returning.
• Library: Removed public trace callback configuration and isolated the maintainer callback on a bounded background queue so callback delay or failure cannot alter communication.
• Library: Bound resolved and parsed address objects to one canonical PLC profile, removed public addressing-option overrides, and reject cross-profile object reuse.
• Library: Moved raw command and prebuilt-payload senders to maintainer-only underscore paths and removed them from async and documented public surfaces.
• Migration: Replace scalar read(device) with read_one(device), sparse read_many(devices) with read_devices(devices), and intentional multi-request ranges with explicit application calls.
• Migration: Replace write_fr(..., commit=True) with write_fr(...) followed by commit_fr(block_start); use explicit CPU-status reads when completion monitoring is required.

Added

• Library: Added ToyopucPlcProfileDescriptor and plc_profile_descriptors() for canonical TOYOPUC Computer Link profile metadata.

Fixed

• Library: Keep protocol-width and unsupported-route validation while treating profile catalog index ranges as advisory application/UI metadata.
• Samples: Updated all sample and maintainer-tool client constructors from the removed protocol= keyword to transport=.
• CI: Made release dispatch check out an existing exact tag and verify the tag, manifest, runtime version, and built asset names before upload.
• Docs: Corrected the release guide and removed the hand-maintained Getting Started navigation block.

Tests

• Tests: Added return-shape, strict count, request-boundary, Dword/float no-partial-transfer, FR single-request and strict-value, explicit block commit, and removed-surface regression coverage.
• CI: Write the generated PyInstaller spec under the ignored build directory so a successful release check does not leave a root-level untracked artifact.

Release integrity

• The registry package, �3.1.0 tag, and attached assets remain immutable.
• Main-branch CHANGELOG classification was corrected by PR #24 without changing runtime code, package metadata, the tag, or published artifacts.