@happyvertical/smrt-core 0.40.69 → 0.40.70

package/dist/postgres-timeouts.d.ts

@@ -0,0 +1,240 @@
+/**
+ * Runtime PostgreSQL timeout defaults for every pool SMRT constructs.
+ *
+ * `@happyvertical/sql` builds its pool as `new Pool({ connectionString, max })`
+ * and nothing else, so an un-configured deployment inherits `pg`'s unbounded
+ * defaults: `pool.connect()` waits forever once the pool is exhausted, a
+ * runaway query holds its client indefinitely, and a request-scoped transaction
+ * that stalls mid-flight holds its locks until the process dies (#2377).
+ *
+ * This module resolves a bounded set of timeouts and applies them at pool
+ * construction. Three of them ride the connection URL: `pg` lifts
+ * `statement_timeout`, `lock_timeout`, and `idle_in_transaction_session_timeout`
+ * out of the connection string's query parameters and sends them in the startup
+ * packet, so they are session defaults on **every** client the pool opens,
+ * including ones opened long after startup. The fourth, the connection
+ * acquisition timeout, is a `pg` *pool* option with no connection-string
+ * spelling; it is emitted as `connectionTimeoutMillis` on the options object
+ * passed to `getDatabase()`, where `resolvePostgresConfig()` currently drops it.
+ * It becomes live with no change here once the SDK forwards pool options
+ * (happyvertical/sdk#1204).
+ *
+ * Scope: this is the *runtime* pool only. `smrt db:migrate` opens its own
+ * connection through `@happyvertical/sql` directly and bounds its statements
+ * with `SET LOCAL lock_timeout` / `statement_timeout` from
+ * `migrations.postgres.*` (#2362); a migration therefore keeps its own, larger
+ * budget even when it runs against a database whose runtime pool is bounded
+ * here. The two read the same way on purpose — same string units, same
+ * "unparseable falls back to the documented default" rule.
+ *
+ * @module
+ */
+/**
+ * Runtime PostgreSQL timeouts, as accepted from configuration.
+ *
+ * Every value is either a number of milliseconds or a duration string with an
+ * `ms`, `s`, `min`/`m`, or `h` suffix — the spelling
+ * `migrations.postgres.lockTimeout` already uses (`'30s'`). `0` means
+ * *disabled*, which is PostgreSQL's own semantic for the three server-side
+ * timeouts and `pg`'s semantic for the connection timeout ("wait forever");
+ * it is emitted explicitly so it overrides a server-side default rather than
+ * silently inheriting one.
+ *
+ * @example
+ * ```typescript
+ * const db = await resolveDatabase({
+ *   type: 'postgres',
+ *   url: process.env.DATABASE_URL,
+ *   timeouts: { statementTimeout: '10s', lockTimeout: '2s' },
+ * });
+ * ```
+ */
+export interface PostgresTimeoutConfig {
+    /**
+     * Milliseconds to wait for a pool client before failing the acquisition.
+     *
+     * Bounds `pool.connect()`, whose `pg` default of `0` waits forever — the
+     * failure mode where one runaway query silently converts into a hung request
+     * queue. Emitted as `connectionTimeoutMillis`.
+     *
+     * @default '10s'
+     */
+    connectionTimeout?: string | number;
+    /**
+     * Session `statement_timeout`: the ceiling on a single statement.
+     *
+     * @default '30s'
+     */
+    statementTimeout?: string | number;
+    /**
+     * Session `idle_in_transaction_session_timeout`: the ceiling on an open
+     * transaction that is not currently executing a statement. This is the one
+     * that releases locks held by a request that died between statements.
+     *
+     * @default '60s'
+     */
+    idleInTransactionSessionTimeout?: string | number;
+    /**
+     * Session `lock_timeout`: the ceiling on waiting for a lock.
+     *
+     * @default '10s'
+     */
+    lockTimeout?: string | number;
+}
+/**
+ * Timeouts resolved to milliseconds, ready to emit.
+ */
+export interface ResolvedPostgresTimeouts {
+    connectionTimeoutMs: number;
+    statementTimeoutMs: number;
+    idleInTransactionSessionTimeoutMs: number;
+    lockTimeoutMs: number;
+}
+/**
+ * Defaults applied to every runtime PostgreSQL pool.
+ *
+ * Chosen to bound the failure modes in #2377 without truncating legitimate
+ * request work: a web request that needs more than 30 s of server time or
+ * holds a transaction open for more than a minute is the pathology these
+ * bound, not the workload. Long-running maintenance does not run on this pool
+ * — `db:migrate` carries its own budget (#2362) — and any deployment that
+ * disagrees raises or disables the value per key.
+ */
+export declare const DEFAULT_POSTGRES_TIMEOUTS: ResolvedPostgresTimeouts;
+/**
+ * Environment variable read for each timeout when configuration does not set
+ * it.
+ *
+ * Deployments that only ever hand SMRT a `DATABASE_URL` (SvelteKit runtime
+ * config, container env, serverless) have no object to put a `timeouts` key on,
+ * so the environment is the configuration surface that actually reaches them.
+ */
+export declare const POSTGRES_TIMEOUT_ENV_VARS: {
+    readonly connectionTimeout: "SMRT_PG_CONNECTION_TIMEOUT";
+    readonly statementTimeout: "SMRT_PG_STATEMENT_TIMEOUT";
+    readonly idleInTransactionSessionTimeout: "SMRT_PG_IDLE_IN_TRANSACTION_TIMEOUT";
+    readonly lockTimeout: "SMRT_PG_LOCK_TIMEOUT";
+};
+/**
+ * Parse a PostgreSQL timeout expressed as milliseconds or as the duration
+ * string used in `smrt.config.js` into milliseconds.
+ *
+ * Accepts a bare number (milliseconds) or a number with an `ms`, `s`, `min`,
+ * `m`, or `h` suffix. Returns `fallback` for `undefined`, empty, or
+ * unparseable input so a typo degrades to the documented default instead of
+ * silently disabling the timeout it was meant to impose.
+ *
+ * This is the single implementation behind both timeout surfaces: the
+ * migration tracker re-exports it as the public
+ * `@happyvertical/smrt-core/migrations` symbol (#2362), so a runtime `timeouts`
+ * config and `migrations.postgres.*` are parsed by the same function and cannot
+ * drift. This module deliberately imports nothing, which is what lets the
+ * migration path depend on it without dragging anything into the connection
+ * path.
+ *
+ * @param value - Millisecond count or duration string
+ * @param fallback - Value returned for missing or unparseable input
+ * @returns Timeout in milliseconds
+ */
+export declare function parsePostgresTimeoutMs(value: string | number | undefined, fallback: number): number;
+/**
+ * Resolve the effective runtime timeouts.
+ *
+ * Precedence, highest first: explicit configuration, then the matching
+ * `SMRT_PG_*` environment variable, then {@link DEFAULT_POSTGRES_TIMEOUTS}.
+ * A parameter already present in the connection URL beats all three, but that
+ * is enforced where the URL is written ({@link applyPostgresTimeoutsToUrl}) —
+ * an operator who spelled a timeout into the DSN keeps it.
+ *
+ * @param config - Timeouts from configuration
+ * @param env - Environment to read (defaults to `process.env`)
+ * @returns Timeouts in milliseconds
+ */
+export declare function resolvePostgresTimeouts(config?: PostgresTimeoutConfig, env?: Record<string, string | undefined>): ResolvedPostgresTimeouts;
+/**
+ * Does this configuration open a PostgreSQL connection?
+ *
+ * Deliberately narrower than `detectEngine()` from the DDL module: that helper
+ * answers "which dialect do I generate SQL in" and folds `json` into `duckdb`,
+ * while this one answers "may I rewrite this URL", which must be false for
+ * every non-PostgreSQL adapter and must not pull the DDL strategy singletons
+ * into the connection path.
+ */
+export declare function isPostgresTarget(url?: string, type?: string): boolean;
+/**
+ * Write the session timeout parameters into a PostgreSQL connection URL.
+ *
+ * Parameters already present are left exactly as they are — an operator who
+ * put `statement_timeout` in the DSN configured it on purpose, and the
+ * per-parameter granularity means overriding one does not surrender the other
+ * two to `pg`'s unbounded defaults.
+ *
+ * The DSN is edited by **appending**, never by re-serializing. Everything the
+ * caller wrote — scheme, userinfo, host, path, and the existing query substring
+ * byte for byte — is copied through, and only the missing parameters are added
+ * after it. `URLSearchParams` is used to *read* which parameters are already
+ * present; writing through it would hand `pg` a re-encoded DSN (`%20` becoming
+ * `+`, parameters reordered) that is merely equivalent rather than identical,
+ * which is not this function's business. The emitted values are bare digits, so
+ * appending needs no encoding of its own.
+ *
+ * @param url - PostgreSQL connection URL
+ * @param timeouts - Resolved timeouts
+ * @returns The URL with the missing timeout parameters appended (the same
+ *   string when all three were already present)
+ */
+export declare function applyPostgresTimeoutsToUrl(url: string, timeouts: ResolvedPostgresTimeouts): string;
+/**
+ * Options object accepted and returned by
+ * {@link applyPostgresRuntimeTimeouts}.
+ */
+export interface PostgresTimeoutAwareConfig {
+    url?: string;
+    type?: string;
+    /** Runtime timeout overrides for this connection. */
+    timeouts?: PostgresTimeoutConfig;
+    /**
+     * `pg` pool option emitted for PostgreSQL configurations. Present on the
+     * result, not on the input.
+     */
+    connectionTimeoutMillis?: number;
+    [key: string]: unknown;
+}
+/**
+ * Bound a runtime database configuration before it reaches `getDatabase()`.
+ *
+ * Non-PostgreSQL configurations pass through unchanged — the same reference,
+ * so SQLite/DuckDB/JSON callers pay nothing and no file path is ever rewritten
+ * — except that a stray `timeouts` key is stripped on every engine, because it
+ * is SMRT configuration and never an adapter option.
+ *
+ * For PostgreSQL the returned object carries a URL with the three session
+ * timeouts and a `connectionTimeoutMillis` pool option. Callers that derive a
+ * `dbid` from the URL must derive it from the **returned** URL: two configs
+ * that differ only in their timeouts are different pools, and every call site
+ * applying the same deterministic rewrite is what keeps them one pool when the
+ * timeouts match.
+ *
+ * A PostgreSQL configuration with no `url` — discrete `host`/`port`/`database`
+ * fields, or a bare `{ type: 'postgres' }` that lets the adapter read
+ * `HAVE_SQL_URL`/`SQLOO_URL` — has nowhere to carry the session parameters and
+ * receives only `connectionTimeoutMillis`. Reproducing the adapter's own
+ * environment precedence here to synthesize a URL would fork it; pass the URL
+ * through the config (or set the `SMRT_PG_*` variables on a config that does
+ * carry one) to get the session timeouts.
+ *
+ * The `timeouts` key is consumed here and not forwarded — `@happyvertical/sql`
+ * would ignore it, and leaving it in the options object would make it look
+ * like a supported adapter option.
+ *
+ * Rewriting the URL also changes the SDK's own pool cache key for call sites
+ * that pass no `dbid`, so a consumer that separately calls `getDatabase()` with
+ * the same raw URL no longer shares SMRT's pool. Consumers that want one pool
+ * should hand SMRT the `DatabaseInterface`, not the same URL.
+ *
+ * @param config - Database configuration bound for `getDatabase()`
+ * @param env - Environment to read (defaults to `process.env`)
+ * @returns Configuration with runtime timeouts applied
+ */
+export declare function applyPostgresRuntimeTimeouts(config: PostgresTimeoutAwareConfig, env?: Record<string, string | undefined>): PostgresTimeoutAwareConfig;
+//# sourceMappingURL=postgres-timeouts.d.ts.map

