rate-limiter

1	# Ticket: Implement the Tidal credit limiter
2	
3	## Context
4	
5	`rate-limiter` is the throttling toolkit our API gateway uses to enforce
6	per-client quotas (TypeScript, Node 20). It already ships a token bucket and an
7	exact sliding-window log, both provided complete.
8	
9	We need a limiter for clients whose traffic is bursty but who we are willing to
10	let run a *controlled* deficit rather than hard-refusing during a spike. It is
11	the **Tidal credit limiter**: a client's spendable balance ebbs and refills
12	continuously, and a client may dip below the waterline (into debt) up to a fixed
13	depth before the tide has to come back in.
14	
15	Its rules are **deliberately not** those of a token bucket, leaky bucket (GCRA),
16	or sliding window. Implement exactly what is written below.
17	
18	## Your task
19	
20	Implement the single unimplemented method:
21	
22	```
23	src/limiter/tidal.ts  ->  TidalRateLimiter.tryAcquire(key, cost = 1): TidalResult
24	```
25	
26	The class, its options, validation, the per-key state map and `reset` are
27	already written. The decision logic is yours. `npm run typecheck` must stay
28	clean and you must not change the public surface (the constructor, option names,
29	exported types, or `reset`).
30	
31	## What the limiter must do
32	
33	Each **key** holds its spendable balance in **two pools** plus an owed balance,
34	all measured in the same units as `cost`:
35	
36	- a **burst pool** , fast and shallow. Capacity `Cb = capacity * burstFraction`,
37	  refilling from empty to `Cb` over `burstWindowMs` (rate `rb = Cb / burstWindowMs`
38	  per ms).
39	- a **sustained pool** , slow and deep. Capacity `Cs = capacity * (1 - burstFraction)`,
40	  refilling from empty to `Cs` over `sustainedWindowMs` (rate `rs = Cs / sustainedWindowMs`
41	  per ms). When `Cs = 0` its rate is `0`.
42	- an **owed balance** , how much the key currently owes from past borrowing.
43	
44	The two pool capacities sum to `capacity`; the **spendable balance** is
45	`burst + sustained`. A fresh key starts with both pools full and owes nothing.
46	Neither pool ever exceeds its own capacity.
47	
48	`burstFraction` is in `(0, 1]` and defaults to `1`. `burstWindowMs` and
49	`sustainedWindowMs` each default to `windowMs`. `repayFraction` is in `(0, 1]`
50	and defaults to `1`. `overdraft` is in `[0, 1)` and defaults to `0`. With the
51	defaults the sustained pool vanishes and the limiter reduces to a single pool of
52	size `capacity` refilling over `windowMs` , the original single-tier behavior.
53	
54	### Replenishment (how the balances change over time)
55	
56	Replenishment is **continuous, time-based and concurrent**: both pools accrue at
57	the same instant, each at its own rate, each capped at its own capacity. Accrual
58	depends only on elapsed time, never on whether requests were made.
59	
60	How accrual is applied depends on whether the key owes anything:
61	
62	- If the key owes **nothing**, the burst pool gains `rb` per ms and the sustained
63	  pool gains `rs` per ms (each clamped to its capacity).
64	- If the key **owes** something, a fixed proportion `repayFraction` of the
65	  **combined** inflow (`rb + rs` per ms) is diverted to reduce the owed balance,
66	  and each pool nets the remaining `(1 - repayFraction)` of its own rate. The
67	  amount directed at the owed balance is only ever as large as the owed balance
68	  itself: the instant the debt reaches zero, accrual reverts to the
69	  owes-nothing rule for the rest of the elapsed time. (So `repayFraction`
70	  controls *only* how inflow is shared while a debt exists.)
71	
72	Because the pools saturate at different times and the debt can clear partway
73	through, the spendable balance grows piecewise-linearly with breakpoints at
74	debt-clear, burst-full and sustained-full.
75	
76	### Admission (how a request is decided)
77	
78	When `tryAcquire(key, cost)` is called, first bring the balances up to the
79	current time, then decide:
80	
81	1. If the **spendable balance** (`burst + sustained`) covers `cost`, admit and
82	   deduct `cost`, **spending the burst pool first, then the sustained pool**.
83	   The owed balance is untouched.
84	2. Otherwise the request must **borrow** the shortfall (`cost` minus the
85	   spendable balance). Borrowing is allowed only while the owed balance would
86	   stay within the **borrowing limit** `capacity * overdraft`. If the shortfall
87	   fits, admit: drive **both pools to zero** and add the shortfall to the owed
88	   balance.
89	3. If even borrowing the shortfall would push the owed balance past the
90	   borrowing limit, **refuse**.
91	
92	With `overdraft = 0` there is no borrowing limit to speak of (the key can never
93	owe anything).
94	
95	### Refusal semantics
96	
97	A refused request **consumes nothing**: it changes neither pool, the owed
98	balance, nor anything else beyond advancing the key's bookkeeping to the current
99	time. Two refusals at the same instant must be identical.
100	
101	### Validation
102	
103	`cost` must be a finite number `>= 1`; otherwise throw
104	`RateLimitError("invalid_cost", ...)` **before** touching any state. Keys are
105	fully isolated.
106	
107	## Return contract , `TidalResult`
108	
109	- `allowed` , whether the request was admitted.
110	- `limit` , the configured `capacity`.
111	- `remaining` , whole units still drawable from the spendable balance (both
112	  pools) immediately after this decision, never negative (round down).
113	- `debtRemaining` , whole units the key still owes immediately after this
114	  decision, never negative (round up); `0` when it owes nothing.
115	- `retryAfterMs` , `0` when `allowed`. On a refusal, the **smallest whole number
116	  of milliseconds** such that, if the caller waited exactly that long and retried
117	  **the same `cost`** (with no other traffic on the key in between), the retry
118	  would be admitted , and waiting any whole millisecond less would still be
119	  refused. This is the exact minimum wait under the two-tier refill and repay
120	  dynamics above; it generally steps across the refill breakpoints and has no
121	  single closed form.
122	- `resetMs` , whole milliseconds from now until the key is **fully replenished**:
123	  both pools at their capacities and owing nothing. `0` if already there.
124	
125	Balances are real-valued; treat them as exact to within about a millionth of a
126	unit when comparing (so a `cost` exactly equal to the spendable balance is
127	covered, and an owed balance exactly at the borrowing limit is within it). The
128	whole-unit fields are the floor/ceil of those real balances.
129	
130	## Definition of done
131	
132	- `npm run typecheck` is clean.
133	- The shipped smoke test (`test/smoke.test.ts`) still passes.
134	- Your `TidalRateLimiter.tryAcquire` implements the contract above. It is graded
135	  by a separate, hidden suite checking admissions, balances, timing fields, edge
136	  cases and randomized workloads against an independent reference.
137	- Implement `tryAcquire` only; do not modify the other files, the public surface,
138	  or the provided limiters.
139	
140	## Running locally
141	
142	```bash
143	npm install      # already done in the provided environment
144	npm run typecheck
145	npm test
146	```
147

