@spine-event-engine/core 2.0.0-snapshot.10

package/dist/entity/entity-column.d.ts

@@ -0,0 +1,158 @@
+import { type DescField, type Message, type MessageShape } from "@bufbuild/protobuf";
+import type { GenMessage } from "@bufbuild/protobuf/codegenv2";
+import { type Version } from "@spine-event-engine/proto";
+/**
+ * Operators available for every Entity column.
+ */
+export type EntityEqualityOperator = "equal";
+/**
+ * Operators available for naturally ordered Entity column values.
+ */
+export type EntityOrderingOperator = EntityEqualityOperator | "greaterThan" | "lessThan" | "greaterOrEqual" | "lessOrEqual";
+/**
+ * Comparison family derived from a column's Protobuf field descriptor.
+ */
+export type EntityComparison = "equality" | "ordering";
+/**
+ * Runtime value category derived from a column's Protobuf field descriptor.
+ */
+export type EntityColumnValueKind = "bigint" | "boolean" | "bytes" | "enum" | "message" | "number" | "string";
+/**
+ * Represents one generated column declaration paired with its descriptor.
+ */
+export interface EntityColumnDefinitionEntry<Comparison extends EntityComparison = EntityComparison> {
+    /**
+     * Identifies the generated Protobuf field declared as a column.
+     */
+    readonly field: DescField;
+    /**
+     * Identifies the comparison family supported by the field.
+     */
+    readonly comparison: Comparison;
+}
+type StateFieldName<Schema extends GenMessage<Message>> = Exclude<keyof MessageShape<Schema>, "$typeName" | "$unknown"> & string;
+type CollectionFieldName<Schema extends GenMessage<Message>> = {
+    [Name in StateFieldName<Schema>]: NonNullable<MessageShape<Schema>[Name]> extends readonly unknown[] ? Name : NonNullable<MessageShape<Schema>[Name]> extends object ? string extends keyof NonNullable<MessageShape<Schema>[Name]> ? Name : never : never;
+}[StateFieldName<Schema>];
+type SupportedStateFieldName<Schema extends GenMessage<Message>> = Exclude<StateFieldName<Schema> & keyof Schema["field"], CollectionFieldName<Schema>>;
+type EntityColumnEntries = Readonly<Record<string, EntityColumnDefinitionEntry>>;
+type SupportedEntryConstraint<Schema extends GenMessage<Message>, Entries extends EntityColumnEntries> = Exclude<keyof Entries, SupportedStateFieldName<Schema>> extends never ? unknown : never;
+/**
+ * Brands generated column definitions for nominal type safety.
+ */
+declare const generatedDefinitionBrand: unique symbol;
+/**
+ * Describes descriptor-backed column metadata emitted next to an Entity schema.
+ *
+ * The package root exports this type, but not its value constructor. Application
+ * code therefore consumes generated metadata instead of authoring string keys.
+ */
+export interface EntityColumnDefinition<Schema extends GenMessage<Message>, Entries extends EntityColumnEntries> {
+    /**
+     * Brands metadata with its owning schema and generated entries.
+     */
+    readonly [generatedDefinitionBrand]: readonly [Schema, Entries];
+    /**
+     * Stores exact generated entries, validated again during registration.
+     * @internal
+     */
+    readonly entries: Entries;
+}
+/**
+ * Creates immutable Entity-column metadata emitted by the companion generator.
+ */
+export declare const GeneratedEntityColumns: Readonly<{
+    /**
+     * Creates immutable metadata for one generated Entity schema.
+     *
+     * @param schema Generated Protobuf schema that owns the declared fields.
+     * @param entries Generated field descriptors and their comparison families.
+     * @returns Metadata accepted by {@link EntityColumn.register}.
+     */
+    define<Schema extends GenMessage<Message>, const Entries extends EntityColumnEntries>(schema: Schema, entries: Entries & SupportedEntryConstraint<NoInfer<Schema>, Entries>): EntityColumnDefinition<Schema, Entries>;
+}>;
+type OperatorsFor<Entry> = Entry extends EntityColumnDefinitionEntry<"ordering"> ? EntityOrderingOperator : EntityEqualityOperator;
+/**
+ * Represents the typed column collection returned for one generated Entity definition.
+ */
+export type EntityColumns<Schema extends GenMessage<Message>, Entries extends EntityColumnEntries> = Readonly<{
+    [Name in keyof Entries & StateFieldName<Schema>]: EntityColumn<Schema, Name, MessageShape<Schema>[Name], OperatorsFor<Entries[Name]>>;
+} & {
+    /**
+     * Identifies the Entity version system column.
+     */
+    readonly version: EntityColumn<Schema, "version", Version>;
+    /**
+     * Identifies the Entity archived system column.
+     */
+    readonly archived: EntityColumn<Schema, "archived", boolean, EntityEqualityOperator>;
+    /**
+     * Identifies the Entity deleted system column.
+     */
+    readonly deleted: EntityColumn<Schema, "deleted", boolean, EntityEqualityOperator>;
+}>;
+/**
+ * Extracts the value type carried by an Entity column.
+ */
+export type EntityColumnValue<Column extends EntityColumn> = Column extends EntityColumn<GenMessage<Message>, string, infer Value> ? Value : never;
+/**
+ * Extracts the legal operator union carried by an Entity column.
+ */
+export type EntityColumnOperator<Column extends EntityColumn> = Column extends EntityColumn<GenMessage<Message>, string, unknown, infer Operator> ? Operator : never;
+/**
+ * An immutable, nominal, descriptor-backed Entity column.
+ *
+ * Instances can only be obtained by registering generated metadata for a
+ * Entity schema. This prevents consumers from constructing arbitrary
+ * string columns that have no corresponding Protobuf declaration.
+ */
+export declare class EntityColumn<Schema extends GenMessage<Message> = GenMessage<Message>, Name extends string = string, Value = unknown, Operator extends EntityOrderingOperator = EntityOrderingOperator> {
+    private readonly entityColumnBrand;
+    /**
+     * Generated Protobuf schema that owns this column.
+     */
+    readonly schema: Schema;
+    /**
+     * Protobuf field name, or the canonical system-column name.
+     */
+    readonly name: string;
+    /**
+     * Protobuf-ES property name, or the canonical system-column name.
+     */
+    readonly localName: Name;
+    /**
+     * Whether the column came from the state descriptor or Entity storage metadata.
+     */
+    readonly source: "declared" | "system";
+    /**
+     * Exact declared field descriptor; system columns have no state field.
+     */
+    readonly descriptor: DescField | undefined;
+    /**
+     * Runtime value category derived from the descriptor.
+     */
+    readonly valueKind: EntityColumnValueKind;
+    /**
+     * Fully qualified message type for message-valued columns.
+     */
+    readonly messageType: string | undefined;
+    /**
+     * Supported comparison family.
+     */
+    readonly comparison: EntityComparison;
+    /**
+     * Exact operator set accepted for this column.
+     */
+    readonly operators: readonly Operator[];
+    private constructor();
+    /**
+     * Registers generated Entity-column metadata for a schema.
+     *
+     * @param schema Generated Entity schema that owns the metadata.
+     * @param definition Immutable generated field metadata.
+     * @returns Stable immutable columns for the Entity schema.
+     */
+    static register<Schema extends GenMessage<Message>, const Entries extends EntityColumnEntries>(schema: Schema, definition: EntityColumnDefinition<Schema, Entries>): EntityColumns<Schema, Entries>;
+}
+export {};
+//# sourceMappingURL=entity-column.d.ts.map

