medre-adapter-chatmail 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 (49) hide show
  1. medre_adapter_chatmail-0.1.0/LICENSE +21 -0
  2. medre_adapter_chatmail-0.1.0/PKG-INFO +232 -0
  3. medre_adapter_chatmail-0.1.0/README.md +212 -0
  4. medre_adapter_chatmail-0.1.0/pyproject.toml +75 -0
  5. medre_adapter_chatmail-0.1.0/setup.cfg +4 -0
  6. medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/__init__.py +1 -0
  7. medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/adapter.py +773 -0
  8. medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/cli.py +253 -0
  9. medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/cli_contrib.py +63 -0
  10. medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/codec.py +182 -0
  11. medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/compat.py +5 -0
  12. medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/config.py +170 -0
  13. medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/fake.py +109 -0
  14. medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/metadata.py +39 -0
  15. medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/plugin.py +120 -0
  16. medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/py.typed +0 -0
  17. medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/renderer.py +185 -0
  18. medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/sample.py +9 -0
  19. medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/session.py +316 -0
  20. medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/state.py +209 -0
  21. medre_adapter_chatmail-0.1.0/src/medre/adapters/chatmail/stopped_declaration.py +334 -0
  22. medre_adapter_chatmail-0.1.0/src/medre_adapter_chatmail.egg-info/PKG-INFO +232 -0
  23. medre_adapter_chatmail-0.1.0/src/medre_adapter_chatmail.egg-info/SOURCES.txt +47 -0
  24. medre_adapter_chatmail-0.1.0/src/medre_adapter_chatmail.egg-info/dependency_links.txt +1 -0
  25. medre_adapter_chatmail-0.1.0/src/medre_adapter_chatmail.egg-info/entry_points.txt +5 -0
  26. medre_adapter_chatmail-0.1.0/src/medre_adapter_chatmail.egg-info/requires.txt +10 -0
  27. medre_adapter_chatmail-0.1.0/src/medre_adapter_chatmail.egg-info/top_level.txt +1 -0
  28. medre_adapter_chatmail-0.1.0/tests/test_chatmail_rpc_retirement_sdk.py +504 -0
  29. medre_adapter_chatmail-0.1.0/tests/test_cli.py +280 -0
  30. medre_adapter_chatmail-0.1.0/tests/test_cli_contrib.py +92 -0
  31. medre_adapter_chatmail-0.1.0/tests/test_common_diagnostics.py +50 -0
  32. medre_adapter_chatmail-0.1.0/tests/test_config_codec_renderer.py +348 -0
  33. medre_adapter_chatmail-0.1.0/tests/test_distribution_license.py +28 -0
  34. medre_adapter_chatmail-0.1.0/tests/test_durable_runtime.py +595 -0
  35. medre_adapter_chatmail-0.1.0/tests/test_live.py +256 -0
  36. medre_adapter_chatmail-0.1.0/tests/test_native_health.py +153 -0
  37. medre_adapter_chatmail-0.1.0/tests/test_native_reply.py +527 -0
  38. medre_adapter_chatmail-0.1.0/tests/test_native_reply_sdk.py +26 -0
  39. medre_adapter_chatmail-0.1.0/tests/test_native_sender_attribution.py +271 -0
  40. medre_adapter_chatmail-0.1.0/tests/test_native_setup_instructions.py +217 -0
  41. medre_adapter_chatmail-0.1.0/tests/test_pin_literal_hygiene.py +124 -0
  42. medre_adapter_chatmail-0.1.0/tests/test_plugin_api_version.py +11 -0
  43. medre_adapter_chatmail-0.1.0/tests/test_project_tooling.py +78 -0
  44. medre_adapter_chatmail-0.1.0/tests/test_recorded_native_reply_evidence.py +108 -0
  45. medre_adapter_chatmail-0.1.0/tests/test_relay_prefix_surface.py +78 -0
  46. medre_adapter_chatmail-0.1.0/tests/test_review_regressions.py +124 -0
  47. medre_adapter_chatmail-0.1.0/tests/test_sdk_contract.py +100 -0
  48. medre_adapter_chatmail-0.1.0/tests/test_stopped_declaration.py +366 -0
  49. medre_adapter_chatmail-0.1.0/tests/test_stopped_native_restore.py +178 -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,232 @@
