@mohasinac/appkit 4.59.0 → 4.60.1

package/dist/_internal/server/jobs/core/dailyDataCleanup.js

@@ -1,7 +1,11 @@
 import { sessionRepository, tokenRepository } from "../../../../repositories/index.js";
+import { gatewayEventsRepository } from "../../../../features/gateway-events/repository/gateway-events.repository.js";
+import { pointsRepository } from "../../../../features/points/repository/points.repository.js";
+import { paymentCasesRepository } from "../../../../features/payment-cases/repository/payment-cases.repository.js";
+import { normalizeError } from "../../../../errors/normalize.js";
 import { batchDelete } from "../handlers/_helpers.js";
 export async function runDailyDataCleanup(ctx) {
-    ctx.logger.info("Starting daily data cleanup (sessions + tokens)");
+    ctx.logger.info("Starting daily data cleanup (sessions + tokens + gateway events)");
     const sessionRefs = await sessionRepository.getExpiredRefs(ctx.now);
     const sessionsDeleted = await batchDelete(ctx, sessionRefs);
     ctx.logger.info("Session cleanup complete", { deleted: sessionsDeleted });
@@ -13,8 +17,152 @@ export async function runDailyDataCleanup(ctx) {
         emailVerificationDeleted: emailDeleted,
         passwordResetDeleted: pwDeleted,
     });
