@ashlr/hub 3.2.6 → 3.2.7

package/dist/core/fleet/quota.d.ts

@@ -6,30 +6,70 @@
  * ledger records each dispatch and answers "how many in the last window?" and
  * "are we still under the configured cap?".
  *
- * Persistence discipline mirrors daemon/state.ts EXACTLY:
- *  - Atomic writes (tmp file + POSIX rename).
- *  - NEVER throws — load returns a fresh empty ledger on missing/corrupt file;
- *    record swallows any persistence error.
+ * Observation compatibility remains deliberately tolerant: load returns a fresh
+ * empty ledger on missing/corrupt state and recordUse remains best-effort. The
+ * authority-bearing reservation API is stricter:
+ *  - One local-store lock serializes read/check/append publication.
+ *  - Configured limits fail closed on ambiguous or unavailable persistence.
+ *  - Reservation identities are hashed and idempotent across retries.
+ *  - The replacement file and containing directory are fsynced before success.
  *  - mkdir -p the parent dir.
- *  - Bounded history (last ~2000 events).
+ *  - Bounded authority history (last 2000 events per known backend, max 30d).
  *  - Homedir re-resolved at call time so tests can relocate HOME.
  *
  * No new runtime deps; node builtins only. evalQuota mirrors evalBudget's
  * three-level (ok/warn/over) semantics with a null-cap-disabled path.
  */
 import type { AshlrConfig, EngineId } from '../types.js';
+import { type LocalStoreLock } from './local-store-lock.js';
 /** A single recorded backend dispatch. */
 export interface FleetQuotaEvent {
     /** Backend that was dispatched. */
     backend: EngineId;
     /** ISO timestamp of the dispatch. */
     ts: string;
+    /** Opaque idempotency identity for an authority-bearing reservation. */
+    reservationIdHash?: string;
 }
 /** The persisted fleet quota ledger. */
 export interface FleetQuota {
     /** Bounded list of recent dispatch events (oldest first). */
     events: FleetQuotaEvent[];
 }
+export interface FleetQuotaReservationRequest {
+    backend: EngineId;
+    dispatchId: string;
+}
+export interface FleetQuotaReservationReceipt {
+    backend: EngineId;
+    status: 'unlimited' | 'reserved';
+    used: number;
+    limit: number | null;
+}
+export type FleetQuotaReservationResult = {
+    kind: 'unlimited' | 'reserved';
+    launchAuthorized: true;
+    reservations: FleetQuotaReservationReceipt[];
+} | {
+    kind: 'invalid' | 'duplicate' | 'conflict' | 'exhausted' | 'unavailable' | 'capacity';
+    launchAuthorized: false;
+    backend?: EngineId;
+    used?: number;
+    limit?: number;
+    /** True means the durable reservation exists, but this call must not launch. */
+    reservationConsumed?: boolean;
+};
+export interface FleetQuotaReservationOptions {
+    /** Bounded local lock wait. Defaults to 250ms. */
+    lockWaitMs?: number;
+}
+export type FleetQuotaAuthorityHealth = 'unlimited' | 'healthy' | 'invalid' | 'unavailable' | 'capacity';
+interface FleetQuotaTestHooks {
+    now?: () => number;
+    releaseLock?: (lock: LocalStoreLock) => boolean;
+}
+/** Test-only fault injection; production callers must never configure this. */
+export declare function setFleetQuotaTestHooksForTests(hooks?: FleetQuotaTestHooks): void;
 /**
  * Convert a window label to milliseconds. Extends rollup.ts's day-granularity
  * vocabulary with sub-day windows used by rate limits. Unknown labels fall back
@@ -38,15 +78,37 @@ export interface FleetQuota {
 export declare function windowToMs(window: string): number;
 /** Absolute path to the fleet quota ledger file. */
 export declare function fleetQuotaPath(): string;
+/**
+ * Private authority ledger. It is deliberately separate from quota.json:
+ * quota.json remains backwards-compatible, best-effort operator telemetry,
+ * while this file is the fail-closed idempotency/capacity boundary.
+ */
+export declare function fleetQuotaReservationPath(): string;
+/** Lock path used by the authority-bearing quota reservation transaction. */
+export declare function fleetQuotaReservationLockPath(): string;
 /**
  * Read and parse fleetQuotaPath(). NEVER throws.
  * Returns a fresh empty ledger when the file is missing or malformed.
  */
 export declare function loadFleetQuota(): FleetQuota;
 /**
- * Append a dispatch event for `backend` (ts = now) and persist. Never throws.
+ * Append an actual dispatch-attempt event for `backend` (ts = now) and
+ * persist. Never throws. This is intentionally not launch authority; the
+ * strict reservation ledger above is separate so legacy 0644 telemetry files
+ * cannot block or overwrite authority state.
  */
 export declare function recordUse(backend: EngineId): void;
+export declare function reserveFleetQuotaUses(requests: readonly FleetQuotaReservationRequest[], cfg: AshlrConfig, options?: FleetQuotaReservationOptions): FleetQuotaReservationResult;
+/** Single-dispatch convenience wrapper over the atomic batch transaction. */
+export declare function reserveFleetQuotaUse(backend: EngineId, cfg: AshlrConfig, dispatchId: string, options?: FleetQuotaReservationOptions): FleetQuotaReservationResult;
+/** Read-only conservative health projection for operator/status surfaces. */
+export declare function inspectFleetQuotaAuthority(backend: EngineId, cfg: AshlrConfig, now?: number): FleetQuotaAuthorityHealth;
+/**
+ * Quota standing derived from reserved authority slots, not attempt telemetry.
+ * This intentionally counts conservative pre-effect reservations that may not
+ * have reached a provider: those slots still consume the configured window.
+ */
+export declare function evalFleetQuotaAuthority(backend: EngineId, cfg: AshlrConfig, now?: number): 'ok' | 'warn' | 'over' | 'unlimited';
 /**
  * Count events for `backend` whose ts is within the last `windowMs`
  * (ts >= now - windowMs). Reads the ledger internally; `now` is injectable for
@@ -58,7 +120,11 @@ export declare function usesInWindow(backend: EngineId, windowMs: number, now?:
  *
  * Mirrors evalBudget's null-cap-disabled logic: when no
  * cfg.foundry.limits[backend] is configured, the backend is unlimited ⇒ always
- * within limit. Otherwise true iff usesInWindow(...) < limit.max. `now` is
+ * within limit. Healthy configured state follows reservation standing so a
+ * consumed slot can route to an eligible peer. Invalid, unavailable, or
+ * capacity-ambiguous authority deliberately remains advisory-eligible here so
+ * the final provider-effect reservation returns the structured fail-closed
+ * refusal instead of silently capability-downgrading to builtin. `now` is
  * injectable for tests.
  */
 export declare function withinLimit(backend: EngineId, cfg: AshlrConfig, now?: number): boolean;
@@ -68,3 +134,4 @@ export declare function withinLimit(backend: EngineId, cfg: AshlrConfig, now?: n
  * cap is configured the backend is unlimited ⇒ always 'ok'. `now` is injectable.
  */
 export declare function evalQuota(backend: EngineId, cfg: AshlrConfig, now?: number): 'ok' | 'warn' | 'over';
+export {};