@mohasinac/appkit 4.62.0 → 4.63.0

package/dist/features/inventory/schemas/stock-reservation.d.ts

@@ -0,0 +1,114 @@
+/**
+ * A HOLD on stock that is not yet an order.
+ *
+ * ## 🛑 Why this has to exist before S5b (Part 6)
+ *
+ * The plan calls this "the largest hidden cost" of the shared-purchase work,
+ * and the reason is that today there is no way to hold stock at all. The only
+ * mechanism is: `onOrderCreate` decrements `availableQuantity`, and
+ * `pendingOrderTimeout` puts it back if the buyer does not pay inside the
+ * 15-minute window. Both are keyed to an ORDER.
+ *
+ * A shared purchase runs for DAYS while co-buyers pay. With no primitive,
+ * either the coordinator places an order up front — which starts a 15-minute
+ * payment clock on a multi-day agreement — or nothing is held, and the item is
+ * sold out from under the arrangement by an ordinary buyer who happened to
+ * check out first. Neither is a product.
+ *
+ * ## The invariant, and where it already lives
+ *
+ * `products.repository.ts` already states it:
+ *
+ *     reserved = stockQuantity - availableQuantity
+ *
+ * …as the comment on `resolveStockResync` puts it, *"the difference between
+ * the two IS the outstanding reservation"*. This collection does not invent a
+ * new idea; it makes that difference ADDRESSABLE — every held unit gets a row
+ * saying who holds it and until when, instead of being an anonymous gap
+ * between two numbers that only an order can close.
+ *
+ * 🛑 So a reservation MUST move `availableQuantity` in the same transaction
+ * that writes its row. A row without the decrement holds nothing; a decrement
+ * without a row is the anonymous gap again, and nothing can expire it.
+ *
+ * ## Why a TTL rather than a cancel button
+ *
+ * A hold with no expiry is a leak: the holder closes the tab, and those units
+ * are off the shelf until a human notices. `expiresAt` means the worst case is
+ * bounded by the sweep interval, and the seller never has to ask anyone to
+ * release anything.
+ */
+import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+export declare const STOCK_RESERVATION_COLLECTION = "stockReservations";
+/**
+ * Who is holding, and therefore what releases it.
+ *
+ * 🛑 A plain `holderId: string` was the first draft and it is wrong: the sweep
+ * and the release path both need to know WHICH system owns the hold before
+ * they can decide whether it is still legitimate. A discriminator makes
+ * "release every hold belonging to arrangement X" expressible; an opaque id
+ * makes it a string-prefix convention nobody enforces.
+ */
+export declare const RESERVATION_HOLDER_KINDS: readonly ["shared-purchase", "manual"];
+export type ReservationHolderKind = (typeof RESERVATION_HOLDER_KINDS)[number];
+/**
+ * 🛑 `cart` and `order` are deliberately NOT holder kinds.
+ *
+ * A cart holds nothing today — adding an item does not decrement anything —
+ * and making it hold would silently turn every abandoned cart into held
+ * stock. An order already has its own hold through `onOrderCreate` +
+ * `pendingOrderTimeout`; a second mechanism over the same units would
+ * double-decrement, which is exactly the class of bug `resolveStockResync`'s
+ * delta exists to prevent. Add a kind only when the thing that owns it also
+ * owns its release.
+ */
+export declare const RESERVATION_STATUSES: readonly ["held", "consumed", "released", "expired"];
+export type ReservationStatus = (typeof RESERVATION_STATUSES)[number];
+export interface StockReservationDocument extends BaseDocument {
+    productId: string;
+    /** Denormalised so the sweep can restore stock without reading the product first. */
+    quantity: number;
+    holderKind: ReservationHolderKind;
+    /** The arrangement / manual-hold id. Scoped by `holderKind`, never globally unique. */
+    holderId: string;
+    /** Who asked for it — an Auth uid, for the audit trail and for admin release. */
+    createdBy: string;
+    status: ReservationStatus;
+    /**
+     * 🛑 The whole point. A hold with no expiry is a leak: the holder closes the
+     * tab and the units are gone until a human notices.
+     */
+    expiresAt: Date;
+    /**
+     * Set when the hold ENDS, whichever way it ended. One field rather than
+     * three (`consumedAt`/`releasedAt`/`expiredAt`) because `status` already
+     * says which, and three nullable dates is three chances for the one that
+     * matters to be the one nobody set.
+     */
+    endedAt?: Date;
+    /** Free text on a manual release — why an admin took the hold back. */
+    endedReason?: string;
+}
+/** Default hold, when a caller names none. */
+export declare const RESERVATION_DEFAULT_TTL_HOURS = 72;
+/**
+ * 🛑 A ceiling, and it is load-bearing rather than defensive.
+ *
+ * A caller may pass any TTL it likes, which makes "hold this for a year" one
+ * typo away — and a year-long hold is indistinguishable from permanently
+ * deleted stock, because nothing in the UI shows a seller why their own
+ * product is unbuyable. 30 days is longer than any agreement window Part 6
+ * contemplates and short enough that a mistake self-heals.
+ */
+export declare const RESERVATION_MAX_TTL_HOURS: number;
+/** A reservation is only holding stock while it is `held` and unexpired. */
+export declare function isReservationActive(reservation: Pick<StockReservationDocument, "status" | "expiresAt">, now?: Date): boolean;
+/**
+ * Firestore hands back a `Timestamp`, a `Date` or an ISO string depending on
+ * the path a document took to get here, and the adapter that normalises those
+ * is not reachable from this file. Returning `null` on anything unparseable is
+ * the honest answer — and callers treat an unparseable expiry as NOT active,
+ * so the failure mode is a hold released early rather than one held forever.
+ */
+declare function toDate(value: unknown): Date | null;
+export { toDate as reservationExpiryDate };

