@memberjunction/integration-engine-base 6.2.0-edge.4 → 6.2.0-edge.6

package/dist/CompanyIntegrationCatalog.d.ts

@@ -0,0 +1,173 @@
+import type { BaseEntity } from '@memberjunction/core';
+import type { MJIntegrationObjectEntity, MJIntegrationObjectFieldEntity } from '@memberjunction/core-entities';
+/**
+ * The per-connection catalog: read-side types, column contract, and projection.
+ *
+ * Every connector and every engine read site names an IntegrationObject's properties directly —
+ * `io.Name` appears 241 times across the connectors repository, `io.Fields` 93, `io.APIPath` 52.
+ * A row loaded for an entity with no registered subclass is a plain `BaseEntity`: it carries its
+ * values in `Fields` and exposes them through `Get()`, and every one of those property reads is
+ * `undefined`. So the cache cannot hand connectors the entity rows themselves.
+ *
+ * It hands them PROJECTIONS instead — plain objects carrying exactly the property surface the read
+ * sites use. That is not a new idea here: `IntegrationEngineBase.SeedForTesting` already seeds the
+ * shared catalog with "plain objects shaped like the entity (property reads only)" for the same
+ * reason, and the replay tiers exercise metadata-driven connectors through them.
+ *
+ * Writes are the other half and do NOT come through here — they go through the store in
+ * `@memberjunction/integration-engine`, which holds real entity rows and uses `Get()`/`Set()`
+ * exclusively. Assigning `row.Name = x` on a subclass-less `BaseEntity` silently creates an own
+ * property, `Save()` sends nothing, and the write is lost with no error anywhere.
+ */
+export declare const ENTITY_COMPANY_INTEGRATION_OBJECTS = "MJ: Company Integration Objects";
+export declare const ENTITY_COMPANY_INTEGRATION_OBJECT_FIELDS = "MJ: Company Integration Object Fields";
+/**
+ * Columns the object projection reads. The first 43 are IntegrationObject's own, copied verbatim so
+ * a per-connection row answers every question a shared row answers; the rest are what per-connection
+ * rows add. `IntegrationID` is deliberately among the first group and denormalised onto the table:
+ * connectors read it off the object, and a join per read would be the wrong trade.
+ */
+export declare const CATALOG_OBJECT_COLUMNS: readonly ["ID", "IntegrationID", "Name", "DisplayName", "Description", "Category", "APIPath", "ResponseDataKey", "DefaultPageSize", "SupportsPagination", "PaginationType", "SupportsIncrementalSync", "SupportsWrite", "DefaultQueryParams", "Configuration", "Sequence", "Status", "WriteAPIPath", "WriteMethod", "DeleteMethod", "IsCustom", "CreateAPIPath", "CreateMethod", "CreateBodyShape", "CreateBodyKey", "CreateIDLocation", "UpdateAPIPath", "UpdateMethod", "UpdateBodyShape", "UpdateBodyKey", "UpdateIDLocation", "DeleteAPIPath", "DeleteIDLocation", "IncrementalWatermarkField", "MetadataSource", "SupportsCreate", "SupportsUpdate", "SupportsDelete", "SyncStrategy", "ContentHashApplicable", "StableOrderingKey", "CompanyIntegrationID", "IntegrationObjectID", "Provenance", "ProvenanceDetail", "IsSelected", "SelectedAt", "FirstSeenAt", "LastSeenAt", "LastSampledAt"];
+/**
+ * Columns the field projection reads. These are all REAL columns on the per-connection field
+ * table — the legacy names `IntegrationObjectID` / `RelatedIntegrationObjectID` are NOT here and
+ * must not be: they are derived in `ProjectCatalogFields` (see FIELD_READ_ALIASES).
+ *
+ * They are derived in TypeScript rather than aliased in the base view because the view is
+ * CodeGen-generated: a hand-added alias column would be silently dropped the next time CodeGen
+ * regenerates it, and the loss would only surface as a schema-mismatch throw much later.
+ */
+export declare const CATALOG_FIELD_COLUMNS: readonly ["ID", "Name", "DisplayName", "Description", "Category", "Type", "Length", "Precision", "Scale", "AllowsNull", "DefaultValue", "IsPrimaryKey", "IsUniqueKey", "IsReadOnly", "IsRequired", "RelatedIntegrationObjectFieldName", "Sequence", "Configuration", "Status", "IsCustom", "MetadataSource", "CompanyIntegrationObjectID", "RelatedCompanyIntegrationObjectID", "IntegrationObjectFieldID", "Provenance", "ProvenanceDetail", "IsSelected", "SelectedAt", "FirstSeenAt", "LastSeenAt", "LastSampledAt", "ObservedMaxLength"];
+/**
+ * The three columns of a per-connection field row that the dependency walk reads.
+ *
+ * The walk is the one consumer that needs every field of a connection that points at another
+ * object, and it needs nothing else of them, so those are loaded for the whole connection as plain
+ * rows — never entities — while full field rows are loaded one object at a time. Conflating the two
+ * is what forced the whole catalog to be resident.
+ */
+export declare const CATALOG_EDGE_COLUMNS: readonly ["ID", "CompanyIntegrationObjectID", "RelatedCompanyIntegrationObjectID"];
+/** One dependency edge: a field of one per-connection object pointing at another of the same connection. */
+export interface CatalogDependencyEdge {
+    ID: string;
+    CompanyIntegrationObjectID: string;
+    RelatedCompanyIntegrationObjectID: string | null;
+}
+/**
+ * The per-connection catalog of the scope in force, as its owner hands it to the engine base
+ * through `IntegrationEngineBase.CatalogDataResolver`.
+ *
+ * Raw rows rather than projections, so projection and memoisation have one home (the engine base)
+ * and a scope owner cannot hand over a projection that skipped the column check.
+ */
+export interface CatalogScopeData {
+    /** Every object row of the connection in scope, loaded when the scope was entered. */
+    Objects: BaseEntity[];
+    /**
+     * Full field rows of the objects warm right now, keyed by lowercased object id. Field rows are
+     * fetched one object at a time into a bounded cache, so an object absent from this map is COLD,
+     * which is a different thing from an object with no fields.
+     */
+    FieldsByObjectID: ReadonlyMap<string, BaseEntity[]>;
+    /**
+     * The connection's dependency edges: one per field that points at another object. Required
+     * whenever a dependency order is asked for: a missing edge set does not fail, it silently
+     * reorders a sync, children first.
+     */
+    Edges?: readonly CatalogDependencyEdge[];
+    /**
+     * True when the scope's owner warms every object before reading it, so a read of a cold object
+     * is a missed warm site and throws. False for owners that have no warm sites yet, whose cold
+     * reads answer empty exactly as they did before the catalog stopped being resident.
+     */
+    RequireWarmFields: boolean;
+}
+export declare const DECLARED_OWNED_OBJECT_COLUMNS: readonly string[];
+export declare const DECLARED_OWNED_FIELD_COLUMNS: readonly string[];
+/** Where a per-connection row's shape came from. */
+export type CatalogProvenance = 'Declared' | 'Endpoint' | 'Sampled';
+/**
+ * A per-connection object as read sites see it: every IntegrationObject property, plus the
+ * per-connection additions. Structurally assignable to `MJIntegrationObjectEntity` for the property
+ * reads connectors perform, which is what makes the swap invisible to them.
+ */
+export type CompanyIntegrationObjectRow = Pick<MJIntegrationObjectEntity, 'ID' | 'IntegrationID' | 'Name' | 'DisplayName' | 'Description' | 'Category' | 'APIPath' | 'ResponseDataKey' | 'DefaultPageSize' | 'SupportsPagination' | 'PaginationType' | 'SupportsIncrementalSync' | 'SupportsWrite' | 'DefaultQueryParams' | 'Configuration' | 'Sequence' | 'Status' | 'WriteAPIPath' | 'WriteMethod' | 'DeleteMethod' | 'IsCustom' | 'CreateAPIPath' | 'CreateMethod' | 'CreateBodyShape' | 'CreateBodyKey' | 'CreateIDLocation' | 'UpdateAPIPath' | 'UpdateMethod' | 'UpdateBodyShape' | 'UpdateBodyKey' | 'UpdateIDLocation' | 'DeleteAPIPath' | 'DeleteIDLocation' | 'IncrementalWatermarkField' | 'MetadataSource' | 'SupportsCreate' | 'SupportsUpdate' | 'SupportsDelete' | 'SyncStrategy' | 'ContentHashApplicable' | 'StableOrderingKey'> & {
+    /** The connection this row belongs to. The axis the whole design exists for. */
+    CompanyIntegrationID: string;
+    /** The declared row this was matched to, or null when the object exists only for this connection. */
+    IntegrationObjectID: string | null;
+    Provenance: CatalogProvenance;
+    /** Per-attribute merge log the persist already computes and currently discards. */
+    ProvenanceDetail: string | null;
+    /**
+     * Catalog membership and sync selection are separate axes. Conflating them is what made a
+     * newly-discovered object arrive `Disabled` and therefore vanish from schema introspection, key
+     * inference and migration — the customer saw it in the picker, selected it, and got nothing.
+     */
+    IsSelected: boolean;
+    SelectedAt: Date | null;
+    FirstSeenAt: Date | null;
+    LastSeenAt: Date | null;
+    LastSampledAt: Date | null;
+};
+/**
+ * A per-connection field as read sites see it. `IntegrationObjectID` and
+ * `RelatedIntegrationObjectID` carry per-connection ids through the view aliases.
+ */
+export type CompanyIntegrationObjectFieldRow = Pick<MJIntegrationObjectFieldEntity, 'ID' | 'IntegrationObjectID' | 'Name' | 'DisplayName' | 'Description' | 'Category' | 'Type' | 'Length' | 'Precision' | 'Scale' | 'AllowsNull' | 'DefaultValue' | 'IsPrimaryKey' | 'IsUniqueKey' | 'IsReadOnly' | 'IsRequired' | 'RelatedIntegrationObjectID' | 'RelatedIntegrationObjectFieldName' | 'Sequence' | 'Configuration' | 'Status' | 'IsCustom' | 'MetadataSource'> & {
+    CompanyIntegrationObjectID: string;
+    RelatedCompanyIntegrationObjectID: string | null;
+    IntegrationObjectFieldID: string | null;
+    Provenance: CatalogProvenance;
+    ProvenanceDetail: string | null;
+    IsSelected: boolean;
+    SelectedAt: Date | null;
+    FirstSeenAt: Date | null;
+    LastSeenAt: Date | null;
+    LastSampledAt: Date | null;
+    /**
+     * The raw sampled maximum, kept apart from `Length`, which carries the padded width the DDL
+     * uses. Without both, a width complaint cannot be told from a padding complaint.
+     */
+    ObservedMaxLength: number | null;
+};
+/**
+ * Thrown when the loaded entity is missing columns this code requires — the migration is absent or
+ * an older version of it ran. Failing here names the problem; letting it through would produce rows
+ * whose per-connection columns are all `undefined`, which reads downstream as "no selection, no
+ * provenance, never seen" and is indistinguishable from a legitimately empty catalog.
+ */
+export declare class CompanyIntegrationCatalogSchemaMismatch extends Error {
+    readonly Code = "PER_CONNECTION_CATALOG_SCHEMA_MISMATCH";
+    constructor(entityName: string, missing: string[]);
+}
+/**
+ * Verify a loaded row carries every column we read. Called once per array load — the cost is one
+ * pass over one row's field list, and the alternative is a silent wrong answer.
+ */
+export declare function AssertCatalogColumns(entityName: string, row: BaseEntity, required: readonly string[]): void;
+/**
+ * Project loaded object rows for the read path. Validates the column set against the FIRST row
+ * only: every row in the array is the same entity, so one is proof, and an empty array proves
+ * nothing and needs no check — a connection with no catalog rows is the ordinary pre-discovery
+ * state, not a schema problem.
+ */
+export declare function ProjectCatalogObjects(rows: BaseEntity[]): CompanyIntegrationObjectRow[];
+/** Project loaded field rows for the read path. Same validation rule as the object projection. */
+export declare function ProjectCatalogFields(rows: BaseEntity[]): CompanyIntegrationObjectFieldRow[];
+/**
+ * Present a projection to code typed against the shared catalog entities.
+ *
+ * The two casts below are the ONLY place this narrowing happens, deliberately, so the reasoning
+ * sits in one auditable spot. A projection carries every property the read sites touch and none of
+ * `BaseEntity`'s behaviour — no `Save()`, no `Fields`, no dirty tracking. That is safe here and
+ * nowhere else, because reads are all this cache serves: the per-connection write path holds real
+ * entity rows and never receives one of these.
+ *
+ * Calling `.Save()` on the result would throw at runtime rather than corrupt anything, which is the
+ * failure mode to want if this contract is ever broken.
+ */
+export declare function AsReadOnlyObject(row: CompanyIntegrationObjectRow): MJIntegrationObjectEntity;
+/** See {@link AsReadOnlyObject}. */
+export declare function AsReadOnlyField(row: CompanyIntegrationObjectFieldRow): MJIntegrationObjectFieldEntity;
+//# sourceMappingURL=CompanyIntegrationCatalog.d.ts.map

