@mohasinac/appkit 4.58.0 → 4.60.0

package/dist/features/payment-cases/schemas/firestore.d.ts

@@ -0,0 +1,229 @@
+/**
+ * `paymentCases` — ONE operator queue for everything where money is at risk.
+ *
+ * ## Why one collection and not several
+ *
+ * A missing order, an unprocessed webhook, a chargeback, a refund mismatch and
+ * a dead job are different problems with the same audience: one person, once a
+ * day, asking "is anything wrong with the money". Three collections would mean
+ * three places to look and three chances to not look at one — and the one you
+ * forget is the one with the deadline.
+ *
+ * `kind` discriminates. Adding a seventh kind is a union edit, not a new
+ * collection.
+ *
+ * ## It mirrors `ReportDocument` on purpose
+ *
+ * `status` / `assignedTo` / `resolution` / `resolvedAt` / `entityType` /
+ * `entityId` are field-for-field the same as `store-extensions`'
+ * `ReportDocument`, so the admin list and detail views are a near-copy of the
+ * reports ones rather than a new UI. The four status values are identical too.
+ * Where it differs it is because a payment case has things a report does not: a
+ * **external deadline**, an **amount at risk**, and an **observation count**.
+ */
+import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+import type { StatusChangeEntry } from "../../../_internal/shared/history/types";
+export declare const PAYMENT_CASES_COLLECTION = "paymentCases";
+/**
+ * What kind of problem this is.
+ *
+ * | kind | opened when |
+ * |---|---|
+ * | `missing_order` | the gateway has a captured payment and we have no order — **the D64 shape** |
+ * | `unprocessed_event` | a `gatewayEvents` row never reached a terminal status |
+ * | `status_conflict` | a late event would have regressed an order's status |
+ * | `dispute` | a chargeback. The only kind with a deadline we do not control |
+ * | `refund_mismatch` | the gateway's `amount_refunded` disagrees with our `refunds[]` |
+ * | `amount_mismatch` | captured amount ≠ the order's recorded total |
+ * | `dead_job` | a job exhausted its retries (Phase 8) |
+ * | `grievance` | a statutory grievance with a clock (Phase 10) |
+ * | `shipping_unpriced` | a store's shipping could not be priced, so we shipped free |
+ * | `manual_refund_due` | a cancellation owes money that no automatic rail can move |
+ * | `protection_claim` | a buyer claimed against cover they paid for |
+ * | `ledger_drift` | a buyer's points mirror disagreed with their ledger |
+ *
+ * 🛑 `shipping_unpriced` is a CONFIGURATION fault with a money consequence,
+ * which is why it belongs in this queue rather than in `serverErrors`. An
+ * `estimate`-mode store with no carrier rate quoted `unavailable`, which the
+ * checkout mapped to `shippingFee: 0` — so every parcel for that store shipped
+ * free at our expense, silently, for as long as nobody looked (D44). Keyed on
+ * the STORE, so a misconfigured seller produces one case however many
+ * checkouts hit them.
+ */
+export type PaymentCaseKind = "missing_order" | "unprocessed_event" | "status_conflict" | "dispute" | "refund_mismatch" | "amount_mismatch" | "dead_job" | "grievance" | "shipping_unpriced"
+/**
+ * A buyer has claimed against protection cover they paid for.
+ *
+ * 🛑 Its own kind rather than borrowed from `refund_mismatch`, which is what
+ * I reached for first and is wrong: a claim is not a disagreement with the
+ * gateway about refund totals, it is a human decision about who absorbs a
+ * loss. Filing it under a kind that means something else makes the queue's
+ * own filters lie, and the kind chips are what an operator triages by.
+ */
+ | "protection_claim"
+/**
+ * A cancelled order owes the buyer money and nothing can move it
+ * automatically — see `_internal/server/features/orders/cancellation-refund.ts`.
+ *
+ * Three situations produce it, and they share this kind because they share
+ * the operator's next action (send money, record the reference): the order
+ * was paid by cash / UPI-manual / EMI so there is no gateway transaction to
+ * reverse; it was cancelled after dispatch, so how much is owed is a human
+ * decision about who bears the outbound leg; or the gateway refund was
+ * attempted and failed.
+ *
+ * 🛑 Distinct from `refund_mismatch`, which means the gateway and our
+ * `refunds[]` DISAGREE about a refund that happened. Here nothing has
+ * happened and that is the point. Filing this under a kind that means
+ * something else is the shortcut I took once already with protection claims,
+ * and it is attractive precisely because a plausible kind exists.
+ *
+ * The amount is on the order too (`refundAmount` + `refundStatus: "pending"`,
+ * written in the same patch as the cancellation), so the case and the order
+ * cannot disagree about what is owed — and the order carries it even if this
+ * write fails.
+ */
+ | "manual_refund_due"
+/**
+ * A buyer's `users/{uid}.pointsBalance` mirror disagrees with the sum of
+ * their `pointsLedger` entries.
+ *
+ * The ledger is append-only and therefore authoritative; the mirror exists
+ * only so a balance read is one document instead of a scan. So drift always
+ * means the mirror is wrong — and the reconciler repairs it. The case is
+ * raised anyway, because **a repaired mirror hides the write path that broke
+ * it.** Root Cause #102 is the same shape one domain over: a counter that
+ * drifted silently, where nothing errored because a wrong number is just a
+ * number.
+ *
+ * 🛑 Its own kind rather than `amount_mismatch`, which means the GATEWAY and
+ * our order total disagree. Nothing external is involved here; this is two of
+ * our own records disagreeing. The kind chips are what an operator triages
+ * by, and the third time this file has had to say so.
+ *
+ * `severity: "warning"` not `"error"`: the buyer's spendable balance is
+ * whatever the repair sets it to, so no money is at risk by the time anyone
+ * reads the case — but a recurring one means a writer is losing entries.
+ * Keyed on the USER, so a persistently broken mirror is one case with a
+ * rising `observedCount` rather than a new row every night.
+ */
+ | "ledger_drift";
+/**
+ * Identical to `ReportStatus`, deliberately — see the header. `actioned` means
+ * a human did something; `dismissed` means a human decided nothing was wrong.
+ * Both require a `resolution`.
+ */
+export type PaymentCaseStatus = "open" | "under-review" | "actioned" | "dismissed";
+/**
+ * Three values, matching `adminNotifications`' own severity vocabulary so one
+ * maps onto the other without a translation table.
+ *
+ * 🛑 Severity only ever ESCALATES — see `openOrObserve`. A reconciler that
+ * re-finds a problem it has already reported must not be able to quietly
+ * downgrade it.
+ */
+export type PaymentCaseSeverity = "info" | "warning" | "error";
+export interface PaymentCaseDocument extends BaseDocument {
+    kind: PaymentCaseKind;
+    status: PaymentCaseStatus;
+    severity: PaymentCaseSeverity;
+    /** Human-readable one-liner. The row an operator scans. */
+    title: string;
+    /** What was observed, in enough detail to act without opening the gateway. */
+    detail: string;
+    /** Mirrors `ReportDocument` — what the case is ABOUT. */
+    entityType: "order" | "payment" | "refund" | "event" | "job" | "store" | "user";
+    entityId: string;
+    /**
+     * The dedupe key, which is ALSO the document id.
+     *
+     * 🛑 Stored as a field as well, redundantly, because a Firestore id is not
+     * queryable as data — `where("dedupeKey","==",…)` is sometimes what a caller
+     * has, and `orderBy(documentId())` has its own restrictions. The redundancy
+     * is one short string and it is never written twice: `openOrObserve` derives
+     * both from the same value.
+     */
+    dedupeKey: string;
+    /** How many times a reconciler has independently re-found this problem. */
+    observedCount: number;
+    lastObservedAt: Date;
+    /**
+     * An EXTERNAL hard deadline, never an SLA we invented.
+     *
+     * 🛑 This is the field that justifies the collection existing. For a dispute
+     * it is the gateway's own `respond_by`: miss it and we lose by default,
+     * irrespective of who was right. For a grievance it is statutory. Nothing
+     * else sets it, and a case with no `dueAt` is a case with no clock — which is
+     * most of them, and that is correct.
+     */
+    dueAt?: Date;
+    /** Decimal rupees. What this case could cost if it goes the wrong way. */
+    amountAtRisk?: number;
+    assignedTo?: string;
+    resolution?: string;
+    resolvedAt?: Date;
+    resolvedBy?: string;
+    /**
+     * Set by a reconciler that no longer observes the problem.
+     *
+     * 🛑 This is NOT a resolution and must never be rendered as one. The UI shows
+     * "looks resolved — confirm?" and the case stays `open`. The distinction:
+     * "the symptom went away" and "a human understands why" are different facts,
+     * and on money the second is the one that matters. A self-healed
+     * `missing_order` might mean the retry worked — or might mean somebody
+     * refunded it by hand and the order will never exist.
+     */
+    selfHealedAt?: Date;
+    /** Gateway / event / order cross-references, for the detail view's links. */
+    gatewayEventIds?: string[];
+    orderIds?: string[];
+    gatewayPaymentId?: string;
+    statusHistory?: StatusChangeEntry[];
+    statusHistoryTruncated?: number;
+}
+export declare const PAYMENT_CASE_FIELDS: {
+    readonly ID: "id";
+    readonly KIND: "kind";
+    readonly STATUS: "status";
+    readonly SEVERITY: "severity";
+    readonly TITLE: "title";
+    readonly DETAIL: "detail";
+    readonly ENTITY_TYPE: "entityType";
+    readonly ENTITY_ID: "entityId";
+    readonly DEDUPE_KEY: "dedupeKey";
+    readonly OBSERVED_COUNT: "observedCount";
+    readonly LAST_OBSERVED_AT: "lastObservedAt";
+    readonly DUE_AT: "dueAt";
+    readonly AMOUNT_AT_RISK: "amountAtRisk";
+    readonly ASSIGNED_TO: "assignedTo";
+    readonly RESOLUTION: "resolution";
+    readonly RESOLVED_AT: "resolvedAt";
+    readonly RESOLVED_BY: "resolvedBy";
+    readonly SELF_HEALED_AT: "selfHealedAt";
+    readonly GATEWAY_PAYMENT_ID: "gatewayPaymentId";
+};
+/** Severity rank, for the escalate-only rule. */
+export declare const PAYMENT_CASE_SEVERITY_RANK: Record<PaymentCaseSeverity, number>;
+/** A resolution must say something. Ten characters is the same floor the admin offer-cancel reason uses. */
+export declare const PAYMENT_CASE_RESOLUTION_MIN = 10;
+/**
+ * Statuses a case can be in while still needing attention.
+ *
+ * 🛑 Exported so the digest, the escalation query and the retention exclusion
+ * all read ONE definition. Three hand-written copies of "which statuses are
+ * open" is how a case stops appearing in one of three places.
+ */
+export declare const PAYMENT_CASE_ACTIVE_STATUSES: readonly PaymentCaseStatus[];
+export declare const PAYMENT_CASE_KINDS: PaymentCaseKind[];
+export declare const PAYMENT_CASE_STATUSES: PaymentCaseStatus[];
+/**
+ * Build the dedupe key, which becomes the document id.
+ *
+ * 🛑 The key must identify THE PROBLEM, not the observation — that is the whole
+ * mechanism. `missing_order:pay_abc123` is the same problem whether a
+ * reconciler notices it once or thirty times, so thirty runs produce ONE case
+ * and ONE notification. Including a timestamp or a run id here would produce
+ * thirty cases and make the queue unusable within a week, which is the failure
+ * mode that makes operators stop opening it.
+ */
+export declare function createPaymentCaseId(kind: PaymentCaseKind, subjectId: string): string;