package/dist/entity/entity-column.d.ts.map

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

package/dist/entity/entity-column.js

@@ -0,0 +1,303 @@
+/*
+ * 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 { getOption, hasOption, } from "@bufbuild/protobuf";
+import { column, entity, EntityOption_Kind } from "@spine-event-engine/proto";
+import { EntityFieldClassification } from "../query/entity-field-classification.js";
+/**
+ * Creates immutable Entity-column metadata emitted by the companion generator.
+ */
+export const GeneratedEntityColumns = Object.freeze({
+    define(schema, entries) {
+        const captured = EntityColumnFacts.captureDefinition(schema, entries);
+        const copiedEntries = Object.fromEntries(Object.entries(entries).map(([name, entry]) => {
+            EntityColumnFacts.deepFreeze(entry.field);
+            return [name, Object.freeze({ field: entry.field, comparison: entry.comparison })];
+        }));
+        const definition = Object.freeze({
+            entries: Object.freeze(copiedEntries),
+        });
+        capturedDefinitions.set(definition, captured);
+        return definition;
+    },
+});
+const equalityOperators = Object.freeze(["equal"]);
+const orderingOperators = Object.freeze([
+    "equal",
+    "greaterThan",
+    "lessThan",
+    "greaterOrEqual",
+    "lessOrEqual",
+]);
+const systemNames = new Set(["version", "archived", "deleted"]);
+const cache = new WeakMap();
+const entityColumnConstructionToken = Symbol("EntityColumnConstructionToken");
+const capturedDefinitions = new WeakMap();
+/**
+ * An immutable, nominal, descriptor-backed Entity column.
+ *
+ * Instances can only be obtained by registering generated metadata for a
+ * Entity schema. This prevents consumers from constructing arbitrary
+ * string columns that have no corresponding Protobuf declaration.
+ */
+export class EntityColumn {
+    /**
+     * Generated Protobuf schema that owns this column.
+     */
+    schema;
+    /**
+     * Protobuf field name, or the canonical system-column name.
+     */
+    name;
+    /**
+     * Protobuf-ES property name, or the canonical system-column name.
+     */
+    localName;
+    /**
+     * Whether the column came from the state descriptor or Entity storage metadata.
+     */
+    source;
+    /**
+     * Exact declared field descriptor; system columns have no state field.
+     */
+    descriptor;
+    /**
+     * Runtime value category derived from the descriptor.
+     */
+    valueKind;
+    /**
+     * Fully qualified message type for message-valued columns.
+     */
+    messageType;
+    /**
+     * Supported comparison family.
+     */
+    comparison;
+    /**
+     * Exact operator set accepted for this column.
+     */
+    operators;
+    constructor(input, token) {
+        if (token !== entityColumnConstructionToken) {
+            throw new TypeError("Entity columns can only be constructed during registration.");
+        }
+        this.schema = input.schema;
+        this.name = input.name;
+        this.localName = input.localName;
+        this.source = input.source;
+        this.descriptor = input.descriptor;
+        this.valueKind = input.valueKind;
+        this.messageType = input.messageType;
+        this.comparison = input.comparison;
+        this.operators = input.operators;
+        Object.freeze(this);
+    }
+    /**
+     * Registers generated Entity-column metadata for a schema.
+     *
+     * @param schema Generated Entity schema that owns the metadata.
+     * @param definition Immutable generated field metadata.
+     * @returns Stable immutable columns for the Entity schema.
+     */
+    static register(schema, definition) {
+        const existing = cache.get(schema);
+        if (existing?.definitions.has(definition) === true) {
+            return existing.columns;
+        }
+        const captured = capturedDefinitions.get(definition);
+        EntityColumnFacts.validateSchema(schema, captured);
+        const declared = EntityColumnFacts.validateDefinition(schema, definition, captured);
+        if (existing !== undefined) {
+            existing.definitions.add(definition);
+            return existing.columns;
+        }
+        const result = {};
+        for (const [localName, field, fieldName, metadata] of declared) {
+            result[localName] = new EntityColumn({
+                schema,
+                name: fieldName,
+                localName,
+                source: "declared",
+                descriptor: field,
+                valueKind: metadata.valueKind,
+                messageType: metadata.messageType,
+                comparison: metadata.comparison,
+                operators: EntityColumnFacts.operatorsFor(metadata.comparison),
+            }, entityColumnConstructionToken);
+        }
+        result.version = new EntityColumn({
+            schema,
+            name: "version",
+            localName: "version",
+            source: "system",
+            valueKind: "message",
+            messageType: "spine.core.Version",
+            comparison: "ordering",
+            operators: orderingOperators,
+        }, entityColumnConstructionToken);
+        for (const name of ["archived", "deleted"]) {
+            result[name] = new EntityColumn({
+                schema,
+                name,
+                localName: name,
+                source: "system",
+                valueKind: "boolean",
+                comparison: "equality",
+                operators: equalityOperators,
+            }, entityColumnConstructionToken);
+        }
+        const columns = Object.freeze(result);
+        cache.set(schema, {
+            definitions: new WeakSet([definition]),
+            columns,
+        });
+        return columns;
+    }
+}
+/**
+ * Internal descriptor facts used while generated column metadata is registered.
+ */
+const EntityColumnFacts = Object.freeze({
+    // prettier-ignore
+    /**
+     * Validates that a schema declares one supported Entity kind.
+     */
+    validateSchema(schema, captured) {
+        const entityKind = captured?.schema === schema
+            ? captured.entityKind
+            : hasOption(schema, entity)
+                ? getOption(schema, entity).kind
+                : undefined;
+        if (entityKind !== EntityOption_Kind.AGGREGATE &&
+            entityKind !== EntityOption_Kind.PROJECTION &&
+            entityKind !== EntityOption_Kind.PROCESS_MANAGER) {
+            throw new TypeError(`Entity column schema "${schema.typeName}" must declare Entity kind.`);
+        }
+    },
+    /**
+     * Validates and describes every declared generated column.
+     */
+    validateDefinition(schema, definition, captured) {
+        const facts = captured?.schema === schema
+            ? captured
+            : EntityColumnFacts.captureDefinition(schema, definition.entries);
+        const annotated = new Map(facts.annotated);
+        const result = [];
+        for (const [localName, entry] of Object.entries(definition.entries)) {
+            if (systemNames.has(localName)) {
+                throw new TypeError(`Entity column definition cannot replace system column "${localName}".`);
+            }
+            if (entry === undefined)
+                continue;
+            const fieldFacts = facts.entries.get(localName) ?? EntityColumnFacts.captureField(entry.field);
+            if (fieldFacts.parent !== schema || fieldFacts.localName !== localName) {
+                throw new TypeError(`Entity column definition key "${localName}" must reference field "${localName}".`);
+            }
+            if (!fieldFacts.markedColumn) {
+                throw new TypeError(`Entity field "${localName}" is not marked (column).`);
+            }
+            const metadata = EntityColumnFacts.describeField(fieldFacts);
+            if (entry.comparison !== metadata.comparison) {
+                throw new TypeError(`Entity column "${localName}" requires ${metadata.comparison} comparison metadata.`);
+            }
+            annotated.delete(localName);
+            result.push([localName, fieldFacts.field, fieldFacts.name, metadata]);
+        }
+        const missing = annotated.keys().next().value;
+        if (missing !== undefined) {
+            throw new TypeError(`Entity column definition is missing annotated field "${missing}".`);
+        }
+        return result;
+    },
+    /**
+     * Derives runtime metadata from one validated descriptor.
+     */
+    describeField(field) {
+        const metadata = field.classification;
+        if (!metadata.supported && metadata.reason === "singular") {
+            throw new TypeError(`Entity column "${field.localName}" must be singular; repeated and map fields are unsupported.`);
+        }
+        if (!metadata.supported) {
+            throw new TypeError(`Entity column "${field.localName}" cannot belong to a oneof.`);
+        }
+        return metadata;
+    },
+    /**
+     * Captures immutable facts from one generated definition.
+     */
+    captureDefinition(schema, entries) {
+        const annotated = new Map(schema.fields
+            .filter((field) => hasOption(field, column) && getOption(field, column))
+            .map((field) => [field.localName, field]));
+        const capturedEntries = new Map();
+        for (const [localName, entry] of Object.entries(entries)) {
+            capturedEntries.set(localName, EntityColumnFacts.captureField(entry.field));
+        }
+        return Object.freeze({
+            schema,
+            entityKind: hasOption(schema, entity) ? getOption(schema, entity).kind : undefined,
+            annotated,
+            entries: capturedEntries,
+        });
+    },
+    /**
+     * Captures immutable facts from one generated field descriptor.
+     */
+    captureField(field) {
+        return Object.freeze({
+            field,
+            parent: field.parent,
+            localName: field.localName,
+            name: field.name,
+            markedColumn: hasOption(field, column) && getOption(field, column),
+            classification: Object.freeze(EntityFieldClassification.classify(field)),
+        });
+    },
+    /**
+     * Deeply freezes a descriptor graph without freezing typed-array views.
+     */
+    deepFreeze(root) {
+        const pending = [root];
+        const visited = new WeakSet();
+        while (pending.length > 0) {
+            const current = pending.pop();
+            if (current === undefined || visited.has(current))
+                continue;
+            visited.add(current);
+            if (ArrayBuffer.isView(current))
+                continue;
+            for (const key of Reflect.ownKeys(current)) {
+                const property = Object.getOwnPropertyDescriptor(current, key);
+                if (property !== undefined &&
+                    "value" in property &&
+                    EntityColumnFacts.isObject(property.value)) {
+                    pending.push(property.value);
+                }
+            }
+            Object.freeze(current);
+        }
+    },
+    /**
+     * Checks whether a value can participate in a descriptor graph.
+     */
+    isObject(value) {
+        return (typeof value === "object" && value !== null) || typeof value === "function";
+    },
+    /**
+     * Returns the supported operator set for a comparison family.
+     */
+    operatorsFor(comparison) {
+        return comparison === "ordering" ? orderingOperators : equalityOperators;
+    },
+});
+//# sourceMappingURL=entity-column.js.map