package/dist/CompanyIntegrationCatalog.d.ts.map

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

package/dist/CompanyIntegrationCatalog.js

@@ -0,0 +1,185 @@
+/**
+ * The per-connection catalog: read-side types, column contract, and projection.
+ *
+ * Every connector and every engine read site names an IntegrationObject's properties directly —
+ * `io.Name` appears 241 times across the connectors repository, `io.Fields` 93, `io.APIPath` 52.
+ * A row loaded for an entity with no registered subclass is a plain `BaseEntity`: it carries its
+ * values in `Fields` and exposes them through `Get()`, and every one of those property reads is
+ * `undefined`. So the cache cannot hand connectors the entity rows themselves.
+ *
+ * It hands them PROJECTIONS instead — plain objects carrying exactly the property surface the read
+ * sites use. That is not a new idea here: `IntegrationEngineBase.SeedForTesting` already seeds the
+ * shared catalog with "plain objects shaped like the entity (property reads only)" for the same
+ * reason, and the replay tiers exercise metadata-driven connectors through them.
+ *
+ * Writes are the other half and do NOT come through here — they go through the store in
+ * `@memberjunction/integration-engine`, which holds real entity rows and uses `Get()`/`Set()`
+ * exclusively. Assigning `row.Name = x` on a subclass-less `BaseEntity` silently creates an own
+ * property, `Save()` sends nothing, and the write is lost with no error anywhere.
+ */
+export const ENTITY_COMPANY_INTEGRATION_OBJECTS = 'MJ: Company Integration Objects';
+export const ENTITY_COMPANY_INTEGRATION_OBJECT_FIELDS = 'MJ: Company Integration Object Fields';
+/**
+ * Columns the object projection reads. The first 43 are IntegrationObject's own, copied verbatim so
+ * a per-connection row answers every question a shared row answers; the rest are what per-connection
+ * rows add. `IntegrationID` is deliberately among the first group and denormalised onto the table:
+ * connectors read it off the object, and a join per read would be the wrong trade.
+ */
+export const CATALOG_OBJECT_COLUMNS = [
+    'ID', 'IntegrationID', 'Name', 'DisplayName', 'Description', 'Category', 'APIPath',
+    'ResponseDataKey', 'DefaultPageSize', 'SupportsPagination', 'PaginationType',
+    'SupportsIncrementalSync', 'SupportsWrite', 'DefaultQueryParams', 'Configuration', 'Sequence',
+    'Status', 'WriteAPIPath', 'WriteMethod', 'DeleteMethod', 'IsCustom', 'CreateAPIPath',
+    'CreateMethod', 'CreateBodyShape', 'CreateBodyKey', 'CreateIDLocation', 'UpdateAPIPath',
+    'UpdateMethod', 'UpdateBodyShape', 'UpdateBodyKey', 'UpdateIDLocation', 'DeleteAPIPath',
+    'DeleteIDLocation', 'IncrementalWatermarkField', 'MetadataSource', 'SupportsCreate',
+    'SupportsUpdate', 'SupportsDelete', 'SyncStrategy', 'ContentHashApplicable', 'StableOrderingKey',
+    'CompanyIntegrationID', 'IntegrationObjectID', 'Provenance', 'ProvenanceDetail', 'IsSelected',
+    'SelectedAt', 'FirstSeenAt', 'LastSeenAt', 'LastSampledAt',
+];
+/**
+ * Columns the field projection reads. These are all REAL columns on the per-connection field
+ * table — the legacy names `IntegrationObjectID` / `RelatedIntegrationObjectID` are NOT here and
+ * must not be: they are derived in `ProjectCatalogFields` (see FIELD_READ_ALIASES).
+ *
+ * They are derived in TypeScript rather than aliased in the base view because the view is
+ * CodeGen-generated: a hand-added alias column would be silently dropped the next time CodeGen
+ * regenerates it, and the loss would only surface as a schema-mismatch throw much later.
+ */
+export const CATALOG_FIELD_COLUMNS = [
+    'ID', 'Name', 'DisplayName', 'Description', 'Category', 'Type', 'Length', 'Precision', 'Scale',
+    'AllowsNull', 'DefaultValue', 'IsPrimaryKey', 'IsUniqueKey', 'IsReadOnly', 'IsRequired',
+    'RelatedIntegrationObjectFieldName', 'Sequence', 'Configuration', 'Status', 'IsCustom',
+    'MetadataSource', 'CompanyIntegrationObjectID', 'RelatedCompanyIntegrationObjectID',
+    'IntegrationObjectFieldID', 'Provenance', 'ProvenanceDetail', 'IsSelected', 'SelectedAt',
+    'FirstSeenAt', 'LastSeenAt', 'LastSampledAt', 'ObservedMaxLength',
+];
+/**
+ * The three columns of a per-connection field row that the dependency walk reads.
+ *
+ * The walk is the one consumer that needs every field of a connection that points at another
+ * object, and it needs nothing else of them, so those are loaded for the whole connection as plain
+ * rows — never entities — while full field rows are loaded one object at a time. Conflating the two
+ * is what forced the whole catalog to be resident.
+ */
+export const CATALOG_EDGE_COLUMNS = ['ID', 'CompanyIntegrationObjectID', 'RelatedCompanyIntegrationObjectID'];
+/**
+ * Legacy read names mapped onto their per-connection columns.
+ *
+ * A connector resolving a dependency edge reads `f.RelatedIntegrationObjectID` and matches it
+ * against its sibling objects (e.g. Rhythm, PathLMS). Deriving these keeps that code working
+ * unchanged while the value it gets is the per-connection id.
+ */
+const FIELD_READ_ALIASES = [
+    ['IntegrationObjectID', 'CompanyIntegrationObjectID'],
+    ['RelatedIntegrationObjectID', 'RelatedCompanyIntegrationObjectID'],
+];
+/**
+ * Columns whose value the CONNECTOR declares (metadata/ folder), as opposed to columns the
+ * connection owns or discovery decides.
+ *
+ * plan.md requires that a schema refresh treat IO/IOF as the source of truth and REPLACE what is
+ * in CIO/CIOF rather than layering on it: "it will use IO/IOF as the SOT before then replacing
+ * what is in the respective CIO/CIOF, it will not do the changes on top of CIO/CIOF since it is
+ * stale metadata". Without that, an open-app upgrade that changes a declared APIPath or page size
+ * would never reach a connection that had already discovered once — the stale per-connection value
+ * would win every subsequent overlay.
+ *
+ * Derived by SUBTRACTION so it cannot drift when a column is added: anything not explicitly
+ * identity, per-connection state, or discovery-owned lifecycle is connector-declared.
+ * Description / DisplayName / IncrementalWatermarkField are deliberately IN this set — they are
+ * rebased from the declaration and then discovery overlays them if it reports a value, which is
+ * exactly the documented precedence.
+ */
+const NOT_DECLARED_OWNED = new Set([
+    // identity and linkage
+    'ID', 'IntegrationID', 'Name',
+    'CompanyIntegrationID', 'IntegrationObjectID',
+    'CompanyIntegrationObjectID', 'RelatedCompanyIntegrationObjectID', 'IntegrationObjectFieldID',
+    // per-connection state
+    'Provenance', 'ProvenanceDetail', 'IsSelected', 'SelectedAt',
+    'FirstSeenAt', 'LastSeenAt', 'LastSampledAt', 'ObservedMaxLength',
+    // decided by discovery, not declared
+    'Status', 'IsCustom', 'MetadataSource',
+]);
+export const DECLARED_OWNED_OBJECT_COLUMNS = CATALOG_OBJECT_COLUMNS.filter(c => !NOT_DECLARED_OWNED.has(c));
+export const DECLARED_OWNED_FIELD_COLUMNS = CATALOG_FIELD_COLUMNS.filter(c => !NOT_DECLARED_OWNED.has(c));
+/**
+ * Thrown when the loaded entity is missing columns this code requires — the migration is absent or
+ * an older version of it ran. Failing here names the problem; letting it through would produce rows
+ * whose per-connection columns are all `undefined`, which reads downstream as "no selection, no
+ * provenance, never seen" and is indistinguishable from a legitimately empty catalog.
+ */
+export class CompanyIntegrationCatalogSchemaMismatch extends Error {
+    constructor(entityName, missing) {
+        super(`${entityName} is missing ${missing.length} required column(s): ${missing.join(', ')}. `
+            + `The per-connection catalog migration has not been applied to this database, or the `
+            + `applied version predates these columns.`);
+        this.Code = 'PER_CONNECTION_CATALOG_SCHEMA_MISMATCH';
+        this.name = 'CompanyIntegrationCatalogSchemaMismatch';
+    }
+}
+/** Names present on a loaded row, whether the value is set or not. */
+function fieldNamesOf(row) {
+    return new Set((row.Fields ?? []).map(f => f.Name));
+}
+/**
+ * Verify a loaded row carries every column we read. Called once per array load — the cost is one
+ * pass over one row's field list, and the alternative is a silent wrong answer.
+ */
+export function AssertCatalogColumns(entityName, row, required) {
+    const present = fieldNamesOf(row);
+    const missing = required.filter(c => !present.has(c));
+    if (missing.length > 0)
+        throw new CompanyIntegrationCatalogSchemaMismatch(entityName, missing);
+}
+function project(row, columns) {
+    const out = {};
+    for (const c of columns)
+        out[c] = row.Get(c);
+    return out;
+}
+/**
+ * Project loaded object rows for the read path. Validates the column set against the FIRST row
+ * only: every row in the array is the same entity, so one is proof, and an empty array proves
+ * nothing and needs no check — a connection with no catalog rows is the ordinary pre-discovery
+ * state, not a schema problem.
+ */
+export function ProjectCatalogObjects(rows) {
+    if (rows.length > 0) {
+        AssertCatalogColumns(ENTITY_COMPANY_INTEGRATION_OBJECTS, rows[0], CATALOG_OBJECT_COLUMNS);
+    }
+    return rows.map(r => project(r, CATALOG_OBJECT_COLUMNS));
+}
+/** Project loaded field rows for the read path. Same validation rule as the object projection. */
+export function ProjectCatalogFields(rows) {
+    if (rows.length > 0) {
+        AssertCatalogColumns(ENTITY_COMPANY_INTEGRATION_OBJECT_FIELDS, rows[0], CATALOG_FIELD_COLUMNS);
+    }
+    return rows.map(r => {
+        const projected = project(r, CATALOG_FIELD_COLUMNS);
+        for (const [alias, source] of FIELD_READ_ALIASES)
+            projected[alias] = projected[source];
+        return projected;
+    });
+}
+/**
+ * Present a projection to code typed against the shared catalog entities.
+ *
+ * The two casts below are the ONLY place this narrowing happens, deliberately, so the reasoning
+ * sits in one auditable spot. A projection carries every property the read sites touch and none of
+ * `BaseEntity`'s behaviour — no `Save()`, no `Fields`, no dirty tracking. That is safe here and
+ * nowhere else, because reads are all this cache serves: the per-connection write path holds real
+ * entity rows and never receives one of these.
+ *
+ * Calling `.Save()` on the result would throw at runtime rather than corrupt anything, which is the
+ * failure mode to want if this contract is ever broken.
+ */
+export function AsReadOnlyObject(row) {
+    return row;
+}
+/** See {@link AsReadOnlyObject}. */
+export function AsReadOnlyField(row) {
+    return row;
+}
+//# sourceMappingURL=CompanyIntegrationCatalog.js.map

