@intentius/chant-lexicon-sql 0.124.46 → 0.124.48

package/dist/clickhouse/named-collections.js

@@ -0,0 +1,203 @@
+/**
+ * Named collections, referenced by name (#4395).
+ *
+ * A named collection holds an integration's connection settings and its
+ * credentials. Those are the environment's, so chant never declares one and
+ * never reads its values (the coverage table's `referenced` status,
+ * `../coverage/clickhouse.json`). A declaration may name one where the server
+ * takes a collection in place of inline arguments:
+ *
+ * - an integration engine's first argument: `ENGINE = S3(lake_creds, format = 'Parquet')`,
+ *   `ENGINE = Kafka(kafka_creds)`, a database's `ENGINE = PostgreSQL(pg_creds)`;
+ * - a table function's first argument: `AS s3(lake_creds)`, `SELECT ... FROM mysql(mysql_creds, table = 't')`;
+ * - a dictionary source's `NAME`: `SOURCE(MYSQL(NAME mysql_creds))`.
+ *
+ * The build records each reference (`namedCollections` on the object and on
+ * the document, `../serializer.ts`), and `chant sql plan` checks that every
+ * one exists on the server by name (`./plan/commands.ts`).
+ */
+import { DATABASE_ENGINES, TABLE_ENGINES, TABLE_FUNCTIONS } from "../generated/clickhouse.js";
+import { unquoteWith } from "../core/cursor.js";
+import { isTrivia, tokenizeText } from "./tokens.js";
+/**
+ * The table and database engines whose first argument may be a named
+ * collection, as the 26.8 reference documents them for each engine.
+ * Filtered to the engines the pinned server has.
+ */
+const COLLECTION_ENGINE_NAMES = [
+    "S3",
+    "S3Queue",
+    "AzureBlobStorage",
+    "AzureQueue",
+    "Iceberg",
+    "IcebergS3",
+    "IcebergAzure",
+    "DeltaLake",
+    "DeltaLakeS3",
+    "DeltaLakeAzure",
+    "Hudi",
+    "Paimon",
+    "PaimonS3",
+    "HDFS",
+    "URL",
+    "Kafka",
+    "RabbitMQ",
+    "NATS",
+    "MySQL",
+    "PostgreSQL",
+    "MaterializedPostgreSQL",
+    "MongoDB",
+    "Redis",
+    "ArrowFlight",
+    "YTsaurus",
+    "DataLakeCatalog",
+];
+const ENGINES = { ...TABLE_ENGINES, ...DATABASE_ENGINES };
+/** The engines a named collection may be the first argument of. */
+export const COLLECTION_ENGINES = new Set(COLLECTION_ENGINE_NAMES.filter((n) => n in ENGINES));
+/**
+ * The table functions a named collection may be the first argument of, lower
+ * case. A `...Cluster` function's first argument is the cluster, so those are
+ * left out.
+ */
+export const COLLECTION_FUNCTIONS = new Set(TABLE_FUNCTIONS.filter((f) => !/Cluster$/.test(f) && /^(s3|gcs|oss|cosn|url|hdfs|mysql|postgresql|mongodb|redis|remote|azureblobstorage|iceberg|deltalake|hudi|paimon|arrowflight|ytsaurus)/i.test(f)).map((f) => f.toLowerCase()));
+/** `lake_creds` or `` `lake creds` ``: an identifier, not a string, a call or `key = value`. */
+function identifierName(text) {
+    const t = text.trim();
+    if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(t))
+        return t.toUpperCase() === "NOSIGN" ? undefined : t;
+    if (/^`(?:[^`\\]|\\.)+`$/.test(t))
+        return unquoteWith(t, "`");
+    return undefined;
+}
+/** The collection an engine names in its first argument, when it is one of the engines that take one. */
+export function engineCollection(engine) {
+    if (!engine || !COLLECTION_ENGINES.has(engine.name) || !engine.args || engine.args.length === 0)
+        return undefined;
+    return identifierName(engine.args[0]);
+}
+const significant = (text) => {
+    try {
+        return tokenizeText(text, 0).filter((t) => !isTrivia(t));
+    }
+    catch {
+        return [];
+    }
+};
+/** The collections a SQL text's table function calls name: `s3(lake_creds, ...)`, `mysql(mysql_creds)`. */
+export function functionCollections(text) {
+    const tokens = significant(text);
+    const out = [];
+    for (let i = 0; i + 3 < tokens.length; i++) {
+        const [fn, open, arg, after] = [tokens[i], tokens[i + 1], tokens[i + 2], tokens[i + 3]];
+        if (fn.kind !== "ident" || !COLLECTION_FUNCTIONS.has(fn.text.toLowerCase()))
+            continue;
+        if (open.kind !== "punct" || open.text !== "(")
+            continue;
+        if (tokens[i - 1]?.kind === "punct" && tokens[i - 1].text === ".")
+            continue;
+        if (arg.kind !== "ident" && arg.kind !== "qident")
+            continue;
+        if (after.kind !== "punct" || (after.text !== "," && after.text !== ")"))
+            continue;
+        const name = identifierName(arg.text);
+        if (name)
+            out.push(name);
+    }
+    return out;
+}
+/** The collection a dictionary source names: `MYSQL(NAME mysql_creds)`. */
+export function sourceCollections(dataSource) {
+    const tokens = significant(dataSource);
+    const out = [];
+    for (let i = 0; i + 1 < tokens.length; i++) {
+        if (tokens[i].kind !== "ident" || tokens[i].text.toUpperCase() !== "NAME")
+            continue;
+        const v = tokens[i + 1];
+        if (v.kind === "ident" || v.kind === "qident")
+            out.push(v.kind === "qident" ? unquoteWith(v.text, '`"') : v.text);
+        else if (v.kind === "string")
+            out.push(unquoteWith(v.text, "'"));
+    }
+    return out;
+}
+/** Every named collection an object names, once each, in the order written. */
+export function namedCollectionReferences(o) {
+    const names = [
+        ...(engineCollection(o.engine) !== undefined ? [engineCollection(o.engine)] : []),
+        ...(o.asFunction ? functionCollections(o.asFunction) : []),
+        ...(o.select ? functionCollections(o.select) : []),
+        ...(o.dataSource ? sourceCollections(o.dataSource) : []),
+    ];
+    return [...new Set(names)];
+}
+/** `CREATE NAMED COLLECTION [IF NOT EXISTS] name ...`: the name, or undefined for another statement. */
+export function createdCollectionName(sql) {
+    const m = /^\s*CREATE\s+NAMED\s+COLLECTION\s+(?:IF\s+NOT\s+EXISTS\s+)?(`(?:[^`\\]|\\.)+`|"(?:[^"\\]|\\.)+"|[A-Za-z_][A-Za-z0-9_]*)/i.exec(sql);
+    return m ? unquoteWith(m[1], '`"') : undefined;
+}
+/**
+ * The collections a whole statement names, read off its tokens: what
+ * {@link namedCollectionReferences} reads from a parsed declaration, for a
+ * statement import has only as text (`SHOW CREATE`).
+ */
+export function statementCollections(ddl) {
+    const tokens = significant(ddl);
+    const out = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const t = tokens[i];
+        if (t.kind !== "ident")
+            continue;
+        const word = t.text.toUpperCase();
+        if (word === "ENGINE" && tokens[i + 1]?.text === "=" && tokens[i + 3]?.text === "(") {
+            const engine = tokens[i + 2];
+            const arg = tokens[i + 4];
+            const after = tokens[i + 5];
+            if (COLLECTION_ENGINES.has(engine.text) && arg && (arg.kind === "ident" || arg.kind === "qident") && (after?.text === "," || after?.text === ")")) {
+                const name = identifierName(arg.text);
+                if (name)
+                    out.push(name);
+            }
+        }
+        else if (word === "SOURCE" && tokens[i + 1]?.text === "(") {
+            let depth = 0;
+            let j = i + 1;
+            for (; j < tokens.length; j++) {
+                if (tokens[j].text === "(")
+                    depth++;
+                else if (tokens[j].text === ")" && --depth === 0)
+                    break;
+            }
+            out.push(...sourceCollections(tokens.slice(i + 2, j).map((x) => x.text).join(" ")));
+            i = j;
+        }
+    }
+    out.push(...functionCollections(ddl));
+    return [...new Set(out)];
+}
+/**
+ * The named collections an import found as prerequisites (#4395), each with
+ * the imported objects that name it, and a warning for each. A collection an
+ * imported object names that was not found is listed too: a live reader
+ * without `SHOW NAMED COLLECTIONS` sees none.
+ */
+export function namedCollectionPrerequisites(found, objects, wording) {
+    const by = new Map(found.map((o) => [o.name, []]));
+    for (const o of objects) {
+        for (const c of statementCollections(o.ddl)) {
+            if (!by.has(c))
+                by.set(c, []);
+            by.get(c).push(o.database ? `${o.database}.${o.name}` : o.name);
+        }
+    }
+    const prerequisites = [...by]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([name, referencedBy]) => ({ kind: "named collection", name, referencedBy }));
+    const seen = new Set(found.map((o) => o.name));
+    const warnings = prerequisites.map((p) => {
+        const used = p.referencedBy.length > 0 ? `, named by ${p.referencedBy.join(", ")}` : "";
+        return (`named collection ${p.name} is a prerequisite${wording.of ? ` of ${wording.of}` : ""}${used}: ${seen.has(p.name) ? wording.found : wording.unseen}, ` +
+            "and chant does not declare it or read its values. Create it on every server the project applies to; chant sql plan checks that it exists");
+    });
+    return { prerequisites, warnings };
+}

