actual-mcp-server 0.16.0 → 0.16.2

package/README.md

@@ -774,7 +774,7 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.16.0 | **Tool Count:** 74 (verified LibreChat-compatible)
+**Version:** 0.16.2 | **Tool Count:** 74 (verified LibreChat-compatible)
 
 ## Sponsor
 

package/dist/src/lib/actual-adapter.js

@@ -1,4 +1,5 @@
 import { subtransactionsSum } from './schemas/common.js';
+import { AsyncLocalStorage } from 'async_hooks';
 import api from '@actual-app/api';
 // @actual-app/api is a CJS package (no "type" field). In NodeNext/ESM context TypeScript
 // cannot expose its named exports via static import syntax. At runtime the default import
@@ -537,6 +538,98 @@ let writeConnectionReuseCount = 0;
 // A fix that drained on every enqueue would close the deadlock and silently turn one
 // batch into N; nothing else in the suite would notice.
 let writeQueueBatchCount = 0;
+/**
+ * #378: the four entity listings, for a write that touches NONE of them.
+ *
+ * Only for operations that write to their OWN table and cannot mint or remove an account,
+ * category, category group or payee: notes, the budget-amount family, tags, rules and
+ * schedules. Each was checked against the installed @actual-app/api source map rather than
+ * assumed: `api/schedule-create`, `api/rule-create` and `api/tag-create` all delegate to their
+ * own handler with no payee path, and the budget writes land in reflect_budgets/zero_budgets.
+ *
+ * NOT for anything that mutates an entity, even indirectly. The traps that kept methods off
+ * this list: `deleteAccount` and `closeAccount` can remove an account's TRANSFER PAYEE;
+ * `updateAccount` renaming an account renames its transfer payee, so the payee listing's
+ * CONTENT changes even though its id set does not, and guards read fields as well as ids;
+ * `deleteCategoryGroup` takes its categories with it; and every transaction write can mint a
+ * payee by two routes (see addTransactions). Those all stay on the invalidate-everything
+ * default, which costs a listing and cannot be wrong.
+ */
+const PRESERVES_ALL_ENTITY_LISTINGS = ['accounts', 'categories', 'categoryGroups', 'payees'];
+/**
+ * The drain's cache lives in an AsyncLocalStorage, NOT in a module-level variable.
+ *
+ * This is structural on purpose. The first version of this used `let drainListingCache` at
+ * module scope, and review could show it was unreachable from outside a drain only by
+ * ARGUING it: every call site happens to sit inside a `queueWriteOperation` body, and
+ * `isProcessingWrites` happens to admit one drain at a time. Both are true and both are
+ * conventions that a future edit can break silently, and the failure they would produce is a
+ * cache shared across sessions and budgets, which in a multi-budget deployment means one
+ * user's guard reading another user's entity list. That is an isolation bug, not a staleness
+ * bug, so it should not rest on a convention.
+ *
+ * With the store, the cache exists only inside the drain's own `.run()`. Any other caller
+ * gets `undefined` and a straight pass-through, and there is nothing to reach even by
+ * mistake.
+ *
+ * BE PRECISE ABOUT WHAT "STRUCTURAL" BUYS, because the trade is real. A module-level binding
+ * was context-INDEPENDENT; an ALS is not. Every readDrainListing call site is
+ * `withConcurrency(() => retry(() => readDrainListing(...)))`, and `withConcurrency` queues a
+ * plain closure on a module-level array when saturated, invoking it from ANOTHER task's
+ * `.finally()`, so a queued task runs in the releasing task's async context. The store
+ * survives that today by arrangement rather than by construction: the drain holds the api lock
+ * for its whole body, so every limiter task inside it is already a drain-context task. If that
+ * ever stops being true the failure is SILENT and benign (a pass-through: correct but slow,
+ * never a wrong or foreign cache, since readDrainListing has no caller outside a drain op), so
+ * case (11) of the drain-cache test squeezes the limiter to 1 and counts the listings. `requestContext` is a separate store carrying the sessionId; this one deliberately
+ * does not ride along in it, because their lifetimes differ (a request spans many drains, a
+ * drain can span two sessions' operations).
+ */
+const drainListingStore = new AsyncLocalStorage();
+/**
+ * Read one entity listing, memoised for the life of the current drain.
+ *
+ * Outside a drain the cache is null and this is a straight pass-through, so non-queued
+ * callers (CLI scripts, startup health checks, the read path) are unaffected and can never
+ * see a cached value.
+ *
+ * The PROMISE is cached, not the resolved value. Two guards that start concurrently inside
+ * one drain therefore share a single in-flight listing rather than racing to start two.
+ */
+async function readDrainListing(kind, fetch) {
+    const drainListingCache = drainListingStore.getStore();
+    if (!drainListingCache)
+        return await fetch();
+    const cached = drainListingCache.get(kind);
+    if (cached)
+        return (await cached);
+    const inFlight = fetch();
+    drainListingCache.set(kind, inFlight);
+    try {
+        return await inFlight;
+    }
+    catch (error) {
+        // A failed listing must not be cached: the next guard in this drain would inherit the
+        // failure and refuse a write for a reason that has nothing to do with its own target.
+        if (drainListingCache.get(kind) === inFlight)
+            drainListingCache.delete(kind);
+        throw error;
+    }
+}
+/**
+ * Drop a cached listing after a write that could have changed it.
+ *
+ * Call this AFTER the write commits, never before: dropping early reopens the window this
+ * exists to close. Over-invalidating is safe and merely costs one listing; under-invalidating
+ * is a false not-found, so when in doubt, invalidate.
+ */
+function invalidateDrainListing(...kinds) {
+    const drainListingCache = drainListingStore.getStore();
+    if (!drainListingCache)
+        return;
+    for (const kind of kinds)
+        drainListingCache.delete(kind);
+}
 /**
  * #278: the ONLY place a write-queue drain is scheduled.
  *
@@ -586,101 +679,171 @@ async function processWriteQueue() {
     // the legacy branch, never that we attribute one session's writes to
     // another's pool entry.
     const batchSessionId = batch[0]?.sessionId;
+    // #378: every distinct session represented in this batch, computed once. See the touch call
+    // in the dispatch loop for why batchSessionId alone is not enough there.
+    const batchSessionIds = [...new Set(batch.map((b) => b.sessionId).filter((x) => !!x))];
     const usePoolBranch = !!batchSessionId && _hasPooledConnection(batchSessionId);
     logger.debug(`[WRITE QUEUE] Processing batch of ${batch.length} operations ` +
         `(sessionId=${batchSessionId ?? 'none'}, poolBranch=${usePoolBranch})`);
     try {
-        await withApiLock(async () => {
-            try {
-                if (usePoolBranch) {
-                    // Pool branch: api singleton already live for this session, no need
-                    // to init or shutdown around the batch. Sync at the end to commit
-                    // writes upstream. On infrastructure-level errors, release the pool
-                    // entry so the next call materialises a fresh connection.
-                    writeConnectionReuseCount++;
-                    logger.debug(`[WRITE QUEUE] Reusing pool connection for session ${batchSessionId} ` +
-                        `(writeReuses=${writeConnectionReuseCount})`);
-                }
-                else {
-                    // Legacy branch: no pool entry, init+shutdown around the batch as
-                    // before. initActualApiForOperation() still short-circuits if the
-                    // api is somehow already live (e.g. another path init'd it).
-                    await initActualApiForOperation();
-                }
-                // Process all queued writes in the same session
-                // Each operation handles its own success/failure
-                await Promise.allSettled(batch.map(async ({ operation, resolve, reject }) => {
-                    try {
-                        // Bound each queued write (#270): a stalled op must reject its own
-                        // promise (so withWriteSession callers don't hang) and let the
-                        // batch settle so the api mutex releases.
-                        const result = await withOpTimeout(operation);
-                        resolve(result);
+        // #378: the drain's listing cache exists ONLY for the duration of this run. There is no
+        // assignment to clear and therefore no path, fatal or otherwise, that can leak it: when
+        // the callback returns the store is gone. This replaced a module-level variable plus a
+        // `finally` that nulled it, which worked but rested on that finally being reached.
+        await drainListingStore.run(new Map(), async () => {
+            await withApiLock(async () => {
+                try {
+                    if (usePoolBranch) {
+                        // Pool branch: api singleton already live for this session, no need
+                        // to init or shutdown around the batch. Sync at the end to commit
+                        // writes upstream. On infrastructure-level errors, release the pool
+                        // entry so the next call materialises a fresh connection.
+                        writeConnectionReuseCount++;
+                        logger.debug(`[WRITE QUEUE] Reusing pool connection for session ${batchSessionId} ` +
+                            `(writeReuses=${writeConnectionReuseCount})`);
                     }
-                    catch (error) {
-                        logger.error('[WRITE QUEUE] Operation failed:', error);
-                        reject(error);
+                    else {
+                        // Legacy branch: no pool entry, init+shutdown around the batch as
+                        // before. initActualApiForOperation() still short-circuits if the
+                        // api is somehow already live (e.g. another path init'd it).
+                        await initActualApiForOperation();
                     }
-                }));
-                // Explicitly sync changes to server before shutdown (legacy) or just
-                // before returning (pool). Persistence guarantee in both branches.
-                logger.debug(`[WRITE QUEUE] Syncing ${batch.length} operations to server`);
-                try {
-                    await withOpTimeout(() => api.sync(), 'sync');
-                    logger.debug(`[WRITE QUEUE] Sync completed`);
-                }
-                catch (syncError) {
-                    logger.error('[WRITE QUEUE] Sync failed:', syncError);
-                    // Pool branch: drop the connection on infrastructure-level sync
-                    // failure so the next write re-initialises cleanly. Mirrors
-                    // withActualApiWrite's policy.
-                    if (usePoolBranch && _shouldDropPoolOnError(syncError)) {
-                        logger.warn(`[WRITE QUEUE] Releasing pool connection for session ${batchSessionId} after sync failure`);
+                    // Process all queued writes in the same session
+                    // Each operation handles its own success/failure
+                    // #378: SEQUENTIAL, in enqueue order. This was `Promise.allSettled(batch.map(...))`,
+                    // which dispatched the whole batch concurrently inside the one api lock.
+                    //
+                    // The api lock makes a drain atomic against OTHER DRAINS. It never made an operation
+                    // atomic against its SIBLINGS in the same batch, and every read-then-write guard
+                    // moved into this adapter by #371 and #376 assumed it did. Reproduced on develop
+                    // before this change: an `actual_payees_delete` and an `actual_payees_update` of the
+                    // SAME payee, issued as parallel tool calls, land in one drain; the update's
+                    // pre-read sees the payee, the guard passes, and rawUpdatePayee then runs against a
+                    // payee the sibling already removed. Per #360 the CRDT apply path INSERTs when the
+                    // row is absent, so that is the phantom partial row the guard exists to prevent. It
+                    // reproduced at every timing tested, including a zero-delay delete.
+                    //
+                    // Caching cannot fix that: it is an ORDERING problem, not a staleness problem. A
+                    // read that happens before the sibling's write is equally wrong whether it came from
+                    // a cache or the database. Ordering the batch is what makes read-decide-write hold.
+                    //
+                    // The concurrency lost is worth very little. Every op in a batch targets the same
+                    // in-process SQLite through one api singleton, so they contend rather than overlap,
+                    // and the memoisation above removes the O(n) listing cost that dominated a bulk
+                    // batch: 200 guarded payee updates now pay ONE listing instead of 200.
+                    //
+                    // Each op keeps its own withOpTimeout (#270) and still settles individually, so one
+                    // stalled or rejected operation cannot hold the api mutex or fail its siblings.
+                    for (const { operation, resolve, reject, preservesListings } of batch) {
                         try {
-                            await connectionPool.shutdownConnection(batchSessionId);
+                            const result = await withOpTimeout(operation);
+                            resolve(result);
                         }
-                        catch (_e) {
-                            /* swallow */
+                        catch (error) {
+                            logger.error('[WRITE QUEUE] Operation failed:', error);
+                            reject(error);
+                        }
+                        finally {
+                            // #378: drop everything this operation did not explicitly promise to leave alone,
+                            // and do it whether the op resolved OR THREW. A failed op may still have written
+                            // before failing, so a rejection is not evidence that nothing changed.
+                            //
+                            // The default is invalidate-all, so a write method added later without an
+                            // annotation is merely slower, never wrong. Only the reverse mistake, claiming a
+                            // listing is preserved when it is not, produces a false not-found, and that
+                            // requires someone to write the claim down.
+                            const preserved = new Set(preservesListings ?? []);
+                            invalidateDrainListing(...['accounts', 'categories', 'categoryGroups', 'payees'].filter((k) => !preserved.has(k)));
+                            // #378: keep every session in this batch alive for the length of the drain.
+                            //
+                            // `connectionPool.touch()` is driven by inbound HTTP requests, not by write ops,
+                            // so `lastActivity` does not advance while a drain runs. That was harmless while
+                            // the batch ran concurrently and a drain was bounded by roughly one
+                            // ACTUAL_OP_TIMEOUT_MS. Sequential dispatch makes a drain's wall clock the SUM of
+                            // its ops, so a batch of slow ops can now outlive SESSION_IDLE_TIMEOUT_MINUTES
+                            // (default 5) and be swept mid-drain. The sweep's shutdownConnection calls
+                            // api.shutdown() WITHOUT holding withApiLock, which is the same hazard this file
+                            // already documents as the reason stdio is kept off the pool: it tears the
+                            // singleton down underneath an in-flight operation.
+                            //
+                            // THIS MUST STAY INSIDE THE LOOP. A single touch at drain start does nothing for
+                            // a drain whose wall clock is the SUM of its ops, which is the entire reason the
+                            // hazard exists. Hoisting it out as a tidy-up reopens the bug in full, and case
+                            // (8) of tests/unit/adapter_drain_listing_cache.test.js samples the pool clock
+                            // from inside the raw call specifically so that hoist goes red.
+                            //
+                            // AND IT MUST COVER EVERY SESSION IN THE BATCH, not just batchSessionId. That is
+                            // `batch[0]?.sessionId`, a heuristic that is sound for the pool-branch decision
+                            // above (a wrong guess merely falls back to the legacy path) and NOT sound here.
+                            // The write queue is process-global, so two HTTP sessions writing inside the same
+                            // WRITE_SESSION_DELAY_MS window batch together. Sweeping the untouched one calls
+                            // api.shutdown() on the PROCESS-GLOBAL singleton, which kills the other session's
+                            // in-flight operation as well. `touch` is a Map lookup that no-ops on an unknown
+                            // id and cannot throw, so covering the whole set costs nothing.
+                            for (const sid of batchSessionIds)
+                                connectionPool.touch(sid);
                         }
                     }