package/dist/features/inventory/schemas/stock-reservation.js

@@ -0,0 +1,103 @@
+/**
+ * A HOLD on stock that is not yet an order.
+ *
+ * ## 🛑 Why this has to exist before S5b (Part 6)
+ *
+ * The plan calls this "the largest hidden cost" of the shared-purchase work,
+ * and the reason is that today there is no way to hold stock at all. The only
+ * mechanism is: `onOrderCreate` decrements `availableQuantity`, and
+ * `pendingOrderTimeout` puts it back if the buyer does not pay inside the
+ * 15-minute window. Both are keyed to an ORDER.
+ *
+ * A shared purchase runs for DAYS while co-buyers pay. With no primitive,
+ * either the coordinator places an order up front — which starts a 15-minute
+ * payment clock on a multi-day agreement — or nothing is held, and the item is
+ * sold out from under the arrangement by an ordinary buyer who happened to
+ * check out first. Neither is a product.
+ *
+ * ## The invariant, and where it already lives
+ *
+ * `products.repository.ts` already states it:
+ *
+ *     reserved = stockQuantity - availableQuantity
+ *
+ * …as the comment on `resolveStockResync` puts it, *"the difference between
+ * the two IS the outstanding reservation"*. This collection does not invent a
+ * new idea; it makes that difference ADDRESSABLE — every held unit gets a row
+ * saying who holds it and until when, instead of being an anonymous gap
+ * between two numbers that only an order can close.
+ *
+ * 🛑 So a reservation MUST move `availableQuantity` in the same transaction
+ * that writes its row. A row without the decrement holds nothing; a decrement
+ * without a row is the anonymous gap again, and nothing can expire it.
+ *
+ * ## Why a TTL rather than a cancel button
+ *
+ * A hold with no expiry is a leak: the holder closes the tab, and those units
+ * are off the shelf until a human notices. `expiresAt` means the worst case is
+ * bounded by the sweep interval, and the seller never has to ask anyone to
+ * release anything.
+ */
+export const STOCK_RESERVATION_COLLECTION = "stockReservations";
+/**
+ * Who is holding, and therefore what releases it.
+ *
+ * 🛑 A plain `holderId: string` was the first draft and it is wrong: the sweep
+ * and the release path both need to know WHICH system owns the hold before
+ * they can decide whether it is still legitimate. A discriminator makes
+ * "release every hold belonging to arrangement X" expressible; an opaque id
+ * makes it a string-prefix convention nobody enforces.
+ */
+export const RESERVATION_HOLDER_KINDS = ["shared-purchase", "manual"];
+/**
+ * 🛑 `cart` and `order` are deliberately NOT holder kinds.
+ *
+ * A cart holds nothing today — adding an item does not decrement anything —
+ * and making it hold would silently turn every abandoned cart into held
+ * stock. An order already has its own hold through `onOrderCreate` +
+ * `pendingOrderTimeout`; a second mechanism over the same units would
+ * double-decrement, which is exactly the class of bug `resolveStockResync`'s
+ * delta exists to prevent. Add a kind only when the thing that owns it also
+ * owns its release.
+ */
+export const RESERVATION_STATUSES = ["held", "consumed", "released", "expired"];
+/** Default hold, when a caller names none. */
+export const RESERVATION_DEFAULT_TTL_HOURS = 72;
+/**
+ * 🛑 A ceiling, and it is load-bearing rather than defensive.
+ *
+ * A caller may pass any TTL it likes, which makes "hold this for a year" one
+ * typo away — and a year-long hold is indistinguishable from permanently
+ * deleted stock, because nothing in the UI shows a seller why their own
+ * product is unbuyable. 30 days is longer than any agreement window Part 6
+ * contemplates and short enough that a mistake self-heals.
+ */
+export const RESERVATION_MAX_TTL_HOURS = 24 * 30;
+/** A reservation is only holding stock while it is `held` and unexpired. */
+export function isReservationActive(reservation, now = new Date()) {
+    if (reservation.status !== "held")
+        return false;
+    const expires = toDate(reservation.expiresAt);
+    return expires !== null && expires.getTime() > now.getTime();
+}
+/**
+ * Firestore hands back a `Timestamp`, a `Date` or an ISO string depending on
+ * the path a document took to get here, and the adapter that normalises those
+ * is not reachable from this file. Returning `null` on anything unparseable is
+ * the honest answer — and callers treat an unparseable expiry as NOT active,
+ * so the failure mode is a hold released early rather than one held forever.
+ */
+function toDate(value) {
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? null : value;
+    if (value && typeof value.toDate === "function") {
+        const d = value.toDate();
+        return d instanceof Date && !Number.isNaN(d.getTime()) ? d : null;
+    }
+    if (typeof value === "string" || typeof value === "number") {
+        const d = new Date(value);
+        return Number.isNaN(d.getTime()) ? null : d;
+    }
+    return null;
+}
+export { toDate as reservationExpiryDate };

