Skip to content

Commit e31d7bc

Browse files
bpapillonbpapillon
authored
add language-agnostic conformance suite for credit lease semantics (#147)
1 parent 35ff242 commit e31d7bc

9 files changed

Lines changed: 3515 additions & 0 deletions

File tree

‎conformance/SPEC.md‎

Lines changed: 440 additions & 0 deletions
Large diffs are not rendered by default.

‎conformance/vectors/check-flow.json‎

Lines changed: 527 additions & 0 deletions
Large diffs are not rendered by default.

‎conformance/vectors/crash-windows.json‎

Lines changed: 271 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,271 @@
1+
{
2+
"category": "crash_window",
3+
"vectors": [
4+
{
5+
"name": "debit_without_record_leaks_bounded",
6+
"description": "Crash window 1 (debit-then-add): the atomic debit landed but the reservation record never did. The leak is exactly the reserved amount; the sweeper can never refund a hold that was never recorded.",
7+
"given": {
8+
"leases": [
9+
{
10+
"lease_id": "lse_1",
11+
"company_id": "co_1",
12+
"credit_type_id": "ct_1",
13+
"granted_amount": 1000,
14+
"expires_at_ms": 60000
15+
}
16+
]
17+
},
18+
"operations": [
19+
{
20+
"op": "try_reserve",
21+
"company_id": "co_1",
22+
"credit_type_id": "ct_1",
23+
"credits": 100,
24+
"expect": { "balance": 900 }
25+
},
26+
{ "op": "reserved_credits", "company_id": "co_1", "credit_type_id": "ct_1", "expect": { "total": 0 } },
27+
{ "op": "advance_clock", "ms": 55000 },
28+
{ "op": "sweep_expired", "expect": { "swept": 0 } },
29+
{
30+
"op": "get_lease",
31+
"company_id": "co_1",
32+
"credit_type_id": "ct_1",
33+
"expect": { "exists": true, "local_remaining_credits": 900 }
34+
}
35+
]
36+
},
37+
{
38+
"name": "debit_leak_reclaimed_at_lease_expiry",
39+
"description": "Crash window 1 recovery: the leaked balance is never served after lease expiry, and the successor lease installs at the full grant — the leak does not outlive the lease.",
40+
"given": {
41+
"leases": [
42+
{
43+
"lease_id": "lse_1",
44+
"company_id": "co_1",
45+
"credit_type_id": "ct_1",
46+
"granted_amount": 1000,
47+
"expires_at_ms": 60000
48+
}
49+
]
50+
},
51+
"operations": [
52+
{
53+
"op": "try_reserve",
54+
"company_id": "co_1",
55+
"credit_type_id": "ct_1",
56+
"credits": 100,
57+
"expect": { "balance": 900 }
58+
},
59+
{ "op": "advance_clock", "ms": 60001 },
60+
{
61+
"op": "try_reserve",
62+
"company_id": "co_1",
63+
"credit_type_id": "ct_1",
64+
"credits": 1,
65+
"expect": { "balance": null }
66+
},
67+
{
68+
"op": "replace_lease",
69+
"lease_id": "lse_2",
70+
"company_id": "co_1",
71+
"credit_type_id": "ct_1",
72+
"granted_amount": 1000,
73+
"expires_at_ms": 180000,
74+
"expect": { "written": true }
75+
},
76+
{
77+
"op": "get_lease",
78+
"company_id": "co_1",
79+
"credit_type_id": "ct_1",
80+
"expect": { "exists": true, "local_remaining_credits": 1000 }
81+
}
82+
]
83+
},
84+
{
85+
"name": "retried_check_after_debit_leak_settles_once",
86+
"description": "A retry after a window-1 crash is a fresh check with a fresh reservation: its unspent slice refunds exactly once; the leaked slice never refunds — not on a repeat consume, not on a sweep.",
87+
"given": {
88+
"leases": [
89+
{
90+
"lease_id": "lse_1",
91+
"company_id": "co_1",
92+
"credit_type_id": "ct_1",
93+
"granted_amount": 1000,
94+
"expires_at_ms": 3600000
95+
}
96+
]
97+
},
98+
"operations": [
99+
{
100+
"op": "try_reserve",
101+
"company_id": "co_1",
102+
"credit_type_id": "ct_1",
103+
"credits": 100,
104+
"expect": { "balance": 900 }
105+
},
106+
{
107+
"op": "try_reserve",
108+
"company_id": "co_1",
109+
"credit_type_id": "ct_1",
110+
"credits": 100,
111+
"expect": { "balance": 800 }
112+
},
113+
{
114+
"op": "add_reservation",
115+
"id": "res_retry",
116+
"lease_id": "lse_1",
117+
"company_id": "co_1",
118+
"credit_type_id": "ct_1",
119+
"event_subtype": "inference_tokens",
120+
"quantity_reserved": 10,
121+
"credits_reserved": 100,
122+
"consumption_rate": 10,
123+
"expires_at_ms": 60000
124+
},
125+
{ "op": "consume_reservation", "id": "res_retry", "credits": 40, "expect": { "consumed": 40 } },
126+
{
127+
"op": "get_lease",
128+
"company_id": "co_1",
129+
"credit_type_id": "ct_1",
130+
"expect": { "exists": true, "local_remaining_credits": 860 }
131+
},
132+
{ "op": "consume_reservation", "id": "res_retry", "credits": 40, "expect": { "consumed": null } },
133+
{ "op": "advance_clock", "ms": 70000 },
134+
{ "op": "sweep_expired", "expect": { "swept": 0 } },
135+
{
136+
"op": "get_lease",
137+
"company_id": "co_1",
138+
"credit_type_id": "ct_1",
139+
"expect": { "exists": true, "local_remaining_credits": 860 }
140+
}
141+
]
142+
},
143+
{
144+
"name": "crash_before_refund_claim_is_durable",
145+
"description": "Crash window 2 (consume-then-refund): the claim survives the crash, so the reservation is gone everywhere and nothing can double-spend; the unspent slice's refund is lost, bounded by credits_reserved. A retried settle neither re-claims nor double-refunds, and the sweeper cannot refund a claimed reservation.",
146+
"given": {
147+
"leases": [
148+
{
149+
"lease_id": "lse_1",
150+
"company_id": "co_1",
151+
"credit_type_id": "ct_1",
152+
"granted_amount": 1000,
153+
"expires_at_ms": 3600000
154+
}
155+
]
156+
},
157+
"operations": [
158+
{
159+
"op": "try_reserve",
160+
"company_id": "co_1",
161+
"credit_type_id": "ct_1",
162+
"credits": 100,
163+
"expect": { "balance": 900 }
164+
},
165+
{
166+
"op": "add_reservation",
167+
"id": "res_1",
168+
"lease_id": "lse_1",
169+
"company_id": "co_1",
170+
"credit_type_id": "ct_1",
171+
"event_subtype": "inference_tokens",
172+
"quantity_reserved": 10,
173+
"credits_reserved": 100,
174+
"consumption_rate": 10,
175+
"expires_at_ms": 60000
176+
},
177+
{
178+
"op": "consume_reservation",
179+
"id": "res_1",
180+
"credits": 30,
181+
"crash_before_refund": true,
182+
"expect": { "throws": true }
183+
},
184+
{ "op": "get_reservation", "id": "res_1", "expect": { "exists": false } },
185+
{ "op": "reserved_credits", "company_id": "co_1", "credit_type_id": "ct_1", "expect": { "total": 0 } },
186+
{
187+
"op": "get_lease",
188+
"company_id": "co_1",
189+
"credit_type_id": "ct_1",
190+
"expect": { "exists": true, "local_remaining_credits": 900 }
191+
},
192+
{ "op": "consume_reservation", "id": "res_1", "credits": 30, "expect": { "consumed": null } },
193+
{ "op": "advance_clock", "ms": 70000 },
194+
{ "op": "sweep_expired", "expect": { "swept": 0 } },
195+
{
196+
"op": "get_lease",
197+
"company_id": "co_1",
198+
"credit_type_id": "ct_1",
199+
"expect": { "exists": true, "local_remaining_credits": 900 }
200+
}
201+
]
202+
},
203+
{
204+
"name": "crash_before_refund_reclaimed_at_lease_expiry",
205+
"description": "Crash window 2 recovery: after the lease expires and a successor takes the slot at full grant, a very late retried settle of the crashed reservation must not leak the lost refund into the successor.",
206+
"given": {
207+
"leases": [
208+
{
209+
"lease_id": "lse_1",
210+
"company_id": "co_1",
211+
"credit_type_id": "ct_1",
212+
"granted_amount": 1000,
213+
"expires_at_ms": 60000
214+
}
215+
]
216+
},
217+
"operations": [
218+
{
219+
"op": "try_reserve",
220+
"company_id": "co_1",
221+
"credit_type_id": "ct_1",
222+
"credits": 100,
223+
"expect": { "balance": 900 }
224+
},
225+
{
226+
"op": "add_reservation",
227+
"id": "res_1",
228+
"lease_id": "lse_1",
229+
"company_id": "co_1",
230+
"credit_type_id": "ct_1",
231+
"event_subtype": "inference_tokens",
232+
"quantity_reserved": 10,
233+
"credits_reserved": 100,
234+
"consumption_rate": 10,
235+
"expires_at_ms": 60000
236+
},
237+
{
238+
"op": "consume_reservation",
239+
"id": "res_1",
240+
"credits": 30,
241+
"crash_before_refund": true,
242+
"expect": { "throws": true }
243+
},
244+
{ "op": "advance_clock", "ms": 60001 },
245+
{
246+
"op": "try_reserve",
247+
"company_id": "co_1",
248+
"credit_type_id": "ct_1",
249+
"credits": 1,
250+
"expect": { "balance": null }
251+
},
252+
{
253+
"op": "replace_lease",
254+
"lease_id": "lse_2",
255+
"company_id": "co_1",
256+
"credit_type_id": "ct_1",
257+
"granted_amount": 1000,
258+
"expires_at_ms": 180000,
259+
"expect": { "written": true }
260+
},
261+
{ "op": "consume_reservation", "id": "res_1", "credits": 0, "expect": { "consumed": null } },
262+
{
263+
"op": "get_lease",
264+
"company_id": "co_1",
265+
"credit_type_id": "ct_1",
266+
"expect": { "exists": true, "lease_id": "lse_2", "local_remaining_credits": 1000 }
267+
}
268+
]
269+
}
270+
]
271+
}

0 commit comments

Comments
 (0)