package/dist/postgres-timeouts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-timeouts.d.ts","sourceRoot":"","sources":["../src/postgres-timeouts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;OAQG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAEpC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAEnC;;;;;;OAMG;IACH,+BAA+B,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAElD;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iCAAiC,EAAE,MAAM,CAAC;IAC1C,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,EAAE,wBAKvC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB;;;;;CAK0B,CAAC;AAgBjE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EAClC,QAAQ,EAAE,MAAM,GACf,MAAM,CAiCR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,GAAE,qBAA0B,EAClC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACvC,wBAAwB,CAiC1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAqBrE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,wBAAwB,GACjC,MAAM,CA0BR;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC;;;OAGG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,0BAA0B,EAClC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACvC,0BAA0B,CAgB5B"}

package/dist/postgres-timeouts.js

@@ -0,0 +1,204 @@
+//#region src/postgres-timeouts.ts
+/**
+* Defaults applied to every runtime PostgreSQL pool.
+*
+* Chosen to bound the failure modes in #2377 without truncating legitimate
+* request work: a web request that needs more than 30 s of server time or
+* holds a transaction open for more than a minute is the pathology these
+* bound, not the workload. Long-running maintenance does not run on this pool
+* — `db:migrate` carries its own budget (#2362) — and any deployment that
+* disagrees raises or disables the value per key.
+*/
+var DEFAULT_POSTGRES_TIMEOUTS = {
+	connectionTimeoutMs: 1e4,
+	statementTimeoutMs: 3e4,
+	idleInTransactionSessionTimeoutMs: 6e4,
+	lockTimeoutMs: 1e4
+};
+/**
+* Environment variable read for each timeout when configuration does not set
+* it.
+*
+* Deployments that only ever hand SMRT a `DATABASE_URL` (SvelteKit runtime
+* config, container env, serverless) have no object to put a `timeouts` key on,
+* so the environment is the configuration surface that actually reaches them.
+*/
+var POSTGRES_TIMEOUT_ENV_VARS = {
+	connectionTimeout: "SMRT_PG_CONNECTION_TIMEOUT",
+	statementTimeout: "SMRT_PG_STATEMENT_TIMEOUT",
+	idleInTransactionSessionTimeout: "SMRT_PG_IDLE_IN_TRANSACTION_TIMEOUT",
+	lockTimeout: "SMRT_PG_LOCK_TIMEOUT"
+};
+/**
+* PostgreSQL connection-string parameters that carry a session timeout.
+*
+* `pg` reads exactly these three out of the connection string and puts them in
+* the startup packet (`Client.getStartupConf`), which is why the URL is the
+* delivery mechanism: the settings then apply to every client the pool opens,
+* not just the first, with no per-checkout `SET` round trip.
+*/
+var URL_TIMEOUT_PARAMS = {
+	statementTimeoutMs: "statement_timeout",
+	idleInTransactionSessionTimeoutMs: "idle_in_transaction_session_timeout",
+	lockTimeoutMs: "lock_timeout"
+};
+/**
+* Parse a PostgreSQL timeout expressed as milliseconds or as the duration
+* string used in `smrt.config.js` into milliseconds.
+*
+* Accepts a bare number (milliseconds) or a number with an `ms`, `s`, `min`,
+* `m`, or `h` suffix. Returns `fallback` for `undefined`, empty, or
+* unparseable input so a typo degrades to the documented default instead of
+* silently disabling the timeout it was meant to impose.
+*
+* This is the single implementation behind both timeout surfaces: the
+* migration tracker re-exports it as the public
+* `@happyvertical/smrt-core/migrations` symbol (#2362), so a runtime `timeouts`
+* config and `migrations.postgres.*` are parsed by the same function and cannot
+* drift. This module deliberately imports nothing, which is what lets the
+* migration path depend on it without dragging anything into the connection
+* path.
+*
+* @param value - Millisecond count or duration string
+* @param fallback - Value returned for missing or unparseable input
+* @returns Timeout in milliseconds
+*/
+function parsePostgresTimeoutMs(value, fallback) {
+	if (typeof value === "number") return Number.isFinite(value) && value >= 0 ? Math.trunc(value) : fallback;
+	if (typeof value !== "string" || value.trim().length === 0) return fallback;
+	const match = /^\s*(\d+(?:\.\d+)?)\s*(ms|s|min|m|h)?\s*$/i.exec(value);
+	if (!match) return fallback;
+	const amount = Number.parseFloat(match[1]);
+	const unit = (match[2] ?? "ms").toLowerCase();
+	const milliseconds = amount * (unit === "h" ? 36e5 : unit === "min" || unit === "m" ? 6e4 : unit === "s" ? 1e3 : 1);
+	return Number.isFinite(milliseconds) ? Math.trunc(milliseconds) : fallback;
+}
+/**
+* Resolve the effective runtime timeouts.
+*
+* Precedence, highest first: explicit configuration, then the matching
+* `SMRT_PG_*` environment variable, then {@link DEFAULT_POSTGRES_TIMEOUTS}.
+* A parameter already present in the connection URL beats all three, but that
+* is enforced where the URL is written ({@link applyPostgresTimeoutsToUrl}) —
+* an operator who spelled a timeout into the DSN keeps it.
+*
+* @param config - Timeouts from configuration
+* @param env - Environment to read (defaults to `process.env`)
+* @returns Timeouts in milliseconds
+*/
+function resolvePostgresTimeouts(config = {}, env) {
+	const environment = env ?? (typeof process !== "undefined" ? process.env : {});
+	const resolve = (key, fallback) => parsePostgresTimeoutMs(config[key] ?? environment[POSTGRES_TIMEOUT_ENV_VARS[key]], fallback);
+	return {
+		connectionTimeoutMs: resolve("connectionTimeout", DEFAULT_POSTGRES_TIMEOUTS.connectionTimeoutMs),
+		statementTimeoutMs: resolve("statementTimeout", DEFAULT_POSTGRES_TIMEOUTS.statementTimeoutMs),
+		idleInTransactionSessionTimeoutMs: resolve("idleInTransactionSessionTimeout", DEFAULT_POSTGRES_TIMEOUTS.idleInTransactionSessionTimeoutMs),
+		lockTimeoutMs: resolve("lockTimeout", DEFAULT_POSTGRES_TIMEOUTS.lockTimeoutMs)
+	};
+}
+/**
+* Does this configuration open a PostgreSQL connection?
+*
+* Deliberately narrower than `detectEngine()` from the DDL module: that helper
+* answers "which dialect do I generate SQL in" and folds `json` into `duckdb`,
+* while this one answers "may I rewrite this URL", which must be false for
+* every non-PostgreSQL adapter and must not pull the DDL strategy singletons
+* into the connection path.
+*/
+function isPostgresTarget(url, type) {
+	const normalized = typeof type === "string" ? type.trim().toLowerCase() : "";
+	if (normalized) {
+		if (normalized === "postgres" || normalized === "postgresql" || normalized === "pg") return true;
+		return false;
+	}
+	const normalizedUrl = (url ?? "").toLowerCase();
+	return normalizedUrl.startsWith("postgres://") || normalizedUrl.startsWith("postgresql://");
+}
+/**
+* Write the session timeout parameters into a PostgreSQL connection URL.
+*
+* Parameters already present are left exactly as they are — an operator who
+* put `statement_timeout` in the DSN configured it on purpose, and the
+* per-parameter granularity means overriding one does not surrender the other
+* two to `pg`'s unbounded defaults.
+*
+* The DSN is edited by **appending**, never by re-serializing. Everything the
+* caller wrote — scheme, userinfo, host, path, and the existing query substring
+* byte for byte — is copied through, and only the missing parameters are added
+* after it. `URLSearchParams` is used to *read* which parameters are already
+* present; writing through it would hand `pg` a re-encoded DSN (`%20` becoming
+* `+`, parameters reordered) that is merely equivalent rather than identical,
+* which is not this function's business. The emitted values are bare digits, so
+* appending needs no encoding of its own.
+*
+* @param url - PostgreSQL connection URL
+* @param timeouts - Resolved timeouts
+* @returns The URL with the missing timeout parameters appended (the same
+*   string when all three were already present)
+*/
+function applyPostgresTimeoutsToUrl(url, timeouts) {
+	const fragmentStart = url.indexOf("#");
+	const fragment = fragmentStart === -1 ? "" : url.slice(fragmentStart);
+	const withoutFragment = fragmentStart === -1 ? url : url.slice(0, fragmentStart);
+	const queryStart = withoutFragment.indexOf("?");
+	const base = queryStart === -1 ? withoutFragment : withoutFragment.slice(0, queryStart);
+	const query = queryStart === -1 ? "" : withoutFragment.slice(queryStart + 1);
+	const present = new URLSearchParams(query);
+	const additions = [];
+	for (const [key, param] of Object.entries(URL_TIMEOUT_PARAMS)) {
+		if (present.has(param)) continue;
+		additions.push(`${param}=${Math.max(0, Math.trunc(timeouts[key]))}`);
+	}
+	if (additions.length === 0) return url;
+	return `${base}?${query}${query.length > 0 ? "&" : ""}${additions.join("&")}${fragment}`;
+}
+/**
+* Bound a runtime database configuration before it reaches `getDatabase()`.
+*
+* Non-PostgreSQL configurations pass through unchanged — the same reference,
+* so SQLite/DuckDB/JSON callers pay nothing and no file path is ever rewritten
+* — except that a stray `timeouts` key is stripped on every engine, because it
+* is SMRT configuration and never an adapter option.
+*
+* For PostgreSQL the returned object carries a URL with the three session
+* timeouts and a `connectionTimeoutMillis` pool option. Callers that derive a
+* `dbid` from the URL must derive it from the **returned** URL: two configs
+* that differ only in their timeouts are different pools, and every call site
+* applying the same deterministic rewrite is what keeps them one pool when the
+* timeouts match.
+*
+* A PostgreSQL configuration with no `url` — discrete `host`/`port`/`database`
+* fields, or a bare `{ type: 'postgres' }` that lets the adapter read
+* `HAVE_SQL_URL`/`SQLOO_URL` — has nowhere to carry the session parameters and
+* receives only `connectionTimeoutMillis`. Reproducing the adapter's own
+* environment precedence here to synthesize a URL would fork it; pass the URL
+* through the config (or set the `SMRT_PG_*` variables on a config that does
+* carry one) to get the session timeouts.
+*
+* The `timeouts` key is consumed here and not forwarded — `@happyvertical/sql`
+* would ignore it, and leaving it in the options object would make it look
+* like a supported adapter option.
+*
+* Rewriting the URL also changes the SDK's own pool cache key for call sites
+* that pass no `dbid`, so a consumer that separately calls `getDatabase()` with
+* the same raw URL no longer shares SMRT's pool. Consumers that want one pool
+* should hand SMRT the `DatabaseInterface`, not the same URL.
+*
+* @param config - Database configuration bound for `getDatabase()`
+* @param env - Environment to read (defaults to `process.env`)
+* @returns Configuration with runtime timeouts applied
+*/
+function applyPostgresRuntimeTimeouts(config, env) {
+	const { timeouts: configuredTimeouts, ...rest } = config;
+	if (!isPostgresTarget(config.url, config.type)) return configuredTimeouts === void 0 ? config : rest;
+	const timeouts = resolvePostgresTimeouts(configuredTimeouts, env);
+	return {
+		...rest,
+		...config.url ? { url: applyPostgresTimeoutsToUrl(config.url, timeouts) } : {},
+		connectionTimeoutMillis: timeouts.connectionTimeoutMs
+	};
+}
+//#endregion
+export { DEFAULT_POSTGRES_TIMEOUTS, POSTGRES_TIMEOUT_ENV_VARS, applyPostgresRuntimeTimeouts, applyPostgresTimeoutsToUrl, isPostgresTarget, parsePostgresTimeoutMs, resolvePostgresTimeouts };
+
+//# sourceMappingURL=postgres-timeouts.js.map