package/dist/features/payment-cases/schemas/firestore.js

@@ -0,0 +1,105 @@
+/**
+ * `paymentCases` — ONE operator queue for everything where money is at risk.
+ *
+ * ## Why one collection and not several
+ *
+ * A missing order, an unprocessed webhook, a chargeback, a refund mismatch and
+ * a dead job are different problems with the same audience: one person, once a
+ * day, asking "is anything wrong with the money". Three collections would mean
+ * three places to look and three chances to not look at one — and the one you
+ * forget is the one with the deadline.
+ *
+ * `kind` discriminates. Adding a seventh kind is a union edit, not a new
+ * collection.
+ *
+ * ## It mirrors `ReportDocument` on purpose
+ *
+ * `status` / `assignedTo` / `resolution` / `resolvedAt` / `entityType` /
+ * `entityId` are field-for-field the same as `store-extensions`'
+ * `ReportDocument`, so the admin list and detail views are a near-copy of the
+ * reports ones rather than a new UI. The four status values are identical too.
+ * Where it differs it is because a payment case has things a report does not: a
+ * **external deadline**, an **amount at risk**, and an **observation count**.
+ */
+export const PAYMENT_CASES_COLLECTION = "paymentCases";
+export const PAYMENT_CASE_FIELDS = {
+    ID: "id",
+    KIND: "kind",
+    STATUS: "status",
+    SEVERITY: "severity",
+    TITLE: "title",
+    DETAIL: "detail",
+    ENTITY_TYPE: "entityType",
+    ENTITY_ID: "entityId",
+    DEDUPE_KEY: "dedupeKey",
+    OBSERVED_COUNT: "observedCount",
+    LAST_OBSERVED_AT: "lastObservedAt",
+    DUE_AT: "dueAt",
+    AMOUNT_AT_RISK: "amountAtRisk",
+    ASSIGNED_TO: "assignedTo",
+    RESOLUTION: "resolution",
+    RESOLVED_AT: "resolvedAt",
+    RESOLVED_BY: "resolvedBy",
+    SELF_HEALED_AT: "selfHealedAt",
+    GATEWAY_PAYMENT_ID: "gatewayPaymentId",
+};
+/** Severity rank, for the escalate-only rule. */
+export const PAYMENT_CASE_SEVERITY_RANK = {
+    info: 0,
+    warning: 1,
+    error: 2,
+};
+/** A resolution must say something. Ten characters is the same floor the admin offer-cancel reason uses. */
+export const PAYMENT_CASE_RESOLUTION_MIN = 10;
+/**
+ * Statuses a case can be in while still needing attention.
+ *
+ * 🛑 Exported so the digest, the escalation query and the retention exclusion
+ * all read ONE definition. Three hand-written copies of "which statuses are
+ * open" is how a case stops appearing in one of three places.
+ */
+export const PAYMENT_CASE_ACTIVE_STATUSES = [
+    "open",
+    "under-review",
+];
+/**
+ * Runtime companions, keyed `Record<Union, true>` so BOTH mistakes are compile
+ * errors: a union member missing here, and a key here that is not a member. An
+ * array literal catches neither — which is how ten independent enumerations of
+ * `ListingType` came to disagree (Root Cause #61).
+ */
+const PAYMENT_CASE_KIND_MAP = {
+    missing_order: true,
+    unprocessed_event: true,
+    status_conflict: true,
+    dispute: true,
+    refund_mismatch: true,
+    amount_mismatch: true,
+    dead_job: true,
+    grievance: true,
+    shipping_unpriced: true,
+    protection_claim: true,
+    manual_refund_due: true,
+    ledger_drift: true,
+};
+export const PAYMENT_CASE_KINDS = Object.keys(PAYMENT_CASE_KIND_MAP);
+const PAYMENT_CASE_STATUS_MAP = {
+    open: true,
+    "under-review": true,
+    actioned: true,
+    dismissed: true,
+};
+export const PAYMENT_CASE_STATUSES = Object.keys(PAYMENT_CASE_STATUS_MAP);
+/**
+ * Build the dedupe key, which becomes the document id.
+ *
+ * 🛑 The key must identify THE PROBLEM, not the observation — that is the whole
+ * mechanism. `missing_order:pay_abc123` is the same problem whether a
+ * reconciler notices it once or thirty times, so thirty runs produce ONE case
+ * and ONE notification. Including a timestamp or a run id here would produce
+ * thirty cases and make the queue unusable within a week, which is the failure
+ * mode that makes operators stop opening it.
+ */
+export function createPaymentCaseId(kind, subjectId) {
+    return `${kind}:${subjectId}`.replace(/[^A-Za-z0-9_.:-]/g, "_").slice(0, 1500);
+}

