@ixo/decision-oracle 0.0.0-stage → 0.2.0

package/dist/cron/funding.js

@@ -0,0 +1,262 @@
+/**
+ * Un-pausing after the chain's "insufficient funds: payment withdrawal failed" (lib/ixo/
+ * chain-write.ts): the collection's admin account could not pay what the message draws, so the
+ * act lane parked the decision `blocked` and paused the collection `admin-unfunded`. The fix is
+ * the OWNER's (top up the admin account — the paused notice names it and the amount), so this
+ * tick reads that account's spendable balance and, once it covers the largest single parked
+ * delivery per denom (`largestParkedDraw`: the evaluation leg PLUS that verdict's payment — chain
+ * v8 fails an approve whole unless the admin covers both, so the evaluation fee alone would
+ * resume, re-fail and re-pause in a loop), resumes the collection and RE-DELIVERS every decision
+ * parked behind the empty account — the ones that exhausted the act step's retries as `pending`
+ * too. Never resumes an operator's pause (`pausedReason: null`) or a reason that isn't ours to
+ * clear. The twin of `billing.ts`.
+ */
+import { and, asc, eq, inArray } from "drizzle-orm";
+import { loadConfig } from "../config.js";
+import { decisions, watchedCollections } from "../db/schema.js";
+import { getClaimById, getCollection } from "../lib/ixo/blocksync/index.js";
+import { getSpendableBalance } from "../lib/ixo/chain.js";
+import { deliverChainEvaluation } from "../lib/ixo/chain-write.js";
+import { adminDraw, claimPayment, evaluationAmount } from "../lib/ixo/payment.js";
+import { reportError } from "../lib/sentry.js";
+import { notifyCollectionResumed } from "../workflows/steps.js";
+/** Parked decisions re-delivered per resumed collection per tick — the rest wait for the next. */
+const REDELIVER_LIMIT = 20;
+/**
+ * Paused collections probed per tick, and how many balances are read at once. This runs BEFORE the
+ * scan (a resumed collection is scanned the same tick), so it must stay short: the probe used to
+ * walk every unfunded row, one Blocksync read plus one RPC query each, in series. The rest are
+ * probed next minute.
+ */
+const ADMIN_FUNDS_PER_TICK = 20;
+const PROBE_CONCURRENCY = 5;
+export async function resumeAdminFunds(ctx) {
+    const { db, logger } = ctx;
+    const paused = await db
+        .select({
+        collectionId: watchedCollections.collectionId,
+        denom: watchedCollections.evaluationDenom,
+        amount: watchedCollections.evaluationAmount,
+    })
+        .from(watchedCollections)
+        .where(and(eq(watchedCollections.status, "paused"), eq(watchedCollections.pausedReason, "admin-unfunded")))
+        // Least recently probed first: a probe that does not resume a row moves it to the back (below),
+        // so twenty accounts that stay empty can never starve the twenty-first.
+        .orderBy(asc(watchedCollections.updatedAt))
+        .limit(ADMIN_FUNDS_PER_TICK);
+    if (paused.length === 0)
+        return 0;
+    // `ctx.deps.config` is `BlocksyncDeps`' narrow slice (cron/collection.ts) — the chain read, the
+    // act lane and the notice need the full `Config`, reloaded from `ctx.env` (billing.ts does the same).
+    const config = loadConfig(ctx.env);
+    // Phase 1 — the balance reads, a few at a time (each is a Blocksync read + an RPC query); a row
+    // that cannot be judged, or is not funded yet, falls out here and never reaches the writes.
+    const fundable = [];
+    for (let i = 0; i < paused.length; i += PROBE_CONCURRENCY) {
+        const probed = await Promise.all(paused.slice(i, i + PROBE_CONCURRENCY).map(async ({ collectionId, denom, amount }) => {
+            // Every registered row carries both (the register gate refuses a collection without
+            // them); a row that doesn't cannot be judged here — say so, leave it to the operator. An
+            // amount that is not a base-unit integer (recorded before payment.ts refused one) would
+            // throw in the `BigInt` below and abort every other probe: the same "cannot be judged".
+            if (!denom || !amount || !/^\d+$/.test(amount)) {
+                logger.warn("cron.admin-funds.no-fee", { collectionId });
+                return null;
+            }
+            const fee = { denom, amount };
+            let admin;
+            let need;
+            let short;
+            try {
+                const collection = await getCollection(ctx.deps, collectionId);
+                admin = collection?.admin;
+                if (!admin)
+                    throw new Error("no resolvable admin");
+                const funds = balanceReader(config, admin);
+                // The evaluation leg first: an account that cannot pay even that stays paused without
+                // reading a single parked claim (the common case, every tick, for every empty account).
+                need = adminDraw({ payments: collection?.payments, fee });
+                short = await shortOf(funds, need);
+                if (!short) {
+                    need = await largestParkedDraw(ctx, collectionId, collection?.payments, fee);
+                    short = await shortOf(funds, need);
+                }
+            }
+            catch (err) {
+                // Unreadable is not "funded": stay paused, say so at warn.
+                logger.warn("cron.admin-funds.unreadable", { collectionId, detail: String(err) });
+                return null;
+            }
+            if (short) {
+                logger.debug("cron.admin-funds.still-paused", {
+                    collectionId,
+                    admin,
+                    short: `${short.amount}${short.denom}`,
+                    required: need.map((coin) => `${coin.amount}${coin.denom}`).join("+"),
+                });
+                return null;
+            }
+            return { collectionId, admin, need };
+        }));
+        for (const hit of probed)
+            if (hit)
+                fundable.push(hit);
+    }
+    // Every row this tick could not resume goes to the back of the line — one statement; the reason
+    // is re-checked so a row someone resumed or re-paused meanwhile is left as it is.
+    const funded = new Set(fundable.map((f) => f.collectionId));
+    const missed = paused.map((p) => p.collectionId).filter((id) => !funded.has(id));
+    if (missed.length > 0) {
+        await db
+            .update(watchedCollections)
+            .set({ updatedAt: new Date() })
+            .where(and(inArray(watchedCollections.collectionId, missed), eq(watchedCollections.status, "paused"), eq(watchedCollections.pausedReason, "admin-unfunded")));
+    }
+    // Phase 2 — the resumes, in series: each re-delivers through the ONE chain signer, whose
+    // sequence is serial anyway.
+    let resumed = 0;
+    for (const { collectionId, admin, need } of fundable) {
+        // The WHERE re-checks the reason: an operator who paused it meanwhile keeps their pause.
+        const rows = await db
+            .update(watchedCollections)
+            .set({ status: "active", pausedReason: null })
+            .where(and(eq(watchedCollections.collectionId, collectionId), eq(watchedCollections.status, "paused"), eq(watchedCollections.pausedReason, "admin-unfunded")))
+            .returning({ collectionId: watchedCollections.collectionId });
+        if (rows.length === 0)
+            continue;
+        resumed++;
+        logger.info("cron.admin-funds.resumed", {
+            collectionId,
+            admin,
+            covers: need.map((coin) => `${coin.amount}${coin.denom}`).join("+"),
+        });
+        // The pause told the owner once; the un-pause owes its pair. Fail-soft: a notice failure must
+        // never undo or abort a resume that already committed.
+        await notifyCollectionResumed(db, {
+            logger,
+            metrics: ctx.metrics,
+            config,
+            trace: ctx.deps.trace,
+            cache: ctx.env.CACHE_KV,
+            email: ctx.env.EMAIL,
+        }, collectionId).catch((err) => logger.warn("collection.notice.failed", { collectionId, detail: String(err) }));
+        await redeliverParked(ctx, config, collectionId);
+    }
+    return resumed;
+}
+/**
+ * The decisions the empty account left behind — `blocked` by the funds park, or `pending` with the
+ * act step's retries exhausted — oldest first, bounded: what `redeliverParked` re-delivers, and so
+ * what the resume threshold is measured against.
+ */
+function parkedDecisions(ctx, collectionId) {
+    return ctx.db
+        .select({ claimId: decisions.claimId, verdict: decisions.verdict })
+        .from(decisions)
+        .where(and(eq(decisions.collectionId, collectionId), eq(decisions.status, "decided"), inArray(decisions.verdict, ["approve", "reject"]), inArray(decisions.chainStatus, ["pending", "blocked"])))
+        .orderBy(asc(decisions.createdAt))
+        .limit(REDELIVER_LIMIT);
+}
+/**
+ * The largest single draw among the parked decisions, per denom (`adminDraw` — the act lane's own
+ * rule: the evaluation leg, plus an ordinary approve's payout or a reject's rejection payment). Any
+ * ONE of them can then go through; a later one still short just re-parks and re-pauses, and the
+ * re-delivery loop stops there. An approve's payout lives on the claim, read the way
+ * `deliverChainEvaluation` reads it (its payment plane → `evaluationAmount`); a claim Blocksync no
+ * longer returns is measured at the collection's approval default. A reject reads no claim. The
+ * act policy's own amount is not knowable here — re-delivery pays the lane's default
+ * (`signEvaluation`'s note), so that is what is measured. No parked rows ⇒ the evaluation leg.
+ */
+async function largestParkedDraw(ctx, collectionId, payments, fee) {
+    const parked = await parkedDecisions(ctx, collectionId);
+    const draws = await Promise.all(parked.map(async ({ claimId, verdict }) => {
+        const approve = verdict === "approve";
+        const claim = approve ? await getClaimById(ctx.deps, claimId) : null;
+        const payment = claimPayment(claim ?? { useIntent: null, paymentsStatus: null, amount: null });
+        return adminDraw({
+            payments,
+            fee,
+            verdict: { approve, payment, claimAmount: evaluationAmount(payment) },
+        });
+    }));
+    const largest = new Map();
+    for (const coin of [adminDraw({ payments, fee }), ...draws].flat()) {
+        const amount = BigInt(coin.amount);
+        if (amount > (largest.get(coin.denom) ?? 0n))
+            largest.set(coin.denom, amount);
+    }
+    return [...largest].map(([denom, amount]) => ({ denom, amount: amount.toString() }));
+}
+/** The admin's spendable balance per denom, each denom read at most once per probe. */
+function balanceReader(config, admin) {
+    const read = new Map();
+    return (denom) => {
+        let balance = read.get(denom);
+        if (!balance) {
+            balance = getSpendableBalance(config, admin, denom);
+            read.set(denom, balance);
+        }
+        return balance;
+    };
+}
+/** The first coin of `need` the balance does not cover, or nothing when it covers them all. */
+async function shortOf(funds, need) {
+    for (const coin of need) {
+        if ((await funds(coin.denom)) < BigInt(coin.amount))
+            return coin;
+    }
+    return undefined;
+}
+/**
+ * The decisions the empty account left behind — `blocked` by the funds park, or `pending` with the
+ * act step's retries exhausted before the park existed — oldest first, bounded, one at a time (the
+ * signer's sequence is serial anyway). A failure on one is logged and the rest still go; a park
+ * that re-pauses the collection (the account covered one delivery, not the next) stops the loop
+ * — the rest are picked up by the next resume. A workflow still retrying its own `act` step re-enters the
+ * lane idempotently (the delivered-once guard, `act.already-landed`).
+ */
+async function redeliverParked(ctx, config, collectionId) {
+    const { db, logger } = ctx;
+    const parked = await parkedDecisions(ctx, collectionId);
+    const deps = {
+        config,
+        logger,
+        metrics: ctx.metrics,
+        trace: ctx.deps.trace,
+        db,
+        sequenceManager: ctx.env.SEQUENCE_MANAGER,
+        cache: ctx.env.CACHE_KV,
+        email: ctx.env.EMAIL,
+        // What the act policy is handed (lib/ixo/chain-write.ts `ChainWriteDeps`) — a re-delivery
+        // consults it exactly like a first delivery does.
+        env: ctx.env,
+    };
+    let delivered = 0;
+    for (const { claimId } of parked) {
+        let outcome;
+        try {
+            outcome = await deliverChainEvaluation(deps, claimId);
+        }
+        catch (err) {
+            logger.warn("cron.admin-funds.redeliver-failed", {
+                collectionId,
+                claimId,
+                detail: String(err),
+            });
+            reportError(err, { lane: "cron", step: "admin-funds-redeliver", claimId, collectionId });
+            continue;
+        }
+        if (outcome === "submitted")
+            delivered++;
+        if (outcome === "blocked") {
+            // The status alone — never the row's 64 KB delegation CAR.
+            const [row] = await db
+                .select({ status: watchedCollections.status })
+                .from(watchedCollections)
+                .where(eq(watchedCollections.collectionId, collectionId));
+            if (row?.status === "paused")
+                break;
+        }
+    }
+    logger.info("cron.admin-funds.redelivered", { collectionId, parked: parked.length, delivered });
+}
+//# sourceMappingURL=funding.js.map

