hikoutei 0.10.1-dev → 0.10.3-dev

package/dist/sheets/providers/google-sheets-api/transport/quotaGovernor.js

@@ -1,299 +0,0 @@
-/**
- * Adaptive quota governor layered ON TOP of the request-start limiters.
- *
- * The interval limiters (`RequestStartLimiter`, `ReadQoSScheduler`) space
- * request STARTS but have no notion of the per-minute quota budget, and a
- * remote 429 never feeds back into their pacing. This module adds the two
- * missing pieces, both of which gate request STARTS only and never touch
- * CAS/fencing, prepared-state, batch building, or result encoding:
- *
- * 1. `RollingQuotaBudget` — a sliding-window per-minute TOTAL request-start
- *    budget per lane (reads vs writes). It composes with (does not replace)
- *    the interval limiters: a start must pass BOTH the budget and its lane's
- *    interval pacing. Admission is BOUNDED with the same semantics as the
- *    interval limiters: a refused caller reserves nothing, so a refusal can
- *    never advance the budget window or the pacing horizon.
- *
- * 2. `QuotaPacingGovernor` — AIMD pacing feedback. When a transport response
- *    is classified as quota-limited (HTTP 429 / `RESOURCE_EXHAUSTED`), the
- *    offending lane's pacing interval doubles (multiplicative decrease,
- *    capped at a multiple of the base). After a sustained quiet period
- *    (enough successful request starts, or enough elapsed time since the
- *    last quota event), the interval steps back down ~10% at a time
- *    (additive increase) and never falls below the base. With no 429 ever
- *    observed the governor stays `nominal` at 1x and pacing is byte-for-byte
- *    the pre-governor behavior.
- *
- * Why a per-minute budget at all: the binding Google quota for our
- * deployment is the per-user READ rate (60/min); a measured 30k-effect
- * burst peaked near 69/min of reads, producing 429s and a delivery-uncertain
- * requeue spiral. The interval pacing alone (75/min at the 800 ms default)
- * cannot hold a per-minute ceiling because concurrent lock-free readers each
- * reserve successive interval slots without any rate cap per window.
- */
-import { GOOGLE_SHEETS_API_DEFAULTS } from "../../../../contracts/sheets/googleSheetsApi.js";
-import { PRESENCE_KINDS } from "../../../../contracts/state/index.js";
-import { RATE_LIMIT_OPTIONS_ERROR_CODES, RateLimitOptionsError, } from "./rateLimiter.js";
-/** Lanes the governor paces: the shared read timeline and the write lane. */
-export const QUOTA_GOVERNOR_LANES = {
-    READ: "read",
-    WRITE: "write",
-};
-/** Lifecycle states of one lane's AIMD pacing. */
-export const QUOTA_PACING_STATES = {
-    NOMINAL: "nominal",
-    BACKOFF: "backoff",
-    RECOVERY: "recovery",
-};
-/**
- * AIMD pacing feedback for the two request-start lanes.
- *
- * `intervalMsFor(lane)` is polled by the lane's limiter at each reservation,
- * so a doubled multiplier doubles the effective spacing on the NEXT start
- * without reconstructing the limiter. `recordRequestStart` and
- * `recordQuotaLimited` are the only state inputs; both are fire-and-forget
- * bookkeeping that can never throw out of the admission path.
- */
-export class QuotaPacingGovernor {
-    baseIntervalMs;
-    now;
-    lanes;
-    constructor(options) {
-        this.baseIntervalMs = options.baseIntervalMs;
-        this.now = options.now ?? Date.now;
-        this.lanes = {
-            [QUOTA_GOVERNOR_LANES.READ]: {
-                multiplier: 1,
-                lastQuotaEventAt: 0,
-                quietStarts: 0,
-                steppedDown: false,
-            },
-            [QUOTA_GOVERNOR_LANES.WRITE]: {
-                multiplier: 1,
-                lastQuotaEventAt: 0,
-                quietStarts: 0,
-                steppedDown: false,
-            },
-        };
-    }
-    /** Effective pacing interval for one lane: base x AIMD multiplier. */
-    intervalMsFor(lane) {
-        // Lazy time-based recovery: a lane with zero traffic never reaches
-        // recordRequestStart, so the quiet window is also advanced wherever the
-        // interval is OBSERVED (the lane reservation path polls this).
-        this.recoverByElapsed(lane);
-        const multiplier = this.lanes[lane].multiplier;
-        return multiplier === 1
-            ? this.baseIntervalMs
-            : Math.round(this.baseIntervalMs * multiplier);
-    }
-    /**
-     * Multiplicative decrease: one quota-limited (429) response doubles this
-     * lane's multiplier, capped at `QUOTA_BACKOFF_MAX_MULTIPLIER` of base.
-     */
-    recordQuotaLimited(lane) {
-        const state = this.lanes[lane];
-        state.multiplier = Math.min(state.multiplier * GOOGLE_SHEETS_API_DEFAULTS.QUOTA_BACKOFF_GROWTH_FACTOR, GOOGLE_SHEETS_API_DEFAULTS.QUOTA_BACKOFF_MAX_MULTIPLIER);
-        state.lastQuotaEventAt = this.now();
-        state.quietStarts = 0;
-        state.steppedDown = false;
-    }
-    /**
-     * Additive increase: one successful request start on this lane. After a
-     * sustained quiet period (RECOVERY_SUCCESS_THRESHOLD starts, or
-     * RECOVERY_QUIET_MS elapsed since the last quota event) the multiplier
-     * steps down by ~10% and needs a FRESH quiet period before the next step,
-     * so recovery is gradual and a single 429 cannot be answered with a
-     * immediate undo. Landing on exactly 1x returns the lane to `nominal`.
-     */
-    recordRequestStart(lane) {
-        const state = this.lanes[lane];
-        if (state.multiplier === 1)
-            return;
-        state.quietStarts += 1;
-        const quietElapsed = this.now() - state.lastQuotaEventAt;
-        if (state.quietStarts < GOOGLE_SHEETS_API_DEFAULTS.QUOTA_RECOVERY_SUCCESS_THRESHOLD &&
-            quietElapsed < GOOGLE_SHEETS_API_DEFAULTS.QUOTA_RECOVERY_QUIET_MS) {
-            return;
-        }
-        this.stepDown(state);
-    }
-    /**
-     * Elapsed-time-only quiet recovery, applied lazily at every state
-     * observation: with no traffic on the lane, `recordRequestStart` never
-     * runs, so a backed-off lane would otherwise stay in backoff forever.
-     */
-    recoverByElapsed(lane) {
-        const state = this.lanes[lane];
-        if (state.multiplier === 1)
-            return;
-        if (this.now() - state.lastQuotaEventAt >=
-            GOOGLE_SHEETS_API_DEFAULTS.QUOTA_RECOVERY_QUIET_MS) {
-            this.stepDown(state);
-        }
-    }
-    /** One additive-increase step: ~10% down, clamped at nominal (1x). */
-    stepDown(state) {
-        state.multiplier = Math.max(state.multiplier / GOOGLE_SHEETS_API_DEFAULTS.QUOTA_RECOVERY_STEP_FACTOR, 1);
-        state.lastQuotaEventAt = this.now();
-        state.quietStarts = 0;
-        state.steppedDown = state.multiplier > 1;
-    }
-    /** Read-only snapshot of one lane's pacing state (for telemetry/tests). */
-    stateFor(lane) {
-        this.recoverByElapsed(lane);
-        const state = this.lanes[lane];
-        if (state.multiplier <= 1 && !state.steppedDown) {
-            return { status: QUOTA_PACING_STATES.NOMINAL, multiplier: 1 };
-        }
-        return {
-            status: state.steppedDown
-                ? QUOTA_PACING_STATES.RECOVERY
-                : QUOTA_PACING_STATES.BACKOFF,
-            multiplier: state.multiplier,
-            lastQuotaEventAt: state.lastQuotaEventAt,
-            quietStarts: state.quietStarts,
-        };
-    }
-}
-/**
- * Returns true when a classified transport outcome proves the request was
- * quota-limited remotely (HTTP 429 or the allowlisted `RESOURCE_EXHAUSTED`
- * google.rpc code; either marker alone is sufficient because a proxy-emitted
- * 429 can carry no body and a body can omit the status line evidence).
- */
-export function isQuotaLimitedOutcome(outcome) {
-    const byStatus = outcome.httpStatus.kind === PRESENCE_KINDS.PRESENT &&
-        outcome.httpStatus.value === GOOGLE_SHEETS_API_DEFAULTS.QUOTA_LIMIT_HTTP_STATUS;
-    const byCode = outcome.code.kind === PRESENCE_KINDS.PRESENT &&
-        outcome.code.value === GOOGLE_SHEETS_API_DEFAULTS.QUOTA_LIMIT_REMOTE_CODE;
-    return byStatus || byCode;
-}
-const DEFAULT_SLEEP = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-/**
- * Sliding-window per-minute request-start budget for ONE lane.
- *
- * Reservations, not completed requests, occupy the window: an admitted
- * caller records the slot it will start at, so a burst of concurrent
- * callers arriving in the same tick each consumes one of the remaining
- * budget slots and the deep ones are refused by the bounded wait, exactly
- * like the interval limiters. A budget refusal records NOTHING, so the
- * window can never be poisoned forward by refused callers.
- *
- * A budget ADMISSION reserves provisionally: a caller that later has to
- * refuse on a downstream gate (e.g. the pacing lane) hands the reservation
- * token to `rollback`, which removes exactly that entry. Rollback never
- * advances (or otherwise touches) the window and can never free a live
- * reservation belonging to another caller.
- *
- * The earliest legal start when the window already holds `max` reservations
- * is `starts[n - max] + windowMs`: at that instant all but the `max - 1`
- * newest reservations have aged out, so admitting keeps the count at `max`.
- */
-export class RollingQuotaBudget {
-    maxStartsPerWindow;
-    windowMs;
-    now;
-    sleep;
-    /**
-     * Reserved start times, kept in chronological (non-decreasing `reservedAt`)
-     * order at all times. Rollback splices its own entry out (order survives)
-     * and every new reservation is inserted at its sorted position rather than
-     * blindly appended: a rolled-back older slot must never let a later caller
-     * land BEHIND a queued future reservation, or the prefix expiry scan would
-     * stop at the future entry and retain the trailing expired one forever,
-     * leaking budget capacity.
-     */
-    starts = [];
-    constructor(options) {
-        const validRate = options.maxStartsPerWindow === Number.POSITIVE_INFINITY ||
-            (Number.isSafeInteger(options.maxStartsPerWindow) && options.maxStartsPerWindow > 0);
-        if (!validRate) {
-            throw new RateLimitOptionsError(RATE_LIMIT_OPTIONS_ERROR_CODES.BUDGET_POSITIVE_INTEGER_REQUIRED);
-        }
-        if (!Number.isSafeInteger(options.windowMs) || options.windowMs <= 0) {
-            throw new RateLimitOptionsError(RATE_LIMIT_OPTIONS_ERROR_CODES.BUDGET_POSITIVE_INTEGER_REQUIRED);
-        }
-        this.maxStartsPerWindow = options.maxStartsPerWindow;
-        this.windowMs = options.windowMs;
-        this.now = options.now ?? Date.now;
-        this.sleep = options.sleep ?? DEFAULT_SLEEP;
-    }
-    /** Number of reservations (admitted, possibly still sleeping) in window. */
-    reservedCount() {
-        return this.starts.length;
-    }
-    /**
-     * Bounded admission to one budget slot: waits only when the predicted
-     * slot is at most `maxWaitMs` out, otherwise returns `refused` having
-     * reserved nothing. The decision and the reservation happen synchronously
-     * before any await, so concurrent callers can never double-book one slot.
-     */
-    async waitForSlot(maxWaitMs) {
-        if (!Number.isSafeInteger(maxWaitMs) || maxWaitMs < 0) {
-            throw new RateLimitOptionsError(RATE_LIMIT_OPTIONS_ERROR_CODES.MAX_WAIT_NON_NEGATIVE_REQUIRED);
-        }
-        const now = this.now();
-        // Age out every reservation that has left the trailing window.
-        const cutoff = now - this.windowMs;
-        let firstLive = 0;
-        for (;;) {
-            const candidate = this.starts[firstLive];
-            if (candidate === undefined || candidate.reservedAt > cutoff)
-                break;
-            firstLive += 1;
-        }
-        if (firstLive > 0) {
-            this.starts = this.starts.slice(firstLive);
-        }
-        let nextStart = now;
-        if (this.starts.length >= this.maxStartsPerWindow) {
-            // Window holds its full budget: the earliest legal start is the moment
-            // the OLDEST still-counted reservation ages out of the trailing window.
-            // The index is in range (length >= max >= 1); the fallback arm only
-            // answers `noUncheckedIndexedAccess` and is unreachable.
-            const anchor = this.starts[this.starts.length - this.maxStartsPerWindow];
-            nextStart = Math.max(now, (anchor?.reservedAt ?? now) + this.windowMs);
-        }
-        const waited = Math.max(0, nextStart - now);
-        if (waited > maxWaitMs) {
-            // Refused WITHOUT reserving: the window keeps only admitted slots.
-            return { status: "refused", waitedMs: waited, nextStartAt: nextStart };
-        }
-        const reservation = { reservedAt: nextStart };
-        this.insertReservation(reservation);
-        if (waited > 0) {
-            await this.sleep(waited);
-        }
-        return { status: "admitted", waitedMs: waited, reservation };
-    }
-    /**
-     * Inserts one reservation keeping {@link starts} chronologically ordered.
-     * The common case (slot at or after every existing entry) is a plain push;
-     * only an out-of-order arrival after a rollback walks back from the tail,
-     * which is bounded by the window budget (a few hundred entries per minute).
-     */
-    insertReservation(reservation) {
-        let index = this.starts.length;
-        while (index > 0 && this.starts[index - 1].reservedAt > reservation.reservedAt) {
-            index -= 1;
-        }
-        this.starts.splice(index, 0, reservation);
-    }
-    /**
-     * Rolls back one PROVISIONAL budget reservation returned by `waitForSlot`
-     * whose caller never reached request start (e.g. a downstream pacing-lane
-     * refusal). Invariants: the removal is matched by object identity, so it
-     * can never release a different live reservation; a token that was already
-     * rolled back or aged out of the window is a no-op (no double release);
-     * rollback never advances the window (remaining reservations and their
-     * timestamps are untouched).
-     */
-    rollback(reservation) {
-        const index = this.starts.indexOf(reservation);
-        if (index !== -1) {
-            this.starts.splice(index, 1);
-        }
-    }
-}
-//# sourceMappingURL=quotaGovernor.js.map

