okmodel 0.6.0 → 0.8.0

package/dist/dialects/pg/relations.d.ts

@@ -1,9 +1,9 @@
 /**
- * `one`, `many`, and `manyThrough` relations.
+ * `one`, `many`, `manyThrough`, and `morph` relations.
  *
  * They name a table. `schema()` resolves the foreign key. An ambiguous key
- * is OKM1021. `manyThrough` names the join table as well and carries its own
- * resolver, so a schema without one does not pay for it. `morph` stays reserved.
+ * is OKM1021. `manyThrough` and `morph` carry their own resolvers, so a schema
+ * that never calls one does not pay for it.
  */
 import type { RelationModel } from "./model.js";
 /** A to-one relation. `field` is the local foreign key when the table has several. */
@@ -28,6 +28,26 @@ export type RelationEdge = {
     /** Referenced SQL names, in the same order. */
     readonly remote: readonly string[];
 };
+/** A table as a morph resolver reads it. Foreign-key resolvers ignore this. */
+export type RelationDescribed = {
+    readonly tsName: string;
+    readonly sqlName: string;
+    /** Primary-key SQL names, in catalog order. */
+    readonly primary: readonly string[];
+    readonly byField: ReadonlyMap<string, {
+        readonly field: string;
+        readonly sqlName: string;
+        readonly dataType: string;
+        readonly nullable: boolean;
+    }>;
+    readonly bySql: ReadonlyMap<string, {
+        readonly field: string;
+        readonly sqlName: string;
+        readonly dataType: string;
+    }>;
+    /** Relation calls stored on the table, before they are resolved. */
+    readonly relationOptions: unknown;
+};
 /** What a relation's own resolver reads from `schema()`. */
 export type RelationScope = {
     /** The table that declares the relation. */
@@ -37,6 +57,19 @@ export type RelationScope = {
     readonly edges: readonly RelationEdge[];
     /** Every table name in the schema, sorted. */
     readonly tables: readonly string[];
+    /**
+     * Looks up a table's columns.
+     *
+     * Present when `schema()` resolves relations. A resolver that only needs
+     * foreign keys ignores it. The value is the prepared table; morph narrows it.
+     */
+    readonly describe?: (table: string) => unknown;
+    /**
+     * Tenant fields tenancy added to a primary key.
+     *
+     * A morph id matches the key that remains. Absent when the schema has no tenancy.
+     */
+    readonly scopeFields?: readonly string[];
 };
 /**
  * A to-many relation through a join table.
@@ -100,3 +133,67 @@ export declare function isRelationCall(value: unknown): value is RelationCall;
 export declare function manyThrough<const TTable extends string>(table: TTable, options: {
     readonly through: string;
 } & ThroughKeys): ManyThroughRelation<TTable>;
+/**
+ * A polymorphic to-one relation.
+ *
+ * `name` is the column stem: the table declares `${name}Type` and `${name}Id`.
+ * The type column stores a target table name. The id column stores that
+ * table's primary key. Include returns one row of the matching target, or
+ * null, as a flat union discriminated by the type field.
+ *
+ * @typeParam TName - Column stem
+ * @typeParam TTargets - Closed list of target tables
+ * @param name - Column stem
+ * @param targets - Target table names, each with one primary-key column
+ * @returns The relation `schema()` resolves
+ */
+export declare function morph<const TName extends string, const TTargets extends readonly [string, ...string[]]>(name: TName, targets: TTargets): MorphRelation<TName, TTargets>;
+/**
+ * The reverse of {@link morph}: many owner rows that point at this table.
+ *
+ * Declare it on each target. `table` is the table that holds the type and id
+ * columns, and `name` is the stem passed to `morph`.
+ *
+ * @typeParam TTable - Table that holds the type and id columns
+ * @param table - That table
+ * @param name - Column stem
+ * @returns The relation `schema()` resolves
+ */
+export declare function morphMany<const TTable extends string>(table: TTable, name: string): MorphManyRelation<TTable>;
+/**
+ * A polymorphic relation declared with {@link morph}.
+ *
+ * It is a {@link OneRelation} so the relation map stays assignable. `morph`
+ * is what include reads to build the union.
+ */
+export type MorphRelation<TName extends string = string, TTargets extends readonly string[] = readonly string[]> = OneRelation<TTargets[number]> & {
+    readonly morph: {
+        readonly name: TName;
+        readonly targets: TTargets;
+        readonly typeField: `${TName}Type`;
+    };
+    readonly resolve: (scope: RelationScope) => RelationModel;
+};
+/**
+ * The reverse many declared with {@link morphMany}.
+ *
+ * It is a {@link ManyRelation}, so include, `has`, `none`, and `every` read it as one.
+ */
+export type MorphManyRelation<TTable extends string = string> = ManyRelation<TTable> & {
+    readonly resolve: (scope: RelationScope) => RelationModel;
+};
+/**
+ * Sets a morph's type and id columns together.
+ *
+ * @typeParam TName - Column stem
+ * @typeParam TType - Target table name
+ * @param name - Column stem passed to `morph`
+ * @param type - Target table name
+ * @param id - That table's primary key
+ * @returns The two fields an insert or update spreads in
+ */
+export declare function morphTo<const TName extends string, const TType extends string>(name: TName, type: TType, id: string): {
+    readonly [K in `${TName}Type`]: TType;
+} & {
+    readonly [K in `${TName}Id`]: string;
+};

package/dist/dialects/pg/schema.d.ts

@@ -5,6 +5,7 @@
  */
 import type { Catalog } from "../../contracts/catalog/types.js";
 import { type ClientGenerator } from "../../contracts/generator.js";
+import { type PostgresMajor } from "./floor.js";
 import { type SchemaHook, type TableModel } from "./model.js";
 import type { FieldsOfList, HasArchive, PresetsOfList, Trait } from "./trait.js";
 import { type ColumnTenancy, type TenantFields } from "./tenancy.js";
@@ -15,8 +16,16 @@ export type SchemaCodecs = {
     readonly numeric: "string" | "number";
     readonly timestamps: "temporal";
 };
-/** Engine requirement recorded for connect. */
+/**
+ * Engine requirement recorded for connect.
+ *
+ * The stored value is `>=` and a major. `minPostgres` and the deprecated
+ * string form normalise to the same object.
+ */
 export type SchemaRequires = {
+    /**
+     * @deprecated Use `minPostgres`. `">=17"` is the same floor as `minPostgres: 17`.
+     */
     readonly postgres?: string;
 };
 /**
@@ -28,6 +37,15 @@ export type SchemaRequires = {
  */
 export type SchemaInput<TTables extends readonly AnyTable[]> = {
     readonly tables: TTables;
+    /**
+     * Oldest Postgres major this schema runs on.
+     *
+     * Omitted means 15. A feature that needs a newer major is refused here.
+     */
+    readonly minPostgres?: PostgresMajor;
+    /**
+     * @deprecated Use {@link SchemaInput.minPostgres}. `">=17"` is the same floor as `minPostgres: 17`.
+     */
     readonly requires?: SchemaRequires;
     readonly casing?: "snake";
     readonly codecs?: {
@@ -39,8 +57,13 @@ export type SchemaInput<TTables extends readonly AnyTable[]> = {
     /**
      * What a bare `t.id()` means.
      *
-     * `"uuidv7"` and `"uuidv4"` are database defaults. A client generator is
-     * filled on insert and stays out of the catalog. A column option wins.
+     * Omitted, the database default is `gen_random_uuid()`. `"uuidv4"` stores
+     * the same function. `"uuidv7"` stores `uuidv7()` and needs Postgres 18
+     * (`minPostgres: 18`).
+     * Pick `uuidv7` for a large write-heavy table: the ids are time-ordered
+     * and the index stays local. Random ids are fine elsewhere. A client
+     * generator is filled on insert and stays out of the catalog. A column
+     * option wins.
      */
     readonly defaults?: {
         readonly id?: "uuidv7" | "uuidv4" | ClientGenerator<string>;
@@ -80,6 +103,11 @@ export type BuiltSchema<TTables extends readonly AnyTable[]> = {
     readonly types: "emitted" | "inferred";
     readonly casing: "snake" | undefined;
     readonly codecs: SchemaCodecs;
+    /**
+     * Declared floor, normalised to `>=` and a major.
+     *
+     * Absent when the schema names no floor. Connect then uses 15.
+     */
     readonly requires: SchemaRequires | undefined;
     readonly tables: TTables;
     /**

package/dist/dialects/pg/view/client.d.ts

@@ -28,21 +28,29 @@ export declare function viewMentions(query: string, name: string): boolean;
 export type ViewInstall = (model: {
     [name: string]: TableModel;
 }, tenancy: ColumnTenancy | undefined, tables: readonly AnyTable[], casing: "snake" | undefined, scoped: Set<string>) => void;
+/** A value, or a function `install` calls once casing is known. */
+type ColumnSource = readonly {
+    readonly name: string;
+    readonly type: string;
+}[] | (() => readonly {
+    readonly name: string;
+    readonly type: string;
+}[]);
+/** A query string, or a function `install` calls once casing is known. */
+type QuerySource = string | (() => string);
 /**
  * Client name, read model, and the hook that moves the handle under `views`.
  *
  * @param name - SQL name of the view
- * @param columns - Declared output columns
- * @param query - Author SQL
+ * @param columns - Declared output columns, or a getter `install` calls
+ * @param query - Author SQL, or a getter `install` calls
  * @param tenancy - `global("reason")`, when the view opts out
  * @param refresh - `plain` stores no `refresh`. A materialized view is `blocking` or `concurrently`
  * @returns Methods stored on the declaration
  */
-export declare function viewClient(name: string, columns: readonly {
-    readonly name: string;
-    readonly type: string;
-}[], query: string, tenancy: unknown, refresh?: "plain" | "blocking" | "concurrently"): {
+export declare function viewClient(name: string, columns: ColumnSource, query: QuerySource, tenancy: unknown, refresh?: "plain" | "blocking" | "concurrently"): {
     readonly field: string;
     readonly install: ViewInstall;
     readonly hook: SchemaHook;
 };
+export {};

package/dist/dialects/pg/view/index.d.ts

@@ -8,7 +8,7 @@
  */
 import type { CatalogObject } from "../../../contracts/catalog/types.js";
 import type { SchemaHook } from "../model.js";
-import type { SqlText } from "../table.js";
+import { type AnyTable, type SqlText } from "../table.js";
 import { type ViewInstall } from "./client.js";
 /** One declared output column. `type` is the Postgres type name. */
 export type ViewColumnInput = {
@@ -29,6 +29,66 @@ export type ViewOptions = {
      */
     readonly tenancy?: unknown;
 };
+/** Output columns of {@link ViewFrom.from}. A tuple keeps each name. */
+type TupleColumns<K extends readonly string[]> = K extends readonly [] ? readonly [] : K extends readonly [infer H extends string, ...infer R extends readonly string[]] ? readonly [{
+    readonly name: H;
+    readonly type: string;
+}, ...TupleColumns<R>] : readonly {
+    readonly name: K[number];
+    readonly type: string;
+}[];
+/** Every column of a table, when `from` is not given a list. */
+type AllColumns<T extends AnyTable> = readonly {
+    readonly name: keyof T["columns"] & string;
+    readonly type: string;
+}[];
+/**
+ * The value `(q) => q.from(...)` returns.
+ *
+ * @typeParam C - Output columns, for `db.views`
+ */
+export type ViewBuilt<C extends readonly ViewColumnInput[] = readonly ViewColumnInput[]> = {
+    /** Declared columns. Present for the type. The catalog uses the SQL names. */
+    readonly "~columns"?: C;
+    /**
+     * Adds a WHERE clause.
+     *
+     * The text is stored as written, the same way `query` is.
+     *
+     * @param predicate - SQL after `where`
+     * @returns The same view, with the clause
+     */
+    where(predicate: SqlText | string): ViewBuilt<C>;
+    /**
+     * Opts the view out of tenancy.
+     *
+     * Pass `global("reason")` from `okmodel/tenancy`.
+     *
+     * @param mark - `global("reason")`
+     * @returns The same view, opted out
+     */
+    tenancy(mark: unknown): ViewBuilt<C>;
+};
+/**
+ * The argument of `view(name, (q) => q.from(...))`.
+ */
+export type ViewFrom = {
+    /**
+     * Selects every column of `table`.
+     *
+     * @param table - Source table
+     * @returns The view query
+     */
+    from<const T extends AnyTable>(table: T): ViewBuilt<AllColumns<T>>;
+    /**
+     * Selects `columns` from `table`, in that order.
+     *
+     * @param table - Source table
+     * @param columns - Output columns. Names are the table's fields
+     * @returns The view query
+     */
+    from<const T extends AnyTable, const K extends readonly (keyof T["columns"] & string)[]>(table: T, columns: K): ViewBuilt<TupleColumns<K>>;
+};
 /**
  * One declared view.
  *
@@ -117,6 +177,17 @@ export type MaterializedViewDeclaration<N extends string = string, C extends rea
 export declare function view<const N extends string, const C extends readonly ViewColumnInput[]>(name: N, options: ViewOptions & {
     readonly columns: C;
 }): ViewDeclaration<N, C>;
+/**
+ * Declares a view from a table.
+ *
+ * `view(name, (q) => q.from(table))` selects that table's columns. Pass a
+ * column list to project. `.where` adds a predicate. `.tenancy` opts out.
+ *
+ * @param name - View name
+ * @param build - `q.from(...)`
+ * @returns The definition object `schema({ views })` stores
+ */
+export declare function view<const N extends string, const C extends readonly ViewColumnInput[]>(name: N, build: (q: ViewFrom) => ViewBuilt<C>): ViewDeclaration<N, C>;
 /**
  * Declares a materialized view.
  *
@@ -130,3 +201,4 @@ export declare function view<const N extends string, const C extends readonly Vi
 export declare function materializedView<const N extends string, const C extends readonly ViewColumnInput[]>(name: N, options: MaterializedViewOptions & {
     readonly columns: C;
 }): MaterializedViewDeclaration<N, C>;
+export {};

package/dist/dialects/pg/view/index.js

@@ -1,11 +1,20 @@
-import {
-  viewClient
-} from "../../../shared/x3jc53kg.js";
 import {
   viewObject,
   materializedViewObject,
   materializedViewIndex
-} from "../../../shared/zy8r7qvz.js";
+} from "../../../shared/12z7aznj.js";
+import {
+  viewClient
+} from "../../../shared/760ppr76.js";
+import {
+  snakeCase
+} from "../../../shared/gcefca6p.js";
+import {
+  formatType
+} from "../../../shared/606g0nbf.js";
+import {
+  quoteIdent
+} from "../../../shared/sjk86yrx.js";
 import {
   staticNamespace2
 } from "../../../shared/358zsv4r.js";
@@ -14,7 +23,11 @@ import {
 } from "../../../shared/52szzakm.js";
 
 // src/dialects/pg/view/index.ts
-function view(name, options) {
+var BUILT = Symbol("okmodel.view.from");
+function view(name, source) {
+  if (typeof source === "function")
+    return viewFrom(name, source);
+  const options = source;
   const schema = options.schema ?? "public";
   const columns = options.columns.map((column) => ({ name: column.name, dataType: column.type }));
   const query = bodyText(options.query);
@@ -100,6 +113,144 @@ function materializedView(name, options) {
     }
   };
 }
+var viewFromApi = {
+  from(table, columns) {
+    return finish({
+      [BUILT]: true,
+      table,
+      picked: columns,
+      predicate: undefined,
+      mark: undefined
+    });
+  }
+};
+function viewFrom(name, build) {
+  const built = build(viewFromApi);
+  if (!isRecipe(built)) {
+    throw new OkmError2("OKM1121", `View ${name} must return q.from(...).`, {
+      fix: { summary: "Return q.from(table), and chain where() or tenancy() on that value." }
+    });
+  }
+  const recipe = built;
+  let casingMode;
+  let rendered;
+  const render = () => {
+    rendered ??= renderQuery(name, recipe, casingMode);
+    return rendered;
+  };
+  const bound = viewClient(name, () => render().columns, () => render().query, recipe.mark, "plain");
+  let securityInvoker = false;
+  return {
+    name,
+    schema: "public",
+    "~kind": "view",
+    install(model, tenancy, tables, casing, scoped) {
+      casingMode = casing;
+      rendered = undefined;
+      bound.install(model, tenancy, tables, casing, scoped);
+      securityInvoker = tenancy?.strategy === "rls" && scoped.has(name);
+    },
+    hook: bound.hook,
+    contribute(peers, builtObjects) {
+      assertPeers(peers);
+      assertNoTable(builtObjects, name);
+      const query = render().query;
+      const columns = render().columns.map((column) => ({
+        name: column.name,
+        dataType: column.type
+      }));
+      const provenance = { origin: "file", name };
+      return [
+        viewObject({
+          namespace: staticNamespace2("public"),
+          name,
+          columns,
+          query,
+          provenance,
+          ...securityInvoker ? { securityInvoker: true } : {}
+        })
+      ];
+    }
+  };
+}
+function isRecipe(value) {
+  return typeof value === "object" && value !== null && BUILT in value;
+}
+function finish(recipe) {
+  const built = {
+    ...recipe,
+    where(predicate) {
+      return finish({ ...recipe, predicate: bodyText(predicate) });
+    },
+    tenancy(mark) {
+      return finish({ ...recipe, mark });
+    }
+  };
+  return built;
+}
+function renderQuery(name, recipe, casing) {
+  const fields = recipe.picked ?? Object.keys(recipe.table.columns);
+  if (fields.length === 0) {
+    throw new OkmError2("OKM1120", `View ${name} selects no columns.`, {
+      fix: { summary: "Pick at least one column of the table." }
+    });
+  }
+  const columns = [];
+  const selected = [];
+  for (const field of fields) {
+    const column = recipe.table.columns[field];
+    if (column === undefined || typeof column !== "object" || column === null) {
+      throw new OkmError2("OKM1020", `View ${name} names ${field}, which ${recipe.table.name} does not have.`, { fix: { summary: "Pass a column of that table." } });
+    }
+    const sqlName = columnSql(column, field, casing);
+    columns.push({ name: sqlName, type: columnType(column, field) });
+    selected.push(quoteIdent(sqlName));
+  }
+  const tableName = tableSql(recipe.table, casing);
+  let query = `select ${selected.join(", ")} from ${quoteIdent(tableName)}`;
+  if (recipe.predicate !== undefined && recipe.predicate.trim().length > 0) {
+    query += ` where ${recipe.predicate}`;
+  }
+  return { query, columns };
+}
+function tableSql(table, casing) {
+  const options = table.options;
+  if (typeof options?.sqlName === "string" && options.sqlName.length > 0)
+    return options.sqlName;
+  return casing === "snake" ? snakeCase(table.name) : table.name;
+}
+function columnSql(column, field, casing) {
+  const state = readState(column, field);
+  if (state.sqlName !== undefined && state.sqlName.length > 0)
+    return state.sqlName;
+  return casing === "snake" ? snakeCase(field) : field;
+}
+function columnType(column, field) {
+  const state = readState(column, field);
+  return formatType(state.baseType, state.dims);
+}
+function readState(column, field) {
+  if (!("state" in column)) {
+    throw new OkmError2("OKM1020", `Column ${field} has no type.`, {
+      fix: { summary: "Pass a column built with t." }
+    });
+  }
+  const state = column.state;
+  if (typeof state !== "object" || state === null || !("baseType" in state)) {
+    throw new OkmError2("OKM1020", `Column ${field} has no type.`, {
+      fix: { summary: "Pass a column built with t." }
+    });
+  }
+  const baseType = state.baseType;
+  const dims = "dims" in state && typeof state.dims === "number" ? state.dims : 0;
+  const sqlName = "sqlName" in state && typeof state.sqlName === "string" ? state.sqlName : undefined;
+  if (typeof baseType !== "string" || baseType.length === 0) {
+    throw new OkmError2("OKM1020", `Column ${field} has no type.`, {
+      fix: { summary: "Pass a column built with t." }
+    });
+  }
+  return { baseType, dims, sqlName };
+}
 function bodyText(body) {
   return typeof body === "string" ? body : body.text;
 }

package/dist/dialects/pg/view/scratch.d.ts

@@ -4,19 +4,22 @@
  * Domain and enum types from the catalog are created there, then the tables,
  * then the functions a view may call, then each view. `pg_get_viewdef`
  * replaces the author query and `pg_depend` supplies column edges (D117).
- * The scratch schema is dropped before this returns. Plans never use it.
+ * A `BEGIN ATOMIC` body is replaced with the `pg_get_functiondef` block, so a
+ * plan from the live catalog does not treat Postgres's reprint as a change
+ * (D273). The scratch schema is dropped before this returns. Plans never use it.
  */
 import type { Catalog } from "../../../contracts/catalog/types.js";
-import type { CatalogQuery } from "../introspect.js";
+import { type CatalogQuery } from "../introspect.js";
 /**
  * Reads dependencies and reprints for every view in `source`.
  *
  * The returned catalog matches what introspection prints for those views
  * when the same query is applied. A declared column list that disagrees
- * with the database is OKM1020.
+ * with the database is OKM1020. A `BEGIN ATOMIC` function body is the
+ * server reprint, including an argument qualifier such as `by_id.n`.
  *
  * @param runner - Database connection. Statements share its session
- * @param source - Catalog whose views are still author SQL
- * @returns A catalog whose views carry the reprint and `pg_depend` edges
+ * @param source - Catalog whose views and atomic bodies are still author SQL
+ * @returns A catalog whose views and atomic bodies carry the reprint
  */
 export declare function sealViews(runner: CatalogQuery, source: Catalog): Promise<Catalog>;

package/dist/runtime/aggregate.d.ts

@@ -7,8 +7,14 @@
  * every aggregate exactly as they apply to a `find`. This module loads on the
  * first `aggregate()`.
  *
- * Not here: `having`, `bucket`, and ordering by an aggregate. A hidden column
- * cannot be grouped or aggregated, so an aggregate never shows what a read hides.
+ * Not here: `having`, ordering by an aggregate, and the time-zone date helpers
+ * (tool 5). A hidden column cannot be grouped or aggregated, so an aggregate
+ * never shows what a read hides.
+ *
+ * `bucket()` is a tagged helper. Its validation and SQL load in their own
+ * chunk, and only when `groupBy` contains one. A request object cannot create
+ * one. A NULL timestamp is one group: the result key is present and the value
+ * is null.
  */
 import { type Mods, type Session } from "./client.js";
 import { type ArchiveView } from "./plan.js";

package/dist/runtime/bucket-group.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Time buckets inside `aggregate` `groupBy` (spec §10, §13 tool 4).
+ *
+ * This module loads on the first `aggregate()` whose `groupBy` contains a
+ * `bucket()`. A plain aggregate does not import it. A NULL timestamp is one
+ * group: the `as` key is present and the value is null.
+ */
+import type { ColumnModel } from "../dialects/pg/model.js";
+import { type BucketUnit } from "../dialects/pg/ops/bucket.js";
+import { type Built, type Indexed, type Sink } from "./plan.js";
+/** One bucket in a group list. */
+export type BucketGroup = {
+    readonly kind: "bucket";
+    readonly column: ColumnModel;
+    readonly unit: BucketUnit;
+    readonly tz: string | undefined;
+    readonly as: string;
+    readonly shift: 0 | 1 | 2;
+    readonly clock: boolean;
+};
+/**
+ * What the aggregate chunk calls after this module loads.
+ *
+ * The aggregate chunk does not import this file. It receives the functions
+ * from `import()`.
+ */
+export type BucketChunk = {
+    readBucket(table: Indexed, value: unknown, fields: ReadonlySet<string>, aliases: Set<string>): BucketGroup;
+    writeBucket(sink: Sink, outputs: Built | undefined, wrote: {
+        at: number;
+    }, group: BucketGroup): void;
+    writeGrouped(sink: Sink, names: readonly string[], orderBy: unknown): void;
+};
+/**
+ * Reads one `bucket()` group.
+ *
+ * Refuses a bad unit, zone, week start, or result name before any SQL.
+ * `__proto__`, `constructor`, `toString`, and `hasOwnProperty` are refused.
+ * `timestamptz` needs an IANA `tz`. `date` refuses `tz`. `timestamp` without
+ * a zone is refused.
+ *
+ * @param table - The grouped table
+ * @param value - One `groupBy` entry
+ * @param fields - Plain group fields already seen
+ * @param aliases - Bucket result names already seen
+ * @returns The group the statement writes
+ */
+export declare function readBucket(table: Indexed, value: unknown, fields: ReadonlySet<string>, aliases: Set<string>): BucketGroup;
+/**
+ * Writes one bucket expression into the select list.
+ *
+ * @param sink - Statement buffer
+ * @param outputs - Decode plan, absent while only marking
+ * @param wrote - How many select items are already written
+ * @param group - The bucket
+ */
+export declare function writeBucket(sink: Sink, outputs: Built | undefined, wrote: {
+    at: number;
+}, group: BucketGroup): void;
+/**
+ * Groups and orders by select-list ordinals.
+ *
+ * The bucket expression is written once, in the select list. A second copy
+ * would bind a new `$n`, and Postgres treats that as a different expression.
+ *
+ * @param sink - Statement buffer
+ * @param names - Group names, in select order
+ * @param orderBy - Caller order, or the default group order
+ */
+export declare function writeGrouped(sink: Sink, names: readonly string[], orderBy: unknown): void;

package/dist/runtime/conflict.d.ts

@@ -23,18 +23,36 @@ export type ConflictPlan = {
  */
 export declare function readConflict(table: Indexed, value: unknown, allow?: ReadonlySet<string>, tenantKey?: string | readonly string[]): ConflictPlan | undefined;
 /**
- * Appends the conflict clause, or wraps a first-or-create insert.
+ * Appends the conflict clause.
+ *
+ * First-or-create is `on conflict do nothing`. It does not read the existing
+ * row here: that lookup is a later statement, so it sees a row another
+ * transaction committed while this insert waited (D246).
  *
  * @param head - `insert into … values …` without `returning`
  * @param returning - ` returning …`, including the leading space
  * @param params - Insert parameters
  * @param plan - Conflict plan
  * @param table - Target table
- * @param returningColumns - Columns in `returning`
- * @param keys - Encoded conflict-key tuples, one per inserted row. Used by `return`
  * @returns Statement text and parameters
  */
-export declare function finishInsert(head: string, returning: string, params: readonly (string | null)[], plan: ConflictPlan, table: Indexed, returningColumns: readonly ColumnModel[], keys: readonly (readonly (string | null)[])[]): {
+export declare function finishInsert(head: string, returning: string, params: readonly (string | null)[], plan: ConflictPlan, table: Indexed): {
+    readonly text: string;
+    readonly params: (string | null)[];
+};
+/**
+ * Reads rows a first-or-create insert did not return.
+ *
+ * The conflict target is the same unique, including the tenant key. A partial
+ * unique on an archivable table only matches the active row.
+ *
+ * @param table - Target table
+ * @param keys - Conflict columns, in constraint order
+ * @param returningColumns - Columns the insert returns, in that order
+ * @param keyRows - Encoded conflict-key tuples that the insert did not return
+ * @returns One select
+ */
+export declare function lookupExisting(table: Indexed, keys: readonly ColumnModel[], returningColumns: readonly ColumnModel[], keyRows: readonly (readonly (string | null)[])[]): {
     readonly text: string;
     readonly params: (string | null)[];
 };