package/dist/features/invoicing/schemas/firestore.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Invoicing — the two gapless series (Phase 7, D12)
+ *
+ * ## Why two series and not one field
+ *
+ * **A GST invoice is issued once and must not change.** So a partial
+ * cancellation or refund gets a CREDIT NOTE with its own number referencing
+ * the invoice it adjusts — never a re-issued invoice. That is the whole reason
+ * `creditNoteNumber` is a second series rather than a revision suffix.
+ *
+ * ## 🛑 Gapless means the counter CANNOT be sharded
+ *
+ * Firestore's ~1 write/sec/document ceiling applies to a counter doc, and the
+ * usual answer is to shard it. That answer is unavailable here: a sharded
+ * counter cannot be gapless, which is the entire requirement. At this volume
+ * the ceiling is irrelevant; the note exists so nobody "optimises" it later
+ * and silently breaks the one property an auditor checks.
+ *
+ * ## 🛑 The FINANCIAL YEAR is the riskiest line in the phase
+ *
+ * The series is `LIR/26-27/0001` (decision 21), resetting on 1 April. So the
+ * allocating transaction must key on the FY — if it keys on anything else, two
+ * years share one counter and NEITHER series is gapless. And a number cannot
+ * be withdrawn without leaving a gap, so this is not a mistake that can be
+ * corrected after the fact.
+ */
+/**
+ * ## 🛑 OUTSTANDING — both collections need a PRESERVE entry in the tester tier
+ *
+ * `invoiceCounters` and `invoiceAllocations` are in **no tier**, and
+ * `assertDeletable` THROWS on an unlisted collection name *mid-run* — which
+ * reads as a harness fault rather than a classification gap. That is the exact
+ * latent trip `gatewayOrderClaims` sat on, and these two are worse: a wiped
+ * counter would restart a series at 1 and re-issue numbers that already exist
+ * on real invoices, which is unrecoverable.
+ *
+ * The entry belongs in `tester/scripts/lib/collections.mjs`'s PRESERVE list,
+ * beside `payoutMethods` and `adminAuditLog`. It is not in this change because
+ * **the `tester` submodule is not initialised in this worktree** (`git
+ * submodule status` shows it uninitialised), so the file does not exist here to
+ * edit. Recorded rather than silently skipped.
+ *
+ * 🛑 And they must get **no `SEED_COLLECTION_PURPOSE` entry**:
+ * `audit-seed-purpose` R1 requires that registry to match `COLLECTION_MAP` in
+ * BOTH directions, so a key for a collection the seeder does not write is a
+ * DEAD entry and fails the audit. Neither of these is ever seeded — they are
+ * written only by allocation. The same mistake was made with `refundClaims`
+ * and reverted.
+ */
+import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+export declare const INVOICE_COUNTER_COLLECTION = "invoiceCounters";
+/** The two independent series. */
+export type InvoiceSeriesKind = "invoice" | "credit_note";
+/**
+ * One counter per (series, financial year).
+ *
+ * The document id IS `${kind}_${fy}` — e.g. `invoice_26-27` — so the
+ * transaction that allocates a number needs no query, and two series in the
+ * same year cannot contend with each other.
+ */
+export interface InvoiceCounterDocument extends BaseDocument {
+    kind: InvoiceSeriesKind;
+    /** `"26-27"` — the FY label that appears in the number itself. */
+    fy: string;
+    /**
+     * The last number ISSUED. The next allocation is `lastNumber + 1`.
+     *
+     * 🛑 Last-issued rather than next-to-issue, deliberately: a counter created
+     * at 0 means "nothing issued yet", which is true and self-evident, whereas a
+     * next-to-issue counter created at 0 would mint `LIR/26-27/0000`.
+     */
+    lastNumber: number;
+    /** When this counter last allocated — for the operator, never read by code. */
+    lastIssuedAt?: Date;
+}
+/**
+ * A record of every number allocated, keyed on what it was allocated FOR.
+ *
+ * ## 🛑 This is the idempotency claim, and it is why a number cannot be issued
+ * twice for one order
+ *
+ * `onOrderStatusChange` can fire more than once, and **two numbers for one
+ * order is the single unrecoverable failure in this phase** — the spare number
+ * is a permanent gap that cannot be explained to an auditor and cannot be
+ * reclaimed.
+ *
+ * So allocation is a `.create()` on `invoiceAllocations/{subjectId}` INSIDE
+ * the same transaction that bumps the counter. `.create()` fails if the
+ * document exists, which makes "already allocated" a transaction-level fact
+ * rather than a read-then-write race. It is the same primitive the refund
+ * claim, the gateway-event inbox and the gateway-order claim all use.
+ */
+export declare const INVOICE_ALLOCATION_COLLECTION = "invoiceAllocations";
+export interface InvoiceAllocationDocument extends BaseDocument {
+    kind: InvoiceSeriesKind;
+    /**
+     * What this number was issued for.
+     *
+     * 🛑 For an invoice this is the ORDER id, so one order can only ever hold
+     * one invoice number. For a credit note it is `${orderId}_${refundId}`,
+     * because an order can legitimately have several credit notes — one per
+     * refund event — and keying a credit note on the order alone would refuse
+     * the second one.
+     */
+    subjectId: string;
+    orderId: string;
+    /** The formatted number, e.g. `LIR/26-27/0001`. */
+    number: string;
+    fy: string;
+    sequence: number;
+    issuedAt: Date;
+}

