@adminiumjs/adapter-postgres 0.1.0-rc.1

package/dist/errors.js

@@ -0,0 +1,69 @@
+/**
+ * Driver error → typed `AdapterError` mapping — 05-introspection-engine.md §3.
+ * The Studio wizard and the `diagnostics-readout` widget map `code` to
+ * remediation copy, so the mapping here is the whole UX for failure states.
+ */
+import { AdapterError } from '@adminium/engine/adapter';
+const AUTH_SQLSTATES = new Set(['28P01', '28000']);
+const NETWORK_ERRNOS = new Set([
+    'ECONNREFUSED',
+    'ECONNRESET',
+    'ENOTFOUND',
+    'EHOSTUNREACH',
+    'ENETUNREACH',
+    'ETIMEDOUT',
+    'EPIPE',
+    'EAI_AGAIN',
+]);
+const TLS_CODES = new Set([
+    'SELF_SIGNED_CERT_IN_CHAIN',
+    'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+    'CERT_HAS_EXPIRED',
+    'DEPTH_ZERO_SELF_SIGNED_CERT',
+    'UNABLE_TO_GET_ISSUER_CERT_LOCALLY',
+    'HOSTNAME_MISMATCH',
+]);
+const HINTS = {
+    AUTH: 'check the username, password, and database name in the connection string',
+    HOST_UNREACHABLE: 'check the host/port and any firewall or IP allowlist — the database must accept connections from this server',
+    TLS: "check the sslmode in the DSN and the server's certificate chain",
+    PERMISSION: 'the connected role lacks the required privilege — grant it or use a different role',
+    TIMEOUT: 'the statement exceeded its time budget; retry or narrow the operation',
+};
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Coerce any driver/socket failure into the one allowed error type. */
+export function toAdapterError(error, context) {
+    if (error instanceof AdapterError)
+        return error;
+    const message = messageOf(error);
+    const code = typeof error === 'object' && error !== null && 'code' in error
+        ? String(error.code)
+        : '';
+    let mapped = 'UNKNOWN';
+    if (AUTH_SQLSTATES.has(code) || code === '3D000')
+        mapped = 'AUTH';
+    else if (code === '42501')
+        mapped = 'PERMISSION';
+    else if (code === '57014')
+        mapped = 'TIMEOUT';
+    else if (code === '42P01' || code === '42703')
+        mapped = 'SCHEMA_DRIFT';
+    else if (NETWORK_ERRNOS.has(code))
+        mapped = 'HOST_UNREACHABLE';
+    else if (TLS_CODES.has(code) ||
+        code.startsWith('ERR_TLS') ||
+        /\b(ssl|tls|certificate)\b/i.test(message)) {
+        mapped = 'TLS';
+    }
+    const options = {
+        detail: code.length > 0 ? `${code}: ${message}` : message,
+        cause: error,
+    };
+    const hint = HINTS[mapped];
+    if (hint !== undefined)
+        options.hint = hint;
+    return new AdapterError(mapped, `${context}: ${message}`, options);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,YAAY,EAAyB,MAAM,0BAA0B,CAAC;AAE/E,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;AACnD,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC;IAC7B,cAAc;IACd,YAAY;IACZ,WAAW;IACX,cAAc;IACd,aAAa;IACb,WAAW;IACX,OAAO;IACP,WAAW;CACZ,CAAC,CAAC;AACH,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC;IACxB,2BAA2B;IAC3B,iCAAiC;IACjC,kBAAkB;IAClB,6BAA6B;IAC7B,mCAAmC;IACnC,mBAAmB;CACpB,CAAC,CAAC;AAEH,MAAM,KAAK,GAA8C;IACvD,IAAI,EAAE,0EAA0E;IAChF,gBAAgB,EACd,8GAA8G;IAChH,GAAG,EAAE,iEAAiE;IACtE,UAAU,EAAE,oFAAoF;IAChG,OAAO,EAAE,uEAAuE;CACjF,CAAC;AAEF,SAAS,SAAS,CAAC,KAAc;IAC/B,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,cAAc,CAAC,KAAc,EAAE,OAAe;IAC5D,IAAI,KAAK,YAAY,YAAY;QAAE,OAAO,KAAK,CAAC;IAEhD,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;IACjC,MAAM,IAAI,GACR,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,IAAI,KAAK;QAC5D,CAAC,CAAC,MAAM,CAAE,KAA2B,CAAC,IAAI,CAAC;QAC3C,CAAC,CAAC,EAAE,CAAC;IAET,IAAI,MAAM,GAAqB,SAAS,CAAC;IACzC,IAAI,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,KAAK,OAAO;QAAE,MAAM,GAAG,MAAM,CAAC;SAC7D,IAAI,IAAI,KAAK,OAAO;QAAE,MAAM,GAAG,YAAY,CAAC;SAC5C,IAAI,IAAI,KAAK,OAAO;QAAE,MAAM,GAAG,SAAS,CAAC;SACzC,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,OAAO;QAAE,MAAM,GAAG,cAAc,CAAC;SAClE,IAAI,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,MAAM,GAAG,kBAAkB,CAAC;SAC1D,IACH,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC;QACnB,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;QAC1B,4BAA4B,CAAC,IAAI,CAAC,OAAO,CAAC,EAC1C,CAAC;QACD,MAAM,GAAG,KAAK,CAAC;IACjB,CAAC;IAED,MAAM,OAAO,GAAsD;QACjE,MAAM,EAAE,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC,OAAO;QACzD,KAAK,EAAE,KAAK;KACb,CAAC;IACF,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IAC3B,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAC5C,OAAO,IAAI,YAAY,CAAC,MAAM,EAAE,GAAG,OAAO,KAAK,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC;AACrE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+import { type AdapterProvider, type AdapterRegistry, type CapabilityProbeResult, type CollectStatsOptions, type ColumnSampleOptions, type ConnectionConfig, type ConnectionRole, type DatabaseAdapter, type DatabaseModel, type Dialect, type FilterSpec, type IntrospectOptions, type MutationResult, type MutationSpec, type QueryResult, type QuerySpec, type Row, type SampleOptions, type StatsResult, type TableRef, type TestResult } from '@adminium/engine/adapter';
+export declare class PostgresAdapter<Role extends ConnectionRole = ConnectionRole> implements DatabaseAdapter<Role> {
+    #private;
+    readonly dialect: Dialect;
+    readonly capabilities: {
+        hasEnums: boolean;
+        hasFKs: boolean;
+        hasSchemas: boolean;
+        hasComments: boolean;
+        hasChecks: boolean;
+        hasRLS: boolean;
+        hasMaterializedViews: boolean;
+        hasRowEstimates: boolean;
+        supportsStatementTimeout: boolean;
+        supportsReturning: boolean;
+        maxIdentifierLength: number;
+    };
+    readonly role: Role;
+    constructor(role: Role);
+    /** Lazy pool — no socket is opened until the first query. */
+    connect(config: ConnectionConfig<Role>): Promise<void>;
+    test(): Promise<TestResult>;
+    /** Runs on every connect/test; results persist on the connection row. */
+    probeCapabilities(): Promise<CapabilityProbeResult>;
+    /** SCHEMA ONLY — reads `pg_catalog` exclusively (05 §10). */
+    introspect(this: DatabaseAdapter<'introspect'>, opts?: IntrospectOptions): Promise<DatabaseModel>;
+    count(this: DatabaseAdapter<'data'>, _table: TableRef, _filter?: FilterSpec, _opts?: {
+        cap?: number;
+    }): Promise<{
+        value: number;
+        capped: boolean;
+    }>;
+    sample(this: DatabaseAdapter<'data'>, _table: TableRef, _opts: SampleOptions): Promise<Row[]>;
+    sampleColumn(this: DatabaseAdapter<'data'>, _table: TableRef, _column: string, _opts: ColumnSampleOptions): Promise<unknown[]>;
+    query(this: DatabaseAdapter<'data'>, _spec: QuerySpec): Promise<QueryResult>;
+    mutate(this: DatabaseAdapter<'data'>, _spec: MutationSpec): Promise<MutationResult>;
+    /** Aggregate statistics for LLM enrichment (06 §4.2); sample-free by default. */
+    collectTableStats(this: DatabaseAdapter<'data'>, table: TableRef, opts?: CollectStatsOptions): Promise<StatsResult>;
+    /** Release the pool; idempotent. */
+    close(): Promise<void>;
+}
+/** What the server registers at boot (01-architecture.md §2.3.1). */
+export declare const postgresAdapter: AdapterProvider;
+/**
+ * Boot registration helper — `@adminium/server` calls `register()` once at
+ * startup; tests may pass their own registry instance.
+ */
+export declare function register(registry?: AdapterRegistry<AdapterProvider>): void;
+export { createQueryEngine } from './query-engine.js';
+export { interpretProbe, introspectPostgres, parseCheckEnum, POSTGRES_CAPABILITIES, PROBE_SQL, type CatalogExecutor, type CatalogRow, type IntrospectContext, type ProbeResult, } from './introspect.js';
+export { classifyDefault, mapPostgresType, type MappedType } from './type-map.js';
+export { collectPostgresStats, normalizePgDistinct, type StatsExecutor } from './stats.js';
+export { PG_MAX_IDENTIFIER_LENGTH, postgresSerializers, quoteIdentifier, } from './serialization.js';
+export { toAdapterError } from './errors.js';
+/** @deprecated M0 scaffold export; kept so early imports keep compiling. */
+export declare const PACKAGE_NAME = "@adminium/adapter-postgres";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,209 @@
+/**
+ * @adminium/adapter-postgres — the `pg`-driver implementation of the
+ * `DatabaseAdapter` contract (05-introspection-engine.md §3/§4.1, M3-T01).
+ *
+ * Scope in this milestone: connect/test/probeCapabilities, `introspect()`
+ * (schema only — never rows), the Kysely query-engine factory, and the boot
+ * registration helper. The data-role methods (`query`/`mutate`/`sample`/
+ * `count`) land with 05-T05 and currently reject with a typed `UNSUPPORTED`
+ * error after their role guard runs.
+ */
+import pg from 'pg';
+import { AdapterError, adapterRegistry, registerAdapter, } from '@adminium/engine/adapter';
+import { toAdapterError } from './errors.js';
+import { interpretProbe, introspectPostgres, POSTGRES_CAPABILITIES, PROBE_SQL, } from './introspect.js';
+import { createQueryEngine } from './query-engine.js';
+import { collectPostgresStats } from './stats.js';
+const INTROSPECT_POOL_MAX = 5;
+const DATA_POOL_MAX = 10;
+const DEFAULT_STATEMENT_TIMEOUT_MS = 15_000;
+export class PostgresAdapter {
+    dialect = 'postgres';
+    capabilities = { ...POSTGRES_CAPABILITIES };
+    role;
+    #pool = null;
+    #closed = false;
+    constructor(role) {
+        this.role = role;
+    }
+    /** Lazy pool — no socket is opened until the first query. */
+    async connect(config) {
+        if (config.role !== this.role) {
+            throw new AdapterError('PERMISSION', `connection config is branded "${config.role}" but this adapter instance is "${this.role}"`, { hint: 'the three logical connections are never interchangeable (01-architecture.md §3)' });
+        }
+        if (config.dsn === undefined || config.dsn.length === 0) {
+            throw new AdapterError('UNKNOWN', 'postgres connections require a DSN', {
+                hint: 'pass a postgres:// connection string; TLS is honored from sslmode',
+            });
+        }
+        const statementTimeoutMs = Math.floor(config.statementTimeoutMs ?? DEFAULT_STATEMENT_TIMEOUT_MS);
+        // Session setup on every new connection — 05 §4.1. Sent in the startup
+        // packet (`options`) rather than an on-connect `client.query()`: the pool
+        // hands a freshly-connected client to its pending waiter in the same
+        // ready-for-query tick as the 'connect' event, so a fire-and-forget setup
+        // query would still be in the client's queue when the waiter's query is
+        // pushed — pg 8.22 deprecates that (removed in pg@9). Startup options cost
+        // zero extra round trips and cannot race. Trade-offs: an explicit
+        // `options` overrides any `options=` in the user DSN (rare), and
+        // transaction-pooling pgbouncer rejects startup options (the previous
+        // per-connection SET was equally broken there).
+        const sessionOptions = `-c statement_timeout=${statementTimeoutMs}` +
+            (this.role === 'introspect'
+                ? ' -c lock_timeout=2s -c idle_in_transaction_session_timeout=10s'
+                : '');
+        const pool = new pg.Pool({
+            connectionString: config.dsn,
+            max: config.poolMax ?? (this.role === 'introspect' ? INTROSPECT_POOL_MAX : DATA_POOL_MAX),
+            options: sessionOptions,
+        });
+        // Surface idle-client failures as pool-level noise, not process crashes.
+        pool.on('error', () => {
+            /* mapped when the next query fails */
+        });
+        this.#pool = pool;
+        this.#closed = false;
+    }
+    #requirePool() {
+        if (this.#pool === null || this.#closed) {
+            throw new AdapterError('UNKNOWN', 'adapter is not connected — call connect() first');
+        }
+        return this.#pool;
+    }
+    async #query(sql) {
+        const pool = this.#requirePool();
+        try {
+            const result = await pool.query(sql);
+            return result.rows;
+        }
+        catch (error) {
+            throw toAdapterError(error, 'postgres query failed');
+        }
+    }
+    async #probe() {
+        const rows = await this.#query(PROBE_SQL);
+        return interpretProbe(rows[0] ?? {});
+    }
+    async test() {
+        const startedAt = Date.now();
+        try {
+            const probe = await this.#probe();
+            return {
+                ok: true,
+                latencyMs: Date.now() - startedAt,
+                serverVersion: probe.serverVersion,
+                currentUser: probe.roleName,
+                canWrite: !probe.readOnly,
+                ssl: probe.ssl,
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                latencyMs: Date.now() - startedAt,
+                serverVersion: null,
+                currentUser: null,
+                canWrite: false,
+                ssl: false,
+                error: toAdapterError(error, 'connection test failed'),
+            };
+        }
+    }
+    /** Runs on every connect/test; results persist on the connection row. */
+    async probeCapabilities() {
+        const probe = await this.#probe();
+        return {
+            capabilities: { ...POSTGRES_CAPABILITIES },
+            privileges: {
+                canReadSchema: true,
+                canRead: true,
+                canWrite: !probe.readOnly,
+                canDDL: probe.canCreate,
+            },
+            serverVersion: probe.serverVersion,
+            currentRole: { name: probe.roleName, readOnly: probe.readOnly },
+        };
+    }
+    /** SCHEMA ONLY — reads `pg_catalog` exclusively (05 §10). */
+    async introspect(opts) {
+        const self = this;
+        // Runtime guard behind the compile-time role brand (05 §3).
+        if (self.role !== 'introspect') {
+            throw new AdapterError('PERMISSION', 'introspect() is only available on the introspect-role instance');
+        }
+        const probe = await self.#probe();
+        return introspectPostgres(async (sql) => self.#query(sql), { connectionId: probe.databaseName, databaseName: probe.databaseName }, opts);
+    }
+    #guardDataRole(method) {
+        if (this.role !== 'data') {
+            throw new AdapterError('PERMISSION', `${method}() is only available on the data-role instance`, { hint: 'row-touching methods never run on the introspect connection (05 §10)' });
+        }
+        throw new AdapterError('UNSUPPORTED', `${method}() lands with 05-T05 (dynamic Kysely CRUD)`, {
+            hint: 'use createQueryEngine() for the CRUD query port in the meantime',
+        });
+    }
+    /* eslint-disable @typescript-eslint/no-unused-vars -- 05-T05 stubs: the
+       parameter lists must match the DatabaseAdapter contract exactly. */
+    async count(_table, _filter, _opts) {
+        return this.#guardDataRole('count');
+    }
+    async sample(_table, _opts) {
+        return this.#guardDataRole('sample');
+    }
+    async sampleColumn(_table, _column, _opts) {
+        return this.#guardDataRole('sampleColumn');
+    }
+    async query(_spec) {
+        return this.#guardDataRole('query');
+    }
+    async mutate(_spec) {
+        return this.#guardDataRole('mutate');
+    }
+    /* eslint-enable @typescript-eslint/no-unused-vars */
+    /** Aggregate statistics for LLM enrichment (06 §4.2); sample-free by default. */
+    async collectTableStats(table, opts) {
+        const self = this;
+        if (self.role !== 'data') {
+            throw new AdapterError('PERMISSION', 'collectTableStats() is only available on the data-role instance', { hint: 'statistics touch user rows and never run on the introspect connection (05 §10)' });
+        }
+        return collectPostgresStats((sql) => self.#query(sql), table, opts);
+    }
+    /** Release the pool; idempotent. */
+    async close() {
+        if (this.#pool === null || this.#closed)
+            return;
+        this.#closed = true;
+        const pool = this.#pool;
+        this.#pool = null;
+        await pool.end();
+    }
+}
+/** What the server registers at boot (01-architecture.md §2.3.1). */
+export const postgresAdapter = {
+    dialect: 'postgres',
+    async create(config) {
+        const adapter = new PostgresAdapter(config.role);
+        await adapter.connect(config);
+        return adapter;
+    },
+    createQueryEngine,
+};
+/**
+ * Boot registration helper — `@adminium/server` calls `register()` once at
+ * startup; tests may pass their own registry instance.
+ */
+export function register(registry = adapterRegistry) {
+    if (registry === adapterRegistry) {
+        registerAdapter(postgresAdapter);
+        return;
+    }
+    registry.register(postgresAdapter);
+}
+export { createQueryEngine } from './query-engine.js';
+export { interpretProbe, introspectPostgres, parseCheckEnum, POSTGRES_CAPABILITIES, PROBE_SQL, } from './introspect.js';
+export { classifyDefault, mapPostgresType } from './type-map.js';
+export { collectPostgresStats, normalizePgDistinct } from './stats.js';
+export { PG_MAX_IDENTIFIER_LENGTH, postgresSerializers, quoteIdentifier, } from './serialization.js';
+export { toAdapterError } from './errors.js';
+/** @deprecated M0 scaffold export; kept so early imports keep compiling. */
+export const PACKAGE_NAME = '@adminium/adapter-postgres';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/introspect.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Postgres introspection — 05-introspection-engine.md §4.1.
+ *
+ * Reads `pg_catalog`, not `information_schema` (too slow at 500 tables): a
+ * FIXED set of 7 set-based catalog queries regardless of table count, joined
+ * in memory. This module is executor-agnostic — `introspectPostgres` takes a
+ * `CatalogExecutor` (any `sql → rows` function) so the assembly logic is
+ * testable without the `pg` driver; `src/index.ts` wires it to the pool.
+ *
+ * THE "SCHEMA ONLY" INVARIANT (05 §10): every statement here references
+ * `pg_catalog.*` exclusively — no user table is ever touched during setup.
+ */
+import { type AdapterCapabilities, type DatabaseModel, type IntrospectOptions } from '@adminium/engine/adapter';
+export type CatalogRow = Record<string, unknown>;
+/** Any `sql → rows` runner (the pg pool in production, psql in the harness). */
+export type CatalogExecutor = (sql: string) => Promise<CatalogRow[]>;
+export interface IntrospectContext {
+    /** `adminium_connections` row id; falls back to the database name. */
+    connectionId: string;
+    /** `current_database()` — becomes `model.name`. */
+    databaseName: string;
+}
+/**
+ * Static dialect capabilities — 05 §2.1 (probe refines per-connection).
+ * Canonical values live in the engine's capability matrix (M9-T04) so the
+ * wizard's degradation copy and the adapter never disagree.
+ */
+export declare const POSTGRES_CAPABILITIES: AdapterCapabilities;
+/**
+ * Session probe. Read-only detection per the M3 workplan: recovery mode
+ * (`pg_is_in_recovery()`), the session default
+ * (`default_transaction_read_only`), or the role lacking CREATE on the
+ * database (`has_database_privilege`).
+ */
+export declare const PROBE_SQL = "\nSELECT current_setting('server_version') AS server_version,\n       current_user AS role_name,\n       pg_catalog.current_database() AS database_name,\n       pg_catalog.pg_is_in_recovery() AS in_recovery,\n       current_setting('default_transaction_read_only') AS default_read_only,\n       pg_catalog.has_database_privilege(pg_catalog.current_database(), 'CREATE') AS can_create,\n       COALESCE(\n         (SELECT s.ssl FROM pg_catalog.pg_stat_ssl s WHERE s.pid = pg_catalog.pg_backend_pid()),\n         false\n       ) AS ssl";
+export interface ProbeResult {
+    serverVersion: string;
+    roleName: string;
+    databaseName: string;
+    readOnly: boolean;
+    canCreate: boolean;
+    ssl: boolean;
+}
+/** Interpret one {@link PROBE_SQL} row (executor-agnostic, pure). */
+export declare function interpretProbe(row: CatalogRow): ProbeResult;
+/** Parse `col = ANY (ARRAY['a', 'b'])` / `col IN ('a','b')` check shapes. */
+export declare function parseCheckEnum(definition: string): {
+    column: string;
+    values: string[];
+} | null;
+/**
+ * Run the fixed catalog query set through `exec` and assemble the
+ * `DatabaseModel`. Schema only — never touches user rows.
+ */
+export declare function introspectPostgres(exec: CatalogExecutor, ctx: IntrospectContext, opts?: IntrospectOptions): Promise<DatabaseModel>;
+//# sourceMappingURL=introspect.d.ts.map

package/dist/introspect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"introspect.d.ts","sourceRoot":"","sources":["../src/introspect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAGL,KAAK,mBAAmB,EAExB,KAAK,aAAa,EAIlB,KAAK,iBAAiB,EAIvB,MAAM,0BAA0B,CAAC;AAQlC,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD,gFAAgF;AAChF,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;AAErE,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,YAAY,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,mBAEnC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,SAAS,0hBAUN,CAAC;AAEjB,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,GAAG,EAAE,OAAO,CAAC;CACd;AAED,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,GAAG,WAAW,CAY3D;AA8MD,6EAA6E;AAC7E,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,GACjB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAQ7C;AA8CD;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,eAAe,EACrB,GAAG,EAAE,iBAAiB,EACtB,IAAI,GAAE,iBAAsB,GAC3B,OAAO,CAAC,aAAa,CAAC,CAmVxB"}