package/dist/entity/entity-column.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-column.js","sourceRoot":"","sources":["../../src/entity/entity-column.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,SAAS,EACT,SAAS,GAIV,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAgB,MAAM,2BAA2B,CAAC;AAC5F,OAAO,EAAE,yBAAyB,EAAE,MAAM,yCAAyC,CAAC;AAqGpF;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAc9B,MAAM,CAAC,MAAM,CAAC;IACjB,MAAM,CACJ,MAAc,EACd,OAAqE;QAErE,MAAM,QAAQ,GAAG,iBAAiB,CAAC,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACtE,MAAM,aAAa,GAAG,MAAM,CAAC,WAAW,CACrC,MAAM,CAAC,OAAO,CAAC,OAAO,CAA6C,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE;YACzF,iBAAiB,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC1C,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;QACrF,CAAC,CAAC,CACH,CAAC;QACF,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC;YAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC;SACtC,CAAuD,CAAC;QACzD,mBAAmB,CAAC,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;QAC9C,OAAO,UAAU,CAAC;IACpB,CAAC;CACF,CAAC,CAAC;AAuDH,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAU,CAAC,CAAC;AAC5D,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,CAAC;IACtC,OAAO;IACP,aAAa;IACb,UAAU;IACV,gBAAgB;IAChB,aAAa;CACL,CAAC,CAAC;AACZ,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC;AAMhE,MAAM,KAAK,GAAG,IAAI,OAAO,EAA+B,CAAC;AACzD,MAAM,6BAA6B,GAAG,MAAM,CAAC,+BAA+B,CAAC,CAAC;AAgB9E,MAAM,mBAAmB,GAAG,IAAI,OAAO,EAAmC,CAAC;AAE3E;;;;;;GAMG;AACH,MAAM,OAAO,YAAY;IAQvB;;OAEG;IACM,MAAM,CAAS;IAExB;;OAEG;IACM,IAAI,CAAS;IAEtB;;OAEG;IACM,SAAS,CAAO;IAEzB;;OAEG;IACM,MAAM,CAAwB;IAEvC;;OAEG;IACM,UAAU,CAAwB;IAE3C;;OAEG;IACM,SAAS,CAAwB;IAE1C;;OAEG;IACM,WAAW,CAAqB;IAEzC;;OAEG;IACM,UAAU,CAAmB;IAEtC;;OAEG;IACM,SAAS,CAAsB;IAExC,YACE,KAUC,EACD,KAAc;QAEd,IAAI,KAAK,KAAK,6BAA6B,EAAE,CAAC;YAC5C,MAAM,IAAI,SAAS,CAAC,6DAA6D,CAAC,CAAC;QACrF,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACvB,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;QACjC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC;QACnC,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;QACjC,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;QACrC,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC;QACnC,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;QACjC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,CACb,MAAc,EACd,UAAmD;QAEnD,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACnC,IAAI,QAAQ,EAAE,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,IAAI,EAAE,CAAC;YACnD,OAAO,QAAQ,CAAC,OAAyC,CAAC;QAC5D,CAAC;QACD,MAAM,QAAQ,GAAG,mBAAmB,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACrD,iBAAiB,CAAC,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QACnD,MAAM,QAAQ,GAAG,iBAAiB,CAAC,kBAAkB,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;QACpF,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YACrC,OAAO,QAAQ,CAAC,OAAyC,CAAC;QAC5D,CAAC;QAED,MAAM,MAAM,GAAiC,EAAE,CAAC;QAChD,KAAK,MAAM,CAAC,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,CAAC,IAAI,QAAQ,EAAE,CAAC;YAC/D,MAAM,CAAC,SAAS,CAAC,GAAG,IAAI,YAAY,CAClC;gBACE,MAAM;gBACN,IAAI,EAAE,SAAS;gBACf,SAAS;gBACT,MAAM,EAAE,UAAU;gBAClB,UAAU,EAAE,KAAK;gBACjB,SAAS,EAAE,QAAQ,CAAC,SAAS;gBAC7B,WAAW,EAAE,QAAQ,CAAC,WAAW;gBACjC,UAAU,EAAE,QAAQ,CAAC,UAAU;gBAC/B,SAAS,EAAE,iBAAiB,CAAC,YAAY,CAAC,QAAQ,CAAC,UAAU,CAAC;aAC/D,EACD,6BAA6B,CAC9B,CAAC;QACJ,CAAC;QACD,MAAM,CAAC,OAAO,GAAG,IAAI,YAAY,CAC/B;YACE,MAAM;YACN,IAAI,EAAE,SAAS;YACf,SAAS,EAAE,SAAS;YACpB,MAAM,EAAE,QAAQ;YAChB,SAAS,EAAE,SAAS;YACpB,WAAW,EAAE,oBAAoB;YACjC,UAAU,EAAE,UAAU;YACtB,SAAS,EAAE,iBAAiB;SAC7B,EACD,6BAA6B,CAC9B,CAAC;QACF,KAAK,MAAM,IAAI,IAAI,CAAC,UAAU,EAAE,SAAS,CAAU,EAAE,CAAC;YACpD,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,YAAY,CAC7B;gBACE,MAAM;gBACN,IAAI;gBACJ,SAAS,EAAE,IAAI;gBACf,MAAM,EAAE,QAAQ;gBAChB,SAAS,EAAE,SAAS;gBACpB,UAAU,EAAE,UAAU;gBACtB,SAAS,EAAE,iBAAiB;aAC7B,EACD,6BAA6B,CAC9B,CAAC;QACJ,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAmC,CAAC;QACxE,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE;YAChB,WAAW,EAAE,IAAI,OAAO,CAAC,CAAC,UAAU,CAAC,CAAC;YACtC,OAAO;SACR,CAAC,CAAC;QACH,OAAO,OAAO,CAAC;IACjB,CAAC;CACF;AAQD;;GAEG;AACH,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,CAAC;IACtC,kBAAkB;IAElB;;OAEG;IACH,cAAc,CAAC,MAA2B,EAAE,QAA6C;QACvF,MAAM,UAAU,GACd,QAAQ,EAAE,MAAM,KAAK,MAAM;YACzB,CAAC,CAAC,QAAQ,CAAC,UAAU;YACrB,CAAC,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC;gBACzB,CAAC,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,IAAI;gBAChC,CAAC,CAAC,SAAS,CAAC;QAClB,IACE,UAAU,KAAK,iBAAiB,CAAC,SAAS;YAC1C,UAAU,KAAK,iBAAiB,CAAC,UAAU;YAC3C,UAAU,KAAK,iBAAiB,CAAC,eAAe,EAChD,CAAC;YACD,MAAM,IAAI,SAAS,CAAC,yBAAyB,MAAM,CAAC,QAAQ,6BAA6B,CAAC,CAAC;QAC7F,CAAC;IACH,CAAC;IAED;;OAEG;IACH,kBAAkB,CAChB,MAA2B,EAC3B,UAA4E,EAC5E,QAA6C;QAE7C,MAAM,KAAK,GACT,QAAQ,EAAE,MAAM,KAAK,MAAM;YACzB,CAAC,CAAC,QAAQ;YACV,CAAC,CAAC,iBAAiB,CAAC,iBAAiB,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;QACtE,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAC3C,MAAM,MAAM,GAA8D,EAAE,CAAC;QAE7E,KAAK,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAG/D,EAAE,CAAC;YACJ,IAAI,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC/B,MAAM,IAAI,SAAS,CACjB,0DAA0D,SAAS,IAAI,CACxE,CAAC;YACJ,CAAC;YACD,IAAI,KAAK,KAAK,SAAS;gBAAE,SAAS;YAClC,MAAM,UAAU,GACd,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,iBAAiB,CAAC,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC9E,IAAI,UAAU,CAAC,MAAM,KAAK,MAAM,IAAI,UAAU,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;gBACvE,MAAM,IAAI,SAAS,CACjB,iCAAiC,SAAS,2BAA2B,SAAS,IAAI,CACnF,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,UAAU,CAAC,YAAY,EAAE,CAAC;gBAC7B,MAAM,IAAI,SAAS,CAAC,iBAAiB,SAAS,2BAA2B,CAAC,CAAC;YAC7E,CAAC;YACD,MAAM,QAAQ,GAAG,iBAAiB,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;YAC7D,IAAI,KAAK,CAAC,UAAU,KAAK,QAAQ,CAAC,UAAU,EAAE,CAAC;gBAC7C,MAAM,IAAI,SAAS,CACjB,kBAAkB,SAAS,cAAc,QAAQ,CAAC,UAAU,uBAAuB,CACpF,CAAC;YACJ,CAAC;YACD,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YAC5B,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,UAAU,CAAC,KAAK,EAAE,UAAU,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;QACxE,CAAC;QAED,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;QAC9C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,IAAI,SAAS,CAAC,wDAAwD,OAAO,IAAI,CAAC,CAAC;QAC3F,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACH,aAAa,CAAC,KAAyB;QACrC,MAAM,QAAQ,GAAG,KAAK,CAAC,cAAc,CAAC;QACtC,IAAI,CAAC,QAAQ,CAAC,SAAS,IAAI,QAAQ,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;YAC1D,MAAM,IAAI,SAAS,CACjB,kBAAkB,KAAK,CAAC,SAAS,8DAA8D,CAChG,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,SAAS,CAAC,kBAAkB,KAAK,CAAC,SAAS,6BAA6B,CAAC,CAAC;QACtF,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;OAEG;IACH,iBAAiB,CACf,MAA2B,EAC3B,OAA4B;QAE5B,MAAM,SAAS,GAAG,IAAI,GAAG,CACvB,MAAM,CAAC,MAAM;aACV,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;aACvE,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC,CAC5C,CAAC;QACF,MAAM,eAAe,GAAG,IAAI,GAAG,EAA8B,CAAC;QAC9D,KAAK,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YACzD,eAAe,CAAC,GAAG,CAAC,SAAS,EAAE,iBAAiB,CAAC,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;QAC9E,CAAC;QACD,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,MAAM;YACN,UAAU,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;YAClF,SAAS;YACT,OAAO,EAAE,eAAe;SACzB,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,KAAgB;QAC3B,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,KAAK;YACL,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,YAAY,EAAE,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC;YAClE,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC,yBAAyB,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;SACzE,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,UAAU,CAAC,IAAY;QACrB,MAAM,OAAO,GAAa,CAAC,IAAI,CAAC,CAAC;QACjC,MAAM,OAAO,GAAG,IAAI,OAAO,EAAU,CAAC;QACtC,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;YAC9B,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;gBAAE,SAAS;YAC5D,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACrB,IAAI,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC;gBAAE,SAAS;YAC1C,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC3C,MAAM,QAAQ,GAAG,MAAM,CAAC,wBAAwB,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;gBAC/D,IACE,QAAQ,KAAK,SAAS;oBACtB,OAAO,IAAI,QAAQ;oBACnB,iBAAiB,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,EAC1C,CAAC;oBACD,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;gBAC/B,CAAC;YACH,CAAC;YACD,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IAED;;OAEG;IACH,QAAQ,CAAC,KAAc;QACrB,OAAO,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC,IAAI,OAAO,KAAK,KAAK,UAAU,CAAC;IACtF,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,UAA4B;QACvC,OAAO,UAAU,KAAK,UAAU,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,iBAAiB,CAAC;IAC3E,CAAC;CACF,CAAC,CAAC"}