@yolk-sdk/pool 0.0.0-stage → 0.1.0-canary.116

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/rank.ts ADDED
@@ -0,0 +1,307 @@
1
+ import { Data, Predicate } from 'effect'
2
+ import type { ProviderSubscriptionUsageSnapshot } from '@yolk-sdk/agent/providers/subscription-usage'
3
+ import type { PoolCooldown } from './model.ts'
4
+
5
+ /** One usage window of a reading, as the ranking reads it. */
6
+ export type PoolWindow = {
7
+ /** Window length; absent when the provider's window has no fixed length (a billing month). */
8
+ readonly durationMinutes?: number
9
+ readonly usedPercent: number
10
+ /** When the window resets; absent when it has not started. */
11
+ readonly resetsAtMs?: number
12
+ /** Lowercase model substrings the window limits; empty for every model. */
13
+ readonly models: ReadonlyArray<string>
14
+ }
15
+
16
+ type MutablePoolWindow = { -readonly [Key in keyof PoolWindow]: PoolWindow[Key] }
17
+
18
+ /** The latest quota reading of one account. */
19
+ export type PoolReading = {
20
+ readonly fetchedAtMs: number
21
+ readonly windows: ReadonlyArray<PoolWindow>
22
+ }
23
+
24
+ /** A configured account as the ranking sees it. */
25
+ export type PoolCandidate = {
26
+ readonly id: string
27
+ readonly priority: number
28
+ }
29
+
30
+ /**
31
+ * The route a request pins: its model id, trimmed and lowercased. Reasoning effort is a separate
32
+ * request field and never part of the route.
33
+ */
34
+ export const poolRoute = (model: string) => model.trim().toLowerCase()
35
+
36
+ /**
37
+ * A usage snapshot as the ranking reads it; an unreadable `fetchedAt` yields no reading. Windows
38
+ * without a length still block a used-up account but never rank it. A window that reports only
39
+ * `resetsAfterSeconds` resets that long after the reading.
40
+ */
41
+ export const poolReadingFromSnapshot = (
42
+ snapshot: ProviderSubscriptionUsageSnapshot
43
+ ): PoolReading | undefined => {
44
+ const fetchedAtMs = Date.parse(snapshot.fetchedAt)
45
+
46
+ if (!Number.isFinite(fetchedAtMs)) {
47
+ return undefined
48
+ }
49
+
50
+ const windows = Array.from(snapshot.windows).map((window): PoolWindow => {
51
+ const resetsAtMs =
52
+ window.resetsAt !== undefined
53
+ ? Date.parse(window.resetsAt)
54
+ : window.resetsAfterSeconds !== undefined
55
+ ? fetchedAtMs + window.resetsAfterSeconds * 1000
56
+ : Number.NaN
57
+
58
+ const models = (window.models ?? []).flatMap(model => {
59
+ const normalized = model.trim().toLowerCase()
60
+
61
+ return normalized === '' ? [] : [normalized]
62
+ })
63
+
64
+ const fields: MutablePoolWindow = { usedPercent: window.usedPercent, models }
65
+
66
+ if (window.windowDurationMinutes !== undefined) {
67
+ fields.durationMinutes = window.windowDurationMinutes
68
+ }
69
+
70
+ if (Number.isFinite(resetsAtMs)) {
71
+ fields.resetsAtMs = resetsAtMs
72
+ }
73
+
74
+ return fields
75
+ })
76
+
77
+ return { fetchedAtMs, windows }
78
+ }
79
+
80
+ /** Why the ranking chose an account. */
81
+ export type PoolDecision = Data.TaggedEnum<{
82
+ /** Fresh readings ranked it first; `resetsAtMs` is its longest window's reset, if started. */
83
+ Quota: { readonly accountId: string; readonly resetsAtMs: number | undefined }
84
+ /** No candidate is usable by a fresh reading; the route's pin is still available. */
85
+ Sticky: { readonly accountId: string }
86
+ /** No candidate is usable by a fresh reading and no pin is: highest priority, then lowest id. */
87
+ FillFirst: { readonly accountId: string }
88
+ }>
89
+
90
+ export const PoolDecision = Data.taggedEnum<PoolDecision>()
91
+
92
+ export type PoolRankInput = {
93
+ /** Configured accounts. */
94
+ readonly accounts: ReadonlyArray<PoolCandidate>
95
+ /** Accounts that cannot serve now: an active cooldown, or already tried by this request. */
96
+ readonly unavailable: ReadonlySet<string>
97
+ readonly readings: ReadonlyMap<string, PoolReading>
98
+ /** The account the route is pinned to, if any. */
99
+ readonly pin: string | undefined
100
+ readonly route: string
101
+ readonly nowMs: number
102
+ readonly maxAgeMs: number
103
+ readonly reservePercent: number
104
+ }
105
+
106
+ const appliesTo = (window: PoolWindow, route: string) =>
107
+ window.models.length === 0 || window.models.some(model => route.includes(model))
108
+
109
+ const hasStarted = (window: PoolWindow, nowMs: number) =>
110
+ window.resetsAtMs !== undefined && window.resetsAtMs > nowMs
111
+
112
+ type AccountRank =
113
+ /** No window of the reading applies to the route: the reading says nothing. */
114
+ | { readonly kind: 'unknown' }
115
+ /** An applicable started window is used up to the reserve. */
116
+ | { readonly kind: 'exhausted' }
117
+ | { readonly kind: 'usable'; readonly resetsAtMs: number | undefined }
118
+
119
+ /**
120
+ * The reset of the account's longest window with a length that applies to the route (undefined
121
+ * when it has not started, or no applicable window has a length). Unusable when no window applies
122
+ * or an applicable started window is used up to the reserve; a window whose reset has passed counts
123
+ * as fresh, whatever the reading said.
124
+ */
125
+ const accountRank = (
126
+ reading: PoolReading,
127
+ route: string,
128
+ nowMs: number,
129
+ reservePercent: number
130
+ ): AccountRank => {
131
+ let usable = false
132
+ let longest = 0
133
+ let resetsAtMs: number | undefined
134
+
135
+ for (const window of reading.windows) {
136
+ if (!appliesTo(window, route)) {
137
+ continue
138
+ }
139
+
140
+ const started = hasStarted(window, nowMs)
141
+
142
+ if (started && window.usedPercent >= 100 - reservePercent) {
143
+ return { kind: 'exhausted' }
144
+ }
145
+
146
+ usable = true
147
+
148
+ if (window.durationMinutes === undefined) {
149
+ continue
150
+ }
151
+
152
+ if (window.durationMinutes > longest) {
153
+ longest = window.durationMinutes
154
+ resetsAtMs = started ? window.resetsAtMs : undefined
155
+ } else if (
156
+ window.durationMinutes === longest &&
157
+ started &&
158
+ window.resetsAtMs !== undefined &&
159
+ (resetsAtMs === undefined || window.resetsAtMs < resetsAtMs)
160
+ ) {
161
+ resetsAtMs = window.resetsAtMs
162
+ }
163
+ }
164
+
165
+ return usable ? { kind: 'usable', resetsAtMs } : { kind: 'unknown' }
166
+ }
167
+
168
+ type Ranked = { readonly candidate: PoolCandidate; readonly resetsAtMs: number | undefined }
169
+
170
+ /** Code-unit id order, so ties never depend on locale. */
171
+ const idBefore = (a: string, b: string) => a < b
172
+
173
+ /**
174
+ * Started windows by soonest reset, then windows that have not started; ties by higher priority,
175
+ * then lower id.
176
+ */
177
+ const ranksBefore = (a: Ranked, b: Ranked) => {
178
+ if (a.resetsAtMs !== undefined && b.resetsAtMs !== undefined) {
179
+ if (a.resetsAtMs !== b.resetsAtMs) {
180
+ return a.resetsAtMs < b.resetsAtMs
181
+ }
182
+ } else if (a.resetsAtMs !== undefined || b.resetsAtMs !== undefined) {
183
+ return a.resetsAtMs !== undefined
184
+ }
185
+
186
+ if (a.candidate.priority !== b.candidate.priority) {
187
+ return a.candidate.priority > b.candidate.priority
188
+ }
189
+
190
+ return idBefore(a.candidate.id, b.candidate.id)
191
+ }
192
+
193
+ /** Highest priority, then lowest id. */
194
+ const fillFirst = (candidates: ReadonlyArray<PoolCandidate>): PoolCandidate | undefined => {
195
+ let best: PoolCandidate | undefined
196
+
197
+ for (const candidate of candidates) {
198
+ if (
199
+ best === undefined ||
200
+ candidate.priority > best.priority ||
201
+ (candidate.priority === best.priority && idBefore(candidate.id, best.id))
202
+ ) {
203
+ best = candidate
204
+ }
205
+ }
206
+
207
+ return best
208
+ }
209
+
210
+ /**
211
+ * Expiring-first: the available account whose longest applicable window resets soonest and still
212
+ * has quota. When no available account is usable by a fresh reading (within `maxAgeMs`), it routes
213
+ * stickily: the pin while it is available, else fill-first, preferring accounts that no fresh
214
+ * reading shows used up; those serve only when nothing else is left, so the provider's own answer
215
+ * decides. Undefined when no account is available.
216
+ */
217
+ export const rankPool = (input: PoolRankInput): PoolDecision | undefined => {
218
+ const candidates = input.accounts.filter(account => !input.unavailable.has(account.id))
219
+ const exhausted = new Set<string>()
220
+
221
+ let best: Ranked | undefined
222
+
223
+ for (const candidate of candidates) {
224
+ const reading = input.readings.get(candidate.id)
225
+
226
+ if (reading === undefined || input.nowMs - reading.fetchedAtMs > input.maxAgeMs) {
227
+ continue
228
+ }
229
+
230
+ const rank = accountRank(reading, input.route, input.nowMs, input.reservePercent)
231
+
232
+ if (rank.kind === 'exhausted') {
233
+ exhausted.add(candidate.id)
234
+ }
235
+
236
+ if (rank.kind !== 'usable') {
237
+ continue
238
+ }
239
+
240
+ const next: Ranked = { candidate, resetsAtMs: rank.resetsAtMs }
241
+
242
+ if (best === undefined || ranksBefore(next, best)) {
243
+ best = next
244
+ }
245
+ }
246
+
247
+ if (best !== undefined) {
248
+ return PoolDecision.Quota({ accountId: best.candidate.id, resetsAtMs: best.resetsAtMs })
249
+ }
250
+
251
+ const unexhausted = candidates.filter(candidate => !exhausted.has(candidate.id))
252
+ const fallback = unexhausted.length > 0 ? unexhausted : candidates
253
+
254
+ if (input.pin !== undefined && fallback.some(candidate => candidate.id === input.pin)) {
255
+ return PoolDecision.Sticky({ accountId: input.pin })
256
+ }
257
+
258
+ const first = fillFirst(fallback)
259
+
260
+ return first === undefined ? undefined : PoolDecision.FillFirst({ accountId: first.id })
261
+ }
262
+
263
+ /** Whether a cooldown still keeps its account out at `nowMs`. */
264
+ export const isCooldownActive = (cooldown: PoolCooldown, nowMs: number) => cooldown.untilMs > nowMs
265
+
266
+ /**
267
+ * Every account-wide window of the reading has quota left or has reset; model-scoped windows block
268
+ * only their models through ranking, never the whole account. A reading without account-wide
269
+ * windows proves nothing.
270
+ */
271
+ const hasQuotaLeft = (reading: PoolReading, nowMs: number) => {
272
+ const accountWide = reading.windows.filter(window => window.models.length === 0)
273
+
274
+ return (
275
+ accountWide.length > 0 &&
276
+ accountWide.every(window => !hasStarted(window, nowMs) || window.usedPercent < 100)
277
+ )
278
+ }
279
+
280
+ /**
281
+ * Active quota cooldowns that a fresh reading taken after they began shows to be over (a limit
282
+ * reset was spent, or the provider reset early). A reading from before the lockout never clears
283
+ * one, and auth cooldowns are never cleared by readings.
284
+ */
285
+ export const staleQuotaCooldowns = (input: {
286
+ readonly cooldowns: ReadonlyArray<PoolCooldown>
287
+ readonly readings: ReadonlyMap<string, PoolReading>
288
+ readonly nowMs: number
289
+ readonly maxAgeMs: number
290
+ }): ReadonlyArray<PoolCooldown> =>
291
+ input.cooldowns.filter(cooldown => {
292
+ if (
293
+ !Predicate.isTagged(cooldown, 'PoolQuotaCooldown') ||
294
+ !isCooldownActive(cooldown, input.nowMs)
295
+ ) {
296
+ return false
297
+ }
298
+
299
+ const reading = input.readings.get(cooldown.accountId)
300
+
301
+ return (
302
+ reading !== undefined &&
303
+ input.nowMs - reading.fetchedAtMs <= input.maxAgeMs &&
304
+ reading.fetchedAtMs > cooldown.startedAtMs &&
305
+ hasQuotaLeft(reading, input.nowMs)
306
+ )
307
+ })
package/src/store.ts ADDED
@@ -0,0 +1,392 @@
1
+ import { Chunk, Effect, Predicate } from 'effect'
2
+ import * as Schema from 'effect/Schema'
3
+ import { ProviderSubscriptionUsageSnapshot } from '@yolk-sdk/agent/providers/subscription-usage'
4
+ import {
5
+ PoolAccountId,
6
+ PoolAuthCooldown,
7
+ PoolPin,
8
+ PoolQuotaCooldown,
9
+ type PoolCooldown,
10
+ type PoolStoreError
11
+ } from './model.ts'
12
+
13
+ export { PoolStoreError } from './model.ts'
14
+
15
+ /** The latest usage snapshot of one account. */
16
+ export class PoolStoredReading extends Schema.Class<PoolStoredReading>('PoolStoredReading')({
17
+ accountId: PoolAccountId,
18
+ snapshot: ProviderSubscriptionUsageSnapshot
19
+ }) {}
20
+
21
+ /** What one pick reads: the route's pin plus the cooldowns and readings of the pool's accounts. */
22
+ export type PoolStoreSnapshot = {
23
+ readonly pin: PoolPin | undefined
24
+ readonly cooldowns: ReadonlyArray<PoolCooldown>
25
+ readonly readings: ReadonlyArray<PoolStoredReading>
26
+ }
27
+
28
+ /** Everything a store holds for one pool, for host UIs. */
29
+ export type PoolStoreState = {
30
+ readonly pins: ReadonlyArray<PoolPin>
31
+ readonly cooldowns: ReadonlyArray<PoolCooldown>
32
+ readonly readings: ReadonlyArray<PoolStoredReading>
33
+ }
34
+
35
+ /**
36
+ * Pool state shared by every instance of a host (ADR 0011). Hosts implement it on their database;
37
+ * `makeMemoryPoolStore` serves tests and single-process hosts, and `poolStoreContract` pins the
38
+ * semantics every implementation must meet.
39
+ *
40
+ * - Pins are keyed by `(poolId, route)`; cooldowns and readings by account id, so a cooldown or
41
+ * reading applies to every pool the account is in.
42
+ * - Operations must be atomic per key: concurrent `movePin` calls with the same `expected` let
43
+ * exactly one through.
44
+ */
45
+ export type PoolStoreApi = {
46
+ /** The route's pin and the requested accounts' cooldowns (expired ones included) and readings. */
47
+ readonly load: (input: {
48
+ readonly poolId: string
49
+ readonly route: string
50
+ readonly accountIds: ReadonlyArray<string>
51
+ }) => Effect.Effect<PoolStoreSnapshot, PoolStoreError>
52
+ /**
53
+ * Compare-and-set: writes `pin` when the route's current account is `expected` (`undefined`:
54
+ * the route has no pin yet). Returns whether it wrote.
55
+ */
56
+ readonly movePin: (input: {
57
+ readonly expected: string | undefined
58
+ readonly pin: PoolPin
59
+ }) => Effect.Effect<boolean, PoolStoreError>
60
+ /**
61
+ * Records a cooldown; when the account already has one, the one that ends later stays, and of two
62
+ * that end together the one that started later (a newer failure must not be cleared by a reading
63
+ * taken before it).
64
+ */
65
+ readonly putCooldown: (cooldown: PoolCooldown) => Effect.Effect<void, PoolStoreError>
66
+ /**
67
+ * Removes the account's cooldown only when it is the one observed (same `startedAtMs`). Returns
68
+ * whether it removed one.
69
+ */
70
+ readonly clearCooldown: (input: {
71
+ readonly accountId: string
72
+ readonly startedAtMs: number
73
+ }) => Effect.Effect<boolean, PoolStoreError>
74
+ /** Records a reading unless the stored one was fetched later. */
75
+ readonly putReading: (reading: PoolStoredReading) => Effect.Effect<void, PoolStoreError>
76
+ /** The pool's pins and the requested accounts' cooldowns and readings. */
77
+ readonly state: (input: {
78
+ readonly poolId: string
79
+ readonly accountIds: ReadonlyArray<string>
80
+ }) => Effect.Effect<PoolStoreState, PoolStoreError>
81
+ }
82
+
83
+ const pinKey = (poolId: string, route: string) => JSON.stringify([poolId, route])
84
+
85
+ const fetchedAtMs = (reading: PoolStoredReading) => Date.parse(reading.snapshot.fetchedAt)
86
+
87
+ /**
88
+ * An in-memory `PoolStoreApi`: state lives in this process only, so it suits tests and hosts that
89
+ * run one long-lived process. Serverless hosts implement the port on their database.
90
+ */
91
+ export const makeMemoryPoolStore = (): PoolStoreApi => {
92
+ const pins = new Map<string, PoolPin>()
93
+ const cooldowns = new Map<string, PoolCooldown>()
94
+ const readings = new Map<string, PoolStoredReading>()
95
+
96
+ const pick = <A>(source: Map<string, A>, accountIds: ReadonlyArray<string>) =>
97
+ accountIds.flatMap(accountId => {
98
+ const value = source.get(accountId)
99
+
100
+ return value === undefined ? [] : [value]
101
+ })
102
+
103
+ return {
104
+ load: input =>
105
+ Effect.sync(() => ({
106
+ pin: pins.get(pinKey(input.poolId, input.route)),
107
+ cooldowns: pick(cooldowns, input.accountIds),
108
+ readings: pick(readings, input.accountIds)
109
+ })),
110
+ movePin: input =>
111
+ Effect.sync(() => {
112
+ const key = pinKey(input.pin.poolId, input.pin.route)
113
+
114
+ if (pins.get(key)?.accountId !== input.expected) {
115
+ return false
116
+ }
117
+
118
+ pins.set(key, input.pin)
119
+
120
+ return true
121
+ }),
122
+ putCooldown: cooldown =>
123
+ Effect.sync(() => {
124
+ const current = cooldowns.get(cooldown.accountId)
125
+
126
+ if (
127
+ current === undefined ||
128
+ cooldown.untilMs > current.untilMs ||
129
+ (cooldown.untilMs === current.untilMs && cooldown.startedAtMs > current.startedAtMs)
130
+ ) {
131
+ cooldowns.set(cooldown.accountId, cooldown)
132
+ }
133
+ }),
134
+ clearCooldown: input =>
135
+ Effect.sync(() => {
136
+ const current = cooldowns.get(input.accountId)
137
+
138
+ if (current === undefined || current.startedAtMs !== input.startedAtMs) {
139
+ return false
140
+ }
141
+
142
+ cooldowns.delete(input.accountId)
143
+
144
+ return true
145
+ }),
146
+ putReading: reading =>
147
+ Effect.sync(() => {
148
+ const current = readings.get(reading.accountId)
149
+
150
+ if (current === undefined || fetchedAtMs(reading) >= fetchedAtMs(current)) {
151
+ readings.set(reading.accountId, reading)
152
+ }
153
+ }),
154
+ state: input =>
155
+ Effect.sync(() => ({
156
+ pins: Array.from(pins.values())
157
+ .filter(pin => pin.poolId === input.poolId)
158
+ .sort((a, b) => (a.route < b.route ? -1 : a.route > b.route ? 1 : 0)),
159
+ cooldowns: pick(cooldowns, input.accountIds),
160
+ readings: pick(readings, input.accountIds)
161
+ }))
162
+ }
163
+ }
164
+
165
+ /** A `PoolStoreApi` implementation broke the store contract. */
166
+ export class PoolStoreContractViolation extends Schema.TaggedError<PoolStoreContractViolation>()(
167
+ 'PoolStoreContractViolation',
168
+ {
169
+ case: Schema.String,
170
+ message: Schema.String
171
+ }
172
+ ) {}
173
+
174
+ /** One semantic every `PoolStoreApi` must meet. Run each case against a fresh, empty store. */
175
+ export type PoolStoreContractCase = {
176
+ readonly name: string
177
+ readonly run: (
178
+ store: PoolStoreApi
179
+ ) => Effect.Effect<void, PoolStoreContractViolation | PoolStoreError>
180
+ }
181
+
182
+ const contractCase = (
183
+ name: string,
184
+ run: (
185
+ store: PoolStoreApi,
186
+ expect: (condition: boolean, message: string) => Effect.Effect<void, PoolStoreContractViolation>
187
+ ) => Effect.Effect<void, PoolStoreContractViolation | PoolStoreError>
188
+ ): PoolStoreContractCase => ({
189
+ name,
190
+ run: store =>
191
+ run(store, (condition, message) =>
192
+ condition ? Effect.void : Effect.fail(new PoolStoreContractViolation({ case: name, message }))
193
+ )
194
+ })
195
+
196
+ const contractPin = (route: string, accountId: string, pinnedAtMs: number, poolId = 'pool') =>
197
+ PoolPin.make({ poolId, route, accountId, pinnedAtMs })
198
+
199
+ const contractReading = (accountId: string, fetchedAt: string) =>
200
+ PoolStoredReading.make({
201
+ accountId,
202
+ snapshot: ProviderSubscriptionUsageSnapshot.make({
203
+ provider: 'contract',
204
+ fetchedAt,
205
+ windows: Chunk.empty()
206
+ })
207
+ })
208
+
209
+ /** The `PoolStoreApi` contract. Hosts run every case against a fresh store of their implementation. */
210
+ export const poolStoreContract: ReadonlyArray<PoolStoreContractCase> = [
211
+ contractCase('pins are created once and moved by compare-and-set', (store, expect) =>
212
+ Effect.gen(function* () {
213
+ const load = store.load({ poolId: 'pool', route: 'model', accountIds: [] })
214
+
215
+ yield* expect((yield* load).pin === undefined, 'a new route has no pin')
216
+ yield* expect(
217
+ yield* store.movePin({ expected: undefined, pin: contractPin('model', 'a', 1) }),
218
+ 'the first pin is written'
219
+ )
220
+ yield* expect(
221
+ !(yield* store.movePin({ expected: undefined, pin: contractPin('model', 'b', 2) })),
222
+ 'creating a pin that already exists is refused'
223
+ )
224
+ yield* expect(
225
+ !(yield* store.movePin({ expected: 'b', pin: contractPin('model', 'c', 3) })),
226
+ 'a move expecting another account is refused'
227
+ )
228
+ yield* expect(
229
+ yield* store.movePin({ expected: 'a', pin: contractPin('model', 'b', 4) }),
230
+ 'a move expecting the current account is written'
231
+ )
232
+
233
+ const pin = (yield* load).pin
234
+
235
+ yield* expect(
236
+ pin?.accountId === 'b' && pin.pinnedAtMs === 4,
237
+ 'load returns the latest pin with its time'
238
+ )
239
+ })
240
+ ),
241
+ contractCase('pins are keyed by pool and route', (store, expect) =>
242
+ Effect.gen(function* () {
243
+ yield* store.movePin({ expected: undefined, pin: contractPin('one', 'a', 1) })
244
+ yield* store.movePin({ expected: undefined, pin: contractPin('two', 'b', 1) })
245
+ yield* store.movePin({ expected: undefined, pin: contractPin('one', 'c', 1, 'other') })
246
+
247
+ const one = yield* store.load({ poolId: 'pool', route: 'one', accountIds: [] })
248
+ const two = yield* store.load({ poolId: 'pool', route: 'two', accountIds: [] })
249
+ const other = yield* store.load({ poolId: 'other', route: 'one', accountIds: [] })
250
+
251
+ yield* expect(
252
+ one.pin?.accountId === 'a' && two.pin?.accountId === 'b' && other.pin?.accountId === 'c',
253
+ 'each (pool, route) keeps its own pin'
254
+ )
255
+
256
+ const state = yield* store.state({ poolId: 'pool', accountIds: [] })
257
+
258
+ yield* expect(
259
+ state.pins.map(pin => pin.route).join() === 'one,two',
260
+ 'state lists the pool’s pins only, ordered by route'
261
+ )
262
+ })
263
+ ),
264
+ contractCase('concurrent moves from the same pin let exactly one through', (store, expect) =>
265
+ Effect.gen(function* () {
266
+ yield* store.movePin({ expected: undefined, pin: contractPin('model', 'a', 1) })
267
+
268
+ const results = yield* Effect.all(
269
+ ['b', 'c', 'd', 'e'].map(accountId =>
270
+ store.movePin({ expected: 'a', pin: contractPin('model', accountId, 2) })
271
+ ),
272
+ { concurrency: 'unbounded' }
273
+ )
274
+
275
+ yield* expect(results.filter(Boolean).length === 1, 'exactly one move is written')
276
+ })
277
+ ),
278
+ contractCase('cooldowns keep the later end and clear only when observed', (store, expect) =>
279
+ Effect.gen(function* () {
280
+ const load = store.load({ poolId: 'pool', route: 'model', accountIds: ['a', 'b'] })
281
+
282
+ yield* store.putCooldown(
283
+ PoolQuotaCooldown.make({ accountId: 'a', startedAtMs: 1, untilMs: 100 })
284
+ )
285
+ yield* store.putCooldown(
286
+ PoolAuthCooldown.make({ accountId: 'a', startedAtMs: 2, untilMs: 50 })
287
+ )
288
+
289
+ const kept = (yield* load).cooldowns
290
+
291
+ yield* expect(
292
+ kept.length === 1 &&
293
+ Predicate.isTagged(kept[0], 'PoolQuotaCooldown') &&
294
+ kept[0].untilMs === 100,
295
+ 'an earlier-ending cooldown does not replace a later one'
296
+ )
297
+
298
+ yield* store.putCooldown(
299
+ PoolAuthCooldown.make({ accountId: 'a', startedAtMs: 3, untilMs: 200 })
300
+ )
301
+
302
+ const replaced = (yield* load).cooldowns
303
+
304
+ yield* expect(
305
+ replaced.length === 1 &&
306
+ Predicate.isTagged(replaced[0], 'PoolAuthCooldown') &&
307
+ replaced[0].startedAtMs === 3,
308
+ 'a later-ending cooldown replaces the current one'
309
+ )
310
+
311
+ yield* store.putCooldown(
312
+ PoolQuotaCooldown.make({ accountId: 'a', startedAtMs: 4, untilMs: 200 })
313
+ )
314
+
315
+ yield* store.putCooldown(
316
+ PoolQuotaCooldown.make({ accountId: 'a', startedAtMs: 2, untilMs: 200 })
317
+ )
318
+
319
+ const renewed = (yield* load).cooldowns
320
+
321
+ yield* expect(
322
+ renewed.length === 1 && renewed[0]?.startedAtMs === 4,
323
+ 'of two cooldowns that end together, the later-started one stays, whatever the write order'
324
+ )
325
+ yield* expect(
326
+ !(yield* store.clearCooldown({ accountId: 'a', startedAtMs: 3 })),
327
+ 'clearing a cooldown that is no longer current is refused'
328
+ )
329
+ yield* expect(
330
+ yield* store.clearCooldown({ accountId: 'a', startedAtMs: 4 }),
331
+ 'clearing the observed cooldown succeeds'
332
+ )
333
+ yield* expect((yield* load).cooldowns.length === 0, 'a cleared cooldown is gone')
334
+ yield* expect(
335
+ !(yield* store.clearCooldown({ accountId: 'b', startedAtMs: 3 })),
336
+ 'clearing an account without a cooldown is refused'
337
+ )
338
+ })
339
+ ),
340
+ contractCase(
341
+ 'cooldowns and readings are returned for the requested accounts only',
342
+ (store, expect) =>
343
+ Effect.gen(function* () {
344
+ yield* store.putCooldown(
345
+ PoolQuotaCooldown.make({ accountId: 'a', startedAtMs: 1, untilMs: 9 })
346
+ )
347
+ yield* store.putCooldown(
348
+ PoolQuotaCooldown.make({ accountId: 'b', startedAtMs: 1, untilMs: 9 })
349
+ )
350
+ yield* store.putReading(contractReading('a', '2026-10-15T12:00:00.000Z'))
351
+ yield* store.putReading(contractReading('b', '2026-10-15T12:00:00.000Z'))
352
+
353
+ const snapshot = yield* store.load({ poolId: 'pool', route: 'model', accountIds: ['b'] })
354
+ const state = yield* store.state({ poolId: 'pool', accountIds: ['a'] })
355
+
356
+ yield* expect(
357
+ snapshot.cooldowns.every(cooldown => cooldown.accountId === 'b') &&
358
+ snapshot.cooldowns.length === 1 &&
359
+ snapshot.readings.every(reading => reading.accountId === 'b') &&
360
+ snapshot.readings.length === 1,
361
+ 'load filters by account'
362
+ )
363
+ yield* expect(
364
+ state.cooldowns.length === 1 &&
365
+ state.cooldowns[0]?.accountId === 'a' &&
366
+ state.readings.length === 1 &&
367
+ state.readings[0]?.accountId === 'a',
368
+ 'state filters by account'
369
+ )
370
+ })
371
+ ),
372
+ contractCase('readings keep the latest fetch', (store, expect) =>
373
+ Effect.gen(function* () {
374
+ const load = store.load({ poolId: 'pool', route: 'model', accountIds: ['a'] })
375
+
376
+ yield* store.putReading(contractReading('a', '2026-10-15T12:00:00.000Z'))
377
+ yield* store.putReading(contractReading('a', '2026-10-15T11:00:00.000Z'))
378
+
379
+ yield* expect(
380
+ (yield* load).readings[0]?.snapshot.fetchedAt === '2026-10-15T12:00:00.000Z',
381
+ 'an older reading does not replace a newer one'
382
+ )
383
+
384
+ yield* store.putReading(contractReading('a', '2026-10-15T13:00:00.000Z'))
385
+
386
+ yield* expect(
387
+ (yield* load).readings[0]?.snapshot.fetchedAt === '2026-10-15T13:00:00.000Z',
388
+ 'a newer reading replaces the stored one'
389
+ )
390
+ })
391
+ )
392
+ ]