medre-adapter-matrix 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 (158) hide show
  1. medre_adapter_matrix-0.1.0/LICENSE +21 -0
  2. medre_adapter_matrix-0.1.0/MANIFEST.in +1 -0
  3. medre_adapter_matrix-0.1.0/PKG-INFO +442 -0
  4. medre_adapter_matrix-0.1.0/README.md +421 -0
  5. medre_adapter_matrix-0.1.0/docs/schemas/README.md +61 -0
  6. medre_adapter_matrix-0.1.0/docs/schemas/examples/matrix-durable-checkpoint-example.json +4 -0
  7. medre_adapter_matrix-0.1.0/docs/schemas/examples/matrix-native-metadata-example.json +47 -0
  8. medre_adapter_matrix-0.1.0/docs/schemas/matrix-durable-checkpoint.schema.json +18 -0
  9. medre_adapter_matrix-0.1.0/docs/schemas/matrix-embedded-metadata.schema.json +364 -0
  10. medre_adapter_matrix-0.1.0/docs/schemas/matrix-native-metadata.schema.json +451 -0
  11. medre_adapter_matrix-0.1.0/docs/schemas/matrix-oauth-credentials.schema.json +96 -0
  12. medre_adapter_matrix-0.1.0/docs/schemas/v0.1.0.freeze.json +10 -0
  13. medre_adapter_matrix-0.1.0/pyproject.toml +85 -0
  14. medre_adapter_matrix-0.1.0/setup.cfg +4 -0
  15. medre_adapter_matrix-0.1.0/setup.py +75 -0
  16. medre_adapter_matrix-0.1.0/src/medre/adapters/fakes/matrix.py +496 -0
  17. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/__init__.py +9 -0
  18. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/adapter.py +2093 -0
  19. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/attribution.py +252 -0
  20. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/auth.py +360 -0
  21. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/bridge_context.py +8 -0
  22. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/cli.py +523 -0
  23. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/cli_contrib.py +320 -0
  24. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/client_lifecycle.py +46 -0
  25. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/codec.py +430 -0
  26. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/compat.py +45 -0
  27. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/device_trust.py +221 -0
  28. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/durable_sync.py +297 -0
  29. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/e2ee_bootstrap.py +189 -0
  30. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/errors.py +180 -0
  31. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/event_shape.py +351 -0
  32. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/identity.py +846 -0
  33. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/metadata.py +208 -0
  34. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/oauth.py +624 -0
  35. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/oauth_approval.py +155 -0
  36. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/oauth_cli.py +179 -0
  37. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/oauth_session.py +297 -0
  38. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/outbound.py +255 -0
  39. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/plugin.py +72 -0
  40. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/provision.py +508 -0
  41. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/py.typed +0 -0
  42. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/relations.py +201 -0
  43. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/renderer.py +1344 -0
  44. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/runtime.py +88 -0
  45. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/sample.py +17 -0
  46. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/session.py +3483 -0
  47. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/signing_cli.py +161 -0
  48. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/signing_recovery.py +135 -0
  49. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/stopped_declaration.py +194 -0
  50. medre_adapter_matrix-0.1.0/src/medre/adapters/matrix/styling.py +230 -0
  51. medre_adapter_matrix-0.1.0/src/medre/config/adapters/matrix.py +395 -0
  52. medre_adapter_matrix-0.1.0/src/medre/config/adapters/matrix_credentials.py +109 -0
  53. medre_adapter_matrix-0.1.0/src/medre/config/adapters/matrix_destinations.py +13 -0
  54. medre_adapter_matrix-0.1.0/src/medre/config/adapters/matrix_errors.py +7 -0
  55. medre_adapter_matrix-0.1.0/src/medre/config/adapters/matrix_runtime.py +20 -0
  56. medre_adapter_matrix-0.1.0/src/medre_adapter_matrix.egg-info/PKG-INFO +442 -0
  57. medre_adapter_matrix-0.1.0/src/medre_adapter_matrix.egg-info/SOURCES.txt +156 -0
  58. medre_adapter_matrix-0.1.0/src/medre_adapter_matrix.egg-info/dependency_links.txt +1 -0
  59. medre_adapter_matrix-0.1.0/src/medre_adapter_matrix.egg-info/entry_points.txt +2 -0
  60. medre_adapter_matrix-0.1.0/src/medre_adapter_matrix.egg-info/requires.txt +12 -0
  61. medre_adapter_matrix-0.1.0/src/medre_adapter_matrix.egg-info/top_level.txt +1 -0
  62. medre_adapter_matrix-0.1.0/tests/test_discovery_matrix.py +17 -0
  63. medre_adapter_matrix-0.1.0/tests/test_distribution_license.py +67 -0
  64. medre_adapter_matrix-0.1.0/tests/test_matrix_adapter.py +1292 -0
  65. medre_adapter_matrix-0.1.0/tests/test_matrix_adapter_auto_join.py +197 -0
  66. medre_adapter_matrix-0.1.0/tests/test_matrix_adapter_delivery.py +217 -0
  67. medre_adapter_matrix-0.1.0/tests/test_matrix_adapter_startup.py +727 -0
  68. medre_adapter_matrix-0.1.0/tests/test_matrix_alpha_run_session.py +456 -0
  69. medre_adapter_matrix-0.1.0/tests/test_matrix_attachment_ingress.py +540 -0
  70. medre_adapter_matrix-0.1.0/tests/test_matrix_attribution.py +538 -0
  71. medre_adapter_matrix-0.1.0/tests/test_matrix_auth_live.py +47 -0
  72. medre_adapter_matrix-0.1.0/tests/test_matrix_auth_login.py +625 -0
  73. medre_adapter_matrix-0.1.0/tests/test_matrix_behavior_reference.py +774 -0
  74. medre_adapter_matrix-0.1.0/tests/test_matrix_boundaries.py +1011 -0
  75. medre_adapter_matrix-0.1.0/tests/test_matrix_bridge_context.py +301 -0
  76. medre_adapter_matrix-0.1.0/tests/test_matrix_cli.py +42 -0
  77. medre_adapter_matrix-0.1.0/tests/test_matrix_client_lifecycle.py +81 -0
  78. medre_adapter_matrix-0.1.0/tests/test_matrix_codec.py +394 -0
  79. medre_adapter_matrix-0.1.0/tests/test_matrix_config.py +821 -0
  80. medre_adapter_matrix-0.1.0/tests/test_matrix_contract_docs.py +53 -0
  81. medre_adapter_matrix-0.1.0/tests/test_matrix_credentials_storage.py +81 -0
  82. medre_adapter_matrix-0.1.0/tests/test_matrix_cross_signing_auth.py +567 -0
  83. medre_adapter_matrix-0.1.0/tests/test_matrix_cross_signing_identity.py +513 -0
  84. medre_adapter_matrix-0.1.0/tests/test_matrix_cross_signing_runtime.py +172 -0
  85. medre_adapter_matrix-0.1.0/tests/test_matrix_cross_signing_sdk_contract.py +149 -0
  86. medre_adapter_matrix-0.1.0/tests/test_matrix_decrypted_event_sdk_contract.py +125 -0
  87. medre_adapter_matrix-0.1.0/tests/test_matrix_default_prefix.py +99 -0
  88. medre_adapter_matrix-0.1.0/tests/test_matrix_device_trust.py +951 -0
  89. medre_adapter_matrix-0.1.0/tests/test_matrix_device_trust_docker.py +846 -0
  90. medre_adapter_matrix-0.1.0/tests/test_matrix_device_trust_sdk_contract.py +192 -0
  91. medre_adapter_matrix-0.1.0/tests/test_matrix_durable_admission_boundary.py +81 -0
  92. medre_adapter_matrix-0.1.0/tests/test_matrix_durable_batches.py +895 -0
  93. medre_adapter_matrix-0.1.0/tests/test_matrix_durable_review.py +166 -0
  94. medre_adapter_matrix-0.1.0/tests/test_matrix_durable_runtime_live.py +324 -0
  95. medre_adapter_matrix-0.1.0/tests/test_matrix_e2ee_live.py +310 -0
  96. medre_adapter_matrix-0.1.0/tests/test_matrix_embedding_modes.py +140 -0
  97. medre_adapter_matrix-0.1.0/tests/test_matrix_event_shape.py +963 -0
  98. medre_adapter_matrix-0.1.0/tests/test_matrix_fake_bridge.py +1193 -0
  99. medre_adapter_matrix-0.1.0/tests/test_matrix_formatted_body.py +323 -0
  100. medre_adapter_matrix-0.1.0/tests/test_matrix_health_lifecycle.py +436 -0
  101. medre_adapter_matrix-0.1.0/tests/test_matrix_health_reasons.py +68 -0
  102. medre_adapter_matrix-0.1.0/tests/test_matrix_identity_continuity_sdk.py +174 -0
  103. medre_adapter_matrix-0.1.0/tests/test_matrix_invite_registration.py +66 -0
  104. medre_adapter_matrix-0.1.0/tests/test_matrix_lifecycle.py +587 -0
  105. medre_adapter_matrix-0.1.0/tests/test_matrix_live.py +1245 -0
  106. medre_adapter_matrix-0.1.0/tests/test_matrix_metadata.py +139 -0
  107. medre_adapter_matrix-0.1.0/tests/test_matrix_native_health.py +290 -0
  108. medre_adapter_matrix-0.1.0/tests/test_matrix_native_lifecycle.py +920 -0
  109. medre_adapter_matrix-0.1.0/tests/test_matrix_oauth.py +572 -0
  110. medre_adapter_matrix-0.1.0/tests/test_matrix_oauth_lock.py +75 -0
  111. medre_adapter_matrix-0.1.0/tests/test_matrix_oauth_redirects.py +137 -0
  112. medre_adapter_matrix-0.1.0/tests/test_matrix_oauth_sdk_contract.py +100 -0
  113. medre_adapter_matrix-0.1.0/tests/test_matrix_oauth_setup.py +692 -0
  114. medre_adapter_matrix-0.1.0/tests/test_matrix_outbound_envelope.py +139 -0
  115. medre_adapter_matrix-0.1.0/tests/test_matrix_pipeline.py +688 -0
  116. medre_adapter_matrix-0.1.0/tests/test_matrix_provision.py +584 -0
  117. medre_adapter_matrix-0.1.0/tests/test_matrix_rate_limit_ownership.py +109 -0
  118. medre_adapter_matrix-0.1.0/tests/test_matrix_reaction_described_delivery.py +324 -0
  119. medre_adapter_matrix-0.1.0/tests/test_matrix_reaction_key.py +83 -0
  120. medre_adapter_matrix-0.1.0/tests/test_matrix_relations.py +132 -0
  121. medre_adapter_matrix-0.1.0/tests/test_matrix_resume_room_state.py +41 -0
  122. medre_adapter_matrix-0.1.0/tests/test_matrix_room_policy.py +379 -0
  123. medre_adapter_matrix-0.1.0/tests/test_matrix_send_idempotency.py +974 -0
  124. medre_adapter_matrix-0.1.0/tests/test_matrix_send_media.py +983 -0
  125. medre_adapter_matrix-0.1.0/tests/test_matrix_session.py +1450 -0
  126. medre_adapter_matrix-0.1.0/tests/test_matrix_session_config.py +340 -0
  127. medre_adapter_matrix-0.1.0/tests/test_matrix_session_coverage.py +452 -0
  128. medre_adapter_matrix-0.1.0/tests/test_matrix_session_e2ee.py +919 -0
  129. medre_adapter_matrix-0.1.0/tests/test_matrix_session_event_shape.py +324 -0
  130. medre_adapter_matrix-0.1.0/tests/test_matrix_session_media_transfer.py +637 -0
  131. medre_adapter_matrix-0.1.0/tests/test_matrix_session_recovery.py +1175 -0
  132. medre_adapter_matrix-0.1.0/tests/test_matrix_session_sync_boundary.py +530 -0
  133. medre_adapter_matrix-0.1.0/tests/test_matrix_signing_recovery.py +530 -0
  134. medre_adapter_matrix-0.1.0/tests/test_matrix_startup_admission.py +158 -0
  135. medre_adapter_matrix-0.1.0/tests/test_matrix_startup_grace.py +304 -0
  136. medre_adapter_matrix-0.1.0/tests/test_matrix_storage_roundtrip.py +396 -0
  137. medre_adapter_matrix-0.1.0/tests/test_matrix_store_lifecycle_sdk.py +67 -0
  138. medre_adapter_matrix-0.1.0/tests/test_matrix_styling.py +209 -0
  139. medre_adapter_matrix-0.1.0/tests/test_matrix_sync_checkpoint_ownership.py +529 -0
  140. medre_adapter_matrix-0.1.0/tests/test_matrix_sync_recovery_sdk_contract.py +78 -0
  141. medre_adapter_matrix-0.1.0/tests/test_matrix_target_selection_rules.py +472 -0
  142. medre_adapter_matrix-0.1.0/tests/test_matrix_thread_reply_intent.py +49 -0
  143. medre_adapter_matrix-0.1.0/tests/test_matrix_trust_review_regressions.py +110 -0
  144. medre_adapter_matrix-0.1.0/tests/test_matrix_typing.py +168 -0
  145. medre_adapter_matrix-0.1.0/tests/test_matrix_unbound_reply.py +103 -0
  146. medre_adapter_matrix-0.1.0/tests/test_native_destination.py +30 -0
  147. medre_adapter_matrix-0.1.0/tests/test_native_setup.py +64 -0
  148. medre_adapter_matrix-0.1.0/tests/test_offline_sample.py +31 -0
  149. medre_adapter_matrix-0.1.0/tests/test_optional_e2ee_readiness.py +124 -0
  150. medre_adapter_matrix-0.1.0/tests/test_pin_literal_hygiene.py +124 -0
  151. medre_adapter_matrix-0.1.0/tests/test_plugin_api_version.py +10 -0
  152. medre_adapter_matrix-0.1.0/tests/test_provider_contract.py +53 -0
  153. medre_adapter_matrix-0.1.0/tests/test_rendering_boundaries.py +256 -0
  154. medre_adapter_matrix-0.1.0/tests/test_runtime_preparation.py +78 -0
  155. medre_adapter_matrix-0.1.0/tests/test_schema_freeze_010.py +146 -0
  156. medre_adapter_matrix-0.1.0/tests/test_schema_wheel_resources.py +151 -0
  157. medre_adapter_matrix-0.1.0/tests/test_stopped_capture_sdk.py +301 -0
  158. medre_adapter_matrix-0.1.0/tests/test_stopped_declaration.py +120 -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 @@