-                    // Don't throw - we still want to shutdown cleanly
-                    // Individual operation errors were already reported to callers
-                }
-                if (!usePoolBranch) {
-                    // Legacy branch only: actually shut the singleton down.
-                    // shutdownActualApi() itself short-circuits to sync-only if another
-                    // path has active pool sessions, so this is safe under contention.
-                    await shutdownActualApi();
-                }
-                logger.debug(`[WRITE QUEUE] Batch completed successfully`);
-            }
-            catch (error) {
-                logger.error('[WRITE QUEUE] Fatal error in write queue:', error);
-                // Reject any operations that weren't processed
-                batch.forEach(({ reject }) => {
+                    // Explicitly sync changes to server before shutdown (legacy) or just
+                    // before returning (pool). Persistence guarantee in both branches.
+                    logger.debug(`[WRITE QUEUE] Syncing ${batch.length} operations to server`);
                     try {
-                        reject(error);
+                        await withOpTimeout(() => api.sync(), 'sync');
+                        logger.debug(`[WRITE QUEUE] Sync completed`);
+                    }
+                    catch (syncError) {
+                        logger.error('[WRITE QUEUE] Sync failed:', syncError);
+                        // Pool branch: drop the connection on infrastructure-level sync
+                        // failure so the next write re-initialises cleanly. Mirrors
+                        // withActualApiWrite's policy.
+                        if (usePoolBranch && _shouldDropPoolOnError(syncError)) {
+                            logger.warn(`[WRITE QUEUE] Releasing pool connection for session ${batchSessionId} after sync failure`);
+                            try {
+                                await connectionPool.shutdownConnection(batchSessionId);
+                            }
+                            catch (_e) {
+                                /* swallow */
+                            }
+                        }
+                        // Don't throw - we still want to shutdown cleanly
+                        // Individual operation errors were already reported to callers
                     }
-                    catch (e) {
-                        logger.error('[WRITE QUEUE] Error rejecting operation:', e);
+                    if (!usePoolBranch) {
+                        // Legacy branch only: actually shut the singleton down.
+                        // shutdownActualApi() itself short-circuits to sync-only if another
+                        // path has active pool sessions, so this is safe under contention.
+                        await shutdownActualApi();
                     }
-                });
-                // Pool branch: drop the pool entry if the error suggests infrastructure
-                // corruption. Legacy branch: full shutdown.
-                if (usePoolBranch) {
-                    if (_shouldDropPoolOnError(error)) {
+                    logger.debug(`[WRITE QUEUE] Batch completed successfully`);
+                }
+                catch (error) {
+                    logger.error('[WRITE QUEUE] Fatal error in write queue:', error);
+                    // Reject any operations that weren't processed
+                    batch.forEach(({ reject }) => {
                         try {
-                            await connectionPool.shutdownConnection(batchSessionId);
+                            reject(error);
                         }
-                        catch (_e) {
-                            /* swallow */
+                        catch (e) {
+                            logger.error('[WRITE QUEUE] Error rejecting operation:', e);
+                        }
+                    });
+                    // Pool branch: drop the pool entry if the error suggests infrastructure
+                    // corruption. Legacy branch: full shutdown.
+                    if (usePoolBranch) {
+                        if (_shouldDropPoolOnError(error)) {
+                            try {
+                                await connectionPool.shutdownConnection(batchSessionId);
+                            }
+                            catch (_e) {
+                                /* swallow */
+                            }
                         }
                     }
+                    else {
+                        await shutdownActualApi();
+                    }
                 }
-                else {
-                    await shutdownActualApi();
-                }
-            }
+            });
         });
     }
     finally {
@@ -694,7 +857,7 @@ async function processWriteQueue() {
             scheduleWriteQueueDrain();
     }
 }
