@rulvar/store-sqlite 1.55.0 → 1.57.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { JournalEntry, LeasableStore, Lease, MetaLookupStore, RunFilter, RunMeta, TranscriptStore } from "@rulvar/core";
+import { JournalEntry, LeasableStore, Lease, MetaLookupStore, QuotaDecision, QuotaLimiter, QuotaReservationRequest, QuotaRule, RunFilter, RunMeta, TranscriptStore, Usage } from "@rulvar/core";
 
 //#region src/store.d.ts
 /** Appendix A interim reference for the sqlite store. */
@@ -113,4 +113,58 @@ declare class SqliteStore implements MetaLookupStore, LeasableStore {
   release(l: Lease): Promise<void>;
 }
 //#endregion
-export { BOOT_BUSY_TIMEOUT_MS, DEFAULT_LEASE_TTL_MS, SqliteStore, type SqliteStoreOptions, type SqliteTranscriptStore };
+//#region src/quota.d.ts
+/**
+* How long a runtime reserve/reconcile transaction waits for a
+* sibling process's transaction before the driver reports busy. Quota
+* admissions are short single-writer transactions; queueing here IS
+* the cross-process serialization working.
+*/
+declare const QUOTA_BUSY_TIMEOUT_MS = 2e3;
+interface SqliteQuotaLimiterOptions {
+  /** Database file path shared by every coordinating process. */
+  path: string;
+  /** The shared rule set; must be identical across processes. */
+  rules: readonly QuotaRule[];
+  /** Injectable clock for window tests. */
+  now?: () => number;
+}
+/**
+* The cross-process reference implementation of the core QuotaLimiter
+* SPI: engine processes pointing instances at ONE database file (this
+* store's file or its own) enforce one global provider quota.
+* Admission consumes the window counters inside a single
+* `BEGIN IMMEDIATE` transaction, so two processes can never both take
+* the last slot; reservations are rows, so `reconcile` settles a
+* grant from any process; both tables are lazily pruned to the
+* current and previous accounting window. The rule model, the fixed
+* epoch-aligned one-minute windows, and the admission decision are
+* the core's own exported functions, so this limiter and
+* `memoryQuotaLimiter` agree on every verdict. The `rules` MUST be
+* identical across coordinating processes (buckets key on rule
+* content). Runtime contention queues briefly on the connection's
+* busy_timeout (a hot limiter is EXPECTED to serialize); a call still
+* busy past the bound throws, and the engine's `onLimiterError`
+* policy decides what that means. Call `close()` when done.
+*/
+declare class SqliteQuotaLimiter implements QuotaLimiter {
+  private readonly db;
+  private readonly rules;
+  private readonly now;
+  constructor(options: SqliteQuotaLimiterOptions);
+  reserve(request: QuotaReservationRequest): Promise<QuotaDecision>;
+  reconcile(reservationId: string, usage: Usage): Promise<void>;
+  /** Current-window counters per rule, for telemetry and referees. */
+  snapshot(): Array<{
+    rule: QuotaRule;
+    windowStart: number;
+    requests: number;
+    tokens: number;
+  }>;
+  close(): void;
+  /** Both tables stay bounded to the current and previous window. */
+  private prune;
+  private rollbackQuietly;
+}
+//#endregion
+export { BOOT_BUSY_TIMEOUT_MS, DEFAULT_LEASE_TTL_MS, QUOTA_BUSY_TIMEOUT_MS, SqliteQuotaLimiter, type SqliteQuotaLimiterOptions, SqliteStore, type SqliteStoreOptions, type SqliteTranscriptStore };

package/dist/index.js

@@ -1,5 +1,6 @@
 import { DatabaseSync } from "node:sqlite";
-import { ConfigError, JournalOrderViolation, LeaseHeldError, metaMatchesFilter } from "@rulvar/core";
+import { ConfigError, JournalOrderViolation, LeaseHeldError, QUOTA_WINDOW_MS, mergeQuotaDenial, metaMatchesFilter, quotaActualTokens, quotaEstimateTokens, quotaRuleAdmission, quotaRuleMatches, validateQuotaRules } from "@rulvar/core";
+import { randomUUID } from "node:crypto";
 //#region src/store.ts
 /**
 * SqliteStore (M5-T02): JournalStore plus LeasableStore with fencing
@@ -60,7 +61,7 @@ const BOOT_BUSY_TIMEOUT_MS = 5e3;
 * also yields SQLITE_BUSY_RECOVERY 261 while a sibling process is
 * recovering the fresh WAL), so the primary code is the low byte.
 */