+    /*
+     * ── gatewayEvents retention, 90 days ──────────────────────────────────────
+     *
+     * Folded in here rather than given its own scheduled function, deliberately:
+     * Cloud Scheduler bills **per registered job** (3 free, 28 already
+     * registered), so a new job for one `where(expiresAt <).limit(500)` query is
+     * ~$0.10/month for work that fits in a slot that already runs daily and
+     * already does exactly this shape for sessions and tokens.
+     *
+     * 🛑 Bounded at 500 per run, which is `getExpiredRefs`' own limit. At the
+     * expected ~100 events/day that is five days of backlog capacity, so the
+     * bound can only bite after a sustained ingest spike — and in that case the
+     * right response is to look at why, not to widen a sweep until it times out.
+     * The count is logged for exactly that reason.
+     *
+     * 🛑 It does NOT exclude rows referenced by an open `paymentCases` row yet —
+     * Phase 3 builds that collection and this is where the exclusion goes. Until
+     * then nothing references a gateway event, so there is nothing to protect;
+     * leaving a TODO-shaped comment here instead of a filter is honest, and the
+     * retention window (90d) is longer than any case should stay open.
+     */
+    const eventRefs = await gatewayEventsRepository().getExpiredRefs(ctx.now);
+    const eventsDeleted = await batchDelete(ctx, eventRefs);
+    ctx.logger.info("Gateway event cleanup complete", {
+        deleted: eventsDeleted,
+        hitLimit: eventRefs.length === 500,
+    });
+    /*
+     * ── Points expiry (Phase P, decision 4) ─────────────────────────────────
+     *
+     * Folded into THIS job rather than registered as its own, which is the same
+     * reasoning the 90-day gateway-event sweep above follows: Cloud Scheduler
+     * bills per REGISTERED JOB (~$0.10/month each, 3 free, 28 already live), and
+     * expiry is a once-a-day question whose answer does not need its own cadence.
+     *
+     * 🛑 It is not a cleanup in the delete sense, and that is why it comes last
+     * and is logged separately. The other three blocks remove rows nobody needs;
+     * this one DEBITS A BUYER by writing an adjustment entry. Burying that count
+     * inside "cleanup complete" would make a line of real money read as
+     * housekeeping.
+     *
+     * Bounded per run, and saturation is reported — at 200 expiries in one day
+     * there are more waiting, which is a fact about the programme's size rather
+     * than an error, but it must not look like the whole number.
+     */
+    let pointsExpired = { examined: 0, expired: 0, points: 0 };
+    try {
+        pointsExpired = await pointsRepository.expireLapsedBatches(ctx.now);
+        if (pointsExpired.expired > 0) {
+            ctx.logger.info("Points expiry complete", { ...pointsExpired });
+        }
+        if (pointsExpired.examined === 200) {
+            ctx.logger.warn("Points expiry hit its page limit — more batches are due than were processed");
+        }
+    }
+    catch (err) {
+        void normalizeError(err);
+        /*
+         * Never fails the cleanup. An unexpired batch stays spendable for another
+         * day, which costs us a day of liability and costs the buyer nothing —
+         * strictly the safe direction, and the next run picks it up because the
+         * query is driven by `expiresAt` rather than by a cursor.
+         */
+        ctx.logger.error("Points expiry failed — batches stay spendable for now");
+    }
+    /*
+     * ── Points ledger ↔ mirror reconciliation (D49) ─────────────────────────
+     *
+     * `sumLedger`'s own docstring has promised this job since the ledger was
+     * written — "to let a reconciliation job prove the two agree" — and nobody
+     * wrote it, so `users/{uid}.pointsBalance` could diverge from the entries
+     * indefinitely with nothing reporting it. Root Cause #102 one domain over.
+     *
+     * Folded in here rather than registered as its own scheduled function, the
+     * same reasoning as the two blocks above: Cloud Scheduler bills per
+     * REGISTERED JOB and "do the two agree" is a once-a-day question. The count
+     * is 33 and adding a 34th for one comparison is ~$0.10/month for work that
+     * fits in a slot already running.
+     *
+     * 🛑 It runs AFTER expiry, deliberately. Expiry writes adjustment entries and
+     * moves the mirror; reconciling first would measure a state expiry is about
+     * to change and could report drift that resolves itself seconds later.
+     *
+     * 🛑 Every drift opens a `ledger_drift` case even though the mirror is
+     * repaired on the spot. Repair without a report is self-healing that hides
+     * the write path which broke it — and `openOrObserve` is keyed on the user,
+     * so a persistently broken writer is ONE case with a rising `observedCount`
+     * rather than a fresh row every night.
+     */
+    let ledgerDrift = 0;
+    try {
+        const recon = await pointsRepository.reconcileLedgerMirror();
+        ledgerDrift = recon.drifted.length;
+        for (const d of recon.drifted) {
+            ctx.logger.error("points mirror disagreed with the ledger — repaired", {
+                userId: d.userId,
+                mirror: d.mirror,
+                ledger: d.ledger,
+            });
+            await paymentCasesRepository()
+                .openOrObserve({
+                kind: "ledger_drift",
+                severity: "warning",
+                subjectId: d.userId,
+                title: "Points balance disagreed with the ledger",
+                detail: `The mirror on users/${d.userId} read ${d.mirror} while the ledger sums to ` +
+                    `${d.ledger}. The mirror has been repaired to the ledger, which is ` +
+                    `authoritative. A repeat means a write path is losing entries.`,
+                entityType: "user",
+                entityId: d.userId,
+                now: ctx.now,
+            })
+                /*
+                 * Best-effort: a case that cannot be filed must not fail the cleanup,
+                 * because the repair has already happened and is the part the buyer
+                 * feels. The logger line above is the fallback record.
+                 */
+                .catch((caseErr) => {
+                void normalizeError(caseErr);
+                ctx.logger.error("could not open a ledger_drift case", { userId: d.userId });
+            });
+        }
+        if (recon.initialised > 0) {
+            // Not a fault — `getBalance` already falls back to summing the ledger.
+            ctx.logger.info("points mirrors initialised", { count: recon.initialised });
+        }
+        if (recon.saturated) {
+            ctx.logger.warn("points reconciliation hit its page limit — more users are unchecked than were checked");
+        }
+    }
+    catch (err) {
+        void normalizeError(err);
+        /*
+         * Never fails the cleanup. An unreconciled mirror is a read that may be
+         * wrong by whatever the drift is, which the next run catches; failing the
+         * job would also skip nothing useful, since every block above has already
+         * run.
+         */
+        ctx.logger.error("points reconciliation failed — mirrors unverified this run");
+    }
     ctx.logger.info("Daily data cleanup complete", {
         sessionsDeleted,
         tokensDeleted: emailDeleted + pwDeleted,
+        gatewayEventsDeleted: eventsDeleted,
+        pointsBatchesExpired: pointsExpired.expired,
+        pointsExpired: pointsExpired.points,
+        pointsLedgerDrift: ledgerDrift,
     });
 }

package/dist/_internal/server/jobs/core/dailyStatusDigest.d.ts

