@intentius/chant-lexicon-sql 0.124.31 → 0.124.33

package/dist/clickhouse/live/describe-resources.js

@@ -0,0 +1,91 @@
+/**
+ * `describeResources()` for the ClickHouse dialect: which declared databases,
+ * tables and views exist on the environment's server.
+ *
+ * One read of `system.databases`, `system.tables` and `system.functions` per
+ * run, then a lookup per declared entity, so N entities are three queries,
+ * not N. An object the
+ * catalog does not list is absent, and the `queried` address says which
+ * server and name were asked. A server that cannot be reached, or refuses the
+ * credentials, leaves every entity unobserved with that reason: never absent.
+ *
+ * Ownership is read from chant's marker, the trailer the applier appends to
+ * the object's comment (`../ownership.ts`): `owned` when the comment carries
+ * it, `foreign` when it does not. With `owned: true` a foreign object is
+ * withheld as `filtered`, which says it exists and is not chant's, never that
+ * it is absent.
+ */
+import { observeEntities, } from "@intentius/chant/observation";
+import { bindClickHouse, classifyClickHouseFailure } from "./bind.js";
+import { ACCESS_ENTITY_TYPES, ACCESS_UNMANAGED_DETAIL, accessOf, readLiveAccess, readLiveSchema } from "./catalog.js";
+import { CLICKHOUSE_ENTITY_TYPES } from "../entities.js";
+import { objectKey } from "../plan/normalize.js";
+import { isChantManaged, readMarker, stripMarker } from "../ownership.js";
+/** The database and name a declared entity is created as. */
+export function declaredAddress(entity, defaultDatabase) {
+    const name = String(entity.props.name ?? "");
+    if (entity.type === CLICKHOUSE_ENTITY_TYPES.database ||
+        entity.type === CLICKHOUSE_ENTITY_TYPES.function ||
+        entity.type === CLICKHOUSE_ENTITY_TYPES.user ||
+        entity.type === CLICKHOUSE_ENTITY_TYPES.role ||
+        entity.type === CLICKHOUSE_ENTITY_TYPES.quota ||
+        entity.type === CLICKHOUSE_ENTITY_TYPES.settingsProfile) {
+        return { name };
+    }
+    return { database: typeof entity.props.database === "string" ? entity.props.database : defaultDatabase, name };
+}
+function adapter(options) {
+    return {
+        async bind() {
+            const target = await bindClickHouse(options);
+            const byKey = new Map();
+            const access = target.access === true ? await readLiveAccess(target, options.access?.(target.defaultDatabase) ?? [], { withStatements: false }) : [];
+            for (const o of [...(await readLiveSchema(target, { withStatements: false })), ...access]) {
+                byKey.set(objectKey(o), o);
+            }
+            return { target, byKey };
+        },
+        classifyBindFailure: (err) => classifyClickHouseFailure(err),
+        async read({ target, byKey }, entity) {
+            if (!entity.type.startsWith("ClickHouse::")) {
+                return { unobserved: { reason: "unsupported-kind", detail: entity.type } };
+            }
+            if (target.access !== true && ACCESS_ENTITY_TYPES.has(entity.type)) {
+                return { unobserved: { reason: "filtered", detail: ACCESS_UNMANAGED_DETAIL } };
+            }
+            if (entity.type === CLICKHOUSE_ENTITY_TYPES.grant) {
+                return { unobserved: { reason: "unsupported-kind", detail: "a grant is compared as part of its grantees' grants, which chant sql plan reports" } };
+            }
+            const { database, name } = declaredAddress(entity, target.defaultDatabase);
+            const queried = `${target.endpoint.url} ${database ? `${database}.` : ""}${name}`;
+            const table = typeof entity.props.table === "string" ? entity.props.table : undefined;
+            const live = byKey.get(objectKey({ type: entity.type, ...(database !== undefined ? { database } : {}), name, ...(table !== undefined ? { table } : {}) }));
+            if (!live)
+                return { absent: true, queried };
+            const owned = isChantManaged(live.comment);
+            if (options.owned && !owned) {
+                return { unobserved: { reason: "filtered", detail: "the object's comment carries no chant ownership marker and owned was requested" }, queried };
+            }
+            const marker = readMarker(live.comment);
+            const comment = live.comment ? stripMarker(live.comment) : "";
+            return {
+                present: {
+                    type: live.type,
+                    physicalId: live.uuid ?? (database ? `${database}.${name}` : name),
+                    status: live.engine,
+                    attributes: { engine: live.engine, ...(live.uuid ? { uuid: live.uuid } : {}), ...(comment ? { comment } : {}) },
+                    ownership: owned ? "owned" : "foreign",
+                    ...(owned && marker?.stack ? { marker: { stack: marker.stack, ...(marker.env ? { env: marker.env } : {}) } } : {}),
+                },
+                queried,
+            };
+        },
+    };
+}
+export async function describeResources(options) {
+    const declared = options.entityNames.map((name) => {
+        const entity = options.entities.get(name);
+        return { name, type: entity?.entityType ?? "", props: entity?.props ?? {} };
+    });
+    return observeEntities(declared, adapter({ ...options, access: (db) => accessOf(options.entities, db) }));
+}

