okmodel 0.5.1 → 0.7.0

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

@@ -15,6 +15,13 @@ export type IntrospectOptions = {
      * When omitted, roles, grants, and default privileges are not read.
      */
     readonly managedRoles?: readonly string[];
+    /**
+     * Read-only role.
+     *
+     * Schema `USAGE` is read for this role only. Other roles keep the schema
+     * privileges they already have.
+     */
+    readonly reportingRole?: string;
 };
 /** A connection that can run one query. Parameters are `$1`, `$2`, … */
 export type CatalogQuery = {

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

@@ -8,15 +8,18 @@ export type IdDefault = "uuidv7" | "uuidv4" | "none";
 /**
  * Primary key.
  *
- * With no options, the database default is `uuidv7()` unless
- * `schema({ defaults: { id } })` says otherwise. `uuidv4` stores
- * `gen_random_uuid()` (built in from Postgres 13). `none` takes the id on
- * insert. A client generator (`uuidv4`, `uuidv7`, or `okid(...)` from
- * `okmodel/ids`) is filled on insert and stored with no database default.
- * OKID is `text` with collation `C`. A database default is omitted from
- * insert and update. `none` is required on insert and omitted from update.
+ * With no options, the database default is `gen_random_uuid()` unless
+ * `schema({ defaults: { id } })` says otherwise. That function is built in
+ * from Postgres 13, so a bare call works on every supported major. `uuidv7`
+ * stores `uuidv7()` and needs Postgres 18 (`minPostgres: 18`). Pick it for a large write-heavy
+ * table: the ids are time-ordered and the index stays local. Random ids are
+ * fine elsewhere. `none` takes the id on insert. A client generator
+ * (`uuidv4`, `uuidv7`, or `okid(...)` from `okmodel/ids`) is filled on insert
+ * and stored with no database default. OKID is `text` with collation `C`. A
+ * database default is omitted from insert and update. `none` is required on
+ * insert and omitted from update.
  *
- * @param options - Which default to store. Omitted means the schema default, or `uuidv7()`
+ * @param options - Which default to store. Omitted means the schema default, or `gen_random_uuid()`
  * @returns An id column
  */
 export declare function id(): ColumnBuilder<string, IdFlags>;

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

@@ -21,8 +21,13 @@ export type ColumnModel = {
      * call a codec it does not need.
      */
     readonly decode: ((wire: string) => unknown) | undefined;
-    /** Excluded from a default select. Named selects still return it. Includes never return it. */
-    readonly hidden: boolean;
+    /**
+     * Excluded from a default select. Named selects still return it. Includes never return it.
+     *
+     * `"filter"` is still excluded, and `where` and `orderBy` may name it.
+     * `true` is excluded and refused there (OKM1120).
+     */
+    readonly hidden: boolean | "filter";
     /**
      * Redacted in logs, errors, and `inspect()`.
      *
@@ -58,6 +63,39 @@ export type ColumnModel = {
      */
     readonly accepts?: readonly string[] | undefined;
 };
+/**
+ * One table a morph include can return.
+ *
+ * `type` is the table's TypeScript name, which is what the type column stores.
+ */
+export type MorphTarget = {
+    readonly type: string;
+    readonly table: string;
+    /** SQL name of the target table. */
+    readonly sql: string;
+    /** SQL name of the target's single primary-key column. */
+    readonly keySql: string;
+};
+/**
+ * A polymorphic pair: a type column and an id column.
+ *
+ * `to` is the owner side (one of several tables). `many` is the reverse on a target.
+ * Absent on every other relation, so a normal relation does not carry it.
+ */
+export type MorphModel = {
+    readonly direction: "to" | "many";
+    /** Column stem. The fields are `${name}Type` and `${name}Id`. */
+    readonly name: string;
+    readonly typeField: string;
+    readonly idField: string;
+    /** SQL name of the type column. */
+    readonly typeSql: string;
+    /** SQL name of the id column. */
+    readonly idSql: string;
+    /** On a reverse many, the table name stored in the type column. */
+    readonly typeValue?: string;
+    readonly targets: readonly MorphTarget[];
+};
 /**
  * A resolved relation.
  *
@@ -72,6 +110,13 @@ export type RelationModel = {
     readonly local: readonly string[];
     /** SQL names on the related table. */
     readonly remote: readonly string[];
+    /**
+     * Set on a morph relation.
+     *
+     * The include planner reads `to`. A reverse many reads `many` and emits
+     * through {@link RelationModel.through}.
+     */
+    readonly morph?: MorphModel;
     /**
      * Set on a `manyThrough` relation.
      *

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

@@ -0,0 +1,43 @@
+/**
+ * Resolver and emitters of a `morph` relation.
+ *
+ * The relation object carries both. `schema()` calls the resolver, and the
+ * planner calls the emitter with its own helpers, so a schema that never
+ * calls `morph` or `morphMany` does not ship this module. A target in another
+ * tenant or archived never shows: the include planner applies those predicates
+ * to each target, the same way it does for any relation.
+ */
+import type { RelationModel } from "./model.js";
+import type { RelationScope } from "./relations.js";
+/**
+ * Resolves `morph(name, targets)` on the table that holds the type and id columns.
+ *
+ * @param scope - What `schema()` knows
+ * @param name - Column stem: `${name}Type` and `${name}Id`
+ * @param targets - Closed list of target table names
+ * @returns The resolved to-one relation
+ */
+export declare function resolveMorph(scope: RelationScope, name: string, targets: readonly string[]): RelationModel;
+/**
+ * Resolves `morphMany(table, name)` on a target table.
+ *
+ * The many reads the owner table's type and id columns. The owner must declare
+ * `morph(name, targets)` and list this table.
+ *
+ * @param scope - What `schema()` knows. `owner` is the target table
+ * @param table - Table that holds the type and id columns
+ * @param name - Column stem declared on that table
+ * @returns The resolved to-many relation
+ */
+export declare function resolveMorphMany(scope: RelationScope, table: string, name: string): RelationModel;
+/**
+ * Refuses `morphTo` when the name, type, or id is missing.
+ *
+ * `null` used to throw a TypeError on `.length`. An empty name or type stays
+ * OKM1020. A null or non-string id, or a null type, is OKM1120.
+ *
+ * @param name - Column stem
+ * @param type - Target table name
+ * @param id - That table's primary key
+ */
+export declare function assertMorphTo(name: unknown, type: unknown, id: unknown): void;

package/dist/dialects/pg/operator-fit.d.ts

@@ -58,9 +58,9 @@ export declare function assertNoControl(value: string, role: string): void;
  */
 export declare function assertBoundText(value: string, role: string): void;
 /**
- * Rejects a regconfig name that is not an identifier.
+ * Rejects a text search language that is not an identifier.
  *
- * @param config - Text search configuration
+ * @param config - Language name, such as `english`
  */
 export declare function assertRegconfig(config: string): void;
 /**

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

@@ -7,7 +7,7 @@
 declare const brand: unique symbol;
 declare const RUNTIME: unique symbol;
 /** Operator names the read path compiles. */
-export type OperatorName = "eq" | "lt" | "lte" | "gt" | "gte" | "between" | "startsWith" | "contains" | "endsWith" | "like" | "ilike" | "inList" | "notIn" | "not" | "or" | "and" | "has" | "none" | "every" | "inc" | "containedBy" | "overlaps" | "hasKey" | "hasAnyKey" | "path" | "matches" | "similar" | "wordSimilar" | "json.set" | "arr.append" | "arr.remove";
+export type OperatorName = "eq" | "lt" | "lte" | "gt" | "gte" | "between" | "startsWith" | "contains" | "endsWith" | "like" | "ilike" | "inList" | "notIn" | "not" | "or" | "and" | "has" | "none" | "every" | "inc" | "containedBy" | "overlaps" | "hasKey" | "hasAnyKey" | "path" | "matches" | "relevance" | "similar" | "wordSimilar" | "json.set" | "arr.append" | "arr.remove";
 /** A tagged operator. `value` is the operand the helper stored. */
 export type Tagged<Name extends OperatorName, V> = {
     readonly [brand]: Name;
@@ -38,16 +38,23 @@ export type PathValue<V> = {
 };
 /** `col #>> segments` compared with `op`. */
 export type Path<V extends string | number | boolean> = Tagged<"path", PathValue<V>>;
-/** How `matches` turns query text into a tsquery. */
-export type MatchMode = "websearch" | "plain" | "phrase";
-/** Full-text query. `config` is a regconfig name when set. */
+/**
+ * How search text is matched.
+ *
+ * `natural` is web-search style. `all-words` requires every word. `phrase`
+ * keeps the words in order. `advanced` is PostgreSQL query syntax.
+ */
+export type SearchMatch = "natural" | "all-words" | "phrase" | "advanced";
+/** Text to look for, how to match it, and the text search language when one was passed. */
 export type MatchValue = {
     readonly query: string;
-    readonly mode: MatchMode;
-    readonly config: string | undefined;
+    readonly match: SearchMatch;
+    readonly language: string | undefined;
 };
-/** `@@` against a tsvector column. */
+/** `@@` against a search column. */
 export type Matches = Tagged<"matches", MatchValue>;
+/** Order by how well a search column matches. Most relevant first. */
+export type Relevance = Tagged<"relevance", MatchValue>;
 /** Text stored on a `pg_trgm` operator. `schema` is the extension's install schema. */
 export type TrigramQuery = {
     readonly query: string;

package/dist/dialects/pg/ops/bucket.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Time bucket for `aggregate` `groupBy` (spec §10, §13 tool 4).
+ *
+ * The brand is a symbol. JSON cannot create one, so a request cannot add a
+ * bucket. A plain object in `groupBy` stays OKM1120. The SQL loads with the
+ * first `aggregate()` whose `groupBy` contains a bucket.
+ */
+declare const brand: unique symbol;
+/** Calendar and clock units `bucket` accepts. */
+export type BucketUnit = "second" | "minute" | "hour" | "day" | "week" | "month" | "quarter" | "year";
+/** Week that starts on Monday (ISO), Sunday, or Saturday. */
+export type WeekStart = "monday" | "sunday" | "saturday";
+/**
+ * A `bucket()` call.
+ *
+ * `C` is the column, `U` the unit, and `A` the result key.
+ */
+export type Bucket<C extends string, U extends string, A extends string> = {
+    readonly [brand]: C;
+    readonly unit: U;
+    readonly as: A;
+};
+/** What {@link bucket} stores. The aggregate chunk reads this. */
+export type BucketInput = {
+    readonly column: unknown;
+    readonly unit: unknown;
+    readonly as: unknown;
+    readonly tz: unknown;
+    readonly weekStart: unknown;
+};
+/**
+ * Groups a timestamp or date column by a calendar or clock unit.
+ *
+ * `tz` is required for `timestamptz` and refused for `date`. `timestamp`
+ * without a zone is refused. `as` is the result key. `__proto__`, `constructor`,
+ * `toString`, and `hasOwnProperty` are refused when the aggregate runs.
+ * `weekStart` applies only
+ * to `week` and defaults to Monday. A NULL timestamp is its own group: the
+ * `as` key is present and the value is null.
+ *
+ * Day, week, month, quarter, and year come back as `Temporal.PlainDate` (the
+ * local date the period starts). Second, minute, and hour come back as
+ * `Temporal.Instant` (the period start).
+ *
+ * @typeParam C - Column name
+ * @typeParam U - Unit
+ * @typeParam A - Result key
+ * @param column - Field to bucket
+ * @param unit - Period
+ * @param options - Zone, result key, and week start
+ * @returns A tagged bucket. Pass it in `groupBy`
+ */
+export declare function bucket<const C extends string, const U extends BucketUnit, const A extends string>(column: C, unit: U, options: {
+    readonly tz?: string;
+    readonly as: A;
+    readonly weekStart?: WeekStart;
+}): Bucket<C, U, A>;
+/**
+ * Reports whether `value` is a {@link bucket} call.
+ *
+ * @param value - One `groupBy` entry
+ * @returns `true` when {@link bucket} created it
+ */
+export declare function isBucket(value: unknown): value is BucketInput;
+export {};

package/dist/dialects/pg/ops/inc.d.ts

@@ -2,9 +2,9 @@ import { type Tagged } from "../operators.js";
 /** Adds to the stored number. `undefined` in `set` still leaves the field unchanged. */
 export type Inc<V> = Tagged<"inc", V>;
 /**
- * Atomic increment used in `update` `set` (spec §11).
+ * Adds to a stored number in `update` `set` (spec §11).
  *
- * JSON and array operators are not this helper.
+ * A null number stays null. JSON and array operators are not this helper.
  *
  * @typeParam V - Amount
  * @param value - Amount to add

package/dist/dialects/pg/ops/matches.d.ts

@@ -1,16 +1,13 @@
-import { type MatchMode, type Matches } from "../operators.js";
+import { type Matches } from "../operators.js";
+import { type SearchOptions } from "./search-query.js";
 /**
- * Full-text match (`@@`) for a tsvector column.
+ * Full-text match for a search column.
  *
- * The default mode is `websearch_to_tsquery`, which does not throw on user
- * input. `"plain"` uses `plainto_tsquery` and `"phrase"` uses `phraseto_tsquery`.
- * A text column is not searched here.
+ * The default match is natural, which does not throw on user input. A plain
+ * text column is not searched here. `relevance` orders by the same match.
  *
- * @param query - Search text
- * @param options - Mode and regconfig name
- * @returns A tagged operator
+ * @param query - Text to look for
+ * @param options - How to match, and the text search language
+ * @returns A tagged operator for `where`
  */
-export declare function matches(query: string, options?: {
-    readonly mode?: MatchMode;
-    readonly config?: string;
-}): Matches;
+export declare function matches(query: string, options?: SearchOptions): Matches;

package/dist/dialects/pg/ops/relevance.d.ts

@@ -0,0 +1,13 @@
+import { type Relevance } from "../operators.js";
+import { type SearchOptions } from "./search-query.js";
+/**
+ * Orders a search column by how well it matches.
+ *
+ * Most relevant first. Pass it as an `orderBy` value. `find({ search })`
+ * compiles to `matches` plus this, so the SQL is the same.
+ *
+ * @param query - Text to look for
+ * @param options - How to match, and the text search language. Same words as `matches`
+ * @returns A tagged order
+ */
+export declare function relevance(query: string, options?: SearchOptions): Relevance;

package/dist/dialects/pg/ops/search-query.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared operand for `matches` and `relevance`.
+ *
+ * Both helpers store this shape. The SQL compiler reads it once, so `search`
+ * and the two helpers emit the same text.
+ */
+import type { MatchValue, SearchMatch } from "../operators.js";
+/** Options `matches` and `relevance` take. */
+export type SearchOptions = {
+    /** How to match. Omitted means `natural`. */
+    readonly match?: SearchMatch;
+    /** Text search language, such as `english`. Omitted uses the database default. */
+    readonly language?: string;
+};
+/**
+ * Stores the text, the match, and the language.
+ *
+ * @param query - Text to look for
+ * @param options - Match and language. Omitted means natural, database language
+ * @returns The operand both helpers tag
+ */
+export declare function searchValue(query: string, options?: SearchOptions): MatchValue;

package/dist/dialects/pg/ops/window.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Window helpers for `select` (spec §10, §13 tool 12).
+ *
+ * The brand is a symbol. JSON cannot create one, so a request cannot add a
+ * window. A plain object in `select` stays OKM1120. The SQL loads on the first
+ * `find` or `one` whose `select` contains one.
+ */
+declare const brand: unique symbol;
+/** `asc` is nulls last and `desc` is nulls first unless `nulls` is set. */
+type SortDir = "asc" | "desc" | {
+    readonly dir: "asc" | "desc";
+    readonly nulls?: "first" | "last";
+};
+/** Columns the window orders by. Names are checked when the call runs. */
+export type WindowOrder = {
+    readonly [field: string]: SortDir | undefined;
+};
+/** What a window helper stores. The planner reads this. */
+export type WindowCall = {
+    readonly label: "rowNumber" | "rank" | "denseRank" | "runningTotal";
+    readonly fn: "row_number" | "rank" | "dense_rank" | "sum";
+    readonly column: string | undefined;
+    readonly partitionBy: readonly string[] | undefined;
+    readonly orderBy: unknown;
+    readonly as: string;
+};
+/**
+ * A window helper.
+ *
+ * `A` is the result key. `V` is `number` for a rank, or the source column for
+ * a running total.
+ */
+export type Window<A extends string, V extends string | number> = {
+    readonly [brand]: V;
+    readonly as: A;
+};
+/**
+ * Options every window helper takes.
+ *
+ * `partitionBy` is the group. Omit it to number the whole result. `orderBy`
+ * is the order inside that group. The primary key breaks ties. `as` is the
+ * result key. `__proto__`, `constructor`, `toString`, and `hasOwnProperty`
+ * are refused when the call runs.
+ */
+type WindowOptions<A extends string> = {
+    readonly partitionBy?: readonly string[];
+    readonly orderBy: WindowOrder;
+    readonly as: A;
+};
+/**
+ * Reports whether `value` is a window helper.
+ *
+ * @param value - One `select` entry
+ * @returns `true` when a helper in this module created it
+ */
+export declare function isWindow(value: unknown): value is WindowCall;
+/**
+ * Row number inside a group, starting at 1.
+ *
+ * Ties get distinct numbers. The primary key breaks them.
+ *
+ * @typeParam A - Result key
+ * @param options - Group, order, and result key
+ * @returns A tagged window. Pass it in `select` on `find` or `one`
+ */
+export declare function rowNumber<const A extends string>(options: WindowOptions<A>): Window<A, number>;
+/**
+ * Rank inside a group, with gaps after a tie.
+ *
+ * Two rows with the same order share a rank. The next rank skips. The primary
+ * key breaks the order when you need a stable row, and it does not split the
+ * rank.
+ *
+ * @typeParam A - Result key
+ * @param options - Group, order, and result key
+ * @returns A tagged window. Pass it in `select` on `find` or `one`
+ */
+export declare function rank<const A extends string>(options: WindowOptions<A>): Window<A, number>;
+/**
+ * Rank inside a group, without gaps after a tie.
+ *
+ * Two rows with the same order share a rank. The next rank is the next number.
+ *
+ * @typeParam A - Result key
+ * @param options - Group, order, and result key
+ * @returns A tagged window. Pass it in `select` on `find` or `one`
+ */
+export declare function denseRank<const A extends string>(options: WindowOptions<A>): Window<A, number>;
+/**
+ * Running total of a number column.
+ *
+ * The total follows `orderBy` inside the group. A null number does not add.
+ * The result uses the column's value type: a number, or the exact decimal
+ * string of a `numeric` column.
+ *
+ * @typeParam C - Column
+ * @typeParam A - Result key
+ * @param column - Field to total
+ * @param options - Group, order, and result key
+ * @returns A tagged window. Pass it in `select` on `find` or `one`
+ */
+export declare function runningTotal<const C extends string, const A extends string>(column: C, options: WindowOptions<A>): Window<A, C>;
+export {};

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

@@ -0,0 +1,42 @@
+/**
+ * Table ownership marks (`external` and `ignored`).
+ *
+ * The mark lives on the table value, not in `table()` options. `schema()` does
+ * not read it, so a featureless app does not load this module. Tooling stamps
+ * the catalog before it plans.
+ */
+import type { Catalog, Owner } from "../../contracts/catalog/types.js";
+import type { AnyTable } from "./table.js";
+/** Owners a declaration may set. `managed` stays the default. */
+export type DeclaredOwner = Exclude<Owner, "managed">;
+/**
+ * Marks a table `external` or `ignored`.
+ *
+ * `external` is known and queryable, and a plan never creates, alters, or
+ * drops it. `ignored` is invisible to diffs, plans, and `okm check`. The
+ * table stays on the schema, so the client can still name it.
+ *
+ * @param table - A `table()` value
+ * @param owner - `external` or `ignored`
+ * @returns The same table
+ */
+export declare function withOwner<T extends AnyTable>(table: T, owner: DeclaredOwner): T;
+/**
+ * Reads the mark {@link withOwner} stored.
+ *
+ * @param table - A table value
+ * @returns The mark, or `undefined` when the table is managed
+ */
+export declare function tableOwner(table: object): DeclaredOwner | undefined;
+/**
+ * Copies `owner` onto a table and the objects that belong to it.
+ *
+ * Columns, indexes, constraints, triggers, policies, and sequences that
+ * depend on the table follow the table. A catalog with no marks is returned
+ * as itself.
+ *
+ * @param source - Catalog from `schema()`
+ * @param marks - SQL table name to owner
+ * @returns The catalog planning and drift should read
+ */
+export declare function stampOwnership(source: Catalog, marks: ReadonlyMap<string, DeclaredOwner>): Catalog;

package/dist/dialects/pg/path-endpoint.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Marks the table a path ends on.
+ *
+ * The symbol lives here so a column-only app and a featureless app do not
+ * load it. `archivable()` reads it. Compile hashes named fields, so the mark
+ * stays out of the catalog.
+ */
+/**
+ * Property set on the tenant table a path ends on.
+ *
+ * An options spread does not copy it. The rewrite sets it on the table object.
+ */
+export declare const pathEndpoint: unique symbol;
+/**
+ * Records that `table` is the end of a path.
+ *
+ * @param table - The rewritten tenant table
+ * @returns The same table, marked
+ */
+export declare function markPathEndpoint<T extends object>(table: T): T;

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

@@ -44,7 +44,7 @@ export type Preset<Row> = (q: PresetQuery<Row>, ...args: never[]) => PresetQuery
  * 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";
+export type ReservedPreset = "find" | "one" | "page" | "aggregate" | "count" | "exists" | "insert" | "update" | "delete" | "descendants" | "ancestors" | "sync" | "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.

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;
+};