New mailbox onboarding no longer floods Telegram with the entire
mailbox history. The initial baseline walk (ReconcileCursor::Walk,
any position) now passes an EmailQueryFilter to list_emails_page that
bounds Email/query to messages received within the last 7 days and
not yet seen ($seen keyword, RFC 8621 §4.1.2).
- EmailQueryFilter { received_after: Option<i64>, unread_only: bool }
in src/domain/jmap.rs (backend-agnostic domain type).
- StalwartJmap::fetch_email_page builds a compound Filter::and from
the filter conditions (after + not_keyword "$seen").
- walk_baseline computes the 7-day cutoff once and passes it to
every page fetch, so resumed walks stay filtered.
- Replay(state) path returns early and never calls list_emails_page,
so /changes incremental is unaffected.
- const INITIAL_BASELINE_WINDOW_DAYS: u64 = 7.
- New test first_reconcile_filters_the_initial_baseline_to_recent_unread
pins the filter on every Walk page and the cursor transition to Replay.
- 3 doc anchors re-anchored (worker.rs:227→241, client.rs:485→513 ×2).
GATE-P0: 104 passed / 0 failed / 4 ignored.
Two layers were masking the real cause of reconcile failures:
1. Backend: worker.rs reconciled all JMAP/Redis failures into Err(()),
so handle_reconcile returned 503 with {"error":"reconcile_retry"} but
no indication of WHICH step broke. Now reconcile() returns
Result<String, &'static str> with diagnostic codes:
- jmap_session_failed — session_state() failed (JMAP unreachable/auth)
- jmap_list_failed — list_emails_page() failed
- reconcile_budget_exhausted — budget/pages exhausted before any progress
- reconcile_no_progress — walk made no progress
- reconcile_lease_lost — background heartbeat lost the lock
- reconcile_state_write_failed — set_reconcile_state() Redis failure
- enqueue_failed — claim_dedup_and_enqueue() Redis failure
The 503 body now includes a "reason" field alongside the documented
"reconcile_retry" error code, so operators can see the cause without
server-side logs. The error code is unchanged (stable contract for
cron-drain.sh and other callers).
2. Cloudflare Worker LB: forwardWithFailover treated all 5xx as backend
failure and replaced the real response body with synthesized
"all backends failed: ..." text. Now the last 5xx HTTP response is
kept and passed through, so the backend's real error body (including
the new reason field) reaches the client. Pure network errors (no HTTP
response at all) still get the synthesized 503 fallback.
Break long compound sentences into shorter ones across both EN and ZH
READMEs without losing any detail. Improves readability of security
model, deployment, and operational sections.
Bare domains like messageweave.example work without the https:// prefix.
Old --*-url flags and MW_*_URL env vars still work as aliases.
Flag values override env vars; defaults applied after parsing.
The previous callout said "secrets must be re-entered on each full
save", which contradicted the field-level hint "leave blank; the
saved value stays". The actual contract: empty secret = keep saved
value (backend apply merge), required only on first setup.
Rewrite the callout (web/index.html + web/config.js, zh/en) to three
short sentences and make it consistent with secret.keepSet /
telegram.workerHint:
- Secrets are stored server-side and never echoed.
- Leave a secret blank to keep its saved value; required on first
setup.
- Other fields are read back automatically.
Dropped the "sent as <code>null</code>" sentence (too technical; field
hints already cover it) and removed the orphaned <code>null</code>
element. Dropped "always uses the primary account" -- the SPA has no
account_id field to move it to, so it is removed from the callout.
No JS logic changes; applyI18n just sets textContent on [data-i18n]
elements, so the <code> removal is safe. GATE-DOCS 6/6 PASS.
The hand-holding tutorial in README §3.6 didn't mention that with
multiple backends behind a load balancer, you only need to configure
on any one node — all backends share one Redis. deployment.md §10.2
covers this, but the tutorial is what users follow during setup.
Per the strengthened acceptance: re-applying a complete patch whose values
equal the already-stored wire must yield an equal wire. Builds the patch
from the wire (patch_from_wire helper) and compares serialized forms, since
BusinessConfigWire does not derive PartialEq. Closes the four-case truth
table: first-save complete, first-save fragment, partial-over-stored merge,
and now same-value idempotence.
Test baseline: 102 -> 103 passed, 0 failed, 4 ignored.
Four copy fixes on the SPA configuration page (web/index.html +
web/config.js). All string-only except one 1-line status override
in the runtime save handler.
1. Callout: "Business configuration is not read from the server" ->
"Business configuration is encrypted in Redis". The old text
contradicted GET /api/business-config, which reads non-secret
fields back. New copy states secrets are not echoed but non-secret
fields are read back; the first save must include all required
secrets.
2. Save feedback: after saving runtime parameters the status line
reused runtime.loaded ("read from Redis"), which is wrong for a
save. Added runtime.savedState ("Saved and applied successfully.")
and set it in the save handler. Dropped the stale "business
config still needs manual filling" sentence from runtime.readToast,
which also contradicted readback.
3. LLM toggle: "Allow network calls" -> "Enable LLM outbound
requests"; the hint now states no LLM client is initialized and
the bot calls no external model service when off.
4. All fixes applied to both zh and en dictionaries and to the HTML
English fallback defaults for consistency.
GATE-DOCS 6/6 PASS. No src/, cloudflare-worker/, or docs/ changes.
`BusinessConfigPatch::apply()` bound `let fallback = stored.expect(...)`
eagerly, so on a first save (stored=None, is_complete() true) it panicked at
bind time before any field was read. A brand-new Redis could not accept a
complete first save — every Save button hit the panic and surfaced as a 502.
Replace the eager expect with a `match stored` that, on `None`, builds the
wire straight from the patch (every required field is named because
is_complete() just proved it; the four Option<Option<String>> fields fall back
to None, their correct stored value on a first save). The stored-configuration
merge branch is unchanged.
Adds three regression tests: first-save with a complete patch (the panic
repro, now green), first-save with an incomplete patch (returns None), and a
partial patch merged into a stored wire (unmentioned fields keep stored).
Test baseline: 99 -> 102 passed, 0 failed, 4 ignored.
The sentence explained why RUN_MODE doesn't exist — but if it doesn't
exist, there's nothing to explain. Removed from README (EN+ZH) §4 and
reference (EN+ZH) §5.1. Also fixed Chinese curly quotes to backticks
on the DEBUG_TOKEN row in reference.zh-CN.md §5.1.
Two changes requested by the user:
1. Fold the hand-holding quickstart tutorial into README §3 (both
languages). Delete docs/quickstart.md and docs/quickstart.zh-CN.md.
Remove them from all 5 validator DOCS lists, README §6 doc index,
and charter §7 boundary table. The tutorial now lives as
README §3.0–§3.11: prerequisites, create Telegram bot, find chat id,
get JMAP credentials, run backend, sign in, fill config, register
callbacks, enable processing, verify, schedule drain, troubleshoot.
2. Replace 'gateway'/'网关' with 'load balancer'/'负载均衡器' across
all markdown (README, docs/, AGENTS.md, cloudflare-worker/README).
Also fix 4 markdown anchor links whose heading slugs changed.
Also fix charter §8 '18 safe routes' → '19' (was missed in the
earlier reference.md fix).
GATE-DOCS 6/6 PASS (71 anchors, 727 path-refs, 455 sec-refs).
New docs/quickstart.md and docs/quickstart.zh-CN.md walk a human operator from
zero to the first notification: create a Telegram bot via BotFather, find the
chat id, get a Stalwart app password, provision Redis, deploy the container,
sign in with CONFIG_ENCRYPTION_KEY, fill the business config, register
callbacks, enable processing, verify end-to-end, and schedule the cron drain.
Every claim was verified against the code:
- healthz is static 200 'ok'; /ready returns 503 until all upstreams
reachable, 200 with per-component booleans
- admin session TTL = 1800s (30 min) in state.rs
- first save must be complete -> 422 (is_complete in config.rs)
- 409 conflict on revision mismatch
- secrets are write-only (Option<SecretString>, never echoed)
- /worker and /reconcile return 204 on success, 503 when disabled
- webhook secret mismatch returns 401 (not 403)
- search triggers: 搜索/查找/检索 + /search command only
- cron-drain.sh uses MW_APP_URL (req), MW_WORKER_TOKEN (req),
MW_RECONCILE_TOKEN (opt)
Registered both files in all 5 validator DOCS lists (audit_paths globs
automatically). Added rows to README §6 and charter §7 in both languages.
Added discoverable links from README §3 to the quickstart.
GATE-DOCS 6/6 PASS (71 anchors, 735 path-refs).
The U+200B sweep from 5f182f9 also collapsed leading whitespace to a
single space on 140 lines. That silently wrecked the fenced ASCII
architecture diagram, the tree listings and the indented JSON/Rust code
blocks in design.md.
This commit restores HEAD^'s indentation and re-applies only the intended
content edits from 5f182f9 (11 lines in section 5.6/5.7, plus the 14
ZWSP characters). Verified: the working tree differs from 5f182f9 on
exactly 140 whitespace-only lines and on nothing else.
GATE-DOCS 6/6 PASS (anchors 71).
SAFE_ROUTES has 19 entries (backends.js), not 18. reference.md and
reference.zh-CN.md both said '18 entries'; both now say 19.
reference §4 said the /api/enabled and /api/admin/session calls are
'admin-session Bearer-auth'd'. The code says otherwise: config_authorized
(notify.rs:423) accepts the shared worker token OR a valid admin session,
and create_admin_session (notify.rs:1187) is gated by worker_authorized
against the admin credential CONFIG_ENCRYPTION_KEY — it is what mints the
session, so it cannot be session-auth'd. Both languages now state the two
distinct credentials and why adding /api/enabled opens no new credential
path.
deployment §10.8 said every request-bearing entry point, listing /healthz
and /api/*, calls refresh_business_config. The actual 10 call sites cover
8 distinct paths (/ready, /worker, /reconcile, /push/jmap, /webhook/tg,
/api/config, /api/business-config, /api/telegram/register-webhook). GET
/healthz is a static 200 "ok" and never refreshes; /api/status,
/api/enabled, /api/push/register, /api/push/disable and the
/api/admin/session pair do not either. Both languages now list the real
set and name the exclusions.
design.md §5.7 listed the search trigger prefixes as English
'search'/'find'/'retrieval'; worker.rs:689 accepts the Chinese prefixes
搜索/查找/检索 and the help text states English aliases are not supported.
The two user-facing strings were also mistranslated: the empty-query
guidance prompt is 请提供搜索关键词，例如：/search 发票 (worker.rs:623)
and the no-match reply is 没有找到匹配「<query>」的邮件。
(worker.rs:792). The degraded-rendering marker is likewise a Chinese
string. SEARCH_SUBJECT_MAX=120 / SEARCH_PREVIEW_MAX=160 /
SEARCH_LIMIT=10 verified unchanged.
design.md §5.6/§5.7 were machine-translated from Chinese back into
English and were broken: 'the first 300 if it fails. characters', a
stray closing ** mid-sentence, '(none) deny_unknown_fields)' with a
mismatched paren, and 5 zero-width-space artefacts. charter.md:168 had a
broken '**Tables, lists, or values may not be copied across documents. **'
and opengaps.md had 4. All ZWSPs removed from docs/.
deployment.zh-CN.md §10.5/§10.6 were thin mistranslations: 'Worker 域'
for 'Worker URL', the debug-token requirement dropped entirely, and a
mangled '两者都使用用于验证部署的可用和版本'. Rewritten against the EN.
Also replaced a worker.rs:227 line anchor with the MetadataWorker doc
comment; that drops the repo's line-refs from 72 to 71, so new text no
longer adds to the drift surface.
No code changes; GATE-DOCS 6/6 (71 anchors, 455 section refs, 727 path
refs).
The zh translation was generated by a machine translator that treated
backtick-delimited literals as prose. It therefore translated Redis
keys, function names, trigger words and status labels, which made the
documentation technically wrong rather than merely stylistically bad:
config:business -> 配置：业务
config:outbound -> 配置：出站
config:admin_session -> 配置：admin_session
consent:ai:{chat_id} -> 同意：ai:{chat_id}
delivery:inflight/committed
-> 交付：飞行中 / 交付：已提交
dedup:jmap:{account}:{email}
-> dedup:jmap:{帐户}:{电子邮件}
ratelimit:push-verify:* -> 速率限制：推送验证：*
push:subscription:* -> 推送：订阅：*
state:jmap:since -> 状态：jmap：自
lock:reconcile -> 锁定：协调
stalwart:*:dlq -> 坚定：*:dlq
set/get_business_config, set_enabled, is_enabled,
remember_push_subscription_id -> Chinese prose
Same damage class, three more forms:
- a typo: delivery:committed -> delivery:comfilled
- a case change that breaks a machine-readable code:
429 push_verify_rate_limited -> 429 Push_verify_rate_limited
- translated trigger words: 直到我取消 / 撤销授权 / 停止摘要 instead of
直到我撤销 / 撤销授权 / 停止摘要
Also repaired:
- six table headers 关键|TTL|作家|读者 -> 键|TTL|写入方|读取方
- a stray TTL number duplicated into the label column (3600 1小时)
- the AI-consent label row (直到截至 -> 直到撤销（最长365天）)
- a dropped aside, 因此递增, which silently removed the reason why
increment, DLQ append and source ACK are atomic
- the 搜索/查找/检索 prefix list, where 检索 had been normalised to 搜索
Section 4 was rewritten rather than patched: the paragraphs carried a
dangling untranslated 'all:' and 'proxy', a dropped closing '**' on
**is forwarded**, 'two calls' rendered as 两个电话, and word order that
reversed the meaning of 'no second ingress is needed'.
Verification: headings and table row counts already matched the English
file exactly (6 section pairs, no structural drift), so this is a
content repair, not a re-sync.
No code changes; GATE-DOCS 6/6 (72 anchors, 455 section refs, 727 path
refs).
Reframe the Cloudflare Worker gateway across the entry points where a
reader forms an impression of it, in both languages:
- README §2 / §5 (en+zh): the gateway is optional and exists because
Cloudflare's Load Balancer product is not on the free plan. Drop the
comparison row that listed 'only the 19 safelisted paths' against
'every route' as if the safelist were a benefit; replace it with
backend reachability, which is identical either way, and move the
route-count fact to its own neutral row. Add one sentence to §5 that
the gateway is outside the secret boundary.
- deployment.md §10 (en+zh): purpose is load balancing, not protection;
no intent to hide or harden the backends, no access control at the
edge, the allowlist is not a firewall.
- cloudflare-worker README (en+zh): new 'why it exists' / 'why it is
not a security feature' block, plus a 'not a security layer' bullet.
Drop 'access-hiding capability' from the non-capabilities list, since
claiming invisibility as something we refuse to provide implies it is
the interesting axis.
- reference.md §4 / §9.2 (en+zh) and deployment.md zh §2: stop saying
bootstrap and /debug/* are 'not exposed' / 'kept off the public path'.
They are simply not in the route set, which is why a request to the
Worker never reaches them — reachable at the backend's own address
either way.
- charter ARCH-LB-WORKER (en+zh): 'only external entrance' -> 'only
*registered* entrance', which is what C-LB-SINGLE-REG-URL actually
says, and backends stay directly reachable.
SAF-LB-PASSTHRU already records the security-side invariant (no auth
or body rewriting, backend may be directly connected to the public
network), so no new stable ID is needed. No code changes; GATE-DOCS
6/6.
BACKEND_ORIGINS_JSON now carries eu-1 and eu-2. Both are public https
origins, so the existing [vars] plaintext exception still applies and
nothing moves to secrets.
LB_VERSION stays at 2026.10.4: it is a code-version marker and the LB
logic is unchanged. The origin list is observable anyway through the
backends array in GET /healthz-worker, which now reports total 2.
Also drop a stale clause that said the origin list travels through
secret; it has lived in [vars] since aa78c13 and the same file says so
twice below it.
eu-2 needs its DNS record and a live backend before this deploy: with
LB_MAX_ATTEMPTS=2 both origins are covered, so a not-yet-deployed eu-2
costs a failed round-trip on about half the requests, and /reconcile
plus /worker run with maxAttempts=1 so those cron runs fail outright
on the half that land there first.
10.2 now spells out that every Redis key is globally named with no
instance dimension, tabulates the shared state (config blob, global
revision, enable gate, cursor, streams, reconcile lock) and records
two consequences: the business configuration exists once so an SPA
edit from any origin writes the same copy (intended, no per-instance
slot exists), and CONFIG_ENCRYPTION_KEY must be byte-identical across
origins since it is the AES-256-GCM key and the SPA admin credential.
Extra origins buy failover, not throughput, because /reconcile is
serialized by lock:reconcile and the cursor is singular.
New 10.8 documents lazy convergence at the request boundary via
refresh_business_config, and the known behavior that a build_worker
failure advances the local revision so the instance does not retry
until a new revision is written. Includes detection via the live field
values in GET /debug/config, the warning that its revision field is the
global Redis value and cannot show convergence, and recovery by
bumping the revision again.
Appended as 10.8 rather than renumbering 10.3-10.7, which charter.md
NFR-HA-MULTI-INSTANCE cites. No code changes; GATE-DOCS 6/6.
Root README gains §2 "Two ways to run it": a side-by-side table of
Form A (backend origin only) against Form B (behind the Cloudflare Worker
gateway) — what answers, failover, the callback URL to register, the
reachable route surface, which health endpoint to watch, and the docs to
read. Late in the switch: registration is idempotent and re-adding retires
the previous subscription, so the switch is one SPA field, not a migration;
nothing secret moves to the gateway; /api/bootstrap and /debug/* stay
origin-only either way. Later sections renumbered, and the monitoring
paragraph now points at the gateway aggregate GET /healthz-worker instead
of the origin-passthrough /healthz.
cloudflare-worker/README.md rewritten as the canonical English version and
cloudflare-worker/README.zh-CN.md added as its translation, covering the
route safelist (19 paths with per-path methods), the timeout/retry budget
with per-route overrides, bounded failover, the two health endpoints,
callback registration, config, local verification, deploy, and the design
invariants.
Both fixes along the way:
- README.zh-CN said the startup env block has 2 required + 2 optional
variables; the table has 3 rows, 2 required + 1 optional.
- docs/charter.md §8 / registry list now names the zh-CN twin next to the
gateway README.
scripts/docs_check gains the new file in validate_docs, check_tables,
audit_anchors and audit_anchor_semantics so it is checked like every other
document. check_sec_refs resolves §-refs against the document being scanned
when a basename is shared: README.md exists both at the repo root and under
cloudflare-worker/, and the basename-keyed heading map silently dropped one
of them. The gate was passing for the wrong reason before.
GATE-DOCS 6/6 clean: 72 anchors, 454 section refs, 727 path refs.
audit_anchor_semantics still reports the same 7 pre-existing candidates,
none in the new or edited files.
The retire-on-change commit inserted ~500 lines into notify.rs and ~110
into state.rs, shifting every anchor at or after the insertion point.
The ANCHOR audit only proves the referenced line exists and is
non-empty, so all of these passed while pointing at the wrong code:
deployment.md/.zh-CN register_telegram_webhook 1619 -> 1623
register_push 1464 -> 1468 (EN)
register_telegram_webhook 1439 -> 1623 (zh)
register_push 1315 -> 1468 (zh)
retired.md/.zh-CN registration_lock fmt 1328-1330 -> 1481-1483
register_push 1315 -> 1468
state.rs read_batch 491 -> 506
state.rs query_async 531 -> 546
state.rs XGROUP CREATE 499-507 -> 514-522
opengaps.md/.zh-CN get_reconcile_state 777 -> 792
set_reconcile_state 785 -> 800
acquire_lock 1076 -> 1130
Every target was verified against the source before editing: two of the
pre-existing anchors pointed inside a different function than the one
they named, and the EN deployment.md had both register anchors off while
the zh twin still carried the original pre-move numbers.
Also documents the new push:registration:current key in the Redis key
table (writer, readers, TTL, and why its literal suffix cannot collide
with the hex session_digest suffix) and carries the zh twin the EN
version already got. Mirror the retire-on-change contract in
deployment.zh-CN.md - the zh twin has its own callback section, which
the EN update skipped.
Four spots told the operator to read the SPA footer to confirm a
deploy landed. The footer no longer renders a version, so restating
that would send an operator looking at a control that no longer
exists. Point them at /api/status instead; the version field itself is
unchanged.
The previous commit inserted 500+ lines into notify.rs, moving
register_push and register_telegram_webhook. Reanchor the two
deployment.md line refs; the other seven refs in that file are before
the insertion point and are unchanged.
Document the new retire-on-change contract in reference.md.
The value rendered was nogit+<UTC build time>, which carried no
information for the operator, so remove all three display sites
(topbar next to the secure-channel note, setup card, page footer).
Clears the three querySelectors, renderVersion, and the two dead i18n
keys. /api/status is untouched and still returns version - the API is
now the only way to confirm a deploy landed.
The <footer> element is removed with its span rather than left empty:
it had no other child, and an empty footer would still render a
visible separator band (border-top plus 41px padding).
The callback section's field was the only one in the SPA sitting
directly on the panel, with no padded ancestor. It spanned the full
card width with zero side padding and pressed the button bar, while
the copy above it was indented 25px. Wrap it in .field-grid and pad it
to match its card siblings on both desktop and the 720px breakpoint;
.field-wide's grid-column now has a grid ancestor.
Rewrite the callback copy to name the Cloudflare Worker front proxy
explicitly instead of the bare word Worker, and state that registering
a new address retires the previous subscription.
Registering with a new callback_url previously left the old Stalwart
subscription live alongside the new one, so Stalwart pushed the same mail
event to both origins and the user got duplicate notifications. The
per-URL mapping had no record of which subscription was current.
Add a push:registration:current pointer written alongside the per-URL
mapping. register_push now retires the previous subscription under the
existing registration lock before creating the new one: destroy first,
then delete the mapping, then mark the status disabled. A destroy failure
returns a retryable 503 (push_destroy_failed) rather than proceeding
silently - silently skipping is exactly the shape of the original bug.
The idempotency short-circuit still runs first, so re-registering the
same URL never touches the retire path. disable_push clears the pointer
only when the disabled URL is the current one.
Extracts destroy_push_registration, shared by disable_push and the new
retire path. Telegram needs no change: setWebhook replaces the previous
webhook atomically.
Adds 5 tests with a recording mock that captures the create/destroy
call order: idempotent no-recreate, retire-on-change, abort-without-
create when the old destroy fails, skip-destroy when the previous
mapping expired, and pointer untouched when disabling a non-current URL.
anonsaber
messageweave