package/dist/features/payment-cases/schemas/resolve-form.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The contract for resolving a payment case — ONE schema, three readers.
+ *
+ * ## Why a schema and not just the repository's check
+ *
+ * `PaymentCasesRepository.resolve()` already refuses a resolution shorter than
+ * `PAYMENT_CASE_RESOLUTION_MIN`, and that check is load-bearing and stays. But
+ * a runtime throw from the repository reaches the operator as a failed request
+ * after they have typed and submitted — the note is gone and the error has no
+ * field to land on, so it renders as a banner. That is precisely the shape
+ * `ReviewDecisionModal` was built to replace on the moderation and report
+ * surfaces.
+ *
+ * So the same floor is declared here, where the modal, the route and the
+ * repository can all read it:
+ *
+ *   · the MODAL parses before submitting, so the message lands on the textarea;
+ *   · the ROUTE parses the body, so a caller bypassing the UI gets a 400 with
+ *     `issues` rather than a 500 from a repository assertion;
+ *   · the REPOSITORY keeps its own assertion, because it is the last line and
+ *     a schema cannot be relied on by a caller that does not use it.
+ *
+ * Modelled field-for-field on `reportReviewFormSchema`, which exists for the
+ * identical reason on a collection `PaymentCaseDocument` deliberately mirrors.
+ *
+ * ## 🛑 `resolvedBy` and `resolvedAt` are NOT fields, and that is the point
+ *
+ * `reportReviewFormSchema`'s header records what happened when a client was
+ * allowed to send its own `resolvedAt`: `new Date()` does not survive
+ * `JSON.stringify`, so an ISO **string** was written into a field declared
+ * `Date`, and the collection ended up holding both shapes for one field.
+ *
+ * Here it would be worse than a type split. `resolve()` asserts
+ * `resolvedBy !== "system"` — that assertion is the whole mechanism keeping a
+ * case human-closed — and a client-supplied `resolvedBy` would let any caller
+ * name itself whatever it liked. The server stamps both from the session.
+ *
+ * EXPORTS:
+ *   paymentCaseResolveFormSchema, paymentCaseResolveUpdateSchema,
+ *   PAYMENT_CASE_REVIEWER_STATUSES, type PaymentCaseResolveFormValues
+ *
+ * @tag domain:payment-cases
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:admin/money-cases,/api/admin/payment-cases/[id]
+ * @tag sideEffects:none
+ */
+import { z } from "zod";
+/**
+ * The statuses a human review can set. `open` is the state a case is born in
+ * and nothing may set it back — a case that has been looked at has been looked
+ * at.
+ *
+ * `satisfies readonly PaymentCaseStatus[]` rather than restated, so a value
+ * outside the real union is a COMPILE error instead of a chip that silently
+ * matches nothing (Root Cause #33).
+ */
+export declare const PAYMENT_CASE_REVIEWER_STATUSES: readonly ["under-review", "actioned", "dismissed"];
+/**
+ * 🛑 `annotate()` must be the OUTERMOST call on each field — it keys a WeakMap
+ * by schema instance and every zod wrapper returns a new one.
+ */
+export declare const paymentCaseResolveFormSchema: z.ZodEffects<z.ZodObject<{
+    status: z.ZodEnum<["under-review", "actioned", "dismissed"]>;
+    resolution: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    status: "under-review" | "actioned" | "dismissed";
+    resolution?: string | undefined;
+}, {
+    status: "under-review" | "actioned" | "dismissed";
+    resolution?: string | undefined;
+}>, {
+    status: "under-review" | "actioned" | "dismissed";
+    resolution?: string | undefined;
+}, {
+    status: "under-review" | "actioned" | "dismissed";
+    resolution?: string | undefined;
+}>;
+export type PaymentCaseResolveFormValues = z.infer<typeof paymentCaseResolveFormSchema>;
+/** Route contract — identical; resolving a case is one atomic decision. */
+export declare const paymentCaseResolveUpdateSchema: z.ZodEffects<z.ZodObject<{
+    status: z.ZodEnum<["under-review", "actioned", "dismissed"]>;
+    resolution: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    status: "under-review" | "actioned" | "dismissed";
+    resolution?: string | undefined;
+}, {
+    status: "under-review" | "actioned" | "dismissed";
+    resolution?: string | undefined;
+}>, {
+    status: "under-review" | "actioned" | "dismissed";
+    resolution?: string | undefined;
+}, {
+    status: "under-review" | "actioned" | "dismissed";
+    resolution?: string | undefined;
+}>;