1	import { RateLimitError } from "./errors.js";
2	import { systemClock } from "./clock.js";
3	import type { Clock, TidalResult } from "./types.js";
4	
5	export interface TidalOptions {
6	  /** Capacity: the spendable balance a fresh key starts with, and its ceiling. Finite, >= 1. */
7	  capacity: number;
8	  /** Window length in ms over which a full `capacity` worth of balance is replenished. Finite, >= 1. */
9	  windowMs: number;
10	  /**
11	   * Overdraft fraction in [0, 1). Controls how deep a key may go into the
12	   * negative (its borrowing limit) relative to `capacity`. Default 0 (no
13	   * borrowing). See `instruction.md` for the exact borrowing contract.
14	   */
15	  overdraft?: number;
16	  /**
17	   * Repay fraction in (0, 1]. Controls how the continuous replenishment is
18	   * apportioned while a key owes a balance. Default 1. See `instruction.md`.
19	   */
20	  repayFraction?: number;
21	  /**
22	   * Burst fraction in (0, 1]. Share of `capacity` held in the fast burst pool;
23	   * the rest is the slow sustained pool. Default 1. See `instruction.md`.
24	   */
25	  burstFraction?: number;
26	  /** Window (ms) over which the burst pool refills. Default `windowMs`. See `instruction.md`. */
27	  burstWindowMs?: number;
28	  /** Window (ms) over which the sustained pool refills. Default `windowMs`. See `instruction.md`. */
29	  sustainedWindowMs?: number;
30	  /** Injectable clock. Defaults to the system clock. */
31	  clock?: Clock;
32	}
33	
34	/** Per-key accounting state. */
35	interface TidalState {
36	  /** Burst pool balance (>= 0). */
37	  burst: number;
38	  /** Sustained pool balance (>= 0). */
39	  sustained: number;
40	  /** Balance currently owed (>= 0). */
41	  debt: number;
42	  /** Instant (epoch ms) the balances were last advanced to. */
43	  updatedAt: number;
44	}
45	
46	/**
47	 * Tidal credit limiter.
48	 *
49	 * A bespoke single-key limiter built around two replenishing spendable pools (a
50	 * fast burst pool and a slow sustained pool) plus a separate owed balance. Its
51	 * admission, replenishment and borrowing rules are NOT those of a textbook
52	 * token bucket / leaky bucket / sliding window , implement exactly the
53	 * behavioral contract documented in `instruction.md`.
54	 *
55	 * The constructor, validation, per-key state map and {@link reset} are provided.
56	 * The decision logic in {@link tryAcquire} is the unimplemented core.
57	 */
58	export class TidalRateLimiter {
59	  protected readonly capacity: number;
60	  protected readonly windowMs: number;
61	  protected readonly overdraft: number;
62	  protected readonly repayFraction: number;
63	  protected readonly clock: Clock;
64	  protected readonly state = new Map<string, TidalState>();
65	
66	  /** Burst pool capacity (`capacity * burstFraction`). */
67	  protected readonly burstCapacity: number;
68	  /** Sustained pool capacity (`capacity * (1 - burstFraction)`). */
69	  protected readonly sustainedCapacity: number;
70	  /** Burst pool refill rate, units per ms. */
71	  protected readonly burstRate: number;
72	  /** Sustained pool refill rate, units per ms. */
73	  protected readonly sustainedRate: number;
74	  /** Borrowing limit (`capacity * overdraft`). */
75	  protected readonly maxDebt: number;
76	
77	  constructor(options: TidalOptions) {
78	    if (!Number.isFinite(options.capacity) || options.capacity < 1) {
79	      throw new RateLimitError("invalid_capacity", "capacity must be a finite number >= 1");
80	    }
81	    if (!Number.isFinite(options.windowMs) || options.windowMs < 1) {
82	      throw new RateLimitError("invalid_window", "windowMs must be a finite number >= 1");
83	    }
84	    const overdraft = options.overdraft ?? 0;
85	    if (!Number.isFinite(overdraft) || overdraft < 0 || overdraft >= 1) {
86	      throw new RateLimitError("invalid_overdraft", "overdraft must be a finite number in [0, 1)");
87	    }
88	    const repayFraction = options.repayFraction ?? 1;
89	    if (!Number.isFinite(repayFraction) || repayFraction <= 0 || repayFraction > 1) {
90	      throw new RateLimitError("invalid_repay", "repayFraction must be a finite number in (0, 1]");
91	    }
92	    const burstFraction = options.burstFraction ?? 1;
93	    if (!Number.isFinite(burstFraction) || burstFraction <= 0 || burstFraction > 1) {
94	      throw new RateLimitError("invalid_burst", "burstFraction must be a finite number in (0, 1]");
95	    }
96	    const burstWindowMs = options.burstWindowMs ?? options.windowMs;
97	    if (!Number.isFinite(burstWindowMs) || burstWindowMs < 1) {
98	      throw new RateLimitError("invalid_window", "burstWindowMs must be a finite number >= 1");
99	    }
100	    const sustainedWindowMs = options.sustainedWindowMs ?? options.windowMs;
101	    if (!Number.isFinite(sustainedWindowMs) || sustainedWindowMs < 1) {
102	      throw new RateLimitError("invalid_window", "sustainedWindowMs must be a finite number >= 1");
103	    }
104	    this.capacity = options.capacity;
105	    this.windowMs = options.windowMs;
106	    this.overdraft = overdraft;
107	    this.repayFraction = repayFraction;
108	    this.clock = options.clock ?? systemClock;
109	    this.burstCapacity = options.capacity * burstFraction;
110	    this.sustainedCapacity = options.capacity * (1 - burstFraction);
111	    this.burstRate = this.burstCapacity / burstWindowMs;
112	    this.sustainedRate = this.sustainedCapacity > 0 ? this.sustainedCapacity / sustainedWindowMs : 0;
113	    this.maxDebt = options.capacity * overdraft;
114	  }
115	
116	  /** Drop all state for `key`. Returns true iff state existed. */
117	  reset(key: string): boolean {
118	    return this.state.delete(key);
119	  }
120	
121	  /**
122	   * Look up (creating if absent) the accounting state for `key`. A fresh key
123	   * starts with both pools full, no owed balance, last-updated `now`.
124	   */
125	  protected stateFor(key: string, now: number): TidalState {
126	    let s = this.state.get(key);
127	    if (!s) {
128	      s = { burst: this.burstCapacity, sustained: this.sustainedCapacity, debt: 0, updatedAt: now };
129	      this.state.set(key, s);
130	    }
131	    return s;
132	  }
133	
134	  /**
135	   * Attempt to admit `cost` units (default 1) for `key` at the current time,
136	   * per the behavioral contract in `instruction.md`.
137	   *
138	   * Validate `cost` (non-finite or `< 1` throws `RateLimitError("invalid_cost")`)
139	   * before touching any state, keep keys isolated, and return a fully-populated
140	   * {@link TidalResult}.
141	   */
142	  tryAcquire(key: string, cost = 1): TidalResult {
143	    void this.capacity;
144	    void this.windowMs;
145	    void this.overdraft;
146	    void this.repayFraction;
147	    void this.clock;
148	    void this.state;
149	    void this.stateFor;
150	    void this.burstCapacity;
151	    void this.sustainedCapacity;
152	    void this.burstRate;
153	    void this.sustainedRate;
154	    void this.maxDebt;
155	    void RateLimitError;
156	    void key;
157	    void cost;
158	
159	    // TODO(limiter): implement the Tidal credit limiter contract from instruction.md.
160	    throw new Error("TidalRateLimiter.tryAcquire not implemented");
161	  }
162	}
163