1
+ recursive-include docs/schemas *
@@ -0,0 +1,442 @@
1
+ Metadata-Version: 2.4
2
+ Name: medre-adapter-matrix
3
+ Version: 0.1.0
4
+ Summary: matrix transport adapter for MEDRE
5
+ License-Expression: MIT
6
+ Classifier: Typing :: Typed
7
+ Requires-Python: >=3.12
8
+ Description-Content-Type: text/markdown
9
+ License-File: LICENSE
10
+ Requires-Dist: medre<0.2.0,>=0.1.0
11
+ Requires-Dist: mindroom-nio[e2e]==1.3.0
12
+ Provides-Extra: test
13
+ Requires-Dist: pytest==9.2.0; extra == "test"
14
+ Requires-Dist: pytest-asyncio==1.5.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
+ Provides-Extra: e2e
19
+ Requires-Dist: mindroom-nio[e2e]==1.3.0; extra == "e2e"
20
+ Dynamic: license-file
21
+
22
+ # medre-adapter-matrix
23
+
24
+ **Matrix provider for MEDRE.** This separately installed distribution owns its
25
+ transport SDK, configuration, native codec and offline fake. MEDRE core owns
26
+ routing, storage, lifecycle and delivery evidence.
27
+
28
+ ## Install from Git
29
+
30
+ Use [uv](https://docs.astral.sh/uv/getting-started/installation/) and Git. For
31
+ a first trial, MEDRE can manage this provider in its persistent tool environment:
32
+
33
+ ```bash
34
+ uv tool install 'git+https://github.com/jeremiah-k/medre.git@main'
35
+ medre adapters install matrix
36
+ medre adapters
37
+ ```
38
+
39
+ Matrix requires Python 3.12+ and includes its durable SQLite/crypto backend.
40
+ The `matrix[e2e]` spelling remains a compatible installation alias.
41
+ The released mindroom-nio store requires POSIX file leases; Windows
42
+ production sessions require a provider release with Windows lease support.
43
+
44
+ On Windows, the package-changing command prints a uv command to run **after**
45
+ `medre.exe` exits, rather than replacing an executable still in use.
46
+ The `main` branch is useful for trials; pin exact core and adapter commits for
47
+ repeatable operation. Use the [MEDRE Getting Started guide](https://github.com/jeremiah-k/medre/blob/main/docs/ops/getting-started.md)
48
+ for fake smoke, guided route creation and native setup. Use the
49
+ [adapter-source guide](https://github.com/jeremiah-k/medre/blob/main/docs/ops/adapter-installation.md)
50
+ for a locked uv deployment project, private Git, local checkouts, index sources,
51
+ and the same-environment requirement. Neither MEDRE nor the provider installs
52
+ packages during runtime startup.
53
+
54
+ ## Startup readiness
55
+
56
+ After authentication and configured room joins, startup waits up to
57
+ `initial_sync_timeout_seconds` (45 seconds by default) for the first acknowledged
58
+ sync. A pending long poll is logged as startup progress. Login alone never
59
+ establishes healthy readiness. On expiry, startup returns with degraded health
60
+ and the existing sync owner keeps recovering; a later acknowledgement publishes
61
+ healthy current state automatically. Native sync failure or reconnect exits
62
+ the wait immediately with its actual health.
63
+
64
+ Set the wait to `0` to report pending health immediately. The runtime's
65
+ `adapter_start_timeout_seconds` bounds the complete adapter start, including
66
+ login, joins, and this wait. Allow additional runtime budget for slow services;
67
+ its cancellation still closes the partially started session. See
68
+ [durable sync](docs/spec/durable-sync.md#startup-readiness) for the contract.
69
+
70
+ ## Message presentation
71
+
72
+ Supported Matrix HTML maps to bounded canonical text spans when its visible text
73
+ matches the plain body. Outbound content escapes text and links and keeps relay
74
+ attribution outside source styles. Unsupported or inconsistent markup retains
75
+ plain presentation. See the [presentation contract](docs/spec/relay-attribution.md#text-presentation)
76
+ for reply, edit, truncation, and block-boundary behavior.
77
+
78
+ ## Browser-approved Matrix login
79
+
80
+ For an OAuth-enabled homeserver, authorize MEDRE from your browser instead of
81
+ providing its account password. The provider includes the crypto backend;
82
+ select the adapter whose persistent device store should be prepared:
83
+
84
+ ```bash
85
+ medre adapter matrix auth login --oauth \
86
+ --user @relay:example.org --adapter-id matrix
87
+ medre adapter matrix auth status
88
+ ```
89
+
90
+ Use the configured adapter key for `--adapter-id`. The command displays the
91
+ verification address and a short code. Approve only the login you initiated.
92
+ Homeserver discovery follows Matrix delegation; `--homeserver` can select an
93
+ explicit server. `--client-id` supports an existing public client registration
94
+ when dynamic registration is unavailable. Without `--adapter-id`, the command
95
+ only establishes credentials and does not load the E2EE SDK.
96
+
97
+ Keep credentials out of the runtime YAML so its missing authentication fields
98
+ resolve from MEDRE's credential sidecar. Runtime requests automatically renew
99
+ OAuth tokens, including SDK retry attempts. Repeating the login command resumes
100
+ the saved device session and retries signing instead of allocating another
101
+ device. Password options cannot be combined with `--oauth`.
102
+
103
+ The browser may request a separate signing-key approval. A matching account
104
+ identity is reused across devices; a missing local identity for an account that
105
+ already has signing keys requires restoring the original store. Deliberately
106
+ replacing lost or conflicting account keys requires `--reset-cross-signing`:
107
+
108
+ ```bash
109
+ medre adapter matrix auth login --oauth --adapter-id matrix --reset-cross-signing
110
+ ```
111
+
112
+ A reset can require other clients to verify the account identity again. It is
113
+ not part of routine login. Signing failures retain OAuth credentials and E2EE
114
+ state so setup can be retried. Own-device signing does not verify other users
115
+ or restore historical encrypted room keys.
116
+
117
+ Stop bridges using this account before changing sessions. To revoke a saved
118
+ password or OAuth session and then authenticate again, use:
119
+
120
+ ```bash
121
+ medre adapter matrix auth logout
122
+ ```
123
+
124
+ Logout preserves the crypto store and account-signing sidecar. Back them up
125
+ securely together. Password login remains available on supporting homeservers
126
+ through the existing interactive or `--password-stdin` commands.
127
+
128
+ ## Packaging and provenance
129
+
130
+ This distribution registers the `medre.adapters` entry point and retains the
131
+ import namespace `medre.adapters.matrix`. Its original adapter source history
132
+ was extracted from MEDRE commit `e59c29dd31a95860d1cdbc19e531896616627a68`;
133
+ Git author and committer identities remain preserved. Runtime configuration and
134
+ adapter discovery do not depend on this repository's distribution name.
135
+
136
+ ## Restart and offline messages
137
+
138
+ The SDK persists captured responses, crypto state, recovery and its upstream
139
+ cursor. MEDRE admits committed records before acknowledging their SDK batch.
140
+ Restart replays unacknowledged records through native-ID deduplication. History
141
+ provenance and recovery losses remain explicit; neither a saved cursor nor a
142
+ connected client establishes successful delivery.
143
+
144
+ Inbound events whose origin server timestamp predates the adapter's start by
145
+ more than `startup_backlog_suppress_seconds` (default 60 seconds, `0` disables)
146
+ are startup history and are suppressed on every delivery path — live sync,
147
+ durable catch-up, or gap recovery — using the same transport-neutral
148
+ `should_suppress_startup_backlog` policy the Meshtastic adapter applies. The
149
+ check precedes decode, so messages, reactions, and edits are equally covered,
150
+ and suppressed events count under `inbound_suppressed_stale` in diagnostics.
151
+ The window covers homeserver federation lag and minor clock drift so events
152
+ sent moments before startup still flow.
153
+
154
+ ## Ownership and imports
155
+
156
+ This distribution owns Matrix's transport implementation, configuration models,
157
+ runtime wrapper, fake adapter, native addressing behavior, SDK requirements,
158
+ and protocol/SDK tests. MEDRE core owns generic events, routing, lifecycle,
159
+ storage, evidence, configuration orchestration, and installed-package discovery.
160
+
161
+ | Surface | Adapter-owned import |
162
+ | --------------- | ---------------------------------------------------------- |
163
+ | Config models | `medre.config.adapters.matrix` |
164
+ | Runtime wrapper | `medre.config.adapters.matrix_runtime.MatrixRuntimeConfig` |
165
+ | SDK-free fake | `medre.adapters.fakes.matrix.FakeMatrixAdapter` |
166
+
167
+ Import the runtime wrapper from this distribution directly. Core has no named
168
+ wrapper compatibility bridge or transport SDK extras. The supported MEDRE
169
+ interface range and native SDK pins are declared in this project's
170
+ `pyproject.toml`; use a matching core revision during pre-release development.
171
+ Community adapter authors can use their own distribution names, import packages,
172
+ and hosting sources with the same `medre.adapters` entry-point contract.
173
+
174
+ MEDRE-authored adapter source is [MIT-licensed](LICENSE). This grant does
175
+ not relicense installed dependencies. Their license terms still apply to any
176
+ combined deployment or redistribution. See [dependency license notes](DEPENDENCY_LICENSES.md).
177
+
178
+ ## Offline samples and diagnostics
179
+
180
+ This distribution contributes native fake values and an opaque conversation
181
+ address to `medre config sample`. Core includes only installed contributors;
182
+ a single contributor gets two fake instances for offline routing. Native
183
+ packet simulation methods remain adapter-specific. Run-session canonical
184
+ callback injection uses `AdapterContract.publish_inbound(event)`.
185
+
186
+ `medre adapters check --config bridge.yaml` distinguishes missing distributions
187
+ from broken/conflicting entry points. Basic CLI help and unrelated healthy
188
+ providers remain available when another provider fails discovery.
189
+
190
+ Matrix configures the core-owned `medre adapter matrix` parser. Optional CLI
191
+ registration failures are reported as `broken CLI contribution` without
192
+ disabling generic help, preflight, healthy commands, or runtime discovery.
193
+
194
+ Durable sync restores the SDK's persisted membership and encryption projection.
195
+ A fresh store obtains its initial state from the homeserver; existing stores keep
196
+ their device identity and pending batches. See the
197
+ [durable sync contract](docs/spec/durable-sync.md) for adoption and rollback limits.
198
+
199
+ Stopped-state maintenance derives this adapter's capture inventory from a
200
+ provider-owned declaration shipped in this distribution; the durable store and
201
+ token sidecar are declared honestly rather than guessed. See the
202
+ [stopped-state declaration contract](docs/spec/stopped-state.md).
203
+
204
+ Matrix event `content.medre` carries versioned canonical provenance and selected
205
+ metadata. `metadata_embedding_mode` is destination-specific: `off` omits the
206
+ MEDRE namespace, `minimal` carries event/actor identity, `safe` adds native
207
+ message references and normalized metadata, and `full` also includes provider
208
+ native and custom metadata. Full mode exports those details deliberately;
209
+ configuration and SDK objects are never embedded.
210
+
211
+ Outbound Matrix content carries no legacy `meshtastic_*` fields; the embedded
212
+ MEDRE namespace is the only relay metadata surface, and selecting
213
+ `metadata_embedding_mode: off` yields content without it. Embedded provenance
214
+ is an untrusted relay hint, not delivery evidence or authorization to operate
215
+ on another message. The wire contract is
216
+ [matrix-embedded-metadata.schema.json](docs/schemas/matrix-embedded-metadata.schema.json).
217
+
218
+ ## Tests
219
+
220
+ Protocol and SDK contract tests live in this repository with adapter-owned
221
+ helpers. Cross-adapter routing and lifecycle tests remain in MEDRE. Run the
222
+ following from this repository in a fresh virtual environment, with a matching
223
+ MEDRE checkout at any location. Set `MEDRE_CORE` to that checkout path.
224
+
225
+ ```bash
226
+ # SDK-free fake tier: core dev supplies test tooling; skip this adapter's SDK deps.
227
+ python -m pip install -e "${MEDRE_CORE:?Set MEDRE_CORE to the core checkout}[dev]"
228
+ python -m pip install --no-deps -e .
229
+ python -m pytest -q
230
+
231
+ # Native SDK tier: this distribution supplies its own SDK pins.
232
+ python -m pip install -e '.[test,e2e]'
233
+ python -m pytest -v -m "matrix_sdk and not local_integration and not soak and not live and not hardware and not docker"
234
+ ```
235
+
236
+ The default pytest selection excludes SDK, service, hardware, local integration,
237
+ and soak tiers. Installing SDKs afterward leaves the same environment SDK-enabled;
238
+ use a fresh environment for a new SDK-free proof.
239
+
240
+ ## Fake smoke sources
241
+
242
+ The fake provides a synchronous `make_event(text=..., event_kind=...)` returning
243
+ a canonical event with its own adapter instance ID. After installing all
244
+ providers referenced by a fake bridge config, exercise a source with:
245
+
246
+ ```bash
247
+ medre smoke --config bridge.yaml --source-adapter ADAPTER_ID --json
248
+ ```
249
+
250
+ Use the configured instance ID, which may differ from the transport name. Each
251
+ normal smoke tests one source; inspect `source_candidates` and
252
+ `coverage_scope: single_source` in its report. Eligible sources must have started
253
+ and provide the helper. A pass requires delivery for every matched configured
254
+ route target, including targets unavailable after construction or startup.
255
+ Factory errors fail the smoke and trigger runtime cleanup. The result proves
256
+ fake direct-pipeline behavior; native callbacks and recipient delivery have
257
+ separate qualification tiers.
258
+
259
+ ## Coordinated CI
260
+
261
+ The repository CI installs MEDRE core and this adapter. Its fake job omits
262
+ native SDK dependencies; its SDK job installs this distribution's declared pins.
263
+ CI resolves MEDRE `main` once per run by default. Keep the repository Actions variable
264
+ `MEDRE_CORE_REF` unset so pull-request checks retain that baseline. Qualify a
265
+ candidate pair with a one-run dispatch and a full core commit SHA:
266
+
267
+ ```bash
268
+ gh workflow run test.yml --ref ADAPTER_BRANCH -f core_ref=FULL_CORE_COMMIT_SHA
269
+ gh workflow run test.yml --ref ADAPTER_BRANCH -f core_ref=FULL_CORE_COMMIT_SHA -f sdk_ref=FULL_SDK_COMMIT_SHA
270
+ ```
271
+
272
+ Record both revisions with the result. The candidate run does not replace the
273
+ adapter PR's checks against core `main`. Follow the
274
+ [coordinated-change policy](https://github.com/jeremiah-k/medre/blob/main/docs/dev/coordinated-changes.md)
275
+ for dependency order and merged compatibility pins.
276
+
277
+ A manual `sdk_ref` selects a full commit from `jeremiah-k/mindroom-nio` for
278
+ installed-SDK jobs. The candidate is installed within the locked core constraints;
279
+ its package version must satisfy the adapter's declared dependency. CI checks
280
+ package consistency and installed-source provenance, and records the exact SDK
281
+ commit. Default jobs retain the released SDK pin. Candidate-source runs qualify
282
+ an experiment; they do not change deployment dependencies or compatibility pins.
283
+
284
+ Core's compatibility matrix tests each selected adapter at the exact commit
285
+ recorded in its manifest, along with cross-adapter behavior. In a coordinated
286
+ checkout containing the selected sibling repos, run from MEDRE:
287
+
288
+ ```bash
289
+ python scripts/ci/adapter_matrix.py --check-local
290
+ # Once all adapter changes are committed:
291
+ python scripts/ci/adapter_matrix.py --sync-local
292
+ ```
293
+
294
+ The helper validates clean sibling checkouts and their entry points, and compares
295
+ Python distribution names using normalized case/separator spelling. Synchronizing
296
+ updates the manifest atomically without fetching or installing packages. Review
297
+ the manifest diff, merge adapter commits into their default branches first, then publish
298
+ 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
299
+ file. Deployment projects should separately lock their chosen complete
300
+ package graph.
301
+
302
+ Standalone CI records the exact core and adapter SHAs tested against its
303
+ configured core baseline. MEDRE core CI qualifies the pinned compatibility
304
+ pair; a standalone green result does not qualify another core revision.
305
+ SDK qualification extras come from the selected core compatibility manifest,
306
+ while SDK versions remain authoritative in this adapter's package metadata.
307
+
308
+ ## Provider contract and quality
309
+
310
+ The [registration reference](https://github.com/jeremiah-k/medre/blob/main/docs/dev/adapter-registration.md)
311
+ documents every hook, its loading phase, and the minimal fake constructor/event
312
+ calls. Shared native-metadata helpers are public under `medre.adapters.metadata`.
313
+ Conformance tests use `medre.testing`; SDK pin checks read this distribution's
314
+ installed metadata while this repository chooses its SDK qualification extras.
315
+ The fake constructor and explicit-keyword event factory are checked in the
316
+ SDK-free tier. Native schemas and validated examples live in `docs/schemas` here.
317
+
318
+ This repository declares its own Ruff/Black policy. CI checks all Python source
319
+ and tests, plus commit whitespace, alongside the fake/native qualification tiers.
320
+ The native adapter package includes its own `py.typed` marker.
321
+
322
+ ## Default relay attribution
323
+
324
+ Matrix output defaults to `[sender/origin]: message`, preserving the full sender
325
+ name. An absent origin renders `[sender]: message`. Set `relay_prefix: ""` to
326
+ disable attribution or supply a custom generic template. Omitted/null selects
327
+ the automatic policy; MMRelay wire metadata keeps the original unprefixed text.
328
+
329
+ ## Device verification
330
+
331
+ E2EE setup uses the adapter's persistent store and checks its own device's
332
+ server-visible signing chain. A fresh device uploads its keys before reusing
333
+ the account signing identity; ordinary login does not require rotating that
334
+ identity. Keep the E2EE store when renewing credentials. A cross-signing reset
335
+ replaces account identity material and can require verification in other clients.
336
+
337
+ ## Peer-device verification policy
338
+
339
+ `verification_policy` is an optional peer-device **send authorization** gate.
340
+ The `permissive` default sends encrypted messages without scanning the local
341
+ peer-device trust store or emitting trust-gap warnings. This is normal bridge
342
+ operation for trusted rooms, not a trust verdict or a delivery receipt.
343
+ Own-device cross-signing is handled independently during identity setup and
344
+ runtime verification and does not establish trust in other users' devices.
345
+
346
+ Operators may explicitly select `strict`: then encrypted sends require an
347
+ affirmative local nio trust view for every recipient device, complete room
348
+ membership, and SDK enforcement with `ignore_unverified_devices=False`.
349
+ Unknown/unverified peers cause a retryable, pre-handoff refusal. MEDRE does
350
+ not currently offer an operator peer-verification workflow, and verification
351
+ performed in a different Matrix client does not automatically populate
352
+ MEDRE's local device store. Do not enable `strict` unless local peer trust
353
+ can be established independently. No automatic verification or plaintext
354
+ downgrade occurs.
355
+
356
+ The policy applies only to encrypted sends — crypto active and the room
357
+ affirmatively encrypted. Plaintext delivery, ephemeral typing, and redactions
358
+ are outside its scope. For the opt-in gate, a recipient missing from the
359
+ local device store counts as a trust gap. The default does not inspect that
360
+ store. The adapter's own current device is handled by cross-signing, not
361
+ peer-device authorization.
362
+
363
+ Pre-release decision note: `permissive` is the default for compatibility, and
364
+ `strict` is NOT scheduled to become the default until a separate,
365
+ independently qualified peer-verification workflow exists. Flipping that
366
+ default is a deliberate, separately reviewed change; do not rely on the
367
+ current default for assurance.
368
+
369
+ Neither mode proves delivery. A refused send is never delivered, but an
370
+ encrypted send that passes the policy — even to fully verified devices — is
371
+ only homeserver acceptance of the Megolm ciphertext. It is not a delivery
372
+ receipt: nobody can observe from the send whether a peer device received,
373
+ decrypted, or read the message.
374
+
375
+ ## Transient typing
376
+
377
+ Routes can explicitly opt in with `forward_typing: true` when both endpoints
378
+ support typing and map concrete conversations. The adapter projects Matrix's
379
+ complete ephemeral user lists into core actor leases, excludes its own relay
380
+ user, and sends the aggregate indicator as the configured relay account.
381
+
382
+ Typing is separate from message encryption and discloses activity even in
383
+ encrypted rooms. The same configured-room, joined-room and encryption-safety
384
+ guards apply to outbound requests. Indicators use finite native timeouts and
385
+ best-effort clears; they create no canonical event, outbox row or receipt.
386
+ Unchanged composition can expire after core's 30-second freshness bound unless
387
+ another native observation arrives. Message forwarding alone does not opt in. The [typing contract](docs/spec/transient-typing.md)
388
+ defines native scope and live-sync behavior.
389
+
390
+ ## Encryption readiness
391
+
392
+ Install the Matrix provider with its declared dependencies. The durable SDK
393
+ requires its SQLite crypto backend even with encryption_mode: plaintext;
394
+ plaintext policy continues refusing encrypted-room delivery. Missing backend
395
+ dependencies fail production startup instead of silently selecting ordinary sync.
396
+
397
+ Encryption readiness and own-device cross-signing are separate diagnostics.
398
+ Installing dependencies or authenticating does not recover lost account signing
399
+ keys. Runtime never resets that identity. To inspect the actual selected store:
400
+
401
+ ```bash
402
+ medre adapter matrix auth status --adapter-id matrix --config ~/medre/bridge.yaml
403
+ ```
404
+
405
+ If a signing file exists but cannot be read, check ownership/read permissions
406
+ first. Preserve a private backup before manually moving a confirmed unusable
407
+ file aside; import refuses replacement. Rerun status after the destination is
408
+ absent. SDK/path inspection failures require diagnosis before assuming keys are
409
+ missing.
410
+
411
+ If the signing file is missing, stop the bridge and locate an existing SDK
412
+ account-signing JSON for the same Matrix account (for example in an MMRelay
413
+ store or a backup). Do not copy tokens or device databases between applications.
414
+ Validate and import that backup using the existing MEDRE credentials:
415
+
416
+ ```bash
417
+ medre adapter matrix auth restore-signing --adapter-id matrix \
418
+ --config ~/medre/bridge.yaml \
419
+ --from ~/.mmrelay/matrix/store/@bot:example.com_cross_signing.json
420
+ ```
421
+
422
+ The command verifies the token's account/device and matches the backup's keys
423
+ against the existing server identity before writing anything. Publication
424
+ requires an absent destination and filesystem hard-link support; an existing
425
+ file is never replaced. The source backup remains unchanged. A post-publication
426
+ filesystem error can leave the complete file present: inspect status before
427
+ retrying. Restart the bridge to sign its own device using the restored keys.
428
+ A readable local file alone does not prove server/device verification. Import
429
+ restores account-signing keys, not historical encrypted-room message keys.
430
+
431
+ Ordinary login preserves account signing keys and cannot reconstruct missing
432
+ private material. Only when no matching backup exists should an operator
433
+ consider authenticated login with --reset-cross-signing; it replaces the account
434
+ identity and requires verification again in other clients. Stop the running
435
+ bridge before using `medre diagnostics --refresh-health`, which opens adapters.
436
+
437
+ The opt-in `test_matrix_durable_runtime_live.py` proof takes explicit local
438
+ homeserver accounts through environment variables. It runs the real MEDRE
439
+ runtime with durable storage and a fake destination across a restart, and
440
+ fails when native ingress fails. `MATRIX_ENCRYPTED=1` selects genuine Megolm
441
+ traffic; use fresh account/device stores for each independent run. The core
442
+ Synapse Docker starter can provision the isolated accounts.