@@ -44,6 +44,20 @@ export interface DailyStatusDigestSummary {
     /** Privileged admin actions recorded in 24h — replaces the per-save settings email. */
     adminActionCount: number;
     unreadAdminNotificationCount: number;
+    /** Active (open + under-review) `paymentCases`, by severity. */
+    paymentCasesError: number;
+    paymentCasesWarning: number;
+    paymentCasesInfo: number;
+    /**
+     * The soonest external deadline across active cases, or null.
+     *
+     * 🛑 Not "oldest case" and not a count: a deadline is the only thing in this
+     * digest that gets WORSE on its own, so it is the one figure worth printing
+     * as a date rather than a number.
+     */
+    nearestCaseDueAt: Date | null;
+    /** Gateway events that never reached a terminal status — the inbox backlog. */
+    unprocessedGatewayEventCount: number;
 }
 /** Gathers the last-24h numbers. Exported so the admin manual-trigger route can reuse it. */
 export declare function collectDailyStatusSummary(): Promise<DailyStatusDigestSummary>;

package/dist/_internal/server/jobs/core/dailyStatusDigest.js

@@ -27,6 +27,15 @@ import { SUPPORT_TICKET_COLLECTION, SUPPORT_TICKET_FIELDS, TicketStatusValues, }
 import { SCAMMER_COLLECTION, SCAMMER_FIELDS } from "../../../../features/scams/schemas/firestore.js";
 import { ADMIN_AUDIT_LOG_COLLECTION } from "../../../../features/audit-log/schemas/firestore.js";
 import { ADMIN_NOTIFICATIONS_COLLECTION } from "../../../../features/store-extensions/schemas/rbac.js";
+/*
+ * Schema modules only — constants and types, no repository. This file is
+ * reachable from the Functions bundle and already queries nine collections
+ * through `getAdminDb()` directly; importing two repositories for four
+ * `count()` calls would widen that graph for nothing. Same reasoning as the
+ * `CountableQuery` structural type below.
+ */
+import { PAYMENT_CASES_COLLECTION, PAYMENT_CASE_ACTIVE_STATUSES, PAYMENT_CASE_FIELDS, } from "../../../../features/payment-cases/schemas/firestore.js";
+import { GATEWAY_EVENTS_COLLECTION, GATEWAY_EVENT_FIELDS, } from "../../../../features/gateway-events/schemas/firestore.js";
 import { EmailBold, EmailContainer, EmailDivider, EmailDoc, EmailFooter, EmailHeader, EmailLink, EmailRow, } from "../../../../features/email/primitives.js";
 import { normalizeError } from "../../../../errors/normalize.js";
 const DAY_MS = 24 * 60 * 60 * 1000;
@@ -137,6 +146,63 @@ export async function collectDailyStatusSummary() {
         safeCount(db.collection(ADMIN_AUDIT_LOG_COLLECTION).where(CREATED_AT, ">=", since)),
         safeCount(db.collection(ADMIN_NOTIFICATIONS_COLLECTION).where(IS_READ, "==", false)),
     ]);