1	/**
2	 * Types for the rate-limiter toolkit.
3	 *
4	 * The toolkit ships several limiter strategies behind a common surface. Two are
5	 * provided complete as references:
6	 *
7	 *   - a **token bucket** , smooth, burst-tolerant throttling that refills
8	 *     continuously at a fixed rate;
9	 *   - a **sliding-window log** , exact "at most N units per rolling window"
10	 *     accounting backed by per-key event timestamps.
11	 *
12	 * A third strategy, the {@link TidalRateLimiter}, is the unimplemented core of
13	 * this exercise; see `instruction.md` for its behavioral contract.
14	 *
15	 * Every limiter is deterministic under an injectable {@link Clock} so that
16	 * windows advance at controlled instants in tests.
17	 */
18	
19	export interface Clock {
20	  /** Current time in epoch milliseconds. */
21	  now(): number;
22	}
23	
24	/**
25	 * The outcome of an attempt to admit some units of work for a key.
26	 *
27	 * `allowed` says whether the request may proceed. The remaining fields are
28	 * advisory and power `X-RateLimit-*` style response headers:
29	 *
30	 *   - `remaining` , whole units still drawable from the key's spendable balance
31	 *     immediately after this decision (never negative).
32	 *   - `limit` , the configured capacity for the key.
33	 *   - `retryAfterMs` , when `allowed` is false, the soonest a retry of the same
34	 *     request could succeed (ms from now); `0` when allowed.
35	 *   - `resetMs` , ms from now until the limiter is fully replenished for the key.
36	 */
37	export interface RateLimitResult {
38	  allowed: boolean;
39	  remaining: number;
40	  limit: number;
41	  retryAfterMs: number;
42	  resetMs: number;
43	}
44	
45	/** Common surface implemented by the simple (single-balance) limiter strategies. */
46	export interface RateLimiter {
47	  /**
48	   * Attempt to admit `cost` units (default 1) for `key` at the current time.
49	   * Quota is consumed only when the request is admitted.
50	   */
51	  tryAcquire(key: string, cost?: number): RateLimitResult;
52	  /** Drop all state for `key` (e.g. on logout). Returns true iff state existed. */
53	  reset(key: string): boolean;
54	}
55	
56	/**
57	 * The outcome returned by {@link TidalRateLimiter.tryAcquire}. Identical to
58	 * {@link RateLimitResult} plus one extra advisory field:
59	 *
60	 *   - `debtRemaining` , the whole units of outstanding balance the key currently
61	 *     owes (rounded up), immediately after this decision; `0` when the key owes
62	 *     nothing.
63	 */
64	export interface TidalResult extends RateLimitResult {
65	  debtRemaining: number;
66	}
67

