Make duplicate reciept by Chigybillionz · Pull Request #1583 · Stellar-Mail/stealth

Chigybillionz · 2026-07-19T17:27:26Z

Close #1549

Summary of the issue

Receipt publication was not deterministic for duplicate delivery and read receipt calls. Clients that retried after timeouts could receive conflicts for otherwise identical duplicate requests, and concurrent retries could race on timestamp assignment.

Root cause

The receipt service performed duplicate handling with separate read-then-write logic. Duplicate delivery receipts were rejected with `409`, and duplicate read receipts were rejected after the first read transition. Because timestamp assignment happened outside an atomic receipt transition, concurrent retries could observe stale state and attempt repeated receipt writes.

Solution implemented

This PR makes receipt publication idempotent and documents timestamp precedence:

Identical duplicate delivery receipts replay the stored receipt.
Duplicate read receipts replay the stored receipt.
The first persisted deliveredAt timestamp wins.
The first persisted readAt timestamp wins.
Duplicate delivery attempts for the same messageId with different participants still return 409 conflict.
Receipt publication performs only one storage/domain transition per delivery/read state change.

Key changes made

Added repository-level receipt transition methods:
- createReceiptIfAbsent
- markReceiptRead
Updated the in-memory repository to serialize per-message receipt transitions for deterministic concurrent behavior.
Updated the Cloudflare KV repository to coordinate receipt transitions through StealthCoordinator.
Added legacy KV hydration so existing receipts keep their original timestamps when first seen by the coordinator-backed flow.
Updated receipt service behavior to replay stored receipts for identical duplicates and preserve conflicts for participant mismatches.
Documented duplicate timestamp precedence in the receipts API README.
Updated protocol vectors and API/e2e expectations for idempotent duplicate receipt behavior.
Added tests for sequential duplicates, concurrent duplicates, timestamp precedence, and single KV mirror writes per receipt transition.

Trade-offs or considerations

The API now treats identical duplicate delivery/read publication as successful replay instead of conflict. Conflicting participant claims for an existing `messageId` remain conflicts to avoid silently changing receipt ownership.

Testing steps

Run focused unit tests:
npm test -- --run tests/unit/api/receipt-service.test.ts tests/unit/api/stealth-coordinator.test.ts tests/unit/api/kv-repository.test.ts tests/unit/api/health.test.ts
Run the full unit suite:
npm test
Optional API verification:
1. Create a delivery receipt.
2. Retry the same delivery receipt and confirm the stored receipt is replayed.
3. Retry with the same messageId but different participants and confirm 409 conflict.
4. Mark the receipt as read.
5. Retry the read call and confirm the first readAt timestamp is preserved.
6. Run concurrent duplicate delivery/read calls and confirm both responses converge on the same stored timestamps.

Please kindly review this task. If there are any corrections, improvements, adjustments, or merge conflicts that you notice regarding my implementation, I'd really appreciate your feedback. I'd also love to hear your overall review of my work on this branch.Thank you!

Stellar-Mail#1515

kryputh · 2026-07-20T16:13:30Z

Format your code

Chigybillionz · 2026-07-20T16:19:03Z

Can I delete the branches and start the task afresh, I think it will be okay that way

…

