@render-foundation/utils 0.0.246 → 0.0.248

package/lib/cjs/client/pg/v2Client.js

@@ -35,7 +35,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.pgClient = exports.batchFinishedAtMedian = exports.foldGrantAllotment = exports.CREDIT_DECIMALS = exports.GRANT_WINDOW_START = exports.EUR_TO_CREDITS = exports.DISPERSED_BURN_CORRECTION_TABLE = exports.DISPERSED_SETTLEMENT_TABLE = exports.GRANT_BURN_TABLE = exports.GRANT_BURN_ID_TABLE = exports.OTOY_GRANT_TABLE = exports.USER_GRANT_SPEND_TABLE = exports.CURRENT_USER_GRANT_SPEND_TABLE = exports.POLYGON_UPGRADE_TABLE = exports.ENTITY_EPOCH_INFO_TABLE = exports.BURN_CORRECTION_TABLE = exports.NETWORK_REVENUE_TABLE = exports.BRIDGE_TRANSFER_TABLE = exports.BURN_TABLE = exports.JOB_TABLE = exports.JOB_ID_TABLE = exports.LIABILITY_ADJUSTMENT_BATCH_TABLE = exports.LIABILITY_ADJUSTMENT_TABLE = exports.LIABILITY_TABLE = exports.SOL_TRANSFER_TABLE = exports.ENTITY_TABLE = exports.MANUAL_BURN_TABLE = exports.EPOCH_TABLE = exports.SOL_TX_TABLE = void 0;
+exports.pgClient = exports.batchFinishedAtMedian = exports.foldGrantAllotment = exports.foldTimeAware = exports.CREDIT_DECIMALS = exports.GRANT_WINDOW_START = exports.EUR_TO_CREDITS = exports.DISPERSED_BURN_CORRECTION_TABLE = exports.DISPERSED_SETTLEMENT_TABLE = exports.GRANT_BURN_TABLE = exports.GRANT_BURN_ID_TABLE = exports.OTOY_GRANT_TABLE = exports.USER_GRANT_SPEND_TABLE = exports.CURRENT_USER_GRANT_SPEND_TABLE = exports.POLYGON_UPGRADE_TABLE = exports.ENTITY_EPOCH_INFO_TABLE = exports.BURN_CORRECTION_TABLE = exports.NETWORK_REVENUE_TABLE = exports.BRIDGE_TRANSFER_TABLE = exports.BURN_TABLE = exports.JOB_TABLE = exports.JOB_ID_TABLE = exports.LIABILITY_ADJUSTMENT_BATCH_TABLE = exports.LIABILITY_ADJUSTMENT_TABLE = exports.LIABILITY_TABLE = exports.SOL_TRANSFER_TABLE = exports.ENTITY_TABLE = exports.MANUAL_BURN_TABLE = exports.EPOCH_TABLE = exports.SOL_TX_TABLE = void 0;
 const kysely_1 = require("kysely");
 const logger_1 = require("../../logger");
 const pg_1 = require("pg");
@@ -88,6 +88,30 @@ exports.CREDIT_DECIMALS = BigInt(100000000); // 1e8
  *
  * fifoGrantId = the oldest grant still holding room, i.e. the one the next spend draws from.
  */
