@bsv/wallet-toolbox 2.1.24 → 3.0.0-alpha.0

package/out/src/storage/StorageKnex.js

@@ -10,17 +10,204 @@ const listOutputsKnex_1 = require("./methods/listOutputsKnex");
 const reviewStatus_1 = require("./methods/reviewStatus");
 const WERR_errors_1 = require("../sdk/WERR_errors");
 const utilityHelpers_1 = require("../utility/utilityHelpers");
+const types_1 = require("../sdk/types");
+const transactionService_1 = require("./schema/transactionService");
 class StorageKnex extends StorageProvider_1.StorageProvider {
     constructor(options) {
         super(options);
+        this._postCutoverCache = undefined;
         this._verifiedReadyForDatabaseAccess = false;
         if (!options.knex)
-            throw new WERR_errors_1.WERR_INVALID_PARAMETER('options.knex', `valid`);
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('options.knex', 'valid');
         this.knex = options.knex;
     }
+    getTransactionService() {
+        // The new-schema transaction service is only valid post-cutover. Pre-cutover,
+        // the `transactions` table is the legacy schema and queries via this service
+        // would return legacy ids that don't satisfy the `tx_audit.transactionId`
+        // FK (which targets `transactions_new`). Callers gate on `undefined` and
+        // fall back to the legacy storage path.
+        if (this._postCutoverCache !== true)
+            return undefined;
+        return new transactionService_1.TransactionService(this.knex);
+    }
+    /**
+     * Eagerly warm the `_postCutoverCache` so sync query builders such as
+     * `findOutputsQuery` can branch on cutover state without an extra await.
+     * Callers that have invoked `makeAvailable` are guaranteed the cache has
+     * been populated.
+     */
+    async makeAvailable() {
+        const settings = await super.makeAvailable();
+        if (this._postCutoverCache === undefined) {
+            this._postCutoverCache = await this.knex.schema.hasTable('transactions_legacy');
+        }
+        return settings;
+    }
+    /**
+     * Returns true when the database has been through `runSchemaCutover` (i.e.
+     * `transactions_legacy` exists). Result is cached for the lifetime of this
+     * StorageKnex instance.
+     */
+    async isPostCutover() {
+        if (this._postCutoverCache === undefined) {
+            this._postCutoverCache = await this.knex.schema.hasTable('transactions_legacy');
+        }
+        return this._postCutoverCache;
+    }
+    /**
+     * Maps legacy TransactionStatus values to their ProcessingStatus equivalents
+     * for use in `outputs JOIN transactions` WHERE clauses post-cutover.
+     */
+    legacyStatiToProcessing(stati) {
+        const result = new Set();
+        for (const s of stati) {
+            result.add((0, types_1.transactionStatusToProcessing)(s));
+            if (s === 'unproven') {
+                // 'sent','seen','seen_multi','unconfirmed' all map to legacy 'unproven'
+                result.add('sent');
+                result.add('seen');
+                result.add('seen_multi');
+                result.add('unconfirmed');
+            }
+        }
+        return [...result];
+    }
+    /**
+     * Returns the canonical name of the `proven_txs` table — `proven_txs_legacy`
+     * post-cutover, `proven_txs` otherwise.
+     *
+     * Public so that helper modules (reviewStatus, purgeData) can resolve the
+     * correct table name without duplicating the post-cutover detection logic.
+     */
+    async provenTxsTableName() {
+        return (await this.isPostCutover()) ? 'proven_txs_legacy' : 'proven_txs';
+    }
+    /**
+     * Returns the canonical name of the `proven_tx_reqs` table —
+     * `proven_tx_reqs_legacy` post-cutover, `proven_tx_reqs` otherwise.
+     *
+     * Public so that helper modules (reviewStatus, purgeData) can resolve the
+     * correct table name without duplicating the post-cutover detection logic.
+     */
+    async provenTxReqsTableName() {
+        return (await this.isPostCutover()) ? 'proven_tx_reqs_legacy' : 'proven_tx_reqs';
+    }
+    /**
+     * Insert a legacy-shaped transaction row into the correct table:
+     * - Post-cutover: `transactions_legacy` (the renamed legacy schema table)
+     * - Pre-cutover:     `transactions` (the standard table, same behaviour as `insertTransaction`)
+     *
+     * This allows `createAction` to store unsigned rows (txid unknown) without
+     * conflicting with the new `transactions` table's NOT NULL txid constraint.
+     * A new `transactions` row + `actions` row are created later by `processAction`
+     * once the real txid is known.
+     *
+     * On SQLite, foreign key enforcement is temporarily disabled while inserting
+     * into `transactions_legacy` because the referenced `proven_txs` table was
+     * renamed to `proven_txs_legacy` during the the schema cutover. Since `provenTxId`
+     * is always NULL for new unsigned transactions this is semantically safe.
+     */
+    async insertLegacyTransaction(tx, trx) {
+        const e = await this.validateEntityForInsert(tx, trx);
+        if (e.transactionId === 0)
+            delete e.transactionId;
+        const hasLegacyTable = await this.knex.schema.hasTable('transactions_legacy');
+        const tableName = hasLegacyTable ? 'transactions_legacy' : 'transactions';
+        const isSqlite = this.dbtype === 'SQLite';
+        // On SQLite post-cutover the `transactions_legacy` FK to `proven_txs` is dangling
+        // (proven_txs was renamed to proven_txs_legacy). Temporarily disable FK checks for
+        // this insert since provenTxId is always NULL for a brand-new unsigned transaction.
+        if (isSqlite && hasLegacyTable)
+            await this.knex.raw('PRAGMA foreign_keys = OFF');
+        try {
+            const [id] = await this.toDb(trx)(tableName).insert(e);
+            tx.transactionId = id;
+            return tx.transactionId;
+        }
+        finally {
+            if (isSqlite && hasLegacyTable)
+                await this.knex.raw('PRAGMA foreign_keys = ON');
+        }
+    }
+    /**
+     * Insert a `tx_labels_map` row for a legacy transaction that does not yet
+     * have a `actions.actionId`. On post-cutover SQLite, temporarily disables
+     * FK checks so that the legacy transactionId (which is not yet an actionId)
+     * can be written. processAction will repoint it via repointLabelsToActionId.
+     *
+     * Note: bypasses `validateEntityForInsert` (and therefore `verifyReadyForDatabaseAccess`
+     * which would re-enable FK checks) to ensure the PRAGMA=OFF persists across
+     * the insert statement.
+     */
+    async insertLegacyTxLabelMap(labelMap, trx) {
+        const isSqlite = this.dbtype === 'SQLite';
+        const hasLegacyTable = isSqlite ? await this.knex.schema.hasTable('transactions_legacy') : false;
+        if (!isSqlite || !hasLegacyTable) {
+            // Pre-cutover or non-SQLite: standard insert is safe (no dangling FK issue).
+            await this.insertTxLabelMap(labelMap, trx);
+            return;
+        }
+        // Post-cutover SQLite: tx_labels_map.transactionId FK now points to actions.actionId.
+        // We are writing a legacyTransactionId (no corresponding actions row yet).
+        // Temporarily disable FK checks for this single insert.
+        const now = new Date();
+        const e = {
+            created_at: now,
+            updated_at: now,
+            txLabelId: labelMap.txLabelId,
+            transactionId: labelMap.transactionId,
+            isDeleted: labelMap.isDeleted ? 1 : 0
+        };
+        // Use the raw knex handle (not toDb(trx)) to send the PRAGMA on the same connection.
+        await this.knex.raw('PRAGMA foreign_keys = OFF');
+        try {
+            await this.knex('tx_labels_map').insert(e);
+        }
+        finally {
+            await this.knex.raw('PRAGMA foreign_keys = ON');
+        }
+    }
     async readSettings() {
         return this.validateEntity((0, utilityHelpers_1.verifyOne)(await this.toDb(undefined)('settings')));
     }
+    /**
+     * Synthesise a `ProvenOrRawTx` from a `TableTransactionNew` row.
+     *
+     * - If the new schema row carries a `merklePath` (i.e. processing is `proven`), build
+     *   a `TableProvenTx`-shaped object so the BEEF assembly code can extract the
+     *   merkle path and merge it into the Beef without hitting the legacy tables.
+     * - If the new schema row only has `rawTx` (broadcast/queued state), return it as the
+     *   raw-tx path.
+     * - Returns `null` when the new schema row has neither rawTx nor merklePath.
+     */
+    newTxToProvenOrRawTx(row, txid) {
+        var _a, _b, _c, _d;
+        // Only use the new-schema row as the primary source when it carries a *non-empty*
+        // merklePath and a rawTx — both are required for `handleProvenTxBranch` to assemble
+        // a valid BEEF.  An empty merklePath (e.g. a backfill race or a req whose proof was
+        // never stored) must fall through to the legacy `proven_txs_legacy` path.
+        // Raw-tx-only rows (no merklePath) are likewise forwarded to the legacy path so
+        // that the legacy `inputBEEF` column is available for recursive BEEF assembly.
+        if (row.merklePath != null && row.merklePath.length > 0 && row.rawTx != null && row.rawTx.length > 0) {
+            // Full proof available — synthesise TableProvenTx shape
+            const proven = {
+                created_at: row.created_at,
+                updated_at: row.updated_at,
+                provenTxId: row.transactionId,
+                txid,
+                height: (_a = row.height) !== null && _a !== void 0 ? _a : 0,
+                index: (_b = row.merkleIndex) !== null && _b !== void 0 ? _b : 0,
+                merklePath: row.merklePath,
+                rawTx: row.rawTx,
+                blockHash: (_c = row.blockHash) !== null && _c !== void 0 ? _c : '',
+                merkleRoot: (_d = row.merkleRoot) !== null && _d !== void 0 ? _d : ''
+            };
+            return { proven, rawTx: undefined, inputBEEF: undefined };
+        }
+        // No complete proof in new-schema row — let the caller fall through to legacy tables.
+        return null;
+    }
     async getProvenOrRawTx(txid, trx) {
         const k = this.toDb(trx);
         const r = {
@@ -28,9 +215,29 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
             rawTx: undefined,
             inputBEEF: undefined
         };
-        r.proven = (0, utilityHelpers_1.verifyOneOrNone)(await this.findProvenTxs({ partial: { txid: txid } }));
-        if (!r.proven) {
-            const reqRawTx = (0, utilityHelpers_1.verifyOneOrNone)(await k('proven_tx_reqs')
+        // Post-cutover: try new `transactions` table first. The new schema row is the single
+        // source of truth for rawTx and merklePath; legacy tables are read-only
+        // archives after cutover.
+        if (await this.isPostCutover()) {
+            try {
+                const txSvc = this.getTransactionService();
+                if (txSvc != null) {
+                    const newTx = await txSvc.findByTxid(txid);
+                    if (newTx != null) {
+                        const newTxResult = this.newTxToProvenOrRawTx(newTx, txid);
+                        if (newTxResult != null)
+                            return newTxResult;
+                    }
+                }
+            }
+            catch (_a) {
+                // new table lookup failed (e.g. table not yet available) — fall through to legacy
+            }
+        }
+        r.proven = (0, utilityHelpers_1.verifyOneOrNone)(await this.findProvenTxs({ partial: { txid } }));
+        if (r.proven == null) {
+            const reqTable = await this.provenTxReqsTableName();
+            const reqRawTx = (0, utilityHelpers_1.verifyOneOrNone)(await k(reqTable)
                 .where('txid', txid)
                 .whereIn('status', ['unsent', 'unmined', 'unconfirmed', 'sending', 'nosend', 'completed'])
                 .select('rawTx', 'inputBEEF'));
@@ -46,38 +253,50 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
             return `substring(${source} from ${fromOffset} for ${forLength})`;
         return `substr(${source}, ${fromOffset}, ${forLength})`;
     }
+    normaliseKnexRawResult(rs) {
+        if (this.dbtype === 'MySQL')
+            return rs[0];
+        return rs;
+    }
+    async getRawTxSlice(txid, offset, length, trx) {
+        // Post-cutover: try new transactions table first — the new table is the canonical store
+        // for rawTx after the cutover. Apply the slice in JS to avoid raw SQL
+        // column naming differences between the two schemas.
+        if (await this.isPostCutover()) {
+            try {
+                const txSvc = this.getTransactionService();
+                if (txSvc != null) {
+                    const newTx = await txSvc.findByTxid(txid);
+                    if ((newTx === null || newTx === void 0 ? void 0 : newTx.rawTx) != null) {
+                        return newTx.rawTx.slice(offset, offset + length);
+                    }
+                }
+            }
+            catch (_a) {
+                // new table lookup failed — fall through to legacy tables
+            }
+        }
+        const sub = this.dbTypeSubstring('rawTx', offset + 1, length);
+        const provenTable = await this.provenTxsTableName();
+        const reqTable = await this.provenTxReqsTableName();
+        let rs = await this.toDb(trx).raw(`select ${sub} as rawTx from ${provenTable} where txid = '${txid}'`);
+        const proven = (0, utilityHelpers_1.verifyOneOrNone)(this.normaliseKnexRawResult(rs));
+        if ((proven === null || proven === void 0 ? void 0 : proven.rawTx) != null)
+            return Array.from(proven.rawTx);
+        rs = await this.toDb(trx).raw(`select ${sub} as rawTx from ${reqTable} where txid = '${txid}' and status in ('unsent', 'nosend', 'sending', 'unmined', 'completed', 'unfail')`);
+        const req = (0, utilityHelpers_1.verifyOneOrNone)(this.normaliseKnexRawResult(rs));
+        return (req === null || req === void 0 ? void 0 : req.rawTx) != null ? Array.from(req.rawTx) : undefined;
+    }
     async getRawTxOfKnownValidTransaction(txid, offset, length, trx) {
         if (!txid)
             return undefined;
         if (!this.isAvailable())
             await this.makeAvailable();
-        let rawTx = undefined;
         if (Number.isInteger(offset) && Number.isInteger(length)) {
-            let rs = await this.toDb(trx).raw(`select ${this.dbTypeSubstring('rawTx', offset + 1, length)} as rawTx from proven_txs where txid = '${txid}'`);
-            if (this.dbtype === 'MySQL')
-                rs = rs[0];
-            const r = (0, utilityHelpers_1.verifyOneOrNone)(rs);
-            if (r && r.rawTx) {
-                rawTx = Array.from(r.rawTx);
-            }
-            else {
-                let rs = await this.toDb(trx).raw(`select ${this.dbTypeSubstring('rawTx', offset + 1, length)} as rawTx from proven_tx_reqs where txid = '${txid}' and status in ('unsent', 'nosend', 'sending', 'unmined', 'completed', 'unfail')`);
-                if (this.dbtype === 'MySQL')
-                    rs = rs[0];
-                const r = (0, utilityHelpers_1.verifyOneOrNone)(rs);
-                if (r && r.rawTx) {
-                    rawTx = Array.from(r.rawTx);
-                }
-            }
-        }
-        else {
-            const r = await this.getProvenOrRawTx(txid, trx);
-            if (r.proven)
-                rawTx = r.proven.rawTx;
-            else
-                rawTx = r.rawTx;
+            return await this.getRawTxSlice(txid, offset, length, trx);
         }
-        return rawTx;
+        const r = await this.getProvenOrRawTx(txid, trx);
+        return r.proven != null ? r.proven.rawTx : r.rawTx;
     }
     getProvenTxsForUserQuery(args) {
         const k = this.toDb(args.trx);
@@ -87,15 +306,34 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
                 .from('transactions')
                 .whereRaw(`proven_txs.provenTxId = transactions.provenTxId and transactions.userId = ${args.userId}`));
         });
-        if (args.paged) {
+        if (args.paged != null) {
             q = q.limit(args.paged.limit);
             q = q.offset(args.paged.offset || 0);
         }
-        if (args.since)
+        if (args.since != null)
             q = q.where('updated_at', '>=', this.validateDateForWhere(args.since));
         return q;
     }
     async getProvenTxsForUser(args) {
+        const postCutover = await this.isPostCutover();
+        if (postCutover) {
+            // Post-cutover: proven_txs → proven_txs_legacy; transactions → transactions_legacy
+            const k = this.toDb(args.trx);
+            let q = k('proven_txs_legacy').where(function () {
+                this.whereExists(k
+                    .select('*')
+                    .from('transactions_legacy')
+                    .whereRaw(`proven_txs_legacy.provenTxId = transactions_legacy.provenTxId and transactions_legacy.userId = ${args.userId}`));
+            });
+            if (args.paged != null) {
+                q = q.limit(args.paged.limit);
+                q = q.offset(args.paged.offset || 0);
+            }
+            if (args.since != null)
+                q = q.where('updated_at', '>=', this.validateDateForWhere(args.since));
+            const rs = await q;
+            return this.validateEntities(rs);
+        }
         const q = this.getProvenTxsForUserQuery(args);
         const rs = await q;
         return this.validateEntities(rs);
@@ -108,15 +346,34 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
                 .from('transactions')
                 .whereRaw(`proven_tx_reqs.txid = transactions.txid and transactions.userId = ${args.userId}`));
         });
