@intentius/chant-lexicon-sql 0.121.1 → 0.123.0

package/src/clickhouse/overlays/codecs.ts

@@ -29,6 +29,7 @@ const WIDTH: ArgumentOverlay & { name: string } = {
   name: "bytes",
   kind: "number",
   optional: true,
+  values: ["1", "2", "4", "8"],
   note: "1, 2, 4 or 8; the column type's width when omitted.",
 };
 
@@ -40,7 +41,10 @@ export const CODEC_OVERLAY: Record<string, CodecOverlay> = {
     role: "compression",
   },
   ZSTD: {
-    parameters: [{ name: "level", kind: "number", optional: true, range: [1, 22], note: "1 when omitted." }],
+    parameters: [
+      { name: "level", kind: "number", optional: true, range: [1, 22], note: "1 when omitted." },
+      { name: "window_log", kind: "number", optional: true, range: [10, 31], note: "Turns on long-range matching with this window log." },
+    ],
     role: "compression",
   },
   Delta: { parameters: [WIDTH], role: "preprocessing" },
@@ -54,7 +58,7 @@ export const CODEC_OVERLAY: Record<string, CodecOverlay> = {
   FPC: {
     parameters: [
       { name: "level", kind: "number", optional: true, range: [1, 28], note: "12 when omitted." },
-      { name: "float_size", kind: "number", optional: true, note: "4 or 8; the column type's width when omitted." },
+      { name: "float_size", kind: "number", optional: true, values: ["4", "8"], note: "4 or 8; the column type's width when omitted." },
     ],
     role: "compression",
   },

package/src/clickhouse/overlays/kinds.ts

@@ -29,7 +29,7 @@ export interface ArgumentOverlay {
   kind: ArgumentKind;
   /** Overrides the syntax line's optionality, with `note` saying why. */
   optional?: boolean;
-  /** The legal values of a `keyword`. */
+  /** The legal values of a `keyword`, or of a `number` limited to a set (a codec's byte width: 1, 2, 4 or 8). */
   values?: readonly string[];
   /** The inclusive range of a `number`. */
   range?: readonly [number, number];

package/src/clickhouse/overlays/types.ts

@@ -26,16 +26,33 @@ const P = (name: string, kind: TypeParameter["kind"], extra: Partial<TypeParamet
 
 const TZ = P("timezone", "string", { optional: true });
 
+/**
+ * The server takes and ignores a MySQL-style display width on an integer
+ * (`INT(11)`, `UInt64(8)`), a precision and scale on a float (`DOUBLE(10, 2)`)
+ * and a length on a string (`VARCHAR(255)`), so each is an optional parameter
+ * here rather than a mistake.
+ */
+const WIDTH = [P("display_width", "number", { optional: true })];
+const FLOAT = [P("precision", "number", { optional: true }), P("scale", "number", { optional: true })];
+const INTEGERS = ["Int8", "Int16", "Int32", "Int64", "Int128", "Int256", "UInt8", "UInt16", "UInt32", "UInt64", "UInt128", "UInt256"];
+
 export const TYPE_PARAMETERS: Record<string, readonly TypeParameter[]> = {
-  Decimal: [P("precision", "number", { range: [1, 76] }), P("scale", "number", { optional: true })],
+  ...Object.fromEntries(INTEGERS.map((name) => [name, WIDTH])),
+  Float32: FLOAT,
+  Float64: FLOAT,
+  BFloat16: FLOAT,
+  String: [P("length", "number", { optional: true })],
+  /** A bare `Decimal` is `Decimal(10, 0)`. */
+  Decimal: [P("precision", "number", { optional: true, range: [1, 76] }), P("scale", "number", { optional: true, range: [0, 76] })],
   Decimal32: [P("scale", "number", { range: [0, 9] })],
   Decimal64: [P("scale", "number", { range: [0, 18] })],
   Decimal128: [P("scale", "number", { range: [0, 38] })],
   Decimal256: [P("scale", "number", { range: [0, 76] })],
   DateTime: [TZ],
   DateTime32: [TZ],
-  DateTime64: [P("precision", "number", { range: [0, 9] }), TZ],
-  Time64: [P("precision", "number", { range: [0, 9] })],
+  /** A bare `DateTime64` has precision 3. */
+  DateTime64: [P("precision", "number", { optional: true, range: [0, 9] }), TZ],
+  Time64: [P("precision", "number", { optional: true, range: [0, 9] })],
   FixedString: [P("length", "number", { range: [1, Number.MAX_SAFE_INTEGER] })],
   Enum: [P("member", "enum-member", { repeated: true })],
   Enum8: [P("member", "enum-member", { repeated: true })],

package/src/clickhouse/plan/commands.ts

@@ -165,5 +165,10 @@ export const sqlCommands: CommandGroup = {
   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")).runTypes(ctx),
+    },
   ],
 };

package/src/clickhouse/row-types.ts

@@ -0,0 +1,158 @@
+/**
+ * What a ClickHouse column's value is in TypeScript, for `RowOf` (#3751): the
+ * value a row has in ClickHouse's JSON formats (`JSONEachRow`, what the HTTP
+ * clients read) with the server's default settings. 64-bit and wider
+ * integers are quoted (`output_format_json_quote_64bit_integers`), so they
+ * are strings; narrower integers, floats and decimals are numbers; dates,
+ * times, UUIDs and addresses are their text; a named tuple is an object
+ * (`output_format_json_named_tuples_as_objects`) and an unnamed one an array.
+ * `Nullable(T)` adds `| null` and `LowCardinality(T)` is `T`.
+ *
+ * The table names every type family of the pinned server's catalog
+ * (`TYPE_FAMILIES`, aliases resolved), and a test fails on one it does not,
+ * so a family a new release adds is a decision rather than a silent
+ * `unknown`.
+ */
+
+import type { ColumnTypeFamily } from "../generated/clickhouse-types";
+import { familyOf } from "../lint/post-synth/clickhouse-type-check";
+import { readType, typeTokens, type TypeParam } from "./type-syntax";
+import { isTrivia } from "./tokens";
+
+/** How a family's parameters make its row type: `inner` maps a parameter that is itself a type. */
+type Composed = (params: readonly TypeParam[], inner: (type: string) => string) => string;
+
+const NUMBER = "number";
+const STRING = "string";
+const UNKNOWN = "unknown";
+const POINT = "[number, number]";
+
+/** A union needs parentheses before `[]`. */
+const element = (ts: string): string => (/[|&]/.test(ts) && !/^\{.*\}$/s.test(ts) ? `(${ts})` : ts);
+
+/** An enum's labels as a union of string literals; its text when none read. */
+const enumLabels: Composed = (params) => {
+  const labels = params.flatMap((p) => {
+    const first = p.tokens.find((t) => !isTrivia(t));
+    return first?.kind === "string" ? [first.text.slice(1, -1).replace(/\\(.)/g, "$1").replace(/''/g, "'")] : [];
+  });
+  return labels.length > 0 ? labels.map((l) => JSON.stringify(l)).join(" | ") : STRING;
+};
+
+/** The TypeScript type of each type family's value, or how its parameters make it. */
+export const CLICKHOUSE_ROW_TYPES: Readonly<Record<ColumnTypeFamily, string | Composed>> = {
+  UInt8: NUMBER,
+  UInt16: NUMBER,
+  UInt32: NUMBER,
+  Int8: NUMBER,
+  Int16: NUMBER,
+  Int32: NUMBER,
+  Float32: NUMBER,
+  Float64: NUMBER,
+  BFloat16: NUMBER,
+  Decimal: NUMBER,
+  Decimal32: NUMBER,
+  Decimal64: NUMBER,
+  Decimal128: NUMBER,
+  Decimal256: NUMBER,
+  // Quoted in JSON, so text.
+  UInt64: STRING,
+  UInt128: STRING,
+  UInt256: STRING,
+  Int64: STRING,
+  Int128: STRING,
+  Int256: STRING,
+  IntervalNanosecond: STRING,
+  IntervalMicrosecond: STRING,
+  IntervalMillisecond: STRING,
+  IntervalSecond: STRING,
+  IntervalMinute: STRING,
+  IntervalHour: STRING,
+  IntervalDay: STRING,
+  IntervalWeek: STRING,
+  IntervalMonth: STRING,
+  IntervalQuarter: STRING,
+  IntervalYear: STRING,
+  Bool: "boolean",
+  String: STRING,
+  FixedString: STRING,
+  UUID: STRING,
+  IPv4: STRING,
+  IPv6: STRING,
+  Date: STRING,
+  Date32: STRING,
+  DateTime: STRING,
+  DateTime32: STRING,
+  DateTime64: STRING,
+  Time: STRING,
+  Time64: STRING,
+  Enum: enumLabels,
+  Enum8: enumLabels,
+  Enum16: enumLabels,
+  // Wrappers and containers.
+  Nullable: (p, inner) => `${inner(p[0]?.text ?? "")} | null`,
+  LowCardinality: (p, inner) => inner(p[0]?.text ?? ""),
+  Array: (p, inner) => `${element(inner(p[0]?.text ?? ""))}[]`,
+  Map: (p, inner) => `Record<string, ${inner(p[1]?.text ?? "")}>`,
+  Tuple: (p, inner) => {
+    const elements = p.map((x) => named(x));
+    if (elements.length > 0 && elements.every((e) => e.name !== undefined)) {
+      return `{ ${elements.map((e) => `${propertyName(e.name!)}: ${inner(e.type)}`).join("; ")} }`;
+    }
+    return `[${elements.map((e) => inner(e.type)).join(", ")}]`;
+  },
+  SimpleAggregateFunction: (p, inner) => inner(p[1]?.text ?? ""),
+  AggregateFunction: UNKNOWN,
+  Nested: UNKNOWN,
+  // Self-describing: the application's own shape.
+  JSON: UNKNOWN,
+  Dynamic: UNKNOWN,
+  Variant: UNKNOWN,
+  QBit: UNKNOWN,
+  Nothing: "null",
+  // Geometry, as the JSON formats write it: points as pairs, nested in arrays.
+  Point: POINT,
+  Ring: `${POINT}[]`,
+  LineString: `${POINT}[]`,
+  Polygon: `${POINT}[][]`,
+  MultiLineString: `${POINT}[][]`,
+  MultiPoint: `${POINT}[]`,
+  MultiPolygon: `${POINT}[][][]`,
+  Geometry: UNKNOWN,
+};
+
+/** A tuple element: `a String` is named `a`, `String` is not. */
+function named(param: TypeParam): { name?: string; type: string } {
+  const syn = readType(param.tokens);
+  if (!syn || syn.words.length < 2) return { type: param.text };
+  if (familyOf(syn.words.map((w) => w.text).join(" "))) return { type: param.text };
+  const first = syn.words[0]!;
+  const rest = param.text.slice(param.text.indexOf(first.text) + first.text.length).trim();
+  return { name: first.kind === "qident" ? first.text.slice(1, -1) : first.text, type: rest };
+}
+
+const propertyName = (name: string): string => (/^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name));
+
+/** A type's row type, wrappers and all; `unknown` for a type this cannot read. */
+export function clickhouseTsType(type: string): string {
+  const tokens = typeTokens(type);
+  const syn = tokens && readType(tokens);
+  if (!syn) return UNKNOWN;
+  const spec = familyOf(syn.words.map((w) => w.text).join(" "));
+  const entry = spec ? (CLICKHOUSE_ROW_TYPES as Readonly<Record<string, string | Composed | undefined>>)[spec.canonical] : undefined;
+  if (entry === undefined) return UNKNOWN;
+  return typeof entry === "string" ? entry : entry(syn.params ?? [], clickhouseTsType);
+}
+
+/** A column's row type and whether it can be NULL: `Nullable(...)` at the top, under any `LowCardinality(...)`. */
+export function clickhouseRowType(type: string): { ts: string; nullable: boolean } {
+  let t = type.trim();
+  let nullable = false;
+  for (;;) {
+    const m = /^(Nullable|LowCardinality)\s*\(([\s\S]*)\)$/i.exec(t);
+    if (!m) break;
+    if (m[1]!.toLowerCase() === "nullable") nullable = true;
+    t = m[2]!.trim();
+  }
+  return { ts: clickhouseTsType(t), nullable };
+}

package/src/clickhouse/type-syntax.ts

@@ -0,0 +1,82 @@
+/**
+ * A column type, read into its family and parameters: `Nullable(String)` is
+ * the family `Nullable` with the one parameter `String`;
+ * `DateTime64(3, 'UTC')` is `DateTime64` with `3` and `'UTC'`.
+ *
+ * The reading is lexical, over the same tokenizer the parser uses, so a
+ * string literal holding a parenthesis (`Enum8('a(' = 1)`) or a comma does not
+ * split a parameter. What a parameter means (a type, a number, a name) is the
+ * caller's question, answered from `TYPE_PARAMETERS`.
+ */
+
+import { isTrivia, tokenizeText, type Token } from "./tokens";
+
+export interface TypeParam {
+  /** The parameter as written, trimmed. */
+  text: string;
+  tokens: Token[];
+}
+
+export interface TypeSyntax {
+  /** The words before the parameters: `UInt64`, `BIGINT UNSIGNED`, or `a String` for a named tuple element. */
+  words: Token[];
+  /** The parameters, or undefined when the type has no parentheses. */
+  params?: TypeParam[];
+}
+
+const textOf = (tokens: readonly Token[]): string => tokens.map((t) => t.text).join("").trim();
+
+/** The significant tokens of a type, or undefined when it does not tokenize. */
+export function typeTokens(text: string): Token[] | undefined {
+  try {
+    return tokenizeText(text, 0);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Read a type into its leading words and its parameters. Undefined when the
+ * text is not a type this can read: no leading name, or unbalanced parentheses.
+ * Anything after the closing parenthesis (`COLLATE utf8`) is ignored.
+ */
+export function readType(tokens: readonly Token[]): TypeSyntax | undefined {
+  const sig = tokens.filter((t) => !isTrivia(t));
+  const words: Token[] = [];
+  let i = 0;
+  // `String COLLATE utf8`: COLLATE ends the type's words.
+  while (i < sig.length && (sig[i]!.kind === "ident" || sig[i]!.kind === "qident") && sig[i]!.text.toUpperCase() !== "COLLATE") words.push(sig[i++]!);
+  if (words.length === 0) return undefined;
+  if (i >= sig.length || !(sig[i]!.kind === "punct" && sig[i]!.text === "(")) return { words };
+  // Parameters: the tokens up to the matching parenthesis, split at top-level commas.
+  const start = tokens.indexOf(sig[i]!);
+  const params: TypeParam[] = [];
+  let depth = 0;
+  let current: Token[] = [];
+  for (let j = start; j < tokens.length; j++) {
+    const t = tokens[j]!;
+    if (t.kind === "punct" && t.text === "(") {
+      if (depth++ === 0) continue;
+    } else if (t.kind === "punct" && t.text === ")") {
+      if (--depth === 0) {
+        if (params.length > 0 || current.some((x) => !isTrivia(x))) params.push({ text: textOf(current), tokens: current });
+        return { words, params };
+      }
+    } else if (depth === 1 && t.kind === "punct" && t.text === ",") {
+      params.push({ text: textOf(current), tokens: current });
+      current = [];
+      continue;
+    }
+    current.push(t);
+  }
+  return undefined;
+}
+
+/** A parameter that is a numeric literal, possibly negative: its value. */
+export function numericParam(param: TypeParam): number | undefined {
+  const sig = param.tokens.filter((t) => !isTrivia(t));
+  const negative = sig.length === 2 && sig[0]!.kind === "op" && sig[0]!.text === "-";
+  const n = negative ? sig[1] : sig.length === 1 ? sig[0] : undefined;
+  if (!n || n.kind !== "number" || !/^\d+(\.\d+)?([eE][+-]?\d+)?$/.test(n.text)) return undefined;
+  return negative ? -Number(n.text) : Number(n.text);
+}

package/src/clickhouse.ts

@@ -50,6 +50,16 @@ export {
   type LineageEdge,
   type TableProps,
   type ViewProps,
+  type SqlSchema,
+  type RowOf,
+  type Column,
+  type ColumnTraits,
+  type AnyColumn,
+  type UncheckedColumn,
+  type KeyColumn,
+  type NotNullColumn,
+  type Named,
+  type Unnamed,
 } from "./clickhouse/entities";
 export * from "./generated/clickhouse";
 export * from "./composites/clickhouse";

package/src/codegen/clickhouse-module.ts

@@ -219,7 +219,7 @@ export function renderClickHouseModule(catalog: ClickHouseCatalog): RenderedModu
 
   const tables = [
     ...header("The tables lint and the LSP read, typed by ./clickhouse-types."),
-    `import type { CodecSpec, DatabaseEngineSpec, SettingSpec, SkipIndexSpec, TableEngineSpec, TypeFamilySpec } from "../clickhouse/catalog-types";`,
+    `import type { CodecSpec, DatabaseEngineSpec, FunctionSpec, SettingSpec, SkipIndexSpec, TableEngineSpec, TypeFamilySpec } from "../clickhouse/catalog-types";`,
     `import type { CodecName, ColumnTypeName, DatabaseEngineName, MergeTreeSettings, QuerySettings, SkipIndexType, TableEngineName } from "./clickhouse-types";`,
     "",
     `export * from "./clickhouse-types";`,
@@ -255,6 +255,20 @@ export function renderClickHouseModule(catalog: ClickHouseCatalog): RenderedModu
     }),
     "};",
     "",
+    `/** Every function the server has (\`system.functions\`, origin System), aliases included. */`,
+    `export const FUNCTIONS: Readonly<Record<string, FunctionSpec>> = {`,
+    ...catalog.functions.map(
+      (f) =>
+        `  ${key(f.name)}: ${JSON.stringify({ aggregate: f.aggregate, caseInsensitive: f.caseInsensitive, ...(f.aliasOf ? { aliasOf: f.aliasOf } : {}) })},`,
+    ),
+    "};",
+    "",
+    `/** The aggregate function combinators (\`system.aggregate_function_combinators\`): the suffixes of \`countIf\`, \`sumState\`. */`,
+    `export const AGGREGATE_COMBINATORS: readonly string[] = ${JSON.stringify(catalog.aggregateCombinators.map((c) => c.name))};`,
+    "",
+    `/** The table functions (\`system.table_functions\`): \`numbers\`, \`remote\`, \`s3\`. */`,
+    `export const TABLE_FUNCTIONS: readonly string[] = ${JSON.stringify(catalog.tableFunctions)};`,
+    "",
     `export const SKIP_INDEX_TYPES: Readonly<Record<SkipIndexType, SkipIndexSpec>> = {`,
     ...indexLines,
     "};",

package/src/codegen/postgres-module.ts

@@ -410,6 +410,43 @@ export function renderPostgresModule(catalogs: readonly PostgresCatalog[]): Rend
     "};",
   ];
 
+  // Names lint checks a declaration against, each with the majors that have it
+  // (`true`: every supported major). Read straight off the catalogs, internal
+  // functions included: a column default may call `pg_current_xact_id()`.
+  const presence = (lists: ReadonlyArray<readonly string[]>): Map<string, number[]> => {
+    const out = new Map<string, number[]>();
+    lists.forEach((names, i) => {
+      for (const n of new Set(names)) out.set(n, [...(out.get(n) ?? []), majors[i]!]);
+    });
+    return out;
+  };
+  const majorsLiteral = (ms: readonly number[]): string => (ms.length === majors.length ? "true" : JSON.stringify(ms));
+  const presenceTable = (m: Map<string, number[]>, indent: string): string[] =>
+    sorted(m.keys()).map((n) => `${indent}${JSON.stringify(n)}: ${majorsLiteral(m.get(n)!)},`);
+  const functionTable = [
+    `/** Every function, aggregate and procedure name in \`pg_proc\`, to the majors that have it (\`true\`: all of them). */`,
+    `export const FUNCTIONS: Readonly<Record<string, true | readonly number[]>> = {`,
+    ...presenceTable(presence(catalogs.map((c) => c.functions.map((f) => f.name))), "  "),
+    "};",
+  ];
+  const methodTable = [
+    `/** The index access methods, to the majors that have each (\`true\`: all of them). */`,
+    `export const INDEX_ACCESS_METHODS: Readonly<Record<string, true | readonly number[]>> = {`,
+    ...presenceTable(presence(catalogs.map((c) => c.accessMethods.filter((a) => a.type === "i").map((a) => a.name))), "  "),
+    "};",
+  ];
+  const opclassAms = sorted(catalogs.flatMap((c) => c.opclasses.map((o) => o.am)));
+  const opclassTable = [
+    `/** The operator classes of each index access method, to the majors that have each (\`true\`: all of them). */`,
+    `export const OPERATOR_CLASSES: Readonly<Record<string, Readonly<Record<string, true | readonly number[]>>>> = {`,
+    ...opclassAms.flatMap((am) => [
+      `  ${key(am)}: {`,
+      ...presenceTable(presence(catalogs.map((c) => c.opclasses.filter((o) => o.am === am).map((o) => o.name))), "    "),
+      "  },",
+    ]),
+    "};",
+  ];
+
   const tables = [
     ...header("The tables lint and the LSP read, typed by ./postgres-types."),
     `import type { ColumnTypeSpec, SettingSpec, StorageParameterSpec } from "../postgres/catalog-types";`,
@@ -425,6 +462,12 @@ export function renderPostgresModule(catalogs: readonly PostgresCatalog[]): Rend
     "",
     ...keywordTable,
     "",
+    ...functionTable,
+    "",
+    ...methodTable,
+    "",
+    ...opclassTable,
+    "",
   ].join("\n");
 
   notes.push(

package/src/composites/composites.test.ts

@@ -202,7 +202,7 @@ test("a prop that is not valid SQL is refused at the interpolation that carried
 // ── What the lexicon's own checks say ──────────────────────────────────
 
 describe("the composites pass the lexicon's post-synth checks", () => {
-  test("SQLCH101-120 find nothing in any of them", () => {
+  test("SQL101 and SQLCH101-127 find nothing in any of them", () => {
     const source = events();
     const instances: Array<[string, CompositeInstance]> = [
       ["users", ReplacingTable({ name: "users", columns: "id UInt64, email String", orderBy: "id" })],
@@ -230,10 +230,11 @@ describe("the composites pass the lexicon's post-synth checks", () => {
     expect(doc.applyOrder.indexOf("hitsLocal")).toBeLessThan(doc.applyOrder.indexOf("hitsDistributed"));
 
     const ctx = makePostSynthCtx("sql", out.primary, entities);
-    const clickhouse = postSynthChecks.filter((c) => c.id.startsWith("SQLCH"));
+    const clickhouse = postSynthChecks.filter((c) => c.id.startsWith("SQLCH") || c.id === "SQL101");
     const ids = clickhouse.map((c) => c.id).sort();
-    expect(ids[0]).toBe("SQLCH101");
-    expect(ids.at(-1)).toBe("SQLCH120");
+    expect(ids[0]).toBe("SQL101");
+    expect(ids).toContain("SQLCH101");
+    expect(ids.at(-1)).toBe("SQLCH127");
     expect(clickhouse.flatMap((check) => check.check(ctx))).toEqual([]);
   });
 });
@@ -559,7 +560,7 @@ describe("the Postgres composites", () => {
     expect(() => TenantTable({ name: "notes", columns: "id bigint NOT NULL, (", primaryKey: "id", indexOn: "id" })).toThrow(SqlTemplateError);
   });
 
-  test("SQLPG101 to SQLPG118 find nothing in any of them", () => {
+  test("SQLPG101 to SQLPG126 find nothing in any of them", () => {
     const people = users();
     const teams = SoftDeleteTable({ name: "teams", schema: "app", columns: "id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY, name text NOT NULL" });
     const members = JoinTable({ name: "memberships", schema: "app", left: people.table, leftColumn: "user_id", right: teams.table, rightColumn: "team_id" });
@@ -588,7 +589,7 @@ describe("the Postgres composites", () => {
 
     const ctx = makePostSynthCtx("sql", out.primary, entities);
     const checks = postSynthChecks.filter((c) => c.id.startsWith("SQLPG"));
-    expect(checks).toHaveLength(18);
+    expect(checks).toHaveLength(26);
     expect(checks.flatMap((check) => check.check(ctx).map((d) => `${check.id} ${d.message}`))).toEqual([]);
   });
 });

package/src/core/index.ts

@@ -25,6 +25,9 @@
  *   (`classifier.ts`);
  * - normalization helpers that are not a database's grammar, such as the
  *   `-- previously:` hint (`normalize.ts`);
+ * - typed columns: the brands, `ColumnsIn`, `SlotsIn` and `RowIn` each
+ *   dialect's `SqlSchema` is read through, and the slot record a tag leaves
+ *   for `chant sql types` (`typed.ts`);
  * - the ownership trailer on an object's comment (`ownership.ts`);
  * - receipts kept on the server (`receipts.ts`);
  * - the applier's tri-state outcome, its envelope projection and the build
@@ -54,6 +57,7 @@ export * from "./references";
 export * from "./diff";
 export * from "./classifier";
 export * from "./normalize";
+export * from "./typed";
 export * from "./ownership";
 export * from "./receipts";
 export * from "./apply";

package/src/core/typed.ts

@@ -0,0 +1,143 @@
+/**
+ * Typed columns (#3751): the types that carry a relation's columns from the
+ * declarations `chant sql types` generates to `tsc`, in every dialect.
+ *
+ * Each dialect declares an empty `SqlSchema` interface keyed by qualified
+ * name, and the generated `sql-types.d.ts` augments it. A tag given the name
+ * as its type argument (`` table<"shop.orders">`CREATE TABLE ...` ``) returns
+ * a relation whose `columns` are that entry's, each a {@link Column} branded
+ * with its SQL type. The tag's interpolations are typed by the entry's
+ * `slots`: the generator writes, per `${}` position, the column a foreign key
+ * or a sort key there must be ({@link KeyColumn}, {@link NotNullColumn}).
+ *
+ * A relation with no type argument, or one the generated file does not list
+ * yet, keeps unchecked columns: any name type-checks and every slot takes
+ * them, so a project adopts the type argument one declaration at a time.
+ *
+ * The runtime half is the record of those slots: a tag notes which `${}`
+ * feeds a foreign key's column list or a sort key, off the serialized output
+ * as `setInterpolationFields` keeps its record, for the generator to read.
+ */
+
+import type { AttrRef } from "@intentius/chant/attrref";
+
+declare const columnBrand: unique symbol;
+declare const checkedBrand: unique symbol;
+declare const relationName: unique symbol;
+declare const unnamedBrand: unique symbol;
+
+/** What the generator knows about a column. */
+export interface ColumnTraits {
+  /** The row type `RowOf` gives the column, before `| null`. */
+  readonly ts: unknown;
+  readonly nullable: boolean;
+  /**
+   * How the column compares in a key. Postgres: the catalog category letter
+   * (`N`, `S`), or the type itself for the user-defined category, an enum or
+   * a row type; a domain compares as its base. ClickHouse: the type family.
+   */
+  readonly cmp: string;
+}
+
+/**
+ * A column reference branded with its SQL type, spelled as the catalog
+ * spells it. `Checked` is true for a column the generated declarations type,
+ * false for an unchecked one; it is a discriminant, so a slot's error names
+ * the checked member it wanted.
+ */
+export interface Column<SqlType extends string = string, T extends ColumnTraits = ColumnTraits, Checked extends boolean = true> extends AttrRef {
+  readonly [columnBrand]: { readonly sqlType: SqlType; readonly traits: T };
+  readonly [checkedBrand]: Checked;
+}
+
+/** A column of a relation the declarations do not cover: any name type-checks, and it fits every slot. */
+export type UncheckedColumn = Column<string, ColumnTraits, false>;
+
+/** Any column, checked or not: what a relation annotated without a name (`PostgresTable`) holds. */
+export type AnyColumn = Column<string, ColumnTraits, boolean>;
+
+/**
+ * What a slot takes besides its checked column: an unchecked relation's
+ * column, which reads as `| undefined` under `noUncheckedIndexedAccess`. A
+ * checked relation's columns are named properties, so nothing of theirs gets
+ * through here.
+ */
+type Unchecked = UncheckedColumn | undefined;
+
+/** A `${}` that must be a column comparing as `Cmp`: the referenced column of a foreign key. */
+export type KeyColumn<Cmp extends string> = Unchecked | Column<string, { readonly ts: unknown; readonly nullable: boolean; readonly cmp: Cmp }>;
+
+/** A `${}` that must be a column that cannot be NULL: an element of a ClickHouse sort key. */
+export type NotNullColumn = Unchecked | Column<string, { readonly ts: unknown; readonly nullable: false; readonly cmp: string }>;
+
+/**
+ * The name a relation's type carries when its tag has no type argument. Its
+ * columns are unchecked, and `RowOf` refuses it.
+ */
+export type Unnamed = string & { readonly [unnamedBrand]: true };
+
+/** Carries a relation's declared name on its type, so `RowOf<typeof t>` can find its entry. */
+export interface Named<N extends string> {
+  readonly [relationName]?: N;
+}
+
+/**
+ * The columns of relation `N` in `Registry` (a dialect's `SqlSchema`):
+ * unchecked for an {@link Unnamed} relation or a name the registry does not
+ * list, any column for the bare annotation (`N` is `string`), and the
+ * entry's own otherwise.
+ */
+export type ColumnsIn<Registry, N extends string> = [N] extends [Unnamed]
+  ? Readonly<Record<string, UncheckedColumn>>
+  : string extends N
+    ? Readonly<Record<string, AnyColumn>>
+    : N extends keyof Registry
+      ? Registry[N] extends { readonly columns: infer C } ? C : never
+      : Readonly<Record<string, UncheckedColumn>>;
+
+/** The interpolations a tag for relation `N` takes: the entry's slots, then anything. */
+export type SlotsIn<Registry, N extends string> = N extends keyof Registry
+  ? Registry[N] extends { readonly slots: infer S extends readonly unknown[] } ? [...S, ...unknown[]] : unknown[]
+  : unknown[];
+
+type RowFromColumns<C> = {
+  -readonly [K in keyof C]: C[K] extends Column<string, infer T> ? (T["nullable"] extends true ? T["ts"] | null : T["ts"]) : unknown;
+};
+
+/** A relation's row: `T` is its name or a relation's type carrying one. */
+export type RowIn<Registry, T> = T extends string
+  ? RowFromColumns<ColumnsIn<Registry, T>>
+  : T extends Named<infer N> ? RowFromColumns<ColumnsIn<Registry, N>> : never;
+
+// ── The slot record ─────────────────────────────────────────────────────
+
+/**
+ * One `${}` the generator types. `references`: a column in a foreign key's
+ * referenced column list, paired with `column`, the referencing table's own
+ * column at that position. `sortKey`: a bare element of a ClickHouse
+ * `ORDER BY` or `PRIMARY KEY`.
+ */
+export type TypedSlot = { readonly index: number; readonly kind: "references"; readonly column: string } | { readonly index: number; readonly kind: "sortKey" };
+
+const TYPED_SLOTS = Symbol.for("chant.sql.typedSlots");
+
+/** Record the typed slots on an entity: non-enumerable and symbol-keyed, so no serializer sees it. */
+export function setTypedSlots(entity: object, slots: readonly TypedSlot[]): void {
+  if (slots.length === 0 || !Object.isExtensible(entity)) return;
+  Object.defineProperty(entity, TYPED_SLOTS, { value: Object.freeze([...slots]), enumerable: false, writable: false, configurable: true });
+}
+
+/** What {@link setTypedSlots} recorded on an entity; empty when nothing was. */
+export function getTypedSlots(entity: object): readonly TypedSlot[] {
+  return ((entity as Record<symbol, unknown>)[TYPED_SLOTS] as readonly TypedSlot[] | undefined) ?? [];
+}
+
+/**
+ * A relation's key in `SqlSchema`: `schema.name` (Postgres) or
+ * `database.name` (ClickHouse), unquoted and with Postgres's folding
+ * applied, or the name alone when the DDL does not qualify it.
+ */
+export function relationKey(props: { readonly schema?: string; readonly database?: string; readonly name: string }): string {
+  const qualifier = props.schema ?? props.database;
+  return qualifier ? `${qualifier}.${props.name}` : props.name;
+}