medre-adapter-meshcore 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) hide show
  1. medre_adapter_meshcore-0.1.0/LICENSE +21 -0
  2. medre_adapter_meshcore-0.1.0/PKG-INFO +254 -0
  3. medre_adapter_meshcore-0.1.0/README.md +235 -0
  4. medre_adapter_meshcore-0.1.0/pyproject.toml +96 -0
  5. medre_adapter_meshcore-0.1.0/setup.cfg +4 -0
  6. medre_adapter_meshcore-0.1.0/src/medre/adapters/fakes/meshcore.py +541 -0
  7. medre_adapter_meshcore-0.1.0/src/medre/adapters/meshcore/__init__.py +12 -0
  8. medre_adapter_meshcore-0.1.0/src/medre/adapters/meshcore/adapter.py +1428 -0
  9. medre_adapter_meshcore-0.1.0/src/medre/adapters/meshcore/attribution.py +124 -0
  10. medre_adapter_meshcore-0.1.0/src/medre/adapters/meshcore/codec.py +258 -0
  11. medre_adapter_meshcore-0.1.0/src/medre/adapters/meshcore/compat.py +21 -0
  12. medre_adapter_meshcore-0.1.0/src/medre/adapters/meshcore/destination.py +13 -0
  13. medre_adapter_meshcore-0.1.0/src/medre/adapters/meshcore/errors.py +77 -0
  14. medre_adapter_meshcore-0.1.0/src/medre/adapters/meshcore/event_shape.py +91 -0
  15. medre_adapter_meshcore-0.1.0/src/medre/adapters/meshcore/identity.py +131 -0
  16. medre_adapter_meshcore-0.1.0/src/medre/adapters/meshcore/limits.py +20 -0
  17. medre_adapter_meshcore-0.1.0/src/medre/adapters/meshcore/packet_classifier.py +235 -0
  18. medre_adapter_meshcore-0.1.0/src/medre/adapters/meshcore/plugin.py +91 -0
  19. medre_adapter_meshcore-0.1.0/src/medre/adapters/meshcore/py.typed +0 -0
  20. medre_adapter_meshcore-0.1.0/src/medre/adapters/meshcore/renderer.py +391 -0
  21. medre_adapter_meshcore-0.1.0/src/medre/adapters/meshcore/sample.py +11 -0
  22. medre_adapter_meshcore-0.1.0/src/medre/adapters/meshcore/session.py +1919 -0
  23. medre_adapter_meshcore-0.1.0/src/medre/adapters/meshcore/stopped_declaration.py +66 -0
  24. medre_adapter_meshcore-0.1.0/src/medre/config/adapters/meshcore.py +320 -0
  25. medre_adapter_meshcore-0.1.0/src/medre/config/adapters/meshcore_destinations.py +11 -0
  26. medre_adapter_meshcore-0.1.0/src/medre/config/adapters/meshcore_errors.py +7 -0
  27. medre_adapter_meshcore-0.1.0/src/medre/config/adapters/meshcore_runtime.py +21 -0
  28. medre_adapter_meshcore-0.1.0/src/medre_adapter_meshcore.egg-info/PKG-INFO +254 -0
  29. medre_adapter_meshcore-0.1.0/src/medre_adapter_meshcore.egg-info/SOURCES.txt +84 -0
  30. medre_adapter_meshcore-0.1.0/src/medre_adapter_meshcore.egg-info/dependency_links.txt +1 -0
  31. medre_adapter_meshcore-0.1.0/src/medre_adapter_meshcore.egg-info/entry_points.txt +2 -0
  32. medre_adapter_meshcore-0.1.0/src/medre_adapter_meshcore.egg-info/requires.txt +9 -0
  33. medre_adapter_meshcore-0.1.0/src/medre_adapter_meshcore.egg-info/top_level.txt +1 -0
  34. medre_adapter_meshcore-0.1.0/tests/test_ble_recovery_cadence.py +127 -0
  35. medre_adapter_meshcore-0.1.0/tests/test_discovery_meshcore.py +19 -0
  36. medre_adapter_meshcore-0.1.0/tests/test_distribution_license.py +29 -0
  37. medre_adapter_meshcore-0.1.0/tests/test_fake_adapter_setup.py +13 -0
  38. medre_adapter_meshcore-0.1.0/tests/test_meshcore_adapter.py +1239 -0
  39. medre_adapter_meshcore-0.1.0/tests/test_meshcore_adapter_startup.py +256 -0
  40. medre_adapter_meshcore-0.1.0/tests/test_meshcore_attribution.py +481 -0
  41. medre_adapter_meshcore-0.1.0/tests/test_meshcore_ble_connection.py +952 -0
  42. medre_adapter_meshcore-0.1.0/tests/test_meshcore_boundaries.py +834 -0
  43. medre_adapter_meshcore-0.1.0/tests/test_meshcore_codec.py +393 -0
  44. medre_adapter_meshcore-0.1.0/tests/test_meshcore_config.py +927 -0
  45. medre_adapter_meshcore-0.1.0/tests/test_meshcore_contact_label.py +592 -0
  46. medre_adapter_meshcore-0.1.0/tests/test_meshcore_dedup_cancel_rollback.py +491 -0
  47. medre_adapter_meshcore-0.1.0/tests/test_meshcore_dedup_rollback.py +461 -0
  48. medre_adapter_meshcore-0.1.0/tests/test_meshcore_diagnostics.py +677 -0
  49. medre_adapter_meshcore-0.1.0/tests/test_meshcore_guarded_channel_identity.py +196 -0
  50. medre_adapter_meshcore-0.1.0/tests/test_meshcore_health_reporting.py +83 -0
  51. medre_adapter_meshcore-0.1.0/tests/test_meshcore_ingress.py +474 -0
  52. medre_adapter_meshcore-0.1.0/tests/test_meshcore_ingress_identity.py +382 -0
  53. medre_adapter_meshcore-0.1.0/tests/test_meshcore_ingress_pressure.py +868 -0
  54. medre_adapter_meshcore-0.1.0/tests/test_meshcore_initial_recovery.py +295 -0
  55. medre_adapter_meshcore-0.1.0/tests/test_meshcore_lifecycle_boundaries.py +241 -0
  56. medre_adapter_meshcore-0.1.0/tests/test_meshcore_live.py +751 -0
  57. medre_adapter_meshcore-0.1.0/tests/test_meshcore_local_integration.py +194 -0
  58. medre_adapter_meshcore-0.1.0/tests/test_meshcore_multipart.py +344 -0
  59. medre_adapter_meshcore-0.1.0/tests/test_meshcore_operational_boundaries.py +592 -0
  60. medre_adapter_meshcore-0.1.0/tests/test_meshcore_packet_classifier.py +354 -0
  61. medre_adapter_meshcore-0.1.0/tests/test_meshcore_pinned_sdk_contract.py +301 -0
  62. medre_adapter_meshcore-0.1.0/tests/test_meshcore_pipeline.py +612 -0
  63. medre_adapter_meshcore-0.1.0/tests/test_meshcore_prestart_buffer.py +847 -0
  64. medre_adapter_meshcore-0.1.0/tests/test_meshcore_process_lifetime_admission.py +720 -0
  65. medre_adapter_meshcore-0.1.0/tests/test_meshcore_reply_presentation.py +106 -0
  66. medre_adapter_meshcore-0.1.0/tests/test_meshcore_retry_timeout_cache.py +494 -0
  67. medre_adapter_meshcore-0.1.0/tests/test_meshcore_sdk_parity.py +858 -0
  68. medre_adapter_meshcore-0.1.0/tests/test_meshcore_session.py +1232 -0
  69. medre_adapter_meshcore-0.1.0/tests/test_meshcore_session_recovery.py +713 -0
  70. medre_adapter_meshcore-0.1.0/tests/test_meshcore_session_startup.py +1225 -0
  71. medre_adapter_meshcore-0.1.0/tests/test_meshcore_session_teardown.py +381 -0
  72. medre_adapter_meshcore-0.1.0/tests/test_meshcore_setup_classification.py +82 -0
  73. medre_adapter_meshcore-0.1.0/tests/test_meshcore_single_packet.py +103 -0
  74. medre_adapter_meshcore-0.1.0/tests/test_meshcore_single_packet_native.py +130 -0
  75. medre_adapter_meshcore-0.1.0/tests/test_meshcore_storage_roundtrip.py +370 -0
  76. medre_adapter_meshcore-0.1.0/tests/test_meshcore_sustained_admission.py +949 -0
  77. medre_adapter_meshcore-0.1.0/tests/test_meshcore_warning_filter.py +54 -0
  78. medre_adapter_meshcore-0.1.0/tests/test_meshcore_wire_budget.py +150 -0
  79. medre_adapter_meshcore-0.1.0/tests/test_native_destination.py +30 -0
  80. medre_adapter_meshcore-0.1.0/tests/test_native_setup.py +91 -0
  81. medre_adapter_meshcore-0.1.0/tests/test_offline_sample.py +32 -0
  82. medre_adapter_meshcore-0.1.0/tests/test_pin_literal_hygiene.py +124 -0
  83. medre_adapter_meshcore-0.1.0/tests/test_plugin_api_version.py +11 -0
  84. medre_adapter_meshcore-0.1.0/tests/test_project_tooling.py +78 -0
  85. medre_adapter_meshcore-0.1.0/tests/test_provider_contract.py +54 -0
  86. medre_adapter_meshcore-0.1.0/tests/test_stopped_declaration.py +63 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Jeremiah K.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,254 @@
