@rulvar/store-sqlite 1.138.0 → 1.140.0

package/dist/index.d.ts

@@ -156,10 +156,31 @@ declare class SqliteQuotaLimiter implements QuotaLimiter {
   private readonly ordered;
   private readonly now;
   constructor(options: SqliteQuotaLimiterOptions);
+  /**
+  * Adds the `requests` column release() returns to the window
+  * (RV1103). Pre-release schemas lack it; the default 1 IS the exact
+  * value for every row an engine wrote, because the engine reserves
+  * exactly one request per admission. Serialized under BEGIN
+  * IMMEDIATE so N processes booting over one legacy file cannot race
+  * the ALTER; idempotent, and busy collisions retry with the rest of
+  * the bootstrap.
+  */
+  private migrateReservationRequests;
   reserve(request: QuotaReservationRequest): Promise<QuotaDecision>;
   reconcile(reservationId: string, usage: Usage, actual?: {
     requests?: number;
   }): Promise<void>;
+  /**
+  * Cancels an UNUSED admission (RV1103, the optional SPI method from
+  * RV1013): exactly what admission consumed, the admitted requests
+  * and the token estimate, returns to the window, from any process
+  * sharing the file. Unknown ids, a double release, and a release
+  * after reconcile are no-ops (the row is gone); a rolled-over window
+  * already aged the estimate out, so only the row is deleted; a
+  * released id settles nothing afterwards. Mirrors
+  * `memoryQuotaLimiter.release` verdict for verdict.
+  */
+  release(reservationId: string): Promise<void>;
   /** Current-window counters per rule, for telemetry and referees. */
   snapshot(): Array<{
     rule: QuotaRule;

package/dist/index.js

@@ -460,12 +460,32 @@ var SqliteQuotaLimiter = class {
 		const bootDeadline = wallClock() + BOOT_BUSY_TIMEOUT_MS;
 		for (;;) try {
 			this.db.exec(schema);
+			this.migrateReservationRequests();
 			break;
 		} catch (thrown) {
 			if (!isSqliteBusy(thrown) || wallClock() > bootDeadline) throw thrown;
 			sleepSync(25);
 		}
 	}
+	/**
+	* Adds the `requests` column release() returns to the window
+	* (RV1103). Pre-release schemas lack it; the default 1 IS the exact
+	* value for every row an engine wrote, because the engine reserves
+	* exactly one request per admission. Serialized under BEGIN
+	* IMMEDIATE so N processes booting over one legacy file cannot race
+	* the ALTER; idempotent, and busy collisions retry with the rest of
+	* the bootstrap.
+	*/
+	migrateReservationRequests() {
+		this.db.exec("BEGIN IMMEDIATE");
+		try {
+			if (!this.db.prepare("PRAGMA table_info(quota_reservations)").all().some((column) => column.name === "requests")) this.db.exec("ALTER TABLE quota_reservations ADD COLUMN requests INTEGER NOT NULL DEFAULT 1");
+			this.db.exec("COMMIT");
+		} catch (thrown) {
+			this.rollbackQuietly();
+			throw thrown;
+		}
+	}
 	reserve(request) {
 		const at = this.now();
 		const windowStart = at - at % QUOTA_WINDOW_MS;
@@ -498,7 +518,7 @@ var SqliteQuotaLimiter = class {
 			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.prepare("INSERT INTO quota_reservations (id, window_start, estimate_tokens, rule_keys, requests) VALUES (?, ?, ?, ?, ?)").run(reservationId, windowStart, estimateTokens, JSON.stringify(matched), request.estimate.requests);
 			this.db.exec("COMMIT");
 			return Promise.resolve({
 				granted: true,
@@ -533,6 +553,38 @@ var SqliteQuotaLimiter = class {
 			throw thrown;
 		}
 	}
+	/**
+	* Cancels an UNUSED admission (RV1103, the optional SPI method from
+	* RV1013): exactly what admission consumed, the admitted requests
+	* and the token estimate, returns to the window, from any process
+	* sharing the file. Unknown ids, a double release, and a release
+	* after reconcile are no-ops (the row is gone); a rolled-over window
+	* already aged the estimate out, so only the row is deleted; a
+	* released id settles nothing afterwards. Mirrors
+	* `memoryQuotaLimiter.release` verdict for verdict.
+	*/
+	release(reservationId) {
+		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, requests 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 giveBack = this.db.prepare("UPDATE quota_buckets SET requests = MAX(0, requests - ?), tokens = MAX(0, tokens - ?) WHERE rule_key = ? AND window_start = ?");
+				for (const key of JSON.parse(row.rule_keys)) giveBack.run(row.requests, row.estimate_tokens, 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();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/store-sqlite",
-  "version": "1.138.0",
+  "version": "1.140.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.138.0"
+    "@rulvar/core": "1.140.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
     "tsdown": "^0.22.14",
     "typescript": "~6.0.3",
-    "@rulvar/store-conformance": "1.138.0"
+    "@rulvar/store-conformance": "1.140.0"
   },
   "repository": {
     "type": "git",