-function queueWriteOperation(operation) {
+function queueWriteOperation(operation, options) {
     // ACL enforcement at the write-queue entry (#156). Failing here means the
     // op is never enqueued and no upstream resource is touched.
     _enforceBudgetAcl();
@@ -703,13 +866,27 @@ function queueWriteOperation(operation) {
     // decision in processWriteQueue would always miss. See #158.
     const sessionId = _resolveSessionId();
     return new Promise((resolve, reject) => {
-        const entry = { operation, resolve, reject, sessionId };
+        const entry = {
+            operation,
+            resolve,
+            reject,
+            sessionId,
+            preservesListings: options?.preservesListings,
+        };
         // #278: bound queue RESIDENCY, not just execution. #270's withOpTimeout bounds an
         // operation that is RUNNING; it cannot bound one that never starts. Reuse the same
         // knob so there is one timeout concept: ACTUAL_OP_TIMEOUT_MS, with <= 0 meaning
-        // disabled (matching withOpTimeout). Worst case for a single call is therefore
-        // residency + execution = 2 * ACTUAL_OP_TIMEOUT_MS; residency is normally under
-        // WRITE_SESSION_DELAY_MS (100ms).
+        // disabled (matching withOpTimeout). Residency is normally under WRITE_SESSION_DELAY_MS
+        // (100ms).
+        //
+        // #378 CHANGED THIS BOUND and it used to read "worst case for a single call is therefore
+        // residency + execution = 2 * ACTUAL_OP_TIMEOUT_MS". That was true while the batch ran
+        // concurrently. It now runs sequentially, and residency timers are cleared for EVERY
+        // entry at dispatch while withOpTimeout bounds only the op currently running, so the
+        // honest worst case for the k-th op in a batch is residency + k * ACTUAL_OP_TIMEOUT_MS.
+        // A drain's wall clock went from the MAX of its ops to the SUM. In practice each op is
+        // milliseconds against in-process SQLite, but see the touch() call in processWriteQueue
+        // for the one consequence that had to be closed rather than merely documented.
         const residencyLimitMs = config.ACTUAL_OP_TIMEOUT_MS;
         if (Number.isFinite(residencyLimitMs) && residencyLimitMs > 0) {
             entry.residencyTimer = setTimeout(() => {
@@ -806,6 +983,15 @@ export async function getAccounts() {
 // addTransactions returns various formats: "ok", array of IDs, or Transaction objects
 export async function addTransactions(txs, options = {}) {
     observability.incrementToolCall('actual.transactions.create').catch(() => { });
+    // #378: a transaction write cannot change the account, category or category-group
+    // listings, so a bulk import pays ONE accounts listing for its guard instead of one per
+    // transaction. `payees` is deliberately NOT claimed: upstream's addTransactions runs
+    // normalizeTransactions, which returns `payeesToCreate` and creates a payee from a raw
+    // payee name (verified in loot-core/src/server/accounts/sync.ts via the source map). There
+    // is a SECOND route too, and it is not gated on the payee_name input at all: runRules fires
+    // unconditionally, and resolvePayeeNameForRules calls insertPayee when a rule action sets
+    // `payee: 'new'`. So a transaction write CAN change the payee listing by two independent
+    // paths, and claiming otherwise would produce a false not-found for a payee it just created.
     return queueWriteOperation(async () => {
         // The Actual API expects addTransactions(accountId, transactions, options)
         // Extract accountId from the first transaction and remove it from transaction objects
@@ -830,7 +1016,7 @@ export async function addTransactions(txs, options = {}) {
         // deliberately still allowed: importing history into a closed account is legitimate,
         // which is why this diverges from createTransfer, where a closed account would be an
         // odd transfer destination.
-        const accounts = await withConcurrency(() => retry(() => rawGetAccounts(), { retries: 2, backoffMs: 200 }));
+        const accounts = await withConcurrency(() => retry(() => readDrainListing('accounts', () => rawGetAccounts()), { retries: 2, backoffMs: 200 }));
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const accountExists = accounts.some((a) => a?.id === accountId);
         if (!accountExists) {
@@ -865,7 +1051,7 @@ export async function addTransactions(txs, options = {}) {
             return [result.id];
         }
         return [];
-    });
+    }, { preservesListings: ['accounts', 'categories', 'categoryGroups'] });
 }
 export async function importTransactions(accountId, txs) {
     observability.incrementToolCall('actual.transactions.import').catch(() => { });
@@ -881,7 +1067,7 @@ export async function createTransfer(params) {
         if (params.from_account === params.to_account) {
             return { success: false, error: 'from_account and to_account must be different accounts.' };
         }
-        const accounts = await withConcurrency(() => retry(() => rawGetAccounts(), { retries: 2, backoffMs: 200 }));
+        const accounts = await withConcurrency(() => retry(() => readDrainListing('accounts', () => rawGetAccounts()), { retries: 2, backoffMs: 200 }));
         const fromAcc = accounts.find((a) => a.id === params.from_account);
         const toAcc = accounts.find((a) => a.id === params.to_account);
         if (!fromAcc)
@@ -892,7 +1078,7 @@ export async function createTransfer(params) {
             return { success: false, error: `Account '${params.to_account}' not found. Use actual_accounts_list to find valid accounts.` };
         if (toAcc.closed)
             return { success: false, error: `Destination account '${toAcc.name}' is closed.` };
-        const payees = await withConcurrency(() => retry(() => rawGetPayees(), { retries: 2, backoffMs: 200 }));
+        const payees = await withConcurrency(() => retry(() => readDrainListing('payees', () => rawGetPayees()), { retries: 2, backoffMs: 200 }));
         const transferPayee = payees.find((p) => p.transfer_acct === params.to_account && !p.tombstone);
         if (!transferPayee) {
             return { success: false, error: `No transfer payee found for destination account '${toAcc.name}'. The account may not support transfers.` };
@@ -992,9 +1178,12 @@ export async function getBudgetMonth(month) {
 }
 export async function setBudgetAmount(month, categoryId, amount) {
     observability.incrementToolCall('actual.budgets.setAmount').catch(() => { });
+    // #378: a budget amount is written to the zero/reflect budget tables and cannot change any
+    // of the four entity listings, so a month of category budgets pays ONE categories listing
+    // for its guard rather than one per category.
     return queueWriteOperation(async () => {
         // Pre-flight: verify category exists — nil/unknown UUIDs silently no-op in Actual Budget
-        const categories = await withConcurrency(() => retry(() => rawGetCategories(), { retries: 2, backoffMs: 200 }));
+        const categories = await withConcurrency(() => retry(() => readDrainListing('categories', () => rawGetCategories()), { retries: 2, backoffMs: 200 }));
         const exists = categories.some((c) => c.id === categoryId);
         if (!exists) {
             // #377: MUST be a typed refusal. `budgets_setAmount` is one of the two tools whose
@@ -1022,7 +1211,7 @@ export async function setBudgetAmount(month, categoryId, amount) {
         }
         const result = await withConcurrency(() => retry(() => rawSetBudgetAmount(month, categoryId, amount), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
         return result;
-    });
+    }, { preservesListings: ['accounts', 'categories', 'categoryGroups', 'payees'] });
 }
 export async function transferBudgetAmount(month, fromCategoryId, toCategoryId, amount) {
     observability.incrementToolCall('actual.budgets.transfer').catch(() => { });
@@ -1059,7 +1248,7 @@ export async function transferBudgetAmount(month, fromCategoryId, toCategoryId,
             fromCategory: { id: fromCategoryId, previousAmount: prevFrom, newAmount: prevFrom - amount },
             toCategory: { id: toCategoryId, previousAmount: prevTo, newAmount: prevTo + amount },
         };
-    });
+    }, { preservesListings: PRESERVES_ALL_ENTITY_LISTINGS });
 }
 export async function createAccount(account, initialBalance) {
     observability.incrementToolCall('actual.accounts.create').catch(() => { });
@@ -1073,12 +1262,15 @@ export async function createAccount(account, initialBalance) {
 export async function updateAccount(id, fields) {
     observability.incrementToolCall('actual.accounts.update').catch(() => { });
     return queueWriteOperation(async () => {
+        // #378: this guard's pre-read is safe against a SIBLING operation in the same drain only
+        // because the batch dispatches sequentially. It reads a listing memoised for this drain,
+        // which the previous operation invalidated unless it declared it could not change it.
         // #360: `db.update` does not run a SQL UPDATE. It sends CRDT messages, and the apply
         // path INSERTs when the row was absent, so an unknown id CREATES a partial row rather
         // than matching nothing. Refuse first, the way updateTag and updateRule already do.
         // A CLOSED account is still updatable: getAccounts filters `tombstone = 0`, not
         // `closed = 0`, so this refuses only ids that genuinely do not exist.
-        const accounts = await withConcurrency(() => retry(() => rawGetAccounts(), { retries: 2, backoffMs: 200 }));
+        const accounts = await withConcurrency(() => retry(() => readDrainListing('accounts', () => rawGetAccounts()), { retries: 2, backoffMs: 200 }));
         if (!(Array.isArray(accounts) && accounts.some((a) => a?.id === id))) {
             throw new NotFoundRefusal('Account', id, 'actual_accounts_list');
         }
@@ -1243,12 +1435,15 @@ export async function deleteTransaction(id) {
 export async function updateCategory(id, fields) {
     observability.incrementToolCall('actual.categories.update').catch(() => { });
     return queueWriteOperation(async () => {
+        // #378: this guard's pre-read is safe against a SIBLING operation in the same drain only
+        // because the batch dispatches sequentially. It reads a listing memoised for this drain,
+        // which the previous operation invalidated unless it declared it could not change it.
         // #360: `db.update` does not run a SQL UPDATE. It sends CRDT messages, and the apply
         // path INSERTs when the row was absent, so an unknown id CREATES a partial row rather
         // than matching nothing. Refuse first, the way updateTag and updateRule already do.
         // Called with no argument, upstream returns every category in every group, hidden
         // included, so a hidden category is not misreported as missing.
-        const categories = await withConcurrency(() => retry(() => rawGetCategories(), { retries: 2, backoffMs: 200 }));
+        const categories = await withConcurrency(() => retry(() => readDrainListing('categories', () => rawGetCategories()), { retries: 2, backoffMs: 200 }));
         if (!(Array.isArray(categories) && categories.some((c) => c?.id === id))) {
             throw new NotFoundRefusal('Category', id, 'actual_categories_get');
         }
@@ -1259,7 +1454,7 @@ export async function deleteCategory(id) {
     observability.incrementToolCall('actual.categories.delete').catch(() => { });
     return queueWriteOperation(async () => {
         // Pre-flight: verify category exists to avoid ECONNRESET on missing id (BUG-1)
-        const categories = await withConcurrency(() => retry(() => rawGetCategories(), { retries: 2, backoffMs: 200 }));
+        const categories = await withConcurrency(() => retry(() => readDrainListing('categories', () => rawGetCategories()), { retries: 2, backoffMs: 200 }));
         const exists = categories.some((c) => c.id === id);
         if (!exists) {
             throw new NotFoundRefusal('Category', id, 'actual_categories_get');
@@ -1270,6 +1465,9 @@ export async function deleteCategory(id) {
 export async function updatePayee(id, fields) {
     observability.incrementToolCall('actual.payees.update').catch(() => { });
     return queueWriteOperation(async () => {
+        // #378: this guard's pre-read is safe against a SIBLING operation in the same drain only
+        // because the batch dispatches sequentially. It reads a listing memoised for this drain,
+        // which the previous operation invalidated unless it declared it could not change it.
         // #360: `db.update` does not run a SQL UPDATE. It sends CRDT messages, and the apply
         // path INSERTs when the row was absent, so an unknown id CREATES a partial row rather
         // than matching nothing. Refuse first, the way updateTag and updateRule already do.
@@ -1280,7 +1478,7 @@ export async function updatePayee(id, fields) {
         // strictly unreachable. It is accepted because updating an orphaned transfer payee,
         // whose account no longer exists, is not a real workflow, and because the alternative
         // is leaving four tools able to create phantom rows.
-        const payees = await withConcurrency(() => retry(() => rawGetPayees(), { retries: 2, backoffMs: 200 }));
+        const payees = await withConcurrency(() => retry(() => readDrainListing('payees', () => rawGetPayees()), { retries: 2, backoffMs: 200 }));
         if (!(Array.isArray(payees) && payees.some((p) => p?.id === id))) {
             throw new NotFoundRefusal('Payee', id, 'actual_payees_get');
         }
@@ -1340,7 +1538,7 @@ export async function deletePayee(id) {
     observability.incrementToolCall('actual.payees.delete').catch(() => { });
     return queueWriteOperation(async () => {
         // Pre-flight: verify payee exists to avoid ECONNRESET on missing id (BUG-2)
-        const payees = await withConcurrency(() => retry(() => rawGetPayees(), { retries: 2, backoffMs: 200 }));
+        const payees = await withConcurrency(() => retry(() => readDrainListing('payees', () => rawGetPayees()), { retries: 2, backoffMs: 200 }));
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const found = payees.find((p) => p.id === id);
         const exists = Boolean(found);
@@ -1377,7 +1575,7 @@ export async function createRule(rule) {
         const raw = await withConcurrency(() => retry(() => rawCreateRule(rule), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
         const id = normalizeToId(raw);
         return id;
-    });
+    }, { preservesListings: PRESERVES_ALL_ENTITY_LISTINGS });
 }
 export async function updateRule(id, fields) {
     observability.incrementToolCall('actual.rules.update').catch(() => { });
@@ -1413,7 +1611,7 @@ export async function updateRule(id, fields) {
         logger.debug(`[UPDATE RULE] Updating rule ${id} with merged fields: ${JSON.stringify(rule)}`);
         await withConcurrency(() => retry(() => rawUpdateRule(rule), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
         logger.debug(`[UPDATE RULE] Update completed for rule ${id}`);
-    });
+    }, { preservesListings: PRESERVES_ALL_ENTITY_LISTINGS });
 }
 /**
  * #355: RETURNS the upstream verdict instead of discarding it, for the same reason
@@ -1474,7 +1672,7 @@ export async function upsertRule(input, stageWasSupplied) {
             ruleData.stage = null;
         const rawId = await withConcurrency(() => retry(() => rawCreateRule(ruleData), { retries: 0, backoffMs: 200 }));
         return { id: normalizeToId(rawId), created: true };
-    });
+    }, { preservesListings: PRESERVES_ALL_ENTITY_LISTINGS });
 }
 /**
  * #376: the existence guard and the schedule-owned refusal moved here from
@@ -1519,7 +1717,7 @@ export async function deleteRule(id) {
                 'instead with actual_schedules_delete (find it with actual_schedules_get), ' +
                 'which removes this rule too.');
         }
-    });
+    }, { preservesListings: PRESERVES_ALL_ENTITY_LISTINGS });
 }
 export async function getSchedules() {
     return withActualApi(async () => {
@@ -1536,13 +1734,13 @@ export async function createSchedule(schedule) {
         const raw = await withConcurrency(() => retry(() => rawCreateSchedule(schedule), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
         const id = normalizeToId(raw);
         return id;
-    });
+    }, { preservesListings: PRESERVES_ALL_ENTITY_LISTINGS });
 }
 export async function updateSchedule(id, fields, resetNextDate) {
     observability.incrementToolCall('actual.schedules.update').catch(() => { });
     return queueWriteOperation(async () => {
         await withConcurrency(() => retry(() => rawUpdateSchedule(id, fields, resetNextDate), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
-    });
+    }, { preservesListings: PRESERVES_ALL_ENTITY_LISTINGS });
 }
 /**
  * #376: the existence guard and the constraint-error translation moved here from
@@ -1566,13 +1764,13 @@ export async function deleteSchedule(id) {
             }
             throw err;
         }
-    });
+    }, { preservesListings: PRESERVES_ALL_ENTITY_LISTINGS });
 }
 export async function setBudgetCarryover(month, categoryId, flag) {
     observability.incrementToolCall('actual.budgets.setCarryover').catch(() => { });
     return queueWriteOperation(async () => {
         await withConcurrency(() => retry(() => rawSetBudgetCarryover(month, categoryId, flag), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
-    });
+    }, { preservesListings: PRESERVES_ALL_ENTITY_LISTINGS });
 }
 /**
  * #357, at the adapter layer since #371.
@@ -1601,7 +1799,7 @@ export async function setBudgetCarryover(month, categoryId, flag) {
 export async function closeAccount(id, transferAccountId, transferCategoryId) {
     observability.incrementToolCall('actual.accounts.close').catch(() => { });
     return queueWriteOperation(async () => {
-        const before = await withConcurrency(() => retry(() => rawGetAccounts(), { retries: 2, backoffMs: 200 }));
+        const before = await withConcurrency(() => retry(() => readDrainListing('accounts', () => rawGetAccounts()), { retries: 2, backoffMs: 200 }));
         const list = Array.isArray(before) ? before : [];
         const target = list.find((a) => a?.id === id);
         if (!target) {
@@ -1630,7 +1828,7 @@ export async function closeAccount(id, transferAccountId, transferCategoryId) {
             // #359's lesson applied to the only WRITE this path can add. Upstream forwards this id
             // straight into `transaction-add` unchecked, so a bogus value writes a "Closing
             // account" transaction carrying a category that does not exist, and syncs it.
-            const categories = await withConcurrency(() => retry(() => rawGetCategories(), { retries: 2, backoffMs: 200 }));
+            const categories = await withConcurrency(() => retry(() => readDrainListing('categories', () => rawGetCategories()), { retries: 2, backoffMs: 200 }));
             const known = Array.isArray(categories) && categories.some((c) => c?.id === transferCategoryId);
             if (!known) {
                 throw new Error(`Transfer category "${transferCategoryId}" not found. Use actual_categories_get to ` +
@@ -1668,7 +1866,7 @@ export async function closeAccount(id, transferAccountId, transferCategoryId) {
 export async function reopenAccount(id) {
     observability.incrementToolCall('actual.accounts.reopen').catch(() => { });
     return queueWriteOperation(async () => {
-        const before = await withConcurrency(() => retry(() => rawGetAccounts(), { retries: 2, backoffMs: 200 }));
+        const before = await withConcurrency(() => retry(() => readDrainListing('accounts', () => rawGetAccounts()), { retries: 2, backoffMs: 200 }));
         const target = (Array.isArray(before) ? before : []).find((a) => a?.id === id);
         if (!target) {
             throw new Error(`Account "${id}" not found, so it cannot be reopened. Use actual_accounts_list to see ` +
@@ -1716,13 +1914,16 @@ export async function createCategoryGroup(group) {
 export async function updateCategoryGroup(id, fields) {
     observability.incrementToolCall('actual.category_groups.update').catch(() => { });
     return queueWriteOperation(async () => {
+        // #378: this guard's pre-read is safe against a SIBLING operation in the same drain only
+        // because the batch dispatches sequentially. It reads a listing memoised for this drain,
+        // which the previous operation invalidated unless it declared it could not change it.
         // #360: `db.update` does not run a SQL UPDATE. It sends CRDT messages, and the apply
         // path INSERTs when the row was absent, so an unknown id CREATES a partial row rather
         // than matching nothing. Refuse first, the way updateTag and updateRule already do.
         // Called with no argument, upstream returns all groups including hidden ones, so a
         // hidden group is not misreported as missing (the same reason category_groups_delete
         // can rely on this listing).
-        const groups = await withConcurrency(() => retry(() => rawGetCategoryGroups(), { retries: 2, backoffMs: 200 }));
+        const groups = await withConcurrency(() => retry(() => readDrainListing('categoryGroups', () => rawGetCategoryGroups()), { retries: 2, backoffMs: 200 }));
         if (!(Array.isArray(groups) && groups.some((g) => g?.id === id))) {
             throw new NotFoundRefusal('Category group', id, 'actual_category_groups_get');
         }
@@ -1737,7 +1938,7 @@ export async function updateCategoryGroup(id, fields) {
 export async function deleteCategoryGroup(id) {
     observability.incrementToolCall('actual.category_groups.delete').catch(() => { });
     return queueWriteOperation(async () => {
-        const groups = await withConcurrency(() => retry(() => rawGetCategoryGroups(), { retries: 2, backoffMs: 200 }));
+        const groups = await withConcurrency(() => retry(() => readDrainListing('categoryGroups', () => rawGetCategoryGroups()), { retries: 2, backoffMs: 200 }));
         if (!Array.isArray(groups) || !groups.some((g) => g?.id === id)) {
             throw new NotFoundRefusal('Category group', id, 'actual_category_groups_get');
         }
@@ -1779,7 +1980,7 @@ function summariseIds(ids, limit = 5) {
 export async function mergePayees(targetId, mergeIds) {
     observability.incrementToolCall('actual.payees.merge').catch(() => { });
     return queueWriteOperation(async () => {
-        const payees = await withConcurrency(() => retry(() => rawGetPayees(), { retries: 2, backoffMs: 200 }));
+        const payees = await withConcurrency(() => retry(() => readDrainListing('payees', () => rawGetPayees()), { retries: 2, backoffMs: 200 }));
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const byId = new Map(payees.map((p) => [p.id, p]));
         const target = byId.get(targetId);
@@ -1855,11 +2056,22 @@ export async function getPayeeRules(payeeId) {
         return filtered;
     });
 }
+/**
+ * #378 CAVEAT ON THIS METHOD'S preservesListings CLAIM. This forwards an arbitrary callback to
+ * rawBatchBudgetUpdates, which upstream is only a batch-budget-start / await func() /
+ * batch-budget-end transaction bracket: it performs no writes of its own, so the annotation is
+ * really a claim about whatever the CALLBACK does. It holds today because
+ * src/tools/budget_updates_batch.ts is the only caller passing a real callback and it calls
+ * only rawSetBudgetAmount and rawSetBudgetCarryover, both verified listing-safe. Nothing in
+ * the signature or upstream constrains that. RE-AUDIT THIS when a second caller appears: a
+ * callback reaching rawCreateCategory or rawDeleteAccount would violate the claim with no
+ * compiler or runtime signal, and the symptom would be a false not-found elsewhere in the drain.
+ */
 export async function batchBudgetUpdates(fn) {
     observability.incrementToolCall('actual.budgets.batchUpdates').catch(() => { });
     return queueWriteOperation(async () => {
         await withConcurrency(() => retry(() => rawBatchBudgetUpdates(fn), { retries: 2, backoffMs: 200 }));
-    });
+    }, { preservesListings: PRESERVES_ALL_ENTITY_LISTINGS });
 }
 /**
  * #355: RETURNS the upstream verdict instead of discarding it.
@@ -1906,13 +2118,13 @@ export async function holdBudgetForNextMonth(month, amount) {
         await withConcurrency(() => retry(() => rawHoldBudgetForNextMonth(month, amount), { retries: 0, backoffMs: 200 }));
         const after = await withConcurrency(() => retry(() => rawGetBudgetMonth(month), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
         return Number(after?.forNextMonth ?? 0) - heldBefore;
-    });
+    }, { preservesListings: PRESERVES_ALL_ENTITY_LISTINGS });
 }
 export async function resetBudgetHold(month) {
     observability.incrementToolCall('actual.budgets.resetHold').catch(() => { });
     return queueWriteOperation(async () => {
         await withConcurrency(() => retry(() => rawResetBudgetHold(month), { retries: 2, backoffMs: 200 }));
-    });
+    }, { preservesListings: PRESERVES_ALL_ENTITY_LISTINGS });
 }
 export async function runQuery(queryString) {
     try {
@@ -2421,7 +2633,7 @@ export async function createTag(tag) {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const raw = await withConcurrency(() => retry(() => rawCreateTag(tag), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
         return normalizeToId(raw);
-    });
+    }, { preservesListings: PRESERVES_ALL_ENTITY_LISTINGS });
 }
 export async function updateTag(id, fields) {
     observability.incrementToolCall('actual.tags.update').catch(() => { });
@@ -2434,7 +2646,7 @@ export async function updateTag(id, fields) {
             throw new NotFoundRefusal('Tag', id, 'actual_tags_list');
         }
         await withConcurrency(() => retry(() => rawUpdateTag(id, fields), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
-    });
+    }, { preservesListings: PRESERVES_ALL_ENTITY_LISTINGS });
 }
 export async function deleteTag(id) {
     observability.incrementToolCall('actual.tags.delete').catch(() => { });
@@ -2447,7 +2659,7 @@ export async function deleteTag(id) {
             throw new NotFoundRefusal('Tag', id, 'actual_tags_list');
         }
         await withConcurrency(() => retry(() => rawDeleteTag(id), { retries: 0, backoffMs: 200 }));
-    });
+    }, { preservesListings: PRESERVES_ALL_ENTITY_LISTINGS });
 }
 export async function getNote(id) {
     return withActualApi(async () => {
@@ -2479,10 +2691,10 @@ export async function updateNote(id, note) {
         if (!BUDGET_MONTH_NOTE_RE.test(id)) {
             const has = (rows) => Array.isArray(rows) && rows.some((e) => e?.id === id);
             const [accounts, categories, categoryGroups, payees] = await Promise.all([
-                withConcurrency(() => retry(() => rawGetAccounts(), { retries: 2, backoffMs: 200 })),
-                withConcurrency(() => retry(() => rawGetCategories(), { retries: 2, backoffMs: 200 })),
-                withConcurrency(() => retry(() => rawGetCategoryGroups(), { retries: 2, backoffMs: 200 })),
-                withConcurrency(() => retry(() => rawGetPayees(), { retries: 2, backoffMs: 200 })),
+                withConcurrency(() => retry(() => readDrainListing('accounts', () => rawGetAccounts()), { retries: 2, backoffMs: 200 })),
+                withConcurrency(() => retry(() => readDrainListing('categories', () => rawGetCategories()), { retries: 2, backoffMs: 200 })),
+                withConcurrency(() => retry(() => readDrainListing('categoryGroups', () => rawGetCategoryGroups()), { retries: 2, backoffMs: 200 })),
+                withConcurrency(() => retry(() => readDrainListing('payees', () => rawGetPayees()), { retries: 2, backoffMs: 200 })),
             ]);
             if (!has(accounts) && !has(categories) && !has(categoryGroups) && !has(payees)) {
                 // Guarding matters here for the same reason as #360: upstream's note write is a
@@ -2492,7 +2704,7 @@ export async function updateNote(id, note) {
             }
         }
         await withConcurrency(() => retry(() => rawUpdateNote(id, note), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
-    });
+    }, { preservesListings: PRESERVES_ALL_ENTITY_LISTINGS });
 }
 /**
  * Export the currently-loaded budget as a zip (#332).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.16.0",
+  "version": "0.16.2",
   "engines": {
     "node": ">=22.0.0",
     "npm": ">=10.0.0"
@@ -30,7 +30,7 @@
     "verify-tools": "npm run build && node scripts/verify-tools.js",
     "check:coverage": "node scripts/list-actual-api-methods.mjs",
     "direct-sync": "node scripts/direct-sync/bank-sync-direct.mjs",
-    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/schema_json_openai_compat.test.js && node tests/unit/config_https_validation.test.js && node tests/unit/config_data_dir.test.js && node tests/unit/config_drift.test.js && node tests/unit/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.test.js && node tests/unit/unraid_template_alignment.test.js && node tests/unit/entrypoint_invariants.test.js && node tests/unit/e2e_spec_collection.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/workflow_release_guards.test.js && node tests/unit/report_train_failure.test.js && node tests/unit/unit_chain_membership.test.js && node tests/unit/api_surface_drift.test.js && node tests/unit/write_effect_audit_staleness.test.js && node tests/unit/write_effect_audit_membership.test.js && node tests/unit/tool_annotations.test.js && node tests/unit/tool_id_schema_drift.test.js && node tests/unit/api_coverage_baseline.test.js && node tests/unit/train_preflight.test.js && node tests/unit/verify_published_artifacts.test.js && node tests/unit/report_train_stale.test.js && node tests/unit/stdio_framing_check.test.js && node tests/unit/server_info.test.js && node tests/unit/transfers_create.test.js && node tests/unit/bot_target_branch.test.js && node tests/unit/auth_posture.test.js && node tests/unit/auth_posture_wiring.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_hold_for_next_month.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/httpServer_session_not_found.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/accounts_delete.test.js && node tests/unit/update_tools_not_found.test.js && node tests/unit/accounts_close.test.js && node tests/unit/accounts_reopen.test.js && node tests/unit/payees_delete.test.js && node tests/unit/payees_merge.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_oidc_jwks_discovery.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpServer_bind_host.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.test.js && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/transactions_update_splits.test.js && node tests/unit/entities_search.test.js && node tests/unit/transactions_import_schema.test.js && node tests/unit/tool_schema_shape.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/stdio_budget_switch.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.test.js && node tests/unit/adapter_op_timeout.test.js && node tests/unit/adapter_write_queue_wakeup.test.js && node tests/unit/ci_workflow_guards.test.js && node tests/unit/node_version_guard.test.js && node tests/unit/node_version_drift.test.js && node tests/unit/observability_smoke.test.js && node tests/unit/residue_pattern.test.js && node tests/unit/dual_transport_gate.test.js && node tests/unit/manual_assertions_use_helper.test.js && node tests/unit/server_version_guard.test.js && node tests/unit/payee_rules_reference_filter.test.js && node tests/unit/oidc_metadata_discovery.test.js && node tests/unit/httpServer_oauth_metadata_route.test.js && node tests/unit/httpServer_mcp_info_route.test.js && node tests/unit/residue_sweep_balance_account.test.js && node tests/unit/tool_factory.test.js && node tests/unit/budget_registry_parse.test.js && node tests/unit/preferences_get.test.js && node tests/unit/budgets_export.test.js && node tests/unit/budgets_import.test.js && node tests/unit/budgets_import_syncid.test.js && node tests/unit/budget_acl_dynamic.test.js && node tests/unit/budget_acl_identity_map.test.js && node tests/unit/budget_acl_userinfo.test.js && node tests/unit/acl_e2e_fixture_contract.test.js && node tests/unit/budget_acl_middleware.test.js && node tests/unit/rules_stage.test.js",
+    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/schema_json_openai_compat.test.js && node tests/unit/config_https_validation.test.js && node tests/unit/config_data_dir.test.js && node tests/unit/config_drift.test.js && node tests/unit/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.test.js && node tests/unit/unraid_template_alignment.test.js && node tests/unit/entrypoint_invariants.test.js && node tests/unit/e2e_spec_collection.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/workflow_release_guards.test.js && node tests/unit/report_train_failure.test.js && node tests/unit/unit_chain_membership.test.js && node tests/unit/api_surface_drift.test.js && node tests/unit/write_effect_audit_staleness.test.js && node tests/unit/write_effect_audit_membership.test.js && node tests/unit/tool_annotations.test.js && node tests/unit/tool_id_schema_drift.test.js && node tests/unit/api_coverage_baseline.test.js && node tests/unit/train_preflight.test.js && node tests/unit/verify_published_artifacts.test.js && node tests/unit/report_train_stale.test.js && node tests/unit/stdio_framing_check.test.js && node tests/unit/server_info.test.js && node tests/unit/transfers_create.test.js && node tests/unit/bot_target_branch.test.js && node tests/unit/auth_posture.test.js && node tests/unit/auth_posture_wiring.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_hold_for_next_month.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/httpServer_session_not_found.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/accounts_delete.test.js && node tests/unit/update_tools_not_found.test.js && node tests/unit/accounts_close.test.js && node tests/unit/accounts_reopen.test.js && node tests/unit/payees_delete.test.js && node tests/unit/payees_merge.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_oidc_jwks_discovery.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpServer_bind_host.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/adapter_drain_listing_cache.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.test.js && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/transactions_update_splits.test.js && node tests/unit/entities_search.test.js && node tests/unit/transactions_import_schema.test.js && node tests/unit/tool_schema_shape.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/stdio_budget_switch.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.test.js && node tests/unit/adapter_op_timeout.test.js && node tests/unit/adapter_write_queue_wakeup.test.js && node tests/unit/ci_workflow_guards.test.js && node tests/unit/node_version_guard.test.js && node tests/unit/node_version_drift.test.js && node tests/unit/observability_smoke.test.js && node tests/unit/residue_pattern.test.js && node tests/unit/dual_transport_gate.test.js && node tests/unit/manual_assertions_use_helper.test.js && node tests/unit/server_version_guard.test.js && node tests/unit/payee_rules_reference_filter.test.js && node tests/unit/oidc_metadata_discovery.test.js && node tests/unit/httpServer_oauth_metadata_route.test.js && node tests/unit/httpServer_mcp_info_route.test.js && node tests/unit/residue_sweep_balance_account.test.js && node tests/unit/tool_factory.test.js && node tests/unit/budget_registry_parse.test.js && node tests/unit/preferences_get.test.js && node tests/unit/budgets_export.test.js && node tests/unit/budgets_import.test.js && node tests/unit/budgets_import_syncid.test.js && node tests/unit/budget_acl_dynamic.test.js && node tests/unit/budget_acl_identity_map.test.js && node tests/unit/budget_acl_userinfo.test.js && node tests/unit/acl_e2e_fixture_contract.test.js && node tests/unit/budget_acl_middleware.test.js && node tests/unit/rules_stage.test.js",
     "test:adapter": "npm run build && node dist/src/tests_adapter_runner.js",
     "test:e2e": "npx playwright test",
     "test:e2e:docker": "./tests/e2e/run-docker-e2e.sh",