actual-mcp-server 0.16.1 → 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.1 | **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,7 +538,54 @@ 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;
-let drainListingCache = null;
+/**
+ * #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.
  *
@@ -549,6 +597,7 @@ let drainListingCache = null;
  * 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);
@@ -562,7 +611,7 @@ async function readDrainListing(kind, fetch) {
     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)
+        if (drainListingCache.get(kind) === inFlight)
             drainListingCache.delete(kind);
         throw error;
     }
@@ -575,6 +624,7 @@ async function readDrainListing(kind, fetch) {
  * 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)
@@ -636,169 +686,167 @@ async function processWriteQueue() {
     logger.debug(`[WRITE QUEUE] Processing batch of ${batch.length} operations ` +
         `(sessionId=${batchSessionId ?? 'none'}, poolBranch=${usePoolBranch})`);
     try {
-        // #378 (L7): opened INSIDE the try whose `finally` nulls it. Created earlier it would
-        // survive a throw between creation and the try, which is benign today only because
-        // isProcessingWrites would wedge the queue first and make the stuck cache unreachable.
-        // Not worth depending on that accident.
-        drainListingCache = new Map();
-        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
-                // #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 {
-                        const result = await withOpTimeout(operation);
-                        resolve(result);
-                    }
-                    catch (error) {
-                        logger.error('[WRITE QUEUE] Operation failed:', error);
-                        reject(error);
+        // #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})`);
                     }
-                    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);
+                    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 {
-        // #378: the cache dies with the drain, on every path including the fatal one. A drain
-        // that threw partway must not hand a partially-invalidated view to the next drain.
-        drainListingCache = null;
         isProcessingWrites = false;
         // #278: ALWAYS re-drain a non-empty queue. The old `&& writeSessionTimeout === null`
         // guard was the lost wakeup: a timer that fired mid-drain left a dead handle here,
@@ -1200,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(() => { });
@@ -1527,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(() => { });
@@ -1563,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
@@ -1624,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
@@ -1669,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 () => {
@@ -1686,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
@@ -1716,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.
@@ -2008,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.
@@ -2059,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 {
@@ -2574,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(() => { });
@@ -2587,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(() => { });
@@ -2600,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 () => {
@@ -2645,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.1",
+  "version": "0.16.2",
   "engines": {
     "node": ">=22.0.0",
     "npm": ">=10.0.0"