okmodel 0.1.1 → 0.3.0

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

@@ -0,0 +1,76 @@
+/**
+ * Preset types and the names a preset may not take (spec section 6.2, D41, D125).
+ *
+ * A preset is a named, typed refinement of a table: `tasks.pending()`. It gets
+ * a builder with one additive method, `where`, and returns that builder. The
+ * builder has no method that removes or replaces a predicate, so a preset can
+ * only narrow what the caller, tenancy, and the active set already allow.
+ *
+ * Only types and one list live here. The code that runs presets loads on the
+ * first call (`runtime/presets.ts`).
+ */
+import type { Or } from "./operators.js";
+import type { FieldWhere } from "./where.js";
+/**
+ * What a preset receives.
+ *
+ * Every method adds. There is no method that removes or replaces a predicate
+ * (D125, D126), and the tenant and active-set predicates are not in the
+ * builder at all: the planner puts them around it.
+ *
+ * @typeParam Row - The table's row
+ */
+export type PresetQuery<Row> = {
+    /**
+     * Adds a predicate, joined with the others by AND.
+     *
+     * Earlier predicates stay, whether the caller's, another preset's, or this
+     * preset's own.
+     *
+     * @param filter - Fields and operators, or `or(...)`
+     * @returns The same builder
+     */
+    where(filter: FieldWhere<Row> | Or<FieldWhere<Row>>): PresetQuery<Row>;
+};
+/**
+ * One preset: the builder first, then the preset's own typed arguments.
+ *
+ * @typeParam Row - The table's row
+ */
+export type Preset<Row> = (q: PresetQuery<Row>, ...args: never[]) => PresetQuery<Row>;
+/**
+ * Names a preset may not take (OKM1040).
+ *
+ * The first group are client methods. The second is reserved for later
+ * releases. `then` would make a table handle look like a promise.
+ */
+export type ReservedPreset = "find" | "one" | "page" | "aggregate" | "count" | "exists" | "insert" | "update" | "delete" | "archive" | "restore" | "withArchived" | "onlyArchived" | "then" | "lock" | "watch" | "subscribe" | "stream" | "inspect" | "explain" | "with" | "for" | "as";
+/**
+ * The `presets` option. A reserved name is a type error here, and OKM1040 when
+ * the schema is used.
+ *
+ * @typeParam Row - The table's row
+ */
+export type PresetMap<Row> = {
+    readonly [name: string]: Preset<Row>;
+} & {
+    readonly [N in ReservedPreset]?: never;
+};
+/** Names {@link ReservedPreset} lists, for the runtime check. */
+export declare const RESERVED_PRESETS: ReadonlySet<string>;
+/**
+ * Throws OKM1040 when a preset name is a client method or reserved.
+ *
+ * @param names - Preset names from one table or one trait
+ * @param where - What defines them, for the message: `table tasks` or `trait softDelete`
+ */
+export declare function checkPresetNames(names: Iterable<string>, where: string): void;
+/**
+ * Throws OKM1040 for a preset name defined by two sources.
+ *
+ * @param name - The preset name
+ * @param table - Table that ends up with both
+ * @param first - What defined it first: `table tasks` or `trait softDelete`
+ * @param second - What defines it again
+ */
+export declare function duplicatePreset(name: string, table: string, first: string, second: string): never;

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

@@ -1,9 +1,11 @@
 /**
- * `one` and `many` relations.
+ * `one`, `many`, and `manyThrough` relations.
  *
  * They name a table. `schema()` resolves the foreign key. An ambiguous key
- * is OKM1021. `manyThrough` arrives in 0.2. `morph` stays reserved.
+ * 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.
  */
