@intentius/chant-lexicon-sql 0.124.30 → 0.124.32

package/dist/plugin.js

@@ -0,0 +1,259 @@
+/**
+ * The sql lexicon plugin.
+ *
+ * One lexicon, a subpath per database dialect (#3047, "Packaging"): ClickHouse
+ * at `@intentius/chant-lexicon-sql/clickhouse`, Postgres at
+ * `@intentius/chant-lexicon-sql/postgres` (#3289). Generation reads
+ * the pinned ClickHouse server's catalog (src/spec/), and the rest of the
+ * plugin is the shared machinery every dialect plugs into.
+ */
+import { sqlSerializer } from "./serializer.js";
+import { rules } from "./lint/rules/index.js";
+import { postSynthChecks as postSynthCheckList } from "./lint/post-synth/index.js";
+import { sqlAuditCatalog } from "./lint/audit-catalog.js";
+import { completions } from "./lsp/completions.js";
+import { hover } from "./lsp/hover.js";
+import { sqlMcpResources, sqlMcpTools } from "./mcp/index.js";
+import { sqlConfigSchema } from "./config.js";
+import { SqlFileParser, dialectOption } from "./import-parser.js";
+import { sqlTemplateGenerator } from "./import-generator.js";
+import { sqlCommands } from "./clickhouse/plan/commands.js";
+import { sqlDeepNormalizationHooks } from "./clickhouse/plan/deep.js";
+import { versionFromReleaseTag } from "./spec/pin.js";
+import { POSTGRES_MAJORS, postgresUpstreamPin } from "./spec/postgres-pin.js";
+import { SQL_OWNERSHIP_CHANNEL } from "./clickhouse/ownership.js";
+import { CLICKHOUSE_EMULATOR } from "./op/activities/clickhouse-emulator.js";
+import { POSTGRES_EMULATOR } from "./op/activities/postgres-emulator.js";
+import { sqlSkills } from "./skill-defs.js";
+import { detectTemplate } from "./detect.js";
+import { sqlWorkspaceOutputs } from "./workspace-outputs.js";
+import { CDC_TEMPLATE, DEFAULT_TEMPLATE, EVENTS_TEMPLATE, POSTGRES_EVENTS_TEMPLATE, POSTGRES_TEMPLATE, POSTGRES_TENANT_TEMPLATE } from "./init-templates.js";
+import { compositeCatalog } from "./composites/catalog.js";
+export const sqlPlugin = {
+    name: "sql",
+    serializer: sqlSerializer,
+    configSchema: sqlConfigSchema,
+    /** The pinned clickhouse-server (#3208) and postgres (#3280), for `chant emulator up`. */
+    emulator: [CLICKHOUSE_EMULATOR, POSTGRES_EMULATOR],
+    /** chant's marker is a trailer on the object's comment (#3208, ./clickhouse/ownership.ts). */
+    ownershipChannel: SQL_OWNERSHIP_CHANNEL,
+    async generate(options) {
+        const { generate, writeGeneratedFiles } = await import("./codegen/generate.js");
+        writeGeneratedFiles(await generate(options));
+    },
+    async validate(_options) {
+        const { validate } = await import("./validate.js");
+        const { printValidationResult } = await import("@intentius/chant/codegen/validate");
+        printValidationResult(await validate());
+    },
+    async coverage(options) {
+        const { analyze, printCoverage } = await import("./coverage.js");
+        printCoverage(analyze(), options);
+    },
+    async package(options) {
+        const { packageLexicon } = await import("./codegen/package.js");
+        const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
+        const { join, dirname } = await import("path");
+        const { fileURLToPath } = await import("url");
+        const { spec, stats } = await packageLexicon(options);
+        writeBundleSpec(spec, join(dirname(dirname(fileURLToPath(import.meta.url))), "dist"));
+        console.error(`Packaged ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+    },
+    lintRules() {
+        return rules;
+    },
+    postSynthChecks() {
+        return postSynthCheckList;
+    },
+    auditCatalog() {
+        return sqlAuditCatalog;
+    },
+    /**
+     * The tags fold: `chant build` reduces a `table`, `view` or other template
+     * to the entity the tag builds, without running the file. An intrinsic is
+     * registered by name and folds as the function the file imports, so
+     * `table` from `/clickhouse` and `table` from `/postgres` are each their
+     * own dialect's. `literal(...)` folds as a call so it can sit inside a tag.
+     */
+    intrinsics() {
+        return [
+            { name: "database", isTag: true, description: "A ClickHouse CREATE DATABASE, parsed into a database entity" },
+            { name: "table", isTag: true, description: "A ClickHouse or Postgres CREATE TABLE, parsed into a table entity" },
+            {
+                name: "view",
+                isTag: true,
+                description: "A CREATE VIEW or CREATE MATERIALIZED VIEW, parsed into a view entity with its lineage",
+            },
+            { name: "dictionary", isTag: true, description: "A ClickHouse CREATE DICTIONARY, parsed into a dictionary entity with its attributes, key, source and layout" },
+            { name: "user", isTag: true, description: "A ClickHouse CREATE USER, parsed into a user entity; its password is the environment's" },
+            { name: "quota", isTag: true, description: "A ClickHouse CREATE QUOTA, parsed into a quota entity with its key, its intervals' limits and whom it applies to" },
+            { name: "settingsProfile", isTag: true, description: "A ClickHouse CREATE SETTINGS PROFILE, parsed into a settings profile entity with its settings, constraints and inherited profiles" },
+            { name: "schema", isTag: true, description: "A Postgres CREATE SCHEMA, parsed into a schema entity" },
+            { name: "index", isTag: true, description: "A Postgres CREATE INDEX, parsed into an index entity" },
+            { name: "sequence", isTag: true, description: "A Postgres CREATE SEQUENCE, parsed into a sequence entity" },
+            { name: "type", isTag: true, description: "A Postgres CREATE TYPE ... AS ENUM, AS (...) or AS RANGE, parsed into an enum, composite or range type entity" },
+            { name: "domain", isTag: true, description: "A Postgres CREATE DOMAIN, parsed into a domain entity" },
+            { name: "extension", isTag: true, description: "A Postgres CREATE EXTENSION, parsed into an extension entity" },
+            { name: "func", isTag: true, description: "A Postgres CREATE FUNCTION, parsed into a function entity with its body kept verbatim, or a ClickHouse CREATE FUNCTION (a named lambda)" },
+            { name: "procedure", isTag: true, description: "A Postgres CREATE PROCEDURE, parsed into a procedure entity with its body kept verbatim" },
+            { name: "aggregate", isTag: true, description: "A Postgres CREATE AGGREGATE, parsed into an aggregate entity identified by its argument types" },
+            { name: "trigger", isTag: true, description: "A Postgres CREATE TRIGGER, parsed into a trigger entity on its table" },
+            { name: "eventTrigger", isTag: true, description: "A Postgres CREATE EVENT TRIGGER, parsed into the database's event trigger entity" },
+            { name: "collation", isTag: true, description: "A Postgres CREATE COLLATION, parsed into a collation entity" },
+            { name: "cast", isTag: true, description: "A Postgres CREATE CAST, parsed into a cast entity named by its two types" },
+            { name: "policy", isTag: true, description: "A Postgres CREATE POLICY, parsed into a row-level security policy on its table, or a ClickHouse CREATE ROW POLICY" },
+            { name: "role", isTag: true, description: "A Postgres CREATE ROLE without a password or memberships, parsed into a role entity, or a ClickHouse CREATE ROLE" },
+            { name: "grant", isTag: true, description: "A Postgres GRANT, REVOKE or ALTER DEFAULT PRIVILEGES, parsed into the privileges it declares, or a ClickHouse GRANT of privileges or roles" },
+            {
+                name: "literal",
+                isTag: false,
+                foldsAsCall: true,
+                description: "A quoted, escaped SQL string literal, for a string interpolated as a value rather than as SQL text",
+            },
+        ];
+    },
+    skills: sqlSkills,
+    /** The ClickHouse and Postgres composites (./composites), as the catalog generated from their exports. */
+    composites() {
+        return compositeCatalog;
+    },
+    // `chant init --lexicon sql [--template events|cdc|postgres|postgres-tenant|postgres-events]`; see ./init-templates.ts.
+    initTemplates(template) {
+        if (template === "events")
+            return EVENTS_TEMPLATE;
+        if (template === "cdc")
+            return CDC_TEMPLATE;
+        if (template === "postgres")
+            return POSTGRES_TEMPLATE;
+        if (template === "postgres-tenant")
+            return POSTGRES_TENANT_TEMPLATE;
+        if (template === "postgres-events")
+            return POSTGRES_EVENTS_TEMPLATE;
+        return DEFAULT_TEMPLATE;
+    },
+    detectTemplate(data) {
+        return detectTemplate(data);
+    },
+    completionProvider(ctx) {
+        return completions(ctx);
+    },
+    hoverProvider(ctx) {
+        return hover(ctx);
+    },
+    mcpTools() {
+        return sqlMcpTools();
+    },
+    mcpResources() {
+        return sqlMcpResources();
+    },
+    /** `chant import schema.sql`: a file of Postgres or ClickHouse DDL (`./import-parser.ts`). */
+    templateParser(options) {
+        return new SqlFileParser(dialectOption(options), { skipUndeclarable: options?.skipUndeclarable === true });
+    },
+    parserOptions() {
+        return [
+            {
+                name: "dialect",
+                type: "string",
+                description: "the DDL's dialect, clickhouse or postgres; read off its statements when omitted",
+            },
+            {
+                name: "skipUndeclarable",
+                type: "boolean",
+                description: "import the rest of the file, and list each CREATE of a kind chant cannot declare (an aggregate, a cast, a quota) as a warning instead of failing",
+            },
+        ];
+    },
+    /**
+     * The `.sql` files in the source directory, read into declarations beside
+     * the tagged templates (`./files/build-root.ts`, #3646).
+     */
+    async buildRoots(ctx) {
+        const { sqlFilesBuildRoot } = await import("./files/build-root.js");
+        return sqlFilesBuildRoot(ctx);
+    },
+    /**
+     * Each table and view, and each of their columns, as workspace outputs
+     * (`./workspace-outputs.ts`, #3931): `public.orders`,
+     * `public.orders.customer_id`. Another member's link to a dropped or
+     * renamed column then fails `chant workspace check`.
+     */
+    workspaceOutputs(entities, unread) {
+        return sqlWorkspaceOutputs(entities, unread);
+    },
+    /** One generator for both dialects: each IR resource's type says whose declarations it is. */
+    templateGenerator() {
+        return sqlTemplateGenerator;
+    },
+    /**
+     * Which declared objects exist on the environment's server
+     * (`sql.profiles.<env>`, else `CLICKHOUSE_URL` or `POSTGRES_URL`). The
+     * declarations' dialect picks the reader; node-postgres loads only for a
+     * Postgres one.
+     */
+    async describeResources(options) {
+        const { dialectOfEntities } = await import("./live-dialect.js");
+        if (dialectOfEntities(options.entities) === "postgres") {
+            const { describeResources } = await import("./postgres/live/describe-resources.js");
+            return describeResources(options);
+        }
+        const { describeResources } = await import("./clickhouse/live/describe-resources.js");
+        return describeResources(options);
+    },
+    /** `chant import --from <env>`: the server's schema as declarations, from `SHOW CREATE` or the Postgres catalog's printers. */
+    async exportResources(options) {
+        const { resolveBindingDialect } = await import("./live-dialect.js");
+        if ((await resolveBindingDialect(options)) === "postgres") {
+            const { exportResources } = await import("./postgres/import/live-export.js");
+            return exportResources(options);
+        }
+        const { exportResources } = await import("./clickhouse/import/live-export.js");
+        return exportResources(options);
+    },
+    /** Each declared object's live definition, in the declaration's own shape. */
+    async observeResourcesDeep(options) {
+        const { dialectOfEntities } = await import("./live-dialect.js");
+        if (dialectOfEntities(options.entities) === "postgres") {
+            const { observeResourcesDeep } = await import("./postgres/plan/deep.js");
+            return observeResourcesDeep(options);
+        }
+        const { observeResourcesDeep } = await import("./clickhouse/plan/deep.js");
+        return observeResourcesDeep(options);
+    },
+    deepNormalizationHooks: sqlDeepNormalizationHooks,
+    /**
+     * What an update costs. ClickHouse: metadata in-place, a background rewrite
+     * rolling, a rebuild replace. Postgres: metadata in-place, a validation, a
+     * CONCURRENTLY build or an ACCESS EXCLUSIVE rewrite rolling, expand and
+     * contract replace. Each dialect answers for its own types.
+     */
+    async classifyDisruption(options) {
+        const { classifyDisruption } = await import("./clickhouse/plan/disruption.js");
+        const { classifyPgDisruption } = await import("./postgres/plan/disruption.js");
+        return { ...classifyDisruption(options), ...classifyPgDisruption(options) };
+    },
+    /** `chant sql diff` and `chant sql plan`: schema changes, classified. */
+    commands() {
+        return sqlCommands;
+    },
+    async docs(options) {
+        const { generateDocs } = await import("./codegen/docs.js");
+        await generateDocs(options);
+    },
+    /**
+     * The pin is a ClickHouse LTS release. GitHub tags them `v26.8.15.10-lts`;
+     * the constant holds `26.8.15.10`, which is also the docker tag. A move also
+     * needs `CLICKHOUSE_IMAGE_DIGEST` updated: generation refuses a server whose
+     * version is not the pin.
+     */
+    upstreamPin: {
+        label: "clickhouse",
+        file: "src/spec/pin.ts",
+        pattern: /export const CLICKHOUSE_VERSION\s*=\s*"([^"]+)"/,
+        replace: (v, line) => line.replace(/= "[^"]+"/, `= "${versionFromReleaseTag(v)}"`),
+        alsoMoves: "CLICKHOUSE_IMAGE_DIGEST in src/spec/pin.ts moves with the version: set CLICKHOUSE_VERSION to the new release, set the digest to that tag's image digest (docker buildx imagetools inspect clickhouse/clickhouse-server:<version>), then run `chant dev generate` and read the diff of src/spec/clickhouse-catalog.snapshot.json.",
+        upstream: { owner: "ClickHouse", repo: "ClickHouse", kind: "releases", tagSuffix: "-lts" },
+    },
+    /** The Postgres servers, one pin per major (`postgres-14` to `postgres-18`). */
+    upstreamPins: POSTGRES_MAJORS.map(postgresUpstreamPin),
+};

package/dist/postgres/access/acl.js

@@ -0,0 +1,344 @@
+/**
+ * Access as chant compares it (#3681): the privileges each role holds on each
+ * object, and the default privileges objects are created with.
+ *
+ * A `grant` declaration is a statement, not an object: `GRANT SELECT ON a, b
+ * TO r1, r2` is four privileges, and the catalog keeps no statement, only
+ * each object's access control list. So declarations and the server are both
+ * brought to the same form, one entry per object (or column) and grantee
+ * holding a set of privileges, and those entries are compared.
+ *
+ * What a declared object's entries should be:
+ *
+ * - what Postgres gives a new object of its kind, the owner's own privileges
+ *   left out (a function or procedure: EXECUTE to PUBLIC; anything else:
+ *   nothing);
+ * - with the declared default privileges for objects of that kind created by
+ *   the role that applies, globally and in the object's schema, since chant
+ *   creates it as that role;
+ * - with every declared GRANT added and every declared REVOKE taken away, in
+ *   the build's order.
+ *
+ * The owner's own privileges are never compared: the owner has them by
+ * owning the object. A grant on an object the build does not declare (the
+ * `public` schema) is compared too, from what Postgres gives a new object.
+ *
+ * Default privileges are compared for the role that applies (and each role a
+ * declaration names with `FOR ROLE`): globally, where none declared means
+ * Postgres's own defaults, and per schema, where none declared means none.
+ */
+import { quoteIdent } from "../keywords.js";
+import { PG_CLASSIFIER_RULES } from "../plan/rules.js";
+import { classifiedChange } from "../../core/classifier.js";
+const SELF = "";
+/** A target's key: relations (tables, views, sequences) share one namespace, as in the catalog. */
+export function targetKey(t) {
+    switch (t.kind) {
+        case "schema":
+            return `schema ${t.name}`;
+        case "table":
+        case "sequence":
+            return `relation ${t.name}`;
+        case "column":
+            return `relation ${t.name} (${quoteIdent(t.column ?? "")})`;
+        case "function":
+        case "procedure":
+            return `routine ${t.name}`;
+        case "default":
+            return `default privileges${t.role ? ` for ${quoteIdent(t.role)}` : ""}${t.schema !== undefined ? ` in ${quoteIdent(t.schema)}` : ""} on ${t.objects}`;
+    }
+}
+export const entryKey = (t, grantee) => `${targetKey(t)} TO ${grantee === "public" ? "PUBLIC" : quoteIdent(grantee)}`;
+/** Every privilege of a kind of object, as ALL PRIVILEGES grants them. MAINTAIN is a table's from 17. */
+export function allPrivileges(kind, major) {
+    switch (kind) {
+        case "table":
+        case "tables":
+            return ["select", "insert", "update", "delete", "truncate", "references", "trigger", ...(major >= 17 ? ["maintain"] : [])];
+        case "sequence":
+        case "sequences":
+            return ["usage", "select", "update"];
+        case "schema":
+        case "schemas":
+            return ["usage", "create"];
+        case "function":
+        case "procedure":
+        case "functions":
+            return ["execute"];
+        case "types":
+            return ["usage"];
+        case "column":
+            return ["select", "insert", "update", "references"];
+        case "default":
+            return [];
+    }
+}
+/** What Postgres gives a new object of a kind, the owner's own privileges left out: EXECUTE on a routine and USAGE on a type to PUBLIC. */
+export function builtinEntries(kind) {
+    if (kind === "function" || kind === "procedure" || kind === "functions")
+        return [{ grantee: "public", privilege: "execute" }];
+    if (kind === "types")
+        return [{ grantee: "public", privilege: "usage" }];
+    return [];
+}
+/** The default-privileges kind an object kind is created as. */
+const defaultObjectsOf = (kind) => kind === "table" ? "tables" : kind === "sequence" ? "sequences" : kind === "function" || kind === "procedure" ? "functions" : kind === "schema" ? "schemas" : undefined;
+function add(state, target, grantee, privilege, grantable) {
+    const key = entryKey(target, grantee);
+    let e = state.get(key);
+    if (!e)
+        state.set(key, (e = { target, grantee, privileges: new Map() }));
+    e.privileges.set(privilege, grantable || e.privileges.get(privilege) === true);
+}
+function remove(state, target, grantee, privilege, grantOptionOnly) {
+    const e = state.get(entryKey(target, grantee));
+    if (!e || !e.privileges.has(privilege))
+        return;
+    if (grantOptionOnly)
+        e.privileges.set(privilege, false);
+    else
+        e.privileges.delete(privilege);
+}
+/** The state with every empty entry left out. */
+const compact = (state) => new Map([...state].filter(([, e]) => e.privileges.size > 0));
+/**
+ * The access a set of declarations adds up to. `objects` are canonical, in
+ * the build's order, keyed by export name. `self` is the role that applies,
+ * when known: a declaration naming it with `FOR ROLE` is its own default
+ * privileges, and a grant to it is the owner's, which is never compared.
+ */
+export function declaredAccess(objects, opts) {
+    const state = new Map();
+    const exportsOf = new Map();
+    const targets = new Map();
+    const relationKind = new Map();
+    const routineKind = new Map();
+    const forRoles = new Set();
+    const roleOf = (r) => (r === undefined || r === opts.self ? SELF : r);
+    const note = (key, exportName) => exportsOf.set(key, [...new Set([...(exportsOf.get(key) ?? []), exportName])]);
+    // The objects themselves.
+    const declaredTargets = [];
+    for (const { canonical: o } of objects) {
+        const name = `${o.schema ? `${quoteIdent(o.schema)}.` : ""}${quoteIdent(o.name)}`;
+        if (o.kind === "schema")
+            declaredTargets.push({ kind: "schema", name: quoteIdent(o.name) });
+        else if (o.kind === "table" || o.kind === "view" || o.kind === "materializedView") {
+            relationKind.set(name, "table");
+            declaredTargets.push({ kind: "table", name });
+        }
+        else if (o.kind === "sequence") {
+            relationKind.set(name, "sequence");
+            declaredTargets.push({ kind: "sequence", name });
+        }
+        else if (o.kind === "function" || o.kind === "procedure") {
+            routineKind.set(`${name}${o.signature ?? ""}`, o.kind);
+            declaredTargets.push({ kind: o.kind, name: `${name}${o.signature ?? ""}` });
+        }
+    }
+    // Default privileges, per role, schema and kind of object.
+    const defaults = new Map();
+    const declaredDefaults = new Set();
+    for (const { key: exportName, canonical: o } of objects) {
+        if (o.kind !== "defaultPrivileges")
+            continue;
+        const g = o.fields.grant;
+        const on = g.on;
+        for (const r of g.forRoles ?? [undefined]) {
+            const role = roleOf(r);
+            if (role !== SELF)
+                forRoles.add(role);
+            for (const schema of g.inSchemas ?? [undefined]) {
+                const target = { kind: "default", name: "", role, ...(schema !== undefined ? { schema } : {}), objects: on };
+                const tk = targetKey(target);
+                if (!declaredDefaults.has(tk)) {
+                    declaredDefaults.add(tk);
+                    targets.set(tk, target);
+                    // A global entry starts from Postgres's own defaults; a schema's from nothing.
+                    if (schema === undefined)
+                        for (const b of builtinEntries(on))
+                            add(defaults, target, b.grantee, b.privilege, false);
+                }
+                for (const grantee of g.grantees) {
+                    for (const p of g.privileges) {
+                        for (const privilege of p.privilege === "all" ? allPrivileges(on, opts.major) : [p.privilege]) {
+                            if (g.action === "grant")
+                                add(defaults, target, grantee, privilege, g.withGrantOption === true);
+                            else
+                                remove(defaults, target, grantee, privilege, g.grantOptionFor === true);
+                        }
+                    }
+                    note(entryKey(target, grantee), exportName);
+                }
+            }
+        }
+    }
+    for (const [k, e] of defaults)
+        state.set(k, e);
+    /** What an object chant creates is given: Postgres's defaults, or the declared global ones, and the declared ones for its schema. */
+    const created = (t, schema) => {
+        const objectsKind = defaultObjectsOf(t.kind);
+        const global = objectsKind ? [...defaults.values()].filter((e) => e.target.role === SELF && e.target.schema === undefined && e.target.objects === objectsKind) : [];
+        const anyGlobal = objectsKind !== undefined && declaredDefaults.has(targetKey({ kind: "default", name: "", role: SELF, objects: objectsKind }));
+        if (!anyGlobal)
+            for (const b of builtinEntries(t.kind))
+                add(state, t, b.grantee, b.privilege, false);
+        for (const e of global)
+            for (const [p, g] of e.privileges)
+                add(state, t, e.grantee, p, g);
+        if (objectsKind && schema !== undefined && objectsKind !== "schemas") {
+            for (const e of defaults.values()) {
+                if (e.target.role === SELF && e.target.schema === schema && e.target.objects === objectsKind)
+                    for (const [p, g] of e.privileges)
+                        add(state, t, e.grantee, p, g);
+            }
+        }
+    };
+    for (const t of declaredTargets) {
+        targets.set(targetKey(t), t);
+        const schema = t.kind === "schema" ? undefined : unquotedSchema(t.name);
+        created(t, schema);
+    }
+    // Grants and revokes, in the build's order.
+    for (const { key: exportName, canonical: o } of objects) {
+        if (o.kind !== "grant")
+            continue;
+        const g = o.fields.grant;
+        for (const name of g.objects ?? []) {
+            const kind = g.on === "schema"
+                ? "schema"
+                : g.on === "sequence"
+                    ? "sequence"
+                    : g.on === "table"
+                        ? (relationKind.get(name) ?? "table")
+                        : g.on === "procedure"
+                            ? "procedure"
+                            : g.on === "function"
+                                ? "function"
+                                : (routineKind.get(name) ?? "function");
+            const target = { kind, name };
+            const tk = targetKey(target);
+            if (!targets.has(tk)) {
+                // An object the build does not declare starts from what Postgres gives a new one.
+                targets.set(tk, target);
+                for (const b of builtinEntries(kind))
+                    add(state, target, b.grantee, b.privilege, false);
+            }
+            for (const grantee of g.grantees) {
+                for (const p of g.privileges) {
+                    const on = p.columns ? p.columns.map((column) => ({ kind: "column", name, column })) : [target];
+                    for (const t of on) {
+                        if (t.kind === "column")
+                            targets.set(targetKey(t), t);
+                        for (const privilege of p.privilege === "all" ? allPrivileges(t.kind, opts.major) : [p.privilege]) {
+                            if (g.action === "grant")
+                                add(state, t, grantee, privilege, g.withGrantOption === true);
+                            else
+                                remove(state, t, grantee, privilege, g.grantOptionFor === true);
+                        }
+                        note(entryKey(t, grantee), exportName);
+                    }
+                }
+            }
+        }
+    }
+    // A grant to the role that applies is the owner's, which owning gives.
+    const out = compact(new Map([...state].filter(([, e]) => opts.self === undefined || e.grantee !== opts.self)));
+    return { state: out, targets: [...targets.values()], exportsOf, forRoles: [...forRoles].sort() };
+}
+/** The schema of a canonical qualified name, unquoted. */
+function unquotedSchema(name) {
+    const m = /^("(?:[^"]|"")*"|[^."]+)\./.exec(name);
+    if (!m)
+        return undefined;
+    return m[1].startsWith('"') ? m[1].slice(1, -1).replace(/""/g, '"') : m[1];
+}
+const show = (privileges) => privileges && privileges.size > 0 ? [...privileges].sort(([a], [b]) => (a < b ? -1 : 1)).map(([p, g]) => `${p}${g ? "*" : ""}`).join(", ") : undefined;
+const ON = { schema: "SCHEMA", table: "TABLE", sequence: "SEQUENCE", function: "FUNCTION", procedure: "PROCEDURE" };
+/** The `ON ...` and grantee of an entry's statements. */
+function onClause(t) {
+    if (t.kind === "column" || t.kind === "default")
+        return "";
+    return `ON ${ON[t.kind]} ${t.name}`;
+}
+const granteeSql = (g) => (g === "public" ? "PUBLIC" : quoteIdent(g));
+/** One GRANT or REVOKE for a set of privileges on one entry's target. */
+function statement(t, grantee, action, privileges, withGrantOption = false) {
+    const list = privileges.map((p) => p.toUpperCase()).join(", ");
+    const verb = action === "grant" ? "GRANT" : action === "revoke" ? "REVOKE" : "REVOKE GRANT OPTION FOR";
+    const to = action === "grant" ? "TO" : "FROM";
+    const tail = action === "grant" && withGrantOption ? " WITH GRANT OPTION" : "";
+    if (t.kind === "column")
+        return `${verb} ${privileges.map((p) => `${p.toUpperCase()} (${quoteIdent(t.column ?? "")})`).join(", ")} ON TABLE ${t.name} ${to} ${granteeSql(grantee)}${tail}`;
+    if (t.kind === "default") {
+        const head = `ALTER DEFAULT PRIVILEGES${t.role ? ` FOR ROLE ${quoteIdent(t.role)}` : ""}${t.schema !== undefined ? ` IN SCHEMA ${quoteIdent(t.schema)}` : ""}`;
+        return `${head} ${verb} ${list} ON ${String(t.objects).toUpperCase()} ${to} ${granteeSql(grantee)}${tail}`;
+    }
+    return `${verb} ${list} ${onClause(t)} ${to} ${granteeSql(grantee)}${tail}`;
+}
+/**
+ * The changes from `before` to `after`, one per entry and direction, each
+ * with its statements: revokes first (a privilege, then a grant option), then
+ * grants (a grant option on its own with WITH GRANT OPTION).
+ */
+export function diffAccess(before, after, exportsOf = new Map()) {
+    const out = [];
+    const keys = [...new Set([...before.keys(), ...after.keys()])].sort();
+    for (const key of keys) {
+        const b = before.get(key);
+        const a = after.get(key);
+        const target = (a ?? b).target;
+        const grantee = (a ?? b).grantee;
+        const bp = b?.privileges ?? new Map();
+        const ap = a?.privileges ?? new Map();
+        const revoke = [...bp.keys()].filter((p) => !ap.has(p)).sort();
+        const revokeOption = [...bp].filter(([p, g]) => g && ap.get(p) === false).map(([p]) => p).sort();
+        const grant = [...ap].filter(([p, g]) => !bp.has(p) || (g && bp.get(p) === false)).map(([p]) => p).sort();
+        if (revoke.length + revokeOption.length + grant.length === 0)
+            continue;
+        const exports = exportsOf.get(key) ?? [];
+        const rule = target.kind === "default" ? "SQLPG298" : revoke.length + revokeOption.length > 0 && grant.length === 0 ? "SQLPG297" : "SQLPG296";
+        const sql = [];
+        if (revoke.length > 0)
+            sql.push(statement(target, grantee, "revoke", revoke));
+        if (revokeOption.length > 0)
+            sql.push(statement(target, grantee, "revoke-option", revokeOption));
+        const plain = grant.filter((p) => ap.get(p) === false);
+        const withOption = grant.filter((p) => ap.get(p) === true);
+        if (plain.length > 0)
+            sql.push(statement(target, grantee, "grant", plain));
+        if (withOption.length > 0)
+            sql.push(statement(target, grantee, "grant", withOption, true));
+        const change = classifiedChange(PG_CLASSIFIER_RULES, `acl ${key}`, "privileges", rule, show(bp), show(ap), revoke.length > 0 && grant.length > 0 ? { note: `revokes ${revoke.join(", ")}` } : {});
+        out.push({ change, target, grantee, sql, exports });
+    }
+    return out;
+}
+/**
+ * The entries the server would give each declared object that does not exist
+ * yet: Postgres's defaults, or the role's global default privileges, and its
+ * default privileges in the object's schema.
+ */
+export function predictedAccess(missing, live) {
+    const out = new Map();
+    const defaults = [...live.state.values()].filter((e) => e.target.kind === "default" && e.target.role === SELF);
+    for (const t of missing) {
+        const objectsKind = defaultObjectsOf(t.kind);
+        if (!objectsKind)
+            continue;
+        if (!live.globalDefaults.has(objectsKind))
+            for (const b of builtinEntries(t.kind))
+                add(out, t, b.grantee, b.privilege, false);
+        const schema = t.kind === "schema" ? undefined : unquotedSchema(t.name);
+        for (const e of defaults) {
+            if (e.target.objects !== objectsKind)
+                continue;
+            if (e.target.schema === undefined || (e.target.schema === schema && objectsKind !== "schemas"))
+                for (const [p, g] of e.privileges)
+                    add(out, t, e.grantee, p, g);
+        }
+    }
+    return compact(out);
+}
+/** Adds an entry, for the live reader. */
+export const addEntry = add;
+export { SELF as APPLYING_ROLE };

package/dist/postgres/access/changes.js

@@ -0,0 +1,30 @@
+/**
+ * The privilege changes a connected server needs (#3681): what `chant sql
+ * plan` reports, and what the deep read reports as pending so the plan digest
+ * an approval binds to moves with a privilege granted or revoked by hand
+ * (#3706).
+ */
+import { declaredAccess, diffAccess, predictedAccess, targetKey } from "./acl.js";
+import { readLiveAccess } from "./live.js";
+/** The role a session runs as: the one whose own privileges owning an object gives, and whose default privileges apply. */
+async function currentRole(client) {
+    const rows = await client.query("SELECT current_user AS self").catch(() => []);
+    return rows[0]?.self ? { self: rows[0].self } : {};
+}
+/**
+ * The changes from the access the server holds to the access the
+ * declarations (keyed by export name, in the build's order) add up to. An
+ * object the server does not hold yet is taken to have what the server gives
+ * a new one. `scope` limits the default privileges read to those schemas.
+ */
+export async function accessChangesAgainst(client, declared, options) {
+    const want = declaredAccess(declared, { major: options.major, ...(await currentRole(client)) });
+    const have = await readLiveAccess(client, want.targets, {
+        ...(options.scope ? { schemas: options.scope } : {}),
+        forRoles: want.forRoles,
+        declaredDefaults: want.targets.filter((t) => t.kind === "default"),
+    });
+    const missing = want.targets.filter((t) => t.kind !== "default" && t.kind !== "column" && !have.present.has(targetKey(t)));
+    const now = new Map([...have.state, ...predictedAccess(missing, have)]);
+    return diffAccess(now, want.state, want.exportsOf);
+}