+    /*
+     * ── MONEY AT RISK ─────────────────────────────────────────────────────────
+     *
+     * Three counts and one date. Deliberately NOT through
+     * `paymentCasesRepository`: this file is reachable from the Functions bundle,
+     * and the digest already talks to `getAdminDb()` directly for its other nine
+     * collections. Pulling a repository in here for three `count()` calls would
+     * widen the bundle's graph for no gain — the same reasoning the file's own
+     * `CountableQuery` comment gives for not importing a firebase-admin type.
+     *
+     * 🛑 Every one goes through `safeCount`, which returns 0 on failure. That is
+     * right for a digest and wrong almost anywhere else: a missing composite
+     * index must not stop the OTHER eleven sections being delivered, and a stuck
+     * zero beside live numbers reads as "that one broke". It is also why the
+     * nearest-deadline query below swallows and returns null rather than
+     * throwing.
+     */
+    const [paymentCasesError, paymentCasesWarning, paymentCasesInfo, unprocessedGatewayEventCount] = await Promise.all([
+        safeCount(db
+            .collection(PAYMENT_CASES_COLLECTION)
+            .where(PAYMENT_CASE_FIELDS.STATUS, "in", [...PAYMENT_CASE_ACTIVE_STATUSES])
+            .where(PAYMENT_CASE_FIELDS.SEVERITY, "==", "error")),
+        safeCount(db
+            .collection(PAYMENT_CASES_COLLECTION)
+            .where(PAYMENT_CASE_FIELDS.STATUS, "in", [...PAYMENT_CASE_ACTIVE_STATUSES])
+            .where(PAYMENT_CASE_FIELDS.SEVERITY, "==", "warning")),
+        safeCount(db
+            .collection(PAYMENT_CASES_COLLECTION)
+            .where(PAYMENT_CASE_FIELDS.STATUS, "in", [...PAYMENT_CASE_ACTIVE_STATUSES])
+            .where(PAYMENT_CASE_FIELDS.SEVERITY, "==", "info")),
+        safeCount(db
+            .collection(GATEWAY_EVENTS_COLLECTION)
+            .where(GATEWAY_EVENT_FIELDS.STATUS, "in", ["received", "processing", "failed"])),
+    ]);
+    /*
+     * The soonest external deadline. One document, ordered — and note it can only
+     * see cases that HAVE a `dueAt`, because a Firestore inequality excludes
+     * documents lacking the field (Root Cause #100). Correct here: a case with no
+     * deadline has nothing to be nearest about.
+     */
+    let nearestCaseDueAt = null;
+    try {
+        const dueSnap = await db
+            .collection(PAYMENT_CASES_COLLECTION)
+            .where(PAYMENT_CASE_FIELDS.STATUS, "in", [...PAYMENT_CASE_ACTIVE_STATUSES])
+            .orderBy(PAYMENT_CASE_FIELDS.DUE_AT, "asc")
+            .limit(1)
+            .get();
+        const raw = dueSnap.docs[0]?.get(PAYMENT_CASE_FIELDS.DUE_AT);
+        if (raw instanceof Date)
+            nearestCaseDueAt = raw;
+        else if (raw && typeof raw.toDate === "function")
+            nearestCaseDueAt = raw.toDate();
+    }
+    catch (err) {
+        void normalizeError(err);
+    }
     /*
      * `contactSubmissions` carries NO PII encryption — name, email, subject and
      * message are stored in plaintext (see `ContactSubmissionDocument`). That is
@@ -174,6 +240,11 @@ export async function collectDailyStatusSummary() {
         newSubscriberCount,
         adminActionCount,
         unreadAdminNotificationCount,
+        paymentCasesError,
+        paymentCasesWarning,
+        paymentCasesInfo,
+        nearestCaseDueAt,
+        unprocessedGatewayEventCount,
     };
 }
 function renderDigestHtml(summary, siteName, version) {
@@ -183,7 +254,7 @@ function renderDigestHtml(summary, siteName, version) {
                             ? `Deployment ${version} is live. Activity for the last 24 hours.`
                             : "Activity for the last 24 hours.", _jsx("br", {}), _jsx("br", {}), _jsx(StatLine, { label: "Orders placed", value: summary.orderCount }), _jsx(StatLine, { label: "Revenue (excl. cancelled/refunded)", value: currency(summary.revenue) }), _jsx(StatLine, { label: "Active listings", value: summary.activeListingCount }), _jsx(StatLine, { label: "Pending > 24h (needs attention)", value: summary.stuckPendingCount })] }), _jsx(EmailDivider, {}), _jsxs(EmailRow, { children: [_jsx(EmailBold, { children: "Orders by status" }), _jsx("br", {}), _jsx("br", {}), statusRows.length === 0 ? ("No orders in this window.") : (statusRows.map(([status, count]) => (_jsx(StatLine, { label: status, value: count }, status))))] }), _jsx(EmailDivider, {}), _jsxs(EmailRow, { children: [_jsx(EmailBold, { children: "Inbox" }), _jsx("br", {}), _jsx("br", {}), _jsx(StatLine, { label: "New contact messages", value: summary.contactTotal }), _jsx(StatLine, { label: "New support tickets", value: summary.newTicketCount }), _jsx(StatLine, { label: "Tickets open / in progress / waiting on user", value: `${summary.ticketsOpen} / ${summary.ticketsInProgress} / ${summary.ticketsWaitingOnUser}` }), _jsx(StatLine, { label: "Unread admin notifications", value: summary.unreadAdminNotificationCount })] }), summary.contactMessages.length > 0 ? (_jsxs(EmailRow, { children: [_jsx(EmailBold, { children: "Contact messages" }), _jsx("br", {}), _jsx("br", {}), summary.contactMessages.map((m) => (_jsxs(Fragment, { children: [_jsx(EmailBold, { children: m.subject }), _jsx("br", {}), m.name, " \u2014", " ", _jsxs(EmailLink, { href: `mailto:${m.email}?subject=${encodeURIComponent(`Re: ${m.subject}`)}`, children: ["Reply to ", m.email] }), _jsx("br", {}), m.excerpt, _jsx("br", {}), _jsx("br", {})] }, m.id))), summary.contactTotal > summary.contactMessages.length
                             ? `…and ${summary.contactTotal - summary.contactMessages.length} more in /admin/contact.`
-                            : null] })) : null, _jsx(EmailDivider, {}), _jsxs(EmailRow, { children: [_jsx(EmailBold, { children: "Needs attention" }), _jsx("br", {}), _jsx("br", {}), _jsx(StatLine, { label: "Manual payments pending", value: summary.manualPaymentPendingCount }), _jsx(StatLine, { label: "New scam reports", value: summary.newScamReportCount }), _jsx(StatLine, { label: "New newsletter subscribers", value: summary.newSubscriberCount }), _jsx(StatLine, { label: "Admin actions logged", value: summary.adminActionCount })] }), _jsx(EmailFooter, { copyright: `© ${new Date().getFullYear()}${siteName ? ` ${siteName}` : ""}. All rights reserved.` })] }) }))}`;
+                            : null] })) : null, _jsx(EmailDivider, {}), _jsxs(EmailRow, { children: [_jsx(EmailBold, { children: "Needs attention" }), _jsx("br", {}), _jsx("br", {}), _jsx(StatLine, { label: "Manual payments pending", value: summary.manualPaymentPendingCount }), _jsx(StatLine, { label: "New scam reports", value: summary.newScamReportCount }), _jsx(StatLine, { label: "New newsletter subscribers", value: summary.newSubscriberCount }), _jsx(StatLine, { label: "Admin actions logged", value: summary.adminActionCount })] }), _jsx(EmailDivider, {}), _jsxs(EmailRow, { children: [_jsx(EmailBold, { children: "Money at risk" }), _jsx("br", {}), _jsx("br", {}), _jsx(StatLine, { label: "Open cases \u2014 urgent", value: summary.paymentCasesError }), _jsx(StatLine, { label: "Open cases \u2014 warning", value: summary.paymentCasesWarning }), _jsx(StatLine, { label: "Open cases \u2014 info", value: summary.paymentCasesInfo }), _jsx(StatLine, { label: "Nearest external deadline", value: summary.nearestCaseDueAt ? summary.nearestCaseDueAt.toISOString() : "none" }), _jsx(StatLine, { label: "Unfinished gateway events", value: summary.unprocessedGatewayEventCount })] }), _jsx(EmailFooter, { copyright: `© ${new Date().getFullYear()}${siteName ? ` ${siteName}` : ""}. All rights reserved.` })] }) }))}`;
 }
 /**
  * The plain-text twin of `renderDigestHtml`.
@@ -211,6 +282,13 @@ function renderDigestText(summary, version) {
         }
     }
     lines.push("", "NEEDS ATTENTION", `Manual payments pending: ${summary.manualPaymentPendingCount}`, `New scam reports: ${summary.newScamReportCount}`, `New newsletter subscribers: ${summary.newSubscriberCount}`, `Admin actions logged: ${summary.adminActionCount}`);
+    /*
+     * The text twin of the HTML "Money at risk" section — this is the pairing
+     * the docstring above exists to enforce. Same five figures, same order, and
+     * the same unconditional rendering, because a mail client showing the text
+     * part must not get a digest missing the one block with a deadline in it.
+     */
+    lines.push("", "MONEY AT RISK", `Open cases — urgent: ${summary.paymentCasesError}`, `Open cases — warning: ${summary.paymentCasesWarning}`, `Open cases — info: ${summary.paymentCasesInfo}`, `Nearest external deadline: ${summary.nearestCaseDueAt ? summary.nearestCaseDueAt.toISOString() : "none"}`, `Unfinished gateway events: ${summary.unprocessedGatewayEventCount}`);
     return lines.join("\n");
 }
 const DEPLOY_MARKER_COLLECTION = "system";