-function isSqliteBusy(thrown) {
+function isSqliteBusy$1(thrown) {
 	const errcode = thrown?.errcode;
 	return errcode !== void 0 && (errcode & 255) === 5;
 }
@@ -69,10 +70,10 @@ function isSqliteBusy(thrown) {
 * synchronous by SPI shape): Atomics.wait blocks the thread for the few
 * milliseconds another process needs to finish the shared bootstrap.
 */
-function sleepSync(ms) {
+function sleepSync$1(ms) {
 	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
-const wallClock = Date.now.bind(globalThis);
+const wallClock$1 = Date.now.bind(globalThis);
 var SqliteStore = class {
 	/**
 	* The fenced writes promise (fenced run state RFC, phase 2): every
@@ -91,7 +92,7 @@ var SqliteStore = class {
 		if (!Number.isInteger(ttlMs) || ttlMs < 1 || ttlMs > 2147483647) throw new ConfigError(`SqliteStoreOptions.ttlMs must be an integer between 1 and 2147483647 ms (workers renew on Node timers at ttl/3); got ${String(ttlMs)}`);
 		this.db = new DatabaseSync(options.path);
 		this.ttlMs = ttlMs;
-		this.now = options.now ?? wallClock;
+		this.now = options.now ?? wallClock$1;
 		const schema = `
       PRAGMA journal_mode = WAL;
       CREATE TABLE IF NOT EXISTS entries (
@@ -127,13 +128,13 @@ var SqliteStore = class {
       );
       CREATE INDEX IF NOT EXISTS blobs_by_run ON blobs (run_id);
     `;
-		const bootDeadline = wallClock() + BOOT_BUSY_TIMEOUT_MS;
+		const bootDeadline = wallClock$1() + BOOT_BUSY_TIMEOUT_MS;
 		for (let attempt = 0;; attempt += 1) try {
 			this.db.exec(schema);
 			break;
 		} catch (thrown) {
-			if (!isSqliteBusy(thrown) || wallClock() > bootDeadline) throw thrown;
-			sleepSync(2 + attempt % 7);
+			if (!isSqliteBusy$1(thrown) || wallClock$1() > bootDeadline) throw thrown;
+			sleepSync$1(2 + attempt % 7);
 		}
 	}
 	close() {
@@ -354,4 +355,217 @@ var SqliteStore = class {
 	}
 };
 //#endregion
-export { BOOT_BUSY_TIMEOUT_MS, DEFAULT_LEASE_TTL_MS, SqliteStore };
+//#region src/quota.ts
+/**
+* SqliteQuotaLimiter (RV-215): the cross-process reference
+* implementation of the core QuotaLimiter SPI over the builtin
+* node:sqlite driver. Engine processes sharing one database file
+* enforce ONE global quota: admission consumes window counters inside
+* a single BEGIN IMMEDIATE transaction (the fenced-run-state lesson:
+* checking in one autocommit statement and mutating in the next
+* leaves a cross-process window where two admitters both read the
+* last slot), so two processes can never both take it.
+*
+* Contract highlights:
+* - The rule model, window math, and admission decision are the
+*   core's own (`quotaRuleAdmission` over fixed epoch-aligned
+*   one-minute windows), so this limiter and `memoryQuotaLimiter`
+*   agree byte-for-byte on every verdict.
+* - Buckets key on the rule CONTENT (a canonical fixed-order JSON of
+*   the rule), not on array position: every process sharing the file
+*   must configure the same rules, and equal rules land on the same
+*   bucket regardless of order.
+* - Reservations are rows, so reconcile works from any process. A
+*   crashed process that never reconciles leaves its estimate in the
+*   window until the window ages out; the lazy prune keeps both
+*   tables bounded to two windows.
+* - Runtime contention queues briefly on the connection's
+*   busy_timeout instead of failing raw: a hot limiter is EXPECTED to
+*   serialize admissions. A still-busy call past the bound throws,
+*   and the engine's `onLimiterError` policy decides what that means.
+*
+* Docs: https://docs.rulvar.com/guide/model-routing
+*/
+/**
+* How long a runtime reserve/reconcile transaction waits for a
+* sibling process's transaction before the driver reports busy. Quota
+* admissions are short single-writer transactions; queueing here IS
+* the cross-process serialization working.
+*/
+const QUOTA_BUSY_TIMEOUT_MS = 2e3;
+/** The SQLITE_BUSY family; the primary code is the low byte. */
+function isSqliteBusy(thrown) {
+	const errcode = thrown?.errcode;
+	return errcode !== void 0 && (errcode & 255) === 5;
+}
+/** Synchronous bounded sleep for the boot retry loop. */
+function sleepSync(ms) {
+	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+const wallClock = Date.now.bind(globalThis);
+/**
+* The canonical bucket key of one rule: a fixed-field-order JSON of
+* its content, identical across processes for identical rules.
+*/
+function ruleKey(rule) {
+	return JSON.stringify({
+		provider: rule.provider ?? null,
+		model: rule.model ?? null,
+		tenant: rule.tenant ?? null,
+		requestsPerMinute: rule.requestsPerMinute ?? null,
+		tokensPerMinute: rule.tokensPerMinute ?? null
+	});
+}
+/**
+* The cross-process reference implementation of the core QuotaLimiter
+* SPI: engine processes pointing instances at ONE database file (this
+* store's file or its own) enforce one global provider quota.
+* Admission consumes the window counters inside a single
+* `BEGIN IMMEDIATE` transaction, so two processes can never both take
+* the last slot; reservations are rows, so `reconcile` settles a
+* grant from any process; both tables are lazily pruned to the
+* current and previous accounting window. The rule model, the fixed
+* epoch-aligned one-minute windows, and the admission decision are
+* the core's own exported functions, so this limiter and
+* `memoryQuotaLimiter` agree on every verdict. The `rules` MUST be
+* identical across coordinating processes (buckets key on rule
+* content). Runtime contention queues briefly on the connection's
+* busy_timeout (a hot limiter is EXPECTED to serialize); a call still
+* busy past the bound throws, and the engine's `onLimiterError`
+* policy decides what that means. Call `close()` when done.
+*/
+var SqliteQuotaLimiter = class {
+	db;
+	rules;
+	now;
+	constructor(options) {
+		if (typeof options.path !== "string" || options.path === "") throw new ConfigError("SqliteQuotaLimiterOptions.path must be a nonempty string");
+		validateQuotaRules(options.rules, "SqliteQuotaLimiterOptions.rules");
+		this.rules = options.rules;
+		this.now = options.now ?? wallClock;
+		this.db = new DatabaseSync(options.path);
+		const schema = `
+      PRAGMA busy_timeout = ${String(QUOTA_BUSY_TIMEOUT_MS)};
+      PRAGMA journal_mode = WAL;
+      CREATE TABLE IF NOT EXISTS quota_buckets (
+        rule_key TEXT NOT NULL,
+        window_start INTEGER NOT NULL,
+        requests INTEGER NOT NULL,
+        tokens INTEGER NOT NULL,
+        PRIMARY KEY (rule_key, window_start)
+      );
+      CREATE TABLE IF NOT EXISTS quota_reservations (
+        id TEXT PRIMARY KEY,
+        window_start INTEGER NOT NULL,
+        estimate_tokens INTEGER NOT NULL,
+        rule_keys TEXT NOT NULL
+      );
+    `;
+		const bootDeadline = wallClock() + BOOT_BUSY_TIMEOUT_MS;
+		for (;;) try {
+			this.db.exec(schema);
+			break;
+		} catch (thrown) {
+			if (!isSqliteBusy(thrown) || wallClock() > bootDeadline) throw thrown;
+			sleepSync(25);
+		}
+	}
+	reserve(request) {
+		const at = this.now();
+		const windowStart = at - at % QUOTA_WINDOW_MS;
+		const estimateTokens = quotaEstimateTokens(request);
+		this.db.exec("BEGIN IMMEDIATE");
+		try {
+			this.prune(windowStart);
+			const read = this.db.prepare("SELECT requests, tokens FROM quota_buckets WHERE rule_key = ? AND window_start = ?");
+			const matched = [];
+			let denial;
+			for (const rule of this.rules) {
+				if (!quotaRuleMatches(rule, request)) continue;
+				const key = ruleKey(rule);
+				matched.push(key);
+				const verdict = quotaRuleAdmission(rule, read.get(key, windowStart) ?? {
+					requests: 0,
+					tokens: 0
+				}, {
+					requests: request.estimate.requests,
+					tokens: estimateTokens
+				}, windowStart + QUOTA_WINDOW_MS - at);
+				if (!verdict.admit) denial = mergeQuotaDenial(denial, verdict);
+			}
+			if (denial !== void 0) {
+				this.db.exec("COMMIT");
+				return Promise.resolve({
+					granted: false,
+					...denial
+				});
+			}
+			const consume = this.db.prepare("INSERT INTO quota_buckets (rule_key, window_start, requests, tokens) VALUES (?, ?, ?, ?) ON CONFLICT (rule_key, window_start) DO UPDATE SET requests = requests + excluded.requests, tokens = tokens + excluded.tokens");
+			for (const key of matched) consume.run(key, windowStart, request.estimate.requests, estimateTokens);
+			const reservationId = randomUUID();
+			this.db.prepare("INSERT INTO quota_reservations (id, window_start, estimate_tokens, rule_keys) VALUES (?, ?, ?, ?)").run(reservationId, windowStart, estimateTokens, JSON.stringify(matched));
+			this.db.exec("COMMIT");
+			return Promise.resolve({
+				granted: true,
+				reservationId
+			});
+		} catch (thrown) {
+			this.rollbackQuietly();
+			throw thrown;
+		}
+	}
+	reconcile(reservationId, usage) {
+		const at = this.now();
+		const windowStart = at - at % QUOTA_WINDOW_MS;
+		this.db.exec("BEGIN IMMEDIATE");
+		try {
+			const row = this.db.prepare("SELECT window_start, estimate_tokens, rule_keys FROM quota_reservations WHERE id = ?").get(reservationId);
+			if (row === void 0) {
+				this.db.exec("COMMIT");
+				return Promise.resolve();
+			}
+			this.db.prepare("DELETE FROM quota_reservations WHERE id = ?").run(reservationId);
+			if (row.window_start === windowStart) {
+				const delta = quotaActualTokens(usage) - row.estimate_tokens;
+				const adjust = this.db.prepare("UPDATE quota_buckets SET tokens = MAX(0, tokens + ?) WHERE rule_key = ? AND window_start = ?");
+				for (const key of JSON.parse(row.rule_keys)) adjust.run(delta, key, windowStart);
+			}
+			this.db.exec("COMMIT");
+			return Promise.resolve();
+		} catch (thrown) {
+			this.rollbackQuietly();
+			throw thrown;
+		}
+	}
+	/** Current-window counters per rule, for telemetry and referees. */
+	snapshot() {
+		const at = this.now();
+		const windowStart = at - at % QUOTA_WINDOW_MS;
+		const read = this.db.prepare("SELECT requests, tokens FROM quota_buckets WHERE rule_key = ? AND window_start = ?");
+		return this.rules.map((rule) => {
+			const row = read.get(ruleKey(rule), windowStart);
+			return {
+				rule,
+				windowStart,
+				requests: row?.requests ?? 0,
+				tokens: row?.tokens ?? 0
+			};
+		});
+	}
+	close() {
+		this.db.close();
+	}
+	/** Both tables stay bounded to the current and previous window. */
+	prune(windowStart) {
+		const cutoff = windowStart - QUOTA_WINDOW_MS;
+		this.db.prepare("DELETE FROM quota_buckets WHERE window_start < ?").run(cutoff);
+		this.db.prepare("DELETE FROM quota_reservations WHERE window_start < ?").run(cutoff);
+	}
+	rollbackQuietly() {
+		try {
+			this.db.exec("ROLLBACK");
+		} catch {}
+	}
+};
+//#endregion
+export { BOOT_BUSY_TIMEOUT_MS, DEFAULT_LEASE_TTL_MS, QUOTA_BUSY_TIMEOUT_MS, SqliteQuotaLimiter, SqliteStore };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/store-sqlite",
-  "version": "1.55.0",
+  "version": "1.57.0",
   "description": "Rulvar SQLite store implementing JournalStore and LeasableStore with a fencing epoch.",
   "type": "module",
   "license": "Apache-2.0",
@@ -22,13 +22,13 @@
     "access": "public"
   },
   "dependencies": {
-    "@rulvar/core": "1.55.0"
+    "@rulvar/core": "1.57.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",
     "tsdown": "^0.22.3",
     "typescript": "~6.0.3",
-    "@rulvar/store-conformance": "1.55.0"
+    "@rulvar/store-conformance": "1.57.0"
   },
   "repository": {
     "type": "git",