package/dist/features/invoicing/schemas/firestore.js

@@ -0,0 +1,45 @@
+/**
+ * Invoicing — the two gapless series (Phase 7, D12)
+ *
+ * ## Why two series and not one field
+ *
+ * **A GST invoice is issued once and must not change.** So a partial
+ * cancellation or refund gets a CREDIT NOTE with its own number referencing
+ * the invoice it adjusts — never a re-issued invoice. That is the whole reason
+ * `creditNoteNumber` is a second series rather than a revision suffix.
+ *
+ * ## 🛑 Gapless means the counter CANNOT be sharded
+ *
+ * Firestore's ~1 write/sec/document ceiling applies to a counter doc, and the
+ * usual answer is to shard it. That answer is unavailable here: a sharded
+ * counter cannot be gapless, which is the entire requirement. At this volume
+ * the ceiling is irrelevant; the note exists so nobody "optimises" it later
+ * and silently breaks the one property an auditor checks.
+ *
+ * ## 🛑 The FINANCIAL YEAR is the riskiest line in the phase
+ *
+ * The series is `LIR/26-27/0001` (decision 21), resetting on 1 April. So the
+ * allocating transaction must key on the FY — if it keys on anything else, two
+ * years share one counter and NEITHER series is gapless. And a number cannot
+ * be withdrawn without leaving a gap, so this is not a mistake that can be
+ * corrected after the fact.
+ */
+export const INVOICE_COUNTER_COLLECTION = "invoiceCounters";
+/**
+ * A record of every number allocated, keyed on what it was allocated FOR.
+ *
+ * ## 🛑 This is the idempotency claim, and it is why a number cannot be issued
+ * twice for one order
+ *
+ * `onOrderStatusChange` can fire more than once, and **two numbers for one
+ * order is the single unrecoverable failure in this phase** — the spare number
+ * is a permanent gap that cannot be explained to an auditor and cannot be
+ * reclaimed.
+ *
+ * So allocation is a `.create()` on `invoiceAllocations/{subjectId}` INSIDE
+ * the same transaction that bumps the counter. `.create()` fails if the
+ * document exists, which makes "already allocated" a transaction-level fact
+ * rather than a read-then-write race. It is the same primitive the refund
+ * claim, the gateway-event inbox and the gateway-order claim all use.
+ */
+export const INVOICE_ALLOCATION_COLLECTION = "invoiceAllocations";