package/dist/_internal/server/jobs/core/index.d.ts

@@ -19,6 +19,8 @@ export { runCleanupRtdbEvents } from "./cleanupRtdbEvents";
 export { runMediaTmpCleanup } from "./mediaTmpCleanup";
 export { runPendingOrderTimeout } from "./pendingOrderTimeout";
 export { runCountersReconcile } from "./countersReconcile";
+export { runPaymentReconcile, reconcileStuckGatewayEvents } from "./paymentReconcile";
+export { runObligationSweep } from "./obligationSweep";
 export { runBundleStockSync } from "./bundleStockSync";
 export { runAutoPayoutEligibility } from "./autoPayoutEligibility";
 export { runProductStatsSync } from "./productStatsSync";

package/dist/_internal/server/jobs/core/index.js

@@ -20,6 +20,8 @@ export { runCleanupRtdbEvents } from "./cleanupRtdbEvents.js";
 export { runMediaTmpCleanup } from "./mediaTmpCleanup.js";
 export { runPendingOrderTimeout } from "./pendingOrderTimeout.js";
 export { runCountersReconcile } from "./countersReconcile.js";
+export { runPaymentReconcile, reconcileStuckGatewayEvents } from "./paymentReconcile.js";
+export { runObligationSweep } from "./obligationSweep.js";
 export { runBundleStockSync } from "./bundleStockSync.js";
 export { runAutoPayoutEligibility } from "./autoPayoutEligibility.js";
 export { runProductStatsSync } from "./productStatsSync.js";