-        if (args.paged) {
+        if (args.paged != null) {
             q = q.limit(args.paged.limit);
             q = q.offset(args.paged.offset || 0);
         }
-        if (args.since)
+        if (args.since != null)
             q = q.where('updated_at', '>=', this.validateDateForWhere(args.since));
         return q;
     }
     async getProvenTxReqsForUser(args) {
+        const postCutover = await this.isPostCutover();
+        if (postCutover) {
+            // Post-cutover: proven_tx_reqs → proven_tx_reqs_legacy; transactions → transactions_legacy
+            const k = this.toDb(args.trx);
+            let q = k('proven_tx_reqs_legacy').where(function () {
+                this.whereExists(k
+                    .select('*')
+                    .from('transactions_legacy')
+                    .whereRaw(`proven_tx_reqs_legacy.txid = transactions_legacy.txid and transactions_legacy.userId = ${args.userId}`));
+            });
+            if (args.paged != null) {
+                q = q.limit(args.paged.limit);
+                q = q.offset(args.paged.offset || 0);
+            }
+            if (args.since != null)
+                q = q.where('updated_at', '>=', this.validateDateForWhere(args.since));
+            const rs = await q;
+            return this.validateEntities(rs, undefined, ['notified']);
+        }
         const q = this.getProvenTxReqsForUserQuery(args);
         const rs = await q;
         return this.validateEntities(rs, undefined, ['notified']);
@@ -127,9 +384,9 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
             .select('*')
             .from('tx_labels')
             .whereRaw(`tx_labels.txLabelId = tx_labels_map.txLabelId and tx_labels.userId = ${args.userId}`));
