@mohasinac/appkit 4.62.0 → 4.62.1

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();

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

@@ -23,6 +23,20 @@ export declare const JobStatusValues: {
     readonly PROCESSING: "processing";
     readonly DONE: "done";
     readonly FAILED: "failed";
+    /**
+     * Phase 8 — attempts exhausted. The dead-letter state.
+     *
+     * 🛑 `failed` and `dead` are DIFFERENT facts and conflating them is what
+     * made a failed job terminal with no signal. `failed` now means "this
+     * attempt failed, and a retry is scheduled or the failure was permanent";
+     * `dead` means "we have stopped trying" and is the only one that opens a
+     * case.
+     *
+     * A reader that treats every non-`done` as hopeless loses that distinction —
+     * which is why the retention sweep excludes `dead` while an open case
+     * references it: the row is the evidence.
+     */
+    readonly DEAD: "dead";
 };
 export type JobStatus = (typeof JobStatusValues)[keyof typeof JobStatusValues];
 export interface JobResult {
@@ -52,7 +66,55 @@ export interface JobDocument extends BaseDocument {
     error?: string;
     startedAt?: Date;
     finishedAt?: Date;
+    /**
+     * 1-based. Absent means 1 — every job written before this field is a first
+     * attempt, which is both true and what every reader should assume.
+     */
+    attempt?: number;
+    /** Defaults to `JOB_MAX_ATTEMPTS`; a jobType may lower it. */
+    maxAttempts?: number;
+    /**
+     * When a retry becomes eligible.
+     *
+     * 🛑 A retry is a **NEW DOCUMENT**, not a mutation of this one, because
+     * `onJobCreated` fires on CREATE — re-running a job by flipping its status
+     * back to `pending` would never wake the trigger, and the job would sit
+     * `pending` forever looking scheduled. So this field lives on the NEW
+     * document and a sweep is what moves it from scheduled to running.
+     */
+    nextAttemptAt?: Date;
+    /**
+     * The document this is a retry OF — present on every attempt after the
+     * first, and absent on the original.
+     *
+     * 🛑 Points at the ORIGINAL, not at the immediately previous attempt. A
+     * flat chain means "show me every attempt of this job" is one equality
+     * query, where a linked list would need N reads to walk; and the question
+     * anyone actually asks is "did this job eventually work", which is about the
+     * original.
+     */
+    parentJobId?: string;
+    /** Why this attempt failed, kept per attempt so a pattern is visible. */
+    lastError?: string;
 }
+/**
+ * Attempts before a job is declared dead.
+ *
+ * Three, with `JOB_BACKOFF_MS` below: a transient fault usually clears in
+ * minutes, and a fourth attempt an hour later is far more likely to be the
+ * same permanent fault again than a different outcome.
+ */
+export declare const JOB_MAX_ATTEMPTS = 3;
+/**
+ * Delay before attempt 2 and attempt 3.
+ *
+ * 🛑 Indexed by `attempt - 1`, so the array length must be at least
+ * `JOB_MAX_ATTEMPTS - 1`. The last value is reused if it is shorter, rather
+ * than producing `undefined` — a `nextAttemptAt` of `Invalid Date` would make
+ * the sweep's `<= now` comparison false forever and the retry would never run,
+ * which is the silent-stall shape this whole phase exists to remove.
+ */
+export declare const JOB_BACKOFF_MS: readonly [number, number];
 export declare const JOB_FIELDS: {
     readonly JOB_TYPE: "jobType";
     readonly STATUS: "status";
@@ -63,10 +125,28 @@ export declare const JOB_FIELDS: {
     readonly FINISHED_AT: "finishedAt";
     readonly CREATED_AT: "createdAt";
     readonly UPDATED_AT: "updatedAt";
+    readonly ATTEMPT: "attempt";
+    readonly MAX_ATTEMPTS: "maxAttempts";
+    readonly NEXT_ATTEMPT_AT: "nextAttemptAt";
+    readonly PARENT_JOB_ID: "parentJobId";
     readonly STATUS_VALUES: {
         readonly PENDING: "pending";
         readonly PROCESSING: "processing";
         readonly DONE: "done";
         readonly FAILED: "failed";
+        /**
+         * Phase 8 — attempts exhausted. The dead-letter state.
+         *
+         * 🛑 `failed` and `dead` are DIFFERENT facts and conflating them is what
+         * made a failed job terminal with no signal. `failed` now means "this
+         * attempt failed, and a retry is scheduled or the failure was permanent";
+         * `dead` means "we have stopped trying" and is the only one that opens a
+         * case.
+         *
+         * A reader that treats every non-`done` as hopeless loses that distinction —
+         * which is why the retention sweep excludes `dead` while an open case
+         * references it: the row is the evidence.
+         */
+        readonly DEAD: "dead";
     };
 };

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

@@ -21,7 +21,39 @@ export const JobStatusValues = {
     PROCESSING: "processing",
     DONE: "done",
     FAILED: "failed",
+    /**
+     * Phase 8 — attempts exhausted. The dead-letter state.
+     *
+     * 🛑 `failed` and `dead` are DIFFERENT facts and conflating them is what
+     * made a failed job terminal with no signal. `failed` now means "this
+     * attempt failed, and a retry is scheduled or the failure was permanent";
+     * `dead` means "we have stopped trying" and is the only one that opens a
+     * case.
+     *
+     * A reader that treats every non-`done` as hopeless loses that distinction —
+     * which is why the retention sweep excludes `dead` while an open case
+     * references it: the row is the evidence.
+     */
+    DEAD: "dead",
 };
+/**
+ * Attempts before a job is declared dead.
+ *
+ * Three, with `JOB_BACKOFF_MS` below: a transient fault usually clears in
+ * minutes, and a fourth attempt an hour later is far more likely to be the
+ * same permanent fault again than a different outcome.
+ */
+export const JOB_MAX_ATTEMPTS = 3;
+/**
+ * Delay before attempt 2 and attempt 3.
+ *
+ * 🛑 Indexed by `attempt - 1`, so the array length must be at least
+ * `JOB_MAX_ATTEMPTS - 1`. The last value is reused if it is shorter, rather
+ * than producing `undefined` — a `nextAttemptAt` of `Invalid Date` would make
+ * the sweep's `<= now` comparison false forever and the retry would never run,
+ * which is the silent-stall shape this whole phase exists to remove.
+ */
+export const JOB_BACKOFF_MS = [5 * 60 * 1000, 30 * 60 * 1000];
 export const JOB_FIELDS = {
     JOB_TYPE: "jobType",
     STATUS: "status",
@@ -32,5 +64,10 @@ export const JOB_FIELDS = {
     FINISHED_AT: "finishedAt",
     CREATED_AT: "createdAt",
     UPDATED_AT: "updatedAt",
+    // Phase 8 retry/DLQ. `NEXT_ATTEMPT_AT` is the sweep's query field.
+    ATTEMPT: "attempt",
+    MAX_ATTEMPTS: "maxAttempts",
+    NEXT_ATTEMPT_AT: "nextAttemptAt",
+    PARENT_JOB_ID: "parentJobId",
     STATUS_VALUES: JobStatusValues,
 };

package/dist/features/lottery/schemas/zod.d.ts

@@ -42,12 +42,12 @@ export declare const reopenLotterySlotSchema: z.ZodObject<{
     adminUserId: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     slotNumber: number;
-    sourceType: "event" | "product";
+    sourceType: "product" | "event";
     sourceId: string;
     adminUserId: string;
 }, {
     slotNumber: number;
-    sourceType: "event" | "product";
+    sourceType: "product" | "event";
     sourceId: string;
     adminUserId: string;
 }>;
@@ -68,7 +68,7 @@ export declare const submitLotteryPullSchema: z.ZodEffects<z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     userId: string;
     transactionId: string;
-    sourceType: "event" | "product";
+    sourceType: "product" | "event";
     paymentTime: string;
     purchasedItemNumber: number;
     userPhone: string;
@@ -79,7 +79,7 @@ export declare const submitLotteryPullSchema: z.ZodEffects<z.ZodObject<{
 }, {
     userId: string;
     transactionId: string;
-    sourceType: "event" | "product";
+    sourceType: "product" | "event";
     paymentTime: string;
     purchasedItemNumber: number;
     userPhone: string;
@@ -90,7 +90,7 @@ export declare const submitLotteryPullSchema: z.ZodEffects<z.ZodObject<{
 }>, {
     userId: string;
     transactionId: string;
-    sourceType: "event" | "product";
+    sourceType: "product" | "event";
     paymentTime: string;
     purchasedItemNumber: number;
     userPhone: string;
@@ -101,7 +101,7 @@ export declare const submitLotteryPullSchema: z.ZodEffects<z.ZodObject<{
 }, {
     userId: string;
     transactionId: string;
-    sourceType: "event" | "product";
+    sourceType: "product" | "event";
     paymentTime: string;
     purchasedItemNumber: number;
     userPhone: string;