@intentius/chant-lexicon-sql 0.124.31 → 0.124.33

package/dist/clickhouse/plan/commands.js

@@ -0,0 +1,159 @@
+/**
+ * `chant sql diff` and `chant sql plan`: the classified change between two
+ * builds, or between a build and a live server. A Postgres build (its output
+ * says `"dialect": "postgres"`) or a Postgres binding goes to
+ * `../../postgres/plan/commands.ts`.
+ *
+ *     chant sql diff <before.json> <after.json> [--json] [--statements] [--topology <topology>]
+ *     chant sql plan <env> <build.json> [--json]
+ *
+ * `diff` is offline: it compares two `chant build` outputs, say a pull
+ * request's base and head, and needs no server. `plan` compares a build with
+ * the server `sql.profiles.<env>` binds and asks that server's formatter about
+ * 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
+ * refused table they name the `ClickHouseRebuildOp` to run instead
+ * (`rebuildOps` in `--json`, `./rebuild-handoff.ts`).
+ *
+ * `diff --statements` prints the statements instead, for a migration file:
+ * each one the applier would send, with its change's rule and class, and a
+ * refused change as the Op that makes it (`../../migration-statements.ts`).
+ * The marker in each `CREATE` is the project's `ownership` config's.
+ *
+ * `--topology` (`single`, `cluster:<name>`, `replicated`, `replicated:<cluster>`,
+ * `cloud`; `../topology.ts`) renders a ClickHouse diff's declarations and
+ * statements for that topology: `ON CLUSTER` and the engine. `--statements`
+ * renders for `single` without it; the plain diff compares the declarations as
+ * written. `plan` takes the topology from `sql.profiles.<env>.topology`.
+ */
+import { diffSchemas } from "./diff.js";
+import { renderDiff } from "./report.js";
+import { keyedByQualifiedName, schemaFromBuildFile, schemaFromServer } from "./schema.js";
+import { dropFormattingOnly } from "./server-format.js";
+import { scopeOf } from "./normalize.js";
+import { ACCESS_KINDS, accessUnmanagedHint, declaredAccess } from "../live/catalog.js";
+import { bindClickHouse } from "../live/bind.js";
+import { rebuildOpSuggestions } from "./rebuild-handoff.js";
+import { readFileSync } from "node:fs";
+import { parseTopology } from "../topology.js";
+/** The dialect a build output names. */
+function outputDialect(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf-8")).dialect;
+    }
+    catch {
+        return undefined;
+    }
+}
+function split(args) {
+    const positional = [];
+    let topology;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--topology")
+            topology = args[++i] ?? "";
+        else if (a.startsWith("--topology="))
+            topology = a.slice("--topology=".length);
+        else if (!a.startsWith("--"))
+            positional.push(a);
+    }
+    return { positional, json: args.includes("--json"), statements: args.includes("--statements"), ...(topology !== undefined ? { topology } : {}) };
+}
+/** `chant sql diff --statements`: the statements between two builds, as SQL with comments or as JSON. Exits 2 when a step is an Op or manual. */
+async function runDiffStatements(before, after, json, topology) {
+    const { diffStatements, renderStatements } = await import("../../migration-statements.js");
+    const { resolveOwnershipMarker } = await import("../../core/apply.js");
+    let marker;
+    try {
+        const { loadChantConfig } = await import("@intentius/chant/config");
+        const config = await loadChantConfig(process.cwd()).then((r) => r.config).catch(() => undefined);
+        marker = resolveOwnershipMarker({}, config, "chant sql diff --statements");
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+    const doc = diffStatements(readFileSync(before, "utf-8"), readFileSync(after, "utf-8"), { ...(marker ? { marker } : {}), ...(topology ? { topology } : {}) });
+    console.log(json ? JSON.stringify(doc, null, 2) : renderStatements(doc));
+    return doc.refused ? 2 : 0;
+}
+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;
+}
+export async function runDiff(ctx) {
+    const { positional, json, statements, topology: topologyArg } = split(ctx.rawArgs);
+    if (positional.length !== 2) {
+        console.error("usage: chant sql diff <before.json> <after.json> [--json] [--statements] [--topology <topology>]");
+        return 1;
+    }
+    let topology;
+    try {
+        topology = topologyArg !== undefined ? parseTopology(topologyArg) : undefined;
+    }
+    catch (err) {
+        console.error(`--topology: ${err.message}`);
+        return 1;
+    }
+    if (statements)
+        return runDiffStatements(positional[0], positional[1], json, topology);
+    if (outputDialect(positional[1]) === "postgres") {
+        const { diffPgBuildFiles, emitPg, projectMajor } = await import("../../postgres/plan/commands.js");
+        return emitPg(diffPgBuildFiles(positional[0], positional[1], await projectMajor()), json, `${positional[0]} -> ${positional[1]}`);
+    }
+    const after = schemaFromBuildFile(positional[1], "default", topology);
+    const diff = diffSchemas(schemaFromBuildFile(positional[0], "default", topology), after);
+    const rebuildOps = rebuildOpSuggestions(diff, new Map(after.map((o) => [o.key, o.canonical])), "<env>");
+    return emit(rebuildOps.length > 0 ? { ...diff, rebuildOps } : diff, json, `${positional[0]} -> ${positional[1]}`);
+}
+/** The declared objects against the server, keys and labels by `database.name`. */
+export async function planAgainstServer(environment, buildFile, options = {}) {
+    const target = await bindClickHouse({ ...options, environment });
+    const all = keyedByQualifiedName(schemaFromBuildFile(buildFile, target.defaultDatabase, target.topology));
+    // Access declarations a profile does not manage are not planned, and the server's access is not read (#3716).
+    const declared = target.access === true ? all : all.filter((o) => !ACCESS_KINDS.has(o.canonical.kind));
+    const unmanaged = all.length - declared.length;
+    const databases = new Set(declared.map((o) => scopeOf(o.canonical)));
+    const unreadable = [];
+    const live = await schemaFromServer(target, databases, unreadable, declaredAccess(declared.map((o) => o.canonical)));
+    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);
+    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 {
+        changes: relabel,
+        rebuilds: relabel.filter((c) => c.class === "rebuild"),
+        hints: unmanaged > 0 ? [...diff.hints, accessUnmanagedHint(unmanaged, environment)] : diff.hints,
+        ...(rebuildOps.length > 0 ? { rebuildOps } : {}),
+        ...(unreadable.length > 0 ? { unreadable } : {}),
+    };
+}
+export async function runPlan(ctx) {
+    const { positional, json } = split(ctx.rawArgs);
+    if (positional.length !== 2) {
+        console.error("usage: chant sql plan <env> <build.json> [--json]");
+        return 1;
+    }
+    if (outputDialect(positional[1]) === "postgres") {
+        const { planPgAgainstServer, emitPg } = await import("../../postgres/plan/commands.js");
+        return emitPg(await planPgAgainstServer(positional[0], positional[1]), json, `${positional[1]} against ${positional[0]}`);
+    }
+    const diff = await planAgainstServer(positional[0], positional[1]);
+    return emit(diff, json, `${positional[1]} against ${positional[0]}`);
+}
+export const sqlCommands = {
+    name: "sql",
+    description: "Schema changes, classified: between two builds, or a build and a live server",
+    commands: [
+        { name: "diff", description: "Classify the change between two chant build outputs (offline); --statements prints the statements it takes, --topology renders them for single, cluster:<name>, replicated or cloud", handler: runDiff },
+        { name: "plan", description: "Classify the change from an environment's server to a chant build output", handler: runPlan },
+        {
+            name: "types",
+            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),
+        },
+    ],
+};

