@drawbridge/drawbridge-utils 0.0.80 → 0.0.81

package/dist/ai.cjs

@@ -101,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,
@@ -115,7 +112,6 @@ var insertTransaction = async ({
       category,
       source,
       amount,
-      ...balance && { balance },
       ...trace && { trace },
       ...rest,
       ...stripeInvoiceId && { stripeInvoiceId },

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 },

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

@@ -164,5 +164,5 @@
     "test": "node --test test/"
   },
   "types": "dist/index.d.ts",
-  "version": "0.0.80"
+  "version": "0.0.81"
 }