package/dist/features/invoicing/utils/financial-year.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The Indian financial year, and the series format built on it.
+ *
+ * ## 🛑 1 April, and getting the boundary wrong is unrecoverable
+ *
+ * The FY segment is what makes the reset safe: a counter keyed on the year
+ * resets by construction, because 1 April produces a new key. But it also
+ * means a boundary error is permanent — a number issued under the wrong FY
+ * leaves a gap in one year's series and an extra in the other, and a number
+ * cannot be withdrawn.
+ *
+ * So the month test is `>= 3` on a ZERO-BASED month (April is 3, not 4). That
+ * single off-by-one is the whole risk, and it is why this is a named function
+ * with its reasoning attached rather than an inline expression at the call
+ * site.
+ */
+/**
+ * `"26-27"` for any date from 2026-04-01 to 2027-03-31.
+ *
+ * Two-digit years, matching decision 21's `LIR/26-27/0001`. The full number is
+ * 14 characters, inside the statutory 16, and uses only `-` and `/` as
+ * separators.
+ */
+export declare function financialYearLabel(at: Date): string;
+/**
+ * Prefixes, per decision 21.
+ *
+ * 🛑 Distinct prefixes rather than one with a suffix, so the two series are
+ * distinguishable at a glance in a bank statement, a spreadsheet and a GSTR-1
+ * row — and so a text search for one can never match the other.
+ */
+export declare const INVOICE_PREFIX = "LIR";
+export declare const CREDIT_NOTE_PREFIX = "LIRCN";
+/**
+ * `LIR/26-27/0001`.
+ *
+ * Zero-padded to four digits, which covers 9,999 documents per series per
+ * year. 🛑 Overflow does NOT wrap or throw: `padStart` is a floor, not a
+ * ceiling, so number 10,000 renders as `10000` and the series stays gapless
+ * and sortable-by-sequence. Width is cosmetic; gaplessness is not, and the
+ * failure mode of a throw here would be a paid order that cannot be invoiced.
+ */
+export declare function formatSeriesNumber(prefix: string, fy: string, sequence: number): string;

