@rulvar/store-postgres 1.94.0 → 1.95.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, shared with the sqlite store. */
@@ -112,4 +112,90 @@ declare class PostgresStore implements MetaLookupStore, LeasableStore {
   release(l: Lease): Promise<void>;
 }
 //#endregion
-export { DEFAULT_LEASE_TTL_MS, DEFAULT_POOL_MAX, PostgresStore, type PostgresStoreOptions, type PostgresTranscriptStore };
+//#region src/quota.d.ts
+/**
+* How long a reserve/reconcile transaction waits for the schema-wide
+* admission lock before postgres cancels the statement. Quota
+* admissions are short single-writer transactions; queueing here IS
+* the cross-host serialization working.
+*/
+declare const QUOTA_LOCK_TIMEOUT_MS = 2e3;
+interface PostgresQuotaLimiterOptions {
+  /**
+  * A postgres connection string shared by every coordinating process
+  * and host (the database may also hold a PostgresStore; the tables
+  * do not collide).
+  */
+  url: string;
+  /**
+  * Schema holding the two quota tables; default `public`. A
+  * non-public schema is created on boot. Must be a plain SQL
+  * identifier.
+  */
+  schema?: string;
+  /** The shared rule set; must be identical across hosts. */
+  rules: readonly QuotaRule[];
+  /** Pool size ceiling; default 10. Admissions are short transactions. */
+  max?: number;
+  /** Injectable clock for window tests. */
+  now?: () => number;
+}
+/**
+* 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
+* provider quota. Admission consumes the window counters inside a
+* single transaction serialized on a schema-wide advisory transaction
+* lock, so two processes or HOSTS can never both take the last slot;
+* reservations are rows, so `reconcile` settles a grant from any host;
+* 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, `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.
+*/
+declare class PostgresQuotaLimiter implements QuotaLimiter {
+  private readonly pool;
+  private readonly schema;
+  private readonly rules;
+  private readonly now;
+  private boot;
+  constructor(options: PostgresQuotaLimiterOptions);
+  /** `"schema".rulvar_<name>`, always schema-qualified. */
+  private table;
+  /**
+  * The lazy idempotent bootstrap, memoized so it runs once per
+  * limiter; a rejected boot clears the memo so the next call retries.
+  * The schema-scoped advisory transaction lock serializes a fleet of
+  * processes bootstrapping the same fresh database (the PostgresStore
+  * pattern: postgres queues on the lock and needs no busy retry).
+  */
+  private booted;
+  private runBootstrap;
+  /**
+  * One serialized admission transaction: BEGIN, bound the lock wait,
+  * 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.
+  */
+  private withQuotaLock;
+  reserve(request: QuotaReservationRequest): Promise<QuotaDecision>;
+  reconcile(reservationId: string, usage: Usage): Promise<void>;
+  /** Current-window counters per rule, for telemetry and referees. */
+  snapshot(): Promise<Array<{
+    rule: QuotaRule;
+    windowStart: number;
+    requests: number;
+    tokens: number;
+  }>>;
+  close(): Promise<void>;
+  /** Both tables stay bounded to the current and previous window. */
+  private prune;
+}
+//#endregion
+export { DEFAULT_LEASE_TTL_MS, DEFAULT_POOL_MAX, PostgresQuotaLimiter, type PostgresQuotaLimiterOptions, PostgresStore, type PostgresStoreOptions, type PostgresTranscriptStore, QUOTA_LOCK_TIMEOUT_MS };

package/dist/index.js

@@ -1,5 +1,6 @@
 import pg from "pg";
-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
 /**
 * PostgresStore (RV-214): JournalStore plus LeasableStore with fencing
@@ -56,9 +57,12 @@ import { ConfigError, JournalOrderViolation, LeaseHeldError, metaMatchesFilter }
 const DEFAULT_LEASE_TTL_MS = 6e4;
 /** Default pg Pool size; every operation is a short transaction. */
 const DEFAULT_POOL_MAX = 10;
-/** The advisory-lock hash seed; a constant namespace for this store. */
+/**
+* The advisory-lock hash seed; a constant namespace shared by this
+* store and the quota limiter beside it (their key strings differ).
+*/
 const LOCK_SEED = 8214;
