@zmdb/orm 1.0.0-beta.1

package/dist/index.js

@@ -0,0 +1,2003 @@
+import { isRecord, resolveRelation, } from '@zmdb/schema';
+import {} from '@zmdb/schema/derive';
+import { buildListResult, decodeCursor, } from '@zmdb/schema/dto';
+import { appTypeOf, dbDecodedColumns, decodeDbValue, objectTypeFromShape, SQL_TYPES, shapeOfVariant, } from '@zmdb/schema/ir';
+import {} from '@zmdb/schema/tags';
+import {} from '@zmdb/sql';
+import { chunkArray, createQueryCompiler, dialectCapabilities, dialectTraits, EXPR, inc, proposed, sanitizeKeys, } from '@zmdb/sql';
+import { aggregateSelectFrom } from '@zmdb/sql/aggregations';
+import { ftsSelectFrom } from '@zmdb/sql/fts';
+import { joinableSelectFrom } from '@zmdb/sql/joins';
+import {} from '@zmdb/sql/schema-objects';
+// @zmdb/orm — the repository layer: reads (#26), writes (#27), delete +
+// lifecycle hooks (#28), transactions (#37), typed populate (#217) and the
+// no-subclass wiring helper (#223). Every SQL statement comes from
+// @zmdb/sql and every type from the schema; there is no runtime
+// reflection, no proxies and no identity map.
+import { issuesFor, ValidationError } from '@zmdb/validator';
+import { cacheTags, copyCachedRows, memoryStore, resultCacheKey, } from './cache/index.js';
+import { compileWhere, applyOrderBy, applyPagination, applyKeysetFilter } from './dto/index.js';
+import { applyResolvedFilters, filtersAsPredicates, resolveFilters, } from './filters/index.js';
+import { createEntityLoader, createRelationLoader, LOADER_ENTITY_BATCH, LOADER_ENTITY_KEY, LOADER_FOR_SCOPE, LOADER_RELATION_BATCH, LOADER_RELATION_KEY, RELATION_LOADER_FOR_SCOPE, } from './loaders/index.js';
+import {} from './relations/index.js';
+import { createRepositoryStream } from './streaming/index.js';
+const BUFFERED_STREAM_REPORTED = new WeakSet();
+function executeOptions(signal, batchSize) {
+    if (signal === undefined)
+        return batchSize === undefined ? undefined : { batchSize };
+    return batchSize === undefined ? { signal } : { signal, batchSize };
+}
+function parseTableSpec(spec) {
+    const match = /^(\S+)(?:\s+(?:as\s+)?(\S+))?$/i.exec(spec.trim());
+    const table = match?.[1] ?? spec.trim();
+    return { table, reference: match?.[2] ?? table };
+}
+function isFilterDef(value) {
+    return (isRecord(value) &&
+        typeof value.name === 'string' &&
+        typeof value.where === 'function' &&
+        (value.table === undefined || typeof value.table === 'string') &&
+        (value.schema === undefined ||
+            (isRecord(value.schema) && typeof value.schema.table === 'string' && isRecord(value.schema.ir))) &&
+        (value.enabled === undefined || typeof value.enabled === 'boolean') &&
+        (value.appliesToWrites === undefined || typeof value.appliesToWrites === 'boolean'));
+}
+function staticFiltersFor(constructor) {
+    const value = Reflect.get(constructor, 'filters');
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || !value.every(isFilterDef)) {
+        throw new ValidationError('repository static filters must be an array of filter definitions');
+    }
+    return value;
+}
+function schemaSqlNames(schema) {
+    const ir = schema.ir;
+    const columns = new Map(ir.columns.map(column => [column.name, column.physicalName]));
+    const renamed = ir.columns.some(column => column.name !== column.physicalName);
+    const entityProjection = renamed
+        ? Object.freeze(ir.columns.map(column => column.name === column.physicalName
+            ? column.physicalName
+            : { column: column.physicalName, alias: column.name }))
+        : undefined;
+    const keyColumns = Object.freeze([...ir.primaryKey]);
+    return {
+        schema,
+        ir,
+        columns,
+        keyColumns,
+        physicalKeyColumns: Object.freeze(keyColumns.map(column => columns.get(column) ?? column)),
+        entityProjection,
+    };
+}
+export { ValidationError };
+/** A composite key omitted one or more required own properties. */
+export class IncompleteKeyError extends ValidationError {
+    table;
+    missing;
+    constructor(table, method, missing) {
+        const orderedMissing = Object.freeze([...missing]);
+        super(`${table}.${method} requires every key column; missing: ${orderedMissing.join(', ')}`);
+        this.name = 'IncompleteKeyError';
+        this.table = table;
+        this.missing = orderedMissing;
+    }
+}
+function isUpdateFieldList(value) {
+    return Array.isArray(value);
+}
+const ROUTINE_SQL_TYPES = new Set(SQL_TYPES);
+function isRoutineDefinition(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.kind !== 'function' && value.kind !== 'procedure')
+        return false;
+    if (typeof value.name !== 'string' || value.name.trim().length === 0)
+        return false;
+    if (typeof value.body !== 'string' || !Array.isArray(value.params))
+        return false;
+    if (value.language !== undefined && typeof value.language !== 'string')
+        return false;
+    if (value.deterministic !== undefined && typeof value.deterministic !== 'boolean')
+        return false;
+    for (const param of value.params) {
+        if (!isRecord(param))
+            return false;
+        if (typeof param.name !== 'string' || param.name.trim().length === 0)
+            return false;
+        if (typeof param.type !== 'string' || !ROUTINE_SQL_TYPES.has(param.type))
+            return false;
+        if (param.mode !== undefined && param.mode !== 'in' && param.mode !== 'out' && param.mode !== 'inout') {
+            return false;
+        }
+    }
+    if (value.returns !== undefined) {
+        if (!isRecord(value.returns))
+            return false;
+        if (typeof value.returns.type !== 'string' ||
+            (value.returns.type !== 'void' && !ROUTINE_SQL_TYPES.has(value.returns.type))) {
+            return false;
+        }
+        if (value.returns.setof !== undefined && typeof value.returns.setof !== 'boolean')
+            return false;
+    }
+    return true;
+}
+function routineColumn(name, sql) {
+    return {
+        name,
+        physicalName: name,
+        sql,
+        nullable: false,
+        primaryKey: false,
+        serial: false,
+        unique: false,
+        hasDefault: false,
+        sensitive: false,
+        constraints: {},
+        rules: [],
+        // A routine declaration carries only the SQL type, so bare JSON has no
+        // narrower payload witness and is correctly validated as unknown.
+        ...(sql === 'json' ? { payload: { kind: 'unknown' } } : {}),
+    };
+}
+function validatedRoutineValue(value, type) {
+    const issues = issuesFor(value, type, 'result');
+    if (issues.length > 0) {
+        throw new ValidationError(`validation failed: ${issues.map(issue => issue.path).join(', ')}`, issues);
+    }
+    return value;
+}
+/**
+ * Whether a value can be a single-column primary key.
+ *
+ * The composite branch of `keyWhere` has always refused a key that is missing a
+ * column; the single-column branch accepted anything and wrapped it, so an object
+ * arriving from untyped input became `{ id: { … } }` — a where-spec that compiles to
+ * no predicate at all and therefore an `UPDATE` or `DELETE` over the whole table
+ * (#608). `PrimaryKeyOf<T>` rules this out at compile time for typed callers; this is
+ * for the value that did not come through the types.
+ *
+ * `Date` counts as a scalar: it is one column's value for a `timestamp` key, and the
+ * composite branch excludes it by name for the same reason.
+ */
+function isScalarKey(value) {
+    return (typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'bigint' ||
+        typeof value === 'boolean' ||
+        value instanceof Date);
+}
+/** What a rejected key was, for the error message. Never the value itself. */
+function describeKey(value) {
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'undefined';
+    if (value instanceof Date)
+        return 'a Date';
+    if (Array.isArray(value))
+        return 'an array';
+    if (typeof value === 'object')
+        return 'an object';
+    return typeof value === 'function' ? 'a function' : `a ${typeof value}`;
+}
+/** Type-tag one SQL key value so values such as `1`, `'1'` and `1n` cannot collide. */
+function loaderKeyPart(value) {
+    if (value instanceof Date)
+        return `d:${value.getTime()}`;
+    if (value === null)
+        return 'z:';
+    if (value === undefined)
+        return 'u:';
+    if (typeof value === 'string')
+        return `s:${value.length}:${value}`;
+    if (typeof value === 'number')
+        return `n:${String(value)}`;
+    if (typeof value === 'bigint')
+        return `i:${String(value)}`;
+    if (typeof value === 'boolean')
+        return `b:${String(value)}`;
+    throw new ValidationError(`dataloader keys must be SQL scalar values; got ${describeKey(value)}`);
+}
+/** Length-prefix each tagged part so composite-key boundaries are unambiguous. */
+function scalarLoaderKey(value) {
+    const part = typeof value === 'number' ? `n:${String(value)}` : loaderKeyPart(value);
+    return `${part.length}:${part}`;
+}
+function loaderKey(parts) {
+    if (parts.length === 1)
+        return scalarLoaderKey(parts[0]);
+    let key = '';
+    for (const value of parts)
+        key += scalarLoaderKey(value);
+    return key;
+}
+function relationKeyValues(row, columns) {
+    return columns.map(column => Reflect.get(row, column));
+}
+function relationRowKey(row, columns) {
+    let key = '';
+    for (const column of columns) {
+        const value = Reflect.get(row, column);
+        if (value === null || value === undefined)
+            return undefined;
+        key += scalarLoaderKey(value);
+    }
+    return key;
+}
+function hasNullishKeyPart(values) {
+    return values.some(value => value === null || value === undefined);
+}
+function copyPopulatedRow(row, nodes) {
+    const copy = { ...row };
+    for (const node of nodes) {
+        const value = Reflect.get(row, node.relation.name);
+        copy[node.relation.name] = Array.isArray(value)
+            ? value.map(child => copyPopulatedRow(child, node.children))
+            : value === null
+                ? null
+                : copyPopulatedRow(value, node.children);
+    }
+    return copy;
+}
+const NO_EXPRESSION_OPERAND = Symbol('zmdb.no-expression-operand');
+function isColumnExpression(value) {
+    return typeof value === 'object' && value !== null && EXPR in value;
+}
+function expressionOperand(expression) {
+    switch (expression.op) {
+        case 'add':
+        case 'sub':
+        case 'mul':
+            return expression.by;
+        case 'concat':
+            return expression.with;
+        case 'coalesce':
+            return expression.fallback;
+        case 'not':
+        case 'proposed':
+            return NO_EXPRESSION_OPERAND;
+    }
+}
+/**
+ * The base repository.
+ *
+ * `T` is the **declared type** — the interface the table was written as — and every DTO on
+ * this class derives from it. It is not the schema value: a repository is handed one of
+ * those at construction, and `defineRepository` recovers `T` from its phantom, but nothing
+ * here reads a column map to work out what a row looks like.
+ *
+ * Relations come from `T` as well. There used to be a second type parameter for them,
+ * paired with a static `relations` map, because `Entity<T>` was derived from a schema value
+ * and a schema value carries no relations — so the map was the only place the runtime could
+ * learn that `orders` means `orders.userId`. The declaration says it:
+ *
+ * ```ts
+ * interface User extends Table<'users'> {
+ *   id: number & Sql<'integer'> & Serial & PrimaryKey;
+ *   orders?: Order[] & OneToMany<'orders', 'userId'>;
+ * }
+ *
+ * class Users extends BaseRepository<User> {
+ *   static override readonly schema = UserSchema;
+ * }
+ * ```
+ *
+ * `populate: ['orders']` is checked against `RelationKeys<User>` and the batched select it
+ * runs comes from the same tag. `defineRepository` needs no subclass at all.
+ */
+export class BaseRepository {
+    static schema;
+    driver;
+    qb;
+    dialect;
+    dialectCapabilities;
+    dialectTraits;
+    /** Ordered primary-key columns, resolved once because a repository's schema cannot change. */
+    keyColumns;
+    physicalKeyColumns;
+    #rootSqlNames;
+    #sqlNamesByDeclaredTable = new Map();
+    #sqlNamesByPhysicalTable = new Map();
+    #additionalSchemas;
+    /** variant → its columns and their object type. See `payloadShape`. */
+    #shapes = new Map();
+    /** The columns a driver may hand back in their storage form. See `decodeRows`. */
+    #decoded;
+    /** Undefined until a custom store is supplied or an opted-in read needs the bounded default. */
+    #cacheStore;
+    #cacheFailureReported = false;
+    #optionFilters;
+    #filterDefinitions;
+    #onQuery;
+    #queryFilters = new WeakMap();
+    /** Loader state is keyed by the explicit request-scope token, never globally. */
+    #entityLoaders = new WeakMap();
+    #relationLoaders = new WeakMap();
+    constructor(driver, dialect = driver.dialect, options) {
+        if (dialect === undefined) {
+            throw new TypeError('repository construction requires an explicit database dialect object');
+        }
+        this.driver = driver;
+        this.dialect = dialect;
+        this.dialectCapabilities = dialectCapabilities(dialect);
+        this.dialectTraits = dialectTraits(dialect);
+        this.#cacheStore = options?.cacheStore;
+        this.#optionFilters = Object.freeze([...(options?.filters ?? [])]);
+        const staticFilters = staticFiltersFor(this.constructor);
+        this.#additionalSchemas = Object.freeze([...(options?.schemas ?? [])]);
+        const rootSchema = this.schema;
+        const configuredSchemas = [
+            rootSchema,
+            ...this.#additionalSchemas,
+            ...staticFilters.flatMap(filter => (filter.schema === undefined ? [] : [filter.schema])),
+            ...this.#optionFilters.flatMap(filter => (filter.schema === undefined ? [] : [filter.schema])),
+        ];
+        for (const schema of configuredSchemas) {
+            const names = schemaSqlNames(schema);
+            const existing = this.#sqlNamesByDeclaredTable.get(names.ir.table);
+            if (existing !== undefined) {
+                if (existing.schema.table !== schema.table) {
+                    throw new ValidationError(`repository schemas disagree on physical table for \`${names.ir.table}\`: ` +
+                        `\`${existing.schema.table}\` and \`${schema.table}\``);
+                }
+                continue;
+            }
+            this.#sqlNamesByDeclaredTable.set(names.ir.table, names);
+            this.#sqlNamesByPhysicalTable.set(schema.table, names);
+        }
+        const rootNames = this.#sqlNamesByPhysicalTable.get(rootSchema.table);
+        if (rootNames === undefined)
+            throw new Error(`repository schema map omitted ${rootSchema.table}`);
+        this.#rootSqlNames = rootNames;
+        this.#filterDefinitions = Object.freeze([...staticFilters, ...this.#optionFilters].map(filter => {
+            if (filter.table !== undefined &&
+                filter.schema !== undefined &&
+                filter.table !== filter.schema.ir.table &&
+                filter.table !== filter.schema.table) {
+                throw new ValidationError(`filter \`${filter.name}\` targets \`${filter.table}\` but its schema declares ` +
+                    `\`${filter.schema.ir.table}\` (physical \`${filter.schema.table}\`)`);
+            }
+            const mapped = filter.schema === undefined
+                ? filter.table === undefined
+                    ? this.#rootSqlNames
+                    : (this.#sqlNamesByDeclaredTable.get(filter.table) ?? this.#sqlNamesByPhysicalTable.get(filter.table))
+                : this.#sqlNamesByDeclaredTable.get(filter.schema.ir.table);
+            return { ...filter, table: mapped?.schema.table ?? filter.table ?? this.schema.table };
+        }));
+        this.#onQuery = options?.onQuery;
+        this.qb = createQueryCompiler(dialect, driver.queryTelemetry === true ? { telemetry: true } : undefined);
+        this.keyColumns = this.#rootSqlNames.keyColumns;
+        this.physicalKeyColumns = this.#rootSqlNames.physicalKeyColumns;
+        const seen = new Set();
+        for (const filter of this.#filterDefinitions) {
+            if (filter.name.trim().length === 0)
+                throw new ValidationError('filter names must not be empty');
+            const identity = `${filter.table ?? this.schema.table}\u0000${filter.name}`;
+            if (seen.has(identity)) {
+                throw new ValidationError(`filter \`${filter.name}\` is declared more than once for \`${filter.table}\``);
+            }
+            seen.add(identity);
+        }
+    }
+    [LOADER_FOR_SCOPE](scope) {
+        const existing = this.#entityLoaders.get(scope);
+        if (existing)
+            return existing;
+        const created = createEntityLoader(this);
+        this.#entityLoaders.set(scope, created);
+        return created;
+    }
+    [RELATION_LOADER_FOR_SCOPE](scope, relation) {
+        let loaders = this.#relationLoaders.get(scope);
+        if (!loaders) {
+            loaders = {};
+            this.#relationLoaders.set(scope, loaders);
+        }
+        const existing = Object.hasOwn(loaders, relation) ? loaders[relation] : undefined;
+        if (existing)
+            return existing;
+        const created = createRelationLoader(this, relation);
+        Object.defineProperty(loaders, relation, {
+            configurable: false,
+            enumerable: true,
+            value: created,
+            writable: false,
+        });
+        return created;
+    }
+    // #37 — bind this repository to a transaction context so all its SQL runs
+    // on the transaction's connection. Re-instantiates via standard constructor
+    // invocation to allocate private instance state and avoid method binding leaks.
+    //
+    // boundary: the assertion names the constructor this class declares, on the subclass that
+    // inherited it, and `this` as its return type. A subclass that widens the signature —
+    // taking a required third argument — would be constructed here without it; that is a
+    // subclass contract, like the static `schema`, and there is no way to state it in the type
+    // system from inside the base class. `new (this.constructor as …)` is the only way to
+    // re-run field initialisers, which is the point: `Object.create` would share `#shapes`.
+    withTransaction(tx) {
+        const txStream = typeof tx.stream === 'function' ? tx.stream : undefined;
+        const txDriver = {
+            dialect: this.dialect,
+            ...(this.driver.queryTelemetry === true ? { queryTelemetry: true } : {}),
+            execute: (query, opts) => tx.execute(query, opts),
+            ...(txStream === undefined
+                ? {}
+                : {
+                    stream: (query, opts) => txStream.call(tx, query, opts),
+                }),
+        };
+        const ctor = this.constructor;
+        const options = {
+            ...(this.#cacheStore === undefined ? {} : { cacheStore: this.#cacheStore }),
+            ...(this.#optionFilters.length === 0 ? {} : { filters: this.#optionFilters }),
+            ...(this.#additionalSchemas.length === 0 ? {} : { schemas: this.#additionalSchemas }),
+            ...(this.#onQuery === undefined ? {} : { onQuery: this.#onQuery }),
+        };
+        return new ctor(txDriver, this.dialect, Object.keys(options).length === 0 ? undefined : options);
+    }
+    async call(definition, args) {
+        if (!isRoutineDefinition(definition)) {
+            throw new ValidationError('routine calls require a declared RoutineDef', [
+                {
+                    path: 'routine',
+                    message: 'expected a declared routine definition, not a caller-supplied name',
+                    expected: 'RoutineDef',
+                    value: definition,
+                },
+            ]);
+        }
+        if (!Array.isArray(args)) {
+            throw new ValidationError(`routine "${definition.name}" arguments must be a tuple`, [
+                { path: 'input', message: 'expected array', expected: 'array', value: args },
+            ]);
+        }
+        const unsupported = definition.params.find(param => param.mode === 'out' || param.mode === 'inout');
+        if (unsupported) {
+            throw new ValidationError(`routine "${definition.name}" parameter "${unsupported.name}" uses unsupported mode "${unsupported.mode}"`);
+        }
+        if (args.length !== definition.params.length) {
+            throw new ValidationError(`routine "${definition.name}" expects ${definition.params.length} argument(s), received ${args.length}`, [
+                {
+                    path: 'input',
+                    message: `expected ${definition.params.length} argument(s), received ${args.length}`,
+                    expected: `tuple of length ${definition.params.length}`,
+                    value: args,
+                },
+            ]);
+        }
+        const seenNames = new Set();
+        const input = {};
+        const shape = definition.params.map((param, index) => {
+            if (seenNames.has(param.name)) {
+                throw new ValidationError(`routine "${definition.name}" declares parameter "${param.name}" more than once`);
+            }
+            seenNames.add(param.name);
+            input[param.name] = args[index];
+            return { column: routineColumn(param.name, param.type), optional: false };
+        });
+        // Binding protects the outer SQL call, but not dynamic SQL inside an opaque
+        // routine body. A routine may also run with definer rights, so every
+        // argument is validated before even compiling the privileged call.
+        const argumentIssues = issuesFor(input, objectTypeFromShape(shape));
+        if (argumentIssues.length > 0) {
+            throw new ValidationError(`validation failed: ${argumentIssues.map(issue => issue.path).join(', ')}`, argumentIssues);
+        }
+        const query = definition.kind === 'procedure'
+            ? this.qb.callProcedure(definition.name, args)
+            : definition.returns?.setof === true
+                ? this.qb.callTableFunction(definition.name, args)
+                : this.qb.callFunction(definition.name, args);
+        const rows = await this.driver.execute(query);
+        if (definition.kind === 'procedure' || definition.returns === undefined || definition.returns.type === 'void') {
+            return validatedRoutineValue(undefined, { kind: 'undefined' });
+        }
+        const column = routineColumn(definition.name, definition.returns.type);
+        const resultType = appTypeOf(column);
+        if (definition.returns.setof === true) {
+            const values = rows.map(row => decodeDbValue(column, row[definition.name]));
+            return validatedRoutineValue(values, { kind: 'array', element: resultType });
+        }
+        const value = decodeDbValue(column, rows[0]?.result);
+        return validatedRoutineValue(value, resultType);
+    }
+    get schema() {
+        // boundary: `this.constructor` is typed `Function`; there is no way to say
+        // "the static side of my own class". The subclass contract is
+        // `static readonly schema = …`, declared abstractly above.
+        return this.constructor.schema;
+    }
+    /**
+     * One relation, by name, resolved from the declaration.
+     *
+     * No assertion, which is the difference from the static `relations` map this replaced:
+     * `schema.ir.relations` is a field of the schema value every repository is handed, so
+     * there is nothing to claim about `this.constructor`. The resolution itself lives in
+     * `@zmdb/schema` because `compilePopulate` needs the same answer, and two resolvers
+     * over one declaration is how the join and the batched select came to disagree before.
+     */
+    relation(name) {
+        return resolveRelation(this.schema.ir, name);
+    }
+    get tableName() {
+        return this.schema.table;
+    }
+    sqlNamesForTable(table) {
+        return this.#sqlNamesByDeclaredTable.get(table) ?? this.#sqlNamesByPhysicalTable.get(table);
+    }
+    relationSqlNames(relation) {
+        return this.#sqlNamesByDeclaredTable.get(relation.targetTable);
+    }
+    physicalColumn(column, names = this.#rootSqlNames) {
+        const separator = column.lastIndexOf('.');
+        const property = separator === -1 ? column : column.slice(separator + 1);
+        const physical = names.columns.get(property);
+        if (physical === undefined)
+            return column;
+        if (separator === -1)
+            return physical;
+        const qualifier = column.slice(0, separator);
+        const physicalQualifier = qualifier === names.schema.ir.table || qualifier === names.schema.table ? names.schema.table : qualifier;
+        return `${physicalQualifier}.${physical}`;
+    }
+    aggregateColumn(column) {
+        const separator = column.indexOf('.');
+        if (separator === -1)
+            return this.physicalColumn(column);
+        const relationName = column.slice(0, separator);
+        const relation = this.schema.ir.relations.find(candidate => candidate.name === relationName);
+        if (relation === undefined)
+            return this.physicalColumn(column);
+        const target = this.#sqlNamesByDeclaredTable.get(relation.target);
+        return target === undefined ? column : this.physicalColumn(column, target);
+    }
+    aggregateSelection(column) {
+        const physical = this.aggregateColumn(column);
+        return physical === column ? column : `${physical} as ${column}`;
+    }
+    selectEntity(names = this.#rootSqlNames) {
+        const builder = this.qb.selectFrom(names.schema.table);
+        return names.entityProjection === undefined ? builder : builder.select(names.entityProjection);
+    }
+    selectProperties(properties, names = this.#rootSqlNames) {
+        const selected = [];
+        const seen = new Set();
+        for (const property of properties) {
+            if (seen.has(property))
+                continue;
+            seen.add(property);
+            const physical = this.physicalColumn(property, names);
+            selected.push(physical === property ? physical : { column: physical, alias: property });
+        }
+        return selected.length === 0 ? this.selectEntity(names) : this.qb.selectFrom(names.schema.table).select(selected);
+    }
+    entityReturning(names = this.#rootSqlNames) {
+        return names.entityProjection ?? ['*'];
+    }
+    physicalRecord(record, names = this.#rootSqlNames) {
+        const physical = {};
+        for (const [property, value] of Object.entries(record)) {
+            physical[this.physicalColumn(property, names)] = value;
+        }
+        return physical;
+    }
+    physicalFields(fields) {
+        if (fields === undefined)
+            return undefined;
+        return isUpdateFieldList(fields) ? fields.map(column => this.physicalColumn(column)) : this.physicalRecord(fields);
+    }
+    filterDefinitionsFor(table, schema) {
+        const definitions = this.#filterDefinitions.filter(filter => filter.table === table);
+        const softDelete = (schema === undefined ? this.sqlNamesForTable(table) : this.sqlNamesForTable(schema.table))?.ir.softDelete ??
+            schema?.ir.softDelete;
+        if (softDelete === undefined || definitions.some(filter => filter.name === 'softDelete')) {
+            return definitions;
+        }
+        return [
+            ...definitions,
+            {
+                name: 'softDelete',
+                table,
+                where: (_params) => [
+                    {
+                        col: softDelete.column,
+                        op: 'is null',
+                        value: undefined,
+                    },
+                ],
+            },
+        ];
+    }
+    knownFilterNames(definitions, additional = []) {
+        return [...new Set([...definitions.map(filter => filter.name), ...additional])];
+    }
+    rootFilterNames() {
+        return this.filterDefinitionsFor(this.tableName, this.schema).map(filter => filter.name);
+    }
+    allDeclaredFilterNames() {
+        return [...new Set([...this.rootFilterNames(), ...this.#filterDefinitions.map(filter => filter.name)])];
+    }
+    populatePlan(paths) {
+        const roots = [];
+        const nodes = new Map();
+        for (const path of paths ?? []) {
+            const parts = path.split('.');
+            if (parts.some(part => part.length === 0))
+                throw new ValidationError(`invalid populate path "${path}"`);
+            let source = this.schema.ir;
+            let parent;
+            for (const name of parts) {
+                const prefix = parent === undefined ? name : `${parent.path}.${name}`;
+                let node = nodes.get(prefix);
+                if (node === undefined) {
+                    const relation = resolveRelation(source, name);
+                    node = { path: prefix, relation, target: this.relationSqlNames(relation), children: [] };
+                    nodes.set(prefix, node);
+                    (parent?.children ?? roots).push(node);
+                }
+                if (parts.length > 1 && node.target === undefined) {
+                    throw new ValidationError(`populate path "${path}" requires the schema for "${node.relation.targetTable}" in RepositoryOptions.schemas`);
+                }
+                source = node.target?.ir ?? source;
+                parent = node;
+            }
+        }
+        return { roots, nodes: [...nodes.values()] };
+    }
+    populateFilterNames(names, plan = this.populatePlan(names)) {
+        const known = new Set(this.rootFilterNames());
+        for (const { relation, target } of plan.nodes) {
+            for (const filter of this.filterDefinitionsFor(target?.schema.table ?? relation.targetTable, target?.schema)) {
+                known.add(filter.name);
+            }
+        }
+        return [...known];
+    }
+    resolveReadFilters(method, options, table, schema, qualifyColumns, additionalKnownNames = [], columnPrefix = table) {
+        const definitions = this.filterDefinitionsFor(table, schema);
+        return resolveFilters(definitions, options?.filters, {
+            method,
+            table,
+            columnPrefix,
+            ...(schema === undefined ? {} : { schema }),
+            ...(qualifyColumns ? { qualifyColumns: true } : {}),
+            knownNames: this.knownFilterNames(definitions, additionalKnownNames),
+        });
+    }
+    /**
+     * The only place a repository read becomes a CompiledQuery.
+     *
+     * Filter parameters are resolved before `build` runs, the resolved predicates
+     * are conjoined unless a structurally richer builder already placed them, and
+     * the same point reports the final SQL plus the applied names.
+     */
+    compileRead(method, options, build, settings = {}) {
+        options?.signal?.throwIfAborted();
+        const table = settings.table ?? this.tableName;
+        const schema = settings.schema ?? (table === this.tableName ? this.schema : undefined);
+        const resolved = settings.resolvedFilters ??
+            this.resolveReadFilters(method, options, table, schema, settings.qualifyColumns === true, settings.additionalKnownNames, settings.columnPrefix);
+        const built = build(resolved);
+        const filtered = settings.filtersApplied === true ? built : applyResolvedFilters(built, resolved);
+        const query = filtered.compile();
+        const names = Object.freeze([...new Set([...resolved.names, ...(settings.additionalFilterNames ?? [])])]);
+        this.#queryFilters.set(query, names);
+        this.#onQuery?.(query, settings.buffered === true ? { filters: names, buffered: true } : { filters: names });
+        return query;
+    }
+    resolveWriteFilters(method, options, excludedFilterNames = []) {
+        const allDefinitions = this.filterDefinitionsFor(this.tableName, this.schema);
+        const excluded = new Set(excludedFilterNames);
+        const definitions = allDefinitions.filter(filter => filter.appliesToWrites !== false && !excluded.has(filter.name));
+        return resolveFilters(definitions, options?.filters, {
+            method,
+            table: this.tableName,
+            schema: this.schema,
+            knownNames: this.knownFilterNames(allDefinitions),
+        });
+    }
+    /**
+     * The only place a repository UPDATE or DELETE becomes a CompiledQuery.
+     *
+     * Write filters default on, are resolved before compilation, and are reported
+     * through the same query-observation hook as reads.
+     */
+    compileWrite(method, options, build, settings = {}) {
+        const resolved = this.resolveWriteFilters(method, options, settings.excludedFilterNames);
+        const query = applyResolvedFilters(build(resolved), resolved).compile();
+        this.#queryFilters.set(query, resolved.names);
+        this.#onQuery?.(query, { filters: resolved.names });
+        return query;
+    }
+    resolvePopulateFilters(names, options) {
+        const byRelation = new Map();
+        const byTable = new Map();
+        const plan = this.populatePlan(names);
+        const knownNames = this.populateFilterNames(names, plan);
+        for (const { path, relation, target } of plan.nodes) {
+            const targetTable = target?.schema.table ?? relation.targetTable;
+            let resolved = byTable.get(targetTable);
+            if (resolved === undefined) {
+                resolved = this.resolveReadFilters('populate', options, targetTable, target?.schema, true, knownNames);
+                byTable.set(targetTable, resolved);
+            }
+            byRelation.set(path, resolved);
+        }
+        return byRelation;
+    }
+    requiredKeyColumns() {
+        if (this.keyColumns.length === 0)
+            throw new Error(`schema ${this.tableName} has no primary key`);
+        return this.keyColumns;
+    }
+    /**
+     * The one row-shape trust boundary in this package (ARCHITECTURE §2.1).
+     *
+     * A driver or configured cache store hands back structurally opaque values;
+     * the compiled query and schema fingerprint decide their shape, so exactly one
+     * assertion re-types them for the caller. Every read method funnels through
+     * here instead of asserting at its own return statement.
+     */
+    async executeRead(query, signal) {
+        signal?.throwIfAborted();
+        const rows = await this.driver.execute(query, executeOptions(signal));
+        signal?.throwIfAborted();
+        return rows;
+    }
+    async rows(query, options) {
+        let value;
+        if (options?.cache === undefined || options.cache === false) {
+            value = this.decodeRows(await this.executeRead(query, options?.signal));
+        }
+        else {
+            value = await this.cachedRows(query, options.cache, options.signal);
+        }
+        // boundary: driver rows are proved by the compiled query; cache entries are stored
+        // only under the same query plus dialect and schema fingerprint. Both establish
+        // `Row` at this one boundary, without re-validating cache hits (§3d).
+        return this.trusted(value);
+    }
+    /**
+     * The repository's one row-shape assertion, shared by buffered and streamed
+     * reads. The compiler that produced the query establishes the public shape;
+     * drivers deliberately return opaque records.
+     */
+    trusted(value) {
+        // boundary: a compiled repository query establishes the row shape; Driver
+        // deliberately returns opaque records so third-party adapters stay structural.
+        return value;
+    }
+    async cachedRows(query, cache, signal) {
+        if (!Number.isFinite(cache.ttlMs) || cache.ttlMs <= 0) {
+            throw new RangeError('cache ttlMs must be a positive finite number');
+        }
+        signal?.throwIfAborted();
+        const store = (this.#cacheStore ??= memoryStore());
+        const filters = this.#queryFilters.get(query);
+        const key = resultCacheKey({
+            dialect: this.dialect,
+            schema: this.schema.ir,
+            table: this.tableName,
+            ...(filters === undefined ? {} : { filters }),
+            query,
+        });
+        let cached;
+        try {
+            cached = await store.get(key);
+        }
+        catch (error) {
+            this.reportCacheFailure(error);
+            return this.decodeRows(await this.executeRead(query, signal));
+        }
+        signal?.throwIfAborted();
+        if (cached !== undefined)
+            return copyCachedRows(cached);
+        const rows = this.decodeRows(await this.executeRead(query, signal));
+        try {
+            await store.set(key, copyCachedRows(rows), cache.ttlMs, cacheTags(this.tableName, cache.tags));
+        }
+        catch (error) {
+            this.reportCacheFailure(error);
+        }
+        signal?.throwIfAborted();
+        return rows;
+    }
+    async invalidateCache(options) {
+        const store = this.#cacheStore;
+        if (store === undefined)
+            return;
+        try {
+            await store.invalidateTags(cacheTags(this.tableName, options?.invalidateTags));
+        }
+        catch (error) {
+            this.reportCacheFailure(error);
+        }
+    }
+    reportCacheFailure(error) {
+        if (this.#cacheFailureReported)
+            return;
+        this.#cacheFailureReported = true;
+        console.warn('@zmdb/orm cache store failed; continuing on the database path', error);
+    }
+    /**
+     * The db→app crossing on the way out (plan D3).
+     *
+     * `Entity<T>` says a `timestamp` column is a `Date`, a `bigint` column is a `bigint`, and
+     * an extension vector is a number array. A driver may or may not agree: `pg` returns a
+     * `Date` for a `timestamptz`, a string for an `int8`, and pgvector's text form when its
+     * parser is absent; SQLite returns the `TEXT` it stored. So a raw row can disagree with
+     * the declared app type silently unless this boundary converts it.
+     *
+     * A schema without a `timestamp`, `bigint`, or extension vector skips the walk entirely
+     * rather than copying every row to no effect. Only `timestamp` and `bigint` need distinct
+     * JSON wire forms; vector decoding is specific to the db→app crossing.
+     */
+    decodeRows(rows) {
+        const columns = this.decodedColumns;
+        if (columns.length === 0 || rows.length === 0)
+            return rows;
+        return rows.map(row => this.decodeRow(row, columns));
+    }
+    decodeRow(row, columns) {
+        if (columns.length === 0)
+            return row;
+        const out = { ...row };
+        for (const column of columns) {
+            if (column.name in out)
+                out[column.name] = decodeDbValue(column, out[column.name]);
+        }
+        return out;
+    }
+    get decodedColumns() {
+        this.#decoded ??= dbDecodedColumns(this.#rootSqlNames.ir);
+        return this.#decoded;
+    }
+    keyValues(id, method) {
+        const keyColumns = this.requiredKeyColumns();
+        if (keyColumns.length === 1) {
+            const [keyColumn] = keyColumns;
+            if (!keyColumn) {
+                throw new Error(`schema ${this.tableName} has empty primary key column`);
+            }
+            if (!isScalarKey(id)) {
+                throw new ValidationError(`${this.tableName}.${method} requires the value of "${keyColumn}", not ${describeKey(id)}`);
+            }
+            return [id];
+        }
+        if (!isRecord(id) || id instanceof Date) {
+            throw new ValidationError(`${this.tableName}.${method} requires every key column; got ${describeKey(id)}, expected an object with (${keyColumns.join(', ')})`);
+        }
+        const missing = [];
+        for (const column of keyColumns) {
+            if (!Object.hasOwn(id, column) || id[column] === undefined)
+                missing.push(column);
+        }
+        if (missing.length > 0)
+            throw new IncompleteKeyError(this.tableName, method, missing);
+        return keyColumns.map(column => id[column]);
+    }
+    keyWhere(builder, id, method) {
+        const values = this.keyValues(id, method);
+        let keyed = builder;
+        for (let index = 0; index < this.physicalKeyColumns.length; index++) {
+            const column = this.physicalKeyColumns[index];
+            if (column !== undefined)
+                keyed = keyed.where(column, '=', values[index]);
+        }
+        return keyed;
+    }
+    /** Add the deterministic order required by dialects whose pagination grammar needs one. */
+    limitOne(builder) {
+        if (!this.dialectTraits.paginationRequiresOrder)
+            return builder.limit(1);
+        const fallback = this.schema.ir.columns[0]?.physicalName;
+        const order = this.physicalKeyColumns.length > 0 ? this.physicalKeyColumns : fallback === undefined ? [] : [fallback];
+        if (order.length === 0) {
+            throw new Error(`schema ${this.tableName} has no column available to order a first-row read`);
+        }
+        let ordered = builder;
+        for (const column of order)
+            ordered = ordered.orderBy(column, 'asc');
+        return ordered.limit(1);
+    }
+    /** Validate a typed key and return its values in schema declaration order. */
+    loaderKeyValues(id) {
+        return this.keyValues(id, 'findById');
+    }
+    [LOADER_ENTITY_KEY](id) {
+        return loaderKey(this.loaderKeyValues(id));
+    }
+    /**
+     * Find a primary-key batch through the repository's compiler, decoder and
+     * dialect parameter ceiling. Composite tuples use OR-of-AND groups; SQL's
+     * AND-before-OR precedence keeps every tuple boundary intact.
+     */
+    async [LOADER_ENTITY_BATCH](ids) {
+        const unique = sanitizeKeys(ids);
+        if (unique.length === 0)
+            return [];
+        const columns = this.requiredKeyColumns();
+        const parameterLimit = this.dialectTraits.paramLimit;
+        const chunkSize = Math.max(1, Math.floor(parameterLimit / columns.length));
+        const found = new Map();
+        const filters = this.resolveReadFilters('loader.load', undefined, this.tableName, this.schema, false);
+        for (const chunk of chunkArray(unique, chunkSize)) {
+            let builder = this.selectEntity();
+            if (columns.length === 1) {
+                const [column] = columns;
+                if (!column)
+                    throw new Error(`schema ${this.tableName} has empty primary key column`);
+                builder = builder.whereIn(this.physicalColumn(column), chunk);
+            }
+            else {
+                for (let tupleIndex = 0; tupleIndex < chunk.length; tupleIndex++) {
+                    const id = chunk[tupleIndex];
+                    if (id === undefined)
+                        continue;
+                    const values = this.loaderKeyValues(id);
+                    for (let columnIndex = 0; columnIndex < columns.length; columnIndex++) {
+                        const column = columns[columnIndex];
+                        if (!column)
+                            continue;
+                        const value = values[columnIndex];
+                        const physicalColumn = this.physicalColumn(column);
+                        if (tupleIndex === 0 && columnIndex === 0)
+                            builder = builder.where(physicalColumn, '=', value);
+                        else if (columnIndex === 0)
+                            builder = builder.orWhere(physicalColumn, '=', value);
+                        else
+                            builder = builder.andWhere(physicalColumn, '=', value);
+                    }
+                }
+            }
+            const query = this.compileRead('loader.load', undefined, () => builder, { resolvedFilters: filters });
+            const rows = await this.rows(query);
+            for (const row of rows) {
+                found.set(loaderKey(columns.map(column => row[column])), row);
+            }
+        }
+        return ids.map(id => found.get(this[LOADER_ENTITY_KEY](id)));
+    }
+    async findById(id, opts) {
+        const populateFilters = this.resolvePopulateFilters(opts?.populate, opts);
+        const query = this.compileRead('findById', opts, () => this.limitOne(this.keyWhere(this.selectEntity(), id, 'findById')), { additionalKnownNames: this.populateFilterNames(opts?.populate) });
+        return this.firstResult(query, opts, populateFilters);
+    }
+    /** The shared body of `findById` and `findOne`: first row for a where clause, relations attached if asked for. */
+    async firstMatching(where, options) {
+        const populateFilters = this.resolvePopulateFilters(options?.populate, options);
+        const query = this.compileRead('findOne', options, () => this.limitOne(compileWhere(this.selectEntity(), where, column => this.physicalColumn(column))), { additionalKnownNames: this.populateFilterNames(options?.populate) });
+        return this.firstResult(query, options, populateFilters);
+    }
+    async firstResult(query, options, populateFilters = new Map()) {
+        const rows = await this.rows(query, options);
+        const row = rows[0];
+        if (!row || !options?.populate?.length)
+            return row;
+        const [populated] = await this.attachRelations([row], options.populate, options, populateFilters);
+        return populated;
+    }
+    /** The children of every parent in parameter-bounded queries, grouped by the ordered target key. */
+    async childrenByParent(childTable, childKeys, parentKeys, options, filters, names = this.sqlNamesForTable(childTable)) {
+        options?.signal?.throwIfAborted();
+        if (childKeys.length === 0) {
+            throw new Error(`relation to ${childTable} resolved no target key columns`);
+        }
+        const unique = new Map();
+        for (const values of parentKeys) {
+            if (values.length !== childKeys.length) {
+                throw new Error(`relation to ${childTable} resolved ${String(childKeys.length)} target columns for ` +
+                    `${String(values.length)} parent values`);
+            }
+            if (!hasNullishKeyPart(values))
+                unique.set(loaderKey(values), values);
+        }
+        const ids = [...unique.values()];
+        if (ids.length === 0)
+            return new Map();
+        const limit = this.dialectTraits.paramLimit;
+        const chunks = chunkArray(ids, Math.max(1, Math.floor(limit / childKeys.length)));
+        const byParent = new Map();
+        const physicalTable = names?.schema.table ?? childTable;
+        const physicalKeys = names === undefined ? childKeys : childKeys.map(childKey => this.physicalColumn(childKey, names));
+        for (const chunk of chunks) {
+            let builder = names === undefined ? this.qb.selectFrom(physicalTable) : this.selectEntity(names);
+            if (physicalKeys.length === 1) {
+                const [physicalKey] = physicalKeys;
+                if (physicalKey === undefined)
+                    throw new Error(`relation to ${childTable} resolved an empty target key`);
+                builder = builder.whereIn(physicalKey, chunk.map(values => values[0]));
+            }
+            else {
+                const predicates = [];
+                for (let tupleIndex = 0; tupleIndex < chunk.length; tupleIndex++) {
+                    const values = chunk[tupleIndex];
+                    if (values === undefined)
+                        continue;
+                    for (let columnIndex = 0; columnIndex < physicalKeys.length; columnIndex++) {
+                        const physicalKey = physicalKeys[columnIndex];
+                        if (physicalKey === undefined)
+                            continue;
+                        predicates.push({
+                            col: physicalKey,
+                            op: '=',
+                            value: values[columnIndex],
+                            connector: tupleIndex > 0 && columnIndex === 0 ? 'OR' : 'AND',
+                        });
+                    }
+                }
+                builder = builder.whereGroup(predicates);
+            }
+            const query = this.compileRead('populate', options, () => builder, {
+                table: physicalTable,
+                ...(names === undefined ? {} : { schema: names.schema }),
+                qualifyColumns: true,
+                ...(filters === undefined ? {} : { resolvedFilters: filters }),
+            });
+            const res = await this.executeRead(query, options?.signal);
+            for (const child of res) {
+                const key = relationRowKey(child, childKeys);
+                if (key === undefined)
+                    continue;
+                const list = byParent.get(key);
+                if (list === undefined)
+                    byParent.set(key, [child]);
+                else
+                    list.push(child);
+            }
+        }
+        return byParent;
+    }
+    async attachRelations(parents, names, options, populateFilters = this.resolvePopulateFilters(names, options)) {
+        return this.populateRows(parents, this.populatePlan(names).roots, options, populateFilters);
+    }
+    async populateRows(parents, nodes, options, populateFilters) {
+        options?.signal?.throwIfAborted();
+        if (parents.length === 0)
+            return [];
+        const current = parents.map(parent => ({ ...parent }));
+        for (const node of nodes) {
+            const { relation: rel, target } = node;
+            const name = rel.name;
+            const byParent = await this.childrenByParent(target?.schema.table ?? rel.targetTable, rel.targetKey, current.map(parent => relationKeyValues(parent, rel.parentKey)), options, populateFilters.get(node.path), target);
+            if (node.children.length > 0) {
+                const children = [...byParent.values()].flat();
+                const populated = await this.populateRows(children, node.children, options, populateFilters);
+                let offset = 0;
+                for (const [key, group] of byParent) {
+                    byParent.set(key, populated.slice(offset, offset + group.length));
+                    offset += group.length;
+                }
+            }
+            const property = { configurable: true, enumerable: true, writable: true };
+            current.forEach(parent => {
+                const key = relationRowKey(parent, rel.parentKey);
+                if (key === undefined) {
+                    property.value = rel.toMany ? [] : null;
+                }
+                else {
+                    const list = byParent.get(key) ?? [];
+                    if (rel.toMany) {
+                        property.value = list.map(child => copyPopulatedRow(child, node.children));
+                    }
+                    else {
+                        const first = list[0];
+                        property.value = first ? copyPopulatedRow(first, node.children) : null;
+                    }
+                }
+                Object.defineProperty(parent, name, property);
+            });
+        }
+        return current;
+    }
+    async populate(rowOrRows, paths, options) {
+        options?.signal?.throwIfAborted();
+        const rows = Array.isArray(rowOrRows) ? rowOrRows : [rowOrRows];
+        const populated = await this.attachRelations(rows, paths, options);
+        return Array.isArray(rowOrRows) ? populated : (populated[0] ?? { ...rowOrRows });
+    }
+    [LOADER_RELATION_KEY](parent, relation) {
+        const resolved = this.relation(relation);
+        return loaderKey(relationKeyValues(parent, resolved.parentKey));
+    }
+    async [LOADER_RELATION_BATCH](parents, relation) {
+        const filters = this.resolvePopulateFilters([relation], undefined);
+        const populated = await this.attachRelations(parents, [relation], undefined, filters);
+        return populated.map(parent => parent[relation]);
+    }
+    async findOne(where, opts) {
+        return this.firstMatching(where, opts);
+    }
+    async find(where, opts) {
+        const populateFilters = this.resolvePopulateFilters(opts?.populate, opts);
+        const query = this.compileRead('find', opts, () => compileWhere(this.selectEntity(), where, column => this.physicalColumn(column)), {
+            additionalKnownNames: this.populateFilterNames(opts?.populate),
+        });
+        const rows = await this.rows(query, opts);
+        if (!opts?.populate?.length)
+            return rows;
+        return this.attachRelations(rows, opts.populate, opts, populateFilters);
+    }
+    async findAll(opts) {
+        const populateFilters = this.resolvePopulateFilters(opts?.populate, opts);
+        const query = this.compileRead('findAll', opts, () => this.selectEntity(), {
+            additionalKnownNames: this.populateFilterNames(opts?.populate),
+        });
+        const rows = await this.rows(query, opts);
+        if (!opts?.populate?.length)
+            return rows;
+        return this.attachRelations(rows, opts.populate, opts, populateFilters);
+    }
+    async count(where, options) {
+        const query = this.compileRead('count', options, () => {
+            let builder = aggregateSelectFrom(this.tableName, this.dialect, this.driver.queryTelemetry === true ? { telemetry: true } : undefined).count('*', 'count');
+            if (where !== undefined)
+                builder = compileWhere(builder, where, column => this.physicalColumn(column));
+            return builder;
+        });
+        const rows = await this.executeRead(query, options?.signal);
+        const value = rows[0]?.['count'];
+        if (value === undefined)
+            return 0;
+        if (typeof value === 'number')
+            return value;
+        if (typeof value === 'bigint' || typeof value === 'string') {
+            const count = Number(value);
+            if (Number.isSafeInteger(count))
+                return count;
+        }
+        throw new ValidationError(`count for \`${this.tableName}\` was not a safe integer`);
+    }
+    async exists(where, options) {
+        const firstColumn = this.physicalKeyColumns[0] ?? this.schema.ir.columns[0]?.physicalName;
+        if (firstColumn === undefined)
+            throw new Error(`schema ${this.tableName} has no column to test for existence`);
+        const query = this.compileRead('exists', options, () => {
+            let builder = this.qb.selectFrom(this.tableName).select([firstColumn]);
+            if (where !== undefined)
+                builder = compileWhere(builder, where, column => this.physicalColumn(column));
+            return this.limitOne(builder);
+        });
+        return (await this.executeRead(query, options?.signal)).length > 0;
+    }
+    async list(query, opts) {
+        const populateFilters = this.resolvePopulateFilters(opts?.populate, opts);
+        const keyColumns = this.requiredKeyColumns();
+        const userOrderBy = query?.orderBy;
+        const effectiveOrderBy = userOrderBy ? [...userOrderBy] : [];
+        for (const column of keyColumns) {
+            if (!effectiveOrderBy.some(item => String(item.column) === column)) {
+                effectiveOrderBy.push({ column, dir: 'asc' });
+            }
+        }
+        const page = query?.page;
+        const limit = page && 'limit' in page ? page.limit : undefined;
+        const keyset = page && 'after' in page && page.after !== undefined && page.after !== null;
+        let cursorValues;
+        if (keyset) {
+            if (typeof page.after === 'string') {
+                cursorValues = decodeCursor(page.after);
+            }
+            else if (typeof page.after === 'object' && !Array.isArray(page.after)) {
+                // boundary: page.after is an untrusted client DTO parameter; runtime check above proves it is a non-null, non-array object.
+                cursorValues = page.after;
+            }
+            else {
+                throw new Error('Invalid cursor parameter: expected string or object');
+            }
+        }
+        const compiled = this.compileRead('list', opts, filters => {
+            const selectedProperties = query?.select === undefined
+                ? undefined
+                : [...query.select.map(String), ...effectiveOrderBy.map(item => String(item.column))];
+            let builder = applyOrderBy(selectedProperties === undefined ? this.selectEntity() : this.selectProperties(selectedProperties), effectiveOrderBy, undefined, column => this.physicalColumn(column));
+            if (keyset && cursorValues !== undefined) {
+                builder = applyKeysetFilter(builder, cursorValues, effectiveOrderBy, query?.where, branch => {
+                    applyResolvedFilters(branch, filters);
+                }, column => this.physicalColumn(column));
+                if (limit !== undefined)
+                    builder = builder.limit(limit + 1);
+                return builder;
+            }
+            if (query?.where)
+                builder = compileWhere(builder, query.where, column => this.physicalColumn(column));
+            if (page) {
+                builder = applyPagination(builder, {
+                    limit: limit !== undefined ? limit + 1 : page.limit,
+                    offset: 'offset' in page ? page.offset : undefined,
+                });
+            }
+            return builder;
+        }, {
+            filtersApplied: keyset === true,
+            additionalKnownNames: this.populateFilterNames(opts?.populate),
+        });
+        const rows = await this.rows(compiled, opts);
+        const listOpts = {
+            ...(limit !== undefined ? { limit } : {}),
+            ...(query?.select ? { select: query.select } : {}),
+            orderBy: effectiveOrderBy,
+        };
+        const res = buildListResult(rows, listOpts);
+        if (opts?.populate?.length) {
+            const populatedItems = await this.attachRelations(res.items, opts.populate, opts, populateFilters);
+            return { ...res, items: populatedItems };
+        }
+        return res;
+    }
+    stream(where, options) {
+        options?.signal?.throwIfAborted();
+        if (options?.batchSize !== undefined && (!Number.isInteger(options.batchSize) || options.batchSize <= 0)) {
+            throw new RangeError('batchSize must be a positive integer');
+        }
+        const driverStream = typeof this.driver.stream === 'function' ? this.driver.stream : undefined;
+        const reportBuffered = driverStream === undefined &&
+            options?.requireCursor !== true &&
+            this.#onQuery !== undefined &&
+            !BUFFERED_STREAM_REPORTED.has(this.driver);
+        if (reportBuffered)
+            BUFFERED_STREAM_REPORTED.add(this.driver);
+        const query = this.compileRead('stream', options, () => where === undefined
+            ? this.selectEntity()
+            : compileWhere(this.selectEntity(), where, column => this.physicalColumn(column)), reportBuffered ? { buffered: true } : {});
+        // Resolve the schema-derived decoder once before iteration; the mapper then
+        // performs only the per-row conversions that ordinary reads use.
+        const columns = this.decodedColumns;
+        const signal = options?.signal;
+        const open = driverStream === undefined
+            ? () => {
+                if (options?.requireCursor === true) {
+                    const ctor = Reflect.get(this.driver, 'constructor');
+                    const name = typeof ctor === 'function' && ctor.name.length > 0 ? ctor.name : 'Driver';
+                    throw new Error(`${name} does not implement stream; pass requireCursor: false to allow buffering`);
+                }
+                const execute = this.executeRead.bind(this);
+                return {
+                    async *[Symbol.asyncIterator]() {
+                        for (const row of await execute(query, signal))
+                            yield row;
+                    },
+                };
+            }
+            : () => driverStream.call(this.driver, query, executeOptions(signal, options?.batchSize ?? 100));
+        return createRepositoryStream(open, row => this.trusted(this.decodeRow(row, columns)), signal);
+    }
+    // #96 — full-text search integration. Uses the query-compiler FTS builder.
+    // SQLite compiles FTS5 virtual table JOINs when ftsTable is declared on the
+    // schema; querying plain SQLite columns without a declared virtual table
+    // throws UnsupportedFeatureError (never a silently-wrong query).
+    async findByFullText(column, term, options) {
+        const ftsTable = this.schema.ftsTable;
+        const query = this.compileRead('findByFullText', options, () => ftsSelectFrom(this.tableName, this.dialect, this.driver.queryTelemetry === true ? { ftsTable, telemetry: true } : { ftsTable }).whereMatch(this.physicalColumn(column), term));
+        return this.executeRead(query, options?.signal);
+    }
+    async findJoined(join, where, options) {
+        const targetTable = typeof join.target === 'string' ? join.target : join.target.table;
+        const targetSpec = parseTableSpec(targetTable);
+        const targetSchema = typeof join.target === 'string' ? undefined : join.target;
+        const targetDefinitions = this.filterDefinitionsFor(targetSpec.table, targetSchema);
+        const targetFilters = this.resolveReadFilters('findJoined', options, targetSpec.table, targetSchema, true, this.rootFilterNames(), targetSpec.reference);
+        const query = this.compileRead('findJoined', options, () => {
+            let builder = joinableSelectFrom(this.tableName, this.dialect, this.driver.queryTelemetry === true ? { telemetry: true } : undefined);
+            const predicates = filtersAsPredicates(targetFilters);
+            const leftCol = this.physicalColumn(join.leftCol);
+            const rightCol = targetSchema === undefined ? join.rightCol : this.physicalColumn(join.rightCol, schemaSqlNames(targetSchema));
+            builder =
+                join.kind === 'inner'
+                    ? builder.innerJoin(targetTable, leftCol, rightCol, predicates)
+                    : builder.leftJoin(targetTable, leftCol, rightCol, predicates);
+            if (where)
+                builder = builder.where(this.aggregateColumn(where.col), where.op, where.value);
+            return builder;
+        }, {
+            additionalFilterNames: targetFilters.names,
+            additionalKnownNames: targetDefinitions.map(filter => filter.name),
+        });
+        return this.executeRead(query, options?.signal);
+    }
+    /**
+     * A relation as a join: the target table, aliased to the relation name, and its ordered column pairs.
+     *
+     * One expression for both directions, where the map-driven version needed a branch per
+     * cardinality — the two spellings put the joining column under a different key depending
+     * on which side owned it (`fk` on the owning side, `mappedBy` on the inverse), and each
+     * arm then had a fallback that guessed a column name from the table name. `parentKey` and
+     * `targetKey` are already the answer to "which column on which side", so there is nothing
+     * left to guess and no default to be wrong about.
+     */
+    resolveRelationJoin(relationName) {
+        const rel = this.relation(relationName);
+        const target = this.relationSqlNames(rel);
+        const alias = relationName.trim();
+        const physicalTargetTable = target?.schema.table ?? rel.targetTable;
+        const targetTable = physicalTargetTable.toLowerCase() === alias.toLowerCase()
+            ? physicalTargetTable
+            : `${physicalTargetTable} as ${alias}`;
+        return {
+            targetTable,
+            filterTable: physicalTargetTable,
+            targetReference: alias,
+            conditions: rel.parentKey.map((parentKey, index) => {
+                const targetKey = rel.targetKey[index];
+                if (targetKey === undefined) {
+                    throw new Error(`${this.tableName}.${relationName}: resolved relation keys have different lengths`);
+                }
+                return {
+                    leftCol: `${this.tableName}.${this.physicalColumn(parentKey)}`,
+                    rightCol: `${alias}.${target === undefined ? targetKey : this.physicalColumn(targetKey, target)}`,
+                };
+            }),
+        };
+    }
+    filteredRelationJoin(relationName, options) {
+        const join = this.resolveRelationJoin(relationName);
+        const definitions = this.filterDefinitionsFor(join.filterTable);
+        const targetSchema = this.sqlNamesForTable(join.filterTable)?.schema;
+        const filters = this.resolveReadFilters('aggregate', options, join.filterTable, targetSchema, true, this.allDeclaredFilterNames(), join.targetReference);
+        return { ...join, filters, knownNames: definitions.map(filter => filter.name) };
+    }
+    createRepositoryAggregateBuilder(options, targetFilterNames, targetKnownNames) {
+        let builder = aggregateSelectFrom(this.tableName, this.dialect, this.driver.queryTelemetry === true ? { telemetry: true } : undefined);
+        const resolveRelationJoin = (relationName) => this.filteredRelationJoin(relationName, options);
+        const resolveTableJoin = (targetTable) => {
+            const target = parseTableSpec(targetTable);
+            const definitions = this.filterDefinitionsFor(target.table);
+            const filters = this.resolveReadFilters('aggregate', options, target.table, undefined, true, this.allDeclaredFilterNames(), target.reference);
+            return { filters, knownNames: definitions.map(filter => filter.name) };
+        };
+        const wrap = (b) => {
+            builder = b;
+            const target = Object.assign(builder, {
+                joinRelation(relationName, kind = 'inner') {
+                    const { targetTable, conditions, filters, knownNames } = resolveRelationJoin(relationName);
+                    for (const name of filters.names)
+                        targetFilterNames.add(name);
+                    for (const name of knownNames)
+                        targetKnownNames.add(name);
+                    let nextB = builder;
+                    const predicates = filtersAsPredicates(filters);
+                    if (kind === 'left')
+                        nextB = builder.leftJoin(targetTable, conditions, predicates);
+                    else if (kind === 'right')
+                        nextB = builder.rightJoin(targetTable, conditions, predicates);
+                    else
+                        nextB = builder.innerJoin(targetTable, conditions, predicates);
+                    return wrap(nextB);
+                },
+            });
+            return new Proxy(target, {
+                get: (t, prop, receiver) => {
+                    if (prop === 'joinRelation') {
+                        return t.joinRelation;
+                    }
+                    if (prop === 'innerJoin' || prop === 'leftJoin' || prop === 'rightJoin') {
+                        return (targetTable, leftColOrConditions, rightColOrOn, scalarOn) => {
+                            const { filters, knownNames } = resolveTableJoin(targetTable);
+                            for (const name of filters.names)
+                                targetFilterNames.add(name);
+                            for (const name of knownNames)
+                                targetKnownNames.add(name);
+                            const on = typeof leftColOrConditions === 'string' ? scalarOn : rightColOrOn;
+                            if (on !== undefined && typeof on === 'string') {
+                                throw new TypeError(`join "${targetTable}" received an invalid ON predicate list`);
+                            }
+                            const predicates = [...(on ?? []), ...filtersAsPredicates(filters)];
+                            let joined;
+                            if (typeof leftColOrConditions === 'string') {
+                                if (typeof rightColOrOn !== 'string') {
+                                    throw new TypeError(`join "${targetTable}" needs a right-hand column`);
+                                }
+                                if (prop === 'leftJoin') {
+                                    joined = builder.leftJoin(targetTable, leftColOrConditions, rightColOrOn, predicates);
+                                }
+                                else if (prop === 'rightJoin') {
+                                    joined = builder.rightJoin(targetTable, leftColOrConditions, rightColOrOn, predicates);
+                                }
+                                else {
+                                    joined = builder.innerJoin(targetTable, leftColOrConditions, rightColOrOn, predicates);
+                                }
+                            }
+                            else if (prop === 'leftJoin') {
+                                joined = builder.leftJoin(targetTable, leftColOrConditions, predicates);
+                            }
+                            else if (prop === 'rightJoin') {
+                                joined = builder.rightJoin(targetTable, leftColOrConditions, predicates);
+                            }
+                            else {
+                                joined = builder.innerJoin(targetTable, leftColOrConditions, predicates);
+                            }
+                            return wrap(joined);
+                        };
+                    }
+                    const val = Reflect.get(t, prop, receiver);
+                    if (typeof val === 'function') {
+                        return (...args) => {
+                            let resolvedArgs = args;
+                            if (prop === 'select' && Array.isArray(args[0])) {
+                                resolvedArgs = [
+                                    args[0].map(column => (typeof column === 'string' ? this.aggregateSelection(column) : column)),
+                                ];
+                            }
+                            else if ((prop === 'count' || prop === 'sum' || prop === 'avg' || prop === 'min' || prop === 'max') &&
+                                typeof args[0] === 'string' &&
+                                args[0] !== '*') {
+                                resolvedArgs = [this.aggregateColumn(args[0]), ...args.slice(1)];
+                            }
+                            else if (prop === 'groupBy') {
+                                resolvedArgs = args.map(arg => (typeof arg === 'string' ? this.aggregateColumn(arg) : arg));
+                            }
+                            else if ((prop === 'where' || prop === 'having' || prop === 'orderBy') && typeof args[0] === 'string') {
+                                resolvedArgs = [this.aggregateColumn(args[0]), ...args.slice(1)];
+                            }
+                            const res = val.apply(t, resolvedArgs);
+                            if (res &&
+                                typeof res === 'object' &&
+                                'compile' in res &&
+                                typeof res.compile === 'function' &&
+                                'select' in res &&
+                                typeof res.select === 'function') {
+                                return wrap(res);
+                            }
+                            return res;
+                        };
+                    }
+                    return val;
+                },
+            });
+        };
+        return wrap(builder);
+    }
+    // #92 & relation-aware aggregations. Runs a grouped aggregate (count/sum/…)
+    // returning typed computed columns or relation-aware flat output fields.
+    async aggregate(specOrBuild, options) {
+        let q;
+        const targetFilterNames = new Set();
+        const targetKnownNames = new Set();
+        if (typeof specOrBuild === 'function') {
+            const builder = this.createRepositoryAggregateBuilder(options, targetFilterNames, targetKnownNames);
+            const res = specOrBuild(builder);
+            q = this.compileRead('aggregate', options, () => res ?? builder, {
+                additionalFilterNames: [...targetFilterNames],
+                additionalKnownNames: [...targetKnownNames],
+            });
+        }
+        else if (typeof specOrBuild === 'object' && specOrBuild !== null) {
+            const spec = specOrBuild;
+            let builder = aggregateSelectFrom(this.tableName, this.dialect, this.driver.queryTelemetry === true ? { telemetry: true } : undefined);
+            const joinedRelations = new Set();
+            const applyJoin = (relName, kind = 'inner') => {
+                if (joinedRelations.has(relName))
+                    return;
+                joinedRelations.add(relName);
+                const { targetTable, conditions, filters, knownNames } = this.filteredRelationJoin(relName, options);
+                for (const name of filters.names)
+                    targetFilterNames.add(name);
+                for (const name of knownNames)
+                    targetKnownNames.add(name);
+                const predicates = filtersAsPredicates(filters);
+                if (kind === 'left')
+                    builder = builder.leftJoin(targetTable, conditions, predicates);
+                else if (kind === 'right')
+                    builder = builder.rightJoin(targetTable, conditions, predicates);
+                else
+                    builder = builder.innerJoin(targetTable, conditions, predicates);
+            };
+            if (spec.joins) {
+                for (const item of spec.joins) {
+                    if (typeof item === 'string') {
+                        applyJoin(item);
+                    }
+                    else if (item && typeof item === 'object') {
+                        applyJoin(item.relation, item.kind);
+                    }
+                }
+            }
+            const relationNames = new Set(this.schema.ir.relations.map(rel => rel.name));
+            const candidateCols = [];
+            if (spec.groupBy)
+                candidateCols.push(...spec.groupBy.map(String));
+            if (spec.computed) {
+                for (const comp of Object.values(spec.computed)) {
+                    if (comp.column)
+                        candidateCols.push(String(comp.column));
+                }
+            }
+            if (spec.where) {
+                candidateCols.push(...Object.keys(spec.where));
+            }
+            for (const col of candidateCols) {
+                if (col.includes('.')) {
+                    const parts = col.split('.');
+                    const relCandidate = parts[0];
+                    if (relCandidate && relationNames.has(relCandidate)) {
+                        applyJoin(relCandidate);
+                    }
+                }
+            }
+            if (spec.groupBy && spec.groupBy.length > 0) {
+                const groupBy = spec.groupBy.map(column => this.aggregateColumn(String(column)));
+                builder = builder
+                    .select(spec.groupBy.map(column => this.aggregateSelection(String(column))))
+                    .groupBy(...groupBy);
+            }
+            if (spec.computed) {
+                for (const [alias, comp] of Object.entries(spec.computed)) {
+                    if (comp.raw) {
+                        builder = builder.expr(comp.raw, alias);
+                    }
+                    else {
+                        const fnLower = comp.fn.toLowerCase();
+                        const col = comp.column ? this.aggregateColumn(String(comp.column)) : '*';
+                        if (fnLower === 'count')
+                            builder = builder.count(col, alias);
+                        else if (fnLower === 'sum')
+                            builder = builder.sum(col, alias);
+                        else if (fnLower === 'avg')
+                            builder = builder.avg(col, alias);
+                        else if (fnLower === 'min')
+                            builder = builder.min(col, alias);
+                        else if (fnLower === 'max')
+                            builder = builder.max(col, alias);
+                    }
+                }
+            }
+            if (spec.where) {
+                for (const [col, val] of Object.entries(spec.where)) {
+                    const physicalColumn = this.aggregateColumn(col);
+                    if (val !== undefined && val !== null && typeof val === 'object' && !Array.isArray(val)) {
+                        for (const [op, opVal] of Object.entries(val)) {
+                            builder = builder.where(physicalColumn, op === 'eq' ? '=' : op, opVal);
+                        }
+                    }
+                    else {
+                        builder = builder.where(physicalColumn, '=', val);
+                    }
+                }
+            }
+            if (spec.having) {
+                builder = builder.having(this.aggregateColumn(String(spec.having.column)), spec.having.op, spec.having.value);
+            }
+            if (spec.orderBy) {
+                for (const item of spec.orderBy) {
+                    builder = builder.orderBy(this.aggregateColumn(String(item.column)), item.dir ?? 'asc');
+                }
+            }
+            if (spec.limit !== undefined)
+                builder = builder.limit(spec.limit);
+            if (spec.offset !== undefined)
+                builder = builder.offset(spec.offset);
+            q = this.compileRead('aggregate', options, () => builder, {
+                additionalFilterNames: [...targetFilterNames],
+                additionalKnownNames: [...targetKnownNames],
+            });
+        }
+        else {
+            throw new Error('aggregate requires a builder callback or AggregateSpec object');
+        }
+        const rawRows = await this.executeRead(q, options?.signal);
+        const mappedRows = rawRows.map(row => {
+            const out = { ...row };
+            for (const [k, v] of Object.entries(row)) {
+                if (k.includes('.')) {
+                    const flatKey = k.replace('.', '_');
+                    if (!(flatKey in out)) {
+                        out[flatKey] = v;
+                    }
+                }
+                else if (k.includes('_')) {
+                    const dotKey = k.replace('_', '.');
+                    if (!(dotKey in out)) {
+                        out[dotKey] = v;
+                    }
+                }
+            }
+            return out;
+        });
+        // boundary: the same claim `rows<Row>` makes, and for the same reason — the aggregate
+        // query that just ran is what decides the shape, and a driver row is opaque. It does not
+        // go through `rows` because an aggregate row is not an entity row: `decodeRows` would
+        // walk it looking for this table's `timestamp`, `bigint`, and extension vector columns,
+        // and `COUNT(*)` is not one of them.
+        return mappedRows;
+    }
+    async findAllWithMany(relationName, childTableOrOptions, childFk, parentKey = 'id', explicitOptions) {
+        const childTable = typeof childTableOrOptions === 'string' ? childTableOrOptions : undefined;
+        const options = typeof childTableOrOptions === 'string' ? explicitOptions : childTableOrOptions;
+        const knownNames = childTable === undefined
+            ? this.populateFilterNames([relationName])
+            : [
+                ...new Set([
+                    ...this.rootFilterNames(),
+                    ...this.filterDefinitionsFor(childTable).map(filter => filter.name),
+                ]),
+            ];
+        const relationFilters = !childTable || !childFk
+            ? this.resolvePopulateFilters([relationName], options)
+            : new Map([
+                [relationName, this.resolveReadFilters('populate', options, childTable, undefined, true, knownNames)],
+            ]);
+        const parentQuery = this.compileRead('findAllWithMany', options, () => this.selectEntity(), {
+            additionalKnownNames: knownNames,
+        });
+        const fetched = await this.rows(parentQuery, options);
+        if (fetched.length === 0)
+            return fetched;
+        // Without an explicit child table/FK the relation has to be looked up, which
+        // is what attachRelations does; with one, the caller has already told us
+        // everything the batched fetch needs.
+        if (!childTable || !childFk)
+            return this.attachRelations(fetched, [relationName], options, relationFilters);
+        const byParent = await this.childrenByParent(childTable, [childFk], fetched.map(p => [p[parentKey]]), options, relationFilters.get(relationName));
+        return fetched.map(p => ({
+            ...p,
+            [relationName]: byParent.get(loaderKey([p[parentKey]])) ?? [],
+        }));
+    }
+    // #207 — typed writes. Create keeps the derived CreateDTO; update accepts the
+    // expression-aware UpdatePatch and validates its plain values and operands
+    // separately before SQL.
+    async create(dto, options) {
+        const clean = this.validatePayload(dto, 'create');
+        this.preInsert(clean);
+        const physical = this.physicalRecord(clean);
+        const rows = await this.rows(this.qb.insertInto(this.tableName).values(physical).returning(this.entityReturning()).compile());
+        await this.invalidateCache(options);
+        const row = rows[0];
+        if (!row)
+            throw new Error(`insert into ${this.tableName} returned no row`);
+        this.postInsert(row);
+        return row;
+    }
+    async upsert(dto, opts) {
+        const clean = this.validatePayload(dto, 'create');
+        this.preInsert(clean);
+        const target = opts?.target ?? this.requiredKeyColumns();
+        const requestedUpdateFields = opts?.updateFields;
+        const updateFields = requestedUpdateFields !== undefined && !isUpdateFieldList(requestedUpdateFields)
+            ? this.validateUpdatePatch(requestedUpdateFields)
+            : requestedUpdateFields;
+        const resolvedUpdateFields = this.softDeleteUpsertFields(clean, target, updateFields);
+        const physicalTarget = typeof target === 'string' ? this.physicalColumn(target) : target.map(column => this.physicalColumn(column));
+        const physicalUpdateFields = this.physicalFields(resolvedUpdateFields);
+        const ib = this.qb
+            .insertInto(this.tableName)
+            .values(this.physicalRecord(clean))
+            .onConflict(physicalTarget)
+            .doUpdate(physicalUpdateFields);
+        if (!this.dialectCapabilities.returning.upsert &&
+            physicalUpdateFields !== undefined &&
+            !isUpdateFieldList(physicalUpdateFields) &&
+            this.hasColumnExpression(physicalUpdateFields)) {
+            await this.driver.execute(ib.compile());
+            await this.invalidateCache(opts);
+            return undefined;
+        }
+        const rows = await this.rows(ib.returning(this.entityReturning()).compile());
+        await this.invalidateCache(opts);
+        const row = rows[0];
+        if (!row) {
+            return undefined;
+        }
+        this.postInsert(row);
+        return row;
+    }
+    async update(id, patch, options) {
+        return this.updateOne(id, patch, options);
+    }
+    async updateMany(where, patch, options) {
+        const clean = this.validateUpdatePatch(patch);
+        this.preUpdate(clean);
+        if (Object.keys(clean).length === 0) {
+            this.resolveWriteFilters('updateMany', options);
+            return 0;
+        }
+        const physical = this.physicalRecord(clean);
+        const build = () => compileWhere(this.qb.updateTable(this.tableName).set(physical), where, column => this.physicalColumn(column));
+        if (!this.dialectCapabilities.returning.update) {
+            await this.driver.execute(this.compileWrite('updateMany', options, build));
+            await this.invalidateCache(options);
+            return undefined;
+        }
+        const returning = this.physicalKeyColumns.length > 0 ? this.physicalKeyColumns : ['*'];
+        const updated = (await this.driver.execute(this.compileWrite('updateMany', options, () => build().returning(returning)))).length;
+        await this.invalidateCache(options);
+        return updated;
+    }
+    async increment(id, column, by, options) {
+        const irColumn = this.payloadShape('update').columns.get(column);
+        if (irColumn === undefined ||
+            irColumn.payload !== undefined ||
+            (irColumn.sql !== 'integer' && irColumn.sql !== 'bigint' && irColumn.sql !== 'numeric')) {
+            throw new ValidationError(`"${column}" is not an updatable numeric column of "${this.tableName}"`, [
+                {
+                    path: `input.${column}`,
+                    message: 'expected an updatable numeric column',
+                    expected: 'integer, bigint, or numeric column',
+                    value: column,
+                },
+            ]);
+        }
+        const operand = by ?? (irColumn.sql === 'bigint' ? 1n : 1);
+        return this.updateOne(id, { [column]: inc(operand) }, options);
+    }
+    async updateOne(id, patch, options) {
+        const clean = this.validateUpdatePatch(patch);
+        this.preUpdate(clean);
+        // Built before the empty-patch shortcut so that a bad key is reported as `update` rather
+        // than as the `findById` it would otherwise delegate to (§2.1: "the method in the message
+        // is the method the caller actually called").
+        if (Object.keys(clean).length === 0) {
+            const query = this.compileWrite('update', options, () => this.limitOne(this.keyWhere(this.selectEntity(), id, 'update')));
+            return this.firstResult(query);
+        }
+        const physical = this.physicalRecord(clean);
+        const build = () => this.keyWhere(this.qb.updateTable(this.tableName).set(physical), id, 'update');
+        if (!this.dialectCapabilities.returning.update && this.hasColumnExpression(physical)) {
+            await this.driver.execute(this.assertKeyed(this.compileWrite('update', options, build), 'update'));
+            await this.invalidateCache(options);
+            return undefined;
+        }
+        const rows = await this.rows(this.assertKeyed(this.compileWrite('update', options, () => build().returning(this.entityReturning())), 'update'));
+        await this.invalidateCache(options);
+        return rows[0];
+    }
+    /**
+     * Refuse a keyed write that lost its `WHERE`.
+     *
+     * `update` and `delete` build the where clause themselves out of a primary key, so
+     * neither has a legitimate unkeyed form and an empty clause is always a bug. The
+     * check is here rather than only in the layers that can produce one because the cost
+     * of being wrong is the whole table, and it survives a new operator, a new caller, or
+     * a fourth way of folding a spec down to nothing (#608).
+     */
+    assertKeyed(query, operation) {
+        if (!/\sWHERE\s/i.test(query.text)) {
+            throw new ValidationError(`refusing to ${operation} every row of ${this.tableName}: the compiled statement has no WHERE clause`);
+        }
+        return query;
+    }
+    // #28 — delete + lifecycle hooks.
+    async delete(id, options) {
+        this.preDelete(id);
+        const softDelete = this.schema.ir.softDelete;
+        const build = softDelete === undefined
+            ? () => this.keyWhere(this.qb.deleteFrom(this.tableName), id, 'delete')
+            : () => this.keyWhere(this.qb.updateTable(this.tableName).set({ [this.physicalColumn(softDelete.column)]: new Date() }), id, 'delete');
+        const statement = softDelete === undefined ? 'delete' : 'update';
+        const query = !this.dialectCapabilities.returning[statement]
+            ? this.compileWrite('delete', options, build)
+            : this.compileWrite('delete', options, () => build().returning(this.physicalKeyColumns));
+        const rows = await this.driver.execute(this.assertKeyed(query, 'delete'));
+        await this.invalidateCache(options);
+        return this.writeMatched(rows, statement);
+    }
+    async deleteMany(where, options) {
+        const softDelete = this.schema.ir.softDelete;
+        const build = softDelete === undefined
+            ? () => compileWhere(this.qb.deleteFrom(this.tableName), where, column => this.physicalColumn(column))
+            : () => compileWhere(this.qb.updateTable(this.tableName).set({ [this.physicalColumn(softDelete.column)]: new Date() }), where, column => this.physicalColumn(column));
+        const statement = softDelete === undefined ? 'delete' : 'update';
+        if (!this.dialectCapabilities.returning[statement]) {
+            await this.driver.execute(this.compileWrite('deleteMany', options, build));
+            await this.invalidateCache(options);
+            return undefined;
+        }
+        const returning = this.physicalKeyColumns.length > 0 ? this.physicalKeyColumns : ['*'];
+        const affected = (await this.driver.execute(this.compileWrite('deleteMany', options, () => build().returning(returning)))).length;
+        await this.invalidateCache(options);
+        return affected;
+    }
+    async hardDelete(id, options) {
+        this.preDelete(id);
+        const build = () => this.keyWhere(this.qb.deleteFrom(this.tableName), id, 'hardDelete');
+        const query = !this.dialectCapabilities.returning.delete
+            ? this.compileWrite('hardDelete', options, build)
+            : this.compileWrite('hardDelete', options, () => build().returning(this.physicalKeyColumns));
+        const rows = await this.driver.execute(this.assertKeyed(query, 'hardDelete'));
+        await this.invalidateCache(options);
+        return this.writeMatched(rows, 'delete');
+    }
+    async restore(id, options) {
+        const softDelete = this.schema.ir.softDelete;
+        if (softDelete === undefined) {
+            throw new ValidationError(`${this.tableName}.restore requires a SoftDelete<'column'> declaration`);
+        }
+        const build = () => this.keyWhere(this.qb.updateTable(this.tableName).set({ [this.physicalColumn(softDelete.column)]: null }), id, 'restore');
+        const query = !this.dialectCapabilities.returning.update
+            ? this.compileWrite('restore', options, build, { excludedFilterNames: ['softDelete'] })
+            : this.compileWrite('restore', options, () => build().returning(this.physicalKeyColumns), {
+                excludedFilterNames: ['softDelete'],
+            });
+        const rows = await this.driver.execute(this.assertKeyed(query, 'restore'));
+        await this.invalidateCache(options);
+        return this.writeMatched(rows, 'update');
+    }
+    writeMatched(rows, statement) {
+        if (!this.dialectCapabilities.returning[statement]) {
+            const affectedRows = rows[0]?.['affectedRows'];
+            if (typeof affectedRows === 'number')
+                return affectedRows > 0;
+        }
+        return rows.length > 0;
+    }
+    softDeleteUpsertFields(clean, target, updateFields) {
+        const softDelete = this.schema.ir.softDelete;
+        if (softDelete === undefined)
+            return updateFields;
+        const restored = {};
+        if (isUpdateFieldList(updateFields)) {
+            for (const column of updateFields) {
+                if (column !== softDelete.column)
+                    restored[column] = proposed();
+            }
+        }
+        else if (updateFields !== undefined) {
+            Object.assign(restored, updateFields);
+        }
+        else {
+            const targetColumns = new Set(typeof target === 'string' ? [target] : target);
+            const nonTarget = Object.keys(clean).filter(column => !targetColumns.has(column));
+            const columns = nonTarget.length > 0 ? nonTarget : Object.keys(clean);
+            for (const column of columns)
+                restored[column] = proposed();
+        }
+        restored[softDelete.column] = null;
+        return restored;
+    }
+    // Explicit, synchronous lifecycle hooks. No hidden change tracking — these
+    // fire only around the corresponding operation, in documented order.
+    preInsert(_row) { }
+    postInsert(_row) { }
+    preUpdate(_patch) { }
+    preDelete(_id) { }
+    postSelect(rows) {
+        return rows;
+    }
+    sanitizePayload(payload) {
+        if (!isRecord(payload)) {
+            throw new ValidationError('payload must be an object', [
+                { path: 'input', message: 'expected object', expected: 'object', value: payload },
+            ]);
+        }
+        const clean = {};
+        for (const key of Object.keys(payload)) {
+            if (payload[key] !== undefined) {
+                clean[key] = payload[key];
+            }
+        }
+        return clean;
+    }
+    /**
+     * One write variant's columns, and the object type they add up to.
+     *
+     * Built once per repository instance per variant. `this.schema` is a static and never
+     * changes, so neither can the IR; without the cache every `create` would walk the
+     * columns again to rebuild an identical object graph.
+     */
+    payloadShape(variant) {
+        const cached = this.#shapes.get(variant);
+        if (cached)
+            return cached;
+        const shape = shapeOfVariant(this.schema.ir, variant);
+        const built = {
+            shape,
+            type: objectTypeFromShape(shape),
+            accepted: new Set(shape.map(({ column }) => column.name)),
+            columns: new Map(shape.map(({ column }) => [column.name, column])),
+        };
+        this.#shapes.set(variant, built);
+        return built;
+    }
+    /**
+     * One issue per key the payload has and this variant does not accept (REQ-RP-3).
+     *
+     * These used to be dropped in silence, which made two mistakes invisible. A misspelled
+     * column — `{ emial: 'a@b.co' }` — reported only that `email` was missing, and a
+     * supplied `id` on a serial key reported nothing at all: the insert went through with a
+     * key the database was about to generate, so the payload the caller wrote and the row
+     * that came back disagreed and nothing said so.
+     *
+     * Reported alongside the structural issues rather than only when there are none, which
+     * is where this deliberately differs from `assertEquals`'s excess check. Its rule is
+     * that "you also passed `extra`" is noise next to "`email` is not a string", and at a
+     * table boundary it usually is not noise: the excess key is a typo *of* the column the
+     * other issue is complaining about, and suppressing it hides the answer.
+     */
+    excessIssues(obj, variant) {
+        const { accepted } = this.payloadShape(variant);
+        const issues = [];
+        for (const key of Object.keys(obj)) {
+            if (accepted.has(key))
+                continue;
+            const column = this.schema.ir.columns.find(candidate => candidate.name === key);
+            const message = !column
+                ? `"${key}" is not a column of "${this.tableName}"`
+                : column.serial
+                    ? `the database generates "${key}", so a payload cannot supply it`
+                    : `"${key}" identifies the row and cannot be patched`;
+            issues.push({ path: `input.${key}`, message, expected: 'no excess properties', value: obj[key] });
+        }
+        return issues;
+    }
+    /**
+     * Runtime validation of a write payload — the type of the payload, checked by the one
+     * runtime walker.
+     *
+     * This used to be a walk of its own over `ColumnMeta`, and it was the fourth of the
+     * four that `@zmdb/schema/ir` exists to collapse: it accepted `Date | string` for
+     * a `timestamp` while the published document said ISO string and `Entity<T>` said
+     * `Date`, and it had no notion of `Min`/`Max`/`Pattern` at all, so a repository write
+     * skipped every bound the schema declared and the same value was rejected only later,
+     * at the HTTP edge, by a different validator. What it needed was not a walk but the
+     * *type* of a `CreateDTO`, which `objectTypeFromShape` produces from the same IR the
+     * documents come from.
+     *
+     * The app layer, not the wire layer: a caller here holds a `Date`, having decoded the
+     * request body already. A handler that has not is the boundary case `Wire<T>` is for.
+     *
+     * A key the variant does not accept is an issue, not something to drop — see
+     * `excessIssues`.
+     */
+    validatePayload(payload, variant) {
+        const obj = this.sanitizePayload(payload);
+        const { shape, type } = this.payloadShape(variant);
+        const issues = [...issuesFor(obj, type), ...this.excessIssues(obj, variant)];
+        return this.validatedColumns(obj, shape, issues);
+    }
+    /**
+     * Validate a patch without teaching the DTO validator that arbitrary objects are
+     * column values. Plain values still cross the unchanged UpdateDTO object check;
+     * branded expressions are omitted from that object and their one operand is
+     * checked against the same column IR separately.
+     */
+    validateUpdatePatch(payload) {
+        const obj = this.sanitizePayload(payload);
+        const values = {};
+        const expressionIssues = [];
+        const { shape, type, columns } = this.payloadShape('update');
+        for (const key of Object.keys(obj)) {
+            const value = obj[key];
+            if (!isColumnExpression(value)) {
+                values[key] = value;
+                continue;
+            }
+            const column = columns.get(key);
+            if (column === undefined)
+                continue;
+            const operand = expressionOperand(value);
+            if (operand !== NO_EXPRESSION_OPERAND) {
+                expressionIssues.push(...issuesFor(operand, appTypeOf(column), `input.${key}`));
+            }
+        }
+        const issues = [...issuesFor(values, type), ...expressionIssues, ...this.excessIssues(obj, 'update')];
+        return this.validatedColumns(obj, shape, issues);
+    }
+    validatedColumns(obj, shape, issues) {
+        if (issues.length > 0) {
+            throw new ValidationError(`validation failed: ${issues.map(issue => issue.path).join(', ')}`, issues);
+        }
+        const out = {};
+        for (const { column } of shape) {
+            if (column.name in obj)
+                out[column.name] = obj[column.name];
+        }
+        return out;
+    }
+    hasColumnExpression(patch) {
+        return Object.values(patch).some(isColumnExpression);
+    }
+}
+export function defineRepository(schema, driver, opts) {
+    // Anonymous subclass binding the schema as a static, exactly like a hand-written
+    // subclass — no proxies, no magic.
+    class Repo extends BaseRepository {
+        static schema = schema;
+    }
+    return new Repo(driver, opts?.dialect ?? driver.dialect, opts);
+}
+export { memoryStore } from './cache/index.js';
+export { createLoaderScope, } from './loaders/index.js';
+export * from './transactions/index.js';
+//# sourceMappingURL=index.js.map