package/dist/features/invoicing/utils/financial-year.js

@@ -0,0 +1,53 @@
+/**
+ * The Indian financial year, and the series format built on it.
+ *
+ * ## 🛑 1 April, and getting the boundary wrong is unrecoverable
+ *
+ * The FY segment is what makes the reset safe: a counter keyed on the year
+ * resets by construction, because 1 April produces a new key. But it also
+ * means a boundary error is permanent — a number issued under the wrong FY
+ * leaves a gap in one year's series and an extra in the other, and a number
+ * cannot be withdrawn.
+ *
+ * So the month test is `>= 3` on a ZERO-BASED month (April is 3, not 4). That
+ * single off-by-one is the whole risk, and it is why this is a named function
+ * with its reasoning attached rather than an inline expression at the call
+ * site.
+ */
+/**
+ * `"26-27"` for any date from 2026-04-01 to 2027-03-31.
+ *
+ * Two-digit years, matching decision 21's `LIR/26-27/0001`. The full number is
+ * 14 characters, inside the statutory 16, and uses only `-` and `/` as
+ * separators.
+ */
+export function financialYearLabel(at) {
+    const year = at.getFullYear();
+    // 🛑 ZERO-BASED. `getMonth()` returns 3 for April, so `>= 3` is "April or
+    // later" and `< 3` is "January to March", which belongs to the FY that
+    // STARTED in the previous calendar year.
+    const startYear = at.getMonth() >= 3 ? year : year - 1;
+    const endYear = startYear + 1;
+    return `${String(startYear % 100).padStart(2, "0")}-${String(endYear % 100).padStart(2, "0")}`;
+}
+/**
+ * Prefixes, per decision 21.
+ *
+ * 🛑 Distinct prefixes rather than one with a suffix, so the two series are
+ * distinguishable at a glance in a bank statement, a spreadsheet and a GSTR-1
+ * row — and so a text search for one can never match the other.
+ */
+export const INVOICE_PREFIX = "LIR";
+export const CREDIT_NOTE_PREFIX = "LIRCN";
+/**
+ * `LIR/26-27/0001`.
+ *
+ * Zero-padded to four digits, which covers 9,999 documents per series per
+ * year. 🛑 Overflow does NOT wrap or throw: `padStart` is a floor, not a
+ * ceiling, so number 10,000 renders as `10000` and the series stays gapless
+ * and sortable-by-sequence. Width is cosmetic; gaplessness is not, and the
+ * failure mode of a throw here would be a paid order that cannot be invoiced.
+ */
+export function formatSeriesNumber(prefix, fy, sequence) {
+    return `${prefix}/${fy}/${String(sequence).padStart(4, "0")}`;
+}

package/dist/features/jobs/actions/enqueue-job.js

@@ -15,7 +15,7 @@
 import { normalizeError } from "../../../errors/normalize.js";
 import { serverLogger } from "../../../monitoring/index.js";
 import { jobsRepository } from "../../../repositories/index.js";
