@spine-event-engine/storage-postgres 2.0.0-snapshot.13

package/dist/postgres/table-initializer.js

@@ -0,0 +1,301 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { createHash } from "node:crypto";
+import { PostgresDataTypes } from "./data-type.js";
+import { PostgresRollbackErrors, PostgresStorageErrors, PostgresStorageSchemaError, PostgresTransactionErrors, } from "./errors.js";
+/**
+ * Prepares one PostgreSQL record-family table.
+ */
+export class PostgresTableInitializer {
+    lifecycle;
+    schema;
+    table;
+    customCreate;
+    #ready;
+    /**
+     * Creates a private initializer for one resolved PostgreSQL table.
+     *
+     * @param lifecycle Acquires clients and supplies the stable database lock identity.
+     * @param schema Names the resolved PostgreSQL schema.
+     * @param table Describes the canonical record-family layout.
+     * @param customCreate Optionally supplies caller-defined create-table SQL.
+     */
+    constructor(lifecycle, schema, table, customCreate) {
+        this.lifecycle = lifecycle;
+        this.schema = schema;
+        this.table = table;
+        this.customCreate = customCreate;
+    }
+    /**
+     * Prepares the table once.
+     *
+     * @returns Completion of initialization.
+     */
+    prepare() {
+        this.#ready ??= this.attempt().catch((error) => this.retry(error));
+        return this.#ready;
+    }
+    /**
+     * Retries initialization only after an admitted transaction conflict.
+     *
+     * @param error Initial table-preparation failure.
+     * @returns Completion of the retry attempt.
+     */
+    retry(error) {
+        if (!PostgresTransactionErrors.retryable(error))
+            throw PostgresStorageErrors.operation(error);
+        return this.attempt();
+    }
+    /**
+     * Creates and verifies the table inside one transaction.
+     *
+     * @returns Completion after commit.
+     */
+    async attempt() {
+        const client = await this.lifecycle.acquire();
+        let discard;
+        try {
+            await client.query("BEGIN");
+            await this.lock(client);
+            await client.query(this.customCreate?.() ?? this.create());
+            await this.verify(client);
+            await client.query("COMMIT");
+        }
+        catch (error) {
+            try {
+                await client.query("ROLLBACK");
+            }
+            catch {
+                discard = PostgresRollbackErrors.discard(error);
+            }
+            throw error;
+        }
+        finally {
+            client.release(discard);
+        }
+    }
+    /**
+     * Acquires the transaction lock for this physical table.
+     *
+     * @param client PostgreSQL transaction client.
+     * @returns PostgreSQL lock-query result.
+     */
+    lock(client) {
+        return client.query("SELECT pg_advisory_xact_lock($1)", [
+            PostgresLocks.key(this.lifecycle.lockIdentity ?? "", this.schema, this.table.tableName),
+        ]);
+    }
+    /**
+     * Builds the default idempotent table-creation statement.
+     *
+     * @returns Schema-qualified PostgreSQL DDL.
+     */
+    create() {
+        const columns = this.table.columns.map(PostgresSql.column).join(", ");
+        const primary = this.table.primaryKey.map(PostgresSql.identifier).join(", ");
+        const qualified = PostgresSql.qualified(this.schema, this.table.tableName);
+        return `CREATE TABLE IF NOT EXISTS ${qualified} (${columns}, PRIMARY KEY (${primary}))`;
+    }
+    /**
+     * Verifies columns, primary key, and unsupported unique constraints.
+     *
+     * @param client PostgreSQL transaction client.
+     * @returns Completion after catalog verification.
+     */
+    async verify(client) {
+        const columns = await PostgresCatalog.columns(client, this.schema, this.table.tableName);
+        PostgresCatalog.assertColumns(this.table.columns, columns);
+        const primary = await PostgresCatalog.primaryKey(client, this.schema, this.table.tableName);
+        PostgresCatalog.assertPrimary(this.table.primaryKey, primary);
+        PostgresCatalog.assertUnique(await PostgresCatalog.unique(client, this.schema, this.table.tableName));
+    }
+}
+const PostgresSql = Object.freeze({
+    /**
+     * Returns one safely quoted PostgreSQL identifier.
+     *
+     * @param value Identifier spelling.
+     * @returns Safely quoted identifier.
+     */
+    identifier(value) {
+        return `"${value.replaceAll('"', '""')}"`;
+    },
+    /**
+     * Builds one quoted schema-qualified table identifier.
+     *
+     * @param schema PostgreSQL schema name.
+     * @param table PostgreSQL table name.
+     * @returns Qualified table reference.
+     */
+    qualified(schema, table) {
+        return `${PostgresSql.identifier(schema)}.${PostgresSql.identifier(table)}`;
+    },
+    /**
+     * Renders one physical column declaration.
+     *
+     * @param column PostgreSQL column specification.
+     * @returns Column DDL fragment.
+     */
+    column(column) {
+        const nullable = column.nullable ? "" : " NOT NULL";
+        const fallback = column.defaultSql === undefined ? "" : ` DEFAULT ${column.defaultSql}`;
+        return `${PostgresSql.identifier(column.name)} ${column.postgresType}${nullable}${fallback}`;
+    },
+});
+const PostgresCatalog = Object.freeze({
+    /**
+     * Reads the ordered column catalog for one table.
+     *
+     * @param client PostgreSQL transaction client.
+     * @param schema PostgreSQL schema name.
+     * @param table PostgreSQL table name.
+     * @returns Catalog column rows.
+     */
+    async columns(client, schema, table) {
+        const result = await client.query("SELECT column_name, data_type, character_maximum_length, is_nullable, column_default " +
+            "FROM information_schema.columns WHERE table_schema=$1 AND table_name=$2 ORDER BY ordinal_position", [schema, table]);
+        return result.rows;
+    },
+    /**
+     * Reads the ordered primary-key catalog for one table.
+     *
+     * @param client PostgreSQL transaction client.
+     * @param schema PostgreSQL schema name.
+     * @param table PostgreSQL table name.
+     * @returns Primary-key column rows.
+     */
+    async primaryKey(client, schema, table) {
+        const result = await client.query("SELECT kcu.column_name, kcu.ordinal_position FROM information_schema.table_constraints tc " +
+            "JOIN information_schema.key_column_usage kcu USING (constraint_catalog, constraint_schema, constraint_name) " +
+            "WHERE tc.table_schema=$1 AND tc.table_name=$2 AND tc.constraint_type = 'PRIMARY KEY' " +
+            "ORDER BY kcu.ordinal_position", [schema, table]);
+        return result.rows;
+    },
+    /**
+     * Reads user-defined unique constraints for one table.
+     *
+     * @param client PostgreSQL transaction client.
+     * @param schema PostgreSQL schema name.
+     * @param table PostgreSQL table name.
+     * @returns Unique-constraint rows.
+     */
+    async unique(client, schema, table) {
+        const result = await client.query("SELECT tc.constraint_name, kcu.column_name, kcu.ordinal_position FROM information_schema.table_constraints tc " +
+            "JOIN information_schema.key_column_usage kcu USING (constraint_catalog, constraint_schema, constraint_name) " +
+            "WHERE tc.table_schema=$1 AND tc.table_name=$2 AND tc.constraint_type = 'UNIQUE' " +
+            "ORDER BY tc.constraint_name, kcu.ordinal_position", [schema, table]);
+        return result.rows;
+    },
+    /**
+     * Verifies the complete physical column set.
+     *
+     * @param expected Required column specifications.
+     * @param actual Catalog column rows.
+     */
+    assertColumns(expected, actual) {
+        if (actual.length !== expected.length)
+            PostgresCatalog.incompatible();
+        for (const expectedColumn of expected) {
+            const actualColumn = actual.find(({ column_name }) => column_name === expectedColumn.name);
+            if (actualColumn === undefined || !PostgresCatalog.sameColumn(expectedColumn, actualColumn))
+                PostgresCatalog.incompatible();
+        }
+    },
+    /**
+     * Verifies the ordered primary-key columns.
+     *
+     * @param expected Required primary-key column names.
+     * @param actual Catalog primary-key rows.
+     */
+    assertPrimary(expected, actual) {
+        if (actual.length !== expected.length ||
+            actual.some(({ column_name }, index) => column_name !== expected[index]))
+            PostgresCatalog.incompatible();
+    },
+    /**
+     * Rejects unexpected user-defined unique constraints.
+     *
+     * @param actual Catalog unique-constraint rows.
+     */
+    assertUnique(actual) {
+        if (actual.length > 0)
+            PostgresCatalog.incompatible();
+    },
+    /**
+     * Compares one expected column with its catalog row.
+     *
+     * @param expected Required column specification.
+     * @param actual Catalog column row.
+     * @returns Whether type, nullability, and default match.
+     */
+    sameColumn(expected, actual) {
+        return (PostgresCatalog.type(expected.postgresType, actual) &&
+            (actual.is_nullable === "YES") === expected.nullable &&
+            PostgresCatalog.default(expected.defaultSql) ===
+                PostgresCatalog.default(actual.column_default));
+    },
+    /**
+     * Compares one canonical DDL type with a catalog type.
+     *
+     * @param expected Canonical PostgreSQL DDL type name.
+     * @param actual Catalog column row.
+     * @returns Whether both describe the same PostgreSQL type.
+     */
+    type(expected, actual) {
+        if (expected === PostgresDataTypes.varchar512)
+            return actual.data_type === "character varying" && actual.character_maximum_length === 512;
+        if (expected === PostgresDataTypes.integer)
+            return actual.data_type === "integer";
+        return expected.toLowerCase() === actual.data_type.toLowerCase();
+    },
+    /**
+     * Normalizes a catalog or expected default expression.
+     *
+     * @param value Default expression.
+     * @returns Normalized expression or `null` when absent.
+     */
+    default(value) {
+        return value === undefined || value === null ? null : value.trim().toLowerCase();
+    },
+    /**
+     * Throws the stable incompatible-schema error.
+     *
+     * @returns This operation never returns.
+     */
+    incompatible() {
+        throw new PostgresStorageSchemaError("PostgreSQL table schema is incompatible.");
+    },
+});
+const PostgresLocks = Object.freeze({
+    /**
+     * Calculates the advisory lock key for one physical table.
+     *
+     * @param database Stable database connection identity.
+     * @param schema PostgreSQL schema name.
+     * @param table PostgreSQL table name.
+     * @returns Signed 64-bit advisory-lock key.
+     */
+    key(database, schema, table) {
+        return createHash("sha256")
+            .update("spine-postgres-table\u0000")
+            .update(database)
+            .update("\u0000")
+            .update(schema)
+            .update("\u0000")
+            .update(table)
+            .digest()
+            .readBigInt64BE();
+    },
+});
+//# sourceMappingURL=table-initializer.js.map