-const wallClock = Date.now.bind(globalThis);
+const wallClock$1 = Date.now.bind(globalThis);
 /** A conservative SQL identifier gate for the schema option. */
 const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
 var PostgresStore = class {
@@ -89,7 +93,7 @@ var PostgresStore = class {
 		if (options.max !== void 0 && (!Number.isInteger(options.max) || options.max < 1)) throw new ConfigError(`PostgresStoreOptions.max must be a positive integer; got ${String(options.max)}`);
 		this.schema = schema;
 		this.ttlMs = ttlMs;
-		this.now = options.now ?? wallClock;
+		this.now = options.now ?? wallClock$1;
 		this.pool = new pg.Pool({
 			connectionString: options.url,
 			max: options.max ?? 10
@@ -408,4 +412,275 @@ var PostgresStore = class {
 	}
 };
 //#endregion
-export { DEFAULT_LEASE_TTL_MS, DEFAULT_POOL_MAX, PostgresStore };
+//#region src/quota.ts
+/**
+* PostgresQuotaLimiter (RV410): the multi-host reference
+* implementation of the core QuotaLimiter SPI over node-postgres.
+* Engine processes on ANY number of hosts pointing instances at one
+* database and schema enforce ONE global quota: admission consumes the
+* window counters inside a single transaction that first takes a
+* schema-wide advisory transaction lock (the PostgresStore translation
+* of the sqlite BEGIN IMMEDIATE lesson: checking in one statement and
+* mutating in the next leaves a window where two admitters both read
+* the last slot), so two hosts 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, `memoryQuotaLimiter`, and
+*   `SqliteQuotaLimiter` 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
+*   database must configure the same rules, and equal rules land on
+*   the same bucket regardless of order.
+* - Reservations are rows, so reconcile works from any host. 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 on the advisory lock instead of failing
+*   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.
+* - 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
+*   policy, exactly as documented for the other references.
+*
+* Docs: https://docs.rulvar.com/guide/model-routing
+*/
+/**
+* How long a reserve/reconcile transaction waits for the schema-wide
+* admission lock before postgres cancels the statement. Quota
+* admissions are short single-writer transactions; queueing here IS
+* the cross-host serialization working.
+*/
+const QUOTA_LOCK_TIMEOUT_MS = 2e3;
+const wallClock = Date.now.bind(globalThis);
+/**
+* The canonical bucket key of one rule: a fixed-field-order JSON of
+* its content, identical across hosts for identical rules (and
+* identical to the SqliteQuotaLimiter encoding).
+*/
+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 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
+* provider quota. Admission consumes the window counters inside a
+* single transaction serialized on a schema-wide advisory transaction
+* lock, so two processes or HOSTS can never both take the last slot;
+* reservations are rows, so `reconcile` settles a grant from any host;
+* 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, `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.
+*/
+var PostgresQuotaLimiter = class {
+	pool;
+	schema;
+	rules;
+	now;
+	boot;
+	constructor(options) {
+		if (typeof options.url !== "string" || options.url === "") throw new ConfigError("PostgresQuotaLimiterOptions.url must be a nonempty connection string");
+		const schema = options.schema ?? "public";
+		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)}`);
+		this.schema = schema;
+		this.rules = options.rules;
+		this.now = options.now ?? wallClock;
+		this.pool = new pg.Pool({
+			connectionString: options.url,
+			max: options.max ?? 10
+		});
+		this.pool.on("error", () => void 0);
+	}
+	/** `"schema".rulvar_<name>`, always schema-qualified. */
+	table(name) {
+		return `"${this.schema}".rulvar_${name}`;
+	}
+	/**
+	* The lazy idempotent bootstrap, memoized so it runs once per
+	* limiter; a rejected boot clears the memo so the next call retries.
+	* The schema-scoped advisory transaction lock serializes a fleet of
+	* processes bootstrapping the same fresh database (the PostgresStore
+	* pattern: postgres queues on the lock and needs no busy retry).
+	*/
+	booted() {
+		this.boot ??= this.runBootstrap().catch((thrown) => {
+			this.boot = void 0;
+			throw thrown;
+		});
+		return this.boot;
+	}
+	async runBootstrap() {
+		const client = await this.pool.connect();
+		try {
+			await client.query("BEGIN");
+			await client.query("SELECT pg_advisory_xact_lock(hashtextextended($1, $2))", [`rulvar-quota-boot:${this.schema}`, LOCK_SEED]);
+			if (this.schema !== "public") await client.query(`CREATE SCHEMA IF NOT EXISTS "${this.schema}"`);
+			await client.query(`
+        CREATE TABLE IF NOT EXISTS ${this.table("quota_buckets")} (
+          rule_key TEXT NOT NULL,
+          window_start BIGINT NOT NULL,
+          requests BIGINT NOT NULL,
+          tokens BIGINT NOT NULL,
+          PRIMARY KEY (rule_key, window_start)
+        );
+        CREATE TABLE IF NOT EXISTS ${this.table("quota_reservations")} (
+          id TEXT PRIMARY KEY,
+          window_start BIGINT NOT NULL,
+          estimate_tokens BIGINT NOT NULL,
+          rule_keys TEXT NOT NULL
+        );
+      `);
+			await client.query("COMMIT");
+		} catch (thrown) {
+			await client.query("ROLLBACK").catch(() => void 0);
+			throw thrown;
+		} finally {
+			client.release();
+		}
+	}
+	/**
+	* One serialized admission transaction: BEGIN, bound the lock wait,
+	* 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.
+	*/
+	async withQuotaLock(fn) {
+		await this.booted();
+		const client = await this.pool.connect();
+		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;
+		} finally {
+			client.release();
+		}
+	}
+	reserve(request) {
+		const at = this.now();
+		const windowStart = at - at % QUOTA_WINDOW_MS;
+		const estimateTokens = quotaEstimateTokens(request);
+		return this.withQuotaLock(async (client) => {
+			await this.prune(client, windowStart);
+			const matched = [];
+			let denial;
+			for (const rule of this.rules) {
+				if (!quotaRuleMatches(rule, request)) continue;
+				const key = ruleKey(rule);
+				matched.push(key);
+				const row = (await client.query(`SELECT requests::int8 AS requests, tokens::int8 AS tokens
+               FROM ${this.table("quota_buckets")} WHERE rule_key = $1 AND window_start = $2`, [key, windowStart])).rows[0];
+				const verdict = quotaRuleAdmission(rule, row === void 0 ? {
+					requests: 0,
+					tokens: 0
+				} : {
+					requests: Number(row.requests),
+					tokens: Number(row.tokens)
+				}, {
+					requests: request.estimate.requests,
+					tokens: estimateTokens
+				}, windowStart + QUOTA_WINDOW_MS - at);
+				if (!verdict.admit) denial = mergeQuotaDenial(denial, verdict);
+			}
+			if (denial !== void 0) return {
+				granted: false,
+				...denial
+			};
+			for (const key of matched) await client.query(`INSERT INTO ${this.table("quota_buckets")} AS b
+             (rule_key, window_start, requests, tokens) VALUES ($1, $2, $3, $4)
+           ON CONFLICT (rule_key, window_start) DO UPDATE SET
+             requests = b.requests + excluded.requests, tokens = b.tokens + excluded.tokens`, [
+				key,
+				windowStart,
+				request.estimate.requests,
+				estimateTokens
+			]);
+			const reservationId = randomUUID();
+			await client.query(`INSERT INTO ${this.table("quota_reservations")}
+           (id, window_start, estimate_tokens, rule_keys) VALUES ($1, $2, $3, $4)`, [
+				reservationId,
+				windowStart,
+				estimateTokens,
+				JSON.stringify(matched)
+			]);
+			return {
+				granted: true,
+				reservationId
+			};
+		});
+	}
+	reconcile(reservationId, usage) {
+		const at = this.now();
+		const windowStart = at - at % QUOTA_WINDOW_MS;
+		return this.withQuotaLock(async (client) => {
+			const row = (await client.query(`SELECT window_start::int8 AS window_start, estimate_tokens::int8 AS estimate_tokens,
+                  rule_keys
+             FROM ${this.table("quota_reservations")} WHERE id = $1`, [reservationId])).rows[0];
+			if (row === void 0) return;
+			await client.query(`DELETE FROM ${this.table("quota_reservations")} WHERE id = $1`, [reservationId]);
+			if (Number(row.window_start) === windowStart) {
+				const delta = quotaActualTokens(usage) - Number(row.estimate_tokens);
+				for (const key of JSON.parse(row.rule_keys)) await client.query(`UPDATE ${this.table("quota_buckets")} SET tokens = GREATEST(0, tokens + $1)
+               WHERE rule_key = $2 AND window_start = $3`, [
+					delta,
+					key,
+					windowStart
+				]);
+			}
+		});
+	}
+	/** Current-window counters per rule, for telemetry and referees. */
+	async snapshot() {
+		await this.booted();
+		const at = this.now();
+		const windowStart = at - at % QUOTA_WINDOW_MS;
+		const out = [];
+		for (const rule of this.rules) {
+			const row = (await this.pool.query(`SELECT requests::int8 AS requests, tokens::int8 AS tokens
+             FROM ${this.table("quota_buckets")} WHERE rule_key = $1 AND window_start = $2`, [ruleKey(rule), windowStart])).rows[0];
+			out.push({
+				rule,
+				windowStart,
+				requests: row === void 0 ? 0 : Number(row.requests),
+				tokens: row === void 0 ? 0 : Number(row.tokens)
+			});
+		}
+		return out;
+	}
+	async close() {
+		await this.pool.end();
+	}
+	/** Both tables stay bounded to the current and previous window. */
+	async prune(client, windowStart) {
+		const cutoff = windowStart - QUOTA_WINDOW_MS;
+		await client.query(`DELETE FROM ${this.table("quota_buckets")} WHERE window_start < $1`, [cutoff]);
+		await client.query(`DELETE FROM ${this.table("quota_reservations")} WHERE window_start < $1`, [cutoff]);
+	}
+};
+//#endregion
+export { DEFAULT_LEASE_TTL_MS, DEFAULT_POOL_MAX, PostgresQuotaLimiter, PostgresStore, QUOTA_LOCK_TIMEOUT_MS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/store-postgres",
-  "version": "1.94.0",
+  "version": "1.95.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.94.0"
+    "@rulvar/core": "1.95.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
     "@types/pg": "^8.20.0",
     "tsdown": "^0.22.14",
     "typescript": "~6.0.3",
-    "@rulvar/store-conformance": "1.94.0"
+    "@rulvar/store-conformance": "1.95.0"
   },
   "repository": {
     "type": "git",