+import type { RelationModel } from "./model.js";
 /** A to-one relation. `field` is the local foreign key when the table has several. */
 export type OneRelation<TTable extends string = string> = {
     readonly kind: "one";
@@ -16,6 +18,46 @@ export type ManyRelation<TTable extends string = string> = {
     readonly table: TTable;
     readonly field: string | undefined;
 };
+/** A foreign key `schema()` resolved, as a relation resolver sees it. */
+export type RelationEdge = {
+    readonly fromTable: string;
+    readonly fromField: string;
+    readonly toTable: string;
+    /** Local SQL names, one column or a composite key. */
+    readonly local: readonly string[];
+    /** Referenced SQL names, in the same order. */
+    readonly remote: readonly string[];
+};
+/** What a relation's own resolver reads from `schema()`. */
+export type RelationScope = {
+    /** The table that declares the relation. */
+    readonly owner: string;
+    /** The relation name. */
+    readonly name: string;
+    readonly edges: readonly RelationEdge[];
+    /** Every table name in the schema, sorted. */
+    readonly tables: readonly string[];
+};
+/**
+ * A to-many relation through a join table.
+ *
+ * It is a {@link ManyRelation} to the types, so `include`, `has`, `none`, and
+ * `every` read it as one. `resolve` is what `schema()` calls in place of the
+ * foreign-key search that `many` uses.
+ */
+export type ManyThroughRelation<TTable extends string = string> = ManyRelation<TTable> & {
+    /** The join table. */
+    readonly through: string;
+    /** Turns this declaration into a resolved model. */
+    readonly resolve: (scope: RelationScope) => RelationModel;
+};
+/** Join-table foreign keys, named only when more than one points at a table. */
+export type ThroughKeys = {
+    /** The join table field that references the declaring table. */
+    readonly from?: string;
+    /** The join table field that references the related table. */
+    readonly to?: string;
+};
 /** A relation `table()` stores. */
 export type RelationCall = OneRelation | ManyRelation;
 /**
@@ -43,3 +85,18 @@ export declare function many<const TTable extends string>(table: TTable, field?:
  * @returns `true` for `one` and `many`
  */
 export declare function isRelationCall(value: unknown): value is RelationCall;
+/**
+ * Declares a to-many relation through a join table.
+ *
+ * The join table has one foreign key to the declaring table and one to the
+ * related table. Name `from` and `to` when a table has more than one. Tenancy
+ * and archivable apply to the join rows and to the related rows alike.
+ *
+ * @typeParam TTable - Related table
+ * @param table - Related table name
+ * @param options - The join table, and its foreign-key fields when ambiguous
+ * @returns The relation `schema()` resolves
+ */
+export declare function manyThrough<const TTable extends string>(table: TTable, options: {
+    readonly through: string;
+} & ThroughKeys): ManyThroughRelation<TTable>;

package/dist/dialects/pg/role/check.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Role checks for `okm doctor` and apply preflight.
+ *
+ * Both run before any catalog statement. `connect()` does not call them.
+ */
+import type { DriverPool } from "../../../contracts/driver.js";
+import type { CatalogObject } from "../../../contracts/catalog/types.js";
+import type { RolesInput } from "./index.js";
+/** A pool or a reserved connection. Both can run one statement. */
+type Runner = Pick<DriverPool, "execute">;
+/**
+ * Checks named roles, `CREATEROLE`, and the application role's privileges.
+ *
+ * A missing external role is reported. A managed role that is absent is not:
+ * the plan creates it. OKM1825 is raised only when the object exists and the
+ * privilege is missing.
+ *
+ * @param runner - Database connection
+ * @param roles - `defineConfig({ roles })`
+ * @param objects - Catalog, including grants
+ */
+export declare function assertRoleHealth(runner: Runner, roles: RolesInput, objects: readonly CatalogObject[]): Promise<void>;
+/**
+ * Refuses to apply role changes when the acting role lacks `CREATEROLE`.
+ *
+ * @param runner - Database connection
+ * @param role - The role that will run `CREATE ROLE` or `ALTER ROLE`
+ */
+export declare function assertCreateRole(runner: Runner, role: string): Promise<void>;
+/**
+ * Reads `current_user`.
+ *
+ * @param runner - Database connection
+ * @returns The role this session is acting as
+ */
+export declare function currentUser(runner: Runner): Promise<string>;
+/**
+ * Reports whether `pg_roles` has the name.
+ *
+ * @param runner - Database connection
+ * @param name - Role name
+ * @returns `true` when the role exists
+ */
+export declare function roleExists(runner: Runner, name: string): Promise<boolean>;
+export {};

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

@@ -0,0 +1,50 @@
+/**
+ * `roles: { migration, app }`.
+ *
+ * The object contributes role, grant, and default-privilege records. `schema()`
+ * does not import this module. Tooling calls {@link attachRoles} when the
+ * config names roles.
+ */
+import type { Catalog, CatalogObject } from "../../../contracts/catalog/types.js";
+/** A role the plan creates and alters. It is never dropped. */
+export type ManagedRole = {
+    readonly name: string;
+    /** `LOGIN` when true. The default is `NOLOGIN`. */
+    readonly login?: boolean;
+    /** `INHERIT` when not `false`. */
+    readonly inherit?: boolean;
+};
+/**
+ * Roles named by `defineConfig`.
+ *
+ * A string is external: it must already exist. A name listed in `managed` is
+ * created when `pg_roles` does not have it.
+ */
+export type RolesInput = {
+    /** Role that runs migrations. */
+    readonly migration: string;
+    /** Role the application connects as. */
+    readonly app: string;
+    /** Roles this catalog creates and alters. */
+    readonly managed?: readonly ManagedRole[];
+};
+/**
+ * Adds role, grant, and default-privilege objects to a catalog.
+ *
+ * Grants and default privileges are for {@link RolesInput.app} on every
+ * managed table, view, materialized view, sequence, and function. Fine-grained
+ * grants are not accepted here.
+ *
+ * @param source - Catalog from `schema()`
+ * @param input - Migration role, application role, and managed roles
+ * @returns A catalog that includes those objects
+ */
+export declare function attachRoles(source: Catalog, input: RolesInput): Catalog;
+/**
+ * Catalog records for one `roles` configuration.
+ *
+ * @param input - Migration role, application role, and managed roles
+ * @param built - Objects already in the catalog
+ * @returns Role, grant, and default-privilege records
+ */
+export declare function contributeRoles(input: RolesInput, built: readonly CatalogObject[]): readonly CatalogObject[];

package/dist/dialects/pg/role/sql.d.ts

@@ -0,0 +1,44 @@
+/**
+ * SQL for roles, grants, and default privileges.
+ *
+ * The plan calls these. `SET ROLE` is not one of them: the runner issues it
+ * once, outside the plan (D119).
+ */
+import type { CatalogObject } from "../../../contracts/catalog/types.js";
+/** Statements the planner inserts around the rest of the catalog. */
+export type PrivilegeSql = {
+    /** Revokes, run while the objects still exist. */
+    readonly revoke: readonly string[];
+    /** Role creates, role alters, and default privileges. Before new tables. */
+    readonly prepare: readonly string[];
+    /** Grants on objects that exist, or that this plan creates first. */
+    readonly grant: readonly string[];
+};
+/**
+ * Diffs role, grant, and default-privilege objects into SQL.
+ *
+ * A role is created only when it is managed and absent. It is altered only
+ * when both sides are managed. It is never dropped. Grants and default
+ * privileges are revoked and granted. None of the statements use
+ * `IF NOT EXISTS`.
+ *
+ * @param before - Previous catalog objects
+ * @param after - Next catalog objects
+ * @param schema - Concrete schema name
+ * @returns Statements in three groups
+ */
+export declare function privilegeSql(before: readonly CatalogObject[], after: readonly CatalogObject[], schema: string): PrivilegeSql;
+/**
+ * Role name in `create role`, when the statement is one.
+ *
+ * @param sql - One plan statement
+ * @returns The role, or `undefined` when the statement is not `CREATE ROLE`
+ */
+export declare function createdRoleName(sql: string): string | undefined;
+/**
+ * Reports whether a statement creates or alters a role.
+ *
+ * @param sql - One plan statement
+ * @returns `true` for `CREATE ROLE` and `ALTER ROLE`
+ */
+export declare function changesRole(sql: string): boolean;

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

@@ -4,8 +4,11 @@
  * Work happens here, not in `table()` and not at import.
  */
 import type { Catalog } from "../../contracts/catalog/types.js";
-import { type TableModel } from "./model.js";
-import { type AnyTable } from "./table.js";
+import { type ClientGenerator } from "../../contracts/generator.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";
+import { type AnyTable, type InsertFrom, type RowFrom, type UpdateFrom } from "./table.js";
 /** Codec defaults from spec section 6.6. */
 export type SchemaCodecs = {
     readonly bigint: "string" | "number" | "bigint";
@@ -33,8 +36,28 @@ export type SchemaInput<TTables extends readonly AnyTable[]> = {
         readonly timestamps?: SchemaCodecs["timestamps"];
     };
     readonly types?: "emitted" | "inferred";
-    readonly traits?: unknown;
-    readonly tenancy?: unknown;
+    /**
+     * 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.
+     */
+    readonly defaults?: {
+        readonly id?: "uuidv7" | "uuidv4" | ClientGenerator<string>;
+    };
+    /**
+     * Traits applied to every table.
+     *
+     * A table opts out with `omitDefaults` and a reason. A table's own `traits`
+     * are added as well.
+     */
+    readonly traits?: readonly Trait[];
+    /**
+     * Column tenancy.
+     *
+     * Every table gains the key unless it passes `global("reason")`.
+     */
+    readonly tenancy?: ColumnTenancy;
     readonly validation?: unknown;
     readonly extensions?: unknown;
     readonly functions?: unknown;
@@ -59,11 +82,68 @@ export type BuiltSchema<TTables extends readonly AnyTable[]> = {
     readonly codecs: SchemaCodecs;
     readonly requires: SchemaRequires | undefined;
     readonly tables: TTables;
+    /**
+     * Schema traits, when the call passed a non-empty list.
+     *
+     * Omitted otherwise, so a schema that uses no traits does not carry the key.
+     */
+    readonly traits?: readonly Trait[];
+    /**
+     * Column tenancy, when the call passed it.
+     *
+     * Omitted otherwise, so a schema with no tenancy does not carry the key.
+     */
+    readonly tenancy?: ColumnTenancy;
     /** Query model. Built once, beside the catalog document. */
     readonly model: {
         readonly [T in TTables[number] as T["~name"]]: TableModel;
     };
 };
+/**
+ * A schema whose tenant tables carry the tenant key on the row.
+ *
+ * A table marked `~global` keeps its own type. No tenancy leaves the schema
+ * type unchanged.
+ *
+ * @typeParam S - Schema type before tenancy
+ * @typeParam TTables - Tables in declaration order
+ * @typeParam TTenancy - Column tenancy, or `undefined`
+ */
+export type TenancySchema<S, TTables extends readonly AnyTable[], TTenancy> = TTenancy extends ColumnTenancy ? Omit<S, "~byName"> & {
+    readonly tenancy: TTenancy;
+    readonly "~byName": {
+        readonly [T in TTables[number] as T["~name"]]: T extends {
+            readonly "~global": string;
+        } ? T : T & {
+            readonly "~row": RowFrom<TenantFields<TTenancy["key"]>>;
+            readonly "~insert": InsertFrom<TenantFields<TTenancy["key"]>>;
+            readonly "~update": UpdateFrom<TenantFields<TTenancy["key"]>>;
+        };
+    };
+} : S;
+/**
+ * A schema whose default traits are part of every table's row type.
+ *
+ * A table with `omitDefaults` keeps its own type. An empty trait list does not
+ * change the schema type.
+ *
+ * @typeParam TTables - Tables in declaration order
+ * @typeParam TTraits - Schema default traits
+ */
+export type SchemaWithTraits<TTables extends readonly AnyTable[], TTraits extends readonly {
+    readonly fields: Readonly<Record<string, object>>;
+}[]> = [keyof FieldsOfList<TTraits> | keyof PresetsOfList<TTraits>] extends [never] ? BuiltSchema<TTables> : Omit<BuiltSchema<TTables>, "~byName"> & {
+    readonly "~byName": {
+        readonly [T in TTables[number] as T["~name"]]: ApplySchemaTraits<T, FieldsOfList<TTraits>, TTraits>;
+    };
+};
+type ApplySchemaTraits<TTable, TFields, TTraits> = TTable extends {
+    readonly "~omitDefaults": true;
+} ? TTable : TTable & {
+    readonly "~row": RowFrom<TFields>;
+    readonly "~insert": InsertFrom<TFields>;
+    readonly "~update": UpdateFrom<TFields>;
+} & HasArchive<TTraits> & PresetsOfList<TTraits>;
 /**
  * Compiles tables into a catalog.
  *
@@ -74,4 +154,28 @@ export type BuiltSchema<TTables extends readonly AnyTable[]> = {
  * @param config - Tables, casing, codecs, and the row-type mode
  * @returns The schema and its catalog
  */
-export declare function schema<const TTables extends readonly AnyTable[]>(config: SchemaInput<TTables>): BuiltSchema<TTables>;
+export declare function schema<const TTables extends readonly AnyTable[], const TTraits extends readonly {
+    readonly fields: Readonly<Record<string, object>>;
+}[], const TTenancy extends ColumnTenancy | undefined = undefined, const TValidation = undefined>(config: Omit<SchemaInput<TTables>, "traits" | "tenancy" | "validation"> & {
+    readonly traits: TTraits;
+    readonly tenancy?: TTenancy;
+    readonly validation?: TValidation;
+}): [TValidation] extends [undefined] ? TenancySchema<SchemaWithTraits<TTables, TTraits>, TTables, TTenancy> : TenancySchema<SchemaWithTraits<TTables, TTraits>, TTables, TTenancy> & {
+    readonly "~validation": TValidation;
+};
+export declare function schema<const TTables extends readonly AnyTable[], const TTenancy extends ColumnTenancy | undefined = undefined, const TValidation = undefined>(config: Omit<SchemaInput<TTables>, "tenancy" | "validation"> & {
+    readonly tenancy?: TTenancy;
+    readonly validation?: TValidation;
+}): [TValidation] extends [undefined] ? TenancySchema<BuiltSchema<TTables>, TTables, TTenancy> : TenancySchema<BuiltSchema<TTables>, TTables, TTenancy> & {
+    readonly "~validation": TValidation;
+};
+/**
+ * Registers a hook from an opt-in module.
+ *
+ * Core does not import that module. A featureless app never calls this, so
+ * the module that loads the validation engine stays out of its graph.
+ *
+ * @param hook - Called for the client and for each table
+ */
+export declare function addSchemaHook(hook: SchemaHook): void;
+export {};

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

@@ -6,6 +6,8 @@
  */
 import { type ColumnInsertOf, type ColumnRowOf, type ColumnUpdateOf } from "./column.js";
 import { type RelationCall } from "./relations.js";
+import type { PresetMap } from "./preset.js";
+import { type FieldsOfList, type HasArchive, type PresetsOfList, type Trait } from "./trait.js";
 /**
  * A column as seen by `indexes` and `checks`.
  *
@@ -20,6 +22,19 @@ export type ColumnHandle = {
 export type IndexCall = {
     readonly columns: readonly string[];
     readonly isUnique: boolean;
+    /**
+     * Partial-index predicate, stored as the catalog wrote it.
+     *
+     * Absent on an ordinary index.
+     */
+    readonly predicate?: string;
+    /**
+     * Raw index tail an extension may set on the call.
+     *
+     * A `using …` tail is the extension's index method. The core factory does
+     * not read it. `compileIndexes` copies the field onto the catalog index.
+     */
+    readonly expression?: string;
     /**
      * Marks the index unique.
      *
@@ -52,16 +67,50 @@ export type TableOptions<TColumns> = {
     readonly unique?: {
         readonly [name: string]: readonly (keyof TColumns & string)[];
     };
+    /**
+     * Composite primary key, in column order.
+     *
+     * A single-column key can use this or `.primaryKey()` on the column.
+     * One table has one primary key.
+     */
+    readonly primaryKey?: readonly (keyof TColumns & string)[];
     readonly sqlName?: string;
     readonly renamedFrom?: string;
     readonly comment?: string;
     readonly validate?: unknown;
     readonly validation?: unknown;
-    readonly traits?: unknown;
-    readonly omitDefaults?: unknown;
-    readonly tenancy?: unknown;
+    /**
+     * Traits added to this table.
+     *
+     * Schema default traits are added as well, unless `omitDefaults` is set.
+     */
+    readonly traits?: readonly Trait[];
+    /**
+     * Skip schema default traits.
+     *
+     * The value is the reason. An empty reason is rejected when the schema is built.
+     */
+    readonly omitDefaults?: string;
+    /**
+     * Opts this table out of schema tenancy.
+     *
+     * `global("reason")` is the opt-out. `{ via }` arrives later.
+     */
+    readonly tenancy?: {
+        readonly kind: "global";
+        readonly reason: string;
+    } | {
+        readonly via: string;
+    };
     readonly computed?: unknown;
-    readonly presets?: unknown;
+    /**
+     * Named, typed refinements called as `tasks.pending()`.
+     *
+     * A preset gets a builder and its own arguments and returns the builder.
+     * The builder only adds predicates. A name that is a client method or is
+     * reserved is OKM1040.
+     */
+    readonly presets?: PresetMap<RowFrom<TColumns>>;
     readonly policies?: unknown;
     readonly reference?: unknown;
     /** `one` and `many`. Other relation kinds stay reserved. */
@@ -85,16 +134,39 @@ export type Handles<TColumns> = {
  * @typeParam TColumns - Column builders
  * @typeParam TRelations - Relations declared on this table
  */
-export type Table<TName extends string, TColumns, TRelations extends Readonly<Record<string, RelationCall>> = Readonly<Record<string, never>>> = {
+export type Table<TName extends string, TColumns, TRelations extends Readonly<Record<string, RelationCall>> = Readonly<Record<string, never>>, TKey extends string = never, TOptions = object> = {
     readonly "~name": TName;
     readonly "~columns": TColumns;
     readonly "~row": RowFrom<TColumns>;
     readonly "~insert": InsertFrom<TColumns>;
-    readonly "~update": UpdateFrom<TColumns>;
+    readonly "~update": UpdateFrom<TColumns, TKey>;
     readonly "~relations": TRelations;
     readonly name: TName;
     readonly columns: TColumns;
-    readonly options?: TableOptions<TColumns>;
+    readonly options?: TOptions;
+    /**
+     * Allowlisted client filters.
+     *
+     * A hidden field in `allow`, `sort`, or `relations` throws OKM1123 here.
+     * `parse` loads the parser on first use.
+     *
+     * @param spec - Fields, operators, and sorts the caller may send
+     * @returns A parser for one request object
+     */
+    filters(spec: FilterSpec): {
+        parse(query: unknown): Promise<ParsedFilters>;
+    };
+};
+/** What {@link Table.filters} accepts. */
+export type FilterSpec = {
+    readonly allow?: Readonly<Record<string, readonly string[]>>;
+    readonly sort?: readonly string[];
+    readonly relations?: Readonly<Record<string, readonly string[]>>;
+};
+/** `where` and `orderBy` a caller can spread into `find`. */
+export type ParsedFilters = {
+    readonly where: Readonly<Record<string, unknown>>;
+    readonly orderBy?: Readonly<Record<string, "asc" | "desc">>;
 };
 /**
  * Any table `schema()` can compile.
@@ -108,6 +180,8 @@ export type AnyTable = {
     readonly name: string;
     readonly columns: Readonly<Record<string, object>>;
     readonly options?: object;
+    /** `file.ts:line` of the `table()` call. Not part of the catalog hash. */
+    readonly source?: string;
 };
 /**
  * Row shape. Hidden columns are omitted.
@@ -130,8 +204,8 @@ export type InsertFrom<TColumns> = {
  *
  * @typeParam TColumns - Column builders
  */
-export type UpdateFrom<TColumns> = {
-    readonly [K in keyof TColumns as ColumnUpdateOf<TColumns[K]> extends never ? never : K]: ColumnUpdateOf<TColumns[K]>;
+export type UpdateFrom<TColumns, TKey extends string = never> = {
+    readonly [K in keyof TColumns as K extends TKey ? never : ColumnUpdateOf<TColumns[K]> extends never ? never : K]: ColumnUpdateOf<TColumns[K]>;
 };
 /**
  * Declares a table.
@@ -145,8 +219,8 @@ export type UpdateFrom<TColumns> = {
  * @param options - Indexes, checks, unique constraints, and names
  * @returns The table
  */
-export declare function table<const TName extends string, const TColumns extends Readonly<Record<string, object>>>(name: TName, columns: TColumns): Table<TName, TColumns, Readonly<Record<string, never>>>;
-export declare function table<const TName extends string, const TColumns extends Readonly<Record<string, object>>, const TOptions extends TableOptions<TColumns>>(name: TName, columns: TColumns, options: TOptions): Table<TName, TColumns, RelationsOf<TOptions>>;
+export declare function table<const TName extends string, const TColumns extends Readonly<Record<string, object>>>(name: TName, columns: TColumns): Table<TName, TColumns, Readonly<Record<string, never>>, never>;
+export declare function table<const TName extends string, const TColumns extends Readonly<Record<string, object>>, const TOptions extends TableOptions<TColumns>>(name: TName, columns: TColumns, options: TOptions): DeclaredTable<TName, TColumns, TOptions>;
 /**
  * Relation map stored on a table.
  *
@@ -158,6 +232,58 @@ export declare function table<const TName extends string, const TColumns extends
 type RelationsOf<TOptions> = TOptions extends {
     readonly relations: infer R;
 } ? R extends Readonly<Record<string, RelationCall>> ? R : Readonly<Record<string, never>> : Readonly<Record<string, never>>;
+/**
+ * Column names listed in a table's `primaryKey` option.
+ *
+ * Absent when the option is omitted, so a table without it does not change
+ * its update shape.
+ *
+ * @typeParam TOptions - Options argument
+ */
+type PrimaryOf<TOptions> = TOptions extends {
+    readonly primaryKey: infer K;
+} ? K extends readonly (infer F)[] ? Extract<F, string> : never : never;
+/**
+ * Table type callers see, including trait fields and an opt-out of schema traits.
+ *
+ * @typeParam TName - Table name
+ * @typeParam TColumns - Column builders
+ * @typeParam TOptions - Options argument
+ */
+type DeclaredTable<TName extends string, TColumns, TOptions> = Table<TName, TColumns, RelationsOf<TOptions>, PrimaryOf<TOptions>, NoInfer<TOptions>> & TraitShapes<TColumns, TOptions> & ArchiveFlag<TOptions> & PresetFlag<TOptions> & OmitFlag<TOptions> & GlobalFlag<TOptions>;
+type ArchiveFlag<TOptions> = TOptions extends {
+    readonly traits: infer TTraits;
+} ? HasArchive<TTraits> : unknown;
+/** `{ "~presets" }` from the table's own `presets` and its traits' presets, when there are any. */
+type PresetFlag<TOptions> = (TOptions extends {
+    readonly presets: infer TPresets;
+} ? {
+    readonly "~presets": TPresets;
+} : unknown) & (TOptions extends {
+    readonly traits: infer TTraits;
+} ? PresetsOfList<TTraits> : unknown);
+type OmitFlag<TOptions> = TOptions extends {
+    readonly omitDefaults: string;
+} ? {
+    readonly "~omitDefaults": true;
+} : unknown;
+type GlobalFlag<TOptions> = TOptions extends {
+    readonly tenancy: {
+        readonly kind: "global";
+        readonly reason: infer TReason;
+    };
+} ? {
+    readonly "~global": TReason;
+} : unknown;
+type TraitShapes<TColumns, TOptions> = TOptions extends {
+    readonly traits: infer TTraits;
+} ? TTraits extends readonly {
+    readonly fields: Readonly<Record<string, object>>;
+}[] ? keyof FieldsOfList<TTraits> extends never ? unknown : {
+    readonly "~row": RowFrom<TColumns> & RowFrom<FieldsOfList<TTraits>>;
+    readonly "~insert": InsertFrom<TColumns> & InsertFrom<FieldsOfList<TTraits>>;
+    readonly "~update": UpdateFrom<TColumns, PrimaryOf<TOptions>> & UpdateFrom<FieldsOfList<TTraits>>;
+} : unknown : unknown;
 /**
  * Declares an index from column handles.
  *