package/dist/_internal/server/jobs/core/marketPriceRollup.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Core: the ASKING-price index — what a thing is currently going for, per leaf.
+ *
+ * ## Why this exists
+ *
+ * The price tool's market half was a single crawl, summarised to
+ * p25/median/p75 per GENERATION and frozen at one `asOf` date. Three things
+ * followed from that shape, none of which was fixable in the renderer:
+ *
+ *   · **Every model in an era showed the same number.** Dragoon MS and Strata
+ *     Dragoon MS are different beys with different markets, and both reported
+ *     ₹3,999 because both inherited the Hard Metal System band.
+ *   · **Whole eras showed nothing.** Engine Gear was never crawled, so Dragoon
+ *     G and Dranzer G — two of the better-known tops in the line — resolved to
+ *     no band at any ancestor and rendered an empty card.
+ *   · **Nothing could age.** One date for the entire dataset means a figure
+ *     measured last October reads exactly like one measured yesterday.
+ *
+ * This job replaces the summary with a derivation over dated rows, so the
+ * window is a parameter rather than a property of the data.
+ *
+ * ## 🛑 What it writes, and what it must never touch
+ *
+ * Writes `marketPriceIndex/{leafId}` ONLY. It does not write `categories`
+ * (Root Cause #92's self-triggering write, plus an ISR drop per row) and it
+ * does not write `priceIndex`, which is the SOLD half and belongs to
+ * `priceIndexRollup`. The seeded `CategoryPriceGuidance.market` band is left
+ * exactly as seeded and is outranked at read time, never overwritten — a bad
+ * import must not be able to erase the only evidence ~60 leaves have.
+ *
+ * ## 🛑 Enumerates LEAVES, not observations
+ *
+ * Root Cause #102: a reconciler that tallies from the events that exist rather
+ * than the entities that exist can only ever add, so a leaf whose last
+ * observation was retracted keeps a band forever. The leaf list is built first,
+ * and a leaf that no longer clears `MIN_BAND_OBSERVATIONS` has its band
+ * CLEARED rather than skipped.
+ *
+ * ## Why daily and never live
+ *
+ * Same answer as the sold half: a live index would scan observations per
+ * request, which is the unbounded-per-request pattern that paused this project
+ * on Hobby caps. One pre-computed read per row, with the window and the
+ * last-seen date travelling beside the figures.
+ *
+ * @tag domain:price-index
+ * @tag layer:job
+ * @tag pattern:rollup
+ * @tag access:server-only
+ * @tag consumers:scheduled.marketPriceRollup
+ * @tag sideEffects:writes marketPriceIndex
+ */
+import type { JobContext } from "../runtime/types";
+/**
+ * 🛑 Returns `void`, and the counts go to the LOG rather than to a caller.
+ *
+ * `ScheduleHandler` is `(ctx) => Promise<void>`, and matching it exactly is
+ * what lets `marketPriceRollupHandler` be a bare alias instead of a wrapper
+ * that discards a value — the same shape `priceIndexRollup` already has. A
+ * result object with no reader would also be speculative infrastructure: the
+ * only consumer today is an operator reading the run log, and
+ * `ctx.logger.info` is what they read.
+ */
+export declare function runMarketPriceRollup(ctx: JobContext): Promise<void>;

package/dist/_internal/server/jobs/core/marketPriceRollup.js

@@ -0,0 +1,153 @@
+/**
+ * Core: the ASKING-price index — what a thing is currently going for, per leaf.
+ *
+ * ## Why this exists
+ *
+ * The price tool's market half was a single crawl, summarised to
+ * p25/median/p75 per GENERATION and frozen at one `asOf` date. Three things
+ * followed from that shape, none of which was fixable in the renderer:
+ *
+ *   · **Every model in an era showed the same number.** Dragoon MS and Strata
+ *     Dragoon MS are different beys with different markets, and both reported
+ *     ₹3,999 because both inherited the Hard Metal System band.
+ *   · **Whole eras showed nothing.** Engine Gear was never crawled, so Dragoon
+ *     G and Dranzer G — two of the better-known tops in the line — resolved to
+ *     no band at any ancestor and rendered an empty card.
+ *   · **Nothing could age.** One date for the entire dataset means a figure
+ *     measured last October reads exactly like one measured yesterday.
+ *
+ * This job replaces the summary with a derivation over dated rows, so the
+ * window is a parameter rather than a property of the data.
+ *
+ * ## 🛑 What it writes, and what it must never touch
+ *
+ * Writes `marketPriceIndex/{leafId}` ONLY. It does not write `categories`
+ * (Root Cause #92's self-triggering write, plus an ISR drop per row) and it
+ * does not write `priceIndex`, which is the SOLD half and belongs to
+ * `priceIndexRollup`. The seeded `CategoryPriceGuidance.market` band is left
+ * exactly as seeded and is outranked at read time, never overwritten — a bad
+ * import must not be able to erase the only evidence ~60 leaves have.
+ *
+ * ## 🛑 Enumerates LEAVES, not observations
+ *
+ * Root Cause #102: a reconciler that tallies from the events that exist rather
+ * than the entities that exist can only ever add, so a leaf whose last
+ * observation was retracted keeps a band forever. The leaf list is built first,
+ * and a leaf that no longer clears `MIN_BAND_OBSERVATIONS` has its band
+ * CLEARED rather than skipped.
+ *
+ * ## Why daily and never live
+ *
+ * Same answer as the sold half: a live index would scan observations per
+ * request, which is the unbounded-per-request pattern that paused this project
+ * on Hobby caps. One pre-computed read per row, with the window and the
+ * last-seen date travelling beside the figures.
+ *
+ * @tag domain:price-index
+ * @tag layer:job
+ * @tag pattern:rollup
+ * @tag access:server-only
+ * @tag consumers:scheduled.marketPriceRollup
+ * @tag sideEffects:writes marketPriceIndex
+ */
+import { marketPriceIndexRepository, } from "../../../../features/categories/repository/market-price-index.repository.js";
+import { priceObservationRepository, } from "../../../../features/categories/repository/price-observation.repository.js";
+import { computeMarketStats, MIN_BAND_OBSERVATIONS, RECENT_WINDOW_DAYS, } from "../../../../features/price-index/market-stats.js";
+/**
+ * Firestore `Timestamp` | `Date` | ISO string -> `Date`.
+ *
+ * `mapDoc` hands back whatever the driver produced, and a `Timestamp` has no
+ * `getTime`. `computeMarketStats` filters on `instanceof Date`, so an
+ * unconverted value would be silently DROPPED from the sample set rather than
+ * throwing — a band quietly computed over fewer rows than it had.
+ */
+function toDate(v) {
+    if (v instanceof Date)
+        return Number.isNaN(v.getTime()) ? null : v;
+    if (typeof v === "string") {
+        const d = new Date(v);
+        return Number.isNaN(d.getTime()) ? null : d;
+    }
+    const t = v;
+    if (t && typeof t.toDate === "function") {
+        const d = t.toDate();
+        return Number.isNaN(d.getTime()) ? null : d;
+    }
+    return null;
+}
+/**
+ * 🛑 Ask and sale are grouped SEPARATELY, never pooled.
+ *
+ * `price-bands.md`'s governing rule — *"a sold-out row proves the item is
+ * GONE, not that it sold at that price"*, against 76–93% of crawled listings
+ * being sold out. Pooling them would produce a figure describing neither event,
+ * and the pooling would be undetectable afterwards because the result is a
+ * number either way.
+ */
+function groupByKind(rows) {
+    const out = new Map();
+    for (const row of rows) {
+        const seenAt = toDate(row.seenAt);
+        if (!seenAt)
+            continue;
+        if (!Number.isFinite(row.amount) || row.amount <= 0)
+            continue;
+        const kind = row.kind === "sale" ? "sale" : "ask";
+        const bucket = out.get(kind) ?? [];
+        bucket.push({ amount: row.amount, seenAt });
+        out.set(kind, bucket);
+    }
+    return out;
+}
+/**
+ * 🛑 Returns `void`, and the counts go to the LOG rather than to a caller.
+ *
+ * `ScheduleHandler` is `(ctx) => Promise<void>`, and matching it exactly is
+ * what lets `marketPriceRollupHandler` be a bare alias instead of a wrapper
+ * that discards a value — the same shape `priceIndexRollup` already has. A
+ * result object with no reader would also be speculative infrastructure: the
+ * only consumer today is an operator reading the run log, and
+ * `ctx.logger.info` is what they read.
+ */
+export async function runMarketPriceRollup(ctx) {
+    const now = new Date();
+    const leafIds = await priceObservationRepository.listLeafIdsWithObservations();
+    let written = 0;
+    let cleared = 0;
+    let counted = 0;
+    for (const leafId of leafIds) {
+        const rows = await priceObservationRepository.findForLeaf(leafId);
+        counted += rows.length;
+        const byKind = {};
+        for (const [kind, samples] of groupByKind(rows)) {
+            const stats = computeMarketStats(samples, now);
+            // `null` means the kind did not clear MIN_BAND_OBSERVATIONS. Omitted,
+            // never zeroed — a ₹0 band renders as a real price meaning "worthless".
+            if (!stats)
+                continue;
+            byKind[kind] = stats;
+        }
+        if (Object.keys(byKind).length === 0) {
+            /*
+             * 🛑 CLEARED, not skipped. This is the retraction path: a leaf whose
+             * observations were removed, or which dropped below the threshold, must
+             * stop publishing. Skipping would leave the last computed band standing
+             * on evidence that no longer exists — and it would look identical to a
+             * freshly computed one.
+             */
+            await marketPriceIndexRepository.clearForLeaf(leafId);
+            cleared += 1;
+            continue;
+        }
+        await marketPriceIndexRepository.setForLeaf(leafId, byKind);
+        written += 1;
+    }
+    ctx.logger.info("marketPriceRollup: complete", {
+        leavesScanned: leafIds.length,
+        leavesWritten: written,
+        leavesCleared: cleared,
+        observationsCounted: counted,
+        recentWindowDays: RECENT_WINDOW_DAYS,
+        minObservations: MIN_BAND_OBSERVATIONS,
+    });
+}

package/dist/_internal/server/jobs/core/obligationSweep.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `obligationSweep` — one job for every deadline in the order lifecycle.
+ *
+ * ## The shape, and why it is one query
+ *
+ * Open obligations past due, oldest first, bounded. For each: **re-read the
+ * subject**, re-evaluate the policy's `precondition`, check `blockedBy`, then
+ * either act or open a case.
+ *
+ * 🛑 THE RE-READ IS THE DESIGN. `obligations` is a due-date index, not truth.
+ * A row saying "cancel this at 15:00" is a hint; the order saying "I was paid
+ * at 14:58" is the fact, and the fact wins — the row closes `superseded` and
+ * nothing happens. Without that step this collection would be a stored mirror
+ * of derived state, which is Root Cause #42's shape and would eventually
+ * cancel a paid order.
+ *
+ * ## Scheduler cost: it goes DOWN
+ *
+ * One new job at every 5 minutes. Three existing jobs —
+ * `paymentWindowTimeout`, `pendingOrderTimeout` and `paymentReviewAutoApprove`
+ * — are superseded by policy rows and are retired in Phase 8, so the registered
+ * count goes **28 → 29 → 27** while roughly twenty scenarios gain coverage.
+ * Scheduler bills per registered job, so that is a real saving, not a wash.
+ *
+ * One query per tick, empty when idle; about a dozen writes per order lifetime.
+ */
+import type { JobContext } from "../runtime/types";
+export interface ObligationSweepResult {
+    due: number;
+    acted: number;
+    escalated: number;
+    superseded: number;
+    blocked: number;
+    failed: number;
+}
+export declare function runObligationSweep(ctx: JobContext): Promise<ObligationSweepResult>;