-import { JobStatusValues } from "../schemas/firestore.js";
+import { JOB_MAX_ATTEMPTS, JobStatusValues } from "../schemas/firestore.js";
 import { getAdminAuth, getAdminRealtimeDb } from "../../../providers/db-firebase/index.js";
 import { RTDB_PATHS } from "../../../providers/db-firebase/rtdb-paths.js";
 export async function enqueueJob(input) {
@@ -24,6 +24,23 @@ export async function enqueueJob(input) {
         status: JobStatusValues.PENDING,
         payload: input.payload,
         requestedBy: input.requestedBy,
+        /*
+         * Phase 8 — attempt 1 of N, stated rather than implied.
+         *
+         * `attempt` defaults to 1 everywhere it is read, so this write is not
+         * strictly required — but an explicit 1 is what makes an ENQUEUED job
+         * distinguishable from a pre-Phase-8 row at a glance, and it is what a
+         * reader of the collection needs when three documents share a
+         * `parentJobId`.
+         *
+         * 🛑 `nextAttemptAt` is deliberately ABSENT. It is the retry sweep's query
+         * field, and the create trigger skips any job carrying a future one — so
+         * setting it here (even to `now`) would put every first attempt at the
+         * mercy of a 5-minute sweep instead of running immediately, turning a
+         * synchronous-feeling admin action into one that appears to hang.
+         */
+        attempt: 1,
+        maxAttempts: JOB_MAX_ATTEMPTS,
     });
     try {
         await getAdminRealtimeDb()

package/dist/features/jobs/repository/jobs.repository.d.ts

@@ -13,8 +13,69 @@ export declare class JobsRepository extends BaseRepository<JobDocument> {
     markDone(id: string, result: JobResult): Promise<JobDocument>;
     markFailed(id: string, error: string): Promise<JobDocument>;
     /**
-     * Refs for finished (done/failed) jobs older than `ttlDays` — used by the
+     * Attempts exhausted, or a permanent failure. The dead-letter state
+     * (Phase 8).
+     *
+     * 🛑 Distinct from `markFailed`, which now means "this attempt failed and a
+     * retry is scheduled". Before Phase 8 there was only `failed`, and it was
+     * terminal with no signal — so a job that gave up looked exactly like a job
+     * that had just failed once, and nothing anywhere distinguished them.
+     */
+    markDead(id: string, error: string): Promise<JobDocument>;
+    /**
+     * Schedule the next attempt as a NEW document (Phase 8).
+     *
+     * ## 🛑 Why a new document and not a reset of this one
+     *
+     * `onJobCreated` fires on CREATE. Flipping a job back to `pending` would
+     * never wake the trigger, so it would sit `pending` forever looking
+     * scheduled — a stall that reads as a queue. A fresh document is what makes
+     * the retry visible to the only mechanism that can run it.
+     *
+     * It also keeps the history: three attempts are three documents, each with
+     * its own error, so a repeating failure is legible instead of being
+     * overwritten by the last one.
+     *
+     * `parentJobId` points at the ORIGINAL — `parentJobId ?? id`, so attempt 3
+     * is linked to attempt 1 rather than to attempt 2. A flat fan means "every
+     * attempt of this job" is one equality query, where a linked list needs N
+     * reads to walk.
+     */
+    createRetry(id: string, job: JobDocument, next: {
+        attempt: number;
+        maxAttempts: number;
+        nextAttemptAt: Date;
+    }): Promise<string>;
+    /**
+     * Retries whose `nextAttemptAt` has passed — the sweep's only query.
+     *
+     * 🛑 `status == pending` AND `nextAttemptAt <= now`, so it can never pick up
+     * a FIRST attempt: an original job carries no `nextAttemptAt`, and a
+     * Firestore inequality excludes every document that lacks the field. That
+     * exclusion is usually the trap (see `.where("isTestData","!=",true)` in
+     * CLAUDE.md, and D26's `orderBy` on an optional field); here it is exactly
+     * the filter wanted, and it is written down so nobody "fixes" it by adding
+     * a default.
+     *
+     * Bounded at 20 per tick. The sweep rides `paymentWindowTimeout`, which runs
+     * every 5 minutes, so that is 240 retries an hour — far above any real
+     * backlog, and low enough that a pathological queue cannot exhaust the
+     * function's own budget in one pass.
+     */
+    getDueRetries(limit?: number): Promise<Array<{
+        id: string;
+        data: JobDocument;
+    }>>;
+    /**
+     * Refs for finished jobs older than `ttlDays` — used by the
      * `cleanupRtdbEvents` sweep to prune the `jobs` collection.
+     *
+     * 🛑 `DEAD` is deliberately NOT in this list. A dead job has an open
+     * `dead_job` case pointing at it, and the job document holds the payload
+     * that would let someone re-run the work by hand — pruning it would leave a
+     * case referencing nothing, which is worse than a stale row. They are
+     * retained until a human resolves the case and can be pruned by a separate,
+     * case-aware sweep if they ever accumulate.
      */
     getStaleFinishedRefs(ttlDays?: number): Promise<DocumentReference[]>;
 }

package/dist/features/jobs/repository/jobs.repository.js

@@ -31,8 +31,91 @@ export class JobsRepository extends BaseRepository {
         });
     }
     /**
-     * Refs for finished (done/failed) jobs older than `ttlDays` — used by the
+     * Attempts exhausted, or a permanent failure. The dead-letter state
+     * (Phase 8).
+     *
+     * 🛑 Distinct from `markFailed`, which now means "this attempt failed and a
+     * retry is scheduled". Before Phase 8 there was only `failed`, and it was
+     * terminal with no signal — so a job that gave up looked exactly like a job
+     * that had just failed once, and nothing anywhere distinguished them.
+     */
+    markDead(id, error) {
+        return this.update(id, {
+            status: JobStatusValues.DEAD,
+            error,
+            finishedAt: new Date(),
+        });
+    }
+    /**
+     * Schedule the next attempt as a NEW document (Phase 8).
+     *
+     * ## 🛑 Why a new document and not a reset of this one
+     *
+     * `onJobCreated` fires on CREATE. Flipping a job back to `pending` would
+     * never wake the trigger, so it would sit `pending` forever looking
+     * scheduled — a stall that reads as a queue. A fresh document is what makes
+     * the retry visible to the only mechanism that can run it.
+     *
+     * It also keeps the history: three attempts are three documents, each with
+     * its own error, so a repeating failure is legible instead of being
+     * overwritten by the last one.
+     *
+     * `parentJobId` points at the ORIGINAL — `parentJobId ?? id`, so attempt 3
+     * is linked to attempt 1 rather than to attempt 2. A flat fan means "every
+     * attempt of this job" is one equality query, where a linked list needs N
+     * reads to walk.
+     */
+    async createRetry(id, job, next) {
+        const created = await this.create({
+            jobType: job.jobType,
+            status: JobStatusValues.PENDING,
+            payload: job.payload,
+            requestedBy: job.requestedBy,
+            attempt: next.attempt,
+            maxAttempts: next.maxAttempts,
+            nextAttemptAt: next.nextAttemptAt,
+            parentJobId: job.parentJobId ?? id,
+            lastError: job.error,
+        });
+        return created.id;
+    }
+    /**
+     * Retries whose `nextAttemptAt` has passed — the sweep's only query.
+     *
+     * 🛑 `status == pending` AND `nextAttemptAt <= now`, so it can never pick up
+     * a FIRST attempt: an original job carries no `nextAttemptAt`, and a
+     * Firestore inequality excludes every document that lacks the field. That
+     * exclusion is usually the trap (see `.where("isTestData","!=",true)` in
+     * CLAUDE.md, and D26's `orderBy` on an optional field); here it is exactly
+     * the filter wanted, and it is written down so nobody "fixes" it by adding
+     * a default.
+     *
+     * Bounded at 20 per tick. The sweep rides `paymentWindowTimeout`, which runs
+     * every 5 minutes, so that is 240 retries an hour — far above any real
+     * backlog, and low enough that a pathological queue cannot exhaust the
+     * function's own budget in one pass.
+     */
+    async getDueRetries(limit = 20) {
+        const snap = await this.getCollection()
+            .where(JOB_FIELDS.STATUS, "==", JobStatusValues.PENDING)
+            .where(JOB_FIELDS.NEXT_ATTEMPT_AT, "<=", new Date())
+            .limit(limit)
+            .get();
+        return snap.docs.map((d) => ({
+            id: d.id,
+            data: { id: d.id, ...d.data() },
+        }));
+    }
+    /**
+     * Refs for finished jobs older than `ttlDays` — used by the
      * `cleanupRtdbEvents` sweep to prune the `jobs` collection.
+     *
+     * 🛑 `DEAD` is deliberately NOT in this list. A dead job has an open
+     * `dead_job` case pointing at it, and the job document holds the payload
+     * that would let someone re-run the work by hand — pruning it would leave a
+     * case referencing nothing, which is worse than a stale row. They are
+     * retained until a human resolves the case and can be pruned by a separate,
+     * case-aware sweep if they ever accumulate.
      */
     async getStaleFinishedRefs(ttlDays = 30) {
         const cutoff = new Date();