@drawbridge/drawbridge-utils 0.0.79 → 0.0.81

package/dist/ai.cjs

@@ -1,6 +1,8 @@
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -14,6 +16,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // lib/ai.js
@@ -91,9 +101,6 @@ var insertTransaction = async ({
   session,
   ...rest
 }) => {
-  var _a;
-  const beforeRaw = (_a = user == null ? void 0 : user.balance) == null ? void 0 : _a[type];
-  const balance = typeof beforeRaw === "number" ? { before: beforeRaw, after: beforeRaw + amount } : void 0;
   const trace = (0, import_drawbridge_telemetry.currentTraceId)();
   await db.create({
     authenticated: user,
@@ -105,7 +112,6 @@ var insertTransaction = async ({
       category,
       source,
       amount,
-      ...balance && { balance },
       ...trace && { trace },
       ...rest,
       ...stripeInvoiceId && { stripeInvoiceId },
@@ -251,6 +257,13 @@ var ai = {
   bill: ({ db, user, model, usage, tools }) => (user == null ? void 0 : user.id) ? () => billRequest({ db, user, model, usage, tools }) : () => Promise.resolve()
 };
 
+// lib/fetch.js
+var import_qs = __toESM(require("qs"), 1);
+var isTransientError = (error) => {
+  const status = error == null ? void 0 : error.status;
+  return !status || status === 429 || status >= 500;
+};
+
 // lib/ai.js
 var google_client = new import_genai.GoogleGenAI({
   apiKey: process.env.GOOGLE_GEMINI_API_KEY
@@ -260,6 +273,16 @@ var googleCircuit = circuit({
   threshold: 3,
   timeout: 6e4
 });
+var withRetries = async (fn, { attempts = 3, delay = 500 } = {}) => {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (attempt >= attempts || !isTransientError(error)) throw error;
+      await new Promise((resolve) => setTimeout(resolve, delay * attempt));
+    }
+  }
+};
 var models = {
   image: "gemini-2.5-flash-image",
   text: "gemini-3.5-flash"
@@ -293,14 +316,14 @@ var google = {
       ...refs.map((ref) => ({ inlineData: { data: ref.data, mimeType: ref.mimeType } })),
       { text: prompt.join("\n") }
     ];
-    const response = await googleCircuit(() => google_client.models.generateContent({
+    const response = await googleCircuit(() => withRetries(() => google_client.models.generateContent({
       model,
       contents: { parts },
       config: {
         ...config,
         responseModalities: ["Image"]
       }
-    }));
+    })));
     const content = (_f = (_e = (_d = (_c = (_b = (_a = response == null ? void 0 : response.candidates) == null ? void 0 : _a[0]) == null ? void 0 : _b.content) == null ? void 0 : _c.parts) == null ? void 0 : _d[0]) == null ? void 0 : _e.inlineData) == null ? void 0 : _f.data;
     if (!content) {
       throw new Error("Could not generate from prompt. Please try again with a different prompt.");
@@ -321,14 +344,14 @@ var google = {
   }) => {
     const model = models.text;
     const contents = parts ? { parts } : images.length ? { parts: [...images.map((image) => ({ inlineData: { data: image.data, mimeType: image.mimeType } })), { text: prompt.join("\n") }] } : prompt.join("\n");
-    const response = await googleCircuit(() => google_client.models.generateContent({
+    const response = await googleCircuit(() => withRetries(() => google_client.models.generateContent({
       config: {
         ...config,
         responseModalities: ["Text"]
       },
       contents,
       model
-    }));
+    })));
     const content = response == null ? void 0 : response.text;
     if (!content) {
       throw new Error("Could not generate from prompt. Please try again with a different prompt.");

package/dist/ai.d.cts

@@ -2,9 +2,11 @@ import { GoogleGenAI } from '@google/genai';
 import { circuit } from './circuit.cjs';
 import { ai } from './billing.cjs';
 export { MARKUP } from './billing.cjs';
+import { isTransientError } from './fetch.cjs';
 import './transactions.cjs';
 import '@drawbridge/drawbridge-telemetry';
 import './usage.cjs';
+import 'qs';
 
 // AI request entry point. Wraps the Google GenAI client with a per-process
 // circuit breaker, owns the per-model pricing table, and atomically debits
@@ -35,6 +37,35 @@ const googleCircuit = circuit({
 	timeout : 60000
 });
 
+// Bounded retry for the raw model call. A single transient failure — undici
+// "fetch failed" on a resource-starved pod, a 429, a 5xx — must not lose the
+// generation step OR count toward the breaker: three of those trip it and
+// hard-fail every AI call for the next 60s. Runs INSIDE the googleCircuit
+// callback so the breaker only counts calls that failed after retries were
+// exhausted, and an OPEN circuit still fails fast without retrying.
+// isTransientError treats status-less errors as transient, which is correct
+// here: the wrapped fn is exactly one SDK call, and the GenAI SDK reports
+// network-level failures as plain Errors with no `.status`.
+const withRetries = async ( fn, { attempts = 3, delay = 500 } = {} ) => {
+
+	for( let attempt = 1; ; attempt++ ){
+
+		try {
+
+			return await fn();
+
+		} catch ( error ) {
+
+			if( attempt >= attempts || ! isTransientError( error ) ) throw error;
+
+			await new Promise( ( resolve ) => setTimeout( resolve, delay * attempt ) );
+
+		}
+
+	}
+
+};
+
 // gemini-2.5-flash was retired by Google (generateContent → 404 "no longer
 // available"), taking down every generation. gemini-3.5-flash is the current
 // stable flash successor. The image model is a distinct model and still live,
@@ -89,14 +120,14 @@ const google = {
 			{ text : prompt.join( '\n' ) }
 		];
 
-		const response = await googleCircuit( () => google_client.models.generateContent({
+		const response = await googleCircuit( () => withRetries( () => google_client.models.generateContent({
 			model,
 			contents : { parts },
 			config : {
 				...config,
 				responseModalities : [ 'Image' ]
 			}
-		}) );
+		}) ) );
 
 		const content = response?.candidates?.[ 0 ]?.content?.parts?.[ 0 ]?.inlineData?.data;
 
@@ -143,14 +174,14 @@ const google = {
 				? { parts : [ ...images.map( ( image ) => ({ inlineData : { data : image.data, mimeType : image.mimeType } }) ), { text : prompt.join( '\n' ) } ] }
 				: prompt.join( '\n' );
 
-		const response = await googleCircuit( () => google_client.models.generateContent({
+		const response = await googleCircuit( () => withRetries( () => google_client.models.generateContent({
 			config : {
 				...config,
 				responseModalities : [ 'Text' ]
 			},
 			contents,
 			model
-		}) );
+		}) ) );
 
 		const content = response?.text;
 

package/dist/ai.d.ts

@@ -2,9 +2,11 @@ import { GoogleGenAI } from '@google/genai';
 import { circuit } from './circuit.js';
 import { ai } from './billing.js';
 export { MARKUP } from './billing.js';
+import { isTransientError } from './fetch.js';
 import './transactions.js';
 import '@drawbridge/drawbridge-telemetry';
 import './usage.js';
+import 'qs';
 
 // AI request entry point. Wraps the Google GenAI client with a per-process
 // circuit breaker, owns the per-model pricing table, and atomically debits
@@ -35,6 +37,35 @@ const googleCircuit = circuit({
 	timeout : 60000
 });
 
+// Bounded retry for the raw model call. A single transient failure — undici
+// "fetch failed" on a resource-starved pod, a 429, a 5xx — must not lose the
+// generation step OR count toward the breaker: three of those trip it and
+// hard-fail every AI call for the next 60s. Runs INSIDE the googleCircuit
+// callback so the breaker only counts calls that failed after retries were
+// exhausted, and an OPEN circuit still fails fast without retrying.
+// isTransientError treats status-less errors as transient, which is correct
+// here: the wrapped fn is exactly one SDK call, and the GenAI SDK reports
+// network-level failures as plain Errors with no `.status`.
+const withRetries = async ( fn, { attempts = 3, delay = 500 } = {} ) => {
+
+	for( let attempt = 1; ; attempt++ ){
+
+		try {
+
+			return await fn();
+
+		} catch ( error ) {
+
+			if( attempt >= attempts || ! isTransientError( error ) ) throw error;
+
+			await new Promise( ( resolve ) => setTimeout( resolve, delay * attempt ) );
+
+		}
+
+	}
+
+};
+
 // gemini-2.5-flash was retired by Google (generateContent → 404 "no longer
 // available"), taking down every generation. gemini-3.5-flash is the current
 // stable flash successor. The image model is a distinct model and still live,
@@ -89,14 +120,14 @@ const google = {
 			{ text : prompt.join( '\n' ) }
 		];
 
-		const response = await googleCircuit( () => google_client.models.generateContent({
+		const response = await googleCircuit( () => withRetries( () => google_client.models.generateContent({
 			model,
 			contents : { parts },
 			config : {
 				...config,
 				responseModalities : [ 'Image' ]
 			}
-		}) );
+		}) ) );
 
 		const content = response?.candidates?.[ 0 ]?.content?.parts?.[ 0 ]?.inlineData?.data;
 
@@ -143,14 +174,14 @@ const google = {
 				? { parts : [ ...images.map( ( image ) => ({ inlineData : { data : image.data, mimeType : image.mimeType } }) ), { text : prompt.join( '\n' ) } ] }
 				: prompt.join( '\n' );
 
-		const response = await googleCircuit( () => google_client.models.generateContent({
+		const response = await googleCircuit( () => withRetries( () => google_client.models.generateContent({
 			config : {
 				...config,
 				responseModalities : [ 'Text' ]
 			},
 			contents,
 			model
-		}) );
+		}) ) );
 
 		const content = response?.text;
 

package/dist/ai.js

@@ -67,9 +67,6 @@ var insertTransaction = async ({
   session,
   ...rest
 }) => {
-  var _a;
-  const beforeRaw = (_a = user == null ? void 0 : user.balance) == null ? void 0 : _a[type];
-  const balance = typeof beforeRaw === "number" ? { before: beforeRaw, after: beforeRaw + amount } : void 0;
   const trace = currentTraceId();
   await db.create({
     authenticated: user,
@@ -81,7 +78,6 @@ var insertTransaction = async ({
       category,
       source,
       amount,
-      ...balance && { balance },
       ...trace && { trace },
       ...rest,
       ...stripeInvoiceId && { stripeInvoiceId },
@@ -227,6 +223,13 @@ var ai = {
   bill: ({ db, user, model, usage, tools }) => (user == null ? void 0 : user.id) ? () => billRequest({ db, user, model, usage, tools }) : () => Promise.resolve()
 };
 
+// lib/fetch.js
+import qs from "qs";
+var isTransientError = (error) => {
+  const status = error == null ? void 0 : error.status;
+  return !status || status === 429 || status >= 500;
+};
+
 // lib/ai.js
 var google_client = new GoogleGenAI({
   apiKey: process.env.GOOGLE_GEMINI_API_KEY
@@ -236,6 +239,16 @@ var googleCircuit = circuit({
   threshold: 3,
   timeout: 6e4
 });
+var withRetries = async (fn, { attempts = 3, delay = 500 } = {}) => {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (attempt >= attempts || !isTransientError(error)) throw error;
+      await new Promise((resolve) => setTimeout(resolve, delay * attempt));
+    }
+  }
+};
 var models = {
   image: "gemini-2.5-flash-image",
   text: "gemini-3.5-flash"
@@ -269,14 +282,14 @@ var google = {
       ...refs.map((ref) => ({ inlineData: { data: ref.data, mimeType: ref.mimeType } })),
       { text: prompt.join("\n") }
     ];
-    const response = await googleCircuit(() => google_client.models.generateContent({
+    const response = await googleCircuit(() => withRetries(() => google_client.models.generateContent({
       model,
       contents: { parts },
       config: {
         ...config,
         responseModalities: ["Image"]
       }
-    }));
+    })));
     const content = (_f = (_e = (_d = (_c = (_b = (_a = response == null ? void 0 : response.candidates) == null ? void 0 : _a[0]) == null ? void 0 : _b.content) == null ? void 0 : _c.parts) == null ? void 0 : _d[0]) == null ? void 0 : _e.inlineData) == null ? void 0 : _f.data;
     if (!content) {
       throw new Error("Could not generate from prompt. Please try again with a different prompt.");
@@ -297,14 +310,14 @@ var google = {
   }) => {
     const model = models.text;
     const contents = parts ? { parts } : images.length ? { parts: [...images.map((image) => ({ inlineData: { data: image.data, mimeType: image.mimeType } })), { text: prompt.join("\n") }] } : prompt.join("\n");
-    const response = await googleCircuit(() => google_client.models.generateContent({
+    const response = await googleCircuit(() => withRetries(() => google_client.models.generateContent({
       config: {
         ...config,
         responseModalities: ["Text"]
       },
       contents,
       model
-    }));
+    })));
     const content = response == null ? void 0 : response.text;
     if (!content) {
       throw new Error("Could not generate from prompt. Please try again with a different prompt.");

package/dist/billing.cjs

@@ -22,6 +22,7 @@ __export(billing_exports, {
   MARKUP: () => MARKUP,
   action: () => action,
   ai: () => ai,
+  balance: () => balance,
   grant: () => grant,
   scrape: () => scrape
 });
@@ -42,9 +43,6 @@ var insertTransaction = async ({
   session,
   ...rest
 }) => {
-  var _a;
-  const beforeRaw = (_a = user == null ? void 0 : user.balance) == null ? void 0 : _a[type];
-  const balance = typeof beforeRaw === "number" ? { before: beforeRaw, after: beforeRaw + amount } : void 0;
   const trace = (0, import_drawbridge_telemetry.currentTraceId)();
   await db.create({
     authenticated: user,
@@ -56,7 +54,6 @@ var insertTransaction = async ({
       category,
       source,
       amount,
-      ...balance && { balance },
       ...trace && { trace },
       ...rest,
       ...stripeInvoiceId && { stripeInvoiceId },
@@ -341,6 +338,28 @@ var scrape = {
     }
   }
 };
+var balance = async ({ db, user, type }) => {
+  const userId = user && user.id || user;
+  if (!db || !userId || !type) return 0;
+  const [checkpoint] = await db.aggregate({
+    collection: "balanceCheckpoint",
+    pipeline: [
+      { $match: { user: userId, type } },
+      { $sort: { _id: -1 } },
+      { $limit: 1 }
+    ]
+  }).catch(() => []);
+  const match = { user: userId, type };
+  if (checkpoint == null ? void 0 : checkpoint.throughId) match._id = { $gt: checkpoint.throughId };
+  const [summed] = await db.aggregate({
+    collection: "transaction",
+    pipeline: [
+      { $match: match },
+      { $group: { _id: null, total: { $sum: "$amount" } } }
+    ]
+  });
+  return ((checkpoint == null ? void 0 : checkpoint.value) || 0) + ((summed == null ? void 0 : summed.total) || 0);
+};
 var grant = {
   // System-issued credit (signup welcome, migration catch-up). Pass `session`
   // to enroll the credit in the caller's transaction.
@@ -471,6 +490,7 @@ var action = {
   MARKUP,
   action,
   ai,
+  balance,
   grant,
   scrape
 });

package/dist/billing.d.cts

@@ -318,10 +318,58 @@ const scrape = {
 
 };
 
+// ─── Balance (derived from the ledger) ──────────────────────────────────────────
+
+// The AI credit balance is DERIVED, never stored — so it cannot drift from the
+// ledger. balance = the newest checkpoint's cumulative value + Σ amount of the
+// rows after it (credits +, debits −); with no checkpoint it sums the whole
+// ledger. Checkpoints (`balanceCheckpoint`) are immutable rollup rows written by
+// drawbridge-sync's nightly job to bound the scan on long-lived accounts — this
+// reader tolerates their absence and falls back to the full sum. The
+// { user:1, type:1, _id:1, amount:1 } index on `transaction` keeps both the full
+// and post-checkpoint sums index-only.
+//
+// `user` accepts an id string or a user object (uses `.id`). `db` is any
+// @drawbridge/mongodb controller (uses `.aggregate`). Returns integer cents;
+// MAY be negative when a generation over-spent past zero — callers clamp the
+// DISPLAY to 0, while the credit gate treats `<= 0` as "no credits".
+const balance = async ({ db, user, type }) => {
+
+	const userId = ( user && user.id ) || user;
+
+	if( ! db || ! userId || ! type ) return 0;
+
+	// Newest immutable checkpoint: its `value` is the cumulative balance through
+	// `throughId`, so we only sum rows inserted after it. Missing collection / no
+	// checkpoint yet → [] and we sum the whole ledger.
+	const [ checkpoint ] = await db.aggregate({
+		collection : 'balanceCheckpoint',
+		pipeline : [
+			{ $match : { user : userId, type } },
+			{ $sort : { _id : -1 } },
+			{ $limit : 1 }
+		]
+	}).catch( () => [] );
+
+	const match = { user : userId, type };
+	if( checkpoint?.throughId ) match._id = { $gt : checkpoint.throughId };
+
+	const [ summed ] = await db.aggregate({
+		collection : 'transaction',
+		pipeline : [
+			{ $match : match },
+			{ $group : { _id : null, total : { $sum : '$amount' } } }
+		]
+	});
+
+	return ( checkpoint?.value || 0 ) + ( summed?.total || 0 );
+
+};
+
 // ─── Grants (credit rail) ──────────────────────────────────────────────────────
 
-// Promotional credits to a user's AI balance. `source` captures who acted; the
-// stream listener on the transaction collection does the balance.ai $inc.
+// Promotional credits to a user's AI balance — append-only rows the derived
+// `balance` sums. `source` captures who acted.
 const grant = {
 
 	// System-issued credit (signup welcome, migration catch-up). Pass `session`
@@ -497,4 +545,4 @@ const action = {
 
 };
 
-export { MARKUP, action, ai, grant, scrape };
+export { MARKUP, action, ai, balance, grant, scrape };

package/dist/billing.d.ts

@@ -318,10 +318,58 @@ const scrape = {
 
 };
 
+// ─── Balance (derived from the ledger) ──────────────────────────────────────────
+
+// The AI credit balance is DERIVED, never stored — so it cannot drift from the
+// ledger. balance = the newest checkpoint's cumulative value + Σ amount of the
+// rows after it (credits +, debits −); with no checkpoint it sums the whole
+// ledger. Checkpoints (`balanceCheckpoint`) are immutable rollup rows written by
+// drawbridge-sync's nightly job to bound the scan on long-lived accounts — this
+// reader tolerates their absence and falls back to the full sum. The
+// { user:1, type:1, _id:1, amount:1 } index on `transaction` keeps both the full
+// and post-checkpoint sums index-only.
+//
+// `user` accepts an id string or a user object (uses `.id`). `db` is any
+// @drawbridge/mongodb controller (uses `.aggregate`). Returns integer cents;
+// MAY be negative when a generation over-spent past zero — callers clamp the
+// DISPLAY to 0, while the credit gate treats `<= 0` as "no credits".
+const balance = async ({ db, user, type }) => {
+
+	const userId = ( user && user.id ) || user;
+
+	if( ! db || ! userId || ! type ) return 0;
+
+	// Newest immutable checkpoint: its `value` is the cumulative balance through
+	// `throughId`, so we only sum rows inserted after it. Missing collection / no
+	// checkpoint yet → [] and we sum the whole ledger.
+	const [ checkpoint ] = await db.aggregate({
+		collection : 'balanceCheckpoint',
+		pipeline : [
+			{ $match : { user : userId, type } },
+			{ $sort : { _id : -1 } },
+			{ $limit : 1 }
+		]
+	}).catch( () => [] );
+
+	const match = { user : userId, type };
+	if( checkpoint?.throughId ) match._id = { $gt : checkpoint.throughId };
+
+	const [ summed ] = await db.aggregate({
+		collection : 'transaction',
+		pipeline : [
+			{ $match : match },
+			{ $group : { _id : null, total : { $sum : '$amount' } } }
+		]
+	});
+
+	return ( checkpoint?.value || 0 ) + ( summed?.total || 0 );
+
+};
+
 // ─── Grants (credit rail) ──────────────────────────────────────────────────────
 
-// Promotional credits to a user's AI balance. `source` captures who acted; the
-// stream listener on the transaction collection does the balance.ai $inc.
+// Promotional credits to a user's AI balance — append-only rows the derived
+// `balance` sums. `source` captures who acted.
 const grant = {
 
 	// System-issued credit (signup welcome, migration catch-up). Pass `session`
@@ -497,4 +545,4 @@ const action = {
 
 };
 
-export { MARKUP, action, ai, grant, scrape };
+export { MARKUP, action, ai, balance, grant, scrape };

package/dist/billing.js

@@ -13,9 +13,6 @@ var insertTransaction = async ({
   session,
   ...rest
 }) => {
-  var _a;
-  const beforeRaw = (_a = user == null ? void 0 : user.balance) == null ? void 0 : _a[type];
-  const balance = typeof beforeRaw === "number" ? { before: beforeRaw, after: beforeRaw + amount } : void 0;
   const trace = currentTraceId();
   await db.create({
     authenticated: user,
@@ -27,7 +24,6 @@ var insertTransaction = async ({
       category,
       source,
       amount,
-      ...balance && { balance },
       ...trace && { trace },
       ...rest,
       ...stripeInvoiceId && { stripeInvoiceId },
@@ -312,6 +308,28 @@ var scrape = {
     }
   }
 };
+var balance = async ({ db, user, type }) => {
+  const userId = user && user.id || user;
+  if (!db || !userId || !type) return 0;
+  const [checkpoint] = await db.aggregate({
+    collection: "balanceCheckpoint",
+    pipeline: [
+      { $match: { user: userId, type } },
+      { $sort: { _id: -1 } },
+      { $limit: 1 }
+    ]
+  }).catch(() => []);
+  const match = { user: userId, type };
+  if (checkpoint == null ? void 0 : checkpoint.throughId) match._id = { $gt: checkpoint.throughId };
+  const [summed] = await db.aggregate({
+    collection: "transaction",
+    pipeline: [
+      { $match: match },
+      { $group: { _id: null, total: { $sum: "$amount" } } }
+    ]
+  });
+  return ((checkpoint == null ? void 0 : checkpoint.value) || 0) + ((summed == null ? void 0 : summed.total) || 0);
+};
 var grant = {
   // System-issued credit (signup welcome, migration catch-up). Pass `session`
   // to enroll the credit in the caller's transaction.
@@ -441,6 +459,7 @@ export {
   MARKUP,
   action,
   ai,
+  balance,
   grant,
   scrape
 };

package/dist/transactions.cjs

@@ -37,9 +37,6 @@ var insertTransaction = async ({
   session,
   ...rest
 }) => {
-  var _a;
-  const beforeRaw = (_a = user == null ? void 0 : user.balance) == null ? void 0 : _a[type];
-  const balance = typeof beforeRaw === "number" ? { before: beforeRaw, after: beforeRaw + amount } : void 0;
   const trace = (0, import_drawbridge_telemetry.currentTraceId)();
   await db.create({
     authenticated: user,
@@ -51,7 +48,6 @@ var insertTransaction = async ({
       category,
       source,
       amount,
-      ...balance && { balance },
       ...trace && { trace },
       ...rest,
       ...stripeInvoiceId && { stripeInvoiceId },

package/dist/transactions.d.cts

@@ -2,12 +2,13 @@ import { currentTraceId } from '@drawbridge/drawbridge-telemetry';
 
 // Ledger transaction insert helpers — no balance writes happen here.
 //
-// User-balance updates are the exclusive job of drawbridge-sync's
-// stream/transaction.js change-stream listener: every insert into the
-// `transaction` collection triggers an atomic $inc on user.balance.<type>
-// (guarded against going negative). This decouples the API surface from
-// the balance arithmetic and makes the `transaction` collection the single
-// source of truth for both audit history and balance derivation.
+// The `transaction` collection is the SINGLE SOURCE OF TRUTH for balance:
+// there is no stored balance field anywhere. The balance is DERIVED by summing
+// a user's rows on read (see `balance` in billing.js) — credits (+) and debits
+// (−) — so it can never drift from the ledger. credit()/debit() only append
+// rows; drawbridge-sync's stream/transaction.js reacts to each insert to fire
+// low/depleted notifications and emit `account.update` (it no longer maintains
+// a balance).
 //
 //   import { credit, debit } from '@drawbridge/drawbridge-utils/transactions';
 //
@@ -21,12 +22,9 @@ import { currentTraceId } from '@drawbridge/drawbridge-telemetry';
 // `db` is the wrapper returned by @drawbridge/mongodb — credit/debit
 // duck-type against its `.create` interface so this module has no hard dep.
 //
-// `user` is the user the transaction is being recorded against. The helper
-// reads `user.balance.<type>` to stamp `balance: { before, after }` on the
-// row as an audit snapshot of what the actor saw at action time — useful
-// for support / dispute resolution. When `balance.<type>` isn't on the user
-// (fresh signup, webhook-initiated row), the snapshot is omitted, which is
-// the honest representation of "no prior view to record".
+// `user` is the user the transaction is being recorded against (stored as
+// `user.id`). No per-row balance snapshot is stamped — the running balance at
+// any row is recoverable by summing the ledger up to it.
 
 const insertTransaction = async ({
 	db,
@@ -42,10 +40,10 @@ const insertTransaction = async ({
 	...rest
 }) => {
 
-	const beforeRaw = user?.balance?.[ type ];
-	const balance = typeof beforeRaw === 'number'
-		? { before : beforeRaw, after : beforeRaw + amount }
-		: undefined;
+	// No balance snapshot is stamped: the balance is DERIVED from this ledger
+	// (billing.balance sums it on read), so the running balance at any row is
+	// recoverable by summing up to that row — a stored before/after would be
+	// redundant and, now that user.balance is gone, has no cheap source anyway.
 
 	// Pull the active Sentry trace ID so every credit/debit auto-correlates
 	// to the originating HTTP request or BullMQ job — useful for grouping
@@ -65,7 +63,6 @@ const insertTransaction = async ({
 			category,
 			source,
 			amount,
-			...( balance && { balance }),
 			...( trace && { trace }),
 			...rest,
 			...( stripeInvoiceId && { stripeInvoiceId }),

package/dist/transactions.d.ts

@@ -2,12 +2,13 @@ import { currentTraceId } from '@drawbridge/drawbridge-telemetry';
 
 // Ledger transaction insert helpers — no balance writes happen here.
 //
-// User-balance updates are the exclusive job of drawbridge-sync's
-// stream/transaction.js change-stream listener: every insert into the
-// `transaction` collection triggers an atomic $inc on user.balance.<type>
-// (guarded against going negative). This decouples the API surface from
-// the balance arithmetic and makes the `transaction` collection the single
-// source of truth for both audit history and balance derivation.
+// The `transaction` collection is the SINGLE SOURCE OF TRUTH for balance:
+// there is no stored balance field anywhere. The balance is DERIVED by summing
+// a user's rows on read (see `balance` in billing.js) — credits (+) and debits
+// (−) — so it can never drift from the ledger. credit()/debit() only append
+// rows; drawbridge-sync's stream/transaction.js reacts to each insert to fire
+// low/depleted notifications and emit `account.update` (it no longer maintains
+// a balance).
 //
 //   import { credit, debit } from '@drawbridge/drawbridge-utils/transactions';
 //
@@ -21,12 +22,9 @@ import { currentTraceId } from '@drawbridge/drawbridge-telemetry';
 // `db` is the wrapper returned by @drawbridge/mongodb — credit/debit
 // duck-type against its `.create` interface so this module has no hard dep.
 //
-// `user` is the user the transaction is being recorded against. The helper
-// reads `user.balance.<type>` to stamp `balance: { before, after }` on the
-// row as an audit snapshot of what the actor saw at action time — useful
-// for support / dispute resolution. When `balance.<type>` isn't on the user
-// (fresh signup, webhook-initiated row), the snapshot is omitted, which is
-// the honest representation of "no prior view to record".
+// `user` is the user the transaction is being recorded against (stored as
+// `user.id`). No per-row balance snapshot is stamped — the running balance at
+// any row is recoverable by summing the ledger up to it.
 
 const insertTransaction = async ({
 	db,
@@ -42,10 +40,10 @@ const insertTransaction = async ({
 	...rest
 }) => {
 
-	const beforeRaw = user?.balance?.[ type ];
-	const balance = typeof beforeRaw === 'number'
-		? { before : beforeRaw, after : beforeRaw + amount }
-		: undefined;
+	// No balance snapshot is stamped: the balance is DERIVED from this ledger
+	// (billing.balance sums it on read), so the running balance at any row is
+	// recoverable by summing up to that row — a stored before/after would be
+	// redundant and, now that user.balance is gone, has no cheap source anyway.
 
 	// Pull the active Sentry trace ID so every credit/debit auto-correlates
 	// to the originating HTTP request or BullMQ job — useful for grouping
@@ -65,7 +63,6 @@ const insertTransaction = async ({
 			category,
 			source,
 			amount,
-			...( balance && { balance }),
 			...( trace && { trace }),
 			...rest,
 			...( stripeInvoiceId && { stripeInvoiceId }),

package/dist/transactions.js

@@ -13,9 +13,6 @@ var insertTransaction = async ({
   session,
   ...rest
 }) => {
-  var _a;
-  const beforeRaw = (_a = user == null ? void 0 : user.balance) == null ? void 0 : _a[type];
-  const balance = typeof beforeRaw === "number" ? { before: beforeRaw, after: beforeRaw + amount } : void 0;
   const trace = currentTraceId();
   await db.create({
     authenticated: user,
@@ -27,7 +24,6 @@ var insertTransaction = async ({
       category,
       source,
       amount,
-      ...balance && { balance },
       ...trace && { trace },
       ...rest,
       ...stripeInvoiceId && { stripeInvoiceId },

package/package.json

@@ -2,7 +2,7 @@
   "type": "module",
   "dependencies": {
     "@drawbridge/drawbridge-agents": "0.0.10",
-    "@drawbridge/drawbridge-telemetry": "0.0.14",
+    "@drawbridge/drawbridge-telemetry": "0.0.15",
     "@google/genai": "1.30.0",
     "axios": "1.16.0",
     "currency-codes": "2.2.0",
@@ -164,5 +164,5 @@
     "test": "node --test test/"
   },
   "types": "dist/index.d.ts",
-  "version": "0.0.79"
+  "version": "0.0.81"
 }