-        if (args.since)
+        if (args.since != null)
             q = q.where('updated_at', '>=', this.validateDateForWhere(args.since));
-        if (args.paged) {
+        if (args.paged != null) {
             q = q.limit(args.paged.limit);
             q = q.offset(args.paged.offset || 0);
         }
@@ -146,9 +403,9 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
             .select('*')
             .from('output_tags')
             .whereRaw(`output_tags.outputTagId = output_tags_map.outputTagId and output_tags.userId = ${args.userId}`));
-        if (args.since)
+        if (args.since != null)
             q = q.where('updated_at', '>=', this.validateDateForWhere(args.since));
-        if (args.paged) {
+        if (args.paged != null) {
             q = q.limit(args.paged.limit);
             q = q.offset(args.paged.offset || 0);
         }
@@ -173,7 +430,8 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         const e = await this.validateEntityForInsert(tx, trx);
         if (e.provenTxId === 0)
             delete e.provenTxId;
-        const [id] = await this.toDb(trx)('proven_txs').insert(e);
+        const tableName = await this.provenTxsTableName();
+        const [id] = await this.toDb(trx)(tableName).insert(e);
         tx.provenTxId = id;
         return tx.provenTxId;
     }
@@ -181,7 +439,10 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         const e = await this.validateEntityForInsert(tx, trx);
         if (e.provenTxReqId === 0)
             delete e.provenTxReqId;
-        const [id] = await this.toDb(trx)('proven_tx_reqs').insert(e);
+        // Post-cutover: route to proven_tx_reqs_legacy.
+        // FK bypass is handled by the caller (disableForeignKeys before any transaction).
+        const reqTable = await this.provenTxReqsTableName();
+        const [id] = await this.toDb(trx)(reqTable).insert(e);
         tx.provenTxReqId = id;
         return tx.provenTxReqId;
     }
@@ -203,7 +464,6 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         const e = await this.validateEntityForInsert(certificate, trx, undefined, ['isDeleted']);
         if (e.certificateId === 0)
             delete e.certificateId;
-        const logger = e.logger;
         if (e.logger)
             delete e.logger;
         const fields = e.fields;
@@ -236,6 +496,28 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         const e = await this.validateEntityForInsert(tx, trx);
         if (e.transactionId === 0)
             delete e.transactionId;
+        // Post-cutover the canonical `transactions` table is the new schema which
+        // does not carry legacy columns (description, status, satoshis, version...).
+        // Legacy-shaped insertions belong in `transactions_legacy`. We route there
+        // automatically so existing callers that still speak the legacy shape keep
+        // working without a code change at every call site. FK enforcement is
+        // bypassed because the renamed legacy table still references the renamed
+        // `proven_txs_legacy` via its original `proven_txs` FK column name.
+        const isSqlite = this.dbtype === 'SQLite';
+        const postCutover = isSqlite ? await this.isPostCutover() : false;
+        if (postCutover) {
+            if (isSqlite)
+                await this.knex.raw('PRAGMA foreign_keys = OFF');
+            try {
+                const [id] = await this.toDb(trx)('transactions_legacy').insert(e);
+                tx.transactionId = id;
+                return tx.transactionId;
+            }
+            finally {
+                if (isSqlite)
+                    await this.knex.raw('PRAGMA foreign_keys = ON');
+            }
+        }
         const [id] = await this.toDb(trx)('transactions').insert(e);
         tx.transactionId = id;
         return tx.transactionId;
@@ -244,21 +526,42 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         const e = await this.validateEntityForInsert(commission, trx);
         if (e.commissionId === 0)
             delete e.commissionId;