package/dist/postgres/table-initializer.js.map

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

package/dist/postgres/table-resolver.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Resolves PostgreSQL physical names for record families.
+ */
+export declare class PostgresTableResolver {
+    #private;
+    /**
+     * Sets an ungrouped record-family table name.
+     *
+     * @param recordType Names the record type.
+     * @param name Specifies the requested physical table name.
+     */
+    setRecordName(recordType: string, name: string): void;
+    /**
+     * Sets a grouped record-family table name.
+     *
+     * @param sourceType Names the source type.
+     * @param recordType Names the grouped record type.
+     * @param name Names the physical table.
+     */
+    setGroupName(sourceType: string, recordType: string, name: string): void;
+    /**
+     * Resolves one record-family physical name.
+     *
+     * @param sourceType Names the record source type.
+     * @param group Names the optional storage group.
+     * @param name Supplies an explicit physical name.
+     * @param recordType Names the grouped record type.
+     * @returns The validated PostgreSQL table identity.
+     */
+    resolve(sourceType: string, group: string | undefined, name?: string, recordType?: string): {
+        readonly tableName: string;
+    };
+    /**
+     * Registers one logical-to-physical table-name request.
+     *
+     * @param identity Stable logical record-family identity.
+     * @param name Requested physical table name.
+     */
+    private set;
+}
+//# sourceMappingURL=table-resolver.d.ts.map