package/dist/postgres-timeouts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-timeouts.js","names":[],"sources":["../src/postgres-timeouts.ts"],"sourcesContent":["/**\n * Runtime PostgreSQL timeout defaults for every pool SMRT constructs.\n *\n * `@happyvertical/sql` builds its pool as `new Pool({ connectionString, max })`\n * and nothing else, so an un-configured deployment inherits `pg`'s unbounded\n * defaults: `pool.connect()` waits forever once the pool is exhausted, a\n * runaway query holds its client indefinitely, and a request-scoped transaction\n * that stalls mid-flight holds its locks until the process dies (#2377).\n *\n * This module resolves a bounded set of timeouts and applies them at pool\n * construction. Three of them ride the connection URL: `pg` lifts\n * `statement_timeout`, `lock_timeout`, and `idle_in_transaction_session_timeout`\n * out of the connection string's query parameters and sends them in the startup\n * packet, so they are session defaults on **every** client the pool opens,\n * including ones opened long after startup. The fourth, the connection\n * acquisition timeout, is a `pg` *pool* option with no connection-string\n * spelling; it is emitted as `connectionTimeoutMillis` on the options object\n * passed to `getDatabase()`, where `resolvePostgresConfig()` currently drops it.\n * It becomes live with no change here once the SDK forwards pool options\n * (happyvertical/sdk#1204).\n *\n * Scope: this is the *runtime* pool only. `smrt db:migrate` opens its own\n * connection through `@happyvertical/sql` directly and bounds its statements\n * with `SET LOCAL lock_timeout` / `statement_timeout` from\n * `migrations.postgres.*` (#2362); a migration therefore keeps its own, larger\n * budget even when it runs against a database whose runtime pool is bounded\n * here. The two read the same way on purpose — same string units, same\n * \"unparseable falls back to the documented default\" rule.\n *\n * @module\n */\n\n/**\n * Runtime PostgreSQL timeouts, as accepted from configuration.\n *\n * Every value is either a number of milliseconds or a duration string with an\n * `ms`, `s`, `min`/`m`, or `h` suffix — the spelling\n * `migrations.postgres.lockTimeout` already uses (`'30s'`). `0` means\n * *disabled*, which is PostgreSQL's own semantic for the three server-side\n * timeouts and `pg`'s semantic for the connection timeout (\"wait forever\");\n * it is emitted explicitly so it overrides a server-side default rather than\n * silently inheriting one.\n *\n * @example\n * ```typescript\n * const db = await resolveDatabase({\n *   type: 'postgres',\n *   url: process.env.DATABASE_URL,\n *   timeouts: { statementTimeout: '10s', lockTimeout: '2s' },\n * });\n * ```\n */\nexport interface PostgresTimeoutConfig {\n  /**\n   * Milliseconds to wait for a pool client before failing the acquisition.\n   *\n   * Bounds `pool.connect()`, whose `pg` default of `0` waits forever — the\n   * failure mode where one runaway query silently converts into a hung request\n   * queue. Emitted as `connectionTimeoutMillis`.\n   *\n   * @default '10s'\n   */\n  connectionTimeout?: string | number;\n\n  /**\n   * Session `statement_timeout`: the ceiling on a single statement.\n   *\n   * @default '30s'\n   */\n  statementTimeout?: string | number;\n\n  /**\n   * Session `idle_in_transaction_session_timeout`: the ceiling on an open\n   * transaction that is not currently executing a statement. This is the one\n   * that releases locks held by a request that died between statements.\n   *\n   * @default '60s'\n   */\n  idleInTransactionSessionTimeout?: string | number;\n\n  /**\n   * Session `lock_timeout`: the ceiling on waiting for a lock.\n   *\n   * @default '10s'\n   */\n  lockTimeout?: string | number;\n}\n\n/**\n * Timeouts resolved to milliseconds, ready to emit.\n */\nexport interface ResolvedPostgresTimeouts {\n  connectionTimeoutMs: number;\n  statementTimeoutMs: number;\n  idleInTransactionSessionTimeoutMs: number;\n  lockTimeoutMs: number;\n}\n\n/**\n * Defaults applied to every runtime PostgreSQL pool.\n *\n * Chosen to bound the failure modes in #2377 without truncating legitimate\n * request work: a web request that needs more than 30 s of server time or\n * holds a transaction open for more than a minute is the pathology these\n * bound, not the workload. Long-running maintenance does not run on this pool\n * — `db:migrate` carries its own budget (#2362) — and any deployment that\n * disagrees raises or disables the value per key.\n */\nexport const DEFAULT_POSTGRES_TIMEOUTS: ResolvedPostgresTimeouts = {\n  connectionTimeoutMs: 10_000,\n  statementTimeoutMs: 30_000,\n  idleInTransactionSessionTimeoutMs: 60_000,\n  lockTimeoutMs: 10_000,\n};\n\n/**\n * Environment variable read for each timeout when configuration does not set\n * it.\n *\n * Deployments that only ever hand SMRT a `DATABASE_URL` (SvelteKit runtime\n * config, container env, serverless) have no object to put a `timeouts` key on,\n * so the environment is the configuration surface that actually reaches them.\n */\nexport const POSTGRES_TIMEOUT_ENV_VARS = {\n  connectionTimeout: 'SMRT_PG_CONNECTION_TIMEOUT',\n  statementTimeout: 'SMRT_PG_STATEMENT_TIMEOUT',\n  idleInTransactionSessionTimeout: 'SMRT_PG_IDLE_IN_TRANSACTION_TIMEOUT',\n  lockTimeout: 'SMRT_PG_LOCK_TIMEOUT',\n} as const satisfies Record<keyof PostgresTimeoutConfig, string>;\n\n/**\n * PostgreSQL connection-string parameters that carry a session timeout.\n *\n * `pg` reads exactly these three out of the connection string and puts them in\n * the startup packet (`Client.getStartupConf`), which is why the URL is the\n * delivery mechanism: the settings then apply to every client the pool opens,\n * not just the first, with no per-checkout `SET` round trip.\n */\nconst URL_TIMEOUT_PARAMS = {\n  statementTimeoutMs: 'statement_timeout',\n  idleInTransactionSessionTimeoutMs: 'idle_in_transaction_session_timeout',\n  lockTimeoutMs: 'lock_timeout',\n} as const;\n\n/**\n * Parse a PostgreSQL timeout expressed as milliseconds or as the duration\n * string used in `smrt.config.js` into milliseconds.\n *\n * Accepts a bare number (milliseconds) or a number with an `ms`, `s`, `min`,\n * `m`, or `h` suffix. Returns `fallback` for `undefined`, empty, or\n * unparseable input so a typo degrades to the documented default instead of\n * silently disabling the timeout it was meant to impose.\n *\n * This is the single implementation behind both timeout surfaces: the\n * migration tracker re-exports it as the public\n * `@happyvertical/smrt-core/migrations` symbol (#2362), so a runtime `timeouts`\n * config and `migrations.postgres.*` are parsed by the same function and cannot\n * drift. This module deliberately imports nothing, which is what lets the\n * migration path depend on it without dragging anything into the connection\n * path.\n *\n * @param value - Millisecond count or duration string\n * @param fallback - Value returned for missing or unparseable input\n * @returns Timeout in milliseconds\n */\nexport function parsePostgresTimeoutMs(\n  value: string | number | undefined,\n  fallback: number,\n): number {\n  if (typeof value === 'number') {\n    return Number.isFinite(value) && value >= 0 ? Math.trunc(value) : fallback;\n  }\n\n  if (typeof value !== 'string' || value.trim().length === 0) {\n    return fallback;\n  }\n\n  const match = /^\\s*(\\d+(?:\\.\\d+)?)\\s*(ms|s|min|m|h)?\\s*$/i.exec(value);\n  if (!match) {\n    return fallback;\n  }\n\n  const amount = Number.parseFloat(match[1]);\n  const unit = (match[2] ?? 'ms').toLowerCase();\n  const multiplier =\n    unit === 'h'\n      ? 3_600_000\n      : unit === 'min' || unit === 'm'\n        ? 60_000\n        : unit === 's'\n          ? 1000\n          : 1;\n\n  // The regex admits an arbitrarily long digit run, so `parseFloat` — and the\n  // unit multiplication after it — can overflow to `Infinity`. That is\n  // unparseable input, not a timeout: emitted into a URL parameter or a pool\n  // option it fails connection setup somewhere far from the typo that caused\n  // it. The numeric branch above already refuses non-finite input; this keeps\n  // the string branch honest to the same contract.\n  const milliseconds = amount * multiplier;\n  return Number.isFinite(milliseconds) ? Math.trunc(milliseconds) : fallback;\n}\n\n/**\n * Resolve the effective runtime timeouts.\n *\n * Precedence, highest first: explicit configuration, then the matching\n * `SMRT_PG_*` environment variable, then {@link DEFAULT_POSTGRES_TIMEOUTS}.\n * A parameter already present in the connection URL beats all three, but that\n * is enforced where the URL is written ({@link applyPostgresTimeoutsToUrl}) —\n * an operator who spelled a timeout into the DSN keeps it.\n *\n * @param config - Timeouts from configuration\n * @param env - Environment to read (defaults to `process.env`)\n * @returns Timeouts in milliseconds\n */\nexport function resolvePostgresTimeouts(\n  config: PostgresTimeoutConfig = {},\n  env?: Record<string, string | undefined>,\n): ResolvedPostgresTimeouts {\n  // Read `process.env` lazily rather than through a default parameter, which\n  // would dereference `process` on every call — including the SQLite ones that\n  // never need it — in whatever environment this module is loaded.\n  const environment =\n    env ?? (typeof process !== 'undefined' ? process.env : {});\n  const resolve = (\n    key: keyof PostgresTimeoutConfig,\n    fallback: number,\n  ): number =>\n    parsePostgresTimeoutMs(\n      config[key] ?? environment[POSTGRES_TIMEOUT_ENV_VARS[key]],\n      fallback,\n    );\n\n  return {\n    connectionTimeoutMs: resolve(\n      'connectionTimeout',\n      DEFAULT_POSTGRES_TIMEOUTS.connectionTimeoutMs,\n    ),\n    statementTimeoutMs: resolve(\n      'statementTimeout',\n      DEFAULT_POSTGRES_TIMEOUTS.statementTimeoutMs,\n    ),\n    idleInTransactionSessionTimeoutMs: resolve(\n      'idleInTransactionSessionTimeout',\n      DEFAULT_POSTGRES_TIMEOUTS.idleInTransactionSessionTimeoutMs,\n    ),\n    lockTimeoutMs: resolve(\n      'lockTimeout',\n      DEFAULT_POSTGRES_TIMEOUTS.lockTimeoutMs,\n    ),\n  };\n}\n\n/**\n * Does this configuration open a PostgreSQL connection?\n *\n * Deliberately narrower than `detectEngine()` from the DDL module: that helper\n * answers \"which dialect do I generate SQL in\" and folds `json` into `duckdb`,\n * while this one answers \"may I rewrite this URL\", which must be false for\n * every non-PostgreSQL adapter and must not pull the DDL strategy singletons\n * into the connection path.\n */\nexport function isPostgresTarget(url?: string, type?: string): boolean {\n  const normalized = typeof type === 'string' ? type.trim().toLowerCase() : '';\n  if (normalized) {\n    if (\n      normalized === 'postgres' ||\n      normalized === 'postgresql' ||\n      normalized === 'pg'\n    ) {\n      return true;\n    }\n    // An explicit non-PostgreSQL type wins over a URL that merely looks like\n    // one; the adapter that will actually run is the one named here. An empty\n    // or whitespace `type` is not an answer, so it falls through to the URL.\n    return false;\n  }\n\n  const normalizedUrl = (url ?? '').toLowerCase();\n  return (\n    normalizedUrl.startsWith('postgres://') ||\n    normalizedUrl.startsWith('postgresql://')\n  );\n}\n\n/**\n * Write the session timeout parameters into a PostgreSQL connection URL.\n *\n * Parameters already present are left exactly as they are — an operator who\n * put `statement_timeout` in the DSN configured it on purpose, and the\n * per-parameter granularity means overriding one does not surrender the other\n * two to `pg`'s unbounded defaults.\n *\n * The DSN is edited by **appending**, never by re-serializing. Everything the\n * caller wrote — scheme, userinfo, host, path, and the existing query substring\n * byte for byte — is copied through, and only the missing parameters are added\n * after it. `URLSearchParams` is used to *read* which parameters are already\n * present; writing through it would hand `pg` a re-encoded DSN (`%20` becoming\n * `+`, parameters reordered) that is merely equivalent rather than identical,\n * which is not this function's business. The emitted values are bare digits, so\n * appending needs no encoding of its own.\n *\n * @param url - PostgreSQL connection URL\n * @param timeouts - Resolved timeouts\n * @returns The URL with the missing timeout parameters appended (the same\n *   string when all three were already present)\n */\nexport function applyPostgresTimeoutsToUrl(\n  url: string,\n  timeouts: ResolvedPostgresTimeouts,\n): string {\n  const fragmentStart = url.indexOf('#');\n  const fragment = fragmentStart === -1 ? '' : url.slice(fragmentStart);\n  const withoutFragment =\n    fragmentStart === -1 ? url : url.slice(0, fragmentStart);\n  const queryStart = withoutFragment.indexOf('?');\n  const base =\n    queryStart === -1 ? withoutFragment : withoutFragment.slice(0, queryStart);\n  const query = queryStart === -1 ? '' : withoutFragment.slice(queryStart + 1);\n  const present = new URLSearchParams(query);\n\n  const additions: string[] = [];\n  for (const [key, param] of Object.entries(URL_TIMEOUT_PARAMS) as [\n    keyof typeof URL_TIMEOUT_PARAMS,\n    string,\n  ][]) {\n    if (present.has(param)) continue;\n    additions.push(`${param}=${Math.max(0, Math.trunc(timeouts[key]))}`);\n  }\n\n  if (additions.length === 0) {\n    return url;\n  }\n\n  const separator = query.length > 0 ? '&' : '';\n  return `${base}?${query}${separator}${additions.join('&')}${fragment}`;\n}\n\n/**\n * Options object accepted and returned by\n * {@link applyPostgresRuntimeTimeouts}.\n */\nexport interface PostgresTimeoutAwareConfig {\n  url?: string;\n  type?: string;\n  /** Runtime timeout overrides for this connection. */\n  timeouts?: PostgresTimeoutConfig;\n  /**\n   * `pg` pool option emitted for PostgreSQL configurations. Present on the\n   * result, not on the input.\n   */\n  connectionTimeoutMillis?: number;\n  [key: string]: unknown;\n}\n\n/**\n * Bound a runtime database configuration before it reaches `getDatabase()`.\n *\n * Non-PostgreSQL configurations pass through unchanged — the same reference,\n * so SQLite/DuckDB/JSON callers pay nothing and no file path is ever rewritten\n * — except that a stray `timeouts` key is stripped on every engine, because it\n * is SMRT configuration and never an adapter option.\n *\n * For PostgreSQL the returned object carries a URL with the three session\n * timeouts and a `connectionTimeoutMillis` pool option. Callers that derive a\n * `dbid` from the URL must derive it from the **returned** URL: two configs\n * that differ only in their timeouts are different pools, and every call site\n * applying the same deterministic rewrite is what keeps them one pool when the\n * timeouts match.\n *\n * A PostgreSQL configuration with no `url` — discrete `host`/`port`/`database`\n * fields, or a bare `{ type: 'postgres' }` that lets the adapter read\n * `HAVE_SQL_URL`/`SQLOO_URL` — has nowhere to carry the session parameters and\n * receives only `connectionTimeoutMillis`. Reproducing the adapter's own\n * environment precedence here to synthesize a URL would fork it; pass the URL\n * through the config (or set the `SMRT_PG_*` variables on a config that does\n * carry one) to get the session timeouts.\n *\n * The `timeouts` key is consumed here and not forwarded — `@happyvertical/sql`\n * would ignore it, and leaving it in the options object would make it look\n * like a supported adapter option.\n *\n * Rewriting the URL also changes the SDK's own pool cache key for call sites\n * that pass no `dbid`, so a consumer that separately calls `getDatabase()` with\n * the same raw URL no longer shares SMRT's pool. Consumers that want one pool\n * should hand SMRT the `DatabaseInterface`, not the same URL.\n *\n * @param config - Database configuration bound for `getDatabase()`\n * @param env - Environment to read (defaults to `process.env`)\n * @returns Configuration with runtime timeouts applied\n */\nexport function applyPostgresRuntimeTimeouts(\n  config: PostgresTimeoutAwareConfig,\n  env?: Record<string, string | undefined>,\n): PostgresTimeoutAwareConfig {\n  const { timeouts: configuredTimeouts, ...rest } = config;\n\n  if (!isPostgresTarget(config.url, config.type)) {\n    return configuredTimeouts === undefined ? config : rest;\n  }\n\n  const timeouts = resolvePostgresTimeouts(configuredTimeouts, env);\n\n  return {\n    ...rest,\n    ...(config.url\n      ? { url: applyPostgresTimeoutsToUrl(config.url, timeouts) }\n      : {}),\n    connectionTimeoutMillis: timeouts.connectionTimeoutMs,\n  };\n}\n"],"mappings":"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"}

package/dist/query-bounds.d.ts

@@ -0,0 +1,97 @@
+import { ValidationError } from './errors';
+/**
+ * Page size a generated list surface uses when the caller supplies none.
+ *
+ * Matches the value the REST and SvelteKit generators already hard-coded, so
+ * adopting the shared parser is not a behavior change for callers that omit
+ * `limit`.
+ */
+export declare const DEFAULT_LIST_LIMIT = 50;
+/**
+ * Largest page a generated list surface will serve.
+ *
+ * Matches the cap `MCPGenerator` already applied in-process, now enforced on
+ * every generated surface rather than one of them.
+ */
+export declare const MAX_LIST_LIMIT = 1000;
+/**
+ * A `limit`/`offset` value that cannot be honored.
+ *
+ * Extends `ValidationError` so the retry classifier never retries it, and
+ * carries `status`/`publicMessage` so `normalizeTypedHttpError()` renders it as
+ * a structured 400 instead of letting a caller typo become a 500.
+ */
+export declare class QueryBoundsError extends ValidationError {
+    readonly status = 400;
+    readonly publicMessage: string;
+    constructor(message: string, code?: string, details?: Record<string, unknown>);
+}
+/**
+ * An `orderBy` term that cannot be honored (#2367).
+ *
+ * `orderBy` reaches SQL in the identifier position, and until this rail existed
+ * it was checked only against `/^[a-zA-Z0-9_]+$/` — so an unknown column
+ * produced a driver error and a *sensitive* column produced a working ordering
+ * oracle: `?orderBy=api_secret&limit=1` reveals the extreme value of a secret
+ * one request at a time, even though the column itself is never serialized.
+ * `where` and `select` have rejected sensitive fields since #1540/#1902; this
+ * is the same rail for the third identifier-position input.
+ */
+export declare class QueryOrderByError extends ValidationError {
+    readonly status = 400;
+    readonly publicMessage: string;
+    constructor(message: string, publicMessage: string, code?: string, details?: Record<string, unknown>);
+}
+/**
+ * Options for {@link resolveListLimit} / {@link resolveListOffset}.
+ */
+export interface ListBoundOptions {
+    /** Value used when the input is absent (`null`, `undefined`, or `''`). */
+    defaultValue?: number;
+    /** Upper bound; larger values are clamped down to it. Omit for none. */
+    maxValue?: number;
+    /** Parameter name used in the rejection message. */
+    parameterName?: string;
+}
+/**
+ * Resolve a page size from untrusted input: default when absent, rejected when
+ * malformed, clamped when oversized.
+ *
+ * @throws {QueryBoundsError} when the input is not a non-negative integer
+ */
+export declare function resolveListLimit(raw: unknown, options?: ListBoundOptions): number;
+/**
+ * Resolve a page offset from untrusted input.
+ *
+ * Unbounded above by default: an offset past the end of the table returns an
+ * empty page, and capping it would silently serve the wrong page instead.
+ *
+ * @throws {QueryBoundsError} when the input is not a non-negative integer
+ */
+export declare function resolveListOffset(raw: unknown, options?: ListBoundOptions): number;
+/**
+ * Deterministic default ordering for a generated list page.
+ *
+ * `LIMIT`/`OFFSET` without `ORDER BY` is not pagination: PostgreSQL may return
+ * rows in any order and is free to choose a different one per query, so page 2
+ * can repeat or skip rows from page 1. `created_at DESC` alone is not enough
+ * either — rows sharing a timestamp still tie — so the primary key follows as a
+ * total-order tiebreak.
+ *
+ * The index that makes this ordering cheap is #2363.
+ */
+export declare const DEFAULT_LIST_ORDER_BY: readonly string[];
+/**
+ * Deterministic default ordering for a model whose primary key may not be `id`.
+ *
+ * A class declaring `@field({ primaryKey: true })` on its own column has no
+ * synthetic `id` column — schema generation omits `id`/`slug`/`context` for
+ * custom-primary-key classes — so `ORDER BY ... id ASC` would name a column
+ * that does not exist and fail the whole page. The tiebreak therefore follows
+ * the declared key.
+ *
+ * @param primaryKeyField - the model's primary-key field name in SMRT (not
+ *   column) form; `collection.list()` maps it to the column
+ */
+export declare function buildDefaultListOrderBy(primaryKeyField?: string): string[];
+//# sourceMappingURL=query-bounds.d.ts.map

package/dist/query-bounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-bounds.d.ts","sourceRoot":"","sources":["../src/query-bounds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAE3C;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,OAAO,CAAC;AAEnC;;;;;;GAMG;AACH,qBAAa,gBAAiB,SAAQ,eAAe;IACnD,QAAQ,CAAC,MAAM,OAAO;IACtB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;gBAG7B,OAAO,EAAE,MAAM,EACf,IAAI,SAAyB,EAC7B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAMpC;AAED;;;;;;;;;;GAUG;AACH,qBAAa,iBAAkB,SAAQ,eAAe;IACpD,QAAQ,CAAC,MAAM,OAAO;IACtB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;gBAG7B,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,EACrB,IAAI,SAAqB,EACzB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAMpC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA2DD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,gBAAqB,GAC7B,MAAM,CAMR;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,gBAAqB,GAC7B,MAAM,CAMR;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAGlD,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,eAAe,SAAO,GAAG,MAAM,EAAE,CAExE"}