+/**
+ * Time-aware reservoir fold. Events = grant issuances (+, at issue time) and job spend (−, at job time),
+ * processed chronologically: a job may only draw entitlement that existed WHEN IT RAN. Spend beyond the
+ * balance at that moment is purchase-paid forever — a later grant must not retroactively absorb it
+ * (the aggregate `granted − allSpend` formula did exactly that, under-issuing 256 users / 44,243 credits;
+ * it also let the UI attribute jobs to grants issued days after they ran).
+ *
+ * Identity used everywhere (SQL + client): with net = Σamt and overshoot = max prefix deficit,
+ *   avail = max(net + overshoot, 0);  beyondGrants = overshoot.
+ */
+const foldTimeAware = (events) => {
+    const sorted = [...events].sort((a, b) => a.t - b.t || (a.amt > b.amt ? -1 : 1)); // credits first on ties
+    let run = BigInt(0);
+    let minRun = BigInt(0);
+    for (const e of sorted) {
+        run += e.amt;
+        if (run < minRun)
+            minRun = run;
+    }
+    const overshoot = minRun < BigInt(0) ? -minRun : BigInt(0);
+    const avail = run + overshoot; // ≥ 0 by construction
+    return { avail, beyondGrants: overshoot };
+};
+exports.foldTimeAware = foldTimeAware;
 const foldGrantAllotment = (grants, attributedSpend, correctionSettled) => {
     const granted = grants.reduce((s, g) => s + g.amountCredits, BigInt(0));
     const consumed = (attributedSpend > BigInt(0) ? attributedSpend : BigInt(0)) +
@@ -232,7 +256,7 @@ const pgClient = (config) => {
     // Spendable grant per user, straight off otoy_grant (FIFO), net of what's already been spent or
     // already settled by a burn correction. See GrantAllotment for the units + the double-spend guard.
     const getGrantAllotments = (db, p, log = logger_1.consoleLogger) => __awaiter(void 0, void 0, void 0, function* () {
-        var _b, _c, _d, _e;
+        var _b;
         const out = {};
         if (!p.userIds.length)
             return out;
@@ -270,70 +294,53 @@ const pgClient = (config) => {
             .where('user_id', 'in', p.userIds)
             .groupBy('user_id')
             .execute();
-        // ALL in-window job spend — the true deduction ledger. Every render job flows through us, and every
-        // job consumed the user's OTOY credits regardless of HOW we funded the burn (emissions or USDC
-        // buy-and-burn). This supersedes the old correction-settled term (those jobs are in-window) and
-        // closes the pre-go-live gap where buy-and-burn jobs didn't decrement grants.
-        const jobspend = yield db
-            .selectFrom(`${exports.JOB_TABLE} as j`)
-            .select((eb) => ['j.user_id as user_id', eb.fn.sum('j.render_amt').as('amt')])
-            .where('j.user_id', 'in', p.userIds)
-            .where('j.completed_at', '>=', new Date(exports.GRANT_WINDOW_START))
-            .groupBy('j.user_id')
-            .execute();
-        // legacy CSV CREDITED (pre-cutoff OTOY grants redeemed against in-window jobs): the FULL credited
-        // amount offsets job spend — those jobs were paid by pre-cutoff grants per OTOY's own redemption
-        // report. Using the floored remaining BALANCE here under-grants users whose emissions burns exceeded
-        // their credited amount (f5adcc66: balance 0 but credited 50,213 -> avail 6,390 vs correct 56,603).
-        const legacy = yield db
-            .selectFrom(exports.USER_GRANT_SPEND_TABLE)
-            .select((eb) => ['user_id', eb.fn.sum('render_spent_delta').as('v')])
-            .where('user_id', 'in', p.userIds)
-            .where('render_spent_delta', '>', '0')
-            .where('otoy_grant_id', 'is', null)
-            .groupBy('user_id')
-            .execute();
-        const spentBy = new Map(spent.map((r) => { var _a; return [r.user_id, BigInt((_a = r.net) !== null && _a !== void 0 ? _a : 0)]; }));
-        const jobBy = new Map(jobspend.map((r) => { var _a; return [r.user_id, BigInt((_a = r.amt) !== null && _a !== void 0 ? _a : 0)]; }));
-        // clamp: legacy exists ONLY to offset the jobs it was minted from — it can never exceed the user's
-        // in-window job spend, so it can never fund forward (closes the 32-user CSV snapshot edge).
-        const legByRaw = new Map(legacy.map((r) => { var _a; return [r.user_id, BigInt((_a = r.v) !== null && _a !== void 0 ? _a : 0)]; }));
-        const legBy = new Map([...legByRaw].map(([u, v]) => {
-            var _a;
-            const js = (_a = jobBy.get(u)) !== null && _a !== void 0 ? _a : BigInt(0);
-            return [u, v < js ? v : js];
-        }));
-        for (const g of grants) {
-            const u = g.user_id;
+        // Time-aware fold (see foldTimeAware): one pass over the user's event stream — grant issuances
+        // (+, at issue time; the legacy CSV credit at window start; pool-stamped credits as capacity moved
+        // out at their created_at) and job spend (−, at completion). A job can only draw entitlement that
+        // existed when it ran; overshoot is purchase-paid forever.
+        const fold = yield (0, kysely_1.sql) `
+      with ev as (
+        select user_id::text as u, coalesce(otoy_created_at, ${exports.GRANT_WINDOW_START}::timestamp) as t,
+               (amount_credits * 4 * 1e8)::numeric as amt
+          from otoy_grant where user_id = any(${p.userIds}::uuid[])
+        union all
+        select user_id::text, ${exports.GRANT_WINDOW_START}::timestamp, sum(render_spent_delta)::numeric
+          from user_grant_spend
+         where user_id = any(${p.userIds}::uuid[]) and render_spent_delta > 0 and otoy_grant_id is null
+         group by user_id
+        union all
+        select user_id::text, created_at, -render_spent_delta::numeric
+          from user_grant_spend
+         where user_id = any(${p.userIds}::uuid[]) and render_spent_delta > 0 and otoy_grant_id is not null
+        union all
+        select user_id, completed_at, -render_amt::numeric
+          from job
+         where user_id = any(${p.userIds}::text[]) and completed_at >= ${exports.GRANT_WINDOW_START}::timestamp
+      ),
+      r as (
+        select u, amt,
+               sum(amt) over (partition by u order by t asc, amt desc rows unbounded preceding) as run
+          from ev
+      )
+      select u as user_id,
+             sum(case when amt > 0 then amt else 0 end)::text as granted_total,
+             sum(amt)::text as net,
+             greatest(-min(run), 0)::text as overshoot
+        from r group by u
+    `.execute(db); // db is always a Kysely trx at runtime; QueryCreator's type just lacks getExecutor
+        const toB = (v) => BigInt(Math.round(Number(v !== null && v !== void 0 ? v : 0)));
+        for (const r of fold.rows) {
+            const u = r.user_id;
             const cur = (_b = out[u]) !== null && _b !== void 0 ? _b : (out[u] = { userId: u, granted: BigInt(0), consumed: BigInt(0), avail: BigInt(0), grants: [] });
-            // amount_credits is numeric EUR — truncate to whole base units after the x4 conversion
-            const credits = (BigInt(Math.round(Number(g.amount_credits) * 1e8)) * exports.EUR_TO_CREDITS);
-            cur.granted += credits;
-            cur.grants.push({
-                id: Number(g.id),
-                amountCredits: credits,
-                createdAt: g.otoy_created_at ? new Date(g.otoy_created_at) : null,
-            });
-        }
-        // legacy-only users (no mirrored grant) still get an entry — their CSV balance is a granted source
-        for (const [u, v] of legBy) {
-            if (v > BigInt(0) && !out[u])
-                out[u] = { userId: u, granted: BigInt(0), consumed: BigInt(0), avail: BigInt(0), grants: [] };
-        }
-        for (const u of Object.keys(out)) {
-            const attributed = (_c = spentBy.get(u)) !== null && _c !== void 0 ? _c : BigInt(0); // ledger-counted (burns + pool-tied credits)
-            const spend = (_d = jobBy.get(u)) !== null && _d !== void 0 ? _d : BigInt(0); // ALL in-window job spend
-            const leg = (_e = legBy.get(u)) !== null && _e !== void 0 ? _e : BigInt(0);
-            // consumed = the larger of the two accountings — the ledger can exceed job spend (pool-tied
-            // credits retiring capacity), job spend can exceed the ledger (pre-go-live buy-and-burn jobs).
-            const consumed = attributed > spend ? attributed : spend;
-            const f = (0, exports.foldGrantAllotment)(out[u].grants, consumed, BigInt(0));
-            out[u].granted = f.granted + leg;
-            out[u].consumed = consumed;
-            out[u].avail =
-                f.granted + leg > consumed ? f.granted + leg - consumed : BigInt(0);
-            if (spend > attributed) {
-                log.info(`grant allotment ${u}: in-window job spend ${spend} > ledger-counted ${attributed} — strict consumption applied (granted ${f.granted} + legacy ${leg} => avail ${out[u].avail})`);
+            const granted = toB(r.granted_total);
+            const net = toB(r.net);
+            const overshoot = toB(r.overshoot);
+            const avail = net + overshoot > BigInt(0) ? net + overshoot : BigInt(0);
+            cur.granted = granted;
+            cur.consumed = granted - avail; // grant capacity actually charged
+            cur.avail = avail;
+            if (overshoot > BigInt(0)) {
+                log.info(`grant allotment ${u}: time-aware fold — overshoot ${overshoot} is purchase-paid; granted ${granted} => avail ${avail}`);
             }
         }
         return out;
@@ -2009,7 +2016,7 @@ const pgClient = (config) => {
                 // took the room), the whole txn rolls back and we return {inserted:false} — the caller must NOT
                 // broadcast (no row, no counter change, no burn).
                 return yield db.transaction().execute((trx) => __awaiter(this, void 0, void 0, function* () {
-                    var _a, _b, _c, _d, _e, _f, _g;
+                    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
                     const res = yield trx
                         .insertInto(exports.DISPERSED_SETTLEMENT_TABLE)
                         .values({
@@ -2024,10 +2031,12 @@ const pgClient = (config) => {
                         usdc_spent: (_c = p.usdcSpent) !== null && _c !== void 0 ? _c : null,
                         correction_id: (_d = p.correctionId) !== null && _d !== void 0 ? _d : null,
                         correction_render: (_e = p.correctionRender) !== null && _e !== void 0 ? _e : null,
+                        usage_from: (_f = p.usageFrom) !== null && _f !== void 0 ? _f : null,
+                        usage_to: (_g = p.usageTo) !== null && _g !== void 0 ? _g : null,
                     })
                         .onConflict((oc) => oc.column('tx_signature').doNothing())
                         .executeTakeFirst();
-                    const inserted = ((_f = res.numInsertedOrUpdatedRows) !== null && _f !== void 0 ? _f : BigInt(0)) > BigInt(0);
+                    const inserted = ((_h = res.numInsertedOrUpdatedRows) !== null && _h !== void 0 ? _h : BigInt(0)) > BigInt(0);
                     // Only reserve when the row was actually inserted (a tx_signature conflict is a no-op → no double
                     // count) and it drew a correction.
                     if (inserted &&
@@ -2042,7 +2051,7 @@ const pgClient = (config) => {
                             .where('id', '=', String(p.correctionId))
                             .where((eb) => eb((0, kysely_1.sql) `consumed_render + ${p.correctionRender}::numeric`, '<=', eb.ref('amount_render')))
                             .executeTakeFirst();
-                        if (((_g = upd.numUpdatedRows) !== null && _g !== void 0 ? _g : BigInt(0)) === BigInt(0)) {
+                        if (((_j = upd.numUpdatedRows) !== null && _j !== void 0 ? _j : BigInt(0)) === BigInt(0)) {
                             // Would exceed amount_render (concurrent draw won the room) — roll back the whole txn.
                             log.warn(`dispersed correction ${p.correctionId}: draw ${p.correctionRender} would over-consume; rejecting outbox insert for tx ${p.txSignature}`);
                             throw new DispersedCorrectionRejected();