package/dist/sheets/providers/google-sheets-api/transport/quotaGovernor.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"quotaGovernor.js","sourceRoot":"","sources":["../../../../../../../../src/sheets/providers/google-sheets-api/transport/quotaGovernor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,0BAA0B,EAAE,MAAM,+CAA+C,CAAC;AAC3F,OAAO,EAAE,cAAc,EAAiB,MAAM,oCAAoC,CAAC;AACnF,OAAO,EACL,8BAA8B,EAC9B,qBAAqB,GAAG,MAAM,kBAAkB,CAAC;AAEnD,6EAA6E;AAC7E,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,OAAO;CACN,CAAC;AAMX,kDAAkD;AAClD,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,QAAQ,EAAE,UAAU;CACZ,CAAC;AA4CX;;;;;;;;GAQG;AACH,MAAM,OAAO,mBAAmB;IACb,cAAc,CAAS;IACvB,GAAG,CAAe;IAClB,KAAK,CAAuC;IAE7D,YAAmB,OAAmC;QACpD,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;QAC7C,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;QACnC,IAAI,CAAC,KAAK,GAAG;YACX,CAAC,oBAAoB,CAAC,IAAI,CAAC,EAAE;gBAC3B,UAAU,EAAE,CAAC;gBACb,gBAAgB,EAAE,CAAC;gBACnB,WAAW,EAAE,CAAC;gBACd,WAAW,EAAE,KAAK;aACnB;YACD,CAAC,oBAAoB,CAAC,KAAK,CAAC,EAAE;gBAC5B,UAAU,EAAE,CAAC;gBACb,gBAAgB,EAAE,CAAC;gBACnB,WAAW,EAAE,CAAC;gBACd,WAAW,EAAE,KAAK;aACnB;SACF,CAAC;IACJ,CAAC;IAED,sEAAsE;IAC/D,aAAa,CAAC,IAAuB;QAC1C,mEAAmE;QACnE,wEAAwE;QACxE,+DAA+D;QAC/D,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;QAC5B,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC;QAC/C,OAAO,UAAU,KAAK,CAAC;YACrB,CAAC,CAAC,IAAI,CAAC,cAAc;YACrB,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,cAAc,GAAG,UAAU,CAAC,CAAC;IACnD,CAAC;IAED;;;OAGG;IACI,kBAAkB,CAAC,IAAuB;QAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC/B,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,CACzB,KAAK,CAAC,UAAU,GAAG,0BAA0B,CAAC,2BAA2B,EACzE,0BAA0B,CAAC,4BAA4B,CACxD,CAAC;QACF,KAAK,CAAC,gBAAgB,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACpC,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC;QACtB,KAAK,CAAC,WAAW,GAAG,KAAK,CAAC;IAC5B,CAAC;IAED;;;;;;;OAOG;IACI,kBAAkB,CAAC,IAAuB;QAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,KAAK,CAAC,UAAU,KAAK,CAAC;YAAE,OAAO;QACnC,KAAK,CAAC,WAAW,IAAI,CAAC,CAAC;QACvB,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,gBAAgB,CAAC;QACzD,IACE,KAAK,CAAC,WAAW,GAAG,0BAA0B,CAAC,gCAAgC;YAC/E,YAAY,GAAG,0BAA0B,CAAC,uBAAuB,EACjE,CAAC;YACD,OAAO;QACT,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACK,gBAAgB,CAAC,IAAuB;QAC9C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,KAAK,CAAC,UAAU,KAAK,CAAC;YAAE,OAAO;QACnC,IACE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,gBAAgB;YACnC,0BAA0B,CAAC,uBAAuB,EAClD,CAAC;YACD,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,sEAAsE;IAC9D,QAAQ,CAAC,KAAgB;QAC/B,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,CACzB,KAAK,CAAC,UAAU,GAAG,0BAA0B,CAAC,0BAA0B,EACxE,CAAC,CACF,CAAC;QACF,KAAK,CAAC,gBAAgB,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACpC,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC;QACtB,KAAK,CAAC,WAAW,GAAG,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC;IAC3C,CAAC;IAED,2EAA2E;IACpE,QAAQ,CAAC,IAAuB;QACrC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;QAC5B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,KAAK,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;YAChD,OAAO,EAAE,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC;QAChE,CAAC;QACD,OAAO;YACL,MAAM,EAAE,KAAK,CAAC,WAAW;gBACvB,CAAC,CAAC,mBAAmB,CAAC,QAAQ;gBAC9B,CAAC,CAAC,mBAAmB,CAAC,OAAO;YAC/B,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;YACxC,WAAW,EAAE,KAAK,CAAC,WAAW;SAC/B,CAAC;IACJ,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAGrC;IACC,MAAM,QAAQ,GACZ,OAAO,CAAC,UAAU,CAAC,IAAI,KAAK,cAAc,CAAC,OAAO;QAClD,OAAO,CAAC,UAAU,CAAC,KAAK,KAAK,0BAA0B,CAAC,uBAAuB,CAAC;IAClF,MAAM,MAAM,GACV,OAAO,CAAC,IAAI,CAAC,IAAI,KAAK,cAAc,CAAC,OAAO;QAC5C,OAAO,CAAC,IAAI,CAAC,KAAK,KAAK,0BAA0B,CAAC,uBAAuB,CAAC;IAC5E,OAAO,QAAQ,IAAI,MAAM,CAAC;AAC5B,CAAC;AAiBD,MAAM,aAAa,GAAG,CAAC,EAAU,EAAiB,EAAE,CAClD,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAoB1D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,kBAAkB;IACZ,kBAAkB,CAAS;IAC3B,QAAQ,CAAS;IACjB,GAAG,CAAe;IAClB,KAAK,CAAgC;IACtD;;;;;;;;OAQG;IACK,MAAM,GAAwB,EAAE,CAAC;IAEzC,YAAmB,OAAkC;QACnD,MAAM,SAAS,GACb,OAAO,CAAC,kBAAkB,KAAK,MAAM,CAAC,iBAAiB;YACvD,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,kBAAkB,CAAC,IAAI,OAAO,CAAC,kBAAkB,GAAG,CAAC,CAAC,CAAC;QACvF,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,qBAAqB,CAC7B,8BAA8B,CAAC,gCAAgC,CAChE,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,QAAQ,IAAI,CAAC,EAAE,CAAC;YACrE,MAAM,IAAI,qBAAqB,CAC7B,8BAA8B,CAAC,gCAAgC,CAChE,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC;QACrD,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;QACnC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,aAAa,CAAC;IAC9C,CAAC;IAED,4EAA4E;IACrE,aAAa;QAClB,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;IAC5B,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,WAAW,CAAC,SAAiB;QACxC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;YACtD,MAAM,IAAI,qBAAqB,CAC7B,8BAA8B,CAAC,8BAA8B,CAC9D,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,+DAA+D;QAC/D,MAAM,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC;QACnC,IAAI,SAAS,GAAG,CAAC,CAAC;QAClB,SAAS,CAAC;YACR,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YACzC,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,UAAU,GAAG,MAAM;gBAAE,MAAM;YACpE,SAAS,IAAI,CAAC,CAAC;QACjB,CAAC;QACD,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;YAClB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAC7C,CAAC;QACD,IAAI,SAAS,GAAG,GAAG,CAAC;QACpB,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAClD,uEAAuE;YACvE,wEAAwE;YACxE,oEAAoE;YACpE,yDAAyD;YACzD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,kBAAkB,CAAC,CAAC;YACzE,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,UAAU,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzE,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,GAAG,GAAG,CAAC,CAAC;QAC5C,IAAI,MAAM,GAAG,SAAS,EAAE,CAAC;YACvB,mEAAmE;YACnE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC;QACzE,CAAC;QACD,MAAM,WAAW,GAAsB,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC;QACjE,IAAI,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;QACpC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;YACf,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC3B,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IAC/D,CAAC;IAED;;;;;OAKG;IACK,iBAAiB,CAAC,WAA8B;QACtD,IAAI,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;QAC/B,OAAO,KAAK,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,CAAE,CAAC,UAAU,GAAG,WAAW,CAAC,UAAU,EAAE,CAAC;YAChF,KAAK,IAAI,CAAC,CAAC;QACb,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,WAAW,CAAC,CAAC;IAC5C,CAAC;IAED;;;;;;;;OAQG;IACI,QAAQ,CAAC,WAA8B;QAC5C,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAC/C,IAAI,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC;YACjB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;CACF"}