1
+ Metadata-Version: 2.4
2
+ Name: medre-adapter-meshcore
3
+ Version: 0.1.0
4
+ Summary: meshcore transport adapter for MEDRE
5
+ License-Expression: MIT
6
+ Classifier: Typing :: Typed
7
+ Requires-Python: >=3.11
8
+ Description-Content-Type: text/markdown
9
+ License-File: LICENSE
10
+ Requires-Dist: medre<0.2.0,>=0.1.0
11
+ Requires-Dist: meshcore==2.3.15
12
+ Provides-Extra: test
13
+ Requires-Dist: pytest==9.1.1; extra == "test"
14
+ Requires-Dist: pytest-asyncio==1.4.0; extra == "test"
15
+ Requires-Dist: pytest-timeout==2.4.0; extra == "test"
16
+ Requires-Dist: jsonschema==4.26.0; extra == "test"
17
+ Requires-Dist: packaging==26.3; extra == "test"
18
+ Dynamic: license-file
19
+
20
+ # medre-adapter-meshcore
21
+
22
+ **Meshcore provider for MEDRE.** This separately installed distribution owns its
23
+ transport SDK, configuration, native codec and offline fake. MEDRE core owns
24
+ routing, storage, lifecycle and delivery evidence.
25
+
26
+ ## Install from Git
27
+
28
+ Use [uv](https://docs.astral.sh/uv/getting-started/installation/) and Git. For
29
+ a first trial, MEDRE can manage this provider in its persistent tool environment:
30
+
31
+ ```bash
32
+ uv tool install 'git+https://github.com/jeremiah-k/medre.git@main'
33
+ medre adapters install meshcore
34
+ medre adapters
35
+ ```
36
+
37
+ On Windows, the package-changing command prints a uv command to run **after**
38
+ `medre.exe` exits, rather than replacing an executable still in use.
39
+ The `main` branch is useful for trials; pin exact core and adapter commits for
40
+ repeatable operation. Use the [MEDRE Getting Started guide](https://github.com/jeremiah-k/medre/blob/main/docs/ops/getting-started.md)
41
+ for fake smoke, guided route creation and native setup. Use the
42
+ [adapter-source guide](https://github.com/jeremiah-k/medre/blob/main/docs/ops/adapter-installation.md)
43
+ for a locked uv deployment project, private Git, local checkouts, index sources,
44
+ and the same-environment requirement. Neither MEDRE nor the provider installs
45
+ packages during runtime startup.
46
+
47
+ ## Packaging and provenance
48
+
49
+ This distribution registers the `medre.adapters` entry point and retains the
50
+ import namespace `medre.adapters.meshcore`. Its original adapter source history
51
+ was extracted from MEDRE commit `e59c29dd31a95860d1cdbc19e531896616627a68`;
52
+ Git author and committer identities remain preserved. Runtime configuration and
53
+ adapter discovery do not depend on this repository's distribution name.
54
+
55
+ ## Ownership and imports
56
+
57
+ This distribution owns MeshCore's transport implementation, configuration models,
58
+ runtime wrapper, fake adapter, native addressing behavior, SDK requirements,
59
+ and protocol/SDK tests. MEDRE core owns generic events, routing, lifecycle,
60
+ storage, evidence, configuration orchestration, and installed-package discovery.
61
+
62
+ | Surface | Adapter-owned import |
63
+ | --------------- | -------------------------------------------------------------- |
64
+ | Config models | `medre.config.adapters.meshcore` |
65
+ | Runtime wrapper | `medre.config.adapters.meshcore_runtime.MeshCoreRuntimeConfig` |
66
+ | SDK-free fake | `medre.adapters.fakes.meshcore.FakeMeshCoreAdapter` |
67
+
68
+ Import the runtime wrapper from this distribution directly. Core has no named
69
+ wrapper compatibility bridge or transport SDK extras. The supported MEDRE
70
+ interface range and native SDK pins are declared in this project's
71
+ `pyproject.toml`; use a matching core revision during pre-release development.
72
+ Community adapter authors can use their own distribution names, import packages,
73
+ and hosting sources with the same `medre.adapters` entry-point contract.
74
+
75
+ MEDRE-authored adapter source is [MIT-licensed](LICENSE). This grant does
76
+ not relicense installed dependencies. Their license terms still apply to any
77
+ combined deployment or redistribution. See [dependency license notes](DEPENDENCY_LICENSES.md).
78
+
79
+ ## Offline samples and diagnostics
80
+
81
+ This distribution contributes native fake values and an opaque conversation
82
+ address to `medre config sample`. Core includes only installed contributors;
83
+ a single contributor gets two fake instances for offline routing. Native
84
+ packet simulation methods remain adapter-specific. Run-session canonical
85
+ callback injection uses `AdapterContract.publish_inbound(event)`.
86
+
87
+ `medre adapters check --config bridge.yaml` distinguishes missing distributions
88
+ from broken/conflicting entry points. Basic CLI help and unrelated healthy
89
+ providers remain available when another provider fails discovery.
90
+
91
+ MeshCore group messages have a 160-byte firmware text limit including the
92
+ firmware's `<device name>: ` prefix. MEDRE reserves that space, uses a conservative
93
+ 127-byte budget before the device name is known, and refreshes the effective
94
+ budget from the live handshake. `max_text_bytes` (default 160) is an operator
95
+ upper bound. Rendering truncates safely at UTF-8 boundaries and records that
96
+ fact; native sends that bypass this budget fail permanently before SDK I/O.
97
+
98
+ All core-rendered native messages use the durable packet grant, including short
99
+ and clipped single packets. A timeout, disconnect or cancellation after submission
100
+ retains uncertainty and does not trigger an internal resend. Empty native wire
101
+ text is rejected before dispatch. Direct session calls keep their legacy retry
102
+ policy and do not provide this guarantee. See [guarded native text](docs/spec/multipart-text.md).
103
+
104
+ Replies and threads relay as inline fallback text. They do not emit native
105
+ reply/thread operations. Delivery evidence identifies `fallback_text`;
106
+ reactions, edits, and deletes remain unsupported and are suppressed.
107
+ Fake adapters expose the same planning capabilities as their health reports.
108
+
109
+ ## Tests
110
+
111
+ Protocol and SDK contract tests live in this repository with adapter-owned
112
+ helpers. Cross-adapter routing and lifecycle tests remain in MEDRE. Run the
113
+ tests through the locked uv core environment described in
114
+ [contributing](CONTRIBUTING.md). That workflow supports arbitrary core and
115
+ provider checkouts, including forks, without a separate manually configured
116
+ virtual environment. Select SDK, service, hardware, local integration and soak
117
+ tiers explicitly. Re-run the SDK-free sync before claiming an SDK-free proof.
118
+
119
+ Deterministic local endpoint integration is also owned here. After installing
120
+ the SDK tier, select it explicitly:
121
+
122
+ ```bash
123
+ uv run --project "${MEDRE_CORE:?Set MEDRE_CORE to the core checkout}" --no-sync medre dev test --project "${MEDRE_CORE}" --editable meshcore=. meshcore -- -v -m "local_integration and not soak and not live and not hardware and not docker"
124
+ ```
125
+
126
+ Soak remains opt-in and is separate from deterministic local integration.
127
+
128
+ ## Fake smoke sources
129
+
130
+ The fake provides a synchronous `make_event(text=..., event_kind=...)` returning
131
+ a canonical event with its own adapter instance ID. After installing all
132
+ providers referenced by a fake bridge config, exercise a source with:
133
+
134
+ ```bash
135
+ medre smoke --config bridge.yaml --source-adapter ADAPTER_ID --json
136
+ ```
137
+
138
+ Use the configured instance ID, which may differ from the transport name. Each
139
+ normal smoke tests one source; inspect `source_candidates` and
140
+ `coverage_scope: single_source` in its report. Eligible sources must have started
141
+ and provide the helper. A pass requires delivery for every matched configured
142
+ route target, including targets unavailable after construction or startup.
143
+ Factory errors fail the smoke and trigger runtime cleanup. The result proves
144
+ fake direct-pipeline behavior; native callbacks and recipient delivery have
145
+ separate qualification tiers.
146
+
147
+ ## Coordinated CI
148
+
149
+ The repository CI installs MEDRE core and this adapter. Its fake job omits
150
+ native SDK dependencies; its SDK job installs this distribution's declared pins.
151
+ CI resolves MEDRE `main` once per run by default. Keep the repository Actions variable
152
+ `MEDRE_CORE_REF` unset so pull-request checks retain that baseline. Qualify a
153
+ candidate pair with a one-run dispatch and a full core commit SHA:
154
+
155
+ ```bash
156
+ gh workflow run test.yml --ref ADAPTER_BRANCH -f core_ref=FULL_CORE_COMMIT_SHA
157
+ ```
158
+
159
+ Record both revisions with the result. The candidate run does not replace the
160
+ adapter PR's checks against core `main`. Follow the
161
+ [coordinated-change policy](https://github.com/jeremiah-k/medre/blob/main/docs/dev/coordinated-changes.md)
162
+ for dependency order and merged compatibility pins.
163
+
164
+ Core's compatibility matrix tests each selected adapter at the exact commit
165
+ recorded in its manifest, along with cross-adapter behavior. In a coordinated
166
+ checkout containing the selected sibling repos, run from MEDRE:
167
+
168
+ ```bash
169
+ python scripts/ci/adapter_matrix.py --check-local
170
+ # Once all adapter changes are committed:
171
+ python scripts/ci/adapter_matrix.py --sync-local
172
+ ```
173
+
174
+ The helper validates clean sibling checkouts and their entry points, and compares
175
+ Python distribution names using normalized case/separator spelling. Synchronizing
176
+ updates the manifest atomically without fetching or installing packages. Review
177
+ the manifest diff, merge adapter commits into their default branches first, then publish
178
+ the core pin update and run `python scripts/ci/adapter_matrix.py --check-merged`. A failed write preserves the original manifest and cleans up the temporary
179
+ file. Deployment projects should separately lock their chosen complete
180
+ package graph.
181
+
182
+ Standalone CI records the exact core and adapter SHAs tested against its
183
+ configured core baseline. MEDRE core CI qualifies the pinned compatibility
184
+ pair; a standalone green result does not qualify another core revision.
185
+ SDK qualification extras come from the selected core compatibility manifest,
186
+ while SDK versions remain authoritative in this adapter's package metadata.
187
+
188
+ ## Provider contract and quality
189
+
190
+ The [registration reference](https://github.com/jeremiah-k/medre/blob/main/docs/dev/adapter-registration.md)
191
+ documents every hook, its loading phase, and the minimal fake constructor/event
192
+ calls. Shared native-metadata helpers are public under `medre.adapters.metadata`.
193
+ Conformance tests use `medre.testing`; SDK pin checks read this distribution's
194
+ installed metadata while this repository chooses its SDK qualification extras.
195
+ The fake constructor and explicit-keyword event factory are checked in the
196
+ SDK-free tier. Native schemas and validated examples live in `docs/schemas` here.
197
+
198
+ Python policy is declared in pyproject.toml. Local work and CI use the same
199
+ committed Trunk launcher and pinned tools for all-file checks, alongside the
200
+ fake/native qualification tiers.
201
+ The native adapter package includes its own `py.typed` marker.
202
+
203
+ ## Offline startup and recovery
204
+
205
+ A long-lived MEDRE adapter returns from initial setup in degraded health when
206
+ its configured radio is unavailable. Each complete native connection attempt
207
+ has a 15-second TCP/serial budget or a 45-second BLE budget (including BlueZ
208
+ cleanup and discovery). One session-owned recovery loop then retries with
209
+ exponential backoff and jitter, capped at 30 seconds between attempts, until the
210
+ radio connects or the adapter stops. The SDK's own auto-reconnect stays disabled.
211
+ Initial unavailability and later disconnects use the same serialized setup path.
212
+ Missing SDKs and invalid configuration still fail explicitly.
213
+
214
+ A disconnected started session reports transient send failure before any native
215
+ handoff. MEDRE owns delivery retries and their configured limits; connection
216
+ recovery does not guarantee unlimited message retention or native delivery.
217
+ Stopping the adapter cancels recovery before native teardown. Session stop
218
+ clears the inbound callback before its first await, so inbound delivery ends
219
+ when stop begins, even if the stop is cancelled mid-teardown. Native
220
+ cancellation still depends on the pinned SDK and driver cooperating; this is
221
+ not a process isolation boundary.
222
+
223
+ Direct one-shot `MeshCoreSession.start()` callers retain strict connection
224
+ failure by default; the production adapter explicitly requests degraded startup
225
+ with `recover_on_failure=True`.
226
+
227
+ ## Connect-time device-buffer drain
228
+
229
+ The pinned SDK's `start_auto_message_fetching()` issues one `get_msg()` while
230
+ `MeshCoreSession.start()` is still awaiting inside `MeshCoreAdapter.start()`,
231
+ so a frame buffered on the device reaches the adapter callback before the
232
+ adapter has marked itself started. Because `GET_NEXT_MSG` pops the frame from
233
+ the device queue, dropping it would lose the message unless the mesh
234
+ re-delivered it. While `start()` is in flight, inbound payloads are held in a
235
+ bounded FIFO (64 items) and flushed through the normal inbound path —
236
+ classification, dedup, and bounded callback admission — in arrival order once
237
+ startup completes. A full buffer drops with a cumulative counter and a
238
+ rate-limited, content-free warning. `stop()` and failed or cancelled starts
239
+ discard the buffer and never replay it into a later session; callbacks outside
240
+ the start window (never started, post-stop) keep the pre-existing silent drop.
241
+ The simulation helper requires a context and raises `RuntimeError` when none
242
+ exists. Buffered mappings are snapshotted, and callbacks from retired sessions
243
+ cannot enter a replacement lifetime. A second concurrent start is rejected, and
244
+ so is a start while an earlier start's session is still installed, such as the
245
+ partial session a cancelled start retains for rollback: `stop()` retires it
246
+ first, including the bounded BlueZ stale-link release for BLE.
247
+ Diagnostics expose `prestart_buffered`, `prestart_flushed`, and
248
+ `prestart_overflow_dropped`, reset at each start boundary. The contract is
249
+ specified in `docs/spec/prestart-inbound-buffer.md`.
250
+
251
+ ## Development tooling
252
+
253
+ See [contributing](CONTRIBUTING.md) for the shared Trunk quality gate and uv-based
254
+ editable development workflow.
@@ -0,0 +1,235 @@
1
+ # medre-adapter-meshcore
2
+
3
+ **Meshcore provider for MEDRE.** This separately installed distribution owns its
4
+ transport SDK, configuration, native codec and offline fake. MEDRE core owns
5
+ routing, storage, lifecycle and delivery evidence.
6
+
7
+ ## Install from Git
8
+
9
+ Use [uv](https://docs.astral.sh/uv/getting-started/installation/) and Git. For
10
+ a first trial, MEDRE can manage this provider in its persistent tool environment:
11
+
12
+ ```bash
13
+ uv tool install 'git+https://github.com/jeremiah-k/medre.git@main'
14
+ medre adapters install meshcore
15
+ medre adapters
16
+ ```
17
+
18
+ On Windows, the package-changing command prints a uv command to run **after**
19
+ `medre.exe` exits, rather than replacing an executable still in use.
20
+ The `main` branch is useful for trials; pin exact core and adapter commits for
21
+ repeatable operation. Use the [MEDRE Getting Started guide](https://github.com/jeremiah-k/medre/blob/main/docs/ops/getting-started.md)
22
+ for fake smoke, guided route creation and native setup. Use the
23
+ [adapter-source guide](https://github.com/jeremiah-k/medre/blob/main/docs/ops/adapter-installation.md)
24
+ for a locked uv deployment project, private Git, local checkouts, index sources,
25
+ and the same-environment requirement. Neither MEDRE nor the provider installs
26
+ packages during runtime startup.
27
+
28
+ ## Packaging and provenance
29
+
30
+ This distribution registers the `medre.adapters` entry point and retains the
31
+ import namespace `medre.adapters.meshcore`. Its original adapter source history
32
+ was extracted from MEDRE commit `e59c29dd31a95860d1cdbc19e531896616627a68`;
33
+ Git author and committer identities remain preserved. Runtime configuration and
34
+ adapter discovery do not depend on this repository's distribution name.
35
+
36
+ ## Ownership and imports
37
+
38
+ This distribution owns MeshCore's transport implementation, configuration models,
39
+ runtime wrapper, fake adapter, native addressing behavior, SDK requirements,
40
+ and protocol/SDK tests. MEDRE core owns generic events, routing, lifecycle,
41
+ storage, evidence, configuration orchestration, and installed-package discovery.
42
+
43
+ | Surface | Adapter-owned import |
44
+ | --------------- | -------------------------------------------------------------- |
45
+ | Config models | `medre.config.adapters.meshcore` |
46
+ | Runtime wrapper | `medre.config.adapters.meshcore_runtime.MeshCoreRuntimeConfig` |
47
+ | SDK-free fake | `medre.adapters.fakes.meshcore.FakeMeshCoreAdapter` |
48
+
49
+ Import the runtime wrapper from this distribution directly. Core has no named
50
+ wrapper compatibility bridge or transport SDK extras. The supported MEDRE
51
+ interface range and native SDK pins are declared in this project's
52
+ `pyproject.toml`; use a matching core revision during pre-release development.
53
+ Community adapter authors can use their own distribution names, import packages,
54
+ and hosting sources with the same `medre.adapters` entry-point contract.
55
+
56
+ MEDRE-authored adapter source is [MIT-licensed](LICENSE). This grant does
57
+ not relicense installed dependencies. Their license terms still apply to any
58
+ combined deployment or redistribution. See [dependency license notes](DEPENDENCY_LICENSES.md).
59
+
60
+ ## Offline samples and diagnostics
61
+
62
+ This distribution contributes native fake values and an opaque conversation
63
+ address to `medre config sample`. Core includes only installed contributors;
64
+ a single contributor gets two fake instances for offline routing. Native
65
+ packet simulation methods remain adapter-specific. Run-session canonical
66
+ callback injection uses `AdapterContract.publish_inbound(event)`.
67
+
68
+ `medre adapters check --config bridge.yaml` distinguishes missing distributions
69
+ from broken/conflicting entry points. Basic CLI help and unrelated healthy
70
+ providers remain available when another provider fails discovery.
71
+
72
+ MeshCore group messages have a 160-byte firmware text limit including the
73
+ firmware's `<device name>: ` prefix. MEDRE reserves that space, uses a conservative
74
+ 127-byte budget before the device name is known, and refreshes the effective
75
+ budget from the live handshake. `max_text_bytes` (default 160) is an operator
76
+ upper bound. Rendering truncates safely at UTF-8 boundaries and records that
77
+ fact; native sends that bypass this budget fail permanently before SDK I/O.
78
+
79
+ All core-rendered native messages use the durable packet grant, including short
80
+ and clipped single packets. A timeout, disconnect or cancellation after submission
81
+ retains uncertainty and does not trigger an internal resend. Empty native wire
82
+ text is rejected before dispatch. Direct session calls keep their legacy retry
83
+ policy and do not provide this guarantee. See [guarded native text](docs/spec/multipart-text.md).
84
+
85
+ Replies and threads relay as inline fallback text. They do not emit native
86
+ reply/thread operations. Delivery evidence identifies `fallback_text`;
87
+ reactions, edits, and deletes remain unsupported and are suppressed.
88
+ Fake adapters expose the same planning capabilities as their health reports.
89
+
90
+ ## Tests
91
+
92
+ Protocol and SDK contract tests live in this repository with adapter-owned
93
+ helpers. Cross-adapter routing and lifecycle tests remain in MEDRE. Run the
94
+ tests through the locked uv core environment described in
95
+ [contributing](CONTRIBUTING.md). That workflow supports arbitrary core and
96
+ provider checkouts, including forks, without a separate manually configured
97
+ virtual environment. Select SDK, service, hardware, local integration and soak
98
+ tiers explicitly. Re-run the SDK-free sync before claiming an SDK-free proof.
99
+
100
+ Deterministic local endpoint integration is also owned here. After installing
101
+ the SDK tier, select it explicitly:
102
+
103
+ ```bash
104
+ uv run --project "${MEDRE_CORE:?Set MEDRE_CORE to the core checkout}" --no-sync medre dev test --project "${MEDRE_CORE}" --editable meshcore=. meshcore -- -v -m "local_integration and not soak and not live and not hardware and not docker"
105
+ ```
106
+
107
+ Soak remains opt-in and is separate from deterministic local integration.
108
+
109
+ ## Fake smoke sources
110
+
111
+ The fake provides a synchronous `make_event(text=..., event_kind=...)` returning
112
+ a canonical event with its own adapter instance ID. After installing all
113
+ providers referenced by a fake bridge config, exercise a source with:
114
+
115
+ ```bash
116
+ medre smoke --config bridge.yaml --source-adapter ADAPTER_ID --json
117
+ ```
118
+
119
+ Use the configured instance ID, which may differ from the transport name. Each
120
+ normal smoke tests one source; inspect `source_candidates` and
121
+ `coverage_scope: single_source` in its report. Eligible sources must have started
122
+ and provide the helper. A pass requires delivery for every matched configured
123
+ route target, including targets unavailable after construction or startup.
124
+ Factory errors fail the smoke and trigger runtime cleanup. The result proves
125
+ fake direct-pipeline behavior; native callbacks and recipient delivery have
126
+ separate qualification tiers.
127
+
128
+ ## Coordinated CI
129
+
130
+ The repository CI installs MEDRE core and this adapter. Its fake job omits
131
+ native SDK dependencies; its SDK job installs this distribution's declared pins.
132
+ CI resolves MEDRE `main` once per run by default. Keep the repository Actions variable
133
+ `MEDRE_CORE_REF` unset so pull-request checks retain that baseline. Qualify a
134
+ candidate pair with a one-run dispatch and a full core commit SHA:
135
+
136
+ ```bash
137
+ gh workflow run test.yml --ref ADAPTER_BRANCH -f core_ref=FULL_CORE_COMMIT_SHA
138
+ ```
139
+
140
+ Record both revisions with the result. The candidate run does not replace the
141
+ adapter PR's checks against core `main`. Follow the
142
+ [coordinated-change policy](https://github.com/jeremiah-k/medre/blob/main/docs/dev/coordinated-changes.md)
143
+ for dependency order and merged compatibility pins.
144
+
145
+ Core's compatibility matrix tests each selected adapter at the exact commit
146
+ recorded in its manifest, along with cross-adapter behavior. In a coordinated
147
+ checkout containing the selected sibling repos, run from MEDRE:
148
+
149
+ ```bash
150
+ python scripts/ci/adapter_matrix.py --check-local
151
+ # Once all adapter changes are committed:
152
+ python scripts/ci/adapter_matrix.py --sync-local
153
+ ```
154
+
155
+ The helper validates clean sibling checkouts and their entry points, and compares
156
+ Python distribution names using normalized case/separator spelling. Synchronizing
157
+ updates the manifest atomically without fetching or installing packages. Review
158
+ the manifest diff, merge adapter commits into their default branches first, then publish
159
+ the core pin update and run `python scripts/ci/adapter_matrix.py --check-merged`. A failed write preserves the original manifest and cleans up the temporary
160
+ file. Deployment projects should separately lock their chosen complete
161
+ package graph.
162
+
163
+ Standalone CI records the exact core and adapter SHAs tested against its
164
+ configured core baseline. MEDRE core CI qualifies the pinned compatibility
165
+ pair; a standalone green result does not qualify another core revision.
166
+ SDK qualification extras come from the selected core compatibility manifest,
167
+ while SDK versions remain authoritative in this adapter's package metadata.
168
+
169
+ ## Provider contract and quality
170
+
171
+ The [registration reference](https://github.com/jeremiah-k/medre/blob/main/docs/dev/adapter-registration.md)
172
+ documents every hook, its loading phase, and the minimal fake constructor/event
173
+ calls. Shared native-metadata helpers are public under `medre.adapters.metadata`.
174
+ Conformance tests use `medre.testing`; SDK pin checks read this distribution's
175
+ installed metadata while this repository chooses its SDK qualification extras.
176
+ The fake constructor and explicit-keyword event factory are checked in the
177
+ SDK-free tier. Native schemas and validated examples live in `docs/schemas` here.
178
+
179
+ Python policy is declared in pyproject.toml. Local work and CI use the same
180
+ committed Trunk launcher and pinned tools for all-file checks, alongside the
181
+ fake/native qualification tiers.
182
+ The native adapter package includes its own `py.typed` marker.
183
+
184
+ ## Offline startup and recovery
185
+
186
+ A long-lived MEDRE adapter returns from initial setup in degraded health when
187
+ its configured radio is unavailable. Each complete native connection attempt
188
+ has a 15-second TCP/serial budget or a 45-second BLE budget (including BlueZ
189
+ cleanup and discovery). One session-owned recovery loop then retries with
190
+ exponential backoff and jitter, capped at 30 seconds between attempts, until the
191
+ radio connects or the adapter stops. The SDK's own auto-reconnect stays disabled.
192
+ Initial unavailability and later disconnects use the same serialized setup path.
193
+ Missing SDKs and invalid configuration still fail explicitly.
194
+
195
+ A disconnected started session reports transient send failure before any native
196
+ handoff. MEDRE owns delivery retries and their configured limits; connection
197
+ recovery does not guarantee unlimited message retention or native delivery.
198
+ Stopping the adapter cancels recovery before native teardown. Session stop
199
+ clears the inbound callback before its first await, so inbound delivery ends
200
+ when stop begins, even if the stop is cancelled mid-teardown. Native
201
+ cancellation still depends on the pinned SDK and driver cooperating; this is
202
+ not a process isolation boundary.
203
+
204
+ Direct one-shot `MeshCoreSession.start()` callers retain strict connection
205
+ failure by default; the production adapter explicitly requests degraded startup
206
+ with `recover_on_failure=True`.
207
+
208
+ ## Connect-time device-buffer drain
209
+
210
+ The pinned SDK's `start_auto_message_fetching()` issues one `get_msg()` while
211
+ `MeshCoreSession.start()` is still awaiting inside `MeshCoreAdapter.start()`,
212
+ so a frame buffered on the device reaches the adapter callback before the
213
+ adapter has marked itself started. Because `GET_NEXT_MSG` pops the frame from
214
+ the device queue, dropping it would lose the message unless the mesh
215
+ re-delivered it. While `start()` is in flight, inbound payloads are held in a
216
+ bounded FIFO (64 items) and flushed through the normal inbound path —
217
+ classification, dedup, and bounded callback admission — in arrival order once
218
+ startup completes. A full buffer drops with a cumulative counter and a
219
+ rate-limited, content-free warning. `stop()` and failed or cancelled starts
220
+ discard the buffer and never replay it into a later session; callbacks outside
221
+ the start window (never started, post-stop) keep the pre-existing silent drop.
222
+ The simulation helper requires a context and raises `RuntimeError` when none
223
+ exists. Buffered mappings are snapshotted, and callbacks from retired sessions
224
+ cannot enter a replacement lifetime. A second concurrent start is rejected, and
225
+ so is a start while an earlier start's session is still installed, such as the
226
+ partial session a cancelled start retains for rollback: `stop()` retires it
227
+ first, including the bounded BlueZ stale-link release for BLE.
228
+ Diagnostics expose `prestart_buffered`, `prestart_flushed`, and
229
+ `prestart_overflow_dropped`, reset at each start boundary. The contract is
230
+ specified in `docs/spec/prestart-inbound-buffer.md`.
231
+
232
+ ## Development tooling
233
+
234
+ See [contributing](CONTRIBUTING.md) for the shared Trunk quality gate and uv-based
235
+ editable development workflow.
@@ -0,0 +1,96 @@
1
+ [project]
2
+ name = "medre-adapter-meshcore"
3
+ version = "0.1.0"
4
+ readme = "README.md"
5
+ description = "meshcore transport adapter for MEDRE"
6
+ requires-python = ">=3.11"
7
+ classifiers = ["Typing :: Typed"]
8
+ license = "MIT"
9
+ dependencies = ["medre>=0.1.0,<0.2.0", 'meshcore==2.3.15']
10
+
11
+ [project.entry-points."medre.adapters"]
12
+ meshcore = "medre.adapters.meshcore.plugin:adapter_spec"
13
+
14
+ [build-system]
15
+ requires = ["setuptools>=77"]
16
+ build-backend = "setuptools.build_meta"
17
+
18
+ [tool.setuptools.packages.find]
19
+ where = ["src"]
20
+ namespaces = true
21
+
22
+ [project.optional-dependencies]
23
+ test = ["pytest==9.1.1", "pytest-asyncio==1.4.0", "pytest-timeout==2.4.0", "jsonschema==4.26.0", "packaging==26.3"]
24
+
25
+ [tool.pytest.ini_options]
26
+ asyncio_mode = "auto"
27
+ asyncio_default_fixture_loop_scope = "function"
28
+ testpaths = ["tests"]
29
+ pythonpath = ["src", "tests"]
30
+ filterwarnings = [
31
+ # The pinned meshcore SDK's EventDispatcher still calls
32
+ # asyncio.iscoroutinefunction, which Python 3.14 deprecates. With
33
+ # warnings-as-errors the dispatcher task would die on the first event
34
+ # and every live SDK connection would time out. Scope the exception to
35
+ # the SDK package (the deprecation is attributed to its call site).
36
+ # Drop the ignore when the installed SDK moves to inspect.iscoroutinefunction().
37
+ "error",
38
+ "ignore:'asyncio\\.iscoroutinefunction' is deprecated.*:DeprecationWarning:meshcore(\\.|$)",
39
+ ]
40
+ timeout = 360
41
+ addopts = "-m 'not live and not docker and not hardware and not local_integration and not soak and not matrix_sdk and not lxmf_sdk and not meshtastic_sdk and not meshcore_sdk'"
42
+ markers = [
43
+ "live: tests that connect to a real service or hardware (skipped by default)",
44
+ "docker: tests requiring Docker services like Synapse or meshtasticd (skipped by default)",
45
+ "matrix_sdk: tests requiring the pinned mindroom-nio Matrix SDK (skipped by default)",
46
+ "lxmf_sdk: tests requiring the pinned LXMF/RNS SDKs (skipped by default)",
47
+ "meshtastic_sdk: tests requiring the pinned mtjk Meshtastic SDK (skipped by default)",
48
+ "meshcore_sdk: tests requiring the pinned meshcore SDK (skipped by default)",
49
+ "local_integration: real pinned SDK plus deterministic local endpoint (skipped by default)",
50
+ "soak: extended-duration or repeated-cycle transport endurance tests (skipped by default)",
51
+ "hardware: tests requiring physical hardware (serial/BLE Meshtastic radios, etc.) — implies live (skipped by default)",
52
+ ]
53
+
54
+ [tool.setuptools.package-data]
55
+ "medre.adapters.meshcore" = ["py.typed"]
56
+
57
+ [tool.ruff]
58
+ line-length = 88
59
+
60
+ [tool.ruff.lint]
61
+ select = ["F", "E4", "E7", "E9", "B", "ASYNC", "RUF100"]
62
+ # RUF001-003: en-dashes in prose are intentional style.
63
+ # SIM105: try/except-pass reads clearer than contextlib.suppress here.
64
+ # ASYNC109: `timeout` parameter naming is the house convention.
65
+ # ASYNC250: interactive CLI prompts block on the main thread on purpose —
66
+ # terminal SIGINT must interrupt input()/getpass() directly; a worker
67
+ # thread would survive cancellation and hold the tty.
68
+ # ASYNC230/240: local-disk reads/writes in async CLI and evidence paths
69
+ # are deliberately synchronous (small files, thread-offloaded where it
70
+ # matters); revisit only if a path ever blocks on slow I/O.
71
+ ignore = [
72
+ "RUF001",
73
+ "RUF002",
74
+ "RUF003",
75
+ "SIM105",
76
+ "ASYNC109",
77
+ "ASYNC230",
78
+ "ASYNC240",
79
+ "ASYNC250",
80
+ ]
81
+
82
+ [tool.black]
83
+ target-version = ["py311"]
84
+
85
+ [tool.mypy]
86
+ python_version = "3.11"
87
+ strict = true
88
+ explicit_package_bases = true
89
+ follow_imports = "silent"
90
+
91
+ [[tool.mypy.overrides]]
92
+ module = ["bleak", "bleak.*", "meshcore", "meshcore.*"]
93
+ ignore_missing_imports = true
94
+
95
+ [tool.isort]
96
+ profile = "black"
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+