package/dist/clickhouse/plan/deep.js

@@ -0,0 +1,345 @@
+/**
+ * `observeResourcesDeep()` for the ClickHouse dialect: each declared object's
+ * live definition as a property tree in the declaration's own shape, so
+ * `chant lifecycle diff --live` and `plan` report property drift with no false
+ * drift.
+ *
+ * The reader parses the server's `SHOW CREATE` with the same tag the
+ * declaration used, which gives the same props shape. A field whose canonical
+ * form (`./normalize.ts`) equals the declaration's is written with the
+ * declaration's own value, so `INTERVAL 180 DAY` and `toIntervalDay(180)` do
+ * not read as drift; a field that differs keeps the server's value.
+ * `deepNormalizationHooks` prunes what is not a property of the object (the
+ * DDL text, the template source, lineage, a view's reads and `TO` target).
+ * `chant sql plan` covers the target, and classifies every change.
+ *
+ * On a `cluster:<name>` topology every replica of every shard is read
+ * (#3664). When a server's copy of a table differs from the profile
+ * server's, that copy is what is reported, with the server in `observedOn`,
+ * which the drift report prints as `seen on`.
+ *
+ * Where the profile manages access, the grants an apply would give or take
+ * from each declared grantee are reported as `pending` (#3733), the same
+ * statements `chant sql plan` plans (SQLCH273, SQLCH274), so a privilege
+ * granted or revoked by hand after an approval moves the plan digest.
+ */
+import { deepObservation, } from "@intentius/chant/deep-observation";
+import { bindClickHouse, classifyClickHouseFailure } from "../live/bind.js";
+import { ACCESS_ENTITY_TYPES, ACCESS_UNMANAGED_DETAIL, accessOf, readLiveAccess, readLiveSchema, SYSTEM_DATABASES } from "../live/catalog.js";
+import { clickhouseQuery } from "../http.js";
+import { sqlString } from "../apply/statements.js";
+import { stripMarkerFromStatement } from "../ownership.js";
+import { database, dictionary, func, policy, quota, role, settingsProfile, table, user, view, CLICKHOUSE_ENTITY_TYPES } from "../entities.js";
+import { canonicalObject, grantsObject, objectKey } from "./normalize.js";
+import { grantStatement, grantsByGrantee, revokeStatement } from "../access.js";
+import { renderFor } from "../topology.js";
+// `concurrently` is how a Postgres index is created, not a property of it.
+const PRUNED = new Set(["ddl", "source", "lineage", "reads", "to", "orReplace", "ifNotExists", "concurrently"]);
+export const sqlDeepNormalizationHooks = {
+    prune: (node) => PRUNED.has(node.pattern.split(/[.[]/)[0]),
+};
+function liveProps(o) {
+    const tag = o.type === CLICKHOUSE_ENTITY_TYPES.database
+        ? database
+        : o.type === CLICKHOUSE_ENTITY_TYPES.table
+            ? table
+            : o.type === CLICKHOUSE_ENTITY_TYPES.dictionary
+                ? dictionary
+                : o.type === CLICKHOUSE_ENTITY_TYPES.function
+                    ? func
+                    : o.type === CLICKHOUSE_ENTITY_TYPES.user
+                        ? user
+                        : o.type === CLICKHOUSE_ENTITY_TYPES.role
+                            ? role
+                            : o.type === CLICKHOUSE_ENTITY_TYPES.rowPolicy
+                                ? policy
+                                : o.type === CLICKHOUSE_ENTITY_TYPES.quota
+                                    ? quota
+                                    : o.type === CLICKHOUSE_ENTITY_TYPES.settingsProfile
+                                        ? settingsProfile
+                                        : view;
+    const strings = Object.assign([o.statement], { raw: [o.statement] });
+    return { ...tag(strings).props };
+}
+const sameColumn = (a, b) => {
+    const strip = ({ text: _t, position: _p, previously: _v, ...rest }) => rest;
+    return JSON.stringify(strip(a)) === JSON.stringify(strip(b));
+};
+/** The live props, with each field the declaration means the same as written the declaration's way. */
+export function inDeclaredVocabulary(declared, live, d, l) {
+    const out = { ...live };
+    const same = (k) => JSON.stringify(d[k]) === JSON.stringify(l[k]);
+    const adopt = (key, equal) => {
+        if (!equal)
+            return;
+        if (declared[key] === undefined)
+            delete out[key];
+        else
+            out[key] = declared[key];
+    };
+    adopt("name", d.name === l.name);
+    adopt("database", d.database === l.database);
+    adopt("engine", same("engine"));
+    for (const k of ["orderBy", "primaryKey", "partitionBy", "sampleBy", "ttl", "comment", "select", "refresh", "dataSource", "layout", "lifetime", "range", "asFunction"])
+        adopt(k, same(k));
+    adopt("settings", same("settings"));
+    // A view's DEFINER and SQL SECURITY are not compared by a plan; the server adds its own to a refreshable materialized view (#3911).
+    adopt("security", d.kind === "view" || d.kind === "materializedView");
+    // A user's, role's or row policy's fields, compared as `../access.ts` reads them.
+    if (d.kind === "user" || d.kind === "role" || d.kind === "rowPolicy") {
+        for (const k of ["identified", "host", "validUntil", "defaultRole", "defaultDatabase", "grantees", "settings", "as", "for", "using", "to"]) {
+            adopt(k, d.access?.[k] === l.access?.[k]);
+        }
+        adopt("table", d.table === l.table);
+        // A user's authentication is the environment's unless the declaration says it.
+        if (d.kind === "user" && declared.identified === undefined)
+            delete out.identified;
+    }
+    // A quota's or settings profile's fields; a quota's intervals are one prop, the same when every interval is.
+    if (d.kind === "quota" || d.kind === "settingsProfile") {
+        const fields = (o, pick) => JSON.stringify(Object.entries(o.access ?? {}).filter(([k]) => pick(k)));
+        for (const k of ["keyed", "settings", "to"])
+            adopt(k, d.access?.[k] === l.access?.[k]);
+        adopt("intervals", fields(d, (k) => k.startsWith("interval.")) === fields(l, (k) => k.startsWith("interval.")));
+    }
+    // A function's parameters and expression are one lambda: the same lambda is the declaration's words.
+    adopt("params", d.kind === "function" && same("lambda"));
+    adopt("body", d.kind === "function" && same("lambda"));
+    adopt("indexes", same("indexes"));
+    adopt("projections", same("projections"));
+    adopt("constraints", same("constraints"));
+    const declaredColumns = declared.columns ?? [];
+    if (d.kind === "view" || d.kind === "materializedView" || (d.kind === "table" && d.asFunction !== undefined && declaredColumns.length === 0)) {
+        // The server infers a view's columns, and a table function's (#3911); a declaration that lists none is not drift.
+        if (declaredColumns.length === 0)
+            out.columns = [];
+    }
+    else if (d.kind === "table" || d.kind === "dictionary") {
+        const liveColumns = live.columns ?? [];
+        out.columns = liveColumns.map((c, i) => {
+            const lc = l.columns[i];
+            const dc = d.columns.find((x) => x.name === c.name);
+            const di = dc ? declaredColumns[dc.position] : undefined;
+            return lc && dc && di && sameColumn(lc, dc) ? di : c;
+        });
+    }
+    return out;
+}
+/** The entity types that belong to no database. */
+const GLOBAL_TYPES = new Set([
+    CLICKHOUSE_ENTITY_TYPES.database,
+    CLICKHOUSE_ENTITY_TYPES.function,
+    CLICKHOUSE_ENTITY_TYPES.user,
+    CLICKHOUSE_ENTITY_TYPES.role,
+    CLICKHOUSE_ENTITY_TYPES.quota,
+    CLICKHOUSE_ENTITY_TYPES.settingsProfile,
+]);
+/** Whether the server's formatter prints two expressions the same. A formatter that cannot parse them says no. */
+async function sameExpression(target, a, b) {
+    try {
+        const [row] = await clickhouseQuery(target.endpoint, `SELECT formatQuerySingleLine(${sqlString(`SELECT ${a}`)}) AS a, formatQuerySingleLine(${sqlString(`SELECT ${b}`)}) AS b`);
+        return row !== undefined && row.a === row.b;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * On a `cluster:<name>` topology, read `system.tables` on every replica of
+ * every shard through the profile's server (`clusterAllReplicas`). A change
+ * made on one server without `ON CLUSTER` (a TTL altered on shard 2 alone)
+ * is then seen, which the profile's server alone would not show. Undefined
+ * for any other topology: there is one copy.
+ */
+async function clusterCopies(target) {
+    if (target.topology?.kind !== "cluster")
+        return undefined;
+    const scope = target.databases
+        ? `IN (${target.databases.map(sqlString).join(", ")})`
+        : `NOT IN (${[...SYSTEM_DATABASES].map(sqlString).join(", ")})`;
+    const [self] = await clickhouseQuery(target.endpoint, "SELECT hostName() AS host");
+    const rows = await clickhouseQuery(target.endpoint, `SELECT hostName() AS host, database, name, create_table_query AS statement ` +
+        `FROM clusterAllReplicas(${sqlString(target.topology.cluster)}, system.tables) ` +
+        `WHERE database ${scope} AND NOT is_temporary AND name NOT LIKE '.inner%' AND engine != 'Dictionary' ORDER BY host, database, name`);
+    const byKey = new Map();
+    for (const r of rows) {
+        const key = `${r.database}.${r.name}`;
+        if (!byKey.has(key))
+            byKey.set(key, new Map());
+        byKey.get(key).set(r.host, stripMarkerFromStatement(r.statement));
+    }
+    return { self: self?.host ?? "", byKey };
+}
+/**
+ * When the servers' copies of `key` do not all read the same, the copy to
+ * report and its server: whichever departs furthest from the declaration
+ * `d`, the profile server's own winning a tie. A copy that differs from the
+ * declaration on any server is then the one the diff sees. Undefined when
+ * every copy reads the same.
+ */
+function copyToReport(copies, key, d, defaultDatabase) {
+    const byHost = copies.byKey.get(key);
+    const mine = byHost?.get(copies.self);
+    if (!byHost || mine === undefined)
+        return undefined;
+    const shape = (c) => {
+        const { columns, ...rest } = c;
+        return JSON.stringify({ ...rest, columns: columns.map(({ text: _t, position: _p, ...col }) => col) });
+    };
+    const reference = shape(canonicalObject(mine, defaultDatabase));
+    const declared = JSON.parse(shape(d));
+    /** How many of the declaration's fields this copy holds differently. */
+    const departures = (statement) => {
+        const live = JSON.parse(shape(canonicalObject(statement, defaultDatabase)));
+        return Object.keys({ ...declared, ...live }).filter((k) => k !== "name" && k !== "database" && JSON.stringify(declared[k]) !== JSON.stringify(live[k])).length;
+    };
+    let pick;
+    for (const [host, statement] of byHost) {
+        if (host === copies.self || shape(canonicalObject(statement, defaultDatabase)) === reference)
+            continue;
+        const score = departures(statement);
+        if (!pick || score > pick.score)
+            pick = { host, statement, score };
+    }
+    if (!pick)
+        return undefined;
+    return pick.score > departures(mine) ? { host: pick.host, statement: pick.statement } : { host: copies.self, statement: mine };
+}
+export async function observeResourcesDeep(options) {
+    const resources = {};
+    const unobserved = {};
+    let target;
+    let live;
+    try {
+        target = await bindClickHouse(options);
+        live = [...(await readLiveSchema(target)), ...(target.access === true ? await readLiveAccess(target, accessOf(options.entities, target.defaultDatabase)) : [])];
+    }
+    catch (err) {
+        const why = classifyClickHouseFailure(err);
+        for (const name of options.entityNames) {
+            unobserved[name] = { type: options.entities.get(name)?.entityType ?? "", reason: why.reason, detail: why.detail };
+        }
+        return deepObservation({}, unobserved);
+    }
+    const byKey = new Map(live.map((o) => [objectKey(o), o]));
+    let copies;
+    try {
+        copies = await clusterCopies(target);
+    }
+    catch (err) {
+        // A cluster whose servers cannot all be read is not reported as matching.
+        const why = classifyClickHouseFailure(err);
+        for (const name of options.entityNames) {
+            unobserved[name] = { type: options.entities.get(name)?.entityType ?? "", reason: why.reason, detail: `reading every server of the cluster: ${why.detail}` };
+        }
+        return deepObservation({}, unobserved);
+    }
+    const pending = [];
+    if (target.access === true) {
+        try {
+            pending.push(...(await pendingGrants(target, options.entities)));
+        }
+        catch (err) {
+            const why = classifyClickHouseFailure(err);
+            for (const name of options.entityNames) {
+                if (options.entities.get(name)?.entityType !== CLICKHOUSE_ENTITY_TYPES.grant)
+                    continue;
+                unobserved[name] = { type: CLICKHOUSE_ENTITY_TYPES.grant, reason: "read-failed", detail: `the server's grants could not be compared: ${why.detail}` };
+            }
+        }
+    }
+    for (const name of options.entityNames) {
+        const entity = options.entities.get(name);
+        if (!entity || !entity.entityType.startsWith("ClickHouse::")) {
+            unobserved[name] = { type: entity?.entityType ?? "", reason: "unsupported-kind" };
+            continue;
+        }
+        if (target.access !== true && ACCESS_ENTITY_TYPES.has(entity.entityType)) {
+            unobserved[name] = { type: entity.entityType, reason: "filtered", detail: ACCESS_UNMANAGED_DETAIL };
+            continue;
+        }
+        if (entity.entityType === CLICKHOUSE_ENTITY_TYPES.grant) {
+            if (unobserved[name])
+                continue;
+            unobserved[name] = {
+                type: entity.entityType,
+                reason: "unsupported-kind",
+                detail: "a grant is compared as part of its grantees' grants: what an apply would grant or revoke is listed as pending (SQLCH273, SQLCH274)",
+            };
+            continue;
+        }
+        const props = entity.props;
+        const isDb = GLOBAL_TYPES.has(entity.entityType);
+        const db = isDb ? undefined : typeof props.database === "string" ? props.database : target.defaultDatabase;
+        const o = byKey.get(objectKey({ type: entity.entityType, ...(db !== undefined ? { database: db } : {}), name: String(props.name), ...(typeof props.table === "string" ? { table: props.table } : {}) }));
+        if (!o)
+            continue;
+        try {
+            const d = canonicalObject(renderFor(String(props.ddl), target.topology), target.defaultDatabase);
+            const physicalId = o.uuid ?? `${db ? `${db}.` : ""}${o.name}`;
+            const other = copies && !isDb ? copyToReport(copies, `${db ?? ""}.${o.name}`, d, target.defaultDatabase) : undefined;
+            if (other) {
+                // The servers disagree: report the copy that departs from the declaration, and where it was seen.
+                const copy = { ...o, statement: other.host === copies.self ? o.statement : other.statement };
+                resources[name] = {
+                    type: o.type,
+                    physicalId,
+                    properties: inDeclaredVocabulary(props, liveProps(copy), d, canonicalObject(copy.statement, target.defaultDatabase)),
+                    observedOn: other.host,
+                };
+                continue;
+            }
+            let l = canonicalObject(o.statement, target.defaultDatabase);
+            // The server prints a function's expression its own way (`k*x + b` as `((k * x) + b)`): its formatter says whether the two are one.
+            if (d.kind === "function" && d.lambda !== l.lambda && (await sameExpression(target, d.lambda ?? "", l.lambda ?? "")))
+                l = { ...l, lambda: d.lambda };
+            // A row policy's condition, the same way.
+            const using = d.access?.using;
+            if (d.kind === "rowPolicy" && using !== undefined && using !== l.access?.using && (await sameExpression(target, using, l.access?.using ?? ""))) {
+                l = { ...l, access: { ...l.access, using } };
+            }
+            resources[name] = {
+                type: o.type,
+                physicalId,
+                properties: inDeclaredVocabulary(props, liveProps(o), d, l),
+            };
+        }
+        catch (err) {
+            unobserved[name] = { type: entity.entityType, reason: "read-failed", detail: `the server's definition does not parse: ${err.message}` };
+        }
+    }
+    return deepObservation(resources, unobserved, pending);
+}
+/**
+ * The grants an apply would give or take from each declared grantee (#3733),
+ * as `chant sql plan` compares them: the declared grants against what
+ * `SHOW GRANTS FOR` prints, atom by atom. One change per grantee, its
+ * REVOKEs before its GRANTs as the applier sends them, with the grant
+ * declarations behind it. A grantee the server does not hold yet is given
+ * every declared grant.
+ */
+export async function pendingGrants(target, entities) {
+    const declared = grantsByGrantee([...entities].map(([name, e]) => ({ export: name, type: e.entityType, ddl: String(e.props.ddl ?? "") })));
+    if (declared.length === 0)
+        return [];
+    const live = await readLiveAccess(target, declared.map((g) => ({ kind: "grants", name: g.grantee })));
+    const held = new Map(live.filter((o) => o.type === CLICKHOUSE_ENTITY_TYPES.grant).map((o) => [o.name, grantsObject(o.statement, o.name, target.defaultDatabase).access ?? {}]));
+    const atom = (json) => JSON.parse(json);
+    const out = [];
+    for (const g of declared) {
+        const want = grantsObject(g.ddl, g.grantee, target.defaultDatabase).access ?? {};
+        const have = held.get(g.grantee) ?? {};
+        const statements = [
+            ...Object.keys(have)
+                .filter((k) => !(k in want))
+                .map((k) => revokeStatement(atom(have[k]), g.grantee)),
+            ...Object.keys(want)
+                .filter((k) => !(k in have))
+                .map((k) => grantStatement(atom(want[k]), g.grantee)),
+        ];
+        if (statements.length === 0)
+            continue;
+        out.push({ subject: `grants ${g.grantee}`, change: statements.join("; "), entities: [...g.exports].sort() });
+    }
+    return out;
+}