pixivflow 2.16.0 → 2.17.0

package/node_modules/@redtidev/pixiv-client/src/rate-limit/RateLimitGate.ts

@@ -0,0 +1,365 @@
+import { setTimeout as delay } from 'node:timers/promises';
+
+import { PixivAbortError, PixivCircuitOpenError } from '../errors/errors';
+import type { KitLogger } from '../logger';
+import type {
+  KitEventListener,
+  RateLimitOptions,
+  RateLimitState,
+  RateLimitStateStore,
+  RateLimitStatus,
+} from '../types';
+
+/** Conservative gate defaults (see packages/pixiv-client/README.md). */
+export const DEFAULT_RATE_LIMIT: Required<
+  Pick<
+    RateLimitOptions,
+    | 'minIntervalMs'
+    | 'jitterRatio'
+    | 'initialCooldownMs'
+    | 'maxCooldownMs'
+    | 'decaySuccesses'
+    | 'openThreshold'
+    | 'scope'
+  >
+> = {
+  minIntervalMs: 1000,
+  jitterRatio: 0.25,
+  initialCooldownMs: 60_000,
+  maxCooldownMs: 15 * 60_000,
+  decaySuccesses: 20,
+  openThreshold: 4,
+  scope: 'default',
+};
+
+function freshState(now: number): RateLimitState {
+  return {
+    nextAllowedAt: 0,
+    cooldownUntil: 0,
+    penaltyLevel: 0,
+    last429At: null,
+    circuitState: 'closed',
+    consecutiveSuccesses: 0,
+    updatedAt: now,
+  };
+}
+
+/** Process-local state store, used when the host injects no persistence. */
+export class MemoryRateLimitStateStore implements RateLimitStateStore {
+  private readonly map = new Map<string, RateLimitState>();
+  load(scope: string): RateLimitState | null {
+    return this.map.get(scope) ?? null;
+  }
+  save(scope: string, state: RateLimitState): void {
+    // Clone so later in-place mutations cannot mutate the stored snapshot.
+    this.map.set(scope, { ...state });
+  }
+}
+
+/**
+ * Pacing/cooldown waits MUST keep the event loop referenced: an unref'd timer
+ * lets a CLI/script process exit silently mid-wait instead of sending the
+ * request (observed as requests that "never happen" with exit code 0).
+ */
+const defaultSleep = (ms: number, signal?: AbortSignal) =>
+  delay(ms, undefined, signal ? { signal } : undefined);
+
+/**
+ * The single shared gate for ALL Pixiv traffic of one client.
+ *
+ * Two responsibilities, both fixed here instead of spread across callers:
+ *
+ * 1. Pacing via SLOT RESERVATION. `acquire()` synchronously reserves the next
+ *    send instant before it awaits anything. N concurrent callers therefore
+ *    leave at t0, t0+interval, t0+2*interval ... instead of all waking from
+ *    the same `nextAllowedAt` simultaneously (the old burst bug).
+ *
+ * 2. The global 429 cooldown + circuit breaker. A 429 anywhere parks the
+ *    whole client (other requests wait at the gate, they do not fire); at
+ *    openThreshold consecutive penalties the circuit opens and requests fast
+ *    fail until one half-open probe succeeds.
+ */
+export class RateLimitGate {
+  private readonly minIntervalMs: number;
+  private readonly jitterRatio: number;
+  private readonly initialCooldownMs: number;
+  private readonly maxCooldownMs: number;
+  private readonly decaySuccesses: number;
+  private readonly openThreshold: number;
+  private readonly scope: string;
+  private readonly store: RateLimitStateStore;
+  private readonly clock: () => number;
+  private readonly sleeper: (ms: number, signal?: AbortSignal) => Promise<void>;
+  private readonly random: () => number;
+  private state: RateLimitState | null = null;
+  private loaded: Promise<void> | null = null;
+  /**
+   * Reservation chain. Callers may REACH acquire() at different microtask
+   * times (auth token fetch, coalescing), so synchronously mutating the slot
+   * cursor is not enough: each caller must reserve strictly after the previous
+   * caller reserved. The chain serializes ONLY the reservation, never the
+   * request itself.
+   */
+  private reservationQueue: Promise<void> = Promise.resolve();
+
+  /**
+   * Synchronously warm the state from a state store whose load() is sync
+   * (MemoryRateLimitStateStore, better-sqlite3, ...). Reservation in
+   * {@link acquire} then happens with NO preceding await, which is what makes
+   * concurrent callers serialize (A 0s, B 1s, C 2s ...).
+   */
+  preload(): void {
+    if (this.state) return;
+    try {
+      const persisted = this.store.load(this.scope) as RateLimitState | null | Promise<RateLimitState | null>;
+      if (persisted instanceof Promise) return; // truly async store: use ensureLoaded
+      this.applyLoaded(persisted);
+    } catch (e) {
+      this.logger?.warn('rate-limit state load failed, starting fresh', { error: String(e) });
+    }
+  }
+
+  constructor(
+    options: RateLimitOptions = {},
+    private readonly logger?: KitLogger,
+    private readonly emit?: KitEventListener
+  ) {
+    this.minIntervalMs = options.minIntervalMs ?? DEFAULT_RATE_LIMIT.minIntervalMs;
+    this.jitterRatio = options.jitterRatio ?? DEFAULT_RATE_LIMIT.jitterRatio;
+    this.initialCooldownMs = options.initialCooldownMs ?? DEFAULT_RATE_LIMIT.initialCooldownMs;
+    this.maxCooldownMs = options.maxCooldownMs ?? DEFAULT_RATE_LIMIT.maxCooldownMs;
+    this.decaySuccesses = options.decaySuccesses ?? DEFAULT_RATE_LIMIT.decaySuccesses;
+    this.openThreshold = options.openThreshold ?? DEFAULT_RATE_LIMIT.openThreshold;
+    this.scope = options.scope ?? DEFAULT_RATE_LIMIT.scope;
+    this.store = options.stateStore ?? new MemoryRateLimitStateStore();
+    this.clock = options.now ?? (() => Date.now());
+    this.sleeper = options.sleep ?? defaultSleep;
+    this.random = options.random ?? Math.random;
+    // Best-effort sync warmup: with a sync store this makes the very first
+    // slot reservation synchronous too (no async-load burst at startup).
+    this.preload();
+  }
+
+  private applyLoaded(persisted: RateLimitState | null): void {
+    const now = this.clock();
+    this.state = persisted ?? freshState(now);
+    // A process restart lands in HALF_OPEN with an expired cooldown:
+    // normalise to CLOSED so the gate is usable; an OPEN with remaining
+    // cooldown stays OPEN.
+    if (this.state.circuitState === 'half_open' && this.state.cooldownUntil <= now) {
+      this.state.circuitState = 'closed';
+    }
+  }
+
+  private async ensureLoaded(): Promise<RateLimitState> {
+    if (this.state) return this.state;
+    if (!this.loaded) {
+      this.loaded = Promise.resolve(this.store.load(this.scope)).then((persisted) => {
+        if (!this.state) this.applyLoaded(persisted);
+      });
+    }
+    await this.loaded;
+    return this.state!;
+  }
+
+  private persist(): void {
+    if (!this.state) return;
+    this.state.updatedAt = this.clock();
+    try {
+      const result = this.store.save(this.scope, { ...this.state });
+      if (result instanceof Promise) result.catch((e) => this.logger?.warn('rate-limit state save failed', { error: String(e) }));
+    } catch (e) {
+      this.logger?.warn('rate-limit state save failed', { error: String(e) });
+    }
+  }
+
+  /** Test/inspection helper. */
+  async getState(): Promise<RateLimitState> {
+    return this.ensureLoaded();
+  }
+
+  /**
+   * Reserve a send slot and wait until it becomes due.
+   * Throws PixivCircuitOpenError while OPEN and the cooldown has not elapsed;
+   * when it has elapsed exactly one caller transitions to HALF_OPEN and acts
+   * as the probe; further callers fast-fail until the probe resolves.
+   */
+  async acquire(signal?: AbortSignal): Promise<{ probe: boolean }> {
+    if (signal?.aborted) throw new PixivAbortError('aborted before rate-limit slot');
+
+    // Serialize the decision + reservation; the actual sleep happens AFTER
+    // releasing the queue, so requests still overlap on the wire while send
+    // times are strictly t, t+i, t+2i ... (never a t+i burst).
+    const previous = this.reservationQueue;
+    let release: () => void = () => {};
+    this.reservationQueue = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    await previous;
+
+    let waitMs: number;
+    let probe = false;
+    try {
+      if (!this.state) await this.ensureLoaded();
+      const s = this.state!;
+      const now = this.clock();
+
+      if (s.circuitState === 'open') {
+        if (now < s.cooldownUntil) {
+          throw new PixivCircuitOpenError('Pixiv rate-limit circuit is open', {
+            retryAfterMs: s.cooldownUntil - now,
+          });
+        }
+        // Cooldown elapsed: allow exactly one probe.
+        s.circuitState = 'half_open';
+        probe = true;
+        this.emit?.({ type: 'circuit_half_open' });
+        this.persist();
+      } else if (s.circuitState === 'half_open') {
+        throw new PixivCircuitOpenError('Pixiv rate-limit circuit half-open probe in flight', {
+          retryAfterMs: Math.max(0, s.cooldownUntil - now),
+        });
+      }
+
+      const scheduledAt = Math.max(now, s.nextAllowedAt, s.cooldownUntil);
+      const jitter = this.minIntervalMs * this.jitterRatio * this.random();
+      s.nextAllowedAt = scheduledAt + this.minIntervalMs + jitter;
+      waitMs = scheduledAt - now;
+    } finally {
+      release();
+    }
+
+    if (waitMs > 0) {
+      try {
+        await this.sleeper(waitMs, signal);
+      } catch {
+        throw new PixivAbortError('aborted while waiting for rate-limit slot');
+      }
+      // Re-validate after sleeping: a 429 from a request that was IN FLIGHT
+      // while this slot was reserved may have moved cooldownUntil forward.
+      // Without this check, callers whose pacing slots were booked before the
+      // 429 arrived would fire straight through the new cooldown.
+      if (this.state) {
+        const now2 = this.clock();
+        if (this.state.circuitState === 'open' && now2 < this.state.cooldownUntil) {
+          throw new PixivCircuitOpenError('Pixiv rate-limit circuit opened while waiting for a slot', {
+            retryAfterMs: this.state.cooldownUntil - now2,
+          });
+        }
+        if (now2 < this.state.cooldownUntil) {
+          return this.acquire(signal);
+        }
+      }
+    }
+    return { probe };
+  }
+
+  /**
+   * A half-open probe failed for ANY reason (429 or transient). Reopen the
+   * circuit with a fresh cooldown rather than declaring health on one 5xx.
+   */
+  async reportProbeFailure(waitMs: number): Promise<void> {
+    const s = await this.ensureLoaded();
+    if (s.circuitState !== 'half_open') return;
+    const now = this.clock();
+    s.circuitState = 'open';
+    s.cooldownUntil = Math.max(s.cooldownUntil, now + waitMs);
+    s.nextAllowedAt = Math.max(s.nextAllowedAt, s.cooldownUntil);
+    this.emit?.({ type: 'circuit_opened', until: s.cooldownUntil });
+    this.persist();
+  }
+
+  /**
+   * Record a 429 and compute the cooldown that was applied globally.
+   * Retry-After is always respected as a floor; the exponential ladder is
+   * 60s -> 120s -> 240s -> 480s ... capped at maxCooldownMs.
+   */
+  async reportRateLimited(retryAfterHeader?: string | null): Promise<{ waitMs: number; circuitOpened: boolean }> {
+    const s = await this.ensureLoaded();
+    const now = this.clock();
+    s.penaltyLevel += 1;
+    s.consecutiveSuccesses = 0;
+    s.last429At = now;
+
+    const hintedMs = parseRetryAfter(retryAfterHeader, now);
+    const ladder = this.initialCooldownMs * 2 ** Math.max(0, s.penaltyLevel - 1);
+    const jitteredLadder = ladder * (1 + this.random() * this.jitterRatio);
+    const computed = Math.min(this.maxCooldownMs, jitteredLadder);
+    const waitMs = Math.max(hintedMs ?? 0, computed);
+
+    const wasOpen = s.circuitState === 'open';
+    s.cooldownUntil = Math.max(s.cooldownUntil, now + waitMs);
+    s.nextAllowedAt = Math.max(s.nextAllowedAt, s.cooldownUntil);
+
+    let circuitOpened = false;
+    if (s.penaltyLevel >= this.openThreshold && s.circuitState !== 'open') {
+      s.circuitState = 'open';
+      circuitOpened = true;
+    } else if (s.circuitState === 'half_open') {
+      // Probe failed: reopen.
+      s.circuitState = 'open';
+      circuitOpened = true;
+    }
+
+    this.emit?.({
+      type: 'rate_limited',
+      endpoint: '',
+      retryAfterMs: waitMs,
+      penaltyLevel: s.penaltyLevel,
+    });
+    this.emit?.({ type: 'cooldown_started', until: s.cooldownUntil, penaltyLevel: s.penaltyLevel });
+    if (circuitOpened && !wasOpen) this.emit?.({ type: 'circuit_opened', until: s.cooldownUntil });
+    this.logger?.warn('Pixiv rate limit cooldown', {
+      penaltyLevel: s.penaltyLevel,
+      waitSec: Math.round(waitMs / 1000),
+      circuitState: s.circuitState,
+    });
+    this.persist();
+    return { waitMs, circuitOpened };
+  }
+
+  /**
+   * Record a successful response. The penalty level only DECAYS after a run of
+   * consecutive successes — one lucky 200 never clears the punishment. A
+   * successful half-open probe closes the circuit and buys one decay step.
+   */
+  async reportSuccess(): Promise<void> {
+    const s = await this.ensureLoaded();
+    const wasHalfOpen = s.circuitState === 'half_open';
+    s.consecutiveSuccesses += 1;
+
+    let changed = wasHalfOpen;
+    if (wasHalfOpen) {
+      s.circuitState = 'closed';
+      s.penaltyLevel = Math.max(0, s.penaltyLevel - 1);
+      s.consecutiveSuccesses = 0;
+      this.emit?.({ type: 'circuit_closed' });
+      this.logger?.info('Pixiv rate-limit probe succeeded, circuit closed');
+    } else if (s.penaltyLevel > 0 && s.consecutiveSuccesses >= this.decaySuccesses) {
+      s.penaltyLevel -= 1;
+      s.consecutiveSuccesses = 0;
+      changed = true;
+    }
+    if (changed) this.persist();
+  }
+
+  async getStatus(): Promise<RateLimitStatus> {
+    const s = await this.ensureLoaded();
+    const now = this.clock();
+    return {
+      circuitState: s.circuitState,
+      cooldownRemainingMs: Math.max(0, s.cooldownUntil - now),
+      penaltyLevel: s.penaltyLevel,
+      last429At: s.last429At,
+      nextAllowedInMs: Math.max(0, s.nextAllowedAt - now),
+    };
+  }
+}
+
+export function parseRetryAfter(value: string | null | undefined, now: number): number | null {
+  if (!value) return null;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) return seconds * 1000;
+  const date = Date.parse(value);
+  return Number.isFinite(date) ? Math.max(0, date - now) : null;
+}

