fix(server): keep a message's time to the millisecond

[mbeisser1]

Bug Description

Expected: A message whose backup records its time to the millisecond is stored and returned by the API with those milliseconds, and two messages in one conversation sent 300 ms apart are listed in the order they were sent.

Actual: The server stored every message time as whole seconds (2020-01-06T11:10:00Z). The milliseconds that WhatsApp, Apple Messages and SMS Backup & Restore record were dropped, and two messages in one second were ordered by sort_order alone, that is by their place in the file.

Root Cause

models::message_from_ir and earlier_version_from_ir divided timestamp_unix_ms and edited_at_unix_ms by 1000 (div_euclid(1000)) and format_utc_timestamp wrote SecondsFormat::Secs, so messages.timestamp (and message_versions.edited_at) had no place for milliseconds.

Fix Description

Decision on #1096 (2026-10-05): option 3, milliseconds now; the precision flag and the whole-second twin dedupe are #1923.

• Schema change (schema/sql/messages.sql, schema/sql/staging.sql): messages.timestamp, staging_messages.timestamp and message_versions.edited_at stay TEXT RFC 3339 UTC, now always with three fractional digits (2015-03-12T18:04:22.250Z, .000 for a whole-second source). One fixed form keeps the text sorting in time order, so every ORDER BY m.timestamp, m.sort_order, m.id, the MIN/MAX aggregates and group_title_at work unchanged. The schema fingerprint changes, so an existing database is rebuilt empty (no migration, per CLAUDE.md).
• API change: no field renamed. Message.timestamp and EarlierVersion.edited_at now carry milliseconds; the dates derived from message times (contact start_date/end_date/last_heard_at, identity start_date/end_date, conversation first/last) carry them too. The doc comments in crates/libs/api-types say so; docs/src/assets/openapi.json and web/src/lib/serverApi.types.ts are regenerated (comment text only). The web app already parses the string with Date.parse/Intl, so no web code changed.
• Search (search/value.rs): a day's start is written in the same millisecond form. A bound like …T00:00:00Z sorts after a stored …T00:00:00.000Z, so without this a message at the first instant of a day fell on the day before. The binary search for the end of a time zone's gap now steps in whole seconds, because a half second it used to leave (hidden by the seconds format) would now show (1994-12-31T10:00:00.439Z for Kiritimati).
• Content key unchanged: dedupe::parse_rfc3339_utc_secs still reads whole seconds, so the content key and the near-time pass match at whole seconds as before.
• Nothing else truncated on the way through: the demo seed goes through the import path, message-crate-pull already parsed RFC 3339 with milliseconds (timestamp_millis), and the export formats carry timestamp_unix_ms (CSV column, mail X-ME header).
• docs/architecture/contacts-identities-and-messages.md: titles are compared to the millisecond. CHANGELOG entry under 0.11.0 (Fixes, and an Upgrading note for API readers).
• Test literals that insert message rows by hand (MessageRow and friends) moved to the millisecond form, and assertions on returned times were updated.

How to Reproduce (Before Fix)

1. Import crates/server/server/tests/fixtures/apple-messages-sub-second-times.jsonl (two messages at …00.550 and …00.250, the later one listed first).
2. GET /v1/messages?sort=date.
3. Both messages show 2020-01-06T11:10:00Z, and guid-300-ms-later is listed before guid-first.

How to Verify (After Fix)