package/dist/sheets/providers/google-sheets-api/transport/rateLimiter.d.ts

@@ -1,185 +0,0 @@
-/**
- * Request-start interval limiter used by the direct Sheets provider.
- *
- * Google Sheets quota windows are per 100 seconds, so bursty request starts
- * can exhaust the budget before the worker's own latency/backoff reacts.
- * The provider keeps TWO independent limiters — one for reads and one for
- * writes — so reads serialize only against reads and writes only against
- * writes: at most one read (getSpreadsheet) or one write (batchUpdate) can
- * start per interval of its own class, while a read and a write may start
- * concurrently. An idle provider is never throttled; the limiter only
- * waits the time remaining since the previous request START. Admission is
- * BOUNDED: a caller whose slot lies more than `maxWaitMs` out is refused
- * without reserving anything, so a burst of concurrent callers can never
- * queue an arbitrarily long line of future reservations.
- */
-/** Persistent error codes for rate-limiter option validation. */
-export declare const RATE_LIMIT_OPTIONS_ERROR_CODES: {
-    readonly INTERVAL_NON_NEGATIVE_REQUIRED: "rate_limiter_interval_non_negative_required";
-    readonly MAX_WAIT_NON_NEGATIVE_REQUIRED: "rate_limiter_max_wait_non_negative_required";
-    readonly BUDGET_POSITIVE_INTEGER_REQUIRED: "rate_limiter_budget_positive_integer_required";
-};
-/** Union type derived from the rate-limit error code table. */
-export type RateLimitOptionErrorCode = (typeof RATE_LIMIT_OPTIONS_ERROR_CODES)[keyof typeof RATE_LIMIT_OPTIONS_ERROR_CODES];
-/** Error thrown when rate-limiter options violate non-negative integer constraints. */
-export declare class RateLimitOptionsError extends RangeError {
-    readonly code: RateLimitOptionErrorCode;
-    constructor(code: RateLimitOptionErrorCode);
-}
-export interface RequestStartLimiterOptions {
-    /** Minimum interval between two request starts of this limiter class. */
-    readonly intervalMs: number;
-    /**
-     * Optional live interval source consulted at EVERY reservation (the
-     * quota-pacing governor). When present, its value paces this limiter
-     * instead of the fixed `intervalMs`, so an AIMD multiplier takes effect on
-     * the next start without reconstructing the limiter. Defaults to the fixed
-     * `intervalMs` (governor disabled or at 1x: zero behavior change).
-     */
-    readonly getIntervalMs?: () => number;
-    /** Injectable clock for deterministic tests; defaults to Date.now. */
-    readonly now?: () => number;
-    /** Injectable sleep used while waiting for the next slot. */
-    readonly sleep?: (ms: number) => Promise<void>;
-}
-/**
- * Result of one BOUNDED `waitForSlot(maxWaitMs)` admission attempt.
- *
- * An admitted caller owns the reserved slot and waits `waitedMs`; a refused
- * caller reserved NOTHING (the future slot stays available to later callers)
- * and the limiter's `lastStartAt` is left untouched, so a refusal can never
- * push the pacing horizon forward.
- */
-export type RequestStartAdmission = {
-    readonly status: "admitted";
-    readonly waitedMs: number;
-} | {
-    readonly status: "refused";
-    /** The wait the refused slot WOULD have required. */
-    readonly waitedMs: number;
-    /** The slot that was NOT reserved; still open to later callers. */
-    readonly nextStartAt: number;
-};
-/**
- * Waits only the remaining interval since the previous request start.
- *
- * Returns the number of milliseconds actually waited. A limiter with a zero
- * interval never waits and records every start.
- */
-export declare class RequestStartLimiter {
-    private readonly intervalMs;
-    private readonly getIntervalMs;
-    private readonly now;
-    private readonly sleep;
-    private lastStartAt;
-    constructor(options: RequestStartLimiterOptions);
-    /** Effective pacing interval NOW: governor-multiplied when wired. */
-    private currentIntervalMs;
-    /** Returns the last recorded request start, when one exists. */
-    lastStart(): number | undefined;
-    /**
-     * Waits for the next request-start slot and records the start time.
-     *
-     * Returns the number of milliseconds actually waited. A limiter with a zero
-     * interval never waits and records every start.
-     *
-     * The slot reservation happens SYNCHRONOUSLY before any await: each caller
-     * reserves the NEXT slot (`nextStart = max(now, lastStartAt + intervalMs)`)
-     * and records it immediately, so two concurrent waiters can never compute
-     * the same remaining time from the same `lastStartAt`, sleep together, and
-     * start at the same instant. A caller that arrives after its reserved slot
-     * has already passed waits zero (its reservation collapses to now).
-     */
-    waitForSlot(): Promise<number>;
-    /**
-     * Bounded admission: waits for the next slot only when the predicted wait
-     * is at most `maxWaitMs`, otherwise returns a REFUSED result without
-     * reserving or advancing the future slot.
-     *
-     * The bound keeps an unbounded queue of concurrent callers from each
-     * reserving a distant future slot: with `maxWaitMs` equal to `intervalMs`
-     * the immediate caller and the one exactly one interval out are admitted
-     * and every later reservation is refused up front. A refusal never records
-     * a start, so the pacing horizon is unchanged and a later caller can still
-     * be admitted once time advances past the reserved slot.
-     */
-    waitForSlot(maxWaitMs: number): Promise<RequestStartAdmission>;
-}
-/** Read QoS classes sharing ONE request-start timeline inside the scheduler. */
-export type ReadQoSClass = "polling" | "preflight";
-/**
- * Internal read request-start scheduler with weighted read-class fairness.
- *
- * All read starts (polling values/observation/safety reads AND outbound
- * preflight reads) share ONE pacing timeline and interval. When BOTH classes
- * have queued work the scheduler applies the weighted fairness policy
- * `polling 2:1 preflight` — two polling starts, then one preflight start —
- * with FIFO inside each class and no preflight starvation (a preflight is
- * served at least every three picks while both queues are non-empty, and an
- * idle class never blocks the other). The separate WRITE lane stays on the
- * plain `RequestStartLimiter`, so reads and writes still pace independently.
- *
- * Bounded admission matches the single-class limiter: a caller whose
- * predicted slot lies more than `maxWaitMs` out is refused WITHOUT reserving
- * anything, and a refusal never advances the shared horizon (so a later
- * caller is still admitted once time passes the open slot). Queued waiters
- * are served in weighted-FIFO batches and every waiter is either admitted or
- * refused before transport, so a burst of concurrent callers can never pile
- * up an arbitrarily long reservation line.
- */
-export declare class ReadQoSScheduler {
-    private readonly intervalMs;
-    private readonly getIntervalMs;
-    private readonly now;
-    private readonly sleep;
-    /** Shared request-start horizon for BOTH read classes. */
-    private lastStartAt;
-    /** Consecutive polling picks since the last preflight pick (fairness state). */
-    private pollingSincePreflight;
-    /** True while the single admission-loop coroutine is running. */
-    private draining;
-    private readonly pollingQueue;
-    private readonly preflightQueue;
-    constructor(options: RequestStartLimiterOptions);
-    /** Effective shared-read pacing interval NOW (governor-aware). */
-    private currentIntervalMs;
-    /** Returns the last recorded shared request start, when one exists. */
-    lastStart(): number | undefined;
-    /**
-     * Bounded admission on one read class, sharing ONE timeline with the other
-     * class. Returns `admitted` after sleeping to the reserved slot or `refused`
-     * (reserving nothing and never advancing the horizon) when the predicted
-     * wait exceeds `maxWaitMs`. Decisions are made synchronously per enqueue, so
-     * concurrent callers can never double-reserve one slot.
-     */
-    waitForSlot(pacing: ReadQoSClass, maxWaitMs: number): Promise<RequestStartAdmission>;
-    /**
-     * Single serialized admission-loop coroutine.
-     *
-     * Every concurrent caller enqueues its waiter and, when a drain is already
-     * running, returns immediately; the running loop picks the waiter up on its
-     * next `serveBatch` pass. Each pass reserves the shared slots for ALL
-     * currently-queued waiters in weighted-FIFO order with the clock frozen for
-     * that pass, so a burst of callers arriving in one synchronous tick is
-     * scheduled against the SAME horizon — deep reservations beyond `maxWaitMs`
-     * are refused without advancing it, exactly like the single-class limiter —
-     * while the 2:1 weighted fairness is applied whenever both read classes are
-     * queued together.
-     */
-    private drain;
-    /**
-     * Reserves the next shared slots for every currently-queued waiter, in
-     * weighted-FIFO order, synchronously (the clock is frozen for the pass). An
-     * admitted waiter sleeps before it is released; a refused waiter is released
-     * immediately WITHOUT reserving or advancing the shared horizon. Returns
-     * whether any waiter was served (admitted or refused).
-     */
-    private serveBatch;
-    /**
-     * Picks the next class to serve: FIFO within a class, and the weighted 2:1
-     * polling:preflight policy only when BOTH classes have queued work so an
-     * idle class never blocks or starves the other.
-     */
-    private pickClass;
-}
-//# sourceMappingURL=rateLimiter.d.ts.map

package/dist/sheets/providers/google-sheets-api/transport/rateLimiter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"rateLimiter.d.ts","sourceRoot":"","sources":["../../../../../../../../src/sheets/providers/google-sheets-api/transport/rateLimiter.ts"],"names":[],"mappings":"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"}