package/dist/cron/funding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"funding.js","sourceRoot":"","sources":["../../src/cron/funding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAe,UAAU,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAEnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,SAAS,EAAa,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC1F,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAG7D,kGAAkG;AAClG,MAAM,eAAe,GAAG,EAAE,CAAC;AAC3B;;;;;GAKG;AACH,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAChC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAE5B,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,GAAY;IACjD,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;IAC3B,MAAM,MAAM,GAAG,MAAM,EAAE;SACpB,MAAM,CAAC;QACN,YAAY,EAAE,kBAAkB,CAAC,YAAY;QAC7C,KAAK,EAAE,kBAAkB,CAAC,eAAe;QACzC,MAAM,EAAE,kBAAkB,CAAC,gBAAgB;KAC5C,CAAC;SACD,IAAI,CAAC,kBAAkB,CAAC;SACxB,KAAK,CACJ,GAAG,CACD,EAAE,CAAC,kBAAkB,CAAC,MAAM,EAAE,QAAQ,CAAC,EACvC,EAAE,CAAC,kBAAkB,CAAC,YAAY,EAAE,gBAAgB,CAAC,CACtD,CACF;QACD,gGAAgG;QAChG,wEAAwE;SACvE,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC;SAC1C,KAAK,CAAC,oBAAoB,CAAC,CAAC;IAC/B,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAElC,gGAAgG;IAChG,sGAAsG;IACtG,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACnC,gGAAgG;IAChG,4FAA4F;IAC5F,MAAM,QAAQ,GAA4D,EAAE,CAAC;IAC7E,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,iBAAiB,EAAE,CAAC;QAC1D,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAC9B,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,iBAAiB,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE;YACnF,oFAAoF;YACpF,yFAAyF;YACzF,wFAAwF;YACxF,wFAAwF;YACxF,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC/C,MAAM,CAAC,IAAI,CAAC,yBAAyB,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC;gBACzD,OAAO,IAAI,CAAC;YACd,CAAC;YACD,MAAM,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;YAC9B,IAAI,KAAgC,CAAC;YACrC,IAAI,IAAY,CAAC;YACjB,IAAI,KAAuB,CAAC;YAC5B,IAAI,CAAC;gBACH,MAAM,UAAU,GAAG,MAAM,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;gBAC/D,KAAK,GAAG,UAAU,EAAE,KAAK,CAAC;gBAC1B,IAAI,CAAC,KAAK;oBAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;gBACnD,MAAM,KAAK,GAAG,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;gBAC3C,sFAAsF;gBACtF,wFAAwF;gBACxF,IAAI,GAAG,SAAS,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC;gBAC1D,KAAK,GAAG,MAAM,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;gBACnC,IAAI,CAAC,KAAK,EAAE,CAAC;oBACX,IAAI,GAAG,MAAM,iBAAiB,CAAC,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;oBAC7E,KAAK,GAAG,MAAM,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;gBACrC,CAAC;YACH,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,2DAA2D;gBAC3D,MAAM,CAAC,IAAI,CAAC,6BAA6B,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBAClF,OAAO,IAAI,CAAC;YACd,CAAC;YACD,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,CAAC,KAAK,CAAC,+BAA+B,EAAE;oBAC5C,YAAY;oBACZ,KAAK;oBACL,KAAK,EAAE,GAAG,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,KAAK,EAAE;oBACtC,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;iBACtE,CAAC,CAAC;gBACH,OAAO,IAAI,CAAC;YACd,CAAC;YACD,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QACvC,CAAC,CAAC,CACH,CAAC;QACF,KAAK,MAAM,GAAG,IAAI,MAAM;YAAE,IAAI,GAAG;gBAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACxD,CAAC;IAED,gGAAgG;IAChG,kFAAkF;IAClF,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC;IAC5D,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IACjF,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,EAAE;aACL,MAAM,CAAC,kBAAkB,CAAC;aAC1B,GAAG,CAAC,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC;aAC9B,KAAK,CACJ,GAAG,CACD,OAAO,CAAC,kBAAkB,CAAC,YAAY,EAAE,MAAM,CAAC,EAChD,EAAE,CAAC,kBAAkB,CAAC,MAAM,EAAE,QAAQ,CAAC,EACvC,EAAE,CAAC,kBAAkB,CAAC,YAAY,EAAE,gBAAgB,CAAC,CACtD,CACF,CAAC;IACN,CAAC;IAED,yFAAyF;IACzF,6BAA6B;IAC7B,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,QAAQ,EAAE,CAAC;QACrD,yFAAyF;QACzF,MAAM,IAAI,GAAG,MAAM,EAAE;aAClB,MAAM,CAAC,kBAAkB,CAAC;aAC1B,GAAG,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;aAC7C,KAAK,CACJ,GAAG,CACD,EAAE,CAAC,kBAAkB,CAAC,YAAY,EAAE,YAAY,CAAC,EACjD,EAAE,CAAC,kBAAkB,CAAC,MAAM,EAAE,QAAQ,CAAC,EACvC,EAAE,CAAC,kBAAkB,CAAC,YAAY,EAAE,gBAAgB,CAAC,CACtD,CACF;aACA,SAAS,CAAC,EAAE,YAAY,EAAE,kBAAkB,CAAC,YAAY,EAAE,CAAC,CAAC;QAChE,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAChC,OAAO,EAAE,CAAC;QACV,MAAM,CAAC,IAAI,CAAC,0BAA0B,EAAE;YACtC,YAAY;YACZ,KAAK;YACL,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;SACpE,CAAC,CAAC;QAEH,8FAA8F;QAC9F,uDAAuD;QACvD,MAAM,uBAAuB,CAC3B,EAAE,EACF;YACE,MAAM;YACN,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,MAAM;YACN,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK;YACrB,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,QAAQ;YACvB,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,KAAK;SACrB,EACD,YAAY,CACb,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CACd,MAAM,CAAC,IAAI,CAAC,0BAA0B,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAC/E,CAAC;QAEF,MAAM,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,SAAS,eAAe,CAAC,GAAY,EAAE,YAAoB;IACzD,OAAO,GAAG,CAAC,EAAE;SACV,MAAM,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,OAAO,EAAE,CAAC;SAClE,IAAI,CAAC,SAAS,CAAC;SACf,KAAK,CACJ,GAAG,CACD,EAAE,CAAC,SAAS,CAAC,YAAY,EAAE,YAAY,CAAC,EACxC,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,EAC/B,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC,EACjD,OAAO,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CACvD,CACF;SACA,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;SACjC,KAAK,CAAC,eAAe,CAAC,CAAC;AAC5B,CAAC;AAED;;;;;;;;;GASG;AACH,KAAK,UAAU,iBAAiB,CAC9B,GAAY,EACZ,YAAoB,EACpB,QAA+C,EAC/C,GAAS;IAET,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;IACxD,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,GAAG,CAC7B,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE;QACxC,MAAM,OAAO,GAAG,OAAO,KAAK,SAAS,CAAC;QACtC,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACrE,MAAM,OAAO,GAAG,YAAY,CAC1B,KAAK,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CACjE,CAAC;QACF,OAAO,SAAS,CAAC;YACf,QAAQ;YACR,GAAG;YACH,OAAO,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAAE;SACtE,CAAC,CAAC;IACL,CAAC,CAAC,CACH,CAAC;IACF,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC1C,KAAK,MAAM,IAAI,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QACnE,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACnC,IAAI,MAAM,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;YAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAChF,CAAC;IACD,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC;AACvF,CAAC;AAED,uFAAuF;AACvF,SAAS,aAAa,CAAC,MAAc,EAAE,KAAa;IAClD,MAAM,IAAI,GAAG,IAAI,GAAG,EAA2B,CAAC;IAChD,OAAO,CAAC,KAAa,EAAE,EAAE;QACvB,IAAI,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC9B,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,GAAG,mBAAmB,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;YACpD,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAC3B,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC;AACJ,CAAC;AAED,+FAA+F;AAC/F,KAAK,UAAU,OAAO,CACpB,KAAyC,EACzC,IAAY;IAEZ,KAAK,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;QACxB,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;YAAE,OAAO,IAAI,CAAC;IACnE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;GAOG;AACH,KAAK,UAAU,eAAe,CAAC,GAAY,EAAE,MAAc,EAAE,YAAoB;IAC/E,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;IAC3B,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;IACxD,MAAM,IAAI,GAAG;QACX,MAAM;QACN,MAAM;QACN,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK;QACrB,EAAE;QACF,eAAe,EAAE,GAAG,CAAC,GAAG,CAAC,gBAAgB;QACzC,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,QAAQ;QACvB,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,KAAK;QACpB,0FAA0F;QAC1F,kDAAkD;QAClD,GAAG,EAAE,GAAG,CAAC,GAAG;KACb,CAAC;IACF,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,KAAK,MAAM,EAAE,OAAO,EAAE,IAAI,MAAM,EAAE,CAAC;QACjC,IAAI,OAA2D,CAAC;QAChE,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,sBAAsB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACxD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CAAC,mCAAmC,EAAE;gBAC/C,YAAY;gBACZ,OAAO;gBACP,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC;aACpB,CAAC,CAAC;YACH,WAAW,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,uBAAuB,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,CAAC;YACzF,SAAS;QACX,CAAC;QACD,IAAI,OAAO,KAAK,WAAW;YAAE,SAAS,EAAE,CAAC;QACzC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,2DAA2D;YAC3D,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,EAAE;iBACnB,MAAM,CAAC,EAAE,MAAM,EAAE,kBAAkB,CAAC,MAAM,EAAE,CAAC;iBAC7C,IAAI,CAAC,kBAAkB,CAAC;iBACxB,KAAK,CAAC,EAAE,CAAC,kBAAkB,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC;YAC5D,IAAI,GAAG,EAAE,MAAM,KAAK,QAAQ;gBAAE,MAAM;QACtC,CAAC;IACH,CAAC;IACD,MAAM,CAAC,IAAI,CAAC,8BAA8B,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;AAClG,CAAC"}