1
+ Metadata-Version: 2.4
2
+ Name: medre-adapter-chatmail
3
+ Version: 0.1.0
4
+ Summary: Chatmail conversations for MEDRE through the official core RPC client
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: deltachat-rpc-client==2.69.0
12
+ Requires-Dist: deltachat-rpc-server==2.69.0
13
+ Provides-Extra: test
14
+ Requires-Dist: pytest==9.2.0; extra == "test"
15
+ Requires-Dist: pytest-asyncio==1.5.0; extra == "test"
16
+ Requires-Dist: pytest-timeout==2.4.0; extra == "test"
17
+ Requires-Dist: pytest-cov==7.1.0; extra == "test"
18
+ Requires-Dist: jsonschema==4.26.0; extra == "test"
19
+ Dynamic: license-file
20
+
21
+ # MEDRE Chatmail adapter
22
+
23
+ Bridge accepted Chatmail group conversations and direct chats through the official
24
+ Python RPC client and native Chatmail core. The provider supplies plain-text
25
+ rendering, durable ingress checkpoints, a bounded outbound queue, and an
26
+ SDK-free fake for offline development.
27
+
28
+ ## Install
29
+
30
+ For a persistent bridge, keep core and adapters in one locked uv project:
31
+
32
+ ```bash
33
+ uv init --bare medre-bridge
34
+ cd medre-bridge
35
+ uv add 'medre @ git+https://github.com/jeremiah-k/medre.git@main' \
36
+ 'medre-adapter-chatmail @ git+https://github.com/jeremiah-k/medre-adapter-chatmail.git@main'
37
+ ```
38
+
39
+ Both RPC packages are installed together; no Rust build or separate daemon
40
+ installation is needed. Use immutable Git revisions for reproducible deployments.
41
+ `uv run --locked` preserves the project lock when starting commands.
42
+
43
+ For a persistent MEDRE tool installation, `medre adapters install chatmail`
44
+ adds the provider to the same environment. Provision through `medre adapter
45
+ chatmail`; a separately exposed helper executable is unnecessary. The
46
+ standalone `medre-chatmail` entry point remains available in activated project
47
+ environments and uses the same arguments and execution path.
48
+
49
+ ## Set up a profile
50
+
51
+ Provisioning proceeds through explicit stages: prerequisites, profile
52
+ provisioning, conversation acceptance and discovery, then offline
53
+ configuration and verification. Profile creation and invitation acceptance
54
+ happen only on these commands; runtime startup never creates an identity or
55
+ accepts an invitation. Chatmail declares no `medre config native` form:
56
+ a profile needs the pinned native tooling that `medre adapter chatmail`
57
+ drives, so the provider contributes these commands instead of an offline
58
+ setup form. On cores that provide the typed setup-instructions seam, the
59
+ provider declares this journey as ordered setup instructions and
60
+ `medre config native --transport chatmail --adapter-id mail --output PATH`
61
+ renders it offline with an `informational_only` classification: the
62
+ contributed commands appear verbatim with a purpose and an evidence note
63
+ each, core never executes them, and no file is written. On older cores this
64
+ README remains the source of the journey. Each stage below states what its
65
+ observations prove and what they leave unproven.
66
+
67
+ > The commands in this journey use `--adapter mail` as an **example** instance.
68
+ > Replace that value consistently with the actual configured provider ID before
69
+ > running commands. `medre config native` displays instructions only; it does
70
+ > not substitute IDs, provision accounts, or create a bridge.
71
+
72
+ ### Prerequisites
73
+
74
+ - The provider installed in MEDRE's environment (above), with the RPC client
75
+ and native server it ships together.
76
+ - A relay's private `DCACCOUNT:` or `DCLOGIN:` QR payload for `init`.
77
+ - An invitation QR payload (`OPENPGP4FPR:` or an `i.delta.chat` link) for
78
+ each conversation to bridge.
79
+ - A terminal with echo control for hidden input, or `--qr-stdin` for
80
+ automation. Credentials never belong in command arguments or committed
81
+ files.
82
+ - The bridge stopped and no other client using the profile. The profile is
83
+ dedicated to one adapter instance; concurrent MEDRE commands refuse the
84
+ profile lock, and an unrelated Chatmail client does not honor that lock.
85
+
86
+ ### Stage 1: provision the profile
87
+
88
+ ```bash
89
+ uv run --locked medre adapter chatmail init --adapter mail
90
+ uv run --locked medre adapter chatmail accounts --adapter mail
91
+ ```
92
+
93
+ `init` reads the relay's private QR payload with hidden terminal input,
94
+ creates the profile on this explicit command only, and keeps an existing
95
+ configured account. `accounts` lists local account IDs and their configured
96
+ state without exposing credentials. A configured profile proves that the
97
+ native core reports this account configured. Profile provisioning is not
98
+ relay service acceptance: relay-side limits surface only through later
99
+ delivery feedback, and this stage sends nothing.
100
+
101
+ ### Stage 2: accept conversations and discover chat IDs
102
+
103
+ ```bash
104
+ uv run --locked medre adapter chatmail join --adapter mail
105
+ uv run --locked medre adapter chatmail chats --adapter mail --groups --json
106
+ ```
107
+
108
+ `join` reads one contact or group invitation, completes the native secure
109
+ join for it, and waits until the native core reports that the chat can send.
110
+ `chats` lists ordinary conversations of this profile, groups first;
111
+ `--groups` limits discovery to groups, and omitting it includes direct
112
+ conversations. A joined chat proves that this conversation is accepted and
113
+ natively sendable. It does not prove that bridge messages reach their
114
+ recipients.
115
+
116
+ ### Stage 3: configure and verify offline
117
+
118
+ Save a private `connections.yaml` using the accepted chat IDs from `chats`:
119
+
120
+ ```yaml
121
+ adapters:
122
+ chatmail:
123
+ mail:
124
+ adapter_kind: real
125
+ account_id: 1 # Replace with the ID reported by 'accounts'.
126
+ chats: [12] # Replace with the accepted chat IDs from this profile.
127
+ origin_label: Chatmail
128
+ ```
129
+
130
+ Then validate without contacting the profile:
131
+
132
+ ```bash
133
+ uv run --locked medre config check --config connections.yaml
134
+ uv run --locked medre routes plan --config connections.yaml
135
+ ```
136
+
137
+ Both commands run entirely offline against the typed configuration model.
138
+ This fragment describes one connection, not a complete bridge: its route plan
139
+ has no delivery legs until a second adapter and explicit routes are added.
140
+ Use `medre config bridge` to construct those legs, then run both checks again.
141
+ Neither a valid config nor a nonempty route plan proves peer delivery.
142
+ `medre smoke` exercises the SDK-free fake only; real configurations are
143
+ rejected by fake smoke. An initial `deferred` result with `local_queue`
144
+ confirmation records retention in the private pending-delivery journal only;
145
+ SMTP handoff is pending. Later correlated `remote_service` feedback confirms
146
+ SMTP-server acceptance, with notes differentiated by native state: the outgoing
147
+ server accepted the message but recipient delivery and reading are unconfirmed,
148
+ or a native MDN (read receipt) confirms reading.
149
+
150
+ ## Configuration reference
151
+
152
+ Add routes using decimal channel strings, such as `source_channel: "12"` or
153
+ `dest_channel: "12"`. Chat IDs are local to a profile; contact addresses are not
154
+ used to guess conversation identity. Run `medre config check` before starting
155
+ the bridge. Explicit `accounts_dir`, `state_dir` and `rpc_server_path` overrides
156
+ are available for existing profiles and native server installations.
157
+
158
+ Profiles default to MEDRE's instance state directory, under
159
+ `adapters/mail/chatmail/accounts`. `MEDRE_HOME` and the usual XDG paths are
160
+ honored. Use the same `--adapter` and `--accounts-dir` options for setup and
161
+ runtime configuration. Once a runtime YAML exists, `--config bridge.yaml
162
+ --adapter mail` selects its profile and account directly, including for the
163
+ `chats` discovery above.
164
+
165
+ Use `--qr-stdin` to supply a QR payload through standard input in automation.
166
+ Keep the profile, MEDRE database and pending-delivery journal together when
167
+ backing up state.
168
+
169
+ ## Delivery and rendering
170
+
171
+ - Preserve plain text and MEDRE attribution. When core uniquely binds an earlier
172
+ message to a native reference in the same private profile and chat,
173
+ a reply uses Delta Chat's native quote UI (`quotedMessageId`). If the target
174
+ cannot be verified, retain a readable inline reply instead. Threads still use
175
+ core's inline fallback. Refuse text exceeding the configured UTF-8 budget.
176
+ - Baseline existing history on first use. Resume after the last durable checkpoint
177
+ on subsequent starts, committing the cursor only after canonical admission.
178
+ - Keep partial text messages pending. Exclude self echoes, blocked contacts,
179
+ informational controls, edits and unsupported media from fresh-message ingress.
180
+ - Return local queue admission as deferred delivery. Report SMTP acceptance only
181
+ after the native core confirms outgoing-server acceptance; recipient delivery
182
+ and reading remain unconfirmed without separate MDN evidence. Neither claims
183
+ relay acceptance or bridge confidentiality.
184
+ - Retain exact attempt/native-ID correlation until core accepts delivery feedback.
185
+ Recover correlated native jobs without resending. Abandon unsent or uncertain
186
+ work recovered across a restart, requiring inspection before an explicit retry.
187
+ - Expose encryption/signature observations in native metadata, alongside the
188
+ sender's chatmail address, native send/receive timestamps and validated
189
+ conversation facts; attribution carries the address as the sender handle.
190
+ A bounded opted-in `public_facts` projection (currently
191
+ `encrypted_and_signed`) feeds core's transport-neutral bridge context.
192
+ Confidentiality across the bridge and identity puppeting are not implied.
193
+
194
+ Attachments, native edits/deletes/reactions, forwarded read receipts, typing
195
+ notifications and puppeting are not advertised. The native core owns SMTP/IMAP,
196
+ cryptography, protocol retries and account storage. MEDRE owns routing and
197
+ lifecycle authority.
198
+
199
+ See the [provider contract](docs/spec/chatmail.md) and
200
+ [configuration schema](docs/schemas/config.schema.json).
201
+
202
+ ## Develop and test
203
+
204
+ Use the locked uv development workflow in [contributing](CONTRIBUTING.md).
205
+ It supports core and provider checkouts at arbitrary locations; select the
206
+ native SDK tier explicitly after synchronization.
207
+
208
+ The default tier excludes native SDK and live tests. The SDK tier runs the actual
209
+ pinned RPC client and server against temporary local profiles without an external
210
+ mail service. CI runs both tiers on Python 3.11–3.14 and qualifies the adapter
211
+ against core `main`, resolved once per run. Keep `MEDRE_CORE_REF` unset;
212
+ workflow dispatch accepts an exact candidate core revision.
213
+ The run summary records both resolved commit IDs. SDK constraints are exported
214
+ from core's lock without installing private core test helpers into this provider.
215
+
216
+ The [live test](tests/test_live.py) accepts an explicitly prepared relay/profile
217
+ fixture. Native quote presentation requires that independent-peer campaign on
218
+ the candidate revision before merging or releasing native reply support; API-shape
219
+ tests alone do not qualify it. See [live testing](docs/live-testing.md). All service fixtures use
220
+ ordinary container permissions; no host system configuration is required by this
221
+ provider's tests.
222
+
223
+ Per-message native sender attribution is enabled by default. Delta Chat recipients
224
+ see the original sender and origin as a message display name while the bridge
225
+ account and contact profile remain unchanged. Set `native_sender_attribution: false`
226
+ to keep only the configured body prefix. See [the provider contract](docs/spec/chatmail.md#per-message-native-attribution)
227
+ and [the two-receipt native qualification](docs/evidence/native-sender-2026-10-25.json).
228
+
229
+ ## Development tooling
230
+
231
+ See [contributing](CONTRIBUTING.md) for the shared Trunk quality gate and uv-based
232
+ editable development workflow.
@@ -0,0 +1,212 @@
1
+ # MEDRE Chatmail adapter
2
+
3
+ Bridge accepted Chatmail group conversations and direct chats through the official
4
+ Python RPC client and native Chatmail core. The provider supplies plain-text
5
+ rendering, durable ingress checkpoints, a bounded outbound queue, and an
6
+ SDK-free fake for offline development.
7
+
8
+ ## Install
9
+
10
+ For a persistent bridge, keep core and adapters in one locked uv project:
11
+
12
+ ```bash
13
+ uv init --bare medre-bridge
14
+ cd medre-bridge
15
+ uv add 'medre @ git+https://github.com/jeremiah-k/medre.git@main' \
16
+ 'medre-adapter-chatmail @ git+https://github.com/jeremiah-k/medre-adapter-chatmail.git@main'
17
+ ```
18
+
19
+ Both RPC packages are installed together; no Rust build or separate daemon
20
+ installation is needed. Use immutable Git revisions for reproducible deployments.
21
+ `uv run --locked` preserves the project lock when starting commands.
22
+
23
+ For a persistent MEDRE tool installation, `medre adapters install chatmail`
24
+ adds the provider to the same environment. Provision through `medre adapter
25
+ chatmail`; a separately exposed helper executable is unnecessary. The
26
+ standalone `medre-chatmail` entry point remains available in activated project
27
+ environments and uses the same arguments and execution path.
28
+
29
+ ## Set up a profile
30
+
31
+ Provisioning proceeds through explicit stages: prerequisites, profile
32
+ provisioning, conversation acceptance and discovery, then offline
33
+ configuration and verification. Profile creation and invitation acceptance
34
+ happen only on these commands; runtime startup never creates an identity or
35
+ accepts an invitation. Chatmail declares no `medre config native` form:
36
+ a profile needs the pinned native tooling that `medre adapter chatmail`
37
+ drives, so the provider contributes these commands instead of an offline
38
+ setup form. On cores that provide the typed setup-instructions seam, the
39
+ provider declares this journey as ordered setup instructions and
40
+ `medre config native --transport chatmail --adapter-id mail --output PATH`
41
+ renders it offline with an `informational_only` classification: the
42
+ contributed commands appear verbatim with a purpose and an evidence note
43
+ each, core never executes them, and no file is written. On older cores this
44
+ README remains the source of the journey. Each stage below states what its
45
+ observations prove and what they leave unproven.
46
+
47
+ > The commands in this journey use `--adapter mail` as an **example** instance.
48
+ > Replace that value consistently with the actual configured provider ID before
49
+ > running commands. `medre config native` displays instructions only; it does
50
+ > not substitute IDs, provision accounts, or create a bridge.
51
+
52
+ ### Prerequisites
53
+
54
+ - The provider installed in MEDRE's environment (above), with the RPC client
55
+ and native server it ships together.
56
+ - A relay's private `DCACCOUNT:` or `DCLOGIN:` QR payload for `init`.
57
+ - An invitation QR payload (`OPENPGP4FPR:` or an `i.delta.chat` link) for
58
+ each conversation to bridge.
59
+ - A terminal with echo control for hidden input, or `--qr-stdin` for
60
+ automation. Credentials never belong in command arguments or committed
61
+ files.
62
+ - The bridge stopped and no other client using the profile. The profile is
63
+ dedicated to one adapter instance; concurrent MEDRE commands refuse the
64
+ profile lock, and an unrelated Chatmail client does not honor that lock.
65
+
66
+ ### Stage 1: provision the profile
67
+
68
+ ```bash
69
+ uv run --locked medre adapter chatmail init --adapter mail
70
+ uv run --locked medre adapter chatmail accounts --adapter mail
71
+ ```
72
+
73
+ `init` reads the relay's private QR payload with hidden terminal input,
74
+ creates the profile on this explicit command only, and keeps an existing
75
+ configured account. `accounts` lists local account IDs and their configured
76
+ state without exposing credentials. A configured profile proves that the
77
+ native core reports this account configured. Profile provisioning is not
78
+ relay service acceptance: relay-side limits surface only through later
79
+ delivery feedback, and this stage sends nothing.
80
+
81
+ ### Stage 2: accept conversations and discover chat IDs
82
+
83
+ ```bash
84
+ uv run --locked medre adapter chatmail join --adapter mail
85
+ uv run --locked medre adapter chatmail chats --adapter mail --groups --json
86
+ ```
87
+
88
+ `join` reads one contact or group invitation, completes the native secure
89
+ join for it, and waits until the native core reports that the chat can send.
90
+ `chats` lists ordinary conversations of this profile, groups first;
91
+ `--groups` limits discovery to groups, and omitting it includes direct
92
+ conversations. A joined chat proves that this conversation is accepted and
93
+ natively sendable. It does not prove that bridge messages reach their
94
+ recipients.
95
+
96
+ ### Stage 3: configure and verify offline
97
+
98
+ Save a private `connections.yaml` using the accepted chat IDs from `chats`:
99
+
100
+ ```yaml
101
+ adapters:
102
+ chatmail:
103
+ mail:
104
+ adapter_kind: real
105
+ account_id: 1 # Replace with the ID reported by 'accounts'.
106
+ chats: [12] # Replace with the accepted chat IDs from this profile.
107
+ origin_label: Chatmail
108
+ ```
109
+
110
+ Then validate without contacting the profile:
111
+
112
+ ```bash
113
+ uv run --locked medre config check --config connections.yaml
114
+ uv run --locked medre routes plan --config connections.yaml
115
+ ```
116
+
117
+ Both commands run entirely offline against the typed configuration model.
118
+ This fragment describes one connection, not a complete bridge: its route plan
119
+ has no delivery legs until a second adapter and explicit routes are added.
120
+ Use `medre config bridge` to construct those legs, then run both checks again.
121
+ Neither a valid config nor a nonempty route plan proves peer delivery.
122
+ `medre smoke` exercises the SDK-free fake only; real configurations are
123
+ rejected by fake smoke. An initial `deferred` result with `local_queue`
124
+ confirmation records retention in the private pending-delivery journal only;
125
+ SMTP handoff is pending. Later correlated `remote_service` feedback confirms
126
+ SMTP-server acceptance, with notes differentiated by native state: the outgoing
127
+ server accepted the message but recipient delivery and reading are unconfirmed,
128
+ or a native MDN (read receipt) confirms reading.
129
+
130
+ ## Configuration reference
131
+
132
+ Add routes using decimal channel strings, such as `source_channel: "12"` or
133
+ `dest_channel: "12"`. Chat IDs are local to a profile; contact addresses are not
134
+ used to guess conversation identity. Run `medre config check` before starting
135
+ the bridge. Explicit `accounts_dir`, `state_dir` and `rpc_server_path` overrides
136
+ are available for existing profiles and native server installations.
137
+
138
+ Profiles default to MEDRE's instance state directory, under
139
+ `adapters/mail/chatmail/accounts`. `MEDRE_HOME` and the usual XDG paths are
140
+ honored. Use the same `--adapter` and `--accounts-dir` options for setup and
141
+ runtime configuration. Once a runtime YAML exists, `--config bridge.yaml
142
+ --adapter mail` selects its profile and account directly, including for the
143
+ `chats` discovery above.
144
+
145
+ Use `--qr-stdin` to supply a QR payload through standard input in automation.
146
+ Keep the profile, MEDRE database and pending-delivery journal together when
147
+ backing up state.
148
+
149
+ ## Delivery and rendering
150
+
151
+ - Preserve plain text and MEDRE attribution. When core uniquely binds an earlier
152
+ message to a native reference in the same private profile and chat,
153
+ a reply uses Delta Chat's native quote UI (`quotedMessageId`). If the target
154
+ cannot be verified, retain a readable inline reply instead. Threads still use
155
+ core's inline fallback. Refuse text exceeding the configured UTF-8 budget.
156
+ - Baseline existing history on first use. Resume after the last durable checkpoint
157
+ on subsequent starts, committing the cursor only after canonical admission.
158
+ - Keep partial text messages pending. Exclude self echoes, blocked contacts,
159
+ informational controls, edits and unsupported media from fresh-message ingress.
160
+ - Return local queue admission as deferred delivery. Report SMTP acceptance only
161
+ after the native core confirms outgoing-server acceptance; recipient delivery
162
+ and reading remain unconfirmed without separate MDN evidence. Neither claims
163
+ relay acceptance or bridge confidentiality.
164
+ - Retain exact attempt/native-ID correlation until core accepts delivery feedback.
165
+ Recover correlated native jobs without resending. Abandon unsent or uncertain
166
+ work recovered across a restart, requiring inspection before an explicit retry.
167
+ - Expose encryption/signature observations in native metadata, alongside the
168
+ sender's chatmail address, native send/receive timestamps and validated
169
+ conversation facts; attribution carries the address as the sender handle.
170
+ A bounded opted-in `public_facts` projection (currently
171
+ `encrypted_and_signed`) feeds core's transport-neutral bridge context.
172
+ Confidentiality across the bridge and identity puppeting are not implied.
173
+
174
+ Attachments, native edits/deletes/reactions, forwarded read receipts, typing
175
+ notifications and puppeting are not advertised. The native core owns SMTP/IMAP,
176
+ cryptography, protocol retries and account storage. MEDRE owns routing and
177
+ lifecycle authority.
178
+
179
+ See the [provider contract](docs/spec/chatmail.md) and
180
+ [configuration schema](docs/schemas/config.schema.json).
181
+
182
+ ## Develop and test
183
+
184
+ Use the locked uv development workflow in [contributing](CONTRIBUTING.md).
185
+ It supports core and provider checkouts at arbitrary locations; select the
186
+ native SDK tier explicitly after synchronization.
187
+
188
+ The default tier excludes native SDK and live tests. The SDK tier runs the actual
189
+ pinned RPC client and server against temporary local profiles without an external
190
+ mail service. CI runs both tiers on Python 3.11–3.14 and qualifies the adapter
191
+ against core `main`, resolved once per run. Keep `MEDRE_CORE_REF` unset;
192
+ workflow dispatch accepts an exact candidate core revision.
193
+ The run summary records both resolved commit IDs. SDK constraints are exported
194
+ from core's lock without installing private core test helpers into this provider.
195
+
196
+ The [live test](tests/test_live.py) accepts an explicitly prepared relay/profile
197
+ fixture. Native quote presentation requires that independent-peer campaign on
198
+ the candidate revision before merging or releasing native reply support; API-shape
199
+ tests alone do not qualify it. See [live testing](docs/live-testing.md). All service fixtures use
200
+ ordinary container permissions; no host system configuration is required by this
201
+ provider's tests.
202
+
203
+ Per-message native sender attribution is enabled by default. Delta Chat recipients
204
+ see the original sender and origin as a message display name while the bridge
205
+ account and contact profile remain unchanged. Set `native_sender_attribution: false`
206
+ to keep only the configured body prefix. See [the provider contract](docs/spec/chatmail.md#per-message-native-attribution)
207
+ and [the two-receipt native qualification](docs/evidence/native-sender-2026-10-25.json).
208
+
209
+ ## Development tooling
210
+
211
+ See [contributing](CONTRIBUTING.md) for the shared Trunk quality gate and uv-based
212
+ editable development workflow.
@@ -0,0 +1,75 @@
1
+ [project]
2
+ name = "medre-adapter-chatmail"
3
+ version = "0.1.0"
4
+ description = "Chatmail conversations for MEDRE through the official core RPC client"
5
+ readme = "README.md"
6
+ requires-python = ">=3.11"
7
+ license = "MIT"
8
+ classifiers = ["Typing :: Typed"]
9
+ dependencies = [
10
+ "medre>=0.1.0,<0.2.0",
11
+ "deltachat-rpc-client==2.69.0",
12
+ "deltachat-rpc-server==2.69.0",
13
+ ]
14
+
15
+ [project.scripts]
16
+ medre-chatmail = "medre.adapters.chatmail.cli:main"
17
+
18
+ [project.entry-points."medre.adapters"]
19
+ chatmail = "medre.adapters.chatmail.plugin:adapter_spec"
20
+
21
+ [project.optional-dependencies]
22
+ test = [
23
+ "pytest==9.2.0",
24
+ "pytest-asyncio==1.5.0",
25
+ "pytest-timeout==2.4.0",
26
+ "pytest-cov==7.1.0",
27
+ "jsonschema==4.26.0",
28
+ ]
29
+
30
+ [build-system]
31
+ requires = ["setuptools>=77"]
32
+ build-backend = "setuptools.build_meta"
33
+
34
+ [tool.setuptools.packages.find]
35
+ where = ["src"]
36
+
37
+ [tool.setuptools.package-data]
38
+ "medre.adapters.chatmail" = ["py.typed"]
39
+
40
+ [tool.pytest.ini_options]
41
+ asyncio_mode = "auto"
42
+ asyncio_default_fixture_loop_scope = "function"
43
+ testpaths = ["tests"]
44
+ pythonpath = ["src"]
45
+ filterwarnings = ["error"]
46
+ timeout = 30
47
+ addopts = "-m 'not chatmail_sdk and not live'"
48
+ markers = [
49
+ "chatmail_sdk: contracts against the released RPC client and native server",
50
+ "live: opt-in tests against an explicitly configured Chatmail relay",
51
+ ]
52
+
53
+ [tool.ruff]
54
+ line-length = 88
55
+
56
+ [tool.ruff.lint]
57
+ select = ["F", "E4", "E7", "E9", "B", "ASYNC", "RUF100"]
58
+ # Lifecycle timeout parameters implement the MEDRE contract.
59
+ ignore = ["ASYNC109"]
60
+
61
+ [tool.black]
62
+ target-version = ["py311"]
63
+
64
+ [tool.mypy]
65
+ python_version = "3.11"
66
+ strict = true
67
+ explicit_package_bases = true
68
+ follow_imports = "silent"
69
+
70
+ [[tool.mypy.overrides]]
71
+ module = ["deltachat_rpc_client", "deltachat_rpc_client.*"]
72
+ ignore_missing_imports = true
73
+
74
+ [tool.isort]
75
+ profile = "black"
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1 @@
1
+ """Chatmail provider; SDK imports belong to the native session boundary."""