package/node_modules/@redtidev/pixiv-client/src/rate-limit/__tests__/RateLimitGate.test.ts

@@ -0,0 +1,258 @@
+import { RateLimitGate, MemoryRateLimitStateStore, DEFAULT_RATE_LIMIT } from '../RateLimitGate';
+import { PixivCircuitOpenError } from '../../errors/errors';
+import type { RateLimitState } from '../../types';
+
+/**
+ * Virtual clock with a deadline queue. `sleep(ms)` resolves when fake time
+ * reaches its deadline; `tick` jumps to each deadline in order, firing FIFO
+ * among equal deadlines, and drains microtasks after each fire so chains that
+ * register new sleeps at the same instant are resolved in registration order.
+ */
+function virtualTime(start = 1_000_000) {
+  let now = start;
+  let seq = 0;
+  const scheduled: Array<{ at: number; seq: number; resolve: () => void }> = [];
+
+  const sleep = (ms: number, signal?: AbortSignal) =>
+    new Promise<void>((resolve, reject) => {
+      const entry = { at: now + ms, seq: seq++, resolve };
+      scheduled.push(entry);
+      if (signal) {
+        if (signal.aborted) {
+          reject(Object.assign(new Error('aborted'), { name: 'AbortError' }));
+          return;
+        }
+        signal.addEventListener(
+          'abort',
+          () => {
+            const i = scheduled.indexOf(entry);
+            if (i >= 0) scheduled.splice(i, 1);
+            reject(Object.assign(new Error('aborted'), { name: 'AbortError' }));
+          },
+          { once: true }
+        );
+      }
+    });
+
+  const flushMicrotasks = async () => {
+    for (let i = 0; i < 100; i++) {
+      await Promise.resolve();
+      await new Promise((r) => setImmediate(r));
+    }
+  };
+
+  const tick = async (ms: number) => {
+    const target = now + ms;
+    // Let any synchronous-then-microtask chains (ensureLoaded, reservation
+    // queue) register their sleeps before we start jumping time.
+    await flushMicrotasks();
+    for (let safety = 0; safety < 1_000_000; safety++) {
+      const due = scheduled.filter((s) => s.at <= target);
+      if (!due.length) break;
+      due.sort((a, b) => (a.at - b.at) || (a.seq - b.seq));
+      const next = due[0];
+      scheduled.splice(scheduled.indexOf(next), 1);
+      now = next.at;
+      next.resolve();
+      // Drain continuation microtasks before picking the next deadline; a
+      // continuation may register a new sleep at this exact timestamp with a
+      // later seq, preserving FIFO spacing (1001 then 1001-registered sleep).
+      for (let i = 0; i < 5; i++) await Promise.resolve();
+    }
+    now = target;
+  };
+
+  return {
+    now: () => now,
+    sleep,
+    tick,
+    advanceOnly: (ms: number) => {
+      now += ms;
+    },
+  };
+}
+
+function gate(opts: ConstructorParameters<typeof RateLimitGate>[0] = {}) {
+  const t = virtualTime();
+  const g = new RateLimitGate(
+    {
+      minIntervalMs: opts.minIntervalMs ?? 1000,
+      jitterRatio: 0,
+      initialCooldownMs: opts.initialCooldownMs ?? 60_000,
+      maxCooldownMs: opts.maxCooldownMs ?? 900_000,
+      decaySuccesses: opts.decaySuccesses ?? 20,
+      openThreshold: opts.openThreshold ?? 4,
+      stateStore: opts.stateStore,
+      scope: opts.scope,
+      now: t.now,
+      sleep: t.sleep,
+      random: () => 0,
+    }
+  );
+  return { g, t };
+}
+
+describe('RateLimitGate pacing', () => {
+  it('defaults to conservative pacing (1000ms, jitter, 60s cooldown)', () => {
+    expect(DEFAULT_RATE_LIMIT.minIntervalMs).toBe(1000);
+    expect(DEFAULT_RATE_LIMIT.initialCooldownMs).toBe(60_000);
+    expect(DEFAULT_RATE_LIMIT.jitterRatio).toBeGreaterThan(0);
+  });
+
+  it('serializes concurrent callers with slot reservation (no burst)', async () => {
+    const { g, t } = gate();
+    const slots: number[] = [];
+    const grab = async () => {
+      await g.acquire();
+      slots.push(t.now());
+    };
+    // Fire 4 concurrent acquisitions; each reserves its slot synchronously.
+    const waits = [grab(), grab(), grab(), grab()];
+    await t.tick(5000);
+    await Promise.all(waits);
+    expect(slots).toEqual([1_000_000, 1_001_000, 1_002_000, 1_003_000]);
+  });
+
+  it('adds jitter to pacing when configured', async () => {
+    const t = virtualTime();
+    const g = new RateLimitGate({ minIntervalMs: 1000, jitterRatio: 0.5, now: t.now, sleep: t.sleep, random: () => 0.5 });
+    const p1 = g.acquire();
+    const p2 = g.acquire();
+    await t.tick(2000);
+    await Promise.all([p1, p2]);
+    const state = await g.getState();
+    // Each reservation advances by interval + jitter (1000 + 250 = 1250);
+    // two reservations -> cursor at start + 2500.
+    expect(state.nextAllowedAt).toBe(1_000_000 + 2500);
+  });
+});
+
+describe('RateLimitGate 429 handling', () => {
+  it('honors Retry-After as a floor', async () => {
+    const { g } = gate();
+    const { waitMs } = await g.reportRateLimited('30');
+    // floor ladder 60s beats the 30s hint
+    expect(waitMs).toBe(60_000);
+    const { waitMs: wait2 } = await g.reportRateLimited('999');
+    expect(wait2).toBe(999_000);
+  });
+
+  it('escalates 60 -> 120 -> 240 -> 480 and caps at maxCooldown', async () => {
+    const { g } = gate({ maxCooldownMs: 300_000 });
+    expect((await g.reportRateLimited(null)).waitMs).toBe(60_000);
+    expect((await g.reportRateLimited(null)).waitMs).toBe(120_000);
+    expect((await g.reportRateLimited(null)).waitMs).toBe(240_000);
+    expect((await g.reportRateLimited(null)).waitMs).toBe(300_000); // capped
+  });
+
+  it('parks the whole client: a second request waits at the gate during cooldown', async () => {
+    const { g, t } = gate();
+    await g.reportRateLimited('60');
+    const p = g.acquire();
+    let resolved = false;
+    p.then(() => (resolved = true));
+    await t.tick(30_000);
+    await Promise.resolve();
+    expect(resolved).toBe(false);
+    await t.tick(40_000);
+    await expect(p).resolves.toBeDefined();
+    expect(resolved).toBe(true);
+  });
+
+  it('does not reset penalty after one success (decay needs a run of successes)', async () => {
+    const { g } = gate({ decaySuccesses: 5 });
+    await g.reportRateLimited(null);
+    await g.reportRateLimited(null);
+    const before = (await g.getStatus()).penaltyLevel;
+    await g.reportSuccess();
+    expect((await g.getStatus()).penaltyLevel).toBe(before);
+    for (let i = 0; i < 4; i++) await g.reportSuccess();
+    expect((await g.getStatus()).penaltyLevel).toBe(before - 1);
+  });
+});
+
+describe('RateLimitGate circuit breaker', () => {
+  it('opens at the threshold, fast-fails, then allows one half-open probe', async () => {
+    const { g, t } = gate({ openThreshold: 3 });
+    await g.reportRateLimited(null);
+    await g.reportRateLimited(null);
+    const { circuitOpened } = await g.reportRateLimited(null);
+    expect(circuitOpened).toBe(true);
+    expect((await g.getStatus()).circuitState).toBe('open');
+
+    // While cooldown is active, requests fail immediately (no thundering herd).
+    await expect(g.acquire()).rejects.toBeInstanceOf(PixivCircuitOpenError);
+
+    // Elapse cooldown: one caller becomes the probe...
+    t.advanceOnly(600_000);
+    const probe = await g.acquire();
+    expect(probe.probe).toBe(true);
+    expect((await g.getStatus()).circuitState).toBe('half_open');
+    // ...others are rejected while the probe is in flight.
+    await expect(g.acquire()).rejects.toBeInstanceOf(PixivCircuitOpenError);
+
+    // Probe succeeds -> closed.
+    await g.reportSuccess();
+    expect((await g.getStatus()).circuitState).toBe('closed');
+  });
+
+  it('reopens when the half-open probe fails', async () => {
+    const { g, t } = gate({ openThreshold: 1 });
+    await g.reportRateLimited(null);
+    t.advanceOnly(600_000);
+    await g.acquire(); // half-open probe
+    await g.reportProbeFailure(60_000);
+    expect((await g.getStatus()).circuitState).toBe('open');
+  });
+});
+
+describe('RateLimitGate persistence', () => {
+  it('persists state on 429 and restores the cooldown into a new gate', async () => {
+    const store = new MemoryRateLimitStateStore();
+    const { g, t } = gate({ stateStore: store, scope: 'acct-1' });
+    await g.reportRateLimited('60');
+    t.advanceOnly(5_000);
+
+    // New process, same store/scope: cooldown is remembered.
+    const t2 = virtualTime(t.now());
+    const g2 = new RateLimitGate({
+      stateStore: store,
+      scope: 'acct-1',
+      now: t2.now,
+      sleep: t2.sleep,
+      jitterRatio: 0,
+      random: () => 0,
+    });
+    const status = await g2.getStatus();
+    expect(status.cooldownRemainingMs).toBe(55_000);
+    expect(status.penaltyLevel).toBe(1);
+    // ...and acquiring after the cooldown elapses works (restart-safe).
+    t2.advanceOnly(55_000);
+    await expect(g2.acquire()).resolves.toEqual({ probe: false });
+  });
+
+  it('surfaces the persisted state shape for SQLite adapters', async () => {
+    const store = new MemoryRateLimitStateStore();
+    const { g } = gate({ stateStore: store });
+    await g.reportRateLimited(null);
+    const saved: RateLimitState | null = await store.load('default');
+    expect(saved).toMatchObject({
+      penaltyLevel: 1,
+      last429At: expect.any(Number),
+      circuitState: 'closed',
+    });
+  });
+});
+
+describe('RateLimitGate abort', () => {
+  it('rejects an aborted wait with an abort error', async () => {
+    const { g, t } = gate();
+    // consume the first immediate slot
+    void g.acquire();
+    const controller = new AbortController();
+    const p = g.acquire(controller.signal);
+    controller.abort();
+    await expect(p).rejects.toMatchObject({ name: 'PixivAbortError' });
+    void t;
+  });
+});