package/dist/cron/payer-billing.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Un-pausing a per-review collection (payments/review-billing.ts) — the twin of billing.ts and
+ * funding.ts for the review-billing pauses: `oracle-plan` (IXO's) once the engine's plan allows
+ * per-review billing again and someone pays, and the two only a payer can lift: `payer-delegation` (no usable delegation)
+ * resumes once who pays resolves again (a new delegation, its signer the organisation's owner, cap
+ * left, a price), `payer-credits` once the payer's credits — read with the stored delegation —
+ * cover one review. Every minute while any such collection is paused, bounded, oldest pause first;
+ * a collection still unpaid is simply asked again next time. Never resumes an operator's pause or
+ * another reason, and nothing while IXO's plan does not allow per-review billing.
+ *
+ * On a resume: the paired "resumed" notice, and the claims whose run gave up while the collection
+ * was paused (`claim_ingests` `failed` with a `payer-billing:` error) are restarted — same instance
+ * id, the ledger converges. `PUT /v1/api/source/review-billing` runs the same for its organisation
+ * at once.
+ */
+import type { Config } from "../config.js";
+import type { Database } from "../db/client.js";
+import type { OracleEnv } from "../env.js";
+import type { Logger } from "../lib/logger.js";
+import type { Metrics } from "../lib/metrics.js";
+import type { TraceContext } from "../lib/tracing.js";
+export interface PayerResumeDeps {
+    db: Database;
+    config: Config;
+    logger: Logger;
+    metrics: Metrics;
+    trace: TraceContext;
+    cache: KVNamespace;
+    env: Pick<OracleEnv, "CLAIM_WORKFLOW" | "EMAIL">;
+}
+/**
+ * Resume what can be resumed; `entityDid` limits it to one organisation's collections (the PUT).
+ * Returns the collections resumed.
+ */
+export declare function resumePayerBilling(deps: PayerResumeDeps, scope?: {
+    entityDid?: string;
+}): Promise<string[]>;
+//# sourceMappingURL=payer-billing.d.ts.map

package/dist/cron/payer-billing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payer-billing.d.ts","sourceRoot":"","sources":["../../src/cron/payer-billing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAW9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGnD,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,QAAQ,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,WAAW,CAAC;IACnB,GAAG,EAAE,IAAI,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,CAAC;CAClD;AAQD;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,eAAe,EACrB,KAAK,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACjC,OAAO,CAAC,MAAM,EAAE,CAAC,CAoEnB"}

package/dist/cron/payer-billing.js

@@ -0,0 +1,119 @@
+/**
+ * Un-pausing a per-review collection (payments/review-billing.ts) — the twin of billing.ts and
+ * funding.ts for the review-billing pauses: `oracle-plan` (IXO's) once the engine's plan allows
+ * per-review billing again and someone pays, and the two only a payer can lift: `payer-delegation` (no usable delegation)
+ * resumes once who pays resolves again (a new delegation, its signer the organisation's owner, cap
+ * left, a price), `payer-credits` once the payer's credits — read with the stored delegation —
+ * cover one review. Every minute while any such collection is paused, bounded, oldest pause first;
+ * a collection still unpaid is simply asked again next time. Never resumes an operator's pause or
+ * another reason, and nothing while IXO's plan does not allow per-review billing.
+ *
+ * On a resume: the paired "resumed" notice, and the claims whose run gave up while the collection
+ * was paused (`claim_ingests` `failed` with a `payer-billing:` error) are restarted — same instance
+ * id, the ledger converges. `PUT /v1/api/source/review-billing` runs the same for its organisation
+ * at once.
+ */
+import { and, asc, eq, inArray, like } from "drizzle-orm";
+import { apiSources, claimIngests, watchedCollections } from "../db/schema.js";
+import { BILLING_PAUSES, companyOf, creditsCover, PayerUnavailable, planAllowsReviewBilling, resolvePayer, } from "../lib/payments/review-billing.js";
+import { reportError } from "../lib/sentry.js";
+import { notifyCollectionResumed } from "../workflows/steps.js";
+/** Paused collections looked at per run, and claims restarted per resumed collection. */
+const RESUME_BATCH = 20;
+const RESTART_BATCH = 20;
+/** The ledger error the workflow writes for a run that gave up on payment (claim-ingest.ts). */
+const GAVE_UP_ON_PAYMENT = "payer-billing:%";
+/**
+ * Resume what can be resumed; `entityDid` limits it to one organisation's collections (the PUT).
+ * Returns the collections resumed.
+ */
+export async function resumePayerBilling(deps, scope = {}) {
+    const { db, logger } = deps;
+    const paying = scope.entityDid
+        ? db
+            .select({ sourceId: apiSources.sourceId })
+            .from(apiSources)
+            .where(eq(apiSources.companyEntityDid, scope.entityDid))
+        : undefined;
+    const paused = await db
+        .select({
+        collectionId: watchedCollections.collectionId,
+        protocolDid: watchedCollections.protocolDid,
+        reason: watchedCollections.pausedReason,
+    })
+        .from(watchedCollections)
+        .where(and(eq(watchedCollections.status, "paused"), inArray(watchedCollections.pausedReason, [...BILLING_PAUSES]), paying ? inArray(watchedCollections.billingSourceId, paying) : undefined))
+        .orderBy(asc(watchedCollections.updatedAt))
+        .limit(RESUME_BATCH);
+    if (paused.length === 0)
+        return [];
+    const billing = { ...deps };
+    // Not IXO's to sell any more: a re-register (on the escrow gate) is the way back.
+    if (!(await planAllowsReviewBilling(billing).catch(() => false)))
+        return [];
+    const resumed = [];
+    for (const p of paused) {
+        try {
+            const payer = await resolvePayer(billing, await companyOf(billing, p.collectionId), p.protocolDid ?? "");
+            // `oracle-plan` (IXO's, the plan allows it again above): resumed as soon as someone pays.
+            if (!payer.ok)
+                continue;
+            if (p.reason === "payer-credits" && !(await creditsCover(billing, payer)))
+                continue;
+            const [flipped] = await db
+                .update(watchedCollections)
+                .set({ status: "active", pausedReason: null, billingSourceId: payer.source.sourceId })
+                .where(and(eq(watchedCollections.collectionId, p.collectionId), eq(watchedCollections.status, "paused"), eq(watchedCollections.pausedReason, p.reason)))
+                .returning({ collectionId: watchedCollections.collectionId });
+            if (!flipped)
+                continue;
+            resumed.push(p.collectionId);
+            logger.info("cron.payer-billing.resumed", { collectionId: p.collectionId, reason: p.reason });
+            deps.metrics.count("review_billing.resumed", 1, { outcome: p.reason ?? null });
+            await afterResume(deps, p.collectionId, p.reason !== "oracle-plan");
+        }
+        catch (err) {
+            // The engine or the facilitator could not say: still paused, asked again next run.
+            if (!(err instanceof PayerUnavailable)) {
+                reportError(err, { lane: "payments", step: "payer-resume", collectionId: p.collectionId });
+            }
+            logger.warn("cron.payer-billing.unreadable", {
+                collectionId: p.collectionId,
+                detail: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return resumed;
+}
+/**
+ * The paired notice (only when the pause sent one — never `oracle-plan`'s), then the claims that
+ * gave up during the pause (fail-soft, bounded).
+ */
+async function afterResume(deps, collectionId, notify) {
+    const { db, logger } = deps;
+    if (notify) {
+        await notifyCollectionResumed(db, {
+            logger,
+            metrics: deps.metrics,
+            config: deps.config,
+            trace: deps.trace,
+            cache: deps.cache,
+            email: deps.env.EMAIL,
+        }, collectionId).catch((err) => logger.warn("collection.notice.failed", { collectionId, detail: String(err) }));
+    }
+    const gaveUp = await db
+        .select({ claimId: claimIngests.claimId, instanceId: claimIngests.instanceId })
+        .from(claimIngests)
+        .where(and(eq(claimIngests.collectionId, collectionId), eq(claimIngests.status, "failed"), like(claimIngests.error, GAVE_UP_ON_PAYMENT)))
+        .limit(RESTART_BATCH);
+    for (const { claimId, instanceId } of gaveUp) {
+        try {
+            await (await deps.env.CLAIM_WORKFLOW.get(instanceId ?? claimId)).restart();
+        }
+        catch (err) {
+            // Its instance is gone (retention): the operator re-creates it by hand (claim-ingest.ts).
+            logger.warn("cron.payer-billing.restart-failed", { claimId, detail: String(err) });
+        }
+    }
+}
+//# sourceMappingURL=payer-billing.js.map

package/dist/cron/payer-billing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payer-billing.js","sourceRoot":"","sources":["../../src/cron/payer-billing.ts"],"names":[],"mappings":"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"}

package/dist/cron/scan.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The cron tick (README "How a claim flows" step 2) — the system of record for ingestion. Each tick picks a
+ * BOUNDED batch of watched collections (active only, the least recently scanned first — see
+ * `lastScannedAt`), discovers their new on-chain claims, and starts one `ClaimIngest` workflow per
+ * claim. That's all it does: the workflow owns the ledger row and its retries
+ * (workflows/claim-ingest.ts); a failing collection is logged and rotates to the back of the queue
+ * like any other.
+ *
+ * The chain is truth — we never trust a pushed claimId — and the design is self-healing by
+ * construction: cursors only advance after instances start, so if we're down (or a tick fails),
+ * the next tick simply re-scans from the watermark.
+ *
+ * The scan is the minute tier's; the same entry point runs the five-minute and hourly tiers
+ * (`CRON_TIERS` below), each trigger only its own jobs.
+ */
+import type { OracleEnv } from "../env.js";
+import { type CronCtx } from "./collection.js";
+/**
+ * The three Cloudflare cron triggers (wrangler.jsonc `triggers.crons`), one tier each. A job runs
+ * in exactly ONE tier, picked by the trigger that fired (`event.cron`) — never by a gate on the
+ * clock or the scheduled minute, which Cloudflare's late-running ticks kept missing.
+ */
+export declare const CRON_TIERS: {
+    readonly "* * * * *": "minute";
+    readonly "*/5 * * * *": "five";
+    readonly "0 * * * *": "hour";
+};
+export type CronTier = (typeof CRON_TIERS)[keyof typeof CRON_TIERS];
+/**
+ * Assemble a `CronCtx` from `env` — loadConfig, a trace, a logger carrying the same base fields,
+ * metrics, and the D1 handle (D1 is a binding — nothing to open or close around a tick,
+ * db/client.ts). The tick below builds one per run; `scanCollection` (../runtime.ts) builds one
+ * the same way so a webhook-triggered scan and the tick that would eventually reach the same
+ * collection agree on every dedupe/cursor rule byte for byte.
+ */
+export declare function cronContext(env: OracleEnv): CronCtx;
+/**
+ * One trigger's run: `cron` is the trigger that fired (`ScheduledController.cron`), and only its
+ * tier's jobs run. A string that names no tier (a trigger in wrangler.jsonc this map lacks) is a
+ * log line and nothing else.
+ */
+export declare function runCronTick(env: OracleEnv, cron: string): Promise<void>;
+//# sourceMappingURL=scan.d.ts.map

package/dist/cron/scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../src/cron/scan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAOH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAUxC,OAAO,EAAE,KAAK,OAAO,EAAqB,MAAM,cAAc,CAAC;AAM/D;;;;GAIG;AACH,eAAO,MAAM,UAAU;aACrB,WAAW,EAAE,QAAQ;aACrB,aAAa,EAAE,MAAM;aACrB,WAAW,EAAE,MAAM;CACX,CAAC;AACX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,CAAC;AAepE;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAgBnD;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiB7E"}