File does not exist. Note: your current working directory is /home/user/app.

src:
index.ts
limiter

src/limiter:
clock.ts
errors.ts
slidingWindow.ts
tidal.ts
tokenBucket.ts
types.ts
windowLog.ts

test:
smoke.test.ts
---
{
  "name": "rate-limiter",
  "version": "0.4.0",
  "private": true,
  "description": "Rate-limiting toolkit: token-bucket and exact sliding-window-log limiters behind a common interface.",
  "type": "module",
  "engines": {
    "node": ">=20"
  },
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "typecheck": "tsc -p tsconfig.json --noEmit",
    "test": "vitest run",
    "test:watch": "vitest"
  },
  "devDependencies": {
    "@types/node": "20.14.10",
    "typescript": "5.5.3",
    "vitest": "1.6.0"
  }
}

1	import { RateLimitError } from "./errors.js";
2	import { systemClock } from "./clock.js";
3	import type { Clock, RateLimiter, RateLimitResult } from "./types.js";
4	
5	export interface TokenBucketOptions {
6	  /** Bucket capacity (max burst). Must be a finite number >= 1. */
7	  capacity: number;
8	  /** Sustained refill rate in tokens per second. Must be finite and > 0. */
9	  refillPerSec: number;
10	  /** Injectable clock for deterministic tests. Defaults to the system clock. */
11	  clock?: Clock;
12	}
13	
14	interface Bucket {
15	  /** Fractional tokens currently available. */
16	  tokens: number;
17	  /** Last instant (epoch ms) at which `tokens` was brought up to date. */
18	  updatedAt: number;
19	}
20	
21	/**
22	 * Classic token-bucket limiter: a bucket holds up to `capacity` tokens and
23	 * refills continuously at `refillPerSec`. Each admitted request removes `cost`
24	 * tokens; a request is refused when fewer than `cost` tokens are available.
25	 *
26	 * Provided complete and used as the reference sibling for the sliding-window
27	 * limiter you are asked to implement , study how it lazily accrues tokens, never
28	 * over-fills past capacity, and mutates state only on admission.
29	 */
30	export class TokenBucketRateLimiter implements RateLimiter {
31	  private readonly capacity: number;
32	  private readonly refillPerMs: number;
33	  private readonly clock: Clock;
34	  private readonly buckets = new Map<string, Bucket>();
35	
36	  constructor(options: TokenBucketOptions) {
37	    if (!Number.isFinite(options.capacity) || options.capacity < 1) {
38	      throw new RateLimitError("invalid_capacity", "capacity must be a finite number >= 1");
39	    }
40	    if (!Number.isFinite(options.refillPerSec) || options.refillPerSec <= 0) {
41	      throw new RateLimitError("invalid_refill", "refillPerSec must be a finite number > 0");
42	    }
43	    this.capacity = options.capacity;
44	    this.refillPerMs = options.refillPerSec / 1000;
45	    this.clock = options.clock ?? systemClock;
46	  }
47	
48	  tryAcquire(key: string, cost = 1): RateLimitResult {
49	    if (!Number.isFinite(cost) || cost < 1) {
50	      throw new RateLimitError("invalid_cost", "cost must be a finite number >= 1");
51	    }
52	    const now = this.clock.now();
53	    const bucket = this.refilled(key, now);
54	
55	    if (bucket.tokens >= cost) {
56	      bucket.tokens -= cost;
57	      return this.result(true, bucket);
58	    }
59	    return this.result(false, bucket, cost);
60	  }
61	
62	  reset(key: string): boolean {
63	    return this.buckets.delete(key);
64	  }
65	
66	  /** Bring a key's bucket up to date with elapsed refill, creating it if absent. */
67	  private refilled(key: string, now: number): Bucket {
68	    let bucket = this.buckets.get(key);
69	    if (!bucket) {
70	      bucket = { tokens: this.capacity, updatedAt: now };
71	      this.buckets.set(key, bucket);
72	      return bucket;
73	    }
74	    const elapsed = Math.max(0, now - bucket.updatedAt);
75	    if (elapsed > 0) {
76	      bucket.tokens = Math.min(this.capacity, bucket.tokens + elapsed * this.refillPerMs);
77	      bucket.updatedAt = now;
78	    }
79	    return bucket;
80	  }
81	
82	  private result(allowed: boolean, bucket: Bucket, cost = 0): RateLimitResult {
83	    const remaining = Math.max(0, Math.floor(bucket.tokens));
84	    const deficit = allowed ? 0 : cost - bucket.tokens;
85	    const retryAfterMs = allowed ? 0 : Math.ceil(deficit / this.refillPerMs);
86	    const missingToFull = this.capacity - bucket.tokens;
87	    const resetMs = missingToFull <= 0 ? 0 : Math.ceil(missingToFull / this.refillPerMs);
88	    return { allowed, remaining, limit: this.capacity, retryAfterMs, resetMs };
89	  }
90	}
91

