@intentius/chant-lexicon-sql 0.118.0 → 0.120.0

package/src/op/apply-gate-access-clickhouse.e2e.test.ts

@@ -0,0 +1,195 @@
+/**
+ * An approval does not cover a ClickHouse privilege granted by hand after it
+ * (#3733), end to end with a profile that manages access. The Postgres
+ * counterpart is `./apply-gate-access.e2e.test.ts`.
+ *
+ * A project in a temporary directory declares a database, a table, a reader
+ * role and a grant of SELECT on the table to it, and a gated `ApplyOp`. The
+ * first approved run creates them. The next run stops at the gate; the test
+ * approves its plan, grants INSERT on the table to the role by hand, and runs
+ * again. The gate refuses with "is approved, but not for this plan", the hand
+ * grant is still there, and the plan the run printed lists the REVOKE an
+ * apply would make. Approving that plan applies it.
+ *
+ * Before #3733 the plan digest was taken over a diff that left grants out (a
+ * grant was unobserved there), so the third run revoked the hand grant under
+ * the earlier approval.
+ *
+ * Everything is written to the database `chant_e2e_3733` and the role
+ * `chant_e2e_3733_reader`, both dropped afterwards.
+ *
+ * The server: `CHANT_SQL_GATE_CLICKHOUSE_URL` names a running one, such as
+ * the one `chant emulator up --lexicon sql` starts. Without it, a throwaway
+ * server at the pin, skipped cleanly when Docker is not available.
+ */
+
+import { execFile } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { dockerAvailable, startScratchServer, type ScratchServer } from "../clickhouse/container";
+import { clickhouseQuery, type ClickHouseEndpoint } from "../clickhouse/http";
+import { clickhouseImage } from "../spec/pin";
+
+const exec = promisify(execFile);
+
+const REPO = join(import.meta.dirname, "../../../..");
+const BIN = join(REPO, "node_modules/.bin");
+const DB = "chant_e2e_3733";
+const READER = "chant_e2e_3733_reader";
+const OP = "schema-apply";
+
+const given = process.env.CHANT_SQL_GATE_CLICKHOUSE_URL;
+const enabled = given ? true : await dockerAvailable();
+
+interface Run {
+  code: number;
+  output: string;
+}
+
+const strip = (s: string) => s.replace(/\u001b\[[0-9;]*m/g, "");
+
+const SCHEMA = `import { database, table, role, grant } from "@intentius/chant-lexicon-sql/clickhouse";
+
+export const db = database\`CREATE DATABASE ${DB} ENGINE = Atomic\`;
+
+export const events = table\`
+  CREATE TABLE \${db}.events (
+    id UInt64,
+    kind String
+  )
+  ENGINE = MergeTree
+  ORDER BY id\`;
+
+export const reader = role\`CREATE ROLE ${READER}\`;
+
+export const readEvents = grant\`GRANT SELECT ON \${events} TO \${reader}\`;
+`;
+
+const OPS = `import { ApplyOp } from "@intentius/chant/op";
+const { op } = ApplyOp({ name: "${OP}", env: "admin", target: "clickhouse", gate: { gate: "approve-schema" } });
+export default op;
+`;
+
+const config = (url: string) => `import type { ChantConfig } from "@intentius/chant";
+import "@intentius/chant-lexicon-sql";
+
+export default {
+  lexicons: ["sql"],
+  ownership: { stack: "e2e-3733", env: "admin" },
+  sql: ${JSON.stringify({ dialect: "clickhouse", profiles: { admin: { url, databases: [DB], access: true } } }, null, 2)},
+} satisfies ChantConfig;
+`;
+
+/** The `--plan <digest>` the stopped run printed in its approve command. */
+function approvedPlan(run: Run): string {
+  const m = /chant approve \S+ \S+ .*?--plan (jcs1-sha256:[0-9a-f]{64})/.exec(run.output);
+  if (!m) throw new Error(`the run printed no approve command with a plan:\n${run.output}`);
+  return m[1];
+}
+
+function gateOf(run: Run): string {
+  const m = /chant approve \S+ (\S+)/.exec(run.output);
+  if (!m) throw new Error(`the run printed no approve command:\n${run.output}`);
+  return m[1];
+}
+
+describe.skipIf(!enabled)("a gated ApplyOp over ClickHouse refuses after a privilege granted by hand (#3733)", () => {
+  let server: ScratchServer | undefined;
+  let admin: ClickHouseEndpoint;
+  let dir: string | undefined;
+  const q = <T = Record<string, unknown>>(sql: string) => clickhouseQuery<T>(admin, sql);
+  const cleanup = async () => {
+    await q(`DROP ROLE IF EXISTS ${READER}`);
+    await q(`DROP DATABASE IF EXISTS ${DB} SYNC`);
+  };
+
+  const chant = async (...args: string[]): Promise<Run> => {
+    try {
+      const r = await exec(join(BIN, "chant"), args, {
+        cwd: dir,
+        env: { ...process.env, PATH: `${BIN}:${process.env.PATH ?? ""}` },
+        maxBuffer: 16 * 1024 * 1024,
+      });
+      return { code: 0, output: strip(`${r.stdout}${r.stderr}`) };
+    } catch (err) {
+      const e = err as { code?: number; stdout?: string; stderr?: string };
+      return { code: typeof e.code === "number" ? e.code : 1, output: strip(`${e.stdout ?? ""}${e.stderr ?? ""}`) };
+    }
+  };
+
+  /** What `SHOW GRANTS FOR` the reader prints, one grant per line. */
+  const readerGrants = async () => (await q<Record<string, string>>(`SHOW GRANTS FOR ${READER}`)).map((r) => Object.values(r)[0]!);
+
+  beforeAll(async () => {
+    if (given) admin = { url: given };
+    else {
+      server = await startScratchServer(clickhouseImage(), { namePrefix: "chant-sql-gate-access" });
+      admin = server.endpoint;
+    }
+    await cleanup();
+    dir = mkdtempSync(join(tmpdir(), "chant-sql-gate-access-ch-"));
+    symlinkSync(join(REPO, "node_modules"), join(dir, "node_modules"), "dir");
+    const files: Record<string, string> = {
+      "package.json": JSON.stringify({ name: "sql-gate-access-ch-e2e", private: true, type: "module", scripts: { build: "chant build src --lexicon sql -o dist/schema.json" } }),
+      ".gitignore": "node_modules\ndist\n.chant\n",
+      "chant.config.ts": config(admin.url),
+      "ops/apply.op.ts": OPS,
+      "src/schema.ts": SCHEMA,
+    };
+    for (const [path, text] of Object.entries(files)) {
+      mkdirSync(join(dir, path, ".."), { recursive: true });
+      writeFileSync(join(dir, path), text);
+    }
+    const git = (...args: string[]) => exec("git", ["-c", "user.email=e2e@chant.invalid", "-c", "user.name=e2e", ...args], { cwd: dir });
+    await git("init", "-q");
+    await git("add", "-A");
+    await git("commit", "-qm", "the schema");
+  }, 600_000);
+
+  afterAll(async () => {
+    if (admin) await cleanup().catch(() => undefined);
+    await server?.stop();
+    if (dir) rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("approve, grant by hand, rerun: the gate refuses and the hand grant stays", async () => {
+    // The first run creates everything once its plan is approved.
+    const created = await chant("run", OP);
+    const approveCreate = await chant("approve", OP, gateOf(created), "--plan", approvedPlan(created));
+    expect(approveCreate.code, approveCreate.output).toBe(0);
+    const applied = await chant("run", OP);
+    expect(applied.output).toMatch(/Op "schema-apply" completed/);
+    expect(await readerGrants()).toEqual([`GRANT SELECT ON ${DB}.events TO ${READER}`]);
+
+    // Nothing to change: the run stops at the gate, and its plan is approved.
+    const first = await chant("run", OP);
+    expect(first.output).not.toContain("PENDING (");
+    const gate = gateOf(first);
+    const digest = approvedPlan(first);
+    const approve = await chant("approve", OP, gate, "--plan", digest);
+    expect(approve.code, approve.output).toBe(0);
+
+    await q(`GRANT INSERT ON ${DB}.events TO ${READER}`);
+
+    const second = await chant("run", OP);
+    expect(second.output).toContain(`Gate "${gate}" is approved, but not for this plan.`);
+    expect(second.output).toContain(`approved: ${digest}`);
+    expect(second.output).toMatch(
+      /PENDING \(changes an apply would make that no declared property shows\):\s+~ grants chant_e2e_3733_reader: REVOKE INSERT ON `chant_e2e_3733`\.`events` FROM `chant_e2e_3733_reader` \[from: readEvents\]/,
+    );
+    expect(second.output).not.toMatch(/Op "schema-apply" completed/);
+    expect((await readerGrants()).join("\n")).toMatch(/GRANT INSERT, SELECT ON chant_e2e_3733\.events TO chant_e2e_3733_reader|GRANT SELECT, INSERT ON chant_e2e_3733\.events/);
+
+    // Approving the plan the second run produced applies the revoke.
+    const fresh = approvedPlan(second);
+    expect(fresh).not.toBe(digest);
+    const reapprove = await chant("approve", OP, gate, "--plan", fresh);
+    expect(reapprove.code, reapprove.output).toBe(0);
+    const third = await chant("run", OP);
+    expect(third.output).toMatch(/Op "schema-apply" completed/);
+    expect(await readerGrants()).toEqual([`GRANT SELECT ON ${DB}.events TO ${READER}`]);
+  }, 600_000);
+});

package/src/op/apply-gate-access.e2e.test.ts

@@ -0,0 +1,207 @@
+/**
+ * An approval does not cover a privilege granted by hand after it (#3706),
+ * end to end on Postgres with a profile that manages access.
+ *
+ * A project in a temporary directory declares a schema, a table and a grant
+ * of SELECT on it to a reader role, and a gated `ApplyOp`. The first approved
+ * run creates them. The next run stops at the gate; the test approves its
+ * plan, grants INSERT on the table to another role by hand, and runs again.
+ * The gate refuses with "is approved, but not for this plan", the hand grant
+ * is still there, and the plan the run printed lists the REVOKE an apply
+ * would make. Approving that plan applies it.
+ *
+ * Before #3706 the plan digest was taken over a diff that left privileges
+ * out (a grant was unobserved there), so the third run revoked the hand
+ * grant under the earlier approval.
+ *
+ * Everything is written to the schema `chant_e2e_3706` and the roles
+ * `chant_e2e_3706_reader` and `chant_e2e_3706_writer`, all dropped afterwards.
+ *
+ * The server: `CHANT_SQL_GATE_POSTGRES_URL` (a `postgres://user@host:port/db`
+ * URL, with `CHANT_SQL_GATE_POSTGRES_PASSWORD`) names a running one, such as
+ * the one `chant emulator up --lexicon sql` starts. Without it, a throwaway
+ * server at the pin, skipped cleanly when Docker is not available.
+ */
+
+import { execFile } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { dockerAvailable, startTestPostgres, type TestPostgres } from "../postgres/testing/server";
+import { connectPostgres, type PostgresClient, type PostgresEndpoint } from "../postgres/live/client";
+
+const exec = promisify(execFile);
+
+const REPO = join(import.meta.dirname, "../../../..");
+const BIN = join(REPO, "node_modules/.bin");
+const S = "chant_e2e_3706";
+const READER = "chant_e2e_3706_reader";
+const WRITER = "chant_e2e_3706_writer";
+const OP = "schema-apply";
+
+const given = process.env.CHANT_SQL_GATE_POSTGRES_URL;
+const enabled = given ? true : await dockerAvailable();
+
+interface Run {
+  code: number;
+  output: string;
+}
+
+const strip = (s: string) => s.replace(/\u001b\[[0-9;]*m/g, "");
+
+const SCHEMA = `import { schema, table, grant } from "@intentius/chant-lexicon-sql/postgres";
+
+export const app = schema\`CREATE SCHEMA ${S}\`;
+
+export const orders = table\`
+  CREATE TABLE \${app}.orders (
+    id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+    total numeric NOT NULL
+  )\`;
+
+export const readOrders = grant\`GRANT SELECT ON TABLE \${orders} TO ${READER}\`;
+`;
+
+const OPS = `import { ApplyOp } from "@intentius/chant/op";
+const { op } = ApplyOp({ name: "${OP}", env: "admin", target: "postgres", gate: { gate: "approve-schema" } });
+export default op;
+`;
+
+const config = (url: string) => `import type { ChantConfig } from "@intentius/chant";
+import "@intentius/chant-lexicon-sql";
+
+export default {
+  lexicons: ["sql"],
+  ownership: { stack: "e2e-3706", env: "admin" },
+  sql: ${JSON.stringify({ dialect: "postgres", profiles: { admin: { url, password: { env: "ADMIN_PASSWORD" }, schemas: [S], access: true } } }, null, 2)},
+} satisfies ChantConfig;
+`;
+
+/** The `--plan <digest>` the stopped run printed in its approve command. */
+function approvedPlan(run: Run): string {
+  const m = /chant approve \S+ \S+ .*?--plan (jcs1-sha256:[0-9a-f]{64})/.exec(run.output);
+  if (!m) throw new Error(`the run printed no approve command with a plan:\n${run.output}`);
+  return m[1];
+}
+
+function gateOf(run: Run): string {
+  const m = /chant approve \S+ (\S+)/.exec(run.output);
+  if (!m) throw new Error(`the run printed no approve command:\n${run.output}`);
+  return m[1];
+}
+
+describe.skipIf(!enabled)("a gated ApplyOp over Postgres refuses after a privilege granted by hand (#3706)", () => {
+  let server: TestPostgres | undefined;
+  let endpoint: PostgresEndpoint;
+  let admin: PostgresClient;
+  let dir: string | undefined;
+  const cleanup = async () => {
+    await admin.query(`DROP SCHEMA IF EXISTS ${S} CASCADE`);
+    for (const r of [READER, WRITER]) await admin.query(`DROP ROLE IF EXISTS ${r}`);
+  };
+
+  const chant = async (...args: string[]): Promise<Run> => {
+    try {
+      const r = await exec(join(BIN, "chant"), args, {
+        cwd: dir,
+        env: { ...process.env, ADMIN_PASSWORD: endpoint.password ?? "", PATH: `${BIN}:${process.env.PATH ?? ""}` },
+        maxBuffer: 16 * 1024 * 1024,
+      });
+      return { code: 0, output: strip(`${r.stdout}${r.stderr}`) };
+    } catch (err) {
+      const e = err as { code?: number; stdout?: string; stderr?: string };
+      return { code: typeof e.code === "number" ? e.code : 1, output: strip(`${e.stdout ?? ""}${e.stderr ?? ""}`) };
+    }
+  };
+
+  /** Run the Op, approve the plan it stopped at, run again: the apply converges. */
+  const approveAndRun = async (): Promise<Run> => {
+    const stopped = await chant("run", OP);
+    const approve = await chant("approve", OP, gateOf(stopped), "--plan", approvedPlan(stopped));
+    expect(approve.code, approve.output).toBe(0);
+    const run = await chant("run", OP);
+    expect(run.output).toMatch(/Op "schema-apply" completed/);
+    return run;
+  };
+
+  const writerPrivileges = async () =>
+    (
+      await admin.query<{ p: string }>(
+        `SELECT privilege_type AS p FROM information_schema.role_table_grants WHERE table_schema = '${S}' AND table_name = 'orders' AND grantee = '${WRITER}'`,
+      )
+    ).map((r) => r.p);
+
+  beforeAll(async () => {
+    if (given) endpoint = { url: given, password: process.env.CHANT_SQL_GATE_POSTGRES_PASSWORD };
+    else {
+      server = await startTestPostgres();
+      endpoint = server.endpoint();
+    }
+    admin = await connectPostgres(endpoint);
+    await cleanup();
+    // The roles are the environment's: provisioned outside the declarations, only named in them.
+    for (const r of [READER, WRITER]) await admin.query(`CREATE ROLE ${r} NOLOGIN`);
+    dir = mkdtempSync(join(tmpdir(), "chant-sql-gate-access-"));
+    symlinkSync(join(REPO, "node_modules"), join(dir, "node_modules"), "dir");
+    const files: Record<string, string> = {
+      "package.json": JSON.stringify({ name: "sql-gate-access-e2e", private: true, type: "module", scripts: { build: "chant build src --lexicon sql -o dist/schema.json" } }),
+      ".gitignore": "node_modules\ndist\n.chant\n",
+      "chant.config.ts": config(endpoint.url),
+      "ops/apply.op.ts": OPS,
+      "src/schema.ts": SCHEMA,
+    };
+    for (const [path, text] of Object.entries(files)) {
+      mkdirSync(join(dir, path, ".."), { recursive: true });
+      writeFileSync(join(dir, path), text);
+    }
+    const git = (...args: string[]) => exec("git", ["-c", "user.email=e2e@chant.invalid", "-c", "user.name=e2e", ...args], { cwd: dir });
+    await git("init", "-q");
+    await git("add", "-A");
+    await git("commit", "-qm", "the schema");
+  }, 600_000);
+
+  afterAll(async () => {
+    if (admin) {
+      await cleanup().catch(() => undefined);
+      await admin.end();
+    }
+    await server?.stop();
+    if (dir) rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("approve, grant by hand, rerun: the gate refuses and the hand grant stays", async () => {
+    await approveAndRun();
+    const readers = await admin.query<{ p: string }>(
+      `SELECT privilege_type AS p FROM information_schema.role_table_grants WHERE table_schema = '${S}' AND table_name = 'orders' AND grantee = '${READER}'`,
+    );
+    expect(readers.map((r) => r.p)).toEqual(["SELECT"]);
+
+    // Nothing to change: the run stops at the gate, and its plan is approved.
+    const first = await chant("run", OP);
+    expect(first.output).not.toContain("PENDING (");
+    const gate = gateOf(first);
+    const digest = approvedPlan(first);
+    const approve = await chant("approve", OP, gate, "--plan", digest);
+    expect(approve.code, approve.output).toBe(0);
+
+    await admin.query(`GRANT INSERT ON ${S}.orders TO ${WRITER}`);
+
+    const second = await chant("run", OP);
+    expect(second.output).toContain(`Gate "${gate}" is approved, but not for this plan.`);
+    expect(second.output).toContain(`approved: ${digest}`);
+    expect(second.output).toMatch(/PENDING \(changes an apply would make that no declared property shows\):\s+~ relation chant_e2e_3706\.orders TO chant_e2e_3706_writer: REVOKE INSERT ON TABLE chant_e2e_3706\.orders FROM chant_e2e_3706_writer/);
+    expect(second.output).not.toMatch(/Op "schema-apply" completed/);
+    expect(await writerPrivileges()).toEqual(["INSERT"]);
+
+    // Approving the plan the second run produced applies the revoke.
+    const fresh = approvedPlan(second);
+    expect(fresh).not.toBe(digest);
+    const reapprove = await chant("approve", OP, gate, "--plan", fresh);
+    expect(reapprove.code, reapprove.output).toBe(0);
+    const third = await chant("run", OP);
+    expect(third.output).toMatch(/Op "schema-apply" completed/);
+    expect(await writerPrivileges()).toEqual([]);
+  }, 600_000);
+});

package/src/postgres/access/access.test.ts

@@ -6,7 +6,7 @@
 
 import { describe, expect, test } from "vitest";
 import { func, grant, policy, role, schema, table } from "../entities";
-import { diffObject, keyedByQualifiedName, pgSchemaFromLive, type PgSchemaObject } from "../plan/schema";
+import { diffObject, keyedByQualifiedName, pgSchemaFromBuildOutput, pgSchemaFromLive, type PgSchemaObject } from "../plan/schema";
 import { diffPgSchemas, matchPgObjects } from "../plan/diff";
 import { accessScoped } from "../plan/commands";
 import { alterSteps } from "../apply/statements";
@@ -21,6 +21,31 @@ const orders = table`
   ALTER TABLE ${app}.orders ENABLE ROW LEVEL SECURITY;
   ALTER TABLE ${app}.orders FORCE ROW LEVEL SECURITY`;
 
+describe("a grant on an interpolated routine (#3707)", () => {
+  const f = func`CREATE FUNCTION ${app}.total(n int, OUT t bigint) LANGUAGE sql AS 'select 1'`;
+  const buildOf = (objects: Array<{ export: string; entity: { entityType: string; props: unknown } }>) =>
+    JSON.stringify({
+      dialect: "postgres",
+      postgresMajor: 18,
+      objects: objects.map((o) => ({ export: o.export, type: o.entity.entityType, ddl: (o.entity.props as { ddl: string }).ddl })),
+    });
+
+  test("its statement names the routine with its parameter types", () => {
+    expect(grant`GRANT EXECUTE ON FUNCTION ${f} TO ${reader}`.props).toMatchObject({ ddl: "GRANT EXECUTE ON FUNCTION app.total(int) TO app_reader", objectNames: ["app.total(int)"] });
+    // Types written after the reference are kept, not doubled.
+    expect((grant`GRANT EXECUTE ON FUNCTION ${f}(int) TO ${reader}`.props as { ddl: string }).ddl).toBe("GRANT EXECUTE ON FUNCTION app.total(int) TO app_reader");
+  });
+
+  test("against a build from before the grant, it plans as one naming the signature does", () => {
+    const before = pgSchemaFromBuildOutput(buildOf([{ export: "app", entity: app }, { export: "total", entity: f }]));
+    const plan = (g: { entityType: string; props: unknown }) =>
+      diffPgSchemas(before, pgSchemaFromBuildOutput(buildOf([{ export: "app", entity: app }, { export: "total", entity: f }, { export: "run", entity: g }])), { major: 18 }).changes.map((c) => [c.object, c.rule, c.after]);
+    const interpolated = plan(grant`GRANT EXECUTE ON FUNCTION ${f} TO ${reader}`);
+    expect(interpolated).toEqual(plan(grant`GRANT EXECUTE ON FUNCTION app.total(int) TO app_reader`));
+    expect(interpolated.map(([, rule]) => rule)).toContain("SQLPG296");
+  });
+});
+
 describe("the tags", () => {
   test("a table's row-level security, a policy, a role", () => {
     expect(orders.props).toMatchObject({ rowSecurity: true, forceRowSecurity: true });

package/src/postgres/access/changes.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 type { PostgresClient } from "../live/client";
+import type { CanonicalPgObject } from "../plan/normalize";
+import { declaredAccess, diffAccess, predictedAccess, targetKey, type AccessChange } from "./acl";
+import { readLiveAccess } from "./live";
+
+/** The role a session runs as: the one whose own privileges owning an object gives, and whose default privileges apply. */
+async function currentRole(client: PostgresClient): Promise<{ self?: string }> {
+  const rows = await client.query<{ self: string }>("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: PostgresClient,
+  declared: ReadonlyArray<{ key: string; canonical: CanonicalPgObject }>,
+  options: { major: number; scope?: readonly string[] },
+): Promise<AccessChange[]> {
+  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);
+}

package/src/postgres/apply/apply.ts

@@ -70,7 +70,7 @@ import type { OwnershipMarker } from "@intentius/chant/ownership";
 import type { ApplyRef } from "@intentius/chant/apply";
 import { SqlApplyError, dependencyFailedDetail, missingDependencies, readBuildObjects, type SqlApplyOutcome } from "../../core/apply";
 import { carriesMarker, isChantManaged } from "../../core/ownership";
-import { PostgresQueryError, type PostgresClient } from "../live/client";
+import { DEFAULT_LOCK_TIMEOUT_MS, PostgresQueryError, withCatalogLockTimeout, type PostgresClient } from "../live/client";
 import type { PostgresTarget } from "../live/bind";
 import type { LivePgObject, readLiveSchema } from "../live/catalog";
 import { liveProps } from "../plan/deep";
@@ -98,7 +98,7 @@ export interface PostgresApplyTimeouts {
   scanTimeoutMs: number;
 }
 
-export const DEFAULT_POSTGRES_APPLY_TIMEOUTS: PostgresApplyTimeouts = { lockTimeoutMs: 5_000, statementTimeoutMs: 60_000, scanTimeoutMs: 0 };
+export const DEFAULT_POSTGRES_APPLY_TIMEOUTS: PostgresApplyTimeouts = { lockTimeoutMs: DEFAULT_LOCK_TIMEOUT_MS, statementTimeoutMs: 60_000, scanTimeoutMs: 0 };
 
 /** One statement as it ran: its object, the timeouts it ran with, and the transaction it was in. */
 export interface RanStatement {
@@ -254,8 +254,10 @@ export async function applyPostgres(
   };
 
   // ── Plan: the same diff `chant sql plan` shows. ──
+  // The catalog reads wait under lockTimeoutMs, as a plan's do (#3726): one blocked behind ACCESS EXCLUSIVE fails naming the holder instead of hanging.
+  const reader = await withCatalogLockTimeout(client, timeouts.lockTimeoutMs);
   const build: PgSchemaObject[] = declared.map((o) => ({ key: o.exportName, canonical: o.canonical }));
-  const plan = await planAgainstClient(client, target, build, {
+  const plan = await planAgainstClient(reader, target, build, {
     ...(opts.major !== undefined ? { major: opts.major } : {}),
     ...(opts.readLive ? { readLive: opts.readLive } : {}),
     ...(opts.serverNormalize ? { serverNormalize: opts.serverNormalize } : {}),
@@ -281,7 +283,7 @@ export async function applyPostgres(
   for (const m of matchPgObjects(plan.live, plan.declared)) if (m.kind === "matched") matchedLive.add(m.after.key);
 
   // An extension's own comment stays under the trailer when the declaration sets none.
-  const extensionComments = await extensionDefaults(client, objects.filter((o) => o.canonical.kind === "extension" && !matchedLive.has(o.key)).map((o) => o.canonical.name));
+  const extensionComments = await extensionDefaults(reader, objects.filter((o) => o.canonical.kind === "extension" && !matchedLive.has(o.key)).map((o) => o.canonical.name));
 
   // ── Each object's statements, or its verdict when it has none to send. ──
   const statements = planPgStatements({
@@ -454,7 +456,7 @@ export async function applyPostgres(
   }
   await commit();
 
-  if (managed) await applyAccess(client, declared, onServer, exportNames, { ...opts, major: plan.major ?? opts.major ?? POSTGRES_LATEST_MAJOR, ...(plan.scope ? { schemas: plan.scope } : {}) }, timeouts, outcome, log);
+  if (managed) await applyAccess(client, reader, declared, onServer, exportNames, { ...opts, major: plan.major ?? opts.major ?? POSTGRES_LATEST_MAJOR, ...(plan.scope ? { schemas: plan.scope } : {}) }, timeouts, outcome, log);
 
   if (opts.prune) await prune(client, statements.drops, liveRawByKey, opts, timeouts, outcome, log);
   if (outcome.failed.length > 0) throw new PostgresApplyError(outcome);
@@ -470,6 +472,7 @@ export async function applyPostgres(
  */
 async function applyAccess(
   client: PostgresClient,
+  reader: PostgresClient,
   declared: readonly DeclaredPgObject[],
   onServer: ReadonlySet<string>,
   exportNames: ReadonlySet<string>,
@@ -487,12 +490,12 @@ async function applyAccess(
     else ready.push(o);
   }
   const skipped = new Set(decls.filter((o) => !ready.includes(o)).map((o) => o.exportName));
-  const [me] = await client.query<{ self: string }>("SELECT current_user AS self");
+  const [me] = await reader.query<{ self: string }>("SELECT current_user AS self");
   const want = declaredAccess(
     declared.filter((o) => !skipped.has(o.exportName)).map((o) => ({ key: o.exportName, canonical: o.canonical })),
     { major: opts.major, ...(me?.self ? { self: me.self } : {}) },
   );
-  const have = await readLiveAccess(client, want.targets, {
+  const have = await readLiveAccess(reader, want.targets, {
     ...(opts.schemas ? { schemas: opts.schemas } : {}),
     forRoles: want.forRoles,
     declaredDefaults: want.targets.filter((t) => t.kind === "default"),

package/src/postgres/entities.ts

@@ -1048,7 +1048,7 @@ function grantProps(ctx: Ctx, node: GrantNode, ddl: string, source: { strings: s
       if (o.args) sqlName += `(${req(text(ctx, o.args, "objects")) ?? ""})`;
       else if (typeof t !== "string" && (t.entityType === POSTGRES_ENTITY_TYPES.function || t.entityType === POSTGRES_ENTITY_TYPES.procedure)) {
         // An interpolated routine is named by its own parameter types.
-        sqlName += `(${(t.props as RoutineProps).args.filter((a) => a.mode !== "out").map((a) => a.type).join(", ")})`;
+        sqlName += `(${routineArgTypes(t.props as RoutineProps)})`;
       } else throw new SqlTemplateError("grant", `${sqlName}: name the parameter types (${sqlName}(...)), or interpolate the routine, since overloads share a name`, 0, 0);
     }
     objectNames.push(sqlName);
@@ -1071,6 +1071,22 @@ function grantProps(ctx: Ctx, node: GrantNode, ddl: string, source: { strings: s
   }) as GrantProps;
 }
 
+/** A routine's parameter types, as `GRANT ... ON FUNCTION f(...)` names it: the `OUT` ones left out. */
+const routineArgTypes = (props: RoutineProps): string => props.args.filter((a) => a.mode !== "out").map((a) => a.type).join(", ");
+
+/** The interpolated functions and procedures not followed by their own `(...)`: the ones a grant's statement writes with the parameter types (#3707). */
+function bareRoutineSplices(tokens: readonly Token[], values: readonly unknown[]): Set<number> {
+  const out = new Set<number>();
+  tokens.forEach((t, k) => {
+    if (t.kind !== "ref") return;
+    const v = values[t.part];
+    if (!isPostgresObject(v) || (v.entityType !== POSTGRES_ENTITY_TYPES.function && v.entityType !== POSTGRES_ENTITY_TYPES.procedure)) return;
+    const next = tokens.slice(k + 1).find((x) => !isTrivia(x));
+    if (!(next?.kind === "punct" && next.text === "(")) out.add(t.part);
+  });
+  return out;
+}
+
 function build(tag: PostgresTag, strings: TemplateStringsArray | readonly string[], rawValues: readonly unknown[]): PostgresObject {
   const rawParts = templateParts(strings);
   const routine = tag === "func" || tag === "procedure";
@@ -1113,9 +1129,12 @@ function build(tag: PostgresTag, strings: TemplateStringsArray | readonly string
   const rowSecurity = rest.filter((n): n is RowSecurityNode => n.statement === "rowSecurity");
 
   const positions = regclassPositions(tokens, values);
+  const bareRoutines = tag === "grant" ? bareRoutineSplices(tokens, values) : new Set<number>();
   const render = (v: unknown, i?: number): string => {
     const at = i === undefined ? undefined : positions.get(i);
     if (at && isPostgresObject(v)) return at === "call" ? `${regclassText(v.sqlName)}::regclass` : regclassText(v.sqlName);
+    // #3707: a routine a grant interpolates is written with its parameter types, so the statement names it on its own.
+    if (i !== undefined && bareRoutines.has(i) && isPostgresObject(v)) return `${renderReference(v)}(${routineArgTypes(v.props as RoutineProps)})`;
     return renderReference(v);
   };
   const ctx: Ctx = { d: { ...POSTGRES_TEMPLATES, renderReference: render }, tokens, values, fed: values.map(() => new Set<string>()) };

package/src/postgres/live/bind.ts

@@ -6,7 +6,7 @@
 
 import type { ChantConfig } from "@intentius/chant/config";
 import type { UnobservedReason } from "@intentius/chant/observation";
-import { connectPostgres, PostgresQueryError, type PostgresClient, type PostgresEndpoint } from "./client";
+import { connectPostgres, DEFAULT_LOCK_TIMEOUT_MS, PostgresQueryError, withCatalogLockTimeout, type PostgresClient, type PostgresEndpoint } from "./client";
 import type { PostgresProvider } from "../providers/types";
 import { credentialSource, TokenSourceError } from "../../token-source";
 
@@ -139,11 +139,23 @@ export async function resolveBoundTarget(options: BindOptions = {}): Promise<Pos
   return target;
 }
 
-/** Resolve the environment's server and connect to it. The caller ends the client. */
+/**
+ * Resolve the environment's server and connect to it. The caller ends the client.
+ *
+ * The session reads under the profile's `lockTimeoutMs` (the applier's 5000 ms
+ * otherwise): a catalog read blocked behind ACCESS EXCLUSIVE fails with the
+ * relation and the pid that holds it, instead of waiting for as long as the
+ * lock is held.
+ */
 export async function bindPostgres(options: BindOptions = {}): Promise<{ target: PostgresTarget; client: PostgresClient }> {
   const target = await resolveBoundTarget(options);
-  const client = await (options.connect ?? connectPostgres)(target.endpoint);
-  return { target, client };
+  const raw = await (options.connect ?? connectPostgres)(target.endpoint);
+  try {
+    return { target, client: await withCatalogLockTimeout(raw, target.timeouts?.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS) };
+  } catch (err) {
+    await raw.end();
+    throw err;
+  }
 }
 
 /** SQLSTATEs that mean the server refused who we are: invalid_authorization_specification, invalid_password, insufficient_privilege. */

package/src/postgres/live/catalog.ts

@@ -44,26 +44,14 @@ import { quoteIdent } from "../keywords";
 import { hasChantTrailerKey, RECEIPTS_TRAILER_KEY, stripMarker } from "../../core/ownership";
 import { MIGRATION_TRAILER_KEY } from "../migrate/names";
 import { isProviderOwned, providerData } from "../providers";
+import { FOREIGN_TABLES } from "../../core/foreign-tables";
 import type { PostgresProvider } from "../providers/types";
 
 /** The server's own schemas, never part of a declared schema. */
 export const SYSTEM_SCHEMAS = ["pg_catalog", "information_schema", "pg_toast"];
 
-/** Tables another tool keeps its migration history in, by name, with the tool. */
-export const FOREIGN_TABLES: Readonly<Record<string, string>> = {
-  _prisma_migrations: "Prisma Migrate",
-  schema_migrations: "a migration runner (Rails, golang-migrate, dbmate)",
-  ar_internal_metadata: "Rails",
-  django_migrations: "Django",
-  alembic_version: "Alembic",
-  __drizzle_migrations: "drizzle-kit",
-  flyway_schema_history: "Flyway",
-  goose_db_version: "goose",
-  knex_migrations: "Knex",
-  knex_migrations_lock: "Knex",
-  SequelizeMeta: "Sequelize",
-  pgmigrations: "node-pg-migrate",
-};
+/** Tables another tool keeps its migration history in, by name, with the tool; both dialects share the list. */
+export { FOREIGN_TABLES };
 
 export interface LivePgObject {
   type: PostgresEntityType;