@stonyx/orm 0.3.2-beta.3 → 0.3.2-beta.300

package/dist/mysql/mysql-db.js

@@ -26,6 +26,14 @@ export default class MysqlDB {
     deps;
     pool;
     mysqlConfig;
+    /**
+     * Promise-chain mutex for write serialization (#156).
+     * All persist() calls chain through this single queue so concurrent
+     * fire-and-forget writes never produce parallel InnoDB transactions
+     * on FK-linked rows (which cause deadlocks).
+     * Reads are NOT affected — only persist() serializes.
+     */
+    _writeQueue = Promise.resolve();
     constructor(deps = {}) {
         if (MysqlDB.instance)
             return MysqlDB.instance;
@@ -57,7 +65,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 +94,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');
@@ -302,14 +330,20 @@ export default class MysqlDB {
         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);
-        }
+        const work = async () => {
+            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);
+            }
+        };
+        // Chain through the write queue — .then(work, work) ensures the queue
+        // advances even when a previous persist rejects (#156).
+        this._writeQueue = this._writeQueue.then(work, work);
+        return this._writeQueue;
     }
     async _persistCreate(modelName, context, response) {
         const schemas = this.deps.introspectModels();
@@ -321,8 +355,10 @@ export default class MysqlDB {
         if (!record)
             return;
         const insertData = this._recordToRow(record, schema);
-        // For auto-increment models, remove the pending ID
-        const isPendingId = record.__data.__pendingSqlId;
+        // 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.
+        const isPendingId = context.rawData?.__pendingSqlId === true;
         if (isPendingId) {
             delete insertData.id;
         }

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

package/dist/orm-request.js

@@ -5,6 +5,7 @@ import { getPluralName } from './plural-registry.js';
 import { getBeforeHooks, getAfterHooks } from './hooks.js';
 import config from 'stonyx/config';
 import { isOrmRecord } from './utils.js';
+import normalizeRecordId from './normalize-record-id.js';
 const methodAccessMap = {
     GET: 'read',
     POST: 'create',
@@ -42,19 +43,46 @@ function getModelRelationships(modelName) {
     }
     return relationships;
 }
-// Helper to build base URL from request
-function getBaseUrl(request) {
+/**
+ * Build the absolute base URL that every advertised link hangs off — origin
+ * plus the prefix the ORM's routes are actually mounted at.
+ *
+ * The prefix is derived from the *request*, not from
+ * `config.orm.restServer.route`. Express sets `request.baseUrl` to the real
+ * mountpath registered by `RestServer.mountRoute`, which for this module is
+ * always `<prefix>/<pluralizedModel>` (see setup-rest-server.ts). Stripping the
+ * trailing model segment therefore yields the prefix by construction, and the
+ * link builder cannot drift from the mount registrar the way a second,
+ * independent normalisation of `route` would.
+ *
+ * When `request.baseUrl` is absent or does not end in the model segment the
+ * prefix is empty, which reproduces the previous origin-only behaviour.
+ */
+function getBaseUrl(request, pluralizedModel) {
     const protocol = request.protocol || 'http';
     const host = request.get('host');
-    return `${protocol}://${host}`;
+    const modelSegment = `/${pluralizedModel}`;
+    const mountPath = request.baseUrl ?? '';
+    const prefix = mountPath.endsWith(modelSegment) ? mountPath.slice(0, -modelSegment.length) : '';
+    return `${protocol}://${host}${prefix}`;
 }
+// Kept as a name because twelve `getId(...)` call sites read it. It is now a
+// thin delegate: there is exactly ONE normalisation of a URL id in the repo,
+// and it is the exported one a consumer can import.
+//
+// "of a URL id" is the load-bearing qualifier, and it is the same one
+// src/normalize-record-id.ts:18 carries. Three copies of the coercion survive
+// at this head — src/orm-request.ts (the create-response path),
+// src/postgres/postgres-db.ts and src/mysql/mysql-db.ts — but each normalises a
+// RESPONSE id (`response?.data?.id`), not a URL id, and each omits this
+// function's `if (!id) return ''` guard. They are tracked as
+// abofs/stonyx-orm#282 and enumerated by name in AC-5's allowlist
+// (test/integration/readme-sample-test.ts).
+//
+// A second implementation of the URL-id normalisation here is the defect
+// abofs/stonyx-orm#270 exists to remove — see src/normalize-record-id.ts.
 function getId(params) {
-    const id = params.id;
-    if (!id)
-        return '';
-    if (isNaN(id))
-        return id;
-    return parseInt(id);
+    return normalizeRecordId(params.id);
 }
 function buildResponse(data, includeParam, recordOrRecords, options = {}) {
     const { links, baseUrl } = options;
@@ -209,7 +237,7 @@ export default class OrmRequest extends Request {
                 recordsToReturn = recordsToReturn.filter(accessFilter);
             if (queryFilterPredicate)
                 recordsToReturn = recordsToReturn.filter(queryFilterPredicate);
-            const baseUrl = getBaseUrl(request);
+            const baseUrl = getBaseUrl(request, pluralizedModel);
             const data = recordsToReturn.map(record => record.toJSON?.({ fields: modelFields, baseUrl }));
             return buildResponse(data, request.query?.include, recordsToReturn, {
                 links: { self: `${baseUrl}/${pluralizedModel}` },
@@ -222,7 +250,7 @@ export default class OrmRequest extends Request {
                 return 404;
             const fieldsMap = parseFields(request.query);
             const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
-            const baseUrl = getBaseUrl(request);
+            const baseUrl = getBaseUrl(request, pluralizedModel);
             return buildResponse(record.toJSON?.({ fields: modelFields, baseUrl }), request.query?.include, record, {
                 links: { self: `${baseUrl}/${pluralizedModel}/${request.params.id}` },
                 baseUrl
@@ -248,7 +276,7 @@ export default class OrmRequest extends Request {
                 }
             }
             const recordAttributes = id !== undefined ? { id, ...sanitizedAttributes } : sanitizedAttributes;
-            const created = createRecord(model, recordAttributes, { serialize: false });
+            const created = createRecord(model, recordAttributes, { serialize: false, _skipAutoPersist: true });
             const record = isOrmRecord(created) ? created : null;
             if (!record)
                 return 500;
@@ -283,13 +311,13 @@ export default class OrmRequest extends Request {
                     }
                 }
                 if (Object.keys(relUpdates).length > 0) {
-                    updateRecord(record, relUpdates);
+                    updateRecord(record, relUpdates, { _skipAutoPersist: true });
                 }
             }
             return { data: record.toJSON?.() };
         };
         const deleteHandler = ({ params }) => {
-            store.remove(model, getId(params));
+            store.remove(model, getId(params), { _skipAutoPersist: true });
             return 204;
         };
         // Wrap handlers with hooks
@@ -348,7 +376,11 @@ export default class OrmRequest extends Request {
             }
             // Execute main handler
             const response = await handler(request, state);
-            // Persist to SQL database for write operations
+            // Set context.record for update BEFORE persist so SQL drivers can read it
+            if (operation === 'update' && response?.data) {
+                context.record = store.get(this.model, getId(request.params));
+            }
+            // Persist to SQL database for all write operations (create/update/delete)
             const sqlDb = Orm.instance.sqlDb;
             if (sqlDb && WRITE_OPERATIONS.has(operation)) {
                 await sqlDb.persist(operation, this.model, context, response);
@@ -367,9 +399,6 @@ export default class OrmRequest extends Request {
                 const recordId = isNaN(responseData.id) ? responseData.id : parseInt(responseData.id);
                 context.record = store.get(this.model, recordId);
             }
-            else if (operation === 'update' && response?.data) {
-                context.record = store.get(this.model, getId(request.params));
-            }
             else if (operation === 'delete') {
                 // For delete, the record may no longer exist, but we have oldState
                 context.recordId = getId(request.params);
@@ -396,7 +425,7 @@ export default class OrmRequest extends Request {
                 if (!record)
                     return 404;
                 const relatedData = record.__relationships[relationshipName];
-                const baseUrl = getBaseUrl(request);
+                const baseUrl = getBaseUrl(request, pluralizedModel);
                 let data;
                 if (info.isArray) {
                     // hasMany - return array
@@ -418,7 +447,7 @@ export default class OrmRequest extends Request {
                 if (!record)
                     return 404;
                 const relatedData = record.__relationships[relationshipName];
-                const baseUrl = getBaseUrl(request);
+                const baseUrl = getBaseUrl(request, pluralizedModel);
                 let data;
                 if (info.isArray) {
                     // hasMany - return array of linkage objects
@@ -463,6 +492,35 @@ export default class OrmRequest extends Request {
         return routes;
     }
     auth(request, state) {
+        // abofs/stonyx-orm#270 — hand the predicate the value the record is
+        // ACTUALLY resolved by, rather than the raw text it was parsed from.
+        //
+        // This is the default path precisely because it requires the consumer to
+        // remember nothing. Exporting `normalizeRecordId` alone would leave the
+        // framework owning resolution while asking every consumer to call one
+        // function, with no signal when they forget — the same silent fail-open,
+        // one step over. The export is the escape hatch for hooks and custom
+        // handlers; this line is the contract.
+        //
+        // `request.params` is deliberately NOT mutated. Twelve `getId(...)` call
+        // sites read it, and `_withHooks` assigns `params: request.params` onto the
+        // hook context, so every consumer hook reads the same object. Changing
+        // `params.id` from string to number underneath them is a silent behaviour
+        // change on paths this issue is not about.
+        //
+        // Synchronous by necessity: @stonyx/rest-server calls auth() without
+        // awaiting it.
+        //
+        // The `undefined` branch is a PRESENCE check, not a second normalisation:
+        // it answers "does this route carry an :id at all", which is how both
+        // documented samples tell a collection request from a record request. It
+        // cannot be folded into normalizeRecordId, because that function must keep
+        // returning '' for a falsy id — `store.get(key, undefined)` returns the
+        // whole model Map rather than a record (abofs/stonyx-orm#167, pinned by
+        // test/unit/store-get-falsy-id-test.ts), so the resolution path depends on
+        // the '' it returns today.
+        const rawId = request.params?.id;
+        request.recordId = rawId === undefined ? undefined : normalizeRecordId(rawId);
         const access = this.access(request);
         if (!access)
             return 403;

package/dist/postgres/column-rules.d.ts

@@ -0,0 +1,33 @@
+import type { ColumnRule } from '../column-conversion.js';
+/**
+ * PostgreSQL's write-path conversion rule (#292).
+ *
+ * JSONB columns must receive a JSON *string*. node-pg's `prepareValue`
+ * (`pg/lib/utils.js`) checks `Array.isArray` before its object fallback, so a
+ * raw array is rendered as a Postgres array literal (`{"1","2","3"}`) rather
+ * than JSON. `[]` becomes `{}`, which is valid JSON, so it lands silently
+ * corrupted with no error.
+ *
+ * Two behaviours this rule must keep:
+ *
+ *  - `typeof value === 'string'` passes through untouched. A JSONB column
+ *    already holding a JSON string (`'{"a":1}'`) must store the object it
+ *    describes; an unconditional `JSON.stringify` would double-encode it.
+ *  - An `undefined` column type is a no-op. `updated_at`, `id` and FK columns
+ *    are added outside the attribute loop and are absent from
+ *    `schema.columns`.
+ *
+ * The `'JSONB'` sentinel is the exact literal emitted by
+ * `src/postgres/type-map.ts`, the only module that produces the values in
+ * `schema.columns`. The two producing functions are `getPgType` and
+ * `getVectorType` (`src/postgres/schema-introspector.ts` writes `columns[key]`
+ * at exactly three sites, all routed through those two); `mysqlTypeToPg` is not
+ * exported and is reachable only from inside `getPgType`.
+ *
+ * One documented gap: `getPgType` returns a consumer transform's declared
+ * `pgType` verbatim, so a consumer writing `pgType: 'jsonb'` puts a value in
+ * `schema.columns` that type-map never authored and this exact-match sentinel
+ * misses. It misses identically on the create path, pre-fix and post-fix --
+ * pre-existing and symmetric, not introduced here.
+ */
+export declare const postgresJsonRule: ColumnRule;

package/dist/postgres/column-rules.js

@@ -0,0 +1,34 @@
+/**
+ * PostgreSQL's write-path conversion rule (#292).
+ *
+ * JSONB columns must receive a JSON *string*. node-pg's `prepareValue`
+ * (`pg/lib/utils.js`) checks `Array.isArray` before its object fallback, so a
+ * raw array is rendered as a Postgres array literal (`{"1","2","3"}`) rather
+ * than JSON. `[]` becomes `{}`, which is valid JSON, so it lands silently
+ * corrupted with no error.
+ *
+ * Two behaviours this rule must keep:
+ *
+ *  - `typeof value === 'string'` passes through untouched. A JSONB column
+ *    already holding a JSON string (`'{"a":1}'`) must store the object it
+ *    describes; an unconditional `JSON.stringify` would double-encode it.
+ *  - An `undefined` column type is a no-op. `updated_at`, `id` and FK columns
+ *    are added outside the attribute loop and are absent from
+ *    `schema.columns`.
+ *
+ * The `'JSONB'` sentinel is the exact literal emitted by
+ * `src/postgres/type-map.ts`, the only module that produces the values in
+ * `schema.columns`. The two producing functions are `getPgType` and
+ * `getVectorType` (`src/postgres/schema-introspector.ts` writes `columns[key]`
+ * at exactly three sites, all routed through those two); `mysqlTypeToPg` is not
+ * exported and is reachable only from inside `getPgType`.
+ *
+ * One documented gap: `getPgType` returns a consumer transform's declared
+ * `pgType` verbatim, so a consumer writing `pgType: 'jsonb'` puts a value in
+ * `schema.columns` that type-map never authored and this exact-match sentinel
+ * misses. It misses identically on the create path, pre-fix and post-fix --
+ * pre-existing and symmetric, not introduced here.
+ */
+export const postgresJsonRule = (value, columnType) => columnType === 'JSONB' && typeof value !== 'string'
+    ? JSON.stringify(value)
+    : value;

package/dist/postgres/connection.d.ts

@@ -6,6 +6,7 @@ interface PgConfig {
     password: string;
     database: string;
     connectionLimit: number;
+    [key: string]: unknown;
 }
 /**
  * Create or return the singleton pg Pool.

package/dist/postgres/connection.js

@@ -7,15 +7,17 @@ export async function getPool(pgConfig, extensions = ['vector']) {
     if (pool)
         return pool;
     const { default: pg } = await import('pg');
+    const { host, port, user, password, database, connectionLimit, migrationsDir, migrationsTable, autoMigrate, ...poolOpts } = pgConfig;
     pool = new pg.Pool({
-        host: pgConfig.host,
-        port: pgConfig.port,
-        user: pgConfig.user,
-        password: pgConfig.password,
-        database: pgConfig.database,
-        max: pgConfig.connectionLimit,
+        host,
+        port,
+        user,
+        password,
+        database,
+        max: connectionLimit,
         idleTimeoutMillis: 30000,
         connectionTimeoutMillis: 10000,
+        ...poolOpts,
     });
     // Enable requested PostgreSQL extensions
     for (const ext of extensions) {

package/dist/postgres/postgres-db.d.ts

@@ -8,6 +8,8 @@ import { createRecord } from '../manage-record.js';
 import { confirm } from '@stonyx/utils/prompt';
 import { readFile } from '@stonyx/utils/file';
 import { getPluralName } from '../plural-registry.js';
+import { convertRow } from '../column-conversion.js';
+import { postgresJsonRule } from './column-rules.js';
 import config from 'stonyx/config';
 import log from 'stonyx/log';
 import path from 'path';
@@ -17,6 +19,7 @@ interface PersistContext {
     record?: OrmRecord;
     recordId?: unknown;
     oldState?: Record<string, unknown>;
+    rawData?: Record<string, unknown>;
 }
 interface PersistResponse {
     data?: {
@@ -56,6 +59,8 @@ interface PostgresDeps {
     confirm: typeof confirm;
     readFile: typeof readFile;
     getPluralName: typeof getPluralName;
+    convertRow: typeof convertRow;
+    postgresJsonRule: typeof postgresJsonRule;
     config: typeof config;
     log: typeof log;
     path: typeof path;
@@ -71,6 +76,14 @@ export default class PostgresDB {
     deps: PostgresDeps;
     pool: Pool | null;
     pgConfig: Record<string, unknown>;
+    /**
+     * Promise-chain mutex for write serialization (#156).
+     * All persist() calls chain through this single queue so concurrent
+     * fire-and-forget writes never produce parallel transactions
+     * on FK-linked rows (which cause deadlocks).
+     * Reads are NOT affected — only persist() serializes.
+     */
+    private _writeQueue;
     constructor(deps?: Partial<PostgresDeps>);
     protected requirePool(): Pool;
     init(): Promise<void>;