@stonyx/orm 0.3.2-beta.33 → 0.3.2-beta.330

package/dist/mysql/mysql-db.js

@@ -2,7 +2,7 @@ import { getPool, closePool } from './connection.js';
 import { ensureMigrationsTable, getAppliedMigrations, getMigrationFiles, applyMigration, parseMigrationFile } from './migration-runner.js';
 import { introspectModels, introspectViews, getTopologicalOrder, schemasToSnapshot } from './schema-introspector.js';
 import { loadLatestSnapshot, detectSchemaDrift } from './migration-generator.js';
-import { buildInsert, buildUpdate, buildDelete, buildSelect } from './query-builder.js';
+import { buildInsert, buildInsertMany, buildUpdate, buildDelete, buildSelect } from './query-builder.js';
 import { store } from '@stonyx/orm';
 import { createRecord } from '../manage-record.js';
 import { confirm } from '@stonyx/utils/prompt';
@@ -12,20 +12,41 @@ import { isDbError } from '../utils.js';
 import config from 'stonyx/config';
 import log from 'stonyx/log';
 import path from 'path';
+const MYSQL_MAX_PLACEHOLDERS = 65535;
+const DEFAULT_WRITE_BATCH_SIZE = 500;
+const DEFAULT_WRITE_QUEUE_LIMIT = 10000;
+export class WriteQueueFullError extends Error {
+    constructor(limit) {
+        super(`MysqlDB write queue is full (${limit} queued writes, writeQueueLimit); the write was rejected`);
+        this.name = 'WriteQueueFullError';
+    }
+}
+export class WriteQueueClosedError extends Error {
+    constructor() {
+        super('MysqlDB is shutting down; the write was rejected');
+        this.name = 'WriteQueueClosedError';
+    }
+}
 const defaultDeps = {
     getPool, closePool, ensureMigrationsTable, getAppliedMigrations,
     getMigrationFiles, applyMigration, parseMigrationFile,
     introspectModels, introspectViews, getTopologicalOrder, schemasToSnapshot,
     loadLatestSnapshot, detectSchemaDrift,
-    buildInsert, buildUpdate, buildDelete, buildSelect,
+    buildInsert, buildInsertMany, buildUpdate, buildDelete, buildSelect,
     createRecord, store: store, confirm, readFile, getPluralName,
-    config, log, path
+    config, log, path, process
 };
 export default class MysqlDB {
     static instance;
     deps;
     pool;
     mysqlConfig;
+    persistResolvesAfterWrite = true;
+    _queuedWrites = [];
+    _inFlightWrites = new Set();
+    _drainingWrites = null;
+    _acceptingWrites = true;
+    _exitReport = null;
     constructor(deps = {}) {
         if (MysqlDB.instance)
             return MysqlDB.instance;
@@ -46,6 +67,17 @@ export default class MysqlDB {
         this.pool = await this.deps.getPool(this.mysqlConfig);
         await this.deps.ensureMigrationsTable(this.pool, this.mysqlConfig.migrationsTable);
         await this.loadMemoryRecords();
+        this._acceptingWrites = true;
+        this._registerExitReport();
+    }
+    get writeBatchSize() {
+        return Number(this.mysqlConfig?.writeBatchSize) || DEFAULT_WRITE_BATCH_SIZE;
+    }
+    get writeQueueLimit() {
+        return Number(this.mysqlConfig?.writeQueueLimit) || DEFAULT_WRITE_QUEUE_LIMIT;
+    }
+    get pendingWriteCount() {
+        return this._inFlightWrites.size + this._queuedWrites.length;
     }
     async startup() {
         if (!this.mysqlConfig.migrationsDir)
@@ -57,7 +89,17 @@ export default class MysqlDB {
         const pending = files.filter(f => !applied.includes(f));
         if (pending.length > 0) {
             this.deps.log.db?.(`${pending.length} pending migration(s) found.`);
-            const shouldApply = await this.deps.confirm(`${pending.length} pending migration(s) found. Apply now?`);
+            let shouldApply;
+            if (this.mysqlConfig.autoMigrate === true) {
+                shouldApply = true;
+            }
+            else if (this.mysqlConfig.autoMigrate === false) {
+                shouldApply = false;
+                this.deps.log.warn?.(`autoMigrate is false — skipping ${pending.length} pending migration(s).`);
+            }
+            else {
+                shouldApply = await this.deps.confirm(`${pending.length} pending migration(s) found. Apply now?`);
+            }
             if (shouldApply) {
                 for (const filename of pending) {
                     const content = await this.deps.readFile(this.deps.path.join(migrationsPath, filename));
@@ -76,7 +118,17 @@ export default class MysqlDB {
             const schemas = this.deps.introspectModels();
             const modelCount = Object.keys(schemas).length;
             if (modelCount > 0) {
-                const shouldGenerate = await this.deps.confirm(`No migrations found but ${modelCount} model(s) detected. Generate and apply initial migration?`);
+                let shouldGenerate;
+                if (this.mysqlConfig.autoMigrate === true) {
+                    shouldGenerate = true;
+                }
+                else if (this.mysqlConfig.autoMigrate === false) {
+                    shouldGenerate = false;
+                    this.deps.log.warn?.(`autoMigrate is false — skipping initial migration generation for ${modelCount} model(s).`);
+                }
+                else {
+                    shouldGenerate = await this.deps.confirm(`No migrations found but ${modelCount} model(s) detected. Generate and apply initial migration?`);
+                }
                 if (shouldGenerate) {
                     const { generateMigration } = await import('./migration-generator.js');
                     const result = await generateMigration('initial_setup');
@@ -106,9 +158,35 @@ export default class MysqlDB {
         }
     }
     async shutdown() {
+        this._acceptingWrites = false;
+        while (this._drainingWrites)
+            await this._drainingWrites;
+        this._unregisterExitReport();
         await this.deps.closePool();
         this.pool = null;
     }
+    _registerExitReport() {
+        if (this._exitReport)
+            return;
+        this._exitReport = () => this._reportUnpersistedWrites();
+        this.deps.process.once('exit', this._exitReport);
+    }
+    _unregisterExitReport() {
+        if (!this._exitReport)
+            return;
+        this.deps.process.removeListener('exit', this._exitReport);
+        this._exitReport = null;
+    }
+    _reportUnpersistedWrites() {
+        const lostWrites = [...this._inFlightWrites, ...this._queuedWrites];
+        if (lostWrites.length === 0)
+            return;
+        const lostByModel = new Map();
+        for (const { modelName } of lostWrites)
+            lostByModel.set(modelName, (lostByModel.get(modelName) ?? 0) + 1);
+        const breakdown = [...lostByModel].map(([modelName, count]) => `${modelName}: ${count}`).join(', ');
+        this.deps.log.error?.(`[MysqlDB] Process exiting with ${lostWrites.length} queued write(s) not persisted; they are lost (${breakdown})`);
+    }
     async save() {
         // No-op: MySQL persists data immediately via persist()
     }
@@ -298,58 +376,174 @@ export default class MysqlDB {
         return rawData;
     }
     async persist(operation, modelName, context, response) {
-        // Views are read-only — no-op for all write operations
         const Orm = (await import('@stonyx/orm')).default;
         if (Orm.instance?.isView?.(modelName))
             return;
-        switch (operation) {
-            case 'create':
-                return this._persistCreate(modelName, context, response);
-            case 'update':
-                return this._persistUpdate(modelName, context, response);
-            case 'delete':
-                return this._persistDelete(modelName, context);
-        }
+        if (!this._acceptingWrites)
+            throw new WriteQueueClosedError();
+        if (this._queuedWrites.length >= this.writeQueueLimit)
+            throw new WriteQueueFullError(this.writeQueueLimit);
+        return new Promise((resolve, reject) => {
+            const write = {
+                operation, modelName, context, response,
+                resolve: () => {
+                    this._inFlightWrites.delete(write);
+                    resolve();
+                },
+                reject: (error) => {
+                    this._inFlightWrites.delete(write);
+                    reject(error);
+                },
+            };
+            this._queuedWrites.push(write);
+            this._drainWritesInBackground();
+        });
     }
-    async _persistCreate(modelName, context, response) {
-        const schemas = this.deps.introspectModels();
-        const schema = schemas[modelName];
-        if (!schema)
+    _drainWritesInBackground() {
+        if (this._drainingWrites)
             return;
+        this._drainingWrites = this._drainQueuedWrites().finally(() => {
+            this._drainingWrites = null;
+        });
+    }
+    async _drainQueuedWrites() {
+        while (this._queuedWrites.length > 0) {
+            const writes = this._takeNextWriteGroup();
+            writes.forEach(write => this._inFlightWrites.add(write));
+            try {
+                await this._executeWriteGroup(writes);
+            }
+            catch (error) {
+                writes.filter(write => this._inFlightWrites.has(write)).forEach(write => write.reject(error));
+            }
+        }
+    }
+    _takeNextWriteGroup() {
+        const [first] = this._queuedWrites;
+        let groupSize = 1;
+        if (first.operation === 'create') {
+            while (groupSize < this.writeBatchSize
+                && groupSize < this._queuedWrites.length
+                && this._queuedWrites[groupSize].operation === 'create'
+                && this._queuedWrites[groupSize].modelName === first.modelName)
+                groupSize++;
+        }
+        return this._queuedWrites.splice(0, groupSize);
+    }
+    async _executeWriteGroup(writes) {
+        const [first] = writes;
+        if (first.operation === 'create')
+            return this._persistCreates(first.modelName, writes);
+        try {
+            if (first.operation === 'update')
+                await this._persistUpdate(first.modelName, first.context, first.response);
+            if (first.operation === 'delete')
+                await this._persistDelete(first.modelName, first.context);
+            first.resolve();
+        }
+        catch (error) {
+            first.reject(error);
+        }
+    }
+    async _persistCreates(modelName, writes) {
+        const schema = this.deps.introspectModels()[modelName];
+        const prepared = [];
+        for (const write of writes) {
+            try {
+                const create = schema ? this._prepareCreate(modelName, schema, write) : null;
+                if (create)
+                    prepared.push(create);
+                else
+                    write.resolve();
+            }
+            catch (error) {
+                write.reject(error);
+            }
+        }
+        for (const chunk of this._chunkForSingleInsert(prepared)) {
+            await this._insertCreates(schema, chunk);
+        }
+    }
+    _prepareCreate(modelName, schema, write) {
+        const { context, response } = write;
         const recordId = response?.data?.id;
         const record = recordId != null ? this.deps.store.get(modelName, (isNaN(recordId) ? recordId : parseInt(recordId))) : null;
         if (!record)
-            return;
-        const insertData = this._recordToRow(record, schema);
-        // For auto-increment models, remove the pending ID.
-        // Check context.rawData (not record.__data) because __pendingSqlId is not a model
-        // attribute and gets lost during serialization.
+            return null;
+        const row = this._recordToRow(record, schema);
         const isPendingId = context.rawData?.__pendingSqlId === true;
-        if (isPendingId) {
-            delete insertData.id;
+        if (isPendingId)
+            delete row.id;
+        return { write, modelName, record, row, isPendingId };
+    }
+    _chunkForSingleInsert(prepared) {
+        const chunks = [];
+        let chunk = [];
+        let chunkColumns = new Set();
+        for (const create of prepared) {
+            const columnsWithCreate = new Set([...chunkColumns, ...Object.keys(create.row)]);
+            const mixesIdSources = chunk.length > 0 && chunk[0].isPendingId !== create.isPendingId;
+            const exceedsPlaceholders = (chunk.length + 1) * columnsWithCreate.size > MYSQL_MAX_PLACEHOLDERS;
+            if (chunk.length > 0 && (mixesIdSources || exceedsPlaceholders)) {
+                chunks.push(chunk);
+                chunk = [];
+                chunkColumns = new Set(Object.keys(create.row));
+            }
+            else {
+                chunkColumns = columnsWithCreate;
+            }
+            chunk.push(create);
         }
-        else if (insertData.id !== undefined) {
-            // Keep user-provided ID (string IDs or explicit numeric IDs)
+        if (chunk.length > 0)
+            chunks.push(chunk);
+        return chunks;
+    }
+    async _insertCreates(schema, creates) {
+        if (creates.length === 1)
+            return this._insertCreatesOneByOne(schema, creates);
+        let firstInsertId;
+        try {
+            const { sql, values } = this.deps.buildInsertMany(schema.table, creates.map(({ row }) => row));
+            const [result] = await this.requirePool().execute(sql, values);
+            firstInsertId = result.insertId;
         }
-        const { sql, values } = this.deps.buildInsert(schema.table, insertData);
-        const [result] = await this.requirePool().execute(sql, values);
-        // Re-key the record in the store if MySQL generated the ID
-        if (isPendingId && result.insertId) {
-            const pendingId = record.id;
-            const realId = result.insertId;
-            const modelStore = this.deps.store.get(modelName);
-            if (!modelStore)
-                throw new Error(`Model "${modelName}" not found in store during ID re-key`);
-            modelStore.delete(pendingId);
-            record.__data.id = realId;
-            record.id = realId;
-            modelStore.set(realId, record);
-            // Update the response data with the real ID
-            if (response?.data) {
-                response.data.id = realId;
-            }
-            delete record.__data.__pendingSqlId;
+        catch {
+            return this._insertCreatesOneByOne(schema, creates);
         }
+        creates.forEach((create, index) => {
+            if (firstInsertId)
+                this._adoptGeneratedId(create, firstInsertId + index);
+            create.write.resolve();
+        });
+    }
+    async _insertCreatesOneByOne(schema, creates) {
+        for (const create of creates) {
+            try {
+                const { sql, values } = this.deps.buildInsert(schema.table, create.row);
+                const [result] = await this.requirePool().execute(sql, values);
+                if (result.insertId)
+                    this._adoptGeneratedId(create, result.insertId);
+                create.write.resolve();
+            }
+            catch (error) {
+                create.write.reject(error);
+            }
+        }
+    }
+    _adoptGeneratedId({ modelName, record, isPendingId, write }, realId) {
+        if (!isPendingId)
+            return;
+        const pendingId = record.id;
+        const modelStore = this.deps.store.get(modelName);
+        if (!modelStore)
+            throw new Error(`Model "${modelName}" not found in store during ID re-key`);
+        modelStore.delete(pendingId);
+        record.__data.id = realId;
+        record.id = realId;
+        modelStore.set(realId, record);
+        if (write.response?.data)
+            write.response.data.id = realId;
+        delete record.__data.__pendingSqlId;
     }
     async _persistUpdate(modelName, context, response) {
         const schemas = this.deps.introspectModels();

package/dist/mysql/query-builder.d.ts

@@ -4,6 +4,7 @@ interface QueryResult {
 }
 export declare function validateIdentifier(name: string, context?: string): string;
 export declare function buildInsert(table: string, data: Record<string, unknown>): QueryResult;
+export declare function buildInsertMany(table: string, rows: Record<string, unknown>[]): QueryResult;
 export declare function buildUpdate(table: string, id: unknown, data: Record<string, unknown>): QueryResult;
 export declare function buildDelete(table: string, id: unknown): QueryResult;
 export declare function buildSelect(table: string, conditions?: Record<string, unknown>): QueryResult;

package/dist/mysql/query-builder.js

@@ -14,6 +14,23 @@ export function buildInsert(table, data) {
     const sql = `INSERT INTO \`${table}\` (${keys.map(k => `\`${k}\``).join(', ')}) VALUES (${placeholders.join(', ')})`;
     return { sql, values };
 }
+export function buildInsertMany(table, rows) {
+    validateIdentifier(table, 'table name');
+    const columns = [...new Set(rows.flatMap(row => Object.keys(row)))];
+    columns.forEach(column => validateIdentifier(column, 'column name'));
+    const values = [];
+    const tuples = rows.map(row => {
+        const cells = columns.map(column => {
+            if (!Object.hasOwn(row, column))
+                return 'DEFAULT';
+            values.push(row[column]);
+            return '?';
+        });
+        return `(${cells.join(', ')})`;
+    });
+    const sql = `INSERT INTO \`${table}\` (${columns.map(column => `\`${column}\``).join(', ')}) VALUES ${tuples.join(', ')}`;
+    return { sql, values };
+}
 export function buildUpdate(table, id, data) {
     validateIdentifier(table, 'table name');
     const keys = Object.keys(data);

package/dist/normalize-record-id.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The ONE place a URL id is turned into the value a record is resolved by —
+ * abofs/stonyx-orm#270.
+ *
+ * Before this existed this coercion was written out seven times: twice in
+ * README.md, once in docs/usage-patterns.md, and four times inside the
+ * framework. Seven copies, not seven identical copies — the three persistence
+ * ones (abofs/stonyx-orm#282) omit the `if (!id) return ''` guard below, which
+ * is the point: nothing held them together, so they had already drifted.
+ * The framework's copy — `getId()`, module-private in
+ * orm-request.ts, unreachable through the package `exports` map — was the one
+ * that decided which record a request addressed, and a consumer's `access()`
+ * predicate had no way to obtain it. So the framework resolved the record by
+ * one value and asked the consumer to authorize on a different one.
+ *
+ * Measured consequence at the time of filing: with the documented predicate
+ * applied verbatim to a numeric-id model, `GET /animals/007`, `/7.9`, `/7e0`,
+ * `/0x7`, `/%207`, `/%2B7` and `/7%0A` each served the protected record, and
+ * `DELETE /animals/007` destroyed it — because `parseInt` folds every one of
+ * those onto `7` while `'007' === '7'` is false.
+ *
+ * Two things follow from this being a single exported function, and both are
+ * the point:
+ *
+ *  1. A permissive change here is HARMLESS, because both sides move together.
+ *     Lowercasing string ids used to disclose and destroy `owner:angela` with
+ *     the whole suite green; with one implementation the predicate simply sees
+ *     the same lowercased value and still refuses.
+ *  2. A divergence — a second, private normaliser at the resolution site — is
+ *     what is now dangerous, and that is what the tests pin, by observing the
+ *     key the resolution path actually used.
+ *
+ * SEMANTICS ARE UNCHANGED FROM `getId()`, deliberately and byte-for-byte.
+ * Whether `7.9` / `0x7` / `%0A` *should* resolve to record 7 at all is a real
+ * question, and it is a behaviour change on the record-resolution path for
+ * every consumer rather than an authorization fix — it belongs in its own
+ * issue with its own compatibility argument (issue body scope item 4). #270
+ * preserves today's semantics exactly and makes both sides agree on them.
+ *
+ * Two details are load-bearing and are pinned by
+ * test/unit/normalize-record-id-test.ts:
+ *
+ *  - `parseInt` is called with NO RADIX. `parseInt('0x7')` is 7;
+ *    `parseInt('0x7', 10)` is 0. Adding the radix looks like a cleanup and
+ *    silently changes which record every hex-spelled URL addresses.
+ *  - The coercion applies only when the id LOOKS numeric, so a model with
+ *    string ids is passed through untouched, case included.
+ *
+ * Must stay synchronous: `auth()` is invoked without `await` by
+ * @stonyx/rest-server, so a promise here would be handed to `access()` as the
+ * record id.
+ *
+ * FALSY AND `NaN` RETURNS ARE LOAD-BEARING ELSEWHERE — abofs/stonyx-orm#287.
+ * `''` is returned for any falsy id because `store.get(key, undefined)` returns
+ * the whole model Map rather than a record (abofs/stonyx-orm#167). But `''` is
+ * not the only falsy return: `'0'`, `'00'`, `'-0'` and `'0x0'` all normalise to
+ * `0`, and `' '`, `'\t'`, `'\n'`, `'\u00a0'` all normalise to `NaN` (their
+ * `Number()` is `0`, so the `isNaN` guard does not fire and `parseInt` runs).
+ * `store.remove(key, id)` branches on truthiness, so those spellings reach a
+ * fall-through this function does not own. Tracked as #287; every row is pinned
+ * in test/unit/normalize-record-id-test.ts so a cleanup here cannot move the
+ * boundary #287 is measured against.
+ *
+ * @param id the raw, already-URL-decoded id text from `request.params.id`
+ * @returns the value the ORM resolves the record by
+ */
+export default function normalizeRecordId(id?: string | null): string | number;

package/dist/normalize-record-id.js

@@ -0,0 +1,88 @@
+/*
+ * Copyright 2025 Stone Costa
+ *
+ * Licensed under the Apache License, Version 2.0 (the 'License');
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an 'AS IS' BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The ONE place a URL id is turned into the value a record is resolved by —
+ * abofs/stonyx-orm#270.
+ *
+ * Before this existed this coercion was written out seven times: twice in
+ * README.md, once in docs/usage-patterns.md, and four times inside the
+ * framework. Seven copies, not seven identical copies — the three persistence
+ * ones (abofs/stonyx-orm#282) omit the `if (!id) return ''` guard below, which
+ * is the point: nothing held them together, so they had already drifted.
+ * The framework's copy — `getId()`, module-private in
+ * orm-request.ts, unreachable through the package `exports` map — was the one
+ * that decided which record a request addressed, and a consumer's `access()`
+ * predicate had no way to obtain it. So the framework resolved the record by
+ * one value and asked the consumer to authorize on a different one.
+ *
+ * Measured consequence at the time of filing: with the documented predicate
+ * applied verbatim to a numeric-id model, `GET /animals/007`, `/7.9`, `/7e0`,
+ * `/0x7`, `/%207`, `/%2B7` and `/7%0A` each served the protected record, and
+ * `DELETE /animals/007` destroyed it — because `parseInt` folds every one of
+ * those onto `7` while `'007' === '7'` is false.
+ *
+ * Two things follow from this being a single exported function, and both are
+ * the point:
+ *
+ *  1. A permissive change here is HARMLESS, because both sides move together.
+ *     Lowercasing string ids used to disclose and destroy `owner:angela` with
+ *     the whole suite green; with one implementation the predicate simply sees
+ *     the same lowercased value and still refuses.
+ *  2. A divergence — a second, private normaliser at the resolution site — is
+ *     what is now dangerous, and that is what the tests pin, by observing the
+ *     key the resolution path actually used.
+ *
+ * SEMANTICS ARE UNCHANGED FROM `getId()`, deliberately and byte-for-byte.
+ * Whether `7.9` / `0x7` / `%0A` *should* resolve to record 7 at all is a real
+ * question, and it is a behaviour change on the record-resolution path for
+ * every consumer rather than an authorization fix — it belongs in its own
+ * issue with its own compatibility argument (issue body scope item 4). #270
+ * preserves today's semantics exactly and makes both sides agree on them.
+ *
+ * Two details are load-bearing and are pinned by
+ * test/unit/normalize-record-id-test.ts:
+ *
+ *  - `parseInt` is called with NO RADIX. `parseInt('0x7')` is 7;
+ *    `parseInt('0x7', 10)` is 0. Adding the radix looks like a cleanup and
+ *    silently changes which record every hex-spelled URL addresses.
+ *  - The coercion applies only when the id LOOKS numeric, so a model with
+ *    string ids is passed through untouched, case included.
+ *
+ * Must stay synchronous: `auth()` is invoked without `await` by
+ * @stonyx/rest-server, so a promise here would be handed to `access()` as the
+ * record id.
+ *
+ * FALSY AND `NaN` RETURNS ARE LOAD-BEARING ELSEWHERE — abofs/stonyx-orm#287.
+ * `''` is returned for any falsy id because `store.get(key, undefined)` returns
+ * the whole model Map rather than a record (abofs/stonyx-orm#167). But `''` is
+ * not the only falsy return: `'0'`, `'00'`, `'-0'` and `'0x0'` all normalise to
+ * `0`, and `' '`, `'\t'`, `'\n'`, `'\u00a0'` all normalise to `NaN` (their
+ * `Number()` is `0`, so the `isNaN` guard does not fire and `parseInt` runs).
+ * `store.remove(key, id)` branches on truthiness, so those spellings reach a
+ * fall-through this function does not own. Tracked as #287; every row is pinned
+ * in test/unit/normalize-record-id-test.ts so a cleanup here cannot move the
+ * boundary #287 is measured against.
+ *
+ * @param id the raw, already-URL-decoded id text from `request.params.id`
+ * @returns the value the ORM resolves the record by
+ */
+export default function normalizeRecordId(id) {
+    if (!id)
+        return '';
+    if (isNaN(id))
+        return id;
+    return parseInt(id);
+}

package/dist/orm-request.d.ts

@@ -1,10 +1,26 @@
 import { Request } from '@stonyx/rest-server';
-interface OrmRequest$ extends Request {
+/**
+ * The request object a consumer's `access()` predicate receives.
+ *
+ * Exported because `recordId` is public API — README's `access()` samples
+ * destructure it — and a public runtime field with an unreachable type asks the
+ * consumer to re-declare something the framework already knows, which is
+ * abofs/stonyx-orm#270's own defect shape one layer over into the type surface.
+ * `HookContext` (src/hooks.ts) is this repo's precedent for exporting the
+ * interface a consumer is handed. Re-exported from the root barrel as
+ * `OrmAccessRequest` (src/index.ts) — NOT as `OrmRequest`, which is already the
+ * default-exported CLASS in this file and means something else. The
+ * `./orm-request` subpath is not in the `exports` map, so the barrel is the
+ * only reachable spelling.
+ */
+export interface OrmRequest$ extends Request {
     protocol?: string;
+    baseUrl?: string;
     method: string;
     params: {
         [key: string]: string;
     };
+    recordId?: string | number | undefined;
     body?: {
         [key: string]: unknown;
     };