package/dist/clickhouse/live/undeclarable.js

@@ -0,0 +1,59 @@
+/**
+ * The objects on a live ClickHouse server of the kinds no declaration holds
+ * (#3911), found so import can refuse them by name instead of leaving them
+ * out (`../../core/undeclarable.ts`).
+ *
+ * One `system.*` query per kind the coverage table marks refused
+ * (`../../coverage/clickhouse.json`), keyed by the row's `kind`. A kind whose
+ * row is flipped to declared is no longer asked about.
+ *
+ * What the server's configuration files define (`storage = 'users_xml'`, a
+ * named collection whose source is the config, an executable function) is
+ * the server's, not a schema's, and is left out; so is what is in a database
+ * out of scope. A server-wide object (a quota, a settings profile, a
+ * workload) is always looked for.
+ */
+import { clickhouseQuery } from "../http.js";
+import { SYSTEM_DATABASES } from "./catalog.js";
+import { KIND_COVERAGE } from "../../coverage.js";
+const quote = (s) => `'${s.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+const serverWide = (table, where = "1") => () => `SELECT '' AS database, name FROM system.${table} WHERE ${where}`;
+const SQL_DEFINED = "storage != 'users_xml'";
+export const CLICKHOUSE_PROBES = {
+    "non-SQL function": serverWide("functions", "origin NOT IN ('System', 'SQLUserDefined', 'ExecutableUserDefined')"),
+    "HTTP handler": serverWide("handlers"),
+    "masking policy": (scope) => `SELECT database, short_name || ' ON ' || table AS name FROM system.masking_policies WHERE ${SQL_DEFINED} AND ${scope("database")}`,
+    "named collection": serverWide("named_collections", "source = 'SQL'"),
+    quota: serverWide("quotas", SQL_DEFINED),
+    "workload resource": serverWide("resources"),
+    "settings profile": serverWide("settings_profiles", SQL_DEFINED),
+    "window view": (scope) => `SELECT database, name FROM system.tables WHERE engine = 'WindowView' AND NOT is_temporary AND ${scope("database")}`,
+    workload: serverWide("workloads"),
+};
+/**
+ * Every object in scope of a kind the coverage table refuses, kind by kind
+ * in the table's order, each by database then name. A kind the reader may
+ * not read (no grant on its `system` table) is a problem in `unread`, not a
+ * pass.
+ */
+export async function readUndeclarable(target) {
+    const scope = (column) => target.databases ? `${column} IN (${target.databases.map(quote).join(", ")})` : `${column} NOT IN (${[...SYSTEM_DATABASES].map(quote).join(", ")})`;
+    const objects = [];
+    const unread = [];
+    for (const row of KIND_COVERAGE.clickhouse) {
+        if (row.status !== "refused")
+            continue;
+        const probe = CLICKHOUSE_PROBES[row.kind];
+        if (!probe)
+            throw new Error(`no system table query finds a ClickHouse ${row.kind} (src/clickhouse/live/undeclarable.ts)`);
+        try {
+            const rows = await clickhouseQuery(target.endpoint, `/* chant undeclarable: ${row.kind} */ SELECT database, name FROM (${probe(scope)}) ORDER BY database, name`);
+            for (const r of rows)
+                objects.push({ kind: row.kind, ...(r.database ? { schema: r.database } : {}), name: r.name });
+        }
+        catch (err) {
+            unread.push(`${row.kind}: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`);
+        }
+    }
+    return { objects, unread };
+}

package/dist/clickhouse/overlays/codecs.js

@@ -0,0 +1,57 @@
+/**
+ * Codec parameters and chaining: the overlay half.
+ *
+ * `system.codecs` gives the 17 names and their flags (compression, generic,
+ * encryption, time series, experimental). The parameters (`ZSTD(level)`,
+ * `Delta(bytes)`) and the order a chain like `CODEC(Delta, ZSTD(3))` must
+ * follow are in no table.
+ *
+ * Every codec at the pin has an entry, and generation fails when one does not,
+ * so a codec a pin move adds is a decision rather than a silent `string`.
+ * `"unknown"` is that decision for the experimental codecs whose parameters
+ * are not documented: they are accepted as written and not checked.
+ */
+const WIDTH = {
+    name: "bytes",
+    kind: "number",
+    optional: true,
+    values: ["1", "2", "4", "8"],
+    note: "1, 2, 4 or 8; the column type's width when omitted.",
+};
+export const CODEC_OVERLAY = {
+    NONE: { parameters: [], role: "none" },
+    LZ4: { parameters: [], role: "compression" },
+    LZ4HC: {
+        parameters: [{ name: "level", kind: "number", optional: true, range: [0, 12], note: "9 when omitted or 0." }],
+        role: "compression",
+    },
+    ZSTD: {
+        parameters: [
+            { name: "level", kind: "number", optional: true, range: [1, 22], note: "1 when omitted." },
+            { name: "window_log", kind: "number", optional: true, range: [10, 31], note: "Turns on long-range matching with this window log." },
+        ],
+        role: "compression",
+    },
+    Delta: { parameters: [WIDTH], role: "preprocessing" },
+    DoubleDelta: { parameters: [WIDTH], role: "compression" },
+    Gorilla: { parameters: [WIDTH], role: "compression" },
+    GCD: { parameters: [], role: "preprocessing" },
+    T64: {
+        parameters: [{ name: "variant", kind: "keyword", optional: true, values: ["'byte'", "'bit'"] }],
+        role: "compression",
+    },
+    FPC: {
+        parameters: [
+            { name: "level", kind: "number", optional: true, range: [1, 28], note: "12 when omitted." },
+            { name: "float_size", kind: "number", optional: true, values: ["4", "8"], note: "4 or 8; the column type's width when omitted." },
+        ],
+        role: "compression",
+    },
+    AES_128_GCM_SIV: { parameters: [], role: "encryption" },
+    AES_256_GCM_SIV: { parameters: [], role: "encryption" },
+    ALP: { parameters: "unknown", role: "compression" },
+    SZ3: { parameters: "unknown", role: "compression" },
+    ZXC: { parameters: "unknown", role: "compression" },
+    Quantized: { parameters: "unknown", role: "preprocessing" },
+    Multiple: { parameters: "unknown", role: "internal" },
+};

package/dist/clickhouse/overlays/engines.js

@@ -0,0 +1,101 @@
+/**
+ * Engine arguments: the overlay half (chant #3195).
+ *
+ * The generator reads each engine's argument names, positions and optionality
+ * from the server's `syntax` line (`engine-syntax.ts`). This table adds what
+ * that line cannot say: whether `ver` is a column, `cluster` a name, `min_time`
+ * a number. Keys are the argument names exactly as the syntax line spells
+ * them, and generation fails when one no longer appears there, so a pin move
+ * that renames or drops an argument is caught rather than mistyped.
+ *
+ * Covered: the MergeTree family and its Replicated twins, and the engines a
+ * schema commonly declares beside them (Distributed, Buffer, Join, Merge,
+ * Dictionary, File, URL, Alias, KeeperMap, EmbeddedRocksDB, GenerateRandom).
+ * Integration engines (S3, Kafka, the lake engines, the database bridges) keep
+ * their arguments untyped: they are connection strings and credentials, which
+ * lint has no business guessing at.
+ */
+const REPLICATED = {
+    zoo_path: {
+        kind: "string",
+        optional: true,
+        note: "May be omitted together with replica_name when the server sets default_replica_path and default_replica_name.",
+    },
+    replica_name: { kind: "string", optional: true, note: "Omitted together with zoo_path." },
+};
+const SIGN = { kind: "column", note: "An Int8 column holding 1 for a state row and -1 for a cancel row." };
+const VERSION = { kind: "column", note: "An unsigned integer, date or datetime column." };
+const SUMMED = { kind: "columns", note: "Numeric columns to sum; every numeric column outside the sort key when omitted." };
+const REPLACING = {
+    ver: { kind: "column", note: "The version column: the row with the highest version wins; the last inserted when omitted." },
+    is_deleted: { kind: "column", note: "A UInt8 column; 1 marks a deleted row. Requires ver." },
+};
+export const ENGINE_ARGUMENTS = {
+    ReplacingMergeTree: REPLACING,
+    SummingMergeTree: { columns: SUMMED },
+    CoalescingMergeTree: { columns: SUMMED },
+    CollapsingMergeTree: { sign: SIGN },
+    VersionedCollapsingMergeTree: { sign: SIGN, version: VERSION },
+    GraphiteMergeTree: { config_section: { kind: "string", note: "The graphite_rollup section of the server config." } },
+    ReplicatedMergeTree: REPLICATED,
+    ReplicatedAggregatingMergeTree: REPLICATED,
+    ReplicatedReplacingMergeTree: { ...REPLICATED, ...REPLACING },
+    ReplicatedSummingMergeTree: { ...REPLICATED, columns: SUMMED },
+    ReplicatedCoalescingMergeTree: { ...REPLICATED, columns: SUMMED },
+    ReplicatedCollapsingMergeTree: { ...REPLICATED, sign: SIGN },
+    ReplicatedVersionedCollapsingMergeTree: { ...REPLICATED, sign: SIGN, version: VERSION },
+    ReplicatedGraphiteMergeTree: { ...REPLICATED, config_section: { kind: "string" } },
+    Distributed: {
+        cluster: { kind: "identifier", note: "A cluster named in the server's remote_servers config." },
+        database: { kind: "identifier" },
+        table: { kind: "identifier" },
+        sharding_key: { kind: "expression", note: "Required for INSERTs into a cluster of more than one shard." },
+        policy_name: { kind: "string", note: "A storage policy for the files queued for sending." },
+    },
+    Buffer: {
+        database: { kind: "identifier" },
+        table: { kind: "identifier" },
+        num_buckets: { kind: "number", range: [1, 1000], note: "Independent buffers; 16 is the documented default." },
+        min_time: { kind: "number" },
+        max_time: { kind: "number" },
+        min_rows: { kind: "number" },
+        max_rows: { kind: "number" },
+        min_bytes: { kind: "number" },
+        max_bytes: { kind: "number" },
+        flush_time: { kind: "number" },
+        flush_rows: { kind: "number" },
+        flush_bytes: { kind: "number" },
+    },
+    Join: {
+        join_strictness: { kind: "keyword", values: ["ANY", "ALL", "SEMI", "ANTI"] },
+        join_type: { kind: "keyword", values: ["INNER", "LEFT", "RIGHT", "FULL", "CROSS"] },
+        k1: { kind: "column" },
+        k2: { kind: "column" },
+    },
+    Merge: {
+        db_name: { kind: "expression", note: "A database name, or REGEXP('pattern')." },
+        tables_regexp: { kind: "string" },
+    },
+    Dictionary: { dictionary_name: { kind: "identifier" } },
+    File: {
+        format: { kind: "identifier", note: "An input/output format name from system.formats." },
+        "path|fd": { kind: "string" },
+    },
+    URL: {
+        url: { kind: "string" },
+        format: { kind: "identifier", note: "A format name from system.formats." },
+        compression: { kind: "string" },
+    },
+    Alias: { target_db: { kind: "identifier" }, target_table: { kind: "identifier" } },
+    KeeperMap: { root_path: { kind: "string" }, keys_limit: { kind: "number" } },
+    EmbeddedRocksDB: {
+        ttl: { kind: "number" },
+        rocksdb_dir: { kind: "string" },
+        read_only: { kind: "number", range: [0, 1] },
+    },
+    GenerateRandom: {
+        random_seed: { kind: "number" },
+        max_string_length: { kind: "number" },
+        max_array_length: { kind: "number" },
+    },
+};

package/dist/clickhouse/overlays/kinds.js

@@ -0,0 +1 @@
+export {};

package/dist/clickhouse/overlays/projections.js

@@ -0,0 +1,26 @@
+/**
+ * Projections: the overlay half.
+ *
+ * `system.table_engines.supports_projections` says which engines accept a
+ * projection, and is generated. The projection's own grammar is fixed and in
+ * no table: a name and a parenthesised query over the table, either a
+ * reordering (`SELECT * ORDER BY x`) or an aggregation (`SELECT k, sum(v)
+ * GROUP BY k`). `system.projections` is runtime state, not grammar.
+ *
+ *     PROJECTION name (SELECT <columns or *> [GROUP BY ...] [ORDER BY ...])
+ */
+export const PROJECTION_FORMS = [
+    { form: "normal", marker: "ORDER BY", summary: "A copy of the selected columns in another sort order." },
+    { form: "aggregate", marker: "GROUP BY", summary: "Pre-aggregated rows, kept current by merges like an AggregatingMergeTree." },
+];
+/**
+ * MergeTree settings that decide what a mutation or deduplicating merge does to
+ * a table with projections. Changing either is metadata only; leaving them at
+ * their defaults makes `ALTER ... UPDATE` on such a table an error.
+ */
+export const PROJECTION_SETTINGS = [
+    "deduplicate_merge_projection_mode",
+    "lightweight_mutation_projection_mode",
+];
+/** Clauses a projection's query may not carry. */
+export const PROJECTION_FORBIDDEN_CLAUSES = ["WHERE", "JOIN", "LIMIT", "HAVING", "ARRAY JOIN"];

package/dist/clickhouse/overlays/skip-indexes.js

@@ -0,0 +1,40 @@
+/**
+ * Skip index parameters: the overlay half.
+ *
+ * `system.data_skipping_index_types` names each type and gives a syntax line,
+ * from which the generator reads parameter names and optionality. This adds
+ * their kinds and ranges. `GRANULARITY` is fixed grammar the parser owns.
+ */
+const HASHES = { kind: "number", range: [1, 1000000], note: "Hash functions per value." };
+const BYTES = { kind: "number", note: "Bloom filter size in bytes." };
+const SEED = { kind: "number", note: "Seed for the hash functions." };
+export const SKIP_INDEX_PARAMETERS = {
+    bloom_filter: {
+        false_positive_rate: { kind: "number", range: [0, 1], note: "Exclusive of 0 and 1; 0.025 when omitted." },
+    },
+    set: { max_rows: { kind: "number", note: "0 keeps every distinct value." } },
+    ngrambf_v1: {
+        n: { kind: "number", range: [1, 256], note: "N-gram size." },
+        size_in_bytes: BYTES,
+        num_hash_functions: HASHES,
+        seed: SEED,
+    },
+    tokenbf_v1: { size_in_bytes: BYTES, num_hash_functions: HASHES, seed: SEED },
+    sparse_grams: {
+        min_ngram_length: { kind: "number" },
+        max_ngram_length: { kind: "number" },
+        min_cutoff_length: { kind: "number" },
+        size_in_bytes: BYTES,
+        num_hash_functions: HASHES,
+        seed: SEED,
+    },
+    text: { tokenizer: { kind: "expression", note: "A tokenizer such as splitByNonAlpha, ngrams(N) or array." } },
+    vector_similarity: {
+        hnsw: { kind: "keyword", values: ["hnsw"], note: "The only method." },
+        distance_function: { kind: "keyword", values: ["L2Distance", "cosineDistance"] },
+        dimensions: { kind: "number" },
+        quantization: { kind: "keyword", values: ["f64", "f32", "f16", "bf16", "i8", "b1"] },
+        hnsw_max_connections_per_layer: { kind: "number" },
+        hnsw_candidate_list_size_for_construction: { kind: "number" },
+    },
+};

package/dist/clickhouse/overlays/ttl.js

@@ -0,0 +1,34 @@
+/**
+ * TTL clauses: the whole grammar is overlay.
+ *
+ * No system table describes TTL. A table TTL is a list of rules, each an
+ * expression evaluating to a `Date` or `DateTime` and an action; a column TTL
+ * is a single expression with no action, after which the column resets to its
+ * default. Which engines accept TTL at all is generated
+ * (`capabilities.ttl` from `system.table_engines.supports_ttl`).
+ *
+ *     TTL expr [DELETE | RECOMPRESS codec | TO DISK 'd' | TO VOLUME 'v'] [WHERE cond]
+ *         [, expr GROUP BY key_columns SET col = agg(col), ...]
+ */
+export const TTL_ACTIONS = [
+    { keywords: "DELETE", where: true, impliedWhenOmitted: true },
+    { keywords: "RECOMPRESS", argument: { kind: "codec", note: "A CODEC(...) expression." }, where: true },
+    { keywords: "TO DISK", argument: { kind: "string", note: "A disk of the table's storage policy." }, where: true },
+    { keywords: "TO VOLUME", argument: { kind: "string", note: "A volume of the table's storage policy." }, where: true },
+    {
+        keywords: "GROUP BY",
+        argument: { kind: "columns", note: "A prefix of the sort key, then SET col = aggregate(col), ..." },
+        where: true,
+    },
+];
+/** A column TTL takes an expression and nothing else. */
+export const COLUMN_TTL_ACTIONS = [];
+/** The types a TTL expression must evaluate to. */
+export const TTL_RESULT_TYPES = ["Date", "Date32", "DateTime", "DateTime64"];
+/** MergeTree settings that change how TTL runs, for lint and hover to point at. */
+export const TTL_SETTINGS = [
+    "merge_with_ttl_timeout",
+    "merge_with_recompression_ttl_timeout",
+    "ttl_only_drop_parts",
+    "materialize_ttl_recalculate_only",
+];

package/dist/clickhouse/overlays/types.js

@@ -0,0 +1,59 @@
+/**
+ * Column type parameters: the overlay half.
+ *
+ * `system.data_type_families` lists the families and their aliases. The
+ * parameter grammar (`Decimal(P, S)`, `DateTime64(precision[, tz])`,
+ * `Enum8('a' = 1)`) is in no system table. A family missing here takes no
+ * parameters; generation fails when a key here is not a family at the pin.
+ */
+const P = (name, kind, extra = {}) => ({
+    name,
+    kind,
+    ...extra,
+});
+const TZ = P("timezone", "string", { optional: true });
+/**
+ * The server takes and ignores a MySQL-style display width on an integer
+ * (`INT(11)`, `UInt64(8)`), a precision and scale on a float (`DOUBLE(10, 2)`)
+ * and a length on a string (`VARCHAR(255)`), so each is an optional parameter
+ * here rather than a mistake.
+ */
+const WIDTH = [P("display_width", "number", { optional: true })];
+const FLOAT = [P("precision", "number", { optional: true }), P("scale", "number", { optional: true })];
+const INTEGERS = ["Int8", "Int16", "Int32", "Int64", "Int128", "Int256", "UInt8", "UInt16", "UInt32", "UInt64", "UInt128", "UInt256"];
+export const TYPE_PARAMETERS = {
+    ...Object.fromEntries(INTEGERS.map((name) => [name, WIDTH])),
+    Float32: FLOAT,
+    Float64: FLOAT,
+    BFloat16: FLOAT,
+    String: [P("length", "number", { optional: true })],
+    /** A bare `Decimal` is `Decimal(10, 0)`. */
+    Decimal: [P("precision", "number", { optional: true, range: [1, 76] }), P("scale", "number", { optional: true, range: [0, 76] })],
+    Decimal32: [P("scale", "number", { range: [0, 9] })],
+    Decimal64: [P("scale", "number", { range: [0, 18] })],
+    Decimal128: [P("scale", "number", { range: [0, 38] })],
+    Decimal256: [P("scale", "number", { range: [0, 76] })],
+    DateTime: [TZ],
+    DateTime32: [TZ],
+    /** A bare `DateTime64` has precision 3. */
+    DateTime64: [P("precision", "number", { optional: true, range: [0, 9] }), TZ],
+    Time64: [P("precision", "number", { optional: true, range: [0, 9] })],
+    FixedString: [P("length", "number", { range: [1, Number.MAX_SAFE_INTEGER] })],
+    Enum: [P("member", "enum-member", { repeated: true })],
+    Enum8: [P("member", "enum-member", { repeated: true })],
+    Enum16: [P("member", "enum-member", { repeated: true })],
+    Nullable: [P("type", "type")],
+    LowCardinality: [P("type", "type")],
+    Array: [P("type", "type")],
+    Map: [P("key", "type"), P("value", "type")],
+    Tuple: [P("element", "named-type", { repeated: true })],
+    Nested: [P("field", "named-type", { repeated: true })],
+    Variant: [P("type", "type", { repeated: true })],
+    AggregateFunction: [P("function", "function"), P("argument", "type", { repeated: true })],
+    SimpleAggregateFunction: [P("function", "function"), P("argument", "type")],
+    JSON: [P("setting", "expression", { optional: true, repeated: true })],
+    Dynamic: [P("max_types", "expression", { optional: true })],
+    QBit: [P("element", "type"), P("dimension", "number")],
+};
+/** Families that wrap another type and pass its nullability and sort-key rules through. */
+export const WRAPPER_TYPES = ["LowCardinality"];

package/dist/clickhouse/ownership.js

@@ -0,0 +1,83 @@
+/**
+ * chant's ownership marker on ClickHouse objects (#3208): a trailer on the
+ * object's own `COMMENT`.
+ *
+ * ClickHouse objects carry no tags or labels. The channels considered:
+ *
+ * - The object `COMMENT`. Every object kind has one (a table of any engine, a
+ *   view, a materialized view, a database), it is set in the `CREATE` itself
+ *   so an object is never created unmarked, `MODIFY COMMENT` restamps it, and
+ *   `system.tables` / `system.databases` return it with the catalog read
+ *   observation already makes. The #3046 candidate.
+ * - Table `SETTINGS`: a MergeTree table refuses a setting it does not know.
+ * - A registry table on the server naming the objects chant created: a record
+ *   apart from the object, which is the state file chant does not keep, and
+ *   one that goes on claiming a table someone dropped and created again.
+ *
+ * So the comment, and the question is the user's own comment, which is a
+ * declared property (`COMMENT 'Raw events'`, classified by SQLCH203). The
+ * marker never replaces it: it is appended as a bracketed trailer,
+ *
+ *     COMMENT 'Raw events [chant managed-by=chant stack=shop env=prod]'
+ *
+ * and taken off again wherever chant reads a definition (`readLiveSchema`
+ * strips it from `SHOW CREATE`), so planning, the deep diff and import compare
+ * and write the declared comment alone. Someone who edits the comment by hand
+ * and drops the trailer makes the object read as foreign, which is the safe
+ * direction: it is never pruned, and the next apply of its declaration
+ * stamps it again.
+ *
+ * Values are percent-encoded outside `[A-Za-z0-9._-]`, so the trailer never
+ * holds a quote, a backslash, a space or a bracket of its own.
+ *
+ * The trailer itself is the shared core's (`../core/ownership.ts`), the same in
+ * every dialect. What is ClickHouse's here: the channel the plugin declares,
+ * taking the trailer off a printed `COMMENT '...'` clause, and the trailer keys
+ * of the rebuild migration's working objects.
+ */
+import { COMMENT_OWNERSHIP_KEYS, RECEIPTS_TRAILER_KEY, TRAILER_PAIR, hasChantTrailerKey } from "../core/ownership.js";
+export { carriesMarker, isChantManaged, markerTrailer, readMarker, readTrailerPairs, RECEIPTS_TRAILER_KEY, stampedComment, stripMarker, } from "../core/ownership.js";
+/** The keys inside the trailer. */
+export const CLICKHOUSE_COMMENT_OWNERSHIP_KEYS = COMMENT_OWNERSHIP_KEYS;
+/**
+ * Where the marker is read back (#1348): `describeResources` and
+ * `exportResources` read the comment from `system.tables` and
+ * `system.databases`. The deep read takes it off with the rest of `SHOW CREATE`
+ * and reports no verdict.
+ */
+export const SQL_OWNERSHIP_CHANNEL = {
+    keys: CLICKHOUSE_COMMENT_OWNERSHIP_KEYS,
+    reads: ["describeResources", "exportResources"],
+};
+/** A comment that is the trailer alone, in a printed statement: the whole `COMMENT '...'` clause. */
+const ONLY_TRAILER_CLAUSE = new RegExp(`\\s*\\bCOMMENT\\s+'\\[chant(?: ${TRAILER_PAIR})+\\]'`, "g");
+/** The trailer inside a printed comment literal, just before its closing quote. */
+const TRAILER_IN_LITERAL = new RegExp(`\\s+\\[chant(?: ${TRAILER_PAIR})+\\]'`, "g");
+/**
+ * The trailer key naming the table a rebuild migration object belongs to
+ * (`./rebuild/`). An object carrying it is the rebuild's own working object,
+ * not a declaration: a new table being filled, the dual-write view, an old
+ * table being retained. Reading a schema leaves those out
+ * (`./live/catalog.ts`), so a plan, an import or a prune never sees them.
+ */
+export const REBUILD_TRAILER_KEY = "rebuild";
+/** Whether a comment marks a rebuild migration's working object. */
+export function isRebuildObject(comment) {
+    return hasChantTrailerKey(comment, [REBUILD_TRAILER_KEY]);
+}
+/**
+ * Whether a comment marks one of chant's own working objects: a rebuild's
+ * new, dual-write or retained table, or the receipts database and table.
+ * Schema reads leave them out.
+ */
+export function isChantWorkingObject(comment) {
+    return hasChantTrailerKey(comment, [REBUILD_TRAILER_KEY, RECEIPTS_TRAILER_KEY]);
+}
+/**
+ * A `SHOW CREATE` statement with the trailer taken off its object comment, so
+ * the statement reads as the declaration it came from. A comment that was the
+ * trailer alone loses its whole `COMMENT` clause.
+ */
+export function stripMarkerFromStatement(statement) {
+    return statement.replace(ONLY_TRAILER_CLAUSE, "").replace(TRAILER_IN_LITERAL, "'");
+}