package/dist/clickhouse/parser.d.ts.map

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

package/dist/clickhouse/parser.js

@@ -51,7 +51,7 @@ export const REFUSED_CREATE_KINDS = [
     {
         words: ["NAMED", "COLLECTION"],
         kind: "NAMED COLLECTION",
-        reason: "a named collection holds credentials (a password, a secret key), which are the environment's and never in a build; the server hides its values, so a plan could not compare them either. Create it from the server's configuration or by hand",
+        reason: "a named collection holds credentials (a password, a secret key), which are the environment's and never in a build. Create it on the server, and name it where it is used: ENGINE = S3(lake_creds, format = 'Parquet'), s3(lake_creds), SOURCE(MYSQL(NAME mysql_creds)). A plan checks that it exists",
     },
     { words: ["MASKING", "POLICY"], kind: "MASKING POLICY", reason: "masking policies are available only in ClickHouse Cloud, not on the pinned server" },
     { words: ["WORKLOAD"], kind: "WORKLOAD", reason: "a workload is server-level scheduling, configured with the server, not a schema object" },

package/dist/clickhouse/plan/commands.d.ts

@@ -13,7 +13,8 @@
  * expressions the rules leave different. Both exit 2 when a change needs a
  * rebuild, which a plan refuses to make in place, and `plan` also when the
  * declared databases hold an object whose definition it cannot read (#3653),
- * which it names; 0 otherwise. For each
+ * which it names, or when the build references a named collection the
+ * server does not have (#4395), which it names; 0 otherwise. For each
  * refused table they name the `ClickHouseRebuildOp` to run instead
  * (`rebuildOps` in `--json`, `./rebuild-handoff.ts`).
  *

package/dist/clickhouse/plan/commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../../src/clickhouse/plan/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAC5F,OAAO,EAAe,KAAK,UAAU,EAAwB,MAAM,QAAQ,CAAC;AAM5E,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAyD9C,wBAAsB,OAAO,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsBvE;AAED,mFAAmF;AACnF,wBAAsB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,CAAC,CAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAyBvJ;AAED,wBAAsB,OAAO,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAYvE;AAED,eAAO,MAAM,WAAW,EAAE,YAYzB,CAAC"}
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../../src/clickhouse/plan/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAC5F,OAAO,EAAe,KAAK,UAAU,EAAwB,MAAM,QAAQ,CAAC;AAM5E,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AA0D9C,wBAAsB,OAAO,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsBvE;AAED,mFAAmF;AACnF,wBAAsB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,CAAC,CAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CA4BvJ;AAED,wBAAsB,OAAO,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAYvE;AAED,eAAO,MAAM,WAAW,EAAE,YAsBzB,CAAC"}

package/dist/clickhouse/plan/commands.js

@@ -13,7 +13,8 @@
  * expressions the rules leave different. Both exit 2 when a change needs a
  * rebuild, which a plan refuses to make in place, and `plan` also when the
  * declared databases hold an object whose definition it cannot read (#3653),
- * which it names; 0 otherwise. For each
+ * which it names, or when the build references a named collection the
+ * server does not have (#4395), which it names; 0 otherwise. For each
  * refused table they name the `ClickHouseRebuildOp` to run instead
  * (`rebuildOps` in `--json`, `./rebuild-handoff.ts`).
  *
@@ -38,6 +39,7 @@ import { bindClickHouse } from "../live/bind.js";
 import { rebuildOpSuggestions } from "./rebuild-handoff.js";
 import { readFileSync } from "node:fs";
 import { parseTopology } from "../topology.js";
+import { checkNamedCollections, namedCollectionsFail, referencedCollectionsOf } from "../live/named-collections.js";
 /** The dialect a build output names. */
 function outputDialect(path) {
     try {
@@ -81,7 +83,7 @@ async function runDiffStatements(before, after, json, topology) {
 }
 function emit(diff, json, title) {
     console.log(json ? JSON.stringify(diff, null, 2) : renderDiff(diff, { title }));
-    return diff.rebuilds.length > 0 || (diff.unreadable?.length ?? 0) > 0 ? 2 : 0;
+    return diff.rebuilds.length > 0 || (diff.unreadable?.length ?? 0) > 0 || namedCollectionsFail(diff.namedCollections) ? 2 : 0;
 }
 export async function runDiff(ctx) {
     const { positional, json, statements, topology: topologyArg } = split(ctx.rawArgs);
@@ -121,6 +123,8 @@ export async function planAgainstServer(environment, buildFile, options = {}) {
     const diff = diffSchemas(live, declared);
     const changes = await dropFormattingOnly(target.endpoint, diff.changes);
     const rebuildOps = rebuildOpSuggestions({ ...diff, changes, rebuilds: changes.filter((c) => c.class === "rebuild") }, new Map(declared.map((o) => [o.key, o.canonical])), environment);
+    // Each named collection the build references must exist on the server, by name; its values are never read (#4395).
+    const namedCollections = await checkNamedCollections(target.endpoint, referencedCollectionsOf(buildFile));
     const label = new Map(declared.map((o) => [o.key, o.exportName === o.key ? o.key : `${o.exportName} (${o.key})`]));
     const relabel = changes.map((c) => ({ ...c, object: label.get(c.object) ?? c.object }));
     return {
@@ -129,6 +133,7 @@ export async function planAgainstServer(environment, buildFile, options = {}) {
         hints: unmanaged > 0 ? [...diff.hints, accessUnmanagedHint(unmanaged, environment)] : diff.hints,
         ...(rebuildOps.length > 0 ? { rebuildOps } : {}),
         ...(unreadable.length > 0 ? { unreadable } : {}),
+        ...(namedCollections ? { namedCollections } : {}),
     };
 }
 export async function runPlan(ctx) {
@@ -155,5 +160,15 @@ export const sqlCommands = {
             description: "Write sql-types.d.ts: typed columns for each table, view and dictionary the build declares, for tags given their name (table<\"app.users\">) and RowOf; --output <path> writes it elsewhere; --check compares instead of writing and exits 1 when the file differs",
             handler: async (ctx) => (await import("../../sql-types-command.js")).runTypes(ctx),
         },
+        {
+            name: "replay",
+            description: "Replay a goose, golang-migrate, clickhouse-migrations or Flyway directory into the empty server --env binds, and record the tables and columns it makes as chant.replay.json; --check compares instead of writing",
+            handler: async (ctx) => (await import("../../migration-replay.js")).runReplay(ctx),
+        },
+        {
+            name: "drizzle",
+            description: "Write a Drizzle schema module (drizzle-schema.ts) from a Postgres build: pgTable per table with columns, keys, indexes, enums, sequences and views, so an application queries with Drizzle's row types while chant owns the schema; --output <path> writes it elsewhere; --check compares instead of writing and exits 1 when the file differs; --bigint bigint reads bigint columns as bigint, not number",
+            handler: async (ctx) => (await import("../../drizzle-command.js")).runDrizzle(ctx),
+        },
     ],
 };

package/dist/clickhouse/plan/diff.d.ts

@@ -33,6 +33,21 @@ export interface SchemaDiff extends ChangeSet<Change> {
      * it out.
      */
     unreadable?: UnreadableEntry[];
+    /**
+     * The named collections the build references, checked against the server
+     * by name (#4395). A plan with one `missing`, or whose check could not run
+     * (`unread`), fails naming it. Their values are never read.
+     */
+    namedCollections?: NamedCollectionCheck;
+}
+/** What a plan found of the named collections a build references: each by name, never its values. */
+export interface NamedCollectionCheck {
+    /** Every collection the build names, sorted. */
+    referenced: string[];
+    /** Those the server has no collection of, or that the plan's user may not see. */
+    missing: string[];
+    /** Why the server's collections could not be read, when they could not. */
+    unread?: string;
 }
 /** An object a plan could not read: `database.name`, its type and why. */
 export interface UnreadableEntry {

package/dist/clickhouse/plan/diff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../../src/clickhouse/plan/diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAoB,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,SAAS,CAAC;AACpF,OAAO,KAAK,EAAmB,eAAe,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE7D,OAAO,EAAoB,KAAK,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAChG,OAAO,EAAmC,KAAK,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAE9E,MAAM,MAAM,YAAY,GAAG,KAAK,CAAC,eAAe,CAAC,CAAC;AAElD,MAAM,MAAM,MAAM,GAAG,gBAAgB,CAAC,gBAAgB,EAAE,WAAW,CAAC,CAAC;AAErE,MAAM,WAAW,UAAW,SAAQ,SAAS,CAAC,MAAM,CAAC;IACnD,wDAAwD;IACxD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,6GAA6G;IAC7G,UAAU,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACnC;;;;OAIG;IACH,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;CAChC;AAED,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAgQD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,EAAE,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,UAAU,CAqBvG"}
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../../src/clickhouse/plan/diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAoB,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,SAAS,CAAC;AACpF,OAAO,KAAK,EAAmB,eAAe,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAG7D,OAAO,EAAoB,KAAK,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAChG,OAAO,EAAmC,KAAK,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAE9E,MAAM,MAAM,YAAY,GAAG,KAAK,CAAC,eAAe,CAAC,CAAC;AAElD,MAAM,MAAM,MAAM,GAAG,gBAAgB,CAAC,gBAAgB,EAAE,WAAW,CAAC,CAAC;AAErE,MAAM,WAAW,UAAW,SAAQ,SAAS,CAAC,MAAM,CAAC;IACnD,wDAAwD;IACxD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,6GAA6G;IAC7G,UAAU,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACnC;;;;OAIG;IACH,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;IAC/B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,oBAAoB,CAAC;CACzC;AAED,qGAAqG;AACrG,MAAM,WAAW,oBAAoB;IACnC,gDAAgD;IAChD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,kFAAkF;IAClF,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AA4RD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,EAAE,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,UAAU,CAgCvG"}

package/dist/clickhouse/plan/diff.js

@@ -17,6 +17,7 @@
  */
 import { CLASSIFIER_RULES } from "./rules.js";
 import { MERGE_TREE_SETTINGS } from "../../generated/clickhouse.js";
+import { isStreamEngine, isStreamTable, positionWarnings, readsTable } from "./stream.js";
 import { classifiedChange } from "../../core/classifier.js";
 import { changedEntries, matchByIdentity } from "../../core/diff.js";
 const qualified = (o) => (o.database ? `${o.database}.${o.name}` : o.name);
@@ -203,9 +204,14 @@ function diffObject(key, before, after, out, hints) {
         diffTableFunction(key, before, after, out);
         return;
     }
+    // A stream table (#4396): replaced, not altered, and not rebuilt, since it holds no rows.
+    if (isStreamTable(before) && isStreamTable(after)) {
+        diffStreamTable(key, before, after, out);
+        return;
+    }
     // A table.
     if (before.engine !== after.engine)
-        out.push(change(key, "engine", "SQLCH223", before.engine, after.engine));
+        out.push(change(key, "engine", "SQLCH223", before.engine, after.engine, isStreamEngine(before.engineName) || isStreamEngine(after.engineName) ? { note: "one side is a stream engine and the other is not, which is a different kind of table: neither the replace nor the rebuild applies" } : {}));
     const added = diffColumns(key, before, after, out, hints);
     const beforePk = before.primaryKey ?? before.orderBy;
     const afterPk = after.primaryKey ?? after.orderBy;
@@ -234,6 +240,32 @@ function diffObject(key, before, after, out, hints) {
     diffMap(key, "projections", before.projections, after.projections, "SQLCH214", out);
     diffMap(key, "constraints", before.constraints, after.constraints, "SQLCH215", out);
 }
+/**
+ * A table on a stream engine, on both sides (#4396). Its engine, its settings
+ * and its columns are all replaced the same way (SQLCH225); the comment is
+ * compared before this. A change that loses the table's position says so in
+ * its note.
+ */
+function diffStreamTable(key, before, after, out) {
+    const start = out.length;
+    if (before.engine !== after.engine)
+        out.push(change(key, "engine", "SQLCH225", before.engine, after.engine));
+    for (const name of changedEntries(before.settings, after.settings))
+        out.push(change(key, `settings.${name}`, "SQLCH225", before.settings[name], after.settings[name]));
+    const column = (c) => [c.type, c.nullable ? "NULL" : "", c.defaultKind ?? "", c.defaultExpr ?? "", c.codec ? `CODEC(${c.codec})` : ""].filter(Boolean).join(" ");
+    const b = new Map(before.columns.map((c) => [c.name, column(c)]));
+    const a = new Map(after.columns.map((c) => [c.name, column(c)]));
+    for (const name of new Set([...b.keys(), ...a.keys()])) {
+        if (b.get(name) !== a.get(name))
+            out.push(change(key, `columns.${name}`, "SQLCH225", b.get(name), a.get(name)));
+    }
+    const order = (o) => o.columns.map((c) => c.name).join(", ");
+    if (order(before) !== order(after) && a.size === b.size && [...a.keys()].every((n) => b.has(n)))
+        out.push(change(key, "columns.order", "SQLCH225", order(before), order(after)));
+    const warnings = positionWarnings(before, after);
+    if (warnings.length > 0 && out.length > start)
+        out[start] = { ...out[start], note: `loses its position: ${warnings.join("; ")}` };
+}
 /**
  * A table over a table function (#3911), on either side. It stores nothing,
  * so every change but its comment replaces it (SQLCH219); a table with data
@@ -308,5 +340,15 @@ export function diffSchemas(before, after) {
             changes.push(change(b.key, "object", "SQLCH250", qualified(b.canonical), undefined, { destructive: b.canonical.kind === "table" || b.canonical.kind === "materializedView" }));
         }
     }
+    // A replaced stream table is replaced around the views that read it (#4396): say which.
+    const replaced = new Set(changes.filter((c) => c.rule === "SQLCH225").map((c) => c.object));
+    for (const m of matches) {
+        if (m.kind !== "matched" || !replaced.has(m.after.key))
+            continue;
+        const readers = before.filter((o) => readsTable(o.canonical, m.before.canonical)).map((o) => qualified(o.canonical));
+        hints.push(readers.length > 0
+            ? `${qualified(m.before.canonical)} is replaced: ${readers.join(", ")} ${readers.length === 1 ? "reads it and is" : "read it and are"} detached first and attached after`
+            : `${qualified(m.before.canonical)} is replaced; no materialized view reads it`);
+    }
     return { changes, rebuilds: changes.filter((c) => c.class === "rebuild"), hints };
 }

package/dist/clickhouse/plan/disruption.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"disruption.d.ts","sourceRoot":"","sources":["../../../src/clickhouse/plan/disruption.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAqChG,wBAAgB,kBAAkB,CAAC,OAAO,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,eAAe,EAAE,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAWlI"}
+{"version":3,"file":"disruption.d.ts","sourceRoot":"","sources":["../../../src/clickhouse/plan/disruption.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AA0ChG,wBAAgB,kBAAkB,CAAC,OAAO,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,eAAe,EAAE,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAWlI"}

package/dist/clickhouse/plan/disruption.js

@@ -12,6 +12,8 @@
 import { MERGE_TREE_SETTINGS } from "../../generated/clickhouse.js";
 import { classifyDisruptionWith } from "../../core/classifier.js";
 import { CHANGE_CLASSES, CLASSIFIER_RULES } from "./rules.js";
+/** Settings only a stream engine takes; the path alone cannot name the engine. */
+const STREAM_SETTING = /^(?:kafka_|rabbitmq_|nats_|s3queue_|azure_queue_|keeper_path$)/;
 function ruleFor(path) {
     const root = path.split(/[.[]/)[0];
     if (root === "name" || root === "database")
@@ -42,6 +44,9 @@ function ruleFor(path) {
         return "SQLCH244";
     if (root === "settings") {
         const key = path.split(".")[1];
+        // A stream engine's own settings (Kafka, RabbitMQ, NATS, S3Queue's keeper_path) have no MODIFY SETTING: the table is replaced (#4396).
+        if (key !== undefined && STREAM_SETTING.test(key))
+            return "SQLCH225";
         const spec = key ? MERGE_TREE_SETTINGS[key] : undefined;
         return spec?.readonly ? "SQLCH218" : "SQLCH206";
     }

package/dist/clickhouse/plan/rebuild-handoff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rebuild-handoff.d.ts","sourceRoot":"","sources":["../../../src/clickhouse/plan/rebuild-handoff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAuC,KAAK,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAGrG,MAAM,WAAW,mBAAoB,SAAQ,qBAAqB;IAChE,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE;QAAE,IAAI,EAAE,mBAAmB,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,KAAK,CAAA;KAAE,CAAC;IAClF,2GAA2G;IAC3G,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAID;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,mBAAmB,EAAE,CA0BzI;AAED,+CAA+C;AAC/C,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,SAAS,mBAAmB,EAAE,GAAG,MAAM,EAAE,CAG9E"}
+{"version":3,"file":"rebuild-handoff.d.ts","sourceRoot":"","sources":["../../../src/clickhouse/plan/rebuild-handoff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAuC,KAAK,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAIrG,MAAM,WAAW,mBAAoB,SAAQ,qBAAqB;IAChE,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE;QAAE,IAAI,EAAE,mBAAmB,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,KAAK,CAAA;KAAE,CAAC;IAClF,2GAA2G;IAC3G,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAID;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,mBAAmB,EAAE,CA4BzI;AAED,+CAA+C;AAC/C,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,SAAS,mBAAmB,EAAE,GAAG,MAAM,EAAE,CAG9E"}

package/dist/clickhouse/plan/rebuild-handoff.js

@@ -16,6 +16,7 @@
  * suggestion are ClickHouse's.
  */
 import { migrationOpName, renderMigrationOps } from "../../core/handoff.js";
+import { isStreamEngine } from "./stream.js";
 import { collapsesRows } from "../rebuild/engines.js";
 const TIME_TYPE = /^(?:Nullable\s*\(\s*)?(?:Date|Date32|DateTime|DateTime64)\b/;
 /**
@@ -29,6 +30,9 @@ export function rebuildOpSuggestions(diff, declared, env) {
         const c = declared.get(key);
         if (!c || c.kind !== "table")
             continue;
+        // The Op refuses a stream-engine table (#4396); a change to one that reaches here is a move to or from a stream engine, for review.
+        if (isStreamEngine(c.engineName))
+            continue;
         const table = `${c.database ?? "default"}.${c.name}`;
         const time = c.columns.find((col) => !col.nullable && TIME_TYPE.test(col.type) && (!col.defaultKind || col.defaultKind === "DEFAULT"));
         const dualWrite = time ? { mode: "materialized-view", cutoverColumn: time.name } : { mode: "app" };

package/dist/clickhouse/plan/report.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../../src/clickhouse/plan/report.ts"],"names":[],"mappings":"AAAA,qHAAqH;AAIrH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAGzC,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,MAAM,CAsBlF"}
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../../src/clickhouse/plan/report.ts"],"names":[],"mappings":"AAAA,qHAAqH;AAIrH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAIzC,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,MAAM,CA0BlF"}

package/dist/clickhouse/plan/report.js

@@ -2,6 +2,7 @@
 import { renderChangeSet } from "../../core/classifier.js";
 import { CHANGE_CLASSES, CLASSIFIER_RULES } from "./rules.js";
 import { renderRebuildOps } from "./rebuild-handoff.js";
+import { renderNamedCollections } from "../live/named-collections.js";
 export function renderDiff(diff, opts = {}) {
     const unreadable = diff.unreadable ?? [];
     const refusedRead = unreadable.length > 0
@@ -13,6 +14,7 @@ export function renderDiff(diff, opts = {}) {
         : [];
     const trailer = [
         ...refusedRead,
+        ...renderNamedCollections(diff.namedCollections),
         ...(diff.rebuilds.length > 0
             ? [
                 "",
@@ -22,5 +24,8 @@ export function renderDiff(diff, opts = {}) {
             ]
             : []),
     ];
-    return renderChangeSet(diff, { ...(opts.title ? { title: opts.title } : {}), rules: CLASSIFIER_RULES, classes: CHANGE_CLASSES, trailer });
+    const text = renderChangeSet(diff, { ...(opts.title ? { title: opts.title } : {}), rules: CLASSIFIER_RULES, classes: CHANGE_CLASSES, trailer });
+    // The shared report prints no trailer under "No changes."; a missing named collection fails the plan all the same (#4395).
+    const missing = renderNamedCollections(diff.namedCollections);
+    return diff.changes.length === 0 && missing.length > 0 ? [text, ...missing].join("\n") : text;
 }

package/dist/clickhouse/plan/rules.d.ts

@@ -10,13 +10,16 @@
  *   parts until `MATERIALIZE INDEX`).
  * - `rewrite`: the change is a mutation that rewrites existing parts in the
  *   background (`system.mutations`), with no rollback.
+ * - `replace`: ClickHouse cannot alter the object, but it holds no rows to
+ *   keep, so the applier drops and creates it, around the views that read it
+ *   (a stream-engine table, #4396). Nothing is copied.
  * - `rebuild`: ClickHouse cannot make the change to the table it has; the data
  *   has to be copied into a new table. A plan refuses to make one in place.
  *
  * Creating and dropping whole objects are classed `create` and `drop`.
  */
 import { type ChangeClasses, type ClassifierRule as SqlClassifierRule } from "../../core/classifier.js";
-export type ChangeClass = "metadata" | "rewrite" | "rebuild" | "create" | "drop";
+export type ChangeClass = "metadata" | "rewrite" | "replace" | "rebuild" | "create" | "drop";
 /** A ClickHouse rule: the shared core's rule shape over these classes, citing a clickhouse.com page. */
 export type ClassifierRule = SqlClassifierRule<ChangeClass>;
 /** The classes as data: report order and labels, and what each costs for `classifyDisruption()`. */
@@ -47,6 +50,7 @@ export declare const CLASSIFIER_RULES: {
     readonly SQLCH222: ClassifierRule;
     readonly SQLCH223: ClassifierRule;
     readonly SQLCH224: ClassifierRule;
+    readonly SQLCH225: ClassifierRule;
     readonly SQLCH230: ClassifierRule;
     readonly SQLCH231: ClassifierRule;
     readonly SQLCH232: ClassifierRule;

package/dist/clickhouse/plan/rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../../src/clickhouse/plan/rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAkB,KAAK,aAAa,EAAE,KAAK,cAAc,IAAI,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAErH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEjF,wGAAwG;AACxG,MAAM,MAAM,cAAc,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;AAE5D,oGAAoG;AACpG,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC,WAAW,CAIrD,CAAC;AAMF,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiRsB,CAAC;AAEpD,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,gBAAgB,CAAC"}
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../../src/clickhouse/plan/rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAkB,KAAK,aAAa,EAAE,KAAK,cAAc,IAAI,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAErH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE7F,wGAAwG;AACxG,MAAM,MAAM,cAAc,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;AAE5D,oGAAoG;AACpG,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC,WAAW,CAIrD,CAAC;AAMF,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwRsB,CAAC;AAEpD,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,gBAAgB,CAAC"}

package/dist/clickhouse/plan/rules.js

@@ -10,6 +10,9 @@
  *   parts until `MATERIALIZE INDEX`).
  * - `rewrite`: the change is a mutation that rewrites existing parts in the
  *   background (`system.mutations`), with no rollback.
+ * - `replace`: ClickHouse cannot alter the object, but it holds no rows to
+ *   keep, so the applier drops and creates it, around the views that read it
+ *   (a stream-engine table, #4396). Nothing is copied.
  * - `rebuild`: ClickHouse cannot make the change to the table it has; the data
  *   has to be copied into a new table. A plan refuses to make one in place.
  *
@@ -18,9 +21,9 @@
 import { classifierRule } from "../../core/classifier.js";
 /** The classes as data: report order and labels, and what each costs for `classifyDisruption()`. */
 export const CHANGE_CLASSES = {
-    order: ["create", "metadata", "rewrite", "rebuild", "drop"],
-    label: { create: "create", drop: "drop", metadata: "metadata only", rewrite: "background rewrite", rebuild: "REBUILD" },
-    disruption: { metadata: "in-place", rewrite: "rolling", rebuild: "replace", create: "in-place", drop: "destroy" },
+    order: ["create", "metadata", "rewrite", "replace", "rebuild", "drop"],
+    label: { create: "create", drop: "drop", metadata: "metadata only", rewrite: "background rewrite", replace: "replace table", rebuild: "REBUILD" },
+    disruption: { metadata: "in-place", rewrite: "rolling", replace: "replace", rebuild: "replace", create: "in-place", drop: "destroy" },
 };
 const DOCS = "https://clickhouse.com/docs/sql-reference/statements";
 const rule = (id, cls, title, restriction, cite) => classifierRule(id, cls, title, restriction, cite);
@@ -50,6 +53,7 @@ export const CLASSIFIER_RULES = {
     SQLCH222: rule("SQLCH222", "rebuild", "Change the partition key", "There is no ALTER for the partition key; parts are laid out by it when they are written.", `${DOCS}/alter`),
     SQLCH223: rule("SQLCH223", "rebuild", "Change the table engine or its arguments", "There is no ALTER for a table's engine or its arguments (a ReplacingMergeTree version column, a Distributed sharding key); a different engine is a different table.", `${DOCS}/alter`),
     SQLCH224: rule("SQLCH224", "rebuild", "Change what kind of object it is", "A table cannot become a view or a view a table; the old object is dropped and the new one created.", `${DOCS}/create`),
+    SQLCH225: rule("SQLCH225", "replace", "Change a stream table", "A Kafka, S3Queue, AzureQueue, RabbitMQ, NATS or FileLog table stores no rows and has no ALTER for its engine arguments, settings or columns; the views that read it are detached, the table is dropped and created, and the views are attached again. Its position (a Kafka group's offsets, an S3Queue's record of processed files) is kept by the broker or Keeper, not by the table.", `${DOCS}/create/table`),
     SQLCH230: rule("SQLCH230", "metadata", "Rename or move a table or view", "RENAME TABLE changes the name, or moves the object to another database, in metadata on an Atomic database.", `${DOCS}/rename`),
     SQLCH231: rule("SQLCH231", "metadata", "Rename a database", "RENAME DATABASE is metadata only, for an Atomic database.", `${DOCS}/rename`),
     SQLCH232: rule("SQLCH232", "rebuild", "Change a database's engine", "A database's engine is fixed at creation; there is no ALTER for it.", `${DOCS}/create/database`),

package/dist/clickhouse/plan/stream.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Stream engines (#4396): Kafka, S3Queue, AzureQueue, RabbitMQ, NATS and
+ * FileLog. A table on one of them stores no rows. It is a consumer: the
+ * materialized views that read it pull messages (or files) through it into a
+ * target, and the position it has reached lives outside the table, in the
+ * broker's committed offsets or in Keeper.
+ *
+ * What follows from that, and what this file holds:
+ *
+ * - There is no ALTER for the engine's arguments, and nothing to copy to a
+ *   new table, so a change is neither `metadata` nor a `rebuild`: the table is
+ *   replaced, with the views that read it detached around the replacement
+ *   (SQLCH225, `./rules.ts`).
+ * - A replacement can lose the table's position. The two changes that do
+ *   are found here and reported on the change as a note.
+ */
+import type { CanonicalObject } from "./normalize.js";
+/** The stream engines, as `system.tables.engine` names them. */
+export declare const STREAM_ENGINES: ReadonlySet<string>;
+/** Whether an engine name is a stream engine. */
+export declare const isStreamEngine: (engine: string | undefined) => boolean;
+/** Whether a canonical table is on a stream engine. */
+export declare const isStreamTable: (o: CanonicalObject) => boolean;
+/** The arguments inside an engine's parentheses, split at top-level commas, string quotes removed. Empty when it has none. */
+export declare function streamEngineArguments(engine: string | undefined): string[];
+/**
+ * What a replacement would lose, in a sentence each (#4396):
+ *
+ * - a different `kafka_group_name` is a different consumer group: it starts
+ *   from the group's committed offsets, or from the topic's start when the
+ *   group has none (`auto.offset.reset`);
+ * - a different S3Queue `keeper_path` is a different place for the table's
+ *   record of processed files, so every file already seen is processed again.
+ *
+ * Neither is a refusal: a new group or path is sometimes the point.
+ */
+export declare function positionWarnings(before: CanonicalObject, after: CanonicalObject): string[];
+/** Whether a materialized view reads from the table: its SELECT names the table, qualified or, in the table's own database, bare. */
+export declare function readsTable(view: CanonicalObject, table: CanonicalObject): boolean;
+//# sourceMappingURL=stream.d.ts.map

package/dist/clickhouse/plan/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../../src/clickhouse/plan/stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,gEAAgE;AAChE,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,MAAM,CAA8E,CAAC;AAE9H,iDAAiD;AACjD,eAAO,MAAM,cAAc,GAAI,QAAQ,MAAM,GAAG,SAAS,KAAG,OAA6D,CAAC;AAE1H,uDAAuD;AACvD,eAAO,MAAM,aAAa,GAAI,GAAG,eAAe,KAAG,OAA6D,CAAC;AAEjH,8HAA8H;AAC9H,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CA0B1E;AAWD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,EAAE,eAAe,GAAG,MAAM,EAAE,CAsB1F;AAED,qIAAqI;AACrI,wBAAgB,UAAU,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAQjF"}