1	/**
2	 * Typed errors for the rate-limiter. A single class with a stable `code`
3	 * discriminator keeps call sites and tests decoupled from message wording.
4	 */
5	export type RateLimitErrorCode =
6	  | "invalid_capacity"
7	  | "invalid_window"
8	  | "invalid_refill"
9	  | "invalid_overdraft"
10	  | "invalid_repay"
11	  | "invalid_burst"
12	  | "invalid_cost";
13	
14	export class RateLimitError extends Error {
15	  readonly code: RateLimitErrorCode;
16	
17	  constructor(code: RateLimitErrorCode, message: string) {
18	    super(message);
19	    this.name = "RateLimitError";
20	    this.code = code;
21	    Object.setPrototypeOf(this, RateLimitError.prototype);
22	  }
23	}
24

1	import { describe, expect, it } from "vitest";
2	import {
3	  TidalRateLimiter,
4	  TokenBucketRateLimiter,
5	  SlidingWindowRateLimiter,
6	  RateLimitError,
7	  ManualClock,
8	} from "../src/index.js";
9	
10	/**
11	 * Trivial smoke test for the shipped project: it only checks that the public
12	 * surface is importable and that the provided constructor validation rejects
13	 * obviously-bad options. It deliberately does NOT exercise admission behavior , 
14	 * the behavioral contract lives in instruction.md and is graded separately.
15	 */
16	describe("toolkit smoke", () => {
17	  it("exposes the limiter classes", () => {
18	    expect(typeof TidalRateLimiter).toBe("function");
19	    expect(typeof TokenBucketRateLimiter).toBe("function");
20	    expect(typeof SlidingWindowRateLimiter).toBe("function");
21	  });
22	
23	  it("TidalRateLimiter validates its options", () => {
24	    const clock = new ManualClock(0);
25	    expect(() => new TidalRateLimiter({ capacity: 0, windowMs: 1000, clock })).toThrowError(RateLimitError);
26	    expect(() => new TidalRateLimiter({ capacity: 5, windowMs: 0, clock })).toThrowError(RateLimitError);
27	    expect(() => new TidalRateLimiter({ capacity: 5, windowMs: 1000, overdraft: 1, clock })).toThrowError(
28	      RateLimitError,
29	    );
30	    expect(() => new TidalRateLimiter({ capacity: 5, windowMs: 1000, repayFraction: 0, clock })).toThrowError(
31	      RateLimitError,
32	    );
33	    // A valid construction does not throw.
34	    expect(
35	      () => new TidalRateLimiter({ capacity: 5, windowMs: 1000, overdraft: 0.5, repayFraction: 0.5, clock }),
36	    ).not.toThrow();
37	  });
38	
39	  it("reset on an unknown key returns false", () => {
40	    const clock = new ManualClock(0);
41	    const g = new TidalRateLimiter({ capacity: 5, windowMs: 1000, clock });
42	    expect(g.reset("never-seen")).toBe(false);
43	  });
44	});
45

