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

package/dist/postgres/postgres-db.js

@@ -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 { isDbError } from '../utils.js';
 import config from 'stonyx/config';
 import log from 'stonyx/log';
@@ -18,7 +20,8 @@ const defaultDeps = {
     introspectModels, introspectViews, getTopologicalOrder, schemasToSnapshot,
     loadLatestSnapshot, detectSchemaDrift,
     buildInsert, buildUpdate, buildDelete, buildSelect, buildVectorSearch, buildHybridSearch,
-    createRecord, store, confirm, readFile, getPluralName, config, log, path
+    createRecord, store, confirm, readFile, getPluralName, config, log, path,
+    convertRow, postgresJsonRule
 };
 export default class PostgresDB {
     /** PostgreSQL extensions to enable on pool init. Subclasses can override. */
@@ -30,6 +33,14 @@ export default class PostgresDB {
     deps;
     pool;
     pgConfig;
+    /**
+     * 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.
+     */
+    _writeQueue = Promise.resolve();
     constructor(deps = {}) {
         const Ctor = this.constructor;
         if (Ctor.instance)
@@ -57,7 +68,17 @@ export default class PostgresDB {
         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.pgConfig.autoMigrate === true) {
+                shouldApply = true;
+            }
+            else if (this.pgConfig.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 +97,17 @@ export default class PostgresDB {
             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.pgConfig.autoMigrate === true) {
+                    shouldGenerate = true;
+                }
+                else if (this.pgConfig.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');
@@ -356,16 +387,22 @@ export default class PostgresDB {
         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) {
+    async _persistCreate(modelName, context, response) {
         const schemas = this.deps.introspectModels();
         const schema = schemas[modelName];
         if (!schema)
@@ -375,13 +412,17 @@ export default class PostgresDB {
         const record = recordId != null ? storeRef.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
-        const isPendingId = record.__data.__pendingSqlId;
+        const insertData = this._recordToRow(record, schema, context.rawData);
+        // 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;
         }
-        const { sql, values } = this.deps.buildInsert(schema.table, insertData);
+        // Convert the *complete* payload (attributes + id + FKs) in one place (#292).
+        const row = this.deps.convertRow(insertData, schema.columns, this.deps.postgresJsonRule);
+        const { sql, values } = this.deps.buildInsert(schema.table, row);
         const result = await this.requirePool().query(sql, values);
         // Re-key the record in the store if PostgreSQL generated the ID (via RETURNING)
         if (isPendingId && result.rows.length > 0) {
@@ -420,7 +461,10 @@ export default class PostgresDB {
         // Check FK changes too
         for (const fkCol of Object.keys(schema.foreignKeys)) {
             const relName = fkCol.replace(/_id$/, '');
-            const currentFkValue = record.__relationships[relName]?.id ?? null;
+            const relValue = record.__relationships[relName];
+            const currentFkValue = (relValue && typeof relValue === 'object' && relValue !== null)
+                ? relValue.id ?? null
+                : relValue ?? record.__data[relName] ?? null;
             const oldFkValue = oldState[relName] ?? null;
             if (currentFkValue !== oldFkValue) {
                 changedData[fkCol] = currentFkValue;
@@ -430,7 +474,11 @@ export default class PostgresDB {
             return;
         // PostgreSQL doesn't have ON UPDATE CURRENT_TIMESTAMP -- set updated_at manually
         changedData.updated_at = new Date();
-        const { sql, values } = this.deps.buildUpdate(schema.table, id, changedData);
+        // Same conversion, same choke point as the create path (#292). Columns
+        // appended after the attribute loop (FKs, updated_at) are absent from
+        // schema.columns and pass through untouched.
+        const row = this.deps.convertRow(changedData, schema.columns, this.deps.postgresJsonRule);
+        const { sql, values } = this.deps.buildUpdate(schema.table, id, row);
         await this.requirePool().query(sql, values);
     }
     async _persistDelete(modelName, context) {
@@ -444,33 +492,38 @@ export default class PostgresDB {
         const { sql, values } = this.deps.buildDelete(schema.table, id);
         await this.requirePool().query(sql, values);
     }
-    _recordToRow(record, schema) {
+    _recordToRow(record, schema, rawData) {
         const row = {};
         const data = record.__data;
         // ID
         if (data.id !== undefined) {
             row.id = data.id;
         }
-        // Attribute columns
-        for (const [col, pgType] of Object.entries(schema.columns)) {
+        // Attribute columns. Type conversion is NOT applied here -- it is applied
+        // once to the finished payload by the caller, via convertRow (#292).
+        for (const col of Object.keys(schema.columns)) {
             if (data[col] !== undefined) {
-                // JSONB columns: stringify non-string values for PostgreSQL JSONB storage
-                row[col] = pgType === 'JSONB' && typeof data[col] !== 'string'
-                    ? JSON.stringify(data[col])
-                    : data[col];
+                row[col] = data[col];
             }
         }
         // FK columns from relationships
         for (const fkCol of Object.keys(schema.foreignKeys)) {
             const relName = fkCol.replace(/_id$/, '');
             const related = record.__relationships[relName];
-            if (related) {
+            if (related && typeof related === 'object' && related !== null) {
                 row[fkCol] = related.id;
             }
+            else if (related != null) {
+                // Raw FK value (e.g., string ID stored directly in __relationships)
+                row[fkCol] = related;
+            }
             else if (data[relName] !== undefined) {
-                // Raw FK value (e.g., from create payload)
                 row[fkCol] = data[relName];
             }
+            else if (rawData?.[relName] !== undefined) {
+                // Fallback to original create payload for unresolved belongsTo FKs
+                row[fkCol] = rawData[relName];
+            }
         }
         return row;
     }

package/dist/record.js

@@ -40,11 +40,13 @@ export default class Record {
         const records = {};
         for (const [key, childRecord] of Object.entries(this.__relationships)) {
             if (Array.isArray(childRecord)) {
+                // Filter out cleaned records (those with no __model)
+                const live = childRecord.filter((r) => r?.__model);
                 // Deduplicate by record ID — keep last occurrence (latest data wins)
                 const seen = new Set();
                 const unique = [];
-                for (let i = childRecord.length - 1; i >= 0; i--) {
-                    const r = childRecord[i];
+                for (let i = live.length - 1; i >= 0; i--) {
+                    const r = live[i];
                     if (!seen.has(r.id)) {
                         seen.add(r.id);
                         unique.push(r);
@@ -54,7 +56,7 @@ export default class Record {
                 records[key] = unique.map((r) => r.serialize());
             }
             else {
-                records[key] = childRecord?.serialize() ?? null;
+                records[key] = childRecord?.__model ? childRecord.serialize() : null;
             }
         }
         return { ...data, ...records };
@@ -86,8 +88,8 @@ export default class Record {
             if (fields && !fields.has(key))
                 continue;
             const relationshipData = Array.isArray(childRecord)
-                ? childRecord.map((r) => ({ type: r.__model.__name, id: r.id }))
-                : childRecord ? { type: childRecord.__model.__name, id: childRecord.id } : null;
+                ? childRecord.filter((r) => r?.__model).map((r) => ({ type: r.__model.__name, id: r.id }))
+                : (childRecord && childRecord.__model) ? { type: childRecord.__model.__name, id: childRecord.id } : null;
             // Dasherize the key for URL paths (e.g., accessLinks -> access-links)
             const dasherizedKey = camelCaseToKebabCase(key);
             relationships[dasherizedKey] = { data: relationshipData };

package/dist/relationships.js

@@ -38,4 +38,4 @@ export function getPendingRegistry() {
 export function getPendingBelongsToRegistry() {
     return relationships.get('pendingBelongsTo');
 }
-export const TYPES = ['global', 'hasMany', 'belongsTo', 'pending'];
+export const TYPES = ['global', 'hasMany', 'belongsTo', 'pending', 'pendingBelongsTo'];

package/dist/serializer.js

@@ -79,8 +79,44 @@ export default class Serializer {
                 // Pass relationship key name to handler for pending fulfillment
                 const handlerOptions = { ...options, _relationshipKey: key };
                 const childRecord = handler(record, data, handlerOptions);
-                rec[key] = childRecord;
-                relatedRecords[key] = childRecord;
+                // hasMany relationships use a getter so format()/toJSON() always read
+                // the live registry array instead of a stale snapshot captured at
+                // serialization time.  This is critical when child records are created
+                // in a later async frame — the belongsTo inverse wiring pushes into
+                // the shared registry array, and the getter ensures the parent sees it.
+                const isHasMany = handler.__relationshipType === 'hasMany';
+                if (isHasMany) {
+                    // `childRecord` IS the shared registry array — define a getter that
+                    // always dereferences through the same array reference.
+                    const registryArray = childRecord;
+                    Object.defineProperty(rec, key, {
+                        enumerable: true,
+                        configurable: true,
+                        get: () => registryArray,
+                        set(v) { relatedRecords[key] = v; }
+                    });
+                    Object.defineProperty(relatedRecords, key, {
+                        enumerable: true,
+                        configurable: true,
+                        get: () => registryArray,
+                        set(v) { Object.defineProperty(relatedRecords, key, { value: v, writable: true, enumerable: true, configurable: true }); }
+                    });
+                }
+                else {
+                    rec[key] = childRecord;
+                    relatedRecords[key] = childRecord;
+                    // Preserve the raw FK value in __data when the belongsTo handler
+                    // couldn't resolve the target (e.g., memory:false model not loaded).
+                    // This allows adapters to read the FK from __data as a fallback
+                    // when __relationships[key] is null.  Only store when `data` is a
+                    // truthy non-object — i.e., a raw FK string/number that the handler
+                    // attempted but failed to resolve.  When `data` is null/undefined
+                    // (optional empty relationship) we intentionally skip to preserve
+                    // the existing behavior of not populating __data for empty FKs.
+                    if (childRecord === null && data && typeof data !== 'object') {
+                        parsedData[key] = data;
+                    }
+                }
                 continue;
             }
             // Aggregate property handling — use the rawData value, not the aggregate descriptor

package/dist/store.d.ts

@@ -45,7 +45,19 @@ export default class Store {
      */
     private _isMemoryModel;
     set(key: string, value: Map<number | string, unknown>): void;
-    remove(key: string, id?: number | string): void;
+    remove(key: string, id?: number | string, options?: {
+        _skipAutoPersist?: boolean;
+    }): void;
+    /**
+     * Evict a record from the store with full relationship registry cleanup.
+     * The caller retains its reference to the returned record, which is the
+     * contract memory:false post-persist eviction relies on.
+     *
+     * @param registryId - The ID used when the record's relationships were
+     *   registered. For SQL models with pending IDs, this is the original
+     *   negative pending ID (before the adapter re-keyed to the real DB ID).
+     */
+    evictRecord(modelName: string, id: unknown, registryId?: unknown): void;
     unloadRecord(model: string, id: unknown, options?: UnloadOptions): void;
     unloadAllRecords(model: string, options?: UnloadOptions): void;
     private _removeFromHasManyArrays;

package/dist/store.js

@@ -1,5 +1,5 @@
 import Orm, { relationships } from '@stonyx/orm';
-import { TYPES, getHasManyRegistry, getBelongsToRegistry, getPendingRegistry } from './relationships.js';
+import { TYPES, getHasManyRegistry, getBelongsToRegistry, getPendingRegistry, getPendingBelongsToRegistry } from './relationships.js';
 import ViewResolver from './view-resolver.js';
 function isStoreRecord(value) {
     return typeof value === 'object' && value !== null && '__data' in value;
@@ -22,7 +22,7 @@ export default class Store {
         this.data = new Map();
     }
     get(key, id) {
-        if (!id)
+        if (id === undefined)
             return this.data.get(key);
         return this.data.get(key)?.get(id);
     }
@@ -107,15 +107,61 @@ export default class Store {
     set(key, value) {
         this.data.set(key, value);
     }
-    remove(key, id) {
+    remove(key, id, options) {
         // Guard: read-only views cannot have records removed
         if (Orm.instance?.isView?.(key)) {
             throw new Error(`Cannot remove records from read-only view '${key}'`);
         }
+        // Auto-persist delete to SQL (fire-and-forget) — skipped when the
+        // request path handles persist itself to avoid double-delete.
+        if (id && Orm.instance?.sqlDb && !options?._skipAutoPersist) {
+            Orm.instance.sqlDb.persist('delete', key, { recordId: id }, {}).catch((err) => {
+                Orm.instance.emitPersistError({
+                    operation: 'delete',
+                    modelName: key,
+                    recordId: id,
+                    error: err instanceof Error ? err : new Error(String(err)),
+                });
+            });
+        }
         if (id)
             return this.unloadRecord(key, id);
         this.unloadAllRecords(key);
     }
+    /**
+     * Evict a record from the store with full relationship registry cleanup.
+     * The caller retains its reference to the returned record, which is the
+     * contract memory:false post-persist eviction relies on.
+     *
+     * @param registryId - The ID used when the record's relationships were
+     *   registered. For SQL models with pending IDs, this is the original
+     *   negative pending ID (before the adapter re-keyed to the real DB ID).
+     */
+    evictRecord(modelName, id, registryId) {
+        const modelStore = this.data.get(modelName);
+        if (!modelStore)
+            return;
+        if (typeof id !== 'string' && typeof id !== 'number')
+            return;
+        const raw = modelStore.get(id);
+        if (!raw || !isStoreRecord(raw))
+            return;
+        const visited = new Set([`${modelName}:${id}`]);
+        // Remove from hasMany arrays and nullify belongsTo references using current ID
+        // (the adapter updates record.id, so value-based matches need the current ID)
+        this._removeFromHasManyArrays(modelName, id, visited);
+        this._nullifyBelongsToReferences(modelName, id, visited);
+        // Clean up relationship registry entries using the registry key
+        // (belongsTo/hasMany registries were keyed by the ID at registration time,
+        // which may differ from the current ID if SQL persist re-keyed the record)
+        const cleanupId = registryId ?? id;
+        this._cleanupRelationshipRegistries(modelName, cleanupId);
+        // If registryId differs from id, also clean with current id as safety net
+        if (registryId !== undefined && registryId !== id) {
+            this._cleanupRelationshipRegistries(modelName, id);
+        }
+        modelStore.delete(id);
+    }
     unloadRecord(model, id, options = {}) {
         const modelStore = this.data.get(model);
         if (!modelStore) {
@@ -138,7 +184,6 @@ export default class Store {
             this._removeFromHasManyArrays(modelName, recordId, visited);
             this._nullifyBelongsToReferences(modelName, recordId, visited);
             this._cleanupRelationshipRegistries(modelName, recordId);
-            recordToUnload.clean();
             this.data.get(modelName)?.delete(recordId);
         }
     }
@@ -219,6 +264,31 @@ export default class Store {
         const pendingMap = getPendingRegistry().get(modelName);
         if (pendingMap)
             pendingMap.delete(recordId);
+        // Clean pendingBelongsTo entries in both directions
+        const pendingBelongsToMap = getPendingBelongsToRegistry();
+        if (pendingBelongsToMap) {
+            // Direction 1: evicted record was the TARGET others were waiting for
+            const targetEntries = pendingBelongsToMap.get(modelName);
+            if (targetEntries)
+                targetEntries.delete(recordId);
+            // Direction 2: evicted record was the SOURCE with unresolved forward-references
+            for (const [, targetIdMap] of pendingBelongsToMap) {
+                for (const [targetId, entries] of targetIdMap) {
+                    if (!Array.isArray(entries))
+                        continue;
+                    const filtered = entries.filter((e) => {
+                        const entry = e;
+                        return !(entry.sourceModelName === modelName && entry.relationshipId === recordId);
+                    });
+                    if (filtered.length === 0) {
+                        targetIdMap.delete(targetId);
+                    }
+                    else if (filtered.length < entries.length) {
+                        targetIdMap.set(targetId, filtered);
+                    }
+                }
+            }
+        }
     }
     /**
      * Extracts hasMany and non-bidirectional belongsTo children from a record

package/dist/types/orm-types.d.ts

@@ -16,6 +16,7 @@ export interface OrmMysqlConfig {
     connectionLimit?: number;
     migrationsDir?: string;
     migrationsTable?: string;
+    autoMigrate?: boolean;
     [key: string]: unknown;
 }
 export interface OrmPostgresConfig {
@@ -27,6 +28,7 @@ export interface OrmPostgresConfig {
     connectionLimit?: number;
     migrationsDir?: string;
     migrationsTable?: string;
+    autoMigrate?: boolean;
     [key: string]: unknown;
 }
 export interface OrmPaths {
@@ -42,6 +44,12 @@ export interface OrmRestServerConfig {
     route: string;
     metaRoute: boolean;
 }
+export interface OrmDynamoDBConfig {
+    region?: string;
+    endpoint?: string;
+    tablePrefix?: string;
+    [key: string]: unknown;
+}
 export interface OrmSection {
     db: OrmDbConfig;
     paths: OrmPaths;
@@ -49,6 +57,9 @@ export interface OrmSection {
     mysql?: OrmMysqlConfig;
     postgres?: OrmPostgresConfig;
     timescale?: OrmPostgresConfig;
+    dynamodb?: OrmDynamoDBConfig;
+    logColor?: string;
+    logMethod?: string;
     [key: string]: unknown;
 }
 export interface OrmConfig {

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.3.2-beta.3",
+  "version": "0.3.2-beta.300",
   "description": "",
   "main": "dist/index.js",
   "type": "module",
@@ -61,16 +61,25 @@
   },
   "homepage": "https://github.com/abofs/stonyx-orm#readme",
   "dependencies": {
-    "@stonyx/cron": "0.2.1-beta.29",
-    "@stonyx/events": "0.1.1-beta.9",
-    "stonyx": "0.2.3-beta.11"
+    "@stonyx/cron": "0.2.1-beta.159",
+    "@stonyx/events": "0.1.1-beta.71",
+    "@stonyx/utils": "0.2.3-beta.28",
+    "stonyx": "0.2.3-beta.104"
   },
   "peerDependencies": {
+    "@aws-sdk/client-dynamodb": "^3.0.0",
+    "@aws-sdk/lib-dynamodb": "^3.0.0",
     "@stonyx/rest-server": ">=0.2.1-beta.14",
     "mysql2": "^3.0.0",
     "pg": "^8.0.0"
   },
   "peerDependenciesMeta": {
+    "@aws-sdk/client-dynamodb": {
+      "optional": true
+    },
+    "@aws-sdk/lib-dynamodb": {
+      "optional": true
+    },
     "mysql2": {
       "optional": true
     },
@@ -82,18 +91,22 @@
     }
   },
   "devDependencies": {
-    "@stonyx/rest-server": "0.2.1-beta.30",
-    "@stonyx/utils": "0.2.3-beta.7",
+    "@stonyx/rest-server": "0.2.1-beta.162",
     "@types/node": "^25.6.0",
     "mysql2": "^3.20.0",
     "pg": "^8.20.0",
     "qunit": "^2.24.1",
     "sinon": "^21.0.0",
+    "tsx": "^4.21.0",
     "typescript": "^5.8.3"
   },
   "scripts": {
     "build": "tsc",
     "build:test": "tsc -p tsconfig.test.json",
-    "test": "npm run build && npm run build:test && stonyx test 'dist-test/test/**/*-test.js'"
+    "test": "pnpm build && NODE_ENV=test node --import tsx/esm --import ./test/setup.ts node_modules/qunit/bin/qunit.js 'test/**/*-test.ts' && ORM_TEST_ROUTE=/ pnpm test:mounted && ORM_TEST_ROUTE=/api pnpm test:mounted && ORM_TEST_ROUTE=api pnpm test:mounted && ORM_TEST_ROUTE=/api/v1 pnpm test:mounted && ORM_TEST_ROUTE=/api/ pnpm test:mounted && pnpm test:readme && pnpm test:reference",
+    "test:mounted": "node --import tsx/esm --import ./test/integration/mounted-route/setup.ts node_modules/qunit/bin/qunit.js 'test/integration/mounted-route/links-mounted.ts' 'test/zz-exit-test.ts'",
+    "test:readme": "pnpm build && node --import tsx/esm --import ./test/integration/readme-access/setup.ts node_modules/qunit/bin/qunit.js 'test/integration/readme-access/readme-sample.ts' 'test/zz-exit-test.ts'",
+    "test:reference": "pnpm build && node --import tsx/esm --import ./test/integration/reference-access/setup.ts node_modules/qunit/bin/qunit.js 'test/integration/reference-access/reference-sample.ts' 'test/integration/reference-access/record-id-resolution.ts' 'test/zz-exit-test.ts'",
+    "test:dynamodb": "pnpm build && node --import tsx/esm --import ./test/integration/dynamodb/setup.ts node_modules/qunit/bin/qunit.js 'test/integration/dynamodb/**/*-test.ts'"
   }
 }

package/src/column-conversion.ts

@@ -0,0 +1,53 @@
+/**
+ * Shared write-path column conversion (#292).
+ *
+ * This module owns the *iteration* only — the single place where a write
+ * payload is walked column-by-column and each value is handed to the driver's
+ * own conversion rule. The rules themselves are genuinely disjoint per driver
+ * (Postgres stringifies for JSONB; DynamoDB's DocumentClient marshals objects
+ * and arrays natively and must NOT be given stringified values) and therefore
+ * deliberately live with their drivers rather than being merged here.
+ *
+ * The duplicated create/update iteration was the drift vector that produced
+ * #292: `_recordToRow` converted, `_persistUpdate` did not. Routing both
+ * through `convertRow` removes the opportunity for the two to diverge again.
+ */
+
+/**
+ * A driver-supplied per-column conversion rule.
+ *
+ * @param value      the raw value about to be bound into the query
+ * @param columnType the column's declared type from `schema.columns`, or
+ *                   `undefined` when the column is not an attribute column
+ *                   (e.g. `updated_at`, FK columns and `id`, which are added
+ *                   outside the attribute loop). Rules MUST be a no-op for
+ *                   `undefined`.
+ */
+export type ColumnRule = (value: unknown, columnType: string | undefined) => unknown;
+
+/**
+ * Applies `rule` to every column of a complete write payload.
+ *
+ * Call this on the *finished* payload immediately before handing it to the
+ * query builder — not inside a payload-building loop. Columns appended after
+ * such a loop (FKs, `updated_at`) would otherwise bypass conversion, which is
+ * the same class of defect #292 reports.
+ */
+export function convertRow(
+  row: Record<string, unknown>,
+  columns: Record<string, string>,
+  rule: ColumnRule
+): Record<string, unknown> {
+  const converted: Record<string, unknown> = {};
+
+  for (const [col, value] of Object.entries(row)) {
+    // `Object.hasOwn`, not `columns[col]`: a column named `toString` or
+    // `constructor` would otherwise reach the rule with a function as its
+    // "declared type". Inert for the shipped Postgres rule (strict equality
+    // against 'JSONB'), but `ColumnRule` is the extension point other drivers
+    // write against, and the obvious `if (columnType)` rule would invert.
+    converted[col] = rule(value, Object.hasOwn(columns, col) ? columns[col] : undefined);
+  }
+
+  return converted;
+}

package/src/commands.ts

@@ -28,6 +28,13 @@ const commands: Record<string, Command> = {
     description: 'Generate a MySQL migration from current model schemas',
     bootstrap: true,
     run: async (args) => {
+      const config = (await import('stonyx/config')).default;
+
+      if (config.orm.dynamodb) {
+        console.log('DynamoDB does not use file-based migrations. Use db:sync to provision tables.');
+        return;
+      }
+
       const description = args?.join(' ') || 'migration';
       const { generateMigration } = await import('./mysql/migration-generator.js');
       const result = await generateMigration(description);
@@ -39,6 +46,25 @@ const commands: Record<string, Command> = {
       }
     }
   },
+  'db:sync': {
+    description: 'Provision DynamoDB tables and GSIs from current model schemas',
+    bootstrap: true,
+    run: async () => {
+      const config = (await import('stonyx/config')).default;
+
+      if (!config.orm.dynamodb) {
+        console.error('DynamoDB is not configured. Set DYNAMODB_REGION (and optionally DYNAMODB_ENDPOINT) to enable DynamoDB mode.');
+        process.exit(1);
+      }
+
+      const { default: DynamoDBDB } = await import('./dynamodb/dynamodb-db.js');
+      const db = new DynamoDBDB();
+      await db.init();
+      await db.startup();
+      await db.shutdown();
+      console.log('DynamoDB tables synced successfully.');
+    }
+  },
   'db:migrate': {
     description: 'Apply pending MySQL migrations',
     bootstrap: true,
@@ -46,6 +72,11 @@ const commands: Record<string, Command> = {
       const config = (await import('stonyx/config')).default;
       const mysqlConfig = config.orm.mysql;
 
+      if (config.orm.dynamodb) {
+        console.log('DynamoDB does not use file-based migrations. Use db:sync to provision tables.');
+        return;
+      }
+
       if (!mysqlConfig) {
         console.error('MySQL is not configured. Set MYSQL_HOST to enable MySQL mode.');
         process.exit(1);
@@ -92,6 +123,12 @@ const commands: Record<string, Command> = {
     bootstrap: true,
     run: async () => {
       const config = (await import('stonyx/config')).default;
+
+      if (config.orm.dynamodb) {
+        console.log('DynamoDB does not support migration rollback. Manage table changes via the AWS console or db:sync.');
+        return;
+      }
+
       const mysqlConfig = config.orm.mysql;
 
       if (!mysqlConfig) {
@@ -138,6 +175,12 @@ const commands: Record<string, Command> = {
     bootstrap: true,
     run: async () => {
       const config = (await import('stonyx/config')).default;
+
+      if (config.orm.dynamodb) {
+        console.log('DynamoDB does not use file-based migrations. Use db:sync to provision tables.');
+        return;
+      }
+
       const mysqlConfig = config.orm.mysql;
 
       if (!mysqlConfig) {