DuplicateInvoicePrevention

1# DuplicateInvoicePrevention.intent
2# The signature IntentLang pattern: a "no duplicates" guarantee is only real when
3# an idempotency key backs it. This mission says so out loud, and proves it.
4
5mission DuplicateInvoicePrevention
6use product
7
8title "Turn a retried checkout into exactly one invoice"
9for BillingCustomer
10
11note pm:
12  A network retry, a double-click, or an at-least-once queue must never bill twice.
13
14goal
15  Ensure one purchase produces exactly one invoice, no matter how many times the
16  request arrives.
17
18why
19  Duplicate invoices cause double charges, refunds, support tickets, finance
20  cleanup, and lost trust. Preventing them is cheaper than curing them.
21
22requires
23  Customer
24  ApprovedOrder
25
26input
27  customer: Customer
28  order: Order
29  idempotencyKey: IdempotencyKey
30    note beginner:
31      The retry key. The same key always returns the first invoice instead of
32      creating a second one.
33    note qa:
34      Send the same order twice with the same key and expect one invoice, same id.
35
36output
37  invoice: Invoice
38
39guarantee a repeated request with the same key returns the first invoice
40  because at-least-once delivery means the same request will arrive more than once
41  note risk:
42    Without this, every retry is a new invoice and a new charge.
43  verify idempotency replay test
44
45guarantee two different keys never collapse into one invoice
46  because over-deduplication silently drops real, distinct purchases
47  verify distinct keys test
48
49never
50  create a second invoice for an already-processed key
51  bill a customer more than once for one order
52
53never create a second invoice for an already-processed key
54  because that is the exact failure this mission exists to prevent
55  verify idempotency replay test
56
57never bill a customer more than once for one order
58  because a double charge is a trust-breaking billing error
59  verify duplicate charge scan
60
61# The idempotency decision, run it with `intent run`, assert it with `intent test`.
62decision InvoiceForKey
63  inputs
64    keySeen
65    orderApproved
66  rule replay
67    when keySeen == true
68    return ReturnExisting
69  rule unapproved
70    when orderApproved == false
71    return Reject
72  default
73    return CreateNew
74
75target
76  TypeScript
77  OpenAPI
78  Tests
79
80test InvoiceForKey
81  case first request creates the invoice
82    given keySeen false, orderApproved true
83    expect CreateNew
84  case retry returns the existing invoice
85    given keySeen true, orderApproved true
86    expect ReturnExisting
87  case a seen key wins even over approval checks
88    given keySeen true, orderApproved false
89    expect ReturnExisting
90  case unapproved order is rejected
91    given keySeen false, orderApproved false
92    expect Reject