1	/**
2	 * Injectable time source. Tests use {@link ManualClock} so rate-limit windows
3	 * advance at exact, controlled instants; production uses {@link systemClock}.
4	 *
5	 * Provided complete.
6	 */
7	import type { Clock } from "./types.js";
8	
9	export class ManualClock implements Clock {
10	  private current: number;
11	
12	  constructor(start = 0) {
13	    this.current = start;
14	  }
15	
16	  now(): number {
17	    return this.current;
18	  }
19	
20	  advance(ms: number): void {
21	    if (ms < 0) throw new Error("cannot advance time backwards");
22	    this.current += ms;
23	  }
24	
25	  set(ms: number): void {
26	    this.current = ms;
27	  }
28	}
29	
30	export const systemClock: Clock = {
31	  now: () => Date.now(),
32	};
33

1	/**
2	 * Public surface of the rate-limiter toolkit.
3	 */
4	export { TokenBucketRateLimiter } from "./limiter/tokenBucket.js";
5	export type { TokenBucketOptions } from "./limiter/tokenBucket.js";
6	export { SlidingWindowRateLimiter } from "./limiter/slidingWindow.js";
7	export type { SlidingWindowOptions } from "./limiter/slidingWindow.js";
8	export { EventLog } from "./limiter/windowLog.js";
9	
10	// The Tidal credit limiter (the unimplemented core of this exercise).
11	export { TidalRateLimiter } from "./limiter/tidal.js";
12	export type { TidalOptions } from "./limiter/tidal.js";
13	
14	export { ManualClock, systemClock } from "./limiter/clock.js";
15	export { RateLimitError } from "./limiter/errors.js";
16	export type { RateLimitErrorCode } from "./limiter/errors.js";
17	export type { Clock, RateLimiter, RateLimitResult, TidalResult } from "./limiter/types.js";
18