1. cargo test -p message-crate-server --lib -- a_message_time_keeps_its_milliseconds_through_import_and_the_api two_messages_300_ms_apart_are_ordered_by_their_times a_day_begins_at_its_first_millisecond
2. cargo test -p message-crate-server --lib -- a_conversation_split_across_batches_keeps_its_order_within_a_second (the Messages of one second come out of order where a conversation is split across batches #1168 test of messages 100 ms apart).
3. The same import as above returns 2020-01-06T11:10:00.250Z and …00.550Z, in that order, on /v1/messages and /v1/conversations/{id}/messages.

Each new test fails without the fix, checked locally:

• a_message_time_keeps_its_milliseconds_through_import_and_the_api and two_messages_300_ms_apart_are_ordered_by_their_times fail with models::format_utc_timestamp put back to whole seconds ("2020-01-06T11:10:00Z" against "…00.250Z"; order ["guid-300-ms-later", "guid-first"]).
• a_day_begins_at_its_first_millisecond fails with the search bound put back to SecondsFormat::Secs (date:2013-05-01 finds nothing).
• The existing every_skipped_day_begins_where_the_next_day_begins fails without the whole-second step in the gap search.

The #1168 100 ms test passes both with and without this change: #1168 was already fixed by numbering sort_order across batches, so it does not fail before this PR.

Impact Assessment

• Severity: Medium
• Users affected: Subset: anyone who imported WhatsApp, Apple Messages or SMS Backup & Restore backups with several messages in one second; programs reading timestamp from the API see a new string form.
• Duration: Since the server first stored message times.

Regression Risk

• Every string compared with messages.timestamp must use the same three-digit form. The only one built from a date is the search day bound, changed here. A time written in the old form would sort after every millisecond time of its second; only test rows inserted by hand could do that, and those were moved to the new form where they meet a comparison.
• The schema change rebuilds an existing database empty on first start; its messages must be imported again (already the case for 0.11.0, see Upgrading).
• An API client that matched the old …SSZ text exactly would see …SS.sssZ. No compatibility is kept, per CLAUDE.md.
• No CHECK constraint enforces the form in SQL; format_utc_timestamp is the one writer.

Checklist

• Root cause identified and documented above
• Fix addresses the root cause (not just symptoms)
• Added test to prevent regression
• Existing tests pass locally (./scripts/check-pr.sh, cargo test --workspace, cargo test -p message-crate-server, web npm test and npm run build, ./scripts/check-generated-api-types.sh, docs npm run check and npm run build)
• Tested the specific reproduction steps

Related Issues

Closes #1096

The precision flag and the whole-second / millisecond twin dedupe follow in #1923. #1168 is updated in a comment.

🤖 Generated with Claude Code

[mbeisser1]

Review of 850b1cb (main merged in; the only conflict was CHANGELOG.md, both entries kept). Standards: 2 findings (below). Spec: no findings. Correctness: no findings. Merge review of the CHANGELOG resolution: no findings.

[mbeisser1]

Re-review of the fix commits 87c5cf0 and 2d1f638 (Standards: 3 findings, below; Correctness: none), and merge review of fc1ca2b, which merges main (#1957, #1960) with a CHANGELOG.md conflict resolved by keeping main's Unsent entry and this PR's entry under one "#### Browsing and search" heading (Correctness: none).

[mbeisser1]

Review summary

Findings per axis (first review pinned to 850b1cb, re-review of the fix commits 87c5cf0 and 2d1f638):

• Standards: 5 findings, all judgement. Fixed 4 (87c5cf0: models::utc_timestamp_text is the one writer of the stored time form, used by the search day bound and the tests; 2d1f638: the dedupe.rs comment and the models.rs module doc). Deferred 1: a type for the stored time, A stored message time is a bare String, so nothing makes a comparison use the stored form #1965.
• Spec: no findings. Every acceptance criterion in the last comment on The server stores message times in whole seconds and drops the milliseconds a backup records #1096 is met; the precision flag and the whole-second twin dedupe stay in The conversation file says whether a message's time has milliseconds, and a whole-second twin is a duplicate #1923.
• Correctness: no findings, in the review or the re-review.

Totals: 4 Fixed, 0 Declined, 1 Deferred (#1965).

Merges of the base

• 850b1cb merged main (up to fix(import): the service decides which types an identity can take #1956); resolved the conflict in CHANGELOG.md (both Fixes entries kept). Merge review: no findings.
• fc1ca2b merged main (fix(search): an Unsent message is not found by the text it hides #1957, fix(desktop): closing the app kills its server's whole process tree #1960); resolved the conflict in CHANGELOG.md (main's Unsent entry and this PR's milliseconds entry under one "#### Browsing and search" heading). Merge review: no findings.

CI: run 37411093248 on fc1ca2b, success. No commits were needed for CI failures.

No Spec skip. No user thread open.