@rulvar/store-postgres 1.96.0 → 1.98.0

package/dist/index.d.ts

@@ -120,6 +120,46 @@ declare class PostgresStore implements MetaLookupStore, LeasableStore {
 * the cross-host serialization working.
 */
 declare const QUOTA_LOCK_TIMEOUT_MS = 2e3;
+/**
+* The default bound on one WHOLE admission path (RV506): lazy
+* bootstrap, pool checkout, and the admission transaction together.
+* `QUOTA_LOCK_TIMEOUT_MS` bounds only the lock-wait stage inside the
+* transaction; before RV506 a call could spend that bound once at
+* checkout and again at the lock and still not be refused. Overridable
+* per limiter through `admissionDeadlineMs`.
+*/
+declare const QUOTA_ADMISSION_DEADLINE_MS = 5e3;
+/**
+* Thrown when one quota admission (reserve or reconcile) misses the
+* full-path deadline. It surfaces exactly where the lock timeout
+* surfaces, as a limiter error consumed by the engine's
+* `onLimiterError` policy: `'deny'` (the default) turns it into a
+* retryable transport-class denial, so nothing dispatches unpoliced.
+* The connection the refused call held is destroyed, never returned
+* dirty to the pool; a transaction cut mid-flight is rolled back by
+* the server. Like any client-side timeout, expiry exactly at the
+* commit boundary can leave a committed reservation behind; it ages
+* out with its window unreconciled, the same bounded residue a
+* crashed process leaves.
+*/
+declare class QuotaDeadlineError extends Error {
+  /** The deadline that expired, in milliseconds. */
+  readonly deadlineMs: number;
+  /** The schema whose admission missed it. */
+  readonly schema: string;
+  /** Where the path stood: acquiring a connection, or mid-transaction. */
+  readonly phase: "acquire" | "transaction";
+  constructor(deadlineMs: number, schema: string, phase: "acquire" | "transaction");
+}
+/**
+* The canonical fingerprint of one rule SET (RV506): sha256 hex over
+* the sorted canonical rule keys. Order-insensitive on purpose,
+* matching bucket semantics (equal rules land on the same bucket
+* regardless of array position), so reordering a config never reads as
+* a rules change. Exported so a deployment can precompute the value it
+* expects a schema to have recorded.
+*/
+declare function quotaRulesFingerprint(rules: readonly QuotaRule[]): string;
 interface PostgresQuotaLimiterOptions {
   /**
   * A postgres connection string shared by every coordinating process
@@ -133,10 +173,33 @@ interface PostgresQuotaLimiterOptions {
   * identifier.
   */
   schema?: string;
-  /** The shared rule set; must be identical across hosts. */
+  /**
+  * The shared rule set; must be identical across hosts. Enforced: the
+  * schema records `quotaRulesFingerprint(rules)` on first boot, and an
+  * instance whose fingerprint differs is refused with a typed
+  * `ConfigError` naming both hashes.
+  */
   rules: readonly QuotaRule[];
   /** Pool size ceiling; default 10. Admissions are short transactions. */
   max?: number;
+  /**
+  * Bound on one whole admission path (bootstrap, pool checkout, and
+  * the admission transaction together); default
+  * `QUOTA_ADMISSION_DEADLINE_MS` (5000). Must be an integer strictly
+  * greater than `QUOTA_LOCK_TIMEOUT_MS`, which bounds only the
+  * lock-wait stage inside it. Expiry throws `QuotaDeadlineError` into
+  * the engine's `onLimiterError` policy and destroys the connection
+  * the refused call held.
+  */
+  admissionDeadlineMs?: number;
+  /**
+  * Rules rotation opt-in: rewrite the schema's recorded rules
+  * fingerprint with this instance's own at boot instead of refusing on
+  * a mismatch. Procedure: enable on the NEW deployment, roll every
+  * host to the new rule set, then remove the flag so drift is refused
+  * again. Default false.
+  */
+  acceptRulesUpdate?: boolean;
   /** Injectable clock for window tests. */
   now?: () => number;
 }
@@ -153,16 +216,26 @@ interface PostgresQuotaLimiterOptions {
 * and the admission decision are the core's own exported functions, so
 * this limiter, `memoryQuotaLimiter`, and `SqliteQuotaLimiter` agree
 * on every verdict. The `rules` MUST be identical across coordinating
-* processes (buckets key on rule content). Runtime contention queues
-* on the advisory lock (a hot limiter is EXPECTED to serialize); a
-* call still waiting past `QUOTA_LOCK_TIMEOUT_MS` throws, and the
-* engine's `onLimiterError` policy decides what that means. Call
-* `close()` when done.
+* processes (buckets key on rule content), and since RV506 that is
+* enforced: boot records `quotaRulesFingerprint(rules)` in the
+* schema's `rulvar_quota_meta` row and refuses a drifted instance with
+* a typed `ConfigError` naming both hashes (`acceptRulesUpdate: true`
+* rotates the record). Runtime contention queues on the advisory lock
+* (a hot limiter is EXPECTED to serialize; note the lock serializes
+* `reserve` AND `reconcile`, so it sees admission attempts plus
+* grants); a call still waiting past `QUOTA_LOCK_TIMEOUT_MS` throws,
+* and the whole admission path (bootstrap, checkout, transaction) is
+* bounded by `admissionDeadlineMs`, whose expiry throws a typed
+* `QuotaDeadlineError` and destroys the held connection. Both throws
+* land in the engine's `onLimiterError` policy, which decides what
+* they mean. Call `close()` when done.
 */
 declare class PostgresQuotaLimiter implements QuotaLimiter {
   private readonly pool;
   private readonly schema;
   private readonly rules;
+  private readonly admissionDeadlineMs;
+  private readonly acceptRulesUpdate;
   private readonly now;
   private boot;
   constructor(options: PostgresQuotaLimiterOptions);
@@ -182,6 +255,17 @@ declare class PostgresQuotaLimiter implements QuotaLimiter {
   * take the schema-wide quota advisory lock, run `fn`, COMMIT. Every
   * counter mutation goes through here, which is what makes the
   * verdict read and the consume one unit across processes and hosts.
+  *
+  * The WHOLE path (lazy bootstrap, pool checkout, transaction) races
+  * `admissionDeadlineMs` (RV506): `lock_timeout` bounds one stage, and
+  * before the deadline a call could spend that bound at checkout and
+  * again at the lock without ever being refused. On expiry the caller
+  * gets a typed `QuotaDeadlineError`, and a connection the refused
+  * call holds is destroyed through `release(err)`, never returned
+  * mid-transaction to the pool; destroying it also cancels the
+  * abandoned wait server-side. The deadline runs on the REAL clock
+  * (an injected test `now` freezes window math, not infrastructure
+  * timeouts).
   */
   private withQuotaLock;
   reserve(request: QuotaReservationRequest): Promise<QuotaDecision>;
@@ -198,4 +282,4 @@ declare class PostgresQuotaLimiter implements QuotaLimiter {
   private prune;
 }
 //#endregion
-export { DEFAULT_LEASE_TTL_MS, DEFAULT_POOL_MAX, PostgresQuotaLimiter, type PostgresQuotaLimiterOptions, PostgresStore, type PostgresStoreOptions, type PostgresTranscriptStore, QUOTA_LOCK_TIMEOUT_MS };
+export { DEFAULT_LEASE_TTL_MS, DEFAULT_POOL_MAX, PostgresQuotaLimiter, type PostgresQuotaLimiterOptions, PostgresStore, type PostgresStoreOptions, type PostgresTranscriptStore, QUOTA_ADMISSION_DEADLINE_MS, QUOTA_LOCK_TIMEOUT_MS, QuotaDeadlineError, quotaRulesFingerprint };

package/dist/index.js

@@ -1,6 +1,6 @@
 import pg from "pg";
 import { ConfigError, JournalOrderViolation, LeaseHeldError, QUOTA_WINDOW_MS, mergeQuotaDenial, metaMatchesFilter, quotaActualTokens, quotaEstimateTokens, quotaRuleAdmission, quotaRuleMatches, validateQuotaRules } from "@rulvar/core";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 //#region src/store.ts
 /**
 * PostgresStore (RV-214): JournalStore plus LeasableStore with fencing
@@ -441,7 +441,19 @@ var PostgresStore = class {
 *   raw: a hot limiter is EXPECTED to serialize admissions. A call
 *   still waiting past `QUOTA_LOCK_TIMEOUT_MS` throws (postgres
 *   cancels the statement under `SET LOCAL lock_timeout`), and the
-*   engine's `onLimiterError` policy decides what that means.
+*   engine's `onLimiterError` policy decides what that means. The lock
+*   serializes `reserve` AND `reconcile`, so its arrival rate is
+*   admission attempts PLUS grants, not attempts alone.
+* - The lock bound is one STAGE; the whole admission path (bootstrap,
+*   pool checkout, transaction) is bounded by `admissionDeadlineMs`
+*   (default `QUOTA_ADMISSION_DEADLINE_MS`, RV506). Expiry throws a
+*   typed `QuotaDeadlineError` into the same `onLimiterError` surface
+*   and destroys the held connection instead of returning it dirty.
+* - Boot records the sha256 fingerprint of the canonical rule set in
+*   `rulvar_quota_meta` under the boot lock; a host with a drifted
+*   rule set is refused typed with both hashes instead of silently
+*   splitting the budget across mismatched bucket keys. Rotation is
+*   the explicit `acceptRulesUpdate` opt-in (RV506).
 * - The durable admission QUEUE stays the host's: a denial carries the
 *   honest window remainder, and what to do while waiting (park the
 *   run, spill to another provider, surface backpressure) is host
@@ -456,6 +468,43 @@ var PostgresStore = class {
 * the cross-host serialization working.
 */
 const QUOTA_LOCK_TIMEOUT_MS = 2e3;
+/**
+* The default bound on one WHOLE admission path (RV506): lazy
+* bootstrap, pool checkout, and the admission transaction together.
+* `QUOTA_LOCK_TIMEOUT_MS` bounds only the lock-wait stage inside the
+* transaction; before RV506 a call could spend that bound once at
+* checkout and again at the lock and still not be refused. Overridable
+* per limiter through `admissionDeadlineMs`.
+*/
+const QUOTA_ADMISSION_DEADLINE_MS = 5e3;
+/**
+* Thrown when one quota admission (reserve or reconcile) misses the
+* full-path deadline. It surfaces exactly where the lock timeout
+* surfaces, as a limiter error consumed by the engine's
+* `onLimiterError` policy: `'deny'` (the default) turns it into a
+* retryable transport-class denial, so nothing dispatches unpoliced.
+* The connection the refused call held is destroyed, never returned
+* dirty to the pool; a transaction cut mid-flight is rolled back by
+* the server. Like any client-side timeout, expiry exactly at the
+* commit boundary can leave a committed reservation behind; it ages
+* out with its window unreconciled, the same bounded residue a
+* crashed process leaves.
+*/
+var QuotaDeadlineError = class extends Error {
+	/** The deadline that expired, in milliseconds. */
+	deadlineMs;
+	/** The schema whose admission missed it. */
+	schema;
+	/** Where the path stood: acquiring a connection, or mid-transaction. */
+	phase;
+	constructor(deadlineMs, schema, phase) {
+		super(`PostgresQuotaLimiter admission over schema "${schema}" missed its ${String(deadlineMs)}ms deadline ` + (phase === "acquire" ? "while waiting for bootstrap or a pooled connection" : "inside the admission transaction") + "; the in-flight admission was abandoned and its connection destroyed");
+		this.name = "QuotaDeadlineError";
+		this.deadlineMs = deadlineMs;
+		this.schema = schema;
+		this.phase = phase;
+	}
+};
 const wallClock = Date.now.bind(globalThis);
 /**
 * The canonical bucket key of one rule: a fixed-field-order JSON of
@@ -472,6 +521,18 @@ function ruleKey(rule) {
 	});
 }
 /**
+* The canonical fingerprint of one rule SET (RV506): sha256 hex over
+* the sorted canonical rule keys. Order-insensitive on purpose,
+* matching bucket semantics (equal rules land on the same bucket
+* regardless of array position), so reordering a config never reads as
+* a rules change. Exported so a deployment can precompute the value it
+* expects a schema to have recorded.
+*/
+function quotaRulesFingerprint(rules) {
+	const keys = rules.map(ruleKey).sort();
+	return createHash("sha256").update(JSON.stringify(keys)).digest("hex");
+}
+/**
 * The multi-host reference implementation of the core QuotaLimiter
 * SPI: engine processes pointing instances at ONE database and schema
 * (a PostgresStore's database or their own) enforce one global
@@ -484,16 +545,26 @@ function ruleKey(rule) {
 * and the admission decision are the core's own exported functions, so
 * this limiter, `memoryQuotaLimiter`, and `SqliteQuotaLimiter` agree
 * on every verdict. The `rules` MUST be identical across coordinating
-* processes (buckets key on rule content). Runtime contention queues
-* on the advisory lock (a hot limiter is EXPECTED to serialize); a
-* call still waiting past `QUOTA_LOCK_TIMEOUT_MS` throws, and the
-* engine's `onLimiterError` policy decides what that means. Call
-* `close()` when done.
+* processes (buckets key on rule content), and since RV506 that is
+* enforced: boot records `quotaRulesFingerprint(rules)` in the
+* schema's `rulvar_quota_meta` row and refuses a drifted instance with
+* a typed `ConfigError` naming both hashes (`acceptRulesUpdate: true`
+* rotates the record). Runtime contention queues on the advisory lock
+* (a hot limiter is EXPECTED to serialize; note the lock serializes
+* `reserve` AND `reconcile`, so it sees admission attempts plus
+* grants); a call still waiting past `QUOTA_LOCK_TIMEOUT_MS` throws,
+* and the whole admission path (bootstrap, checkout, transaction) is
+* bounded by `admissionDeadlineMs`, whose expiry throws a typed
+* `QuotaDeadlineError` and destroys the held connection. Both throws
+* land in the engine's `onLimiterError` policy, which decides what
+* they mean. Call `close()` when done.
 */
 var PostgresQuotaLimiter = class {
 	pool;
 	schema;
 	rules;
+	admissionDeadlineMs;
+	acceptRulesUpdate;
 	now;
 	boot;
 	constructor(options) {
@@ -502,12 +573,16 @@ var PostgresQuotaLimiter = class {
 		if (!IDENTIFIER.test(schema)) throw new ConfigError(`PostgresQuotaLimiterOptions.schema must be a plain SQL identifier; got '${schema}'`);
 		validateQuotaRules(options.rules, "PostgresQuotaLimiterOptions.rules");
 		if (options.max !== void 0 && (!Number.isInteger(options.max) || options.max < 1)) throw new ConfigError(`PostgresQuotaLimiterOptions.max must be a positive integer; got ${String(options.max)}`);
+		if (options.admissionDeadlineMs !== void 0 && (!Number.isInteger(options.admissionDeadlineMs) || options.admissionDeadlineMs <= 2e3)) throw new ConfigError(`PostgresQuotaLimiterOptions.admissionDeadlineMs must be an integer greater than QUOTA_LOCK_TIMEOUT_MS (${String(QUOTA_LOCK_TIMEOUT_MS)}), the lock-wait stage it bounds; got ${String(options.admissionDeadlineMs)}`);
 		this.schema = schema;
 		this.rules = options.rules;
+		this.admissionDeadlineMs = options.admissionDeadlineMs ?? 5e3;
+		this.acceptRulesUpdate = options.acceptRulesUpdate ?? false;
 		this.now = options.now ?? wallClock;
 		this.pool = new pg.Pool({
 			connectionString: options.url,
-			max: options.max ?? 10
+			max: options.max ?? 10,
+			connectionTimeoutMillis: this.admissionDeadlineMs
 		});
 		this.pool.on("error", () => void 0);
 	}
@@ -530,6 +605,7 @@ var PostgresQuotaLimiter = class {
 		return this.boot;
 	}
 	async runBootstrap() {
+		const fingerprint = quotaRulesFingerprint(this.rules);
 		const client = await this.pool.connect();
 		try {
 			await client.query("BEGIN");
@@ -549,7 +625,19 @@ var PostgresQuotaLimiter = class {
           estimate_tokens BIGINT NOT NULL,
           rule_keys TEXT NOT NULL
         );
+        CREATE TABLE IF NOT EXISTS ${this.table("quota_meta")} (
+          key TEXT PRIMARY KEY,
+          value TEXT
+        );
       `);
+			const recorded = (await client.query(`SELECT value FROM ${this.table("quota_meta")} WHERE key = 'rules_fingerprint'`)).rows[0]?.value;
+			if (recorded === void 0 || this.acceptRulesUpdate) await client.query(`INSERT INTO ${this.table("quota_meta")} (key, value) VALUES ('rules_fingerprint', $1)
+           ON CONFLICT (key) DO UPDATE SET value = excluded.value`, [fingerprint]);
+			else if (recorded !== fingerprint) throw new ConfigError(`PostgresQuotaLimiter rules mismatch over schema "${this.schema}": the schema records rules fingerprint ${recorded}, this instance computes ${fingerprint}. Every coordinating process must configure the identical rule set (buckets key on rule content, so a drifted host would silently split the budget). To rotate the rules, boot the new deployment with acceptRulesUpdate: true, then remove the flag.`, { data: {
+				schema: this.schema,
+				recorded,
+				computed: fingerprint
+			} });
 			await client.query("COMMIT");
 		} catch (thrown) {
 			await client.query("ROLLBACK").catch(() => void 0);
@@ -563,22 +651,60 @@ var PostgresQuotaLimiter = class {
 	* take the schema-wide quota advisory lock, run `fn`, COMMIT. Every
 	* counter mutation goes through here, which is what makes the
 	* verdict read and the consume one unit across processes and hosts.
+	*
+	* The WHOLE path (lazy bootstrap, pool checkout, transaction) races
+	* `admissionDeadlineMs` (RV506): `lock_timeout` bounds one stage, and
+	* before the deadline a call could spend that bound at checkout and
+	* again at the lock without ever being refused. On expiry the caller
+	* gets a typed `QuotaDeadlineError`, and a connection the refused
+	* call holds is destroyed through `release(err)`, never returned
+	* mid-transaction to the pool; destroying it also cancels the
+	* abandoned wait server-side. The deadline runs on the REAL clock
+	* (an injected test `now` freezes window math, not infrastructure
+	* timeouts).
 	*/
 	async withQuotaLock(fn) {
-		await this.booted();
-		const client = await this.pool.connect();
+		let client;
+		let expired = false;
+		let timer;
+		const refusal = () => new QuotaDeadlineError(this.admissionDeadlineMs, this.schema, client === void 0 ? "acquire" : "transaction");
+		const work = (async () => {
+			await this.booted();
+			if (expired) throw refusal();
+			const checkout = await this.pool.connect();
+			if (expired) {
+				checkout.release();
+				throw refusal();
+			}
+			client = checkout;
+			try {
+				await client.query("BEGIN");
+				await client.query(`SET LOCAL lock_timeout = '${String(QUOTA_LOCK_TIMEOUT_MS)}ms'`);
+				await client.query("SELECT pg_advisory_xact_lock(hashtextextended($1, $2))", [`${this.schema}:rulvar-quota`, LOCK_SEED]);
+				const result = await fn(client);
+				await client.query("COMMIT");
+				return result;
+			} catch (thrown) {
+				if (!expired) await client.query("ROLLBACK").catch(() => void 0);
+				throw thrown;
+			} finally {
+				if (!expired) client.release();
+				client = void 0;
+			}
+		})();
+		const gate = new Promise((_, reject) => {
+			timer = setTimeout(() => {
+				const reason = refusal();
+				expired = true;
+				client?.release(reason);
+				client = void 0;
+				reject(reason);
+			}, this.admissionDeadlineMs);
+		});
 		try {
-			await client.query("BEGIN");
-			await client.query(`SET LOCAL lock_timeout = '${String(QUOTA_LOCK_TIMEOUT_MS)}ms'`);
-			await client.query("SELECT pg_advisory_xact_lock(hashtextextended($1, $2))", [`${this.schema}:rulvar-quota`, LOCK_SEED]);
-			const result = await fn(client);
-			await client.query("COMMIT");
-			return result;
-		} catch (thrown) {
-			await client.query("ROLLBACK").catch(() => void 0);
-			throw thrown;
+			return await Promise.race([work, gate]);
 		} finally {
-			client.release();
+			clearTimeout(timer);
 		}
 	}
 	reserve(request) {
@@ -683,4 +809,4 @@ var PostgresQuotaLimiter = class {
 	}
 };
 //#endregion
-export { DEFAULT_LEASE_TTL_MS, DEFAULT_POOL_MAX, PostgresQuotaLimiter, PostgresStore, QUOTA_LOCK_TIMEOUT_MS };
+export { DEFAULT_LEASE_TTL_MS, DEFAULT_POOL_MAX, PostgresQuotaLimiter, PostgresStore, QUOTA_ADMISSION_DEADLINE_MS, QUOTA_LOCK_TIMEOUT_MS, QuotaDeadlineError, quotaRulesFingerprint };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/store-postgres",
-  "version": "1.96.0",
+  "version": "1.98.0",
   "description": "Rulvar PostgreSQL store implementing JournalStore and LeasableStore with a fencing epoch, for multi-process and multi-host deployments.",
   "type": "module",
   "license": "Apache-2.0",
@@ -23,14 +23,14 @@
   },
   "dependencies": {
     "pg": "^8.22.0",
-    "@rulvar/core": "1.96.0"
+    "@rulvar/core": "1.98.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
     "@types/pg": "^8.20.0",
     "tsdown": "^0.22.14",
     "typescript": "~6.0.3",
-    "@rulvar/store-conformance": "1.96.0"
+    "@rulvar/store-conformance": "1.98.0"
   },
   "repository": {
     "type": "git",