package/dist/features/payment-cases/schemas/resolve-form.js

@@ -0,0 +1,114 @@
+/**
+ * The contract for resolving a payment case — ONE schema, three readers.
+ *
+ * ## Why a schema and not just the repository's check
+ *
+ * `PaymentCasesRepository.resolve()` already refuses a resolution shorter than
+ * `PAYMENT_CASE_RESOLUTION_MIN`, and that check is load-bearing and stays. But
+ * a runtime throw from the repository reaches the operator as a failed request
+ * after they have typed and submitted — the note is gone and the error has no
+ * field to land on, so it renders as a banner. That is precisely the shape
+ * `ReviewDecisionModal` was built to replace on the moderation and report
+ * surfaces.
+ *
+ * So the same floor is declared here, where the modal, the route and the
+ * repository can all read it:
+ *
+ *   · the MODAL parses before submitting, so the message lands on the textarea;
+ *   · the ROUTE parses the body, so a caller bypassing the UI gets a 400 with
+ *     `issues` rather than a 500 from a repository assertion;
+ *   · the REPOSITORY keeps its own assertion, because it is the last line and
+ *     a schema cannot be relied on by a caller that does not use it.
+ *
+ * Modelled field-for-field on `reportReviewFormSchema`, which exists for the
+ * identical reason on a collection `PaymentCaseDocument` deliberately mirrors.
+ *
+ * ## 🛑 `resolvedBy` and `resolvedAt` are NOT fields, and that is the point
+ *
+ * `reportReviewFormSchema`'s header records what happened when a client was
+ * allowed to send its own `resolvedAt`: `new Date()` does not survive
+ * `JSON.stringify`, so an ISO **string** was written into a field declared
+ * `Date`, and the collection ended up holding both shapes for one field.
+ *
+ * Here it would be worse than a type split. `resolve()` asserts
+ * `resolvedBy !== "system"` — that assertion is the whole mechanism keeping a
+ * case human-closed — and a client-supplied `resolvedBy` would let any caller
+ * name itself whatever it liked. The server stamps both from the session.
+ *
+ * EXPORTS:
+ *   paymentCaseResolveFormSchema, paymentCaseResolveUpdateSchema,
+ *   PAYMENT_CASE_REVIEWER_STATUSES, type PaymentCaseResolveFormValues
+ *
+ * @tag domain:payment-cases
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:admin/money-cases,/api/admin/payment-cases/[id]
+ * @tag sideEffects:none
+ */
+import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta.js";
+import { PAYMENT_CASE_RESOLUTION_MIN, } from "./firestore.js";
+/**
+ * The statuses a human review can set. `open` is the state a case is born in
+ * and nothing may set it back — a case that has been looked at has been looked
+ * at.
+ *
+ * `satisfies readonly PaymentCaseStatus[]` rather than restated, so a value
+ * outside the real union is a COMPILE error instead of a chip that silently
+ * matches nothing (Root Cause #33).
+ */
+export const PAYMENT_CASE_REVIEWER_STATUSES = [
+    "under-review",
+    "actioned",
+    "dismissed",
+];
+/**
+ * 🛑 `annotate()` must be the OUTERMOST call on each field — it keys a WeakMap
+ * by schema instance and every zod wrapper returns a new one.
+ */
+export const paymentCaseResolveFormSchema = z
+    .object({
+    status: annotate(z.enum(PAYMENT_CASE_REVIEWER_STATUSES), {
+        section: "review",
+        sectionLabel: "Case decision",
+        sectionRequired: true,
+        quick: true,
+        order: 1,
+        row: "pair",
+    }),
+    resolution: annotate(z.string().max(2000, "Keep the resolution under 2000 characters.").optional(), {
+        section: "review",
+        order: 2,
+        row: "full",
+        kind: "textarea",
+        help: "Required when actioning or dismissing — say what you did, and what you checked.",
+    }),
+})
+    .strict()
+    .superRefine((v, ctx) => {
+    /*
+     * Taking a case for review needs no note; closing one does.
+     *
+     * 🛑 The floor is `PAYMENT_CASE_RESOLUTION_MIN`, imported rather than
+     * retyped, and it is higher than a non-empty check for a measured reason:
+     * the case queue's whole value is that a closed case explains itself to the
+     * next person, and "done", "ok" and "fixed" explain nothing. On money that
+     * matters more than elsewhere — a `missing_order` closed with "ok" leaves
+     * no way to tell "I refunded the buyer" from "I decided it was a duplicate".
+     *
+     * Trimmed before measuring, so ten spaces is not a resolution.
+     */
+    if (v.status === "under-review")
+        return;
+    const note = v.resolution?.trim() ?? "";
+    if (note.length < PAYMENT_CASE_RESOLUTION_MIN) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["resolution"],
+            message: `Say what was done about this case — at least ${PAYMENT_CASE_RESOLUTION_MIN} characters.`,
+        });
+    }
+});
+/** Route contract — identical; resolving a case is one atomic decision. */
+export const paymentCaseResolveUpdateSchema = paymentCaseResolveFormSchema;

package/dist/features/payments/repository/payout.repository.d.ts

@@ -74,7 +74,6 @@ export declare class PayoutRepository extends BaseRepository<PayoutDocument> {
      * encryption path with one extra step on top, rather than two parallel paths
      * that have to agree — which is what the hand-rolled override was.
      */
-    /** Override mapDoc to auto-decrypt PII on every Firestore read */
     /**
      * Create a new payout request
      */

package/dist/features/payments/repository/payout.repository.js

@@ -104,7 +104,6 @@ export class PayoutRepository extends BaseRepository {
      * `PayoutBankAccount` carries no secret field to encrypt. See the tombstone
      * in `security/pii-encrypt.ts`.
      */
-    /** Override mapDoc to auto-decrypt PII on every Firestore read */
     /**
      * Create a new payout request
      */