@render-foundation/utils 0.0.248 → 0.0.250

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.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;
+exports.pgClient = exports.batchFinishedAtMedian = exports.foldGrantWindow = exports.GRANT_LOOKBACK_MS = exports.GRANT_LOOKBACK_DAYS = 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");
@@ -76,59 +76,97 @@ exports.EUR_TO_CREDITS = BigInt(4);
 // emissions-funded ones (counting only emissions-attributed spend over-issued ~2.58M credits, 2026-08-04).
 exports.GRANT_WINDOW_START = '2025-05-01';
 exports.CREDIT_DECIMALS = BigInt(100000000); // 1e8
-/**
- * Pure core of the grant allotment: fold a user's OTOY grants against what's already been spent.
- *
- * consumed = attributedSpend (spend already stamped with an otoy_grant_id)
- *          + correctionSettled (jobs whose grant is already being settled by a burn_correction)
- *
- * The correctionSettled term is the DOUBLE-SPEND GUARD: an escrow_credit correction means we're
- * recovering that job's dollars from escrow, so its grant is already committed. Counting it here stops
- * the same grant from also funding a future emissions burn.
- *
- * 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) => {
+// A grant is consumable for this long after issuance; whatever is left after that EXPIRES (2026-08-05
+// model change). A job can only draw grants issued within the lookback window before it ran.
+exports.GRANT_LOOKBACK_DAYS = 60;
+exports.GRANT_LOOKBACK_MS = exports.GRANT_LOOKBACK_DAYS * 24 * 3600 * 1000;
+const foldGrantWindow = (events, opts = {}) => {
+    var _a, _b, _c;
+    const lookback = (_a = opts.lookbackMs) !== null && _a !== void 0 ? _a : exports.GRANT_LOOKBACK_MS;
+    const now = (_b = opts.now) !== null && _b !== void 0 ? _b : Date.now();
     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);
+    const buckets = [];
+    const remaining = (b) => b.amount - b.reversed - b.drawnEmissions - b.drawnMisrouted;
+    let beyond = BigInt(0);
     for (const e of sorted) {
-        run += e.amt;
-        if (run < minRun)
-            minRun = run;
+        if (e.src === 'grant') {
+            if (e.amt > BigInt(0)) {
+                buckets.push({
+                    grantId: e.grantId,
+                    t: e.t,
+                    amount: e.amt,
+                    reversed: BigInt(0),
+                    drawnEmissions: BigInt(0),
+                    drawnMisrouted: BigInt(0),
+                    expired: BigInt(0),
+                    left: BigInt(0),
+                });
+            }
+            else {
+                let claw = -e.amt; // clawback hits remaining capacity oldest-first; excess is dropped
+                for (const b of buckets) {
+                    if (claw <= BigInt(0))
+                        break;
+                    const take = remaining(b) < claw ? remaining(b) : claw;
+                    if (take > BigInt(0)) {
+                        b.reversed += take;
+                        claw -= take;
+                    }
+                }
+            }
+        }
+        else {
+            let need = -e.amt;
+            let emissionsLeft = (_c = e.emissions) !== null && _c !== void 0 ? _c : need; // no split provided -> count it all as emissions
+            for (const b of buckets) {
+                if (need <= BigInt(0))
+                    break;
+                if (b.t + lookback < e.t)
+                    continue; // grant expired before this job ran
+                const take = remaining(b) < need ? remaining(b) : need;
+                if (take <= BigInt(0))
+                    continue;
+                const em = emissionsLeft < take ? emissionsLeft : take;
+                b.drawnEmissions += em;
+                b.drawnMisrouted += take - em;
+                emissionsLeft -= em;
+                need -= take;
+            }
+            beyond += need;
+        }
     }
-    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)) +
-        (correctionSettled > BigInt(0) ? correctionSettled : BigInt(0));
-    const avail = granted > consumed ? granted - consumed : BigInt(0);
-    let drawn = consumed;
+    let avail = BigInt(0);
+    let expired = BigInt(0);
+    let usedEmissions = BigInt(0);
+    let usedMisrouted = BigInt(0);
     let fifoGrantId;
-    for (const g of grants) {
-        if (drawn < g.amountCredits) {
-            fifoGrantId = g.id;
-            break;
+    for (const b of buckets) {
+        usedEmissions += b.drawnEmissions;
+        usedMisrouted += b.drawnMisrouted;
+        const rem = remaining(b);
+        if (b.t + lookback < now) {
+            b.expired = rem;
         }
-        drawn -= g.amountCredits;
+        else {
+            b.left = rem;
+            avail += rem;
+            if (fifoGrantId === undefined && rem > BigInt(0) && b.grantId !== undefined)
+                fifoGrantId = b.grantId;
+        }
+        expired += b.expired;
     }
-    return { granted, consumed, avail, fifoGrantId };
+    return {
+        avail,
+        beyondGrants: beyond,
+        jobCharged: usedEmissions + usedMisrouted,
+        usedEmissions,
+        usedMisrouted,
+        expired,
+        buckets,
+        fifoGrantId,
+    };
 };
-exports.foldGrantAllotment = foldGrantAllotment;
+exports.foldGrantWindow = foldGrantWindow;
 const base_2 = require("./base");
 const moment_1 = __importDefault(require("moment"));
 pg.types.setTypeParser(1114, (str) => moment_1.default.utc(str).toDate());
@@ -256,91 +294,54 @@ 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;
+        var _b, _c;
         const out = {};
         if (!p.userIds.length)
             return out;
-        const grants = yield db
-            .selectFrom(exports.OTOY_GRANT_TABLE)
-            .select(['id', 'user_id', 'amount_credits', 'otoy_created_at'])
-            .where('user_id', 'in', p.userIds)
-            .orderBy('otoy_created_at', 'asc')
-            .orderBy('id', 'asc')
-            .execute();
-        if (!grants.length)
-            return out;
-        // EVERY grant-ledger row retires pool capacity, in either direction:
-        //  - negative delta = an emissions burn. ALL of them count, not just ones stamped with an
-        //    otoy_grant_id. Historical grants are now backfilled to cover the Sep/Oct-2025 burns, so those
-        //    burns must net against them; counting only stamped rows would re-issue ~1.06M credits of
-        //    already-spent grant.
-        //  - positive delta = the grant was CREDITED into current_user_grant_spend (the one-off canary
-        //    route). That balance reaches the split separately, so leaving it in the pool double-issues it.
-        // Hence abs() over the whole ledger.
-        // NOT abs() over the whole ledger — that would charge the Sep/Oct-2025 CSV *credits* as if they
-        // were spend, double-penalising those users (464e8e33: 376,749 burned + 79,304 credited = 456,053).
-        // A positive only retires capacity when it is tied to a pool grant (the canary route, where the
-        // grant was moved into current_user_grant_spend and reaches the split from there).
-        const spent = yield db
-            .selectFrom(exports.USER_GRANT_SPEND_TABLE)
-            .select((eb) => [
-            'user_id',
-            eb.fn
-                .sum((0, kysely_1.sql) `case when render_spent_delta < 0 then -render_spent_delta
-                     when otoy_grant_id is not null then render_spent_delta
-                     else 0 end`)
-                .as('net'),
-        ])
-            .where('user_id', 'in', p.userIds)
-            .groupBy('user_id')
-            .execute();
-        // 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: [] });
-            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}`);
+        // Raw event stream, folded in code (foldGrantWindow — per-grant buckets, 60-day consumable window,
+        // reversals clamp capacity, only jobs create beyond-grants). SQL can't express the bucketed clamp.
+        const evRes = yield (0, kysely_1.sql) `
+      select user_id::text as u, coalesce(otoy_created_at, ${exports.GRANT_WINDOW_START}::timestamp) as t,
+             (amount_credits * 4 * 1e8)::numeric::text as amt, 'grant' as src, id as gid
+        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)::text, 'grant', null
+        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)::text, 'grant', null
+        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)::text, 'job', null
+        from job
+       where user_id = any(${p.userIds}::text[]) and completed_at >= ${exports.GRANT_WINDOW_START}::timestamp
+    `.execute(db); // db is always a Kysely trx at runtime
+        const byUser = new Map();
+        for (const r of evRes.rows) {
+            const arr = (_b = byUser.get(r.u)) !== null && _b !== void 0 ? _b : [];
+            arr.push({
+                t: new Date(r.t).getTime(),
+                amt: BigInt(Math.round(Number(r.amt))),
+                src: r.src,
+                grantId: (_c = r.gid) !== null && _c !== void 0 ? _c : undefined,
+            });
+            byUser.set(r.u, arr);
+        }
+        for (const [u, events] of byUser) {
+            const f = (0, exports.foldGrantWindow)(events);
+            out[u] = {
+                userId: u,
+                granted: events.reduce((a, e) => (e.src === 'grant' && e.amt > BigInt(0) ? a + e.amt : a), BigInt(0)),
+                consumed: f.jobCharged,
+                avail: f.avail,
+                expired: f.expired,
+                fifoGrantId: f.fifoGrantId,
+            };
+            if (f.beyondGrants > BigInt(0)) {
+                log.info(`grant allotment ${u}: ${f.beyondGrants} beyond grants (purchase-paid at the time), ` +
+                    `${f.expired} expired past the ${exports.GRANT_LOOKBACK_DAYS}d window — avail ${f.avail}`);
             }
         }
         return out;
@@ -1209,7 +1210,7 @@ const pgClient = (config) => {
             });
         },
         insertGrantSpend(db, p, log = logger_1.consoleLogger) {
-            var _a, _b, _c;
+            var _a, _b, _c, _d;
             return __awaiter(this, void 0, void 0, function* () {
                 const existing = yield getCurrentUserGrantSpend(db.trx, { userId: p.userId }, log);
                 const diff = {
@@ -1236,16 +1237,13 @@ const pgClient = (config) => {
                             return;
                         }
                     }
-                    // FIFO-attribute this spend to the user's oldest OTOY grant that still has room. Stamping
-                    // otoy_grant_id is what makes getGrantAllotments count it as consumed — an unattributed row
-                    // would leave the grant looking unspent and let it fund a second burn.
+                    // FIFO-attribute this spend to the user's oldest LIVE OTOY grant that still has room (the fold
+                    // already applies the lookback window). Stamping otoy_grant_id is what shows the draw in the
+                    // admin drill-down — an unattributed row would leave the grant looking unspent there.
                     let otoyGrantId = p.otoyGrantId;
                     if (otoyGrantId === undefined && p.renderSpentDelta < BigInt(0)) {
                         const allots = yield getGrantAllotments(db.trx, { userIds: [p.userId] }, log);
-                        const a = allots[p.userId];
-                        if (a) {
-                            otoyGrantId = (0, exports.foldGrantAllotment)(a.grants, a.consumed, BigInt(0)).fifoGrantId;
-                        }
+                        otoyGrantId = (_c = allots[p.userId]) === null || _c === void 0 ? void 0 : _c.fifoGrantId;
                     }
                     const v = {
                         user_id: p.userId,
@@ -1271,7 +1269,7 @@ const pgClient = (config) => {
                     user_id: p.userId,
                     render_spent: p.renderSpentDelta,
                     description: p.description,
-                    perpetual: (_c = p.perpetual) !== null && _c !== void 0 ? _c : false,
+                    perpetual: (_d = p.perpetual) !== null && _d !== void 0 ? _d : false,
                 })
                     .onConflict((oc) => oc.column('user_id').doUpdateSet(diff))
                     .returning((eb) => [