package/dist/CompanyIntegrationCatalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CompanyIntegrationCatalog.js","sourceRoot":"","sources":["../src/CompanyIntegrationCatalog.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,CAAC,MAAM,kCAAkC,GAAG,iCAAiC,CAAC;AACpF,MAAM,CAAC,MAAM,wCAAwC,GAAG,uCAAuC,CAAC;AAEhG;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IAClC,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,aAAa,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS;IAClF,iBAAiB,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,gBAAgB;IAC5E,yBAAyB,EAAE,eAAe,EAAE,oBAAoB,EAAE,eAAe,EAAE,UAAU;IAC7F,QAAQ,EAAE,cAAc,EAAE,aAAa,EAAE,cAAc,EAAE,UAAU,EAAE,eAAe;IACpF,cAAc,EAAE,iBAAiB,EAAE,eAAe,EAAE,kBAAkB,EAAE,eAAe;IACvF,cAAc,EAAE,iBAAiB,EAAE,eAAe,EAAE,kBAAkB,EAAE,eAAe;IACvF,kBAAkB,EAAE,2BAA2B,EAAE,gBAAgB,EAAE,gBAAgB;IACnF,gBAAgB,EAAE,gBAAgB,EAAE,cAAc,EAAE,uBAAuB,EAAE,mBAAmB;IAChG,sBAAsB,EAAE,qBAAqB,EAAE,YAAY,EAAE,kBAAkB,EAAE,YAAY;IAC7F,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,eAAe;CACpD,CAAC;AAEX;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACjC,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO;IAC9F,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY;IACvF,mCAAmC,EAAE,UAAU,EAAE,eAAe,EAAE,QAAQ,EAAE,UAAU;IACtF,gBAAgB,EAAE,4BAA4B,EAAE,mCAAmC;IACnF,0BAA0B,EAAE,YAAY,EAAE,kBAAkB,EAAE,YAAY,EAAE,YAAY;IACxF,aAAa,EAAE,YAAY,EAAE,eAAe,EAAE,mBAAmB;CAC3D,CAAC;AAEX;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,IAAI,EAAE,4BAA4B,EAAE,mCAAmC,CAAU,CAAC;AAuCvH;;;;;;GAMG;AACH,MAAM,kBAAkB,GAA4D;IAChF,CAAC,qBAAqB,EAAE,4BAA4B,CAAC;IACrD,CAAC,4BAA4B,EAAE,mCAAmC,CAAC;CAC7D,CAAC;AAEX;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAS;IACvC,uBAAuB;IACvB,IAAI,EAAE,eAAe,EAAE,MAAM;IAC7B,sBAAsB,EAAE,qBAAqB;IAC7C,4BAA4B,EAAE,mCAAmC,EAAE,0BAA0B;IAC7F,uBAAuB;IACvB,YAAY,EAAE,kBAAkB,EAAE,YAAY,EAAE,YAAY;IAC5D,aAAa,EAAE,YAAY,EAAE,eAAe,EAAE,mBAAmB;IACjE,qCAAqC;IACrC,QAAQ,EAAE,UAAU,EAAE,gBAAgB;CACzC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,6BAA6B,GACtC,sBAAsB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAEnE,MAAM,CAAC,MAAM,4BAA4B,GACrC,qBAAqB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAsElE;;;;;GAKG;AACH,MAAM,OAAO,uCAAwC,SAAQ,KAAK;IAE9D,YAAY,UAAkB,EAAE,OAAiB;QAC7C,KAAK,CACD,GAAG,UAAU,eAAe,OAAO,CAAC,MAAM,wBAAwB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;cACtF,qFAAqF;cACrF,yCAAyC,CAC9C,CAAC;QANU,SAAI,GAAG,wCAAwC,CAAC;QAO5D,IAAI,CAAC,IAAI,GAAG,yCAAyC,CAAC;IAC1D,CAAC;CACJ;AAED,sEAAsE;AACtE,SAAS,YAAY,CAAC,GAAe;IACjC,OAAO,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AACxD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,UAAkB,EAAE,GAAe,EAAE,QAA2B;IACjG,MAAM,OAAO,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IAClC,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACtD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,IAAI,uCAAuC,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;AACnG,CAAC;AAED,SAAS,OAAO,CAAI,GAAe,EAAE,OAA0B;IAC3D,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,IAAI,OAAO;QAAE,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC7C,OAAO,GAAQ,CAAC;AACpB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAkB;IACpD,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClB,oBAAoB,CAAC,kCAAkC,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,sBAAsB,CAAC,CAAC;IAC9F,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAA8B,CAAC,EAAE,sBAAsB,CAAC,CAAC,CAAC;AAC1F,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,oBAAoB,CAAC,IAAkB;IACnD,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClB,oBAAoB,CAAC,wCAAwC,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,qBAAqB,CAAC,CAAC;IACnG,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE;QAChB,MAAM,SAAS,GAAG,OAAO,CAA0B,CAAC,EAAE,qBAAqB,CAAC,CAAC;QAC7E,KAAK,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,kBAAkB;YAAE,SAAS,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;QACvF,OAAO,SAAwD,CAAC;IACpE,CAAC,CAAC,CAAC;AACP,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAgC;IAC7D,OAAO,GAA2C,CAAC;AACvD,CAAC;AAED,oCAAoC;AACpC,MAAM,UAAU,eAAe,CAAC,GAAqC;IACjE,OAAO,GAAgD,CAAC;AAC5D,CAAC"}