package/dist/postgres/table-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table-resolver.d.ts","sourceRoot":"","sources":["../../src/postgres/table-resolver.ts"],"names":[],"mappings":"AAcA;;GAEG;AACH,qBAAa,qBAAqB;;IAKhC;;;;;OAKG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAIrD;;;;;;OAMG;IACH,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAIxE;;;;;;;;OAQG;IACH,OAAO,CACL,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,IAAI,CAAC,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,MAAM,GAClB;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE;IAmBjC;;;;;OAKG;IACH,OAAO,CAAC,GAAG;CASZ"}

package/dist/postgres/table-resolver.js

@@ -0,0 +1,225 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+/**
+ * Resolves PostgreSQL physical names for record families.
+ */
+export class PostgresTableResolver {
+    #names = new Map();
+    #resolved = new Map();
+    /**
+     * Sets an ungrouped record-family table name.
+     *
+     * @param recordType Names the record type.
+     * @param name Specifies the requested physical table name.
+     */
+    setRecordName(recordType, name) {
+        this.set(`record:${recordType}`, name);
+    }
+    /**
+     * Sets a grouped record-family table name.
+     *
+     * @param sourceType Names the source type.
+     * @param recordType Names the grouped record type.
+     * @param name Names the physical table.
+     */
+    setGroupName(sourceType, recordType, name) {
+        this.set(`group:${sourceType}\u0000${recordType}`, name);
+    }
+    /**
+     * Resolves one record-family physical name.
+     *
+     * @param sourceType Names the record source type.
+     * @param group Names the optional storage group.
+     * @param name Supplies an explicit physical name.
+     * @param recordType Names the grouped record type.
+     * @returns The validated PostgreSQL table identity.
+     */
+    resolve(sourceType, group, name, recordType) {
+        const identity = group === undefined
+            ? sourceType
+            : `${sourceType}\u0000${recordType ?? sourceType}\u0000${group}`;
+        const readable = name ??
+            (group === undefined
+                ? this.#names.get(`record:${sourceType}`)
+                : this.#names.get(`group:${sourceType}\u0000${recordType ?? sourceType}`)) ??
+            PostgresNames.default(sourceType, group, recordType);
+        const tableName = PostgresNames.physical(readable);
+        const previous = this.#resolved.get(tableName);
+        if (previous !== undefined && previous !== identity)
+            throw new Error(`PostgreSQL table name collides: ${tableName}`);
+        this.#resolved.set(tableName, identity);
+        return Object.freeze({ tableName });
+    }
+    /**
+     * Registers one logical-to-physical table-name request.
+     *
+     * @param identity Stable logical record-family identity.
+     * @param name Requested physical table name.
+     */
+    set(identity, name) {
+        const physical = PostgresNames.physical(name);
+        for (const [registered, value] of this.#names) {
+            if (registered !== identity && PostgresNames.physical(value) === physical) {
+                throw new Error(`PostgreSQL table name collides: ${physical}`);
+            }
+        }
+        this.#names.set(identity, name);
+    }
+}
+const PostgresNames = Object.freeze({
+    /**
+     * Calculates the default readable name for one record family.
+     *
+     * @param sourceType Record source type name.
+     * @param group Optional storage group name.
+     * @param recordType Optional grouped record type name.
+     * @returns Default readable table name.
+     */
+    default(sourceType, group, recordType) {
+        if (group === undefined)
+            return sourceType.replaceAll(".", "_");
+        const type = recordType ?? sourceType;
+        return `${group.replaceAll(".", "_")}_${type.slice(type.lastIndexOf(".") + 1)}`;
+    },
+    /**
+     * Applies PostgreSQL identifier validation and case folding.
+     *
+     * @param name Requested readable table name.
+     * @returns Validated physical table name.
+     */
+    physical(name) {
+        if (/\s/u.test(name) ||
+            name.includes("\u0000") ||
+            name.length === 0 ||
+            Buffer.byteLength(name) > 63) {
+            throw new Error(`PostgreSQL table name is invalid: ${name}`);
+        }
+        return PostgresNames.plain(name) && !PostgresNames.reserved.has(name.toLowerCase())
+            ? name.replace(/[A-Z]/g, (letter) => letter.toLowerCase())
+            : name;
+    },
+    /**
+     * Checks whether a name uses the unquoted PostgreSQL identifier grammar.
+     *
+     * @param name Requested table name.
+     * @returns Whether PostgreSQL may use the name without quoting for spelling.
+     */
+    plain(name) {
+        return /^[A-Za-z_][A-Za-z0-9_]*$/u.test(name);
+    },
+    // QueryDSL 5.1.0 querydsl-sql `keywords/postgresql`, loaded by `Keywords.POSTGRESQL`.
+    reserved: new Set([
+        "ALL",
+        "ANALYSE",
+        "ANALYZE",
+        "AND",
+        "ANY",
+        "ARRAY",
+        "AS",
+        "ASC",
+        "ASYMMETRIC",
+        "AUTHORIZATION",
+        "BINARY",
+        "BOTH",
+        "CASE",
+        "CAST",
+        "CHECK",
+        "COLLATE",
+        "COLLATION",
+        "COLUMN",
+        "CONCURRENTLY",
+        "CONSTRAINT",
+        "CREATE",
+        "CROSS",
+        "CURRENT_CATALOG",
+        "CURRENT_DATE",
+        "CURRENT_ROLE",
+        "CURRENT_SCHEMA",
+        "CURRENT_TIME",
+        "CURRENT_TIMESTAMP",
+        "CURRENT_USER",
+        "DEFAULT",
+        "DEFERRABLE",
+        "DESC",
+        "DISTINCT",
+        "DO",
+        "ELSE",
+        "END",
+        "EXCEPT",
+        "FALSE",
+        "FETCH",
+        "FOR",
+        "FOREIGN",
+        "FREEZE",
+        "FROM",
+        "FULL",
+        "GRANT",
+        "GROUP",
+        "HAVING",
+        "ILIKE",
+        "IN",
+        "INITIALLY",
+        "INNER",
+        "INTERSECT",
+        "INTO",
+        "IS",
+        "ISNULL",
+        "JOIN",
+        "LATERAL",
+        "LEADING",
+        "LEFT",
+        "LIKE",
+        "LIMIT",
+        "LOCALTIME",
+        "LOCALTIMESTAMP",
+        "NATURAL",
+        "NOT",
+        "NOTNULL",
+        "NULL",
+        "OFFSET",
+        "ON",
+        "ONLY",
+        "OR",
+        "ORDER",
+        "OUTER",
+        "OVER",
+        "OVERLAPS",
+        "PLACING",
+        "PRIMARY",
+        "REFERENCES",
+        "RETURNING",
+        "RIGHT",
+        "SELECT",
+        "SESSION_USER",
+        "SIMILAR",
+        "SOME",
+        "SYMMETRIC",
+        "TABLE",
+        "THEN",
+        "TO",
+        "TRAILING",
+        "TRUE",
+        "UNION",
+        "UNIQUE",
+        "USER",
+        "USING",
+        "VARIADIC",
+        "VERBOSE",
+        "WHEN",
+        "WHERE",
+        "WINDOW",
+        "WITH",
+    ].map((keyword) => keyword.toLowerCase())),
+});
+//# sourceMappingURL=table-resolver.js.map

package/dist/postgres/table-resolver.js.map

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

package/dist/postgres/table-spec.d.ts

@@ -0,0 +1,40 @@
+import { type Message } from "@bufbuild/protobuf";
+import type { GenMessage } from "@bufbuild/protobuf/codegenv2";
+import type { RecordColumn, RecordColumnType } from "@spine-event-engine/storage";
+import { type PostgresDdlType } from "./data-type.js";
+import type { PostgresTableSpec } from "./storage-factory.js";
+/**
+ * Resolves PostgreSQL-native declared-column and record-family table layouts.
+ */
+export declare const PostgresTableSpecs: PostgresTableSpecifications;
+/**
+ * Describes PostgreSQL table-layout operations.
+ */
+interface PostgresTableSpecifications {
+    /**
+     * Maps one declared record-column type to PostgreSQL DDL.
+     *
+     * @param type Declared Protobuf column type.
+     * @returns Canonical PostgreSQL DDL type name.
+     */
+    postgresColumnType(type: RecordColumnType): PostgresDdlType;
+    /**
+     * Builds the complete physical layout for one record family.
+     *
+     * @typeParam I Record identifier type.
+     * @typeParam R Stored Protobuf record type.
+     * @param input Resolved schema, table, types, group, and declared columns.
+     * @returns Complete PostgreSQL table specification.
+     */
+    resolvedPostgresTableSpec<I, R extends Message>(input: {
+        readonly schema: string;
+        readonly tableName: string;
+        readonly sourceType: GenMessage<Message>;
+        readonly recordType: GenMessage<R>;
+        readonly idType: I extends Message ? GenMessage<I> : string;
+        readonly groupName?: string;
+        readonly declaredColumns: readonly RecordColumn<R>[];
+    }): PostgresTableSpec<I, R>;
+}
+export {};
+//# sourceMappingURL=table-spec.d.ts.map

package/dist/postgres/table-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table-spec.d.ts","sourceRoot":"","sources":["../../src/postgres/table-spec.ts"],"names":[],"mappings":"AAcA,OAAO,EAAc,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAGlF,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACzE,OAAO,KAAK,EAAsB,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAGlF;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,2BA8D/B,CAAC;AAEH;;GAEG;AACH,UAAU,2BAA2B;IACnC;;;;;OAKG;IACH,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,eAAe,CAAC;IAE5D;;;;;;;OAOG;IACH,yBAAyB,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO,EAAE,KAAK,EAAE;QACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;QACzC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;QACnC,QAAQ,CAAC,MAAM,EAAE,CAAC,SAAS,OAAO,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;QAC5D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,eAAe,EAAE,SAAS,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;KACtD,GAAG,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CAC7B"}