On Mon, Jul 20, 2026, 5:13 PM Uthaimin ***@***.***> wrote: *kryputh* left a comment (Stellar-Mail/stealth#1583) <#1583 (comment)> Format your code — Reply to this email directly, view it on GitHub <#1583?email_source=notifications&email_token=BMBZJ5AFSHFANXYY55JOHZT5FZAMBA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMBSGQ2DINJTGAY2M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#issuecomment-5024445301>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BMBZJ5B5G7XEK5XDXYXJQN35FZAMBAVCNFSNUABGKJSXA33TNF2G64TZHMYTEMZQGQ3DGOJYGA5US43TOVSTWNBZGIZTMOBTG42DLILWAI> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/BMBZJ5E4X62UR7FJWOEIE3D5FZAMBA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMBSGQ2DINJTGAY2M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KUZTPN52GK4S7NFXXG> and Android <https://github.com/notifications/mobile/android/BMBZJ5GHNG6VOJDRJXZBYRD5FZAMBA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMBSGQ2DINJTGAY2M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2K4ZTPN52GK4S7MFXGI4TPNFSA>. Download it today! You are receiving this because you authored the thread.Message ID: ***@***.***>

kryputh · 2026-07-20T21:52:56Z

@Chigybillionz tell your agent to run bun command with prettier to format the code

Then check ✅ it again with bun after with bun prettier check ✅...

That the case for all your issues. If you have CODEX try using it or just connect your GitHub with GPT and use chatGPT work with the GitHub mcp

It should also solve it

kryputh · 2026-07-20T21:54:04Z

@Chigybillionz tell your agent to run bun command with prettier to format the code

Then check ✅ it again with bun after with bun prettier check ✅...

That the case for all your issues. If you have CODEX try using it or just connect your GitHub with GPT and use chatGPT work with the GitHub mcp

It should also solve it

Chigybillionz · 2026-07-20T21:56:23Z

Alright let me see.. I'll send feedback back

…

On Mon, Jul 20, 2026, 10:54 PM Uthaimin ***@***.***> wrote: *kryputh* left a comment (Stellar-Mail/stealth#1583) <#1583 (comment)> @Chigybillionz <https://github.com/Chigybillionz> tell your agent to run bun command with prettier to format the code Then check ✅ it again with bun after with bun prettier check ✅... That the case for all your issues. If you have CODEX try using it or just connect your GitHub with GPT and use chatGPT work with the GitHub mcp It should also solve it — Reply to this email directly, view it on GitHub <#1583?email_source=notifications&email_token=BMBZJ5GJLNARH6L4UBTNE235F2IJFA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMBSG43DKNBSGY32M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-5027654267>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BMBZJ5EDH2CTJHAUXWIYCHT5F2IJFAVCNFSNUABGKJSXA33TNF2G64TZHMYTEMZQGQ3DGOJYGA5US43TOVSTWNBZGIZTMOBTG42DLILWAI> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/BMBZJ5F3ON6G7V2DP2NIXBD5F2IJFA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMBSG43DKNBSGY32M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJKTGN5XXIZLSL5UW64Y> and Android <https://github.com/notifications/mobile/android/BMBZJ5EQAH6P5JB5FU23VNL5F2IJFA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMBSG43DKNBSGY32M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLTGN5XXIZLSL5QW4ZDSN5UWI>. Download it today! You are receiving this because you were mentioned.Message ID: ***@***.***>

kryputh · 2026-07-21T06:39:21Z

First which AI agent are you using second is how good is your prompt techniques because this CI is almost getting impossible for you to solve

Chigybillionz · 2026-07-21T13:35:23Z

I have not worked it out... Am about to do it Am using antigravity I'll do this afternoon

…

On Tue, Jul 21, 2026, 7:39 AM Uthaimin ***@***.***> wrote: *kryputh* left a comment (Stellar-Mail/stealth#1583) <#1583 (comment)> First which AI agent are you using second is how good is your prompt techniques because this CI is almost getting impossible for you to solve — Reply to this email directly, view it on GitHub <#1583?email_source=notifications&email_token=BMBZJ5DLBDC5WL2FTOEREC35F4F27A5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMBTGA4TCMZWGYZ2M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-5030913663>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BMBZJ5DKUJGFEBTZR35SWGL5F4F27AVCNFSNUABGKJSXA33TNF2G64TZHMYTEMZQGQ3DGOJYGA5US43TOVSTWNBZGIZTMOBTG42DLILWAI> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/BMBZJ5GJY5LO3MSIGUH6SUT5F4F27A5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMBTGA4TCMZWGYZ2M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJKTGN5XXIZLSL5UW64Y> and Android <https://github.com/notifications/mobile/android/BMBZJ5EMCOGYACGVXIQDWDL5F4F27A5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMBTGA4TCMZWGYZ2M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLTGN5XXIZLSL5QW4ZDSN5UWI>. Download it today! You are receiving this because you were mentioned.Message ID: ***@***.***>

Chigybillionz added 4 commits July 19, 2026 18:05

Implement readiness checks for required API dependencies

1b177bd

Stellar-Mail#1515

Make duplicate receipt publication deterministic

2ed9274

style: fix prettier formatting

a4c80bb

style: format fixtures.md with prettier

34206dc

Chigybillionz force-pushed the make-duplicate-reciept branch from 6a5041c to 34206dc Compare July 20, 2026 12:51

fix: resolve typecheck error in health.ts and prettier formatting

6ed7d83

Chigybillionz force-pushed the make-duplicate-reciept branch from 96b483f to 6ed7d83 Compare July 20, 2026 19:21

Merge branch 'main' into make-duplicate-reciept

40844f4

fix: resolve syntax error in health.ts

9f2ba3a

Chigybillionz mentioned this pull request Jul 21, 2026

Define fail open #1587

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Make duplicate reciept#1583

Make duplicate reciept#1583
Chigybillionz wants to merge 7 commits into
Stellar-Mail:mainfrom
Chigybillionz:make-duplicate-reciept

Chigybillionz commented Jul 19, 2026

Uh oh!

kryputh commented Jul 20, 2026

Uh oh!

Chigybillionz commented Jul 20, 2026 via email

Uh oh!

kryputh commented Jul 20, 2026

Uh oh!

kryputh commented Jul 20, 2026

Uh oh!

Chigybillionz commented Jul 20, 2026 via email

Uh oh!

kryputh commented Jul 21, 2026

Uh oh!

Chigybillionz commented Jul 21, 2026 via email

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

Chigybillionz commented Jul 19, 2026

Close #1549

Summary of the issue

Receipt publication was not deterministic for duplicate delivery and read receipt calls. Clients that retried after timeouts could receive conflicts for otherwise identical duplicate requests, and concurrent retries could race on timestamp assignment.

Root cause

Solution implemented

Key changes made

Trade-offs or considerations

The API now treats identical duplicate delivery/read publication as successful replay instead of conflict. Conflicting participant claims for an existing messageId remain conflicts to avoid silently changing receipt ownership.

Testing steps

Uh oh!

kryputh commented Jul 20, 2026

Uh oh!

Chigybillionz commented Jul 20, 2026 via email

Uh oh!

kryputh commented Jul 20, 2026

Uh oh!

kryputh commented Jul 20, 2026

Uh oh!

Chigybillionz commented Jul 20, 2026 via email

Uh oh!

kryputh commented Jul 21, 2026

Uh oh!

Chigybillionz commented Jul 21, 2026 via email

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

The API now treats identical duplicate delivery/read publication as successful replay instead of conflict. Conflicting participant claims for an existing `messageId` remain conflicts to avoid silently changing receipt ownership.