The file /home/user/app/src/limiter/tidal.ts has been updated successfully. (file state is current in your context , no need to Read it back)

> rate-limiter@0.4.0 typecheck
> tsc -p tsconfig.json --noEmit

> rate-limiter@0.4.0 test
> vitest run


 RUN  v1.6.0 /home/user/app

 ✓ test/smoke.test.ts  (3 tests) 3ms

 Test Files  1 passed (1)
      Tests  3 passed (3)
   Start at  20:27:55
   Duration  405ms (transform 135ms, setup 0ms, collect 154ms, tests 3ms, environment 0ms, prepare 107ms)

use tsx instead
vitest

File created successfully at: /home/user/app/scratch_verify.test.ts (file state is current in your context , no need to Read it back)

RUN  v1.6.0 /home/user/app

filter:  scratch_verify.test.ts
include: test/**/*.test.ts
exclude:  **/node_modules/**, **/dist/**, **/cypress/**, **/.{idea,git,cache,output,temp}/**, **/{karma,rollup,webpack,vite,vitest,jest,ava,babel,nyc,cypress,tsup,build,eslint,prettier}.config.*
watch exclude:  **/node_modules/**, **/dist/**

No test files found, exiting with code 1

RUN  v1.6.0 /home/user/app

 ❯ test/scratch_verify.test.ts  (0 test)

⎯⎯⎯⎯⎯⎯ Failed Suites 1 ⎯⎯⎯⎯⎯⎯⎯

 FAIL  test/scratch_verify.test.ts [ test/scratch_verify.test.ts ]
Error: Failed to load url ./src/index.js (resolved id: ./src/index.js) in /home/user/app/test/scratch_verify.test.ts. Does the file exist?
 ❯ loadAndTransform node_modules/vite/dist/node/chunks/dep-BK3b2jBa.js:51969:17

⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[1/1]⎯

 Test Files  1 failed (1)
      Tests  no tests
   Start at  20:28:26
   Duration  273ms (transform 42ms, setup 0ms, collect 0ms, tests 0ms, environment 0ms, prepare 94ms)

RUN  v1.6.0 /home/user/app

 ✓ test/scratch_verify.test.ts  (5 tests) 7ms
stdout | test/scratch_verify.test.ts > tidal manual checks > overdraft borrowing
retryAfter after over-borrow: 100 reset: 1500


 Test Files  1 passed (1)
      Tests  5 passed (5)
   Start at  20:28:29
   Duration  363ms (transform 119ms, setup 0ms, collect 137ms, tests 7ms, environment 0ms, prepare 98ms)

<tool_use_error>File has not been read yet. Read it first before writing to it.</tool_use_error>

1	import { describe, it, expect } from "vitest";
2	import { TidalRateLimiter, ManualClock } from "../src/index.js";
3

The file /home/user/app/test/scratch_verify.test.ts has been updated successfully. (file state is current in your context , no need to Read it back)

RUN  v1.6.0 /home/user/app

 ✓ test/scratch_verify.test.ts  (3 tests) 4ms

 Test Files  1 passed (1)
      Tests  3 passed (3)
   Start at  20:29:24
   Duration  360ms (transform 119ms, setup 0ms, collect 132ms, tests 4ms, environment 0ms, prepare 90ms)

The file /home/user/app/test/scratch_verify.test.ts has been updated successfully. (file state is current in your context , no need to Read it back)

The file /home/user/app/test/scratch_verify.test.ts has been updated successfully. (file state is current in your context , no need to Read it back)

RUN  v1.6.0 /home/user/app

 ✓ test/scratch_verify.test.ts  (2 tests) 205ms

 Test Files  1 passed (1)
      Tests  2 passed (2)
   Start at  20:30:47
   Duration  606ms (transform 141ms, setup 0ms, collect 167ms, tests 205ms, environment 0ms, prepare 94ms)

The file /home/user/app/test/scratch_verify.test.ts has been updated successfully. (file state is current in your context , no need to Read it back)

RUN  v1.6.0 /home/user/app

 ✓ test/scratch_verify.test.ts  (3 tests) 218ms

 Test Files  1 passed (1)
      Tests  3 passed (3)
   Start at  20:31:02
   Duration  639ms (transform 150ms, setup 0ms, collect 192ms, tests 218ms, environment 0ms, prepare 88ms)

> rate-limiter@0.4.0 typecheck
> tsc -p tsconfig.json --noEmit

=== TEST ===

 ✓ test/smoke.test.ts  (3 tests) 4ms

 Test Files  1 passed (1)
      Tests  3 passed (3)
   Start at  20:31:09
   Duration  442ms (transform 145ms, setup 0ms, collect 175ms, tests 4ms, environment 0ms, prepare 116ms)

142	  tryAcquire(key: string, cost = 1): TidalResult {
143	    if (!Number.isFinite(cost) || cost < 1) {
144	      throw new RateLimitError("invalid_cost", "cost must be a finite number >= 1");
145	    }
146	
147	    const now = this.clock.now();
148	    const s = this.stateFor(key, now);
149	    this.advance(s, now);
150	
151	    const spendable = s.burst + s.sustained;
152	    let allowed: boolean;
153	
154	    if (spendable + TOL >= cost) {
155	      // Case 1: covered by the spendable balance , spend burst first, then sustained.
156	      allowed = true;
157	      const fromBurst = Math.min(s.burst, cost);
158	      s.burst = clampZero(s.burst - fromBurst);
159	      s.sustained = clampZero(s.sustained - (cost - fromBurst));
160	    } else {
161	      // Case 2/3: must borrow the shortfall against the owed balance.
162	      const shortfall = cost - spendable;
163	      const newDebt = s.debt + shortfall;
164	      if (newDebt <= this.maxDebt + TOL) {
165	        allowed = true;
166	        s.burst = 0;
167	        s.sustained = 0;
168	        s.debt = newDebt;
169	      } else {
170	        allowed = false; // Refusal consumes nothing.
171	      }
172	    }
173	
174	    const remaining = Math.max(0, Math.floor(s.burst + s.sustained + TOL));
175	    const debtRemaining = s.debt <= TOL ? 0 : Math.max(0, Math.ceil(s.debt - TOL));
176	    const resetMs = this.timeToFull(s);
177	    const retryAfterMs = allowed ? 0 : this.timeToAdmit(s, cost);
178	
179	    return {
180	      allowed,
181	      limit: this.capacity,
182	      remaining,
183	      debtRemaining,
184	      retryAfterMs,
185	      resetMs,
186	    };
187	  }
188	
189	  /**
190	   * Bring a key's pools and owed balance up to `now`, applying the continuous,
191	   * concurrent two-pool replenishment (with repayment-while-in-debt) described
192	   * in `instruction.md`.
193	   */
194	  private advance(s: TidalState, now: number): void {
195	    let dt = Math.max(0, now - s.updatedAt);
196	    s.updatedAt = now;
197	    if (dt <= 0) return;
198	
199	    const Cb = this.burstCapacity;
200	    const Cs = this.sustainedCapacity;
201	    const rb = this.burstRate;