structwire 0.1.0__tar.gz

structwire-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# Contributing
+
+Keep StructWire independent of transports, devices and test frameworks. New features
+should describe binary layout semantics; see [design](docs/DESIGN.md).
+
+## Development
+
+Create and activate a virtual environment from this checkout (Unix/macOS):
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[dev]'
+python -m pytest
+python -m ruff check .
+python -m ruff format --check .
+python -m mypy src/structwire
+python -m compileall -q src examples tests scripts
+python scripts/check_readme.py
+```
+
+On Windows, create the environment with `py -3 -m venv .venv` and activate it
+in PowerShell with `.venv\Scripts\Activate.ps1`, then use the same `python` commands.
+The README checker renders the PyPI description and checks local documentation
+links and anchors.
+
+Codec changes need encode/decode tests, meaningful round trips and malformed-input
+coverage. Document byte order, width and failure behavior. Update the
+[compatibility contract](docs/COMPATIBILITY.md) when changing precision, canonical
+output, or schema validation. Add boundary and differential/property tests for
+numeric changes.
+
+Pytest executes the four Python examples and every Python block in the README and
+`docs/`. YAML snippets are parsed and their StructWire schemas compiled; application
+routing examples are checked for valid nested layouts. The example routing files
+are checked against the supplied catalog. Property tests compare integer and float
+bytes with Python's standard library, exercise shared bit fields, and test scaled
+integer conversion with biases. Targeted cases cover malformed inputs, duplicate
+schemas, and precision loss.
+
+## Coverage
+
+CI reports branch coverage for all `structwire` modules without a percentage gate
+or custom exclusions. To inspect the same report locally:
+
+```bash
+python -m coverage run --branch --source=structwire -m pytest
+python -m coverage report -m
+```
+
+The report measures the main test process; subprocess example and resource-limit
+checks run separately and are not counted. Review missing behavior, not only the
+percentage. Pathological compilation tests use a memory-limited subprocess on
+Linux; portable allocation and overlap tests also run on the other platforms.
+
+## Distribution checks
+
+Build into an empty `dist/` directory; move any previous output aside first.
+
+```bash
+python -m build
+python -m twine check --strict dist/*.whl dist/*.tar.gz
+python scripts/check_dist.py dist
+python scripts/verify_install.py dist
+python scripts/verify_install.py dist --distribution sdist
+```
+
+`build` creates the sdist and builds the wheel from it. The configured build and
+development tools support SPDX license metadata and core metadata version 2.4.
+`check_dist.py` verifies metadata, license/typing files, the single-source version,
+public links, and matching package bytes in both artifacts. It prints artifact hashes.
+
+`verify_install.py` creates a fresh environment outside the checkout, installs the
+selected distribution and test dependencies, checks imports and metadata under
+`python -I`, then runs the full suite from the extracted source distribution.
+Tests exercise the installed package without a source-tree import path.
+
+CI runs quality checks and builds once, then tests that wheel on CPython 3.11–3.14
+on Linux, Windows, and macOS. The source installation is tested independently.
+See [releasing](RELEASING.md) for publication using those artifacts.
+
+## Source material
+
+Contribute only source, schemas and fixtures that you have the right to publish
+under MIT. Prefer synthetic examples and public protocol specifications. Keep
+private/customer payload databases, bench configuration and device secrets out
+of this repository. Customer and project mappings belong in their private plugins
+unless publication rights are explicit. Automated checks cannot establish those
+rights; the domain-neutral API never requires publishing customer protocol data.

structwire-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nidhal Abidi
+
+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.

structwire-0.1.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include CONTRIBUTING.md
+include RELEASING.md
+include SECURITY.md
+recursive-include docs *.md
+recursive-include examples *.py *.yaml
+recursive-include tests *.py
+recursive-include scripts *.py
+global-exclude __pycache__ *.py[cod]
+prune artifacts
+prune .github

structwire-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: structwire
+Version: 0.1.0
+Summary: A small schema-driven binary payload codec for Python.
+Author: Nidhal Abidi
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nidops/structwire
+Project-URL: Documentation, https://github.com/nidops/structwire/blob/master/docs/SCHEMA.md
+Project-URL: Source, https://github.com/nidops/structwire
+Project-URL: Issues, https://github.com/nidops/structwire/issues
+Keywords: binary,codec,schema,embedded,payload,bitfield,yaml
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: hypothesis>=6; extra == "test"
+Requires-Dist: readme-renderer[md]>=44; extra == "test"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: coverage>=7; extra == "dev"
+Requires-Dist: mypy>=1.13; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: hypothesis>=6; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: twine>=6.2; extra == "dev"
+Requires-Dist: packaging>=24.2; extra == "dev"
+Requires-Dist: readme-renderer[md]>=44; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0.12; extra == "dev"
+Dynamic: license-file
+
+# StructWire
+
+StructWire converts fixed-layout binary payloads to Python values and back.
+Use it when a device message, file record or test fixture has a known byte layout.
+Define fields in Python or YAML, then reuse a compiled codec to encode and decode.
+Your application supplies the bytes and handles transport I/O and routing.
+
+## Install
+
+Python 3.11 or newer is required. Install from the source checkout:
+
+```bash
+git clone https://github.com/nidops/structwire.git
+cd structwire
+python -m pip install .
+```
+
+Version `0.1.0` is an alpha API. PyYAML is installed automatically for YAML loading.
+
+## Quick start
+
+```python
+from structwire import Field, Layout
+
+codec = Layout(
+    Field("temperature_c", "i16le", scale=0.1),
+    Field("state", "u8"),
+).compile()
+
+payload = codec.encode({"temperature_c": 23.5, "state": 1})
+assert payload == bytes.fromhex("eb 00 01")
+assert codec.decode(payload) == {"temperature_c": 23.5, "state": 1}
+```
+
+Compile a layout once and reuse its codec.
+
+## YAML example
+
+Save this as `codecs.yaml`:
+
+```yaml
+version: 1
+codecs:
+  node_status:
+    size: 4
+    fields:
+      - name: mode
+        type: enum
+        values: {0: asleep, 1: awake, 2: fault}
+      - name: supply_voltage
+        type: uint16_le
+        offset: 2
+        scale: 0.001
+        unit: V
+```
+
+```python
+from structwire import catalog_from_yaml
+
+catalog = catalog_from_yaml("codecs.yaml")
+payload = bytes.fromhex("01 00 88 13")
+values = catalog.decode("node_status", payload)
+assert values == {"mode": "awake", "supply_voltage": 5.0}
+assert catalog.encode("node_status", values) == payload
+```
+
+Offsets and sizes are in bytes. Here, byte 1 is unused and encodes as zero.
+`unit` is display metadata; it does not change the conversion.
+
+## Supported layouts
+
+- Signed and unsigned 8/16/24/32/64-bit integers, with explicit byte order.
+- IEEE-754 32/64-bit floats, BCD, fixed ASCII, bytes and MAC addresses.
+- Enums, named flags, booleans and masked sub-fields.
+- Numeric scaling and bias, explicit offsets and optional total payload size.
+- Immutable layouts and reusable compiled codecs, with exact-length decoding by default.
+- Named catalogs and single-layout loaders for YAML or Python mappings.
+
+## Limitations
+
+Unscaled integers preserve their full range, including 64-bit values. Scaling uses
+Python floats, so some values cannot be represented exactly. Integer encoding
+rejects values between raw counts, allowing small rounding errors; decoding raises
+`DecodeError` if scaling loses the original count. For exact arithmetic, decode
+unscaled integers and convert them in your application.
+
+Encoding zeroes unused bytes and bits, encodes booleans as 0 or 1, and writes only
+declared masks from flags mappings. Arbitrary payloads may therefore change after
+decoding and re-encoding. See the
+[compatibility contract](https://github.com/nidops/structwire/blob/master/docs/COMPATIBILITY.md)
+for precise round-trip and floating-point guarantees.
+
+Variable-length fields, nested/repeated layouts and checksums are not supported.
+
+Schemas are trusted configuration. Safe YAML loading does not impose resource
+limits; applications must bound untrusted schema and payload sizes. See
+[schema resource limits](https://github.com/nidops/structwire/blob/master/docs/SCHEMA.md#trusted-schemas-and-resource-limits).
+
+## Documentation and examples
+
+- [Python API](https://github.com/nidops/structwire/blob/master/docs/API.md)
+- [Schema reference](https://github.com/nidops/structwire/blob/master/docs/SCHEMA.md)
+- [Examples](https://github.com/nidops/structwire/tree/master/examples)
+- [Questions and bug reports](https://github.com/nidops/structwire/issues)
+
+MIT. See [LICENSE](https://github.com/nidops/structwire/blob/master/LICENSE).

structwire-0.1.0/README.md

@@ -0,0 +1,106 @@
+# StructWire
+
+StructWire converts fixed-layout binary payloads to Python values and back.
+Use it when a device message, file record or test fixture has a known byte layout.
+Define fields in Python or YAML, then reuse a compiled codec to encode and decode.
+Your application supplies the bytes and handles transport I/O and routing.
+
+## Install
+
+Python 3.11 or newer is required. Install from the source checkout:
+
+```bash
+git clone https://github.com/nidops/structwire.git
+cd structwire
+python -m pip install .
+```
+
+Version `0.1.0` is an alpha API. PyYAML is installed automatically for YAML loading.
+
+## Quick start
+
+```python
+from structwire import Field, Layout
+
+codec = Layout(
+    Field("temperature_c", "i16le", scale=0.1),
+    Field("state", "u8"),
+).compile()
+
+payload = codec.encode({"temperature_c": 23.5, "state": 1})
+assert payload == bytes.fromhex("eb 00 01")
+assert codec.decode(payload) == {"temperature_c": 23.5, "state": 1}
+```
+
+Compile a layout once and reuse its codec.
+
+## YAML example
+
+Save this as `codecs.yaml`:
+
+```yaml
+version: 1
+codecs:
+  node_status:
+    size: 4
+    fields:
+      - name: mode
+        type: enum
+        values: {0: asleep, 1: awake, 2: fault}
+      - name: supply_voltage
+        type: uint16_le
+        offset: 2
+        scale: 0.001
+        unit: V
+```
+
+```python
+from structwire import catalog_from_yaml
+
+catalog = catalog_from_yaml("codecs.yaml")
+payload = bytes.fromhex("01 00 88 13")
+values = catalog.decode("node_status", payload)
+assert values == {"mode": "awake", "supply_voltage": 5.0}
+assert catalog.encode("node_status", values) == payload
+```
+
+Offsets and sizes are in bytes. Here, byte 1 is unused and encodes as zero.
+`unit` is display metadata; it does not change the conversion.
+
+## Supported layouts
+
+- Signed and unsigned 8/16/24/32/64-bit integers, with explicit byte order.
+- IEEE-754 32/64-bit floats, BCD, fixed ASCII, bytes and MAC addresses.
+- Enums, named flags, booleans and masked sub-fields.
+- Numeric scaling and bias, explicit offsets and optional total payload size.
+- Immutable layouts and reusable compiled codecs, with exact-length decoding by default.
+- Named catalogs and single-layout loaders for YAML or Python mappings.
+
+## Limitations
+
+Unscaled integers preserve their full range, including 64-bit values. Scaling uses
+Python floats, so some values cannot be represented exactly. Integer encoding
+rejects values between raw counts, allowing small rounding errors; decoding raises
+`DecodeError` if scaling loses the original count. For exact arithmetic, decode
+unscaled integers and convert them in your application.
+
+Encoding zeroes unused bytes and bits, encodes booleans as 0 or 1, and writes only
+declared masks from flags mappings. Arbitrary payloads may therefore change after
+decoding and re-encoding. See the
+[compatibility contract](https://github.com/nidops/structwire/blob/master/docs/COMPATIBILITY.md)
+for precise round-trip and floating-point guarantees.
+
+Variable-length fields, nested/repeated layouts and checksums are not supported.
+
+Schemas are trusted configuration. Safe YAML loading does not impose resource
+limits; applications must bound untrusted schema and payload sizes. See
+[schema resource limits](https://github.com/nidops/structwire/blob/master/docs/SCHEMA.md#trusted-schemas-and-resource-limits).
+
+## Documentation and examples
+
+- [Python API](https://github.com/nidops/structwire/blob/master/docs/API.md)
+- [Schema reference](https://github.com/nidops/structwire/blob/master/docs/SCHEMA.md)
+- [Examples](https://github.com/nidops/structwire/tree/master/examples)
+- [Questions and bug reports](https://github.com/nidops/structwire/issues)
+
+MIT. See [LICENSE](https://github.com/nidops/structwire/blob/master/LICENSE).

structwire-0.1.0/RELEASING.md

@@ -0,0 +1,31 @@
+# Releasing StructWire
+
+Package version lives in `src/structwire/__init__.py`; setuptools derives metadata
+from it. Keep this as the single version source.
+
+## Setup
+
+Configure [trusted publishing](https://docs.pypi.org/trusted-publishers/)
+separately on TestPyPI and PyPI for project `structwire`, repository
+`nidops/structwire`, and workflow `publish.yml`. Use GitHub environments `testpypi`
+and `pypi` respectively, restricted to release tags. For a new project, register
+a pending publisher; this does not reserve the package name. Confirm account
+ownership and public documentation links.
+
+## Release
+
+1. Update the package version and documentation.
+2. Run the [development checks](CONTRIBUTING.md#development) and
+   [distribution checks](CONTRIBUTING.md#distribution-checks).
+3. From a clean checkout, tag the reviewed `master` commit as `vX.Y.Z` after all
+   supported CI jobs pass. Verify the version with
+   `python scripts/check_dist.py dist --tag vX.Y.Z`, substituting the actual version.
+4. Push the tag, then manually run **Publish** in GitHub Actions with that tag selected.
+
+The workflow reruns CI, uploads verified artifacts to TestPyPI, checks the downloaded
+wheel's hash and installation, then publishes the same artifacts to PyPI and verifies
+again. Pushes alone do not publish. Check the package page after completion.
+
+If publication fails, rerun failed jobs in the same run while its `release-dist`
+artifact is available. Never overwrite tags or uploaded files, or hide mismatches
+with `skip-existing`. Changed release contents require a new version.

structwire-0.1.0/SECURITY.md

@@ -0,0 +1,13 @@
+# Security policy
+
+StructWire parses binary payloads using caller-supplied schemas. Report vulnerabilities
+privately through the repository's security-advisory feature rather than a public issue.
+Only the latest released `0.x` version receives fixes.
+
+Schemas are trusted application configuration. YAML loading uses safe constructors
+and rejects duplicate mapping keys, without arbitrary Python object construction;
+it does not limit input size, nesting or resource consumption. Applications own
+access control and resource limits for schemas and payloads. Bound widths, offsets,
+layout sizes and field/table counts before accepting untrusted schemas. Encoding
+still allocates a complete payload even when a sparse layout compiles cheaply.
+See [schema resource limits](docs/SCHEMA.md#trusted-schemas-and-resource-limits).

structwire-0.1.0/docs/API.md

@@ -0,0 +1,138 @@
+# Python API
+
+All names below are exported from `structwire`.
+See the [schema reference](SCHEMA.md) for field kinds and options and the
+[compatibility contract](COMPATIBILITY.md) for precision and canonical encoding.
+
+## Fields and layouts
+
+`Field(name, kind, ...)` describes one field. Optional arguments are `length`, `offset`, `mask`,
+`shift`, `scale`, `bias`, `values`, `bits`, `byteorder`, `description` and `unit`.
+Python constructors use these canonical names; the YAML key aliases `type`,
+`bitmask`, `bitshift` and `physical_offset` belong to the loaders. Kind aliases
+such as `uint16_le` work in both APIs.
+
+`Field.width` reports its storage size in bytes. `Field.effective_byteorder` reports the
+byte order used by integer, float, enum, flag, boolean and MAC conversions.
+BCD always stores its most significant decimal digits first; ASCII and bytes
+retain their byte sequence. `Field.signed` identifies signed integer kinds.
+Fields are immutable and copy their enum/flag tables into read-only mappings.
+Non-empty `values` is valid only for enums and non-empty `bits` only for flags;
+empty mappings are accepted on other kinds so descriptions can be reloaded.
+Numeric kinds take precedence over a conflicting `byteorder`; see the
+[byte-order policy](SCHEMA.md#field-keys).
+
+`Layout(*fields, name="", description="", size=None)` stores an ordered tuple of
+fields. `size` can add reserved bytes but cannot truncate a field. An empty layout
+is valid, with size zero unless a size is supplied. Layouts are immutable.
+
+`layout.compile()` returns a `Codec`. Compilation resolves offsets and rejects
+overlapping writers and undersized layouts with `SchemaError`. Reuse the compiled
+codec when processing multiple payloads. `layout.encode(...)` and `layout.decode(...)`
+are convenience methods that compile on each call and accept the same arguments
+as the codec methods.
+
+```python
+from structwire import Field, Layout
+
+codec = Layout(
+    Field("counter", "u16le"),
+    Field("state", "u8"),
+    name="status",
+    size=4,
+).compile()
+assert codec.size == 4
+assert codec.fields[0].width == 2
+assert codec.encode({"counter": 0x1234, "state": 1}) == b"\x34\x12\x01\x00"
+```
+
+## Compiled codecs
+
+`Codec(layout)` is equivalent to `layout.compile()`. Its `layout`, `fields` and
+`size` properties expose the source layout, ordered fields and exact payload size.
+Codecs keep no mutable state between calls and can be reused by independent callers.
+
+| Method | Behavior |
+|---|---|
+| `decode(payload, *, strict=True)` | Accepts `bytes`, `bytearray` or `memoryview`; returns a new dictionary of named values. Exact length is required by default. |
+| `decode(payload, strict=False)` | Ignores trailing bytes; short payloads still raise `DecodeError`. |
+| `encode(values, *, require_all=True)` | Accepts a mapping and returns new `bytes`. All fields are required by default; unknown names always raise `EncodeError`. |
+| `encode(values, require_all=False)` | Leaves omitted fields' storage bits zero, rather than applying a physical-value default. |
+| `describe()` | Returns a new dictionary with layout metadata and resolved field offsets, widths, kinds, byte order and enum/flag tables. |
+
+Inputs are not modified. Encoding zeroes unrepresented bytes and bits. A zeroed
+omitted field need not decode as physical zero: scaling, bias or enum labels can
+give those bits a different meaning. Descriptions can be serialized with
+`json.dumps` and loaded again with `layout_from_mapping`; modifying a description
+does not change the codec.
+
+## Catalogs and loaders
+
+`Catalog(layouts)` accepts a non-empty mapping of names to `Layout` or `Codec`
+objects and compiles layouts immediately. A layout's non-empty name must match its
+catalog key. Catalogs implement the read-only `Mapping[str, Codec]` interface:
+indexing, iteration, `len`, `keys`, `values`, `items` and `get` are available.
+`catalog.names` returns names in declaration order. An unknown name raises `KeyError`.
+Invalid containers or entries raise `SchemaError`.
+
+`catalog.encode(name, values, *, require_all=True)` and
+`catalog.decode(name, payload, *, strict=True)` delegate to that codec.
+`catalog.describe()` returns a fresh mapping from names to codec descriptions.
+
+```python
+from structwire import Catalog, Field, Layout
+
+catalog = Catalog({"status": Layout(Field("counter", "u8"))})
+assert catalog.names == ("status",)
+assert catalog.encode("status", {"counter": 7}) == b"\x07"
+assert catalog.decode("status", b"\x07") == {"counter": 7}
+```
+
+| Loader | Input and result |
+|---|---|
+| `layout_from_mapping(data, *, default_name="")` | A single layout mapping; returns an uncompiled `Layout`. Uses `default_name` when `name` is omitted. A non-empty `default_name` must match an explicit layout name. |
+| `layout_from_yaml(path)` | A UTF-8 YAML file containing a single layout; returns an uncompiled `Layout`. |
+| `catalog_from_mapping(data)` | A versioned catalog mapping; returns a compiled `Catalog`. |
+| `catalog_from_yaml(path)` | A UTF-8 YAML file containing a catalog; returns a compiled `Catalog`. |
+
+File loaders accept a string or `pathlib.Path` path, not YAML text.
+Loading a single layout validates its field definitions;
+call `compile()` to also validate overlaps and total size. Catalog loading performs
+both steps. See the [schema document shapes](SCHEMA.md).
+
+## Formatting
+
+`format_mac_address(data, *, byteorder="big")` accepts exactly six bytes as `bytes`,
+`bytearray` or `memoryview` and returns uppercase colon-separated hexadecimal.
+`byteorder="little"` reverses the address bytes. Invalid input raises `ValueError`.
+
+`format_value(value)` converts byte buffers to uppercase, space-separated hex
+(or `"<empty>"`), recursively visiting dictionaries, lists and tuples. Other values
+are returned unchanged. `format_record(record)` applies it to each value in a
+dictionary and returns a new dictionary. These helpers do not apply units or
+change numeric values.
+
+```python
+from structwire import format_mac_address, format_record
+
+assert format_mac_address(bytes.fromhex("01 23 45 67 89 AB")) == "01:23:45:67:89:AB"
+assert format_record({"raw": b"\x01\xab", "count": 2}) == {"raw": "01 AB", "count": 2}
+```
+
+## Errors
+
+`StructWireError` is the common base for `SchemaError`, `EncodeError` and
+`DecodeError`. All three specific exceptions also inherit from `ValueError`.
+
+- `SchemaError`: invalid field definitions, schema mappings or YAML, ambiguous
+  overlaps, unsupported versions or an undersized layout.
+- `EncodeError`: non-mapping input, unknown or missing fields, invalid values, values
+  outside storage limits, off-grid scaled integers or finite values that overflow inverse scaling.
+- `DecodeError`: invalid payload type or length, malformed ASCII/BCD, scaled integer
+  precision loss or finite float values that overflow scaling.
+
+File access errors remain normal `OSError` exceptions.
+BCD values that exceed Python's integer/string conversion limit raise `EncodeError`
+or `DecodeError`.
+The type annotations describe the supported public inputs; unrelated Python
+programming errors are not uniformly converted to StructWire exceptions.

structwire-0.1.0/docs/AUTOSPAN_ADOPTION.md

@@ -0,0 +1,41 @@
+# Optional AutoSpan adoption
+
+An AutoSpan project plugin can use StructWire to encode and decode payloads.
+StructWire has no AutoSpan dependency, and using it does not require AutoSpan core
+to depend on it.
+
+Suggested responsibilities for this optional integration:
+
+| Component | Responsibility |
+|---|---|
+| AutoSpan core | Test planning, execution and evidence |
+| StructWire | Payload layouts, encoding, decoding and value formatting |
+| Driver or adapter | Transport, protocol and device operations |
+| Project plugin | Device configuration, routing and payload definitions |
+
+## Project payload catalog
+
+A project-specific diagnostic or signal catalog should own the mapping from its identifier to a
+StructWire `Codec`:
+
+```python
+from structwire import Field, Layout
+
+SOFTWARE_VERSION = Layout(
+    Field("major", "bcd"),
+    Field("minor", "bcd"),
+    Field("patch", "bcd"),
+).compile()
+
+PAYLOADS = {
+    0x1001: SOFTWARE_VERSION,
+}
+```
+
+The protocol layer remains responsible for extracting or adding service identifiers and headers.
+StructWire receives only the payload region whose binary layout it owns.
+
+## Integration rule
+
+Declare the StructWire dependency in the plugin that uses it. For named catalogs
+and inline layouts, see the [integration examples](INTEGRATION_MODEL.md).