-        const [id] = await this.toDb(trx)('commissions').insert(e);
-        commission.commissionId = id;
-        return commission.commissionId;
+        // Post-cutover bridge-period: commissions.transactionId FKs new transactions.
+        // During createAction the transactionId references transactions_legacy, so bypass FK.
+        const isSqlite = this.dbtype === 'SQLite';
+        const postCutover = isSqlite ? await this.isPostCutover() : false;
+        if (postCutover)
+            await this.knex.raw('PRAGMA foreign_keys = OFF');
+        try {
+            const [id] = await this.toDb(trx)('commissions').insert(e);
+            commission.commissionId = id;
+            return commission.commissionId;
+        }
+        finally {
+            if (postCutover)
+                await this.knex.raw('PRAGMA foreign_keys = ON');
+        }
     }
     async insertOutput(output, trx) {
+        const e = await this.validateEntityForInsert(output, trx);
+        if (e.outputId === 0)
+            delete e.outputId;
+        // Post-cutover bridge-period: outputs.transactionId FKs new transactions,
+        // but new unsigned outputs reference transactions_legacy (bridge-period rows).
+        // Temporarily disable FK checks on SQLite. Safe because once processAction
+        // runs, spentBy and transactionId are remapped to real new-schema IDs.
+        const isSqlite = this.dbtype === 'SQLite';
+        const postCutover = isSqlite ? await this.isPostCutover() : false;
+        if (postCutover)
+            await this.knex.raw('PRAGMA foreign_keys = OFF');
         try {
-            const e = await this.validateEntityForInsert(output, trx);
-            if (e.outputId === 0)
-                delete e.outputId;
             const [id] = await this.toDb(trx)('outputs').insert(e);
             output.outputId = id;
             return output.outputId;
         }
-        catch (e) {
-            throw e;
+        finally {
+            if (postCutover)
+                await this.knex.raw('PRAGMA foreign_keys = ON');
         }
     }
     async insertOutputTag(tag, trx) {
@@ -271,7 +574,7 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
     }
     async insertOutputTagMap(tagMap, trx) {
         const e = await this.validateEntityForInsert(tagMap, trx, undefined, ['isDeleted']);
-        const [id] = await this.toDb(trx)('output_tags_map').insert(e);
+        await this.toDb(trx)('output_tags_map').insert(e);
     }
     async insertTxLabel(label, trx) {
         const e = await this.validateEntityForInsert(label, trx, undefined, ['isDeleted']);
@@ -283,7 +586,23 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
     }
     async insertTxLabelMap(labelMap, trx) {
         const e = await this.validateEntityForInsert(labelMap, trx, undefined, ['isDeleted']);
-        const [id] = await this.toDb(trx)('tx_labels_map').insert(e);
+        // Post-cutover SQLite: tx_labels_map.transactionId references actions.actionId
+        // (rebuilt during schema cutover). Sync paths that import legacy rows still
+        // carry the legacy transactionId until repointLabelsToActionId remaps them.
+        // Temporarily disable FK checks so the import does not fail.
+        const isSqlite = this.dbtype === 'SQLite';
+        const postCutover = isSqlite ? await this.isPostCutover() : false;
+        if (postCutover) {
+            await this.knex.raw('PRAGMA foreign_keys = OFF');
+            try {
+                await this.toDb(trx)('tx_labels_map').insert(e);
+            }
+            finally {
+                await this.knex.raw('PRAGMA foreign_keys = ON');
+            }
+            return;
+        }
+        await this.toDb(trx)('tx_labels_map').insert(e);
     }
     async insertMonitorEvent(event, trx) {
         const e = await this.validateEntityForInsert(event, trx);
@@ -315,9 +634,22 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
     }
     async updateCommission(id, update, trx) {
         await this.verifyReadyForDatabaseAccess(trx);
-        return await this.toDb(trx)('commissions')
-            .where({ commissionId: id })
-            .update(this.validatePartialForUpdate(update));
+        // Post-cutover SQLite: commissions.transactionId FK references the new
+        // schema `transactions` table. Legacy callers carry transactionId values
+        // that still point at transactions_legacy. Bypass FK so the update lands.
+        const isSqlite = this.dbtype === 'SQLite';
+        const postCutover = isSqlite ? await this.isPostCutover() : false;
+        if (postCutover)
+            await this.knex.raw('PRAGMA foreign_keys = OFF');
+        try {
+            return await this.toDb(trx)('commissions')
+                .where({ commissionId: id })
+                .update(this.validatePartialForUpdate(update));
+        }
+        finally {
+            if (postCutover)
+                await this.knex.raw('PRAGMA foreign_keys = ON');
+        }
     }
     async updateOutputBasket(id, update, trx) {
         await this.verifyReadyForDatabaseAccess(trx);
@@ -345,14 +677,15 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
     }
     async updateProvenTxReq(id, update, trx) {
         await this.verifyReadyForDatabaseAccess(trx);
+        const reqTable = await this.provenTxReqsTableName();
         let r;
         if (Array.isArray(id)) {
-            r = await this.toDb(trx)('proven_tx_reqs')
+            r = await this.toDb(trx)(reqTable)
                 .whereIn('provenTxReqId', id)
                 .update(this.validatePartialForUpdate(update));
         }
         else if (Number.isInteger(id)) {
-            r = await this.toDb(trx)('proven_tx_reqs')
+            r = await this.toDb(trx)(reqTable)
                 .where({ provenTxReqId: id })
                 .update(this.validatePartialForUpdate(update));
         }
@@ -363,7 +696,8 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
     }
     async updateProvenTx(id, update, trx) {
         await this.verifyReadyForDatabaseAccess(trx);
-        return await this.toDb(trx)('proven_txs')
+        const tableName = await this.provenTxsTableName();
+        return await this.toDb(trx)(tableName)
             .where({ provenTxId: id })
             .update(this.validatePartialForUpdate(update));
     }
@@ -375,21 +709,36 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
     }
     async updateTransaction(id, update, trx) {
         await this.verifyReadyForDatabaseAccess(trx);
-        let r;
-        if (Array.isArray(id)) {
-            r = await this.toDb(trx)('transactions')
-                .whereIn('transactionId', id)
-                .update(await this.validatePartialForUpdate(update));
-        }
-        else if (Number.isInteger(id)) {
-            r = await this.toDb(trx)('transactions')
-                .where({ transactionId: id })
-                .update(await this.validatePartialForUpdate(update));
+        // Post-cutover the canonical `transactions` table is the new schema which
+        // lacks legacy columns (userId, status, description, satoshis, version, ...).
+        // Legacy-shaped updates belong in `transactions_legacy`, matching the
+        // routing performed by `insertTransaction`.
+        const isSqlite = this.dbtype === 'SQLite';
+        const postCutover = isSqlite ? await this.isPostCutover() : false;
+        const tableName = postCutover ? 'transactions_legacy' : 'transactions';
+        if (postCutover && isSqlite)
+            await this.knex.raw('PRAGMA foreign_keys = OFF');
+        try {
+            let r;
+            if (Array.isArray(id)) {
+                r = await this.toDb(trx)(tableName)
+                    .whereIn('transactionId', id)
+                    .update(this.validatePartialForUpdate(update));
+            }
+            else if (Number.isInteger(id)) {
+                r = await this.toDb(trx)(tableName)
+                    .where({ transactionId: id })
+                    .update(this.validatePartialForUpdate(update));
+            }
+            else {
+                throw new WERR_errors_1.WERR_INVALID_PARAMETER('id', 'transactionId or array of transactionId');
+            }
+            return r;
         }
-        else {
-            throw new WERR_errors_1.WERR_INVALID_PARAMETER('id', 'transactionId or array of transactionId');
+        finally {
+            if (postCutover && isSqlite)
+                await this.knex.raw('PRAGMA foreign_keys = ON');
         }
-        return r;
     }
     async updateTxLabelMap(transactionId, txLabelId, update, trx) {
         await this.verifyReadyForDatabaseAccess(trx);
@@ -414,10 +763,10 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
             .update(this.validatePartialForUpdate(update));
     }
     setupQuery(table, args) {
-        let q = this.toDb(args.trx)(table);
+        const q = this.toDb(args.trx)(table);
         if (args.partial && Object.keys(args.partial).length > 0)
             q.where(args.partial);
-        if (args.since)
+        if (args.since != null)
             q.where('updated_at', '>=', this.validateDateForWhere(args.since));
         if (args.orderDescending) {
             let sortColumn = '';
@@ -438,15 +787,18 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
                     sortColumn = 'outputTagId';
                     break;
                 case 'proven_tx_reqs':
+                case 'proven_tx_reqs_legacy':
                     sortColumn = 'provenTxReqId';
                     break;
                 case 'proven_txs':
+                case 'proven_txs_legacy':
                     sortColumn = 'provenTxId';
                     break;
                 case 'sync_states':
                     sortColumn = 'syncStateId';
                     break;
                 case 'transactions':
+                case 'transactions_legacy':
                     sortColumn = 'transactionId';
                     break;
                 case 'tx_labels':
@@ -465,7 +817,7 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
                 q.orderBy(sortColumn, 'desc');
             }
         }
-        if (args.paged) {
+        if (args.paged != null) {
             q.limit(args.paged.limit);
             q.offset(args.paged.offset || 0);
         }
@@ -476,26 +828,40 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
     }
     findCertificatesQuery(args) {
         const q = this.setupQuery('certificates', args);
-        if (args.certifiers && args.certifiers.length > 0)
+        if ((args.certifiers != null) && args.certifiers.length > 0)
             q.whereIn('certifier', args.certifiers);
-        if (args.types && args.types.length > 0)
+        if ((args.types != null) && args.types.length > 0)
             q.whereIn('type', args.types);
         return q;
     }
     findCommissionsQuery(args) {
-        if (args.partial.lockingScript)
-            throw new WERR_errors_1.WERR_INVALID_PARAMETER('partial.lockingScript', `undefined. Commissions may not be found by lockingScript value.`);
+        if (args.partial.lockingScript != null) {
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('partial.lockingScript', 'undefined. Commissions may not be found by lockingScript value.');
+        }
         return this.setupQuery('commissions', args);
     }
     findOutputBasketsQuery(args) {
         return this.setupQuery('output_baskets', args);
     }
     findOutputsQuery(args, count) {
-        if (args.partial.lockingScript)
-            throw new WERR_errors_1.WERR_INVALID_PARAMETER('args.partial.lockingScript', `undefined. Outputs may not be found by lockingScript value.`);
+        if (args.partial.lockingScript != null) {
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('args.partial.lockingScript', 'undefined. Outputs may not be found by lockingScript value.');
+        }
         const q = this.setupQuery('outputs', args);
-        if (args.txStatus && args.txStatus.length > 0) {
-            q.whereRaw(`(select status from transactions where transactions.transactionId = outputs.transactionId) in (${args.txStatus.map(s => `'${s}'`).join(',')})`);
+        if ((args.txStatus != null) && args.txStatus.length > 0) {
+            // Post-cutover the `transactions` table carries `processing`
+            // (ProcessingStatus), not the legacy `status` column. We translate
+            // the requested legacy status set to its ProcessingStatus equivalents
+            // when the cutover has been applied; pre-cutover the original `status`
+            // column lookup remains correct.
+            if (this._postCutoverCache === true) {
+                const processingFilter = this.legacyStatiToProcessing(args.txStatus);
+                const filterList = processingFilter.map(s => "'" + s + "'").join(',');
+                q.whereRaw(`(select processing from transactions where transactions.transactionId = outputs.transactionId) in (${filterList})`);
+            }
+            else {
+                q.whereRaw(`(select status from transactions where transactions.transactionId = outputs.transactionId) in (${args.txStatus.map(s => "'" + s + "'").join(',')})`);
+            }
         }
         if (args.noScript && !count) {
             const columns = tables_1.outputColumnsWithoutLockingScript.map(c => `outputs.${c}`);
@@ -505,37 +871,41 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
     }
     findOutputTagMapsQuery(args) {
         const q = this.setupQuery('output_tags_map', args);
-        if (args.tagIds && args.tagIds.length > 0)
+        if ((args.tagIds != null) && args.tagIds.length > 0)
             q.whereIn('outputTagId', args.tagIds);
         return q;
     }
     findOutputTagsQuery(args) {
         return this.setupQuery('output_tags', args);
     }
-    findProvenTxReqsQuery(args) {
-        if (args.partial.rawTx)
-            throw new WERR_errors_1.WERR_INVALID_PARAMETER('args.partial.rawTx', `undefined. ProvenTxReqs may not be found by rawTx value.`);
-        if (args.partial.inputBEEF)
-            throw new WERR_errors_1.WERR_INVALID_PARAMETER('args.partial.inputBEEF', `undefined. ProvenTxReqs may not be found by inputBEEF value.`);
-        const q = this.setupQuery('proven_tx_reqs', args);
-        if (args.status && args.status.length > 0)
+    findProvenTxReqsQuery(args, tableName = 'proven_tx_reqs') {
+        if (args.partial.rawTx != null) {
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('args.partial.rawTx', 'undefined. ProvenTxReqs may not be found by rawTx value.');
+        }
+        if (args.partial.inputBEEF != null) {
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('args.partial.inputBEEF', 'undefined. ProvenTxReqs may not be found by inputBEEF value.');
+        }
+        const q = this.setupQuery(tableName, args);
+        if ((args.status != null) && args.status.length > 0)
             q.whereIn('status', args.status);
-        if (args.txids) {
+        if (args.txids != null) {
             const txids = args.txids.filter(txid => txid !== undefined);
             if (txids.length > 0)
                 q.whereIn('txid', txids);
         }
         return q;
     }
-    findProvenTxsQuery(args) {
-        if (args.partial.rawTx)
-            throw new WERR_errors_1.WERR_INVALID_PARAMETER('args.partial.rawTx', `undefined. ProvenTxs may not be found by rawTx value.`);
-        if (args.partial.merklePath)
-            throw new WERR_errors_1.WERR_INVALID_PARAMETER('args.partial.merklePath', `undefined. ProvenTxs may not be found by merklePath value.`);
-        return this.setupQuery('proven_txs', args);
+    findProvenTxsQuery(args, tableName = 'proven_txs') {
+        if (args.partial.rawTx != null) {
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('args.partial.rawTx', 'undefined. ProvenTxs may not be found by rawTx value.');
+        }
+        if (args.partial.merklePath != null) {
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('args.partial.merklePath', 'undefined. ProvenTxs may not be found by merklePath value.');
+        }
+        return this.setupQuery(tableName, args);
     }
-    findStaleMerkleRootsQuery(args) {
-        let q = this.toDb(args.trx)('proven_txs');
+    findStaleMerkleRootsQuery(args, tableName = 'proven_txs') {
+        const q = this.toDb(args.trx)(tableName);
         q.where('height', '=', args.height);
         q.where('merkleRoot', '!=', args.merkleRoot);
         q.select('merkleRoot');
@@ -546,26 +916,37 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         return this.setupQuery('sync_states', args);
     }
     findTransactionsQuery(args, count) {
-        if (args.partial.rawTx)
-            throw new WERR_errors_1.WERR_INVALID_PARAMETER('args.partial.rawTx', `undefined. Transactions may not be found by rawTx value.`);
-        if (args.partial.inputBEEF)
-            throw new WERR_errors_1.WERR_INVALID_PARAMETER('args.partial.inputBEEF', `undefined. Transactions may not be found by inputBEEF value.`);
-        const q = this.setupQuery('transactions', args);
-        if (args.status && args.status.length > 0)
+        if (args.partial.rawTx != null) {
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('args.partial.rawTx', 'undefined. Transactions may not be found by rawTx value.');
+        }
+        if (args.partial.inputBEEF != null) {
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('args.partial.inputBEEF', 'undefined. Transactions may not be found by inputBEEF value.');
+        }
+        // Post-cutover the original per-user `transactions` table has been
+        // renamed to `transactions_legacy`. `findTransactions` returns the
+        // legacy shape (status / userId / satoshis / description / etc.) so it
+        // must route at the renamed table to preserve the legacy read surface
+        // through the bridge period. New-canonical per-txid reads go through
+        // TransactionService.
+        const tableName = this._postCutoverCache === true
+            ? 'transactions_legacy'
+            : 'transactions';
+        const q = this.setupQuery(tableName, args);
+        if ((args.status != null) && args.status.length > 0)
             q.whereIn('status', args.status);
-        if (args.from)
+        if (args.from != null)
             q.where('created_at', '>=', this.validateDateForWhere(args.from));
-        if (args.to)
+        if (args.to != null)
             q.where('created_at', '<', this.validateDateForWhere(args.to));
         if (args.noRawTx && !count) {
-            const columns = tables_1.transactionColumnsWithoutRawTx.map(c => `transactions.${c}`);
+            const columns = tables_1.transactionColumnsWithoutRawTx.map(c => `${tableName}.${c}`);
             q.select(columns);
         }
         return q;
     }
     findTxLabelMapsQuery(args) {
         const q = this.setupQuery('tx_labels_map', args);
-        if (args.labelIds && args.labelIds.length > 0)
+        if ((args.labelIds != null) && args.labelIds.length > 0)
             q.whereIn('txLabelId', args.labelIds);
         return q;
     }
@@ -644,17 +1025,20 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         return this.validateEntities(r, undefined, ['isDeleted']);
     }
     async findProvenTxReqs(args) {
-        const q = this.findProvenTxReqsQuery(args);
+        const reqTable = await this.provenTxReqsTableName();
+        const q = this.findProvenTxReqsQuery(args, reqTable);
         const r = await q;
-        return this.validateEntities(r, undefined, ['notified']);
+        return this.validateEntities(r, undefined, ['notified', 'wasBroadcast']);
     }
     async findProvenTxs(args) {
-        const q = this.findProvenTxsQuery(args);
+        const tableName = await this.provenTxsTableName();
+        const q = this.findProvenTxsQuery(args, tableName);
         const r = await q;
         return this.validateEntities(r);
     }
     async findStaleMerkleRoots(args) {
-        const q = this.findStaleMerkleRootsQuery(args);
+        const tableName = await this.provenTxsTableName();
+        const q = this.findStaleMerkleRootsQuery(args, tableName);
         const r = await q;
         return r.map((row) => row.merkleRoot);
     }
@@ -673,6 +1057,172 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         }
         return this.validateEntities(r, undefined, ['isOutgoing']);
     }
+    /**
+     * Post-cutover: queries `transactions_legacy` for unsigned/pending rows
+     * created by `createAction` (which have no real txid yet and therefore have no
+     * new-schema counterpart).  Falls back to the standard `findTransactions` pre-cutover.
+     *
+     * Used by `processAction.validateCommitNewTxToStorageArgs` to locate the
+     * unsigned transaction row by `{userId, reference}`.
+     *
+     * Mapping §2: legacy `unsigned` / `unprocessed` → these rows only exist in
+     * `transactions_legacy` post-cutover; new `transactions` has `processing` not
+     * `status` and no unsigned-state rows.
+     */
+    async findLegacyTransactions(args) {
+        const postCutover = await this.isPostCutover();
+        if (!postCutover) {
+            // Pre-cutover: standard transactions table
+            return await this.findTransactions(args);
+        }
+        // Post-cutover: unsigned/unprocessed rows live in transactions_legacy
+        const q = this.setupQuery('transactions_legacy', args);
+        if ((args.status != null) && args.status.length > 0)
+            q.whereIn('status', args.status);
+        if (args.from != null)
+            q.where('created_at', '>=', this.validateDateForWhere(args.from));
+        if (args.to != null)
+            q.where('created_at', '<', this.validateDateForWhere(args.to));
+        if (args.noRawTx) {
+            const columns = tables_1.transactionColumnsWithoutRawTx.map(c => `transactions_legacy.${c}`);
+            q.select(columns);
+        }
+        const r = await q;
+        if (!args.noRawTx) {
+            for (const t of r) {
+                await this.validateRawTransaction(t, args.trx);
+            }
+        }
+        return this.validateEntities(r, undefined, ['isOutgoing']);
+    }
+    /**
+     * Post-cutover: updates `transactions_legacy` (where unsigned rows live).
+     * Pre-cutover: delegates to `updateTransaction`.
+     *
+     * Used by `processAction.commitNewTxToStorage` to write back the real txid
+     * and status to the legacy row that was created by `createAction`.
+     *
+     * Mapping §2: legacy `unsigned` → `unprocessed` transition and txid write-back
+     * must go to `transactions_legacy` post-cutover, not new `transactions`.
+     */
+    async updateLegacyTransaction(id, update, trx) {
+        const postCutover = await this.isPostCutover();
+        if (!postCutover) {
+            return await this.updateTransaction(id, update, trx);
+        }
+        // Post-cutover: unsigned rows are in transactions_legacy
+        await this.verifyReadyForDatabaseAccess(trx);
+        let r;
+        if (Array.isArray(id)) {
+            r = await this.toDb(trx)('transactions_legacy')
+                .whereIn('transactionId', id)
+                .update(this.validatePartialForUpdate(update));
+        }
+        else if (Number.isInteger(id)) {
+            r = await this.toDb(trx)('transactions_legacy')
+                .where({ transactionId: id })
+                .update(this.validatePartialForUpdate(update));
+        }
+        else {
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('id', 'transactionId or array of transactionId');
+        }
+        return r;
+    }
+    /**
+     * Post-cutover SQLite: temporarily disable FK enforcement around the
+     * `outputs.spentBy = legacyTransactionId` UPDATE. The `outputs.spentBy` FK
+     * references `transactions.transactionId` after cutover, but unsigned
+     * transactions from `createAction` live in `transactions_legacy` (their new-schema
+     * counterpart is created later by `processAction`).
+     *
+     * IMPORTANT: We bypass `updateOutput` (and therefore `verifyReadyForDatabaseAccess`)
+     * because `verifyReadyForDatabaseAccess` always re-enables FK with
+     * `PRAGMA foreign_keys = ON`, which would undo our bypass. Instead we
+     * directly run the UPDATE via the raw knex handle.
+     *
+     * Pre-cutover or MySQL: delegates to `updateOutput` unchanged.
+     *
+     * Mapping §2: bridge-period spentBy references transactions_legacy during
+     * createAction; FK bypass covers this until processAction wires the new-schema.
+     */
+    async markOutputAsSpentBy(outputId, update, trx) {
+        const postCutover = await this.isPostCutover();
+        const isSqlite = this.dbtype === 'SQLite';
+        if (postCutover && isSqlite) {
+            // Build the UPDATE payload the same way validatePartialForUpdate does,
+            // but WITHOUT calling verifyReadyForDatabaseAccess (which always issues
+            // PRAGMA foreign_keys = ON, undoing our bypass).
+            const now = new Date().toISOString();
+            const payload = { updated_at: now };
+            for (const [k, v] of Object.entries(update)) {
+                if (v === undefined) {
+                    payload[k] = null;
+                }
+                else if (Array.isArray(v) && (v.length === 0 || typeof v[0] === 'number')) {
+                    payload[k] = Buffer.from(v);
+                }
+                else {
+                    payload[k] = v;
+                }
+            }
+            // Strategy: FK is a connection-level setting in SQLite. PRAGMA changes
+            // inside a Knex transaction are no-ops (SQLite restriction), but PRAGMA
+            // changes OUTSIDE a transaction persist.
+            //
+            // When called with trx (inside a transaction): the caller is expected to have
+            // already disabled FK before opening the transaction. We run the UPDATE via
+            // the transaction handle (no PRAGMA calls needed here — they'd be no-ops or
+            // pool-exhausting anyway).
+            //
+            // When called without trx (outside a transaction): disable FK, run UPDATE,
+            // re-enable FK.
+            if (trx != null) {
+                // Inside caller's transaction — FK was disabled before the transaction.
+                // Just run the UPDATE; do NOT try to PRAGMA here (no-op or timeout).
+                this.whenLastAccess = new Date();
+                await (this.toDb(trx))('outputs')
+                    .where({ outputId })
+                    .update(payload);
+            }
+            else {
+                // Outside any transaction — we can safely toggle FK on the bare connection.
+                await this.knex.raw('PRAGMA foreign_keys = OFF');
+                try {
+                    this.whenLastAccess = new Date();
+                    await this.knex('outputs').where({ outputId }).update(payload);
+                }
+                finally {
+                    await this.knex.raw('PRAGMA foreign_keys = ON');
+                }
+            }
+        }
+        else {
+            await this.updateOutput(outputId, update, trx);
+        }
+    }
+    /**
+     * Post-cutover SQLite: disable FK on the bare connection BEFORE opening a
+     * transaction. PRAGMA foreign_keys changes inside SQLite transactions are no-ops,
+     * so this MUST be called before `this.knex.transaction()`.
+     *
+     * Only acts when post-cutover AND SQLite. Pre-cutover or MySQL: no-op.
+     */
+    async disableForeignKeys() {
+        const postCutover = await this.isPostCutover();
+        if (postCutover && this.dbtype === 'SQLite') {
+            await this.knex.raw('PRAGMA foreign_keys = OFF');
+        }
+    }
+    /**
+     * Re-enable FK after the transaction opened via `disableForeignKeys()` completes.
+     * Only acts when post-cutover AND SQLite.
+     */
+    async enableForeignKeys() {
+        const postCutover = await this.isPostCutover();
+        if (postCutover && this.dbtype === 'SQLite') {
+            await this.knex.raw('PRAGMA foreign_keys = ON');
+        }
+    }
     async findTxLabelMaps(args) {
         const q = this.findTxLabelMapsQuery(args);
         const r = await q;
@@ -734,10 +1284,12 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         return await this.getCount(this.findOutputTagsQuery(args));
     }
     async countProvenTxReqs(args) {
-        return await this.getCount(this.findProvenTxReqsQuery(args));
+        const reqTable = await this.provenTxReqsTableName();
+        return await this.getCount(this.findProvenTxReqsQuery(args, reqTable));
     }
     async countProvenTxs(args) {
-        return await this.getCount(this.findProvenTxsQuery(args));
+        const tableName = await this.provenTxsTableName();
+        return await this.getCount(this.findProvenTxsQuery(args, tableName));
     }
     async countSyncStates(args) {
         return await this.getCount(this.findSyncStatesQuery(args));
@@ -810,11 +1362,14 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
             try {
                 const r = await this.knex.migrate.down(config);
                 if (!r) {
-                    console.error(`Migration returned falsy result await this.knex.migrate.down(config)`);
+                    console.error('Migration returned falsy result await this.knex.migrate.down(config)');
                     break;
                 }
             }
-            catch (eu) {
+            catch (migrationError) {
+                // migrate.down throws when there are no more migrations to roll back — this is
+                // the expected terminal condition, so we stop iterating rather than propagating.
+                console.debug('migrate.down stopped (no more migrations or error):', migrationError);
                 break;
             }
         }
@@ -824,7 +1379,7 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         }
     }
     async transaction(scope, trx) {
-        if (trx)
+        if (trx != null)
             return await scope(trx);
         return await this.knex.transaction(async (knextrx) => {
             const trx = knextrx;
@@ -837,7 +1392,7 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
      */
     toDb(trx) {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const db = !trx ? this.knex : trx;
+        const db = (trx == null) ? this.knex : trx;
         this.whenLastAccess = new Date();
         return db;
     }
@@ -847,7 +1402,7 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
             return;
         // rawTransaction is missing, see if we moved it ...
         const rawTx = await this.getRawTxOfKnownValidTransaction(t.txid, undefined, undefined, trx);
-        if (!rawTx)
+        if (rawTx == null)
             return;
         t.rawTx = rawTx;
     }
@@ -860,9 +1415,8 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
      * @param trx
      */
     async verifyReadyForDatabaseAccess(trx) {
-        if (!this._settings) {
-            this._settings = await this.readSettings();
-        }
+        var _a;
+        (_a = this._settings) !== null && _a !== void 0 ? _a : (this._settings = await this.readSettings());
         // Always run the PRAGMA for SQLite to ensure foreign key constraints are enabled.
         // This is necessary because PRAGMA foreign_keys is a per-connection setting,
         // and connection pools may create new connections that don't have it set.
@@ -873,6 +1427,39 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         this._verifiedReadyForDatabaseAccess = true;
         return this._settings.dbtype;
     }
+    /** Convert every number-array value to a Buffer and every undefined to null on an arbitrary object. */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    serialiseForKnex(v) {
+        for (const key of Object.keys(v)) {
+            const val = v[key];
+            if (Array.isArray(val) && (val.length === 0 || typeof val[0] === 'number')) {
+                v[key] = Buffer.from(val);
+            }
+            else if (val === undefined) {
+                v[key] = null;
+            }
+        }
+    }
+    /** Apply optional date-field coercion list in-place. */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    coerceDateFields(v, dateFields) {
+        if (dateFields == null)
+            return;
+        for (const df of dateFields) {
+            if (v[df])
+                v[df] = this.validateOptionalEntityDate(v[df]);
+        }
+    }
+    /** Apply optional boolean-field coercion list in-place. */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    coerceBooleanFields(v, booleanFields) {
+        if (booleanFields == null)
+            return;
+        for (const df of booleanFields) {
+            if (v[df] !== undefined)
+                v[df] = v[df] ? 1 : 0;
+        }
+    }
     /**
      * Helper to force uniform behavior across database engines.
      * Use to process the update template for entities being updated.
@@ -880,6 +1467,7 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
     validatePartialForUpdate(update, dateFields, booleanFields) {
         if (!this.dbtype)
             throw new WERR_errors_1.WERR_INTERNAL('must call verifyReadyForDatabaseAccess first');
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const v = update;
         if (v.created_at)
             v.created_at = this.validateEntityDate(v.created_at);
@@ -889,27 +1477,9 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
             delete v.created_at;
         if (!v.updated_at)
             v.updated_at = this.validateEntityDate(new Date());
-        if (dateFields) {
-            for (const df of dateFields) {
-                if (v[df])
-                    v[df] = this.validateOptionalEntityDate(v[df]);
-            }
-        }
-        if (booleanFields) {
-            for (const df of booleanFields) {
-                if (update[df] !== undefined)
-                    update[df] = !!update[df] ? 1 : 0;
-            }
-        }
-        for (const key of Object.keys(v)) {
-            const val = v[key];
-            if (Array.isArray(val) && (val.length === 0 || typeof val[0] === 'number')) {
-                v[key] = Buffer.from(val);
-            }
-            else if (val === undefined) {
-                v[key] = null;
-            }
-        }
+        this.coerceDateFields(v, dateFields);
+        this.coerceBooleanFields(update, booleanFields);
+        this.serialiseForKnex(v);
         this.isDirty = true;
         return v;
     }
@@ -917,8 +1487,11 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
      * Helper to force uniform behavior across database engines.
      * Use to process new entities being inserted into the database.
      */
-    async validateEntityForInsert(entity, trx, dateFields, booleanFields) {
+    async validateEntityForInsert(entity, trx, dateFields, booleanFields
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ) {
         await this.verifyReadyForDatabaseAccess(trx);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const v = { ...entity };
         v.created_at = this.validateOptionalEntityDate(v.created_at, true);
         v.updated_at = this.validateOptionalEntityDate(v.updated_at, true);
@@ -926,27 +1499,9 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
             delete v.created_at;
         if (!v.updated_at)
             delete v.updated_at;
-        if (dateFields) {
-            for (const df of dateFields) {
-                if (v[df])
-                    v[df] = this.validateOptionalEntityDate(v[df]);
-            }
-        }
-        if (booleanFields) {
-            for (const df of booleanFields) {
-                if (entity[df] !== undefined)
-                    entity[df] = !!entity[df] ? 1 : 0;
-            }
-        }
-        for (const key of Object.keys(v)) {
-            const val = v[key];
-            if (Array.isArray(val) && (val.length === 0 || typeof val[0] === 'number')) {
-                v[key] = Buffer.from(val);
-            }
-            else if (val === undefined) {
-                v[key] = null;
-            }
-        }
+        this.coerceDateFields(v, dateFields);
+        this.coerceBooleanFields(entity, booleanFields);
+        this.serialiseForKnex(v);
         this.isDirty = true;
         return v;
     }
@@ -982,13 +1537,19 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
      * - sending (if excludeSending is false)
      */
     async countChangeInputs(userId, basketId, excludeSending) {
-        const status = ['completed', 'unproven'];
+        const legacyStatus = ['completed', 'unproven'];
         if (!excludeSending)
-            status.push('sending');
+            legacyStatus.push('sending');
+        const postCutover = await this.isPostCutover();
         const q = this.knex('outputs as o')
             .join('transactions as t', 'o.transactionId', 't.transactionId')
-            .where({ 'o.userId': userId, 'o.spendable': true, 'o.basketId': basketId })
-            .whereIn('t.status', status);
+            .where({ 'o.userId': userId, 'o.spendable': true, 'o.basketId': basketId });
+        if (postCutover) {
+            q.whereIn('t.processing', this.legacyStatiToProcessing(legacyStatus));
+        }
+        else {
+            q.whereIn('t.status', legacyStatus);
+        }
         const count = await this.getCount(q);
         return count;
     }
@@ -1069,16 +1630,21 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         return byTag;
     }
     async sumSpendableSatoshisInBasket(userId, basketId, excludeSending, trx) {
-        const status = ['completed', 'unproven'];
+        const legacyStatus = ['completed', 'unproven'];
         if (!excludeSending)
-            status.push('sending');
-        const row = await this.toDb(trx)('outputs as o')
+            legacyStatus.push('sending');
+        const postCutover = await this.isPostCutover();
+        const q = this.toDb(trx)('outputs as o')
             .join('transactions as t', 'o.transactionId', 't.transactionId')
-            .where({ 'o.userId': userId, 'o.spendable': true, 'o.basketId': basketId })
-            .whereIn('t.status', status)
-            .sum({ totalSatoshis: 'o.satoshis' })
-            .first();
-        return Number((row && row['totalSatoshis']) || 0);
+            .where({ 'o.userId': userId, 'o.spendable': true, 'o.basketId': basketId });
+        if (postCutover) {
+            q.whereIn('t.processing', this.legacyStatiToProcessing(legacyStatus));
+        }
+        else {
+            q.whereIn('t.status', legacyStatus);
+        }
+        const row = await q.sum({ totalSatoshis: 'o.satoshis' }).first();
+        return Number(((row != null) && row.totalSatoshis) || 0);
     }
     /**
      *  Finds closest matching available change output to use as input for new transaction.
@@ -1086,50 +1652,97 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
      * Transactionally allocate the output such that
      */
     async allocateChangeInput(userId, basketId, targetSatoshis, exactSatoshis, excludeSending, transactionId) {
-        const status = ['completed', 'unproven'];
+        const legacyStatus = ['completed', 'unproven'];
         if (!excludeSending)
-            status.push('sending');
-        const r = await this.knex.transaction(async (trx) => {
-            const baseQuery = () => trx('outputs as o')
-                .join('transactions as t', 'o.transactionId', 't.transactionId')
-                .where('o.userId', userId)
-                .where('o.spendable', true)
-                .where('o.basketId', basketId)
-                .whereIn('t.status', status)
-                .select('o.*');
-            let output;
-            if (exactSatoshis !== undefined) {
-                output = await baseQuery().where('o.satoshis', exactSatoshis).orderBy('o.outputId', 'asc').first();
-            }
-            if (!output) {
-                output = await baseQuery()
+            legacyStatus.push('sending');
+        const postCutover = await this.isPostCutover();
+        const processingFilter = postCutover ? this.legacyStatiToProcessing(legacyStatus) : undefined;
+        // Post-cutover bridge-period: `transactionId` here is a legacy row in
+        // `transactions_legacy` (new unsigned tx created by createAction). The
+        // `outputs.spentBy` FK now references `transactions.transactionId`, so
+        // setting spentBy to a transactions_legacy ID would violate the constraint.
+        // PRAGMA foreign_keys is silently ignored inside SQLite transactions, so
+        // we toggle FK enforcement on the bare connection BEFORE opening the
+        // transaction. processAction will remap spentBy to the real new transactionId
+        // once the txid is known and the new schema row is created.
+        const isSqlite = this.dbtype === 'SQLite';
+        if (postCutover && isSqlite) {
+            await this.knex.raw('PRAGMA foreign_keys = OFF');
+        }
+        let r;
+        try {
+            r = await this.knex.transaction(async (trx) => {
+                const baseQuery = () => {
+                    const q = trx('outputs as o')
+                        .join('transactions as t', 'o.transactionId', 't.transactionId')
+                        .where('o.userId', userId)
+                        .where('o.spendable', true)
+                        .where('o.basketId', basketId)
+                        .select('o.*');
+                    if (processingFilter != null) {
+                        q.whereIn('t.processing', processingFilter);
+                    }
+                    else {
+                        q.whereIn('t.status', legacyStatus);
+                    }
+                    return q;
+                };
+                let output;
+                if (exactSatoshis !== undefined) {
+                    output = await baseQuery().where('o.satoshis', exactSatoshis).orderBy('o.outputId', 'asc').first();
+                }
+                output !== null && output !== void 0 ? output : (output = await baseQuery()
                     .where('o.satoshis', '>=', targetSatoshis)
                     .orderBy('o.satoshis', 'asc')
                     .orderBy('o.outputId', 'asc')
-                    .first();
-            }
-            if (!output) {
-                output = await baseQuery()
+                    .first());
+                output !== null && output !== void 0 ? output : (output = await baseQuery()
                     .where('o.satoshis', '<', targetSatoshis)
                     .orderBy('o.satoshis', 'desc')
                     .orderBy('o.outputId', 'desc')
-                    .first();
+                    .first());
+                if (output == null)
+                    return undefined;
+                // Post-cutover: transactionId is in transactions_legacy; FK would fail.
+                // markOutputAsSpentBy disables FK via raw knex handle, bypassing
+                // verifyReadyForDatabaseAccess that would re-enable it.
+                // Mapping §2: bridge-period spentBy → transactions_legacy during createAction.
+                await this.markOutputAsSpentBy(output.outputId, {
+                    spendable: false,
+                    spentBy: transactionId
+                }, trx);
+                // Keep behavior identical to the pre-optimization path: ensure lockingScript
+                // is present even when it was offloaded from outputs into rawTx storage.
+                await this.validateOutputScript(output, trx);
+                output.spendable = false;
+                output.spentBy = transactionId;
+                return output;
+            });
+        }
+        finally {
+            if (postCutover && isSqlite) {
+                await this.knex.raw('PRAGMA foreign_keys = ON');
             }
-            if (!output)
-                return undefined;
-            await this.updateOutput(output.outputId, {
-                spendable: false,
-                spentBy: transactionId
-            }, trx);
-            // Keep behavior identical to the pre-optimization path: ensure lockingScript
-            // is present even when it was offloaded from outputs into rawTx storage.
-            await this.validateOutputScript(output, trx);
-            output.spendable = false;
-            output.spentBy = transactionId;
-            return output;
-        });
+        }
         return r;
     }
+    /** Convert null→undefined and Buffer→number[] on a retrieved entity in-place. */
+    deserialiseFromKnex(entity) {
+        for (const key of Object.keys(entity)) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const val = entity[key];
+            if (val === null) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                ;
+                entity[key] = undefined;
+            }
+            else if (Buffer.isBuffer(val)) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                ;
+                entity[key] = Array.from(val);
+            }
+        }
+    }
     /**
      * Helper to force uniform behavior across database engines.
      * Use to process all individual records with time stamps retreived from database.
@@ -1137,27 +1750,21 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
     validateEntity(entity, dateFields, booleanFields) {
         entity.created_at = this.validateDate(entity.created_at);
         entity.updated_at = this.validateDate(entity.updated_at);
-        if (dateFields) {
+        if (dateFields != null) {
             for (const df of dateFields) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
                 if (entity[df])
                     entity[df] = this.validateDate(entity[df]);
             }
         }
-        if (booleanFields) {
+        if (booleanFields != null) {
             for (const df of booleanFields) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
                 if (entity[df] !== undefined)
                     entity[df] = !!entity[df];
             }
         }
-        for (const key of Object.keys(entity)) {
-            const val = entity[key];
-            if (val === null) {
-                entity[key] = undefined;
-            }
-            else if (Buffer.isBuffer(val)) {
-                entity[key] = Array.from(val);
-            }
-        }
+        this.deserialiseFromKnex(entity);
         return entity;
     }
     /**
@@ -1179,7 +1786,7 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
             orderDescending: true,
             paged: { limit: 1 }
         }));
-        const monitorStats = monitorEvent ? JSON.parse(monitorEvent.details) : undefined;
+        const monitorStats = (monitorEvent != null) ? JSON.parse(monitorEvent.details) : undefined;
         const servicesStats = this.getServices().getServicesCallHistory(true);
         const one_day_ago = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
         const one_week_ago = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();