@mohasinac/appkit 4.59.0 → 4.60.0

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

@@ -52,6 +52,21 @@ export declare class PointsRepository {
         orderId?: string;
         adminReason?: string;
         actorUid?: string;
+        /**
+         * When this batch stops being spendable. Decision 4: three months.
+         *
+         * 🛑 Optional, and ABSENT MEANS NEVER EXPIRES — which is the right default
+         * for every entry written before the field existed. Treating absence as
+         * "expired" would retroactively void live balances.
+         *
+         * A caller crediting points SHOULD pass it; `pointsExpiryFrom(now)` is the
+         * one helper that computes it, so the three-month figure has one owner.
+         * Spends and reversals deliberately pass nothing: a spend has nothing to
+         * expire, and a reversal restores points whose original clock was already
+         * consumed — a fresh three months there would be a quiet extension nobody
+         * granted.
+         */
+        expiresAt?: Date;
     }): Promise<{
         entryId: string;
         balance: number;
@@ -75,7 +90,114 @@ export declare class PointsRepository {
         entryId: string;
         balance: number;
     }>;
+    /**
+     * Expire every lapsed batch, debiting whatever was never spent.
+     *
+     * ## 🛑 Expiry is a LEDGER ENTRY, never a silent balance edit
+     *
+     * The balance is DEFINED as the sum of the ledger. Quietly lowering the
+     * mirror would make the two disagree by exactly the expired amount, and the
+     * reconciliation job would then report drift forever with no way to tell it
+     * from a real fault. An adjustment row with a stated reason is the honest
+     * representation: the points left, and the row says why.
+     *
+     * 🛑 `actorUid: "system:points-expiry"` is a sentinel and this is the ONE
+     * place a system actor may write an adjustment — because expiry is a rule
+     * with a date attached, not a discretionary decision. Every other adjustment
+     * is a human's, which is why `adminReason` is mandatory on the kind.
+     *
+     * Marks the batch fully `consumed` in the same pass, and THAT is the
+     * idempotency key: without it an expiry job that ran twice would debit the
+     * buyer twice for one lapse.
+     */
+    expireLapsedBatches(now: Date, limit?: number): Promise<{
+        examined: number;
+        expired: number;
+        points: number;
+    }>;
+    /**
+     * Return points a cancelled order had consumed — `redemption_reversal`.
+     *
+     * ## 🛑 Points come back as POINTS, never as money
+     *
+     * The schema header states it as a legal boundary rather than a preference:
+     * *"never refunded as cash when an order is cancelled; points SPENT on a
+     * cancelled order are returned as points."* Paying them out in rupees is what
+     * would make this stored value, and stored value in India is PPI territory
+     * with RBI authorisation attached. This is the writer that makes that stated
+     * rule true — the kind has existed with no writer since it was declared (D48).
+     *
+     * 🛑 NO fresh `expiresAt`. A reversal restores points whose original clock has
+     * already been consumed; granting three new months would be a quiet extension
+     * nobody authorised, and it would reward cancelling an order with a longer
+     * window than keeping it.
+     *
+     * Idempotent on the ORDER: one reversal per order, found by querying for an
+     * existing `redemption_reversal` carrying the same `orderId`. An append-only
+     * ledger cannot net off a double reversal, so the check has to happen before
+     * the write.
+     */
+    reverseRedemptionForOrder(orderId: string, reason: string): Promise<{
+        reversed: number;
+    }>;
     /** Most recent entries first, for the buyer's own points page. */
     listForUser(userId: string, limit?: number): Promise<PointsLedgerEntry[]>;
+    /**
+     * Prove the mirror agrees with the ledger, and repair it where it does not.
+     *
+     * ## This is the job `sumLedger`'s own docstring has promised since day one
+     *
+     * That method says it exists "to repair the mirror and to let a
+     * reconciliation job prove the two agree" — and no such job was ever written
+     * (D49). So `users/{uid}.pointsBalance` could diverge from the entries
+     * indefinitely with nothing reporting it, which is Root Cause #102 exactly:
+     * a counter that cannot be checked drifts silently, because a wrong number
+     * raises nothing.
+     *
+     * ## 🛑 It enumerates USERS, not ledger entries
+     *
+     * Root Cause #102's reconciler could only ever ADD, because it built its
+     * tally from the events that existed rather than the entities that do — so a
+     * row whose last event was deleted was never visited and never reset. The
+     * same trap here: a user whose entries were all removed keeps a stale
+     * non-zero mirror forever if you only walk the ledger.
+     *
+     * So the candidate set is the UNION of two reads:
+     *
+     *   - every user document carrying a `pointsBalance` — catches a mirror with
+     *     no entries behind it, which is the case a ledger walk cannot see
+     *   - the distinct `userId`s in a bounded page of the ledger — catches
+     *     entries whose user has no mirror yet
+     *
+     * ## Repair direction, and why it still opens a case
+     *
+     * The ledger is append-only and is the DEFINITION of the balance, so repair
+     * is always mirror ← `sumLedger`. There is no judgement in it.
+     *
+     * 🛑 But a repaired mirror hides the writer that broke it. Every drift is
+     * therefore returned for the caller to raise a `ledger_drift` case: silent
+     * self-healing would make a persistently broken write path look like a
+     * healthy system, which is the failure this whole phase exists to remove.
+     *
+     * Absence of a mirror is NOT drift. `getBalance` already falls back to
+     * summing the ledger, so a user with entries and no mirror reads correctly —
+     * it is merely uncomputed. It is still written, because paying the scan on
+     * every balance read is what the mirror exists to avoid, but it is counted
+     * separately and never reported as a fault.
+     *
+     * Saturation is reported rather than hidden: at the page limit there are more
+     * users to check than were checked, which is a fact about the programme's
+     * size, not an error — but it must not read as "all clear".
+     */
+    reconcileLedgerMirror(limit?: number): Promise<{
+        examined: number;
+        drifted: {
+            userId: string;
+            mirror: number;
+            ledger: number;
+        }[];
+        initialised: number;
+        saturated: boolean;
+    }>;
 }
 export declare const pointsRepository: PointsRepository;

package/dist/features/points/repository/points.repository.js

@@ -1,5 +1,5 @@
 import { getAdminDb } from "../../../providers/db-firebase/index.js";
-import { POINTS_FIELDS, POINTS_LEDGER_COLLECTION, isPointsEntryWellFormed, } from "../schemas/firestore.js";
+import { POINTS_FIELDS, POINTS_LEDGER_COLLECTION, POINTS_EXPIRY_MONTHS, isPointsEntryWellFormed, } from "../schemas/firestore.js";
 import { USER_COLLECTION } from "../../auth/schemas/firestore.js";
 /**
  * The points ledger: append-only entries, and a balance that is their sum.
@@ -90,6 +90,7 @@ export class PointsRepository {
                 ...(input.orderId ? { orderId: input.orderId } : {}),
                 ...(input.adminReason ? { adminReason: input.adminReason } : {}),
                 ...(input.actorUid ? { actorUid: input.actorUid } : {}),
+                ...(input.expiresAt ? { expiresAt: input.expiresAt } : {}),
                 createdAt: new Date(),
                 updatedAt: new Date(),
             };
@@ -116,6 +117,74 @@ export class PointsRepository {
         const db = getAdminDb();
         const entryRef = db.collection(POINTS_LEDGER_COLLECTION).doc();
         const userRef = db.collection(USER_COLLECTION).doc(input.userId);
+        const now = new Date();
+        /*
+         * ── FIFO: which BATCHES does this spend draw from? ────────────────────
+         *
+         * 🛑 Queried OUTSIDE the transaction, and that is a Firestore constraint
+         * rather than a preference: a transaction must complete all reads before
+         * any write, and a collection QUERY cannot be mixed with the per-document
+         * updates below it. The part that must not race — the balance check — stays
+         * inside.
+         *
+         * The residual risk is two concurrent redemptions picking the same batches
+         * and over-consuming one, leaving a `consumed` figure above that entry's
+         * `amount`. That is an artefact on an EXPIRY calculation, not on a balance:
+         * the balance is guarded transactionally and still cannot go negative. The
+         * reconciliation job reports it, and a lock here would buy nothing a buyer
+         * can see.
+         */
+        const credits = await db
+            .collection(POINTS_LEDGER_COLLECTION)
+            .where(POINTS_FIELDS.USER_ID, "==", input.userId)
+            .where(POINTS_FIELDS.AMOUNT, ">", 0)
+            .orderBy(POINTS_FIELDS.AMOUNT)
+            .limit(200)
+            .get();
+        /*
+         * 🛑 Re-sorted in memory, because the QUERY CANNOT RETURN FIFO ORDER.
+         * Firestore forces an inequality's field to lead the `orderBy` (Root Cause
+         * #59), so `amount > 0` means the results arrive smallest-credit-first.
+         * Skipping this sort would consume the SMALLEST batches first — which looks
+         * exactly like FIFO on a ledger where every credit happens to be the same
+         * size, and silently is not.
+         *
+         * Oldest first, so a buyer never loses points they could have spent.
+         * Newest-first silently maximises expiry: the house winning by a mechanism
+         * nobody announced.
+         */
+        const batches = credits.docs
+            .map((d) => d.data())
+            .filter((e) => {
+            /*
+             * An expired batch is not spendable. Absent `expiresAt` means never
+             * expires — correct for every entry written before the field existed.
+             */
+            if (!e.expiresAt)
+                return true;
+            const exp = e.expiresAt instanceof Date ? e.expiresAt : new Date(e.expiresAt);
+            return exp.getTime() > now.getTime();
+        })
+            .sort((a, b) => {
+            const at = a.createdAt instanceof Date ? a.createdAt.getTime() : 0;
+            const bt = b.createdAt instanceof Date ? b.createdAt.getTime() : 0;
+            return at - bt;
+        });
+        let toDraw = input.points;
+        const draws = [];
+        for (const batch of batches) {
+            if (toDraw <= 0)
+                break;
+            const remaining = Math.round((batch.amount - (batch.consumed ?? 0)) * 100) / 100;
+            if (remaining <= 0)
+                continue;
+            const take = Math.min(remaining, toDraw);
+            draws.push({
+                id: batch.id,
+                consumed: Math.round(((batch.consumed ?? 0) + take) * 100) / 100,
+            });
+            toDraw = Math.round((toDraw - take) * 100) / 100;
+        }
         const balance = await db.runTransaction(async (tx) => {
             const userSnap = await tx.get(userRef);
             const current = typeof userSnap.data()?.pointsBalance === "number"
@@ -134,12 +203,138 @@ export class PointsRepository {
                 description: input.description,
                 createdAt: new Date(),
                 updatedAt: new Date(),
+                /*
+                 * Which batches paid for this spend, recorded ON the spend rather than
+                 * derived later — a reversal needs to know what to give back, and by
+                 * then those batches may have expired. "Return it where it came from"
+                 * is only answerable if the spend wrote it down.
+                 */
+                ...(draws.length ? { drawnFrom: draws.map((d) => d.id) } : {}),
             });
+            for (const d of draws) {
+                tx.update(db.collection(POINTS_LEDGER_COLLECTION).doc(d.id), {
+                    consumed: d.consumed,
+                    updatedAt: new Date(),
+                });
+            }
             tx.set(userRef, { pointsBalance: next }, { merge: true });
             return next;
         });
         return { entryId: entryRef.id, balance };
     }
+    /**
+     * Expire every lapsed batch, debiting whatever was never spent.
+     *
+     * ## 🛑 Expiry is a LEDGER ENTRY, never a silent balance edit
+     *
+     * The balance is DEFINED as the sum of the ledger. Quietly lowering the
+     * mirror would make the two disagree by exactly the expired amount, and the
+     * reconciliation job would then report drift forever with no way to tell it
+     * from a real fault. An adjustment row with a stated reason is the honest
+     * representation: the points left, and the row says why.
+     *
+     * 🛑 `actorUid: "system:points-expiry"` is a sentinel and this is the ONE
+     * place a system actor may write an adjustment — because expiry is a rule
+     * with a date attached, not a discretionary decision. Every other adjustment
+     * is a human's, which is why `adminReason` is mandatory on the kind.
+     *
+     * Marks the batch fully `consumed` in the same pass, and THAT is the
+     * idempotency key: without it an expiry job that ran twice would debit the
+     * buyer twice for one lapse.
+     */
+    async expireLapsedBatches(now, limit = 200) {
+        const db = getAdminDb();
+        const snap = await db
+            .collection(POINTS_LEDGER_COLLECTION)
+            .where(POINTS_FIELDS.EXPIRES_AT, "<=", now)
+            .orderBy(POINTS_FIELDS.EXPIRES_AT, "asc")
+            .limit(limit)
+            .get();
+        let expired = 0;
+        let points = 0;
+        for (const doc of snap.docs) {
+            const e = doc.data();
+            /*
+             * Credits only. A redemption carries no `expiresAt` so should never
+             * appear here — but the guard is free, and the cost of being wrong is
+             * debiting a buyer for a spend they already made.
+             */
+            if (e.amount <= 0)
+                continue;
+            const remaining = Math.round((e.amount - (e.consumed ?? 0)) * 100) / 100;
+            if (remaining <= 0)
+                continue;
+            await this.append({
+                userId: e.userId,
+                kind: "admin_adjustment",
+                amount: -remaining,
+                description: `${remaining} points expired.`,
+                adminReason: `Automatic expiry after ${POINTS_EXPIRY_MONTHS} months — batch ${e.id}.`,
+                actorUid: "system:points-expiry",
+            });
+            await doc.ref.update({ consumed: e.amount, updatedAt: now });
+            expired += 1;
+            points = Math.round((points + remaining) * 100) / 100;
+        }
+        return { examined: snap.size, expired, points };
+    }
+    /**
+     * Return points a cancelled order had consumed — `redemption_reversal`.
+     *
+     * ## 🛑 Points come back as POINTS, never as money
+     *
+     * The schema header states it as a legal boundary rather than a preference:
+     * *"never refunded as cash when an order is cancelled; points SPENT on a
+     * cancelled order are returned as points."* Paying them out in rupees is what
+     * would make this stored value, and stored value in India is PPI territory
+     * with RBI authorisation attached. This is the writer that makes that stated
+     * rule true — the kind has existed with no writer since it was declared (D48).
+     *
+     * 🛑 NO fresh `expiresAt`. A reversal restores points whose original clock has
+     * already been consumed; granting three new months would be a quiet extension
+     * nobody authorised, and it would reward cancelling an order with a longer
+     * window than keeping it.
+     *
+     * Idempotent on the ORDER: one reversal per order, found by querying for an
+     * existing `redemption_reversal` carrying the same `orderId`. An append-only
+     * ledger cannot net off a double reversal, so the check has to happen before
+     * the write.
+     */
+    async reverseRedemptionForOrder(orderId, reason) {
+        const db = getAdminDb();
+        const already = await db
+            .collection(POINTS_LEDGER_COLLECTION)
+            .where(POINTS_FIELDS.ORDER_ID, "==", orderId)
+            .where(POINTS_FIELDS.KIND, "==", "redemption_reversal")
+            .limit(1)
+            .get();
+        if (!already.empty)
+            return { reversed: 0 };
+        const spends = await db
+            .collection(POINTS_LEDGER_COLLECTION)
+            .where(POINTS_FIELDS.ORDER_ID, "==", orderId)
+            .where(POINTS_FIELDS.KIND, "==", "redemption")
+            .get();
+        if (spends.empty)
+            return { reversed: 0 };
+        const rows = spends.docs.map((d) => d.data());
+        /*
+         * `Math.abs`, because a redemption is stored NEGATIVE and a reversal must
+         * be positive — `isPointsEntryWellFormed` refuses the wrong sign, so a
+         * missing `abs` here would throw rather than silently credit a negative.
+         */
+        const total = Math.round(rows.reduce((sum, r) => sum + Math.abs(r.amount), 0) * 100) / 100;
+        if (total <= 0)
+            return { reversed: 0 };
+        await this.append({
+            userId: rows[0].userId,
+            kind: "redemption_reversal",
+            amount: total,
+            orderId,
+            description: `${total} points returned — ${reason}`,
+        });
+        return { reversed: total };
+    }
     /** Most recent entries first, for the buyer's own points page. */
     async listForUser(userId, limit = 50) {
         const db = getAdminDb();
@@ -151,5 +346,113 @@ export class PointsRepository {
             .get();
         return rows.docs.map((d) => d.data());
     }
+    /**
+     * Prove the mirror agrees with the ledger, and repair it where it does not.
+     *
+     * ## This is the job `sumLedger`'s own docstring has promised since day one
+     *
+     * That method says it exists "to repair the mirror and to let a
+     * reconciliation job prove the two agree" — and no such job was ever written
+     * (D49). So `users/{uid}.pointsBalance` could diverge from the entries
+     * indefinitely with nothing reporting it, which is Root Cause #102 exactly:
+     * a counter that cannot be checked drifts silently, because a wrong number
+     * raises nothing.
+     *
+     * ## 🛑 It enumerates USERS, not ledger entries
+     *
+     * Root Cause #102's reconciler could only ever ADD, because it built its
+     * tally from the events that existed rather than the entities that do — so a
+     * row whose last event was deleted was never visited and never reset. The
+     * same trap here: a user whose entries were all removed keeps a stale
+     * non-zero mirror forever if you only walk the ledger.
+     *
+     * So the candidate set is the UNION of two reads:
+     *
+     *   - every user document carrying a `pointsBalance` — catches a mirror with
+     *     no entries behind it, which is the case a ledger walk cannot see
+     *   - the distinct `userId`s in a bounded page of the ledger — catches
+     *     entries whose user has no mirror yet
+     *
+     * ## Repair direction, and why it still opens a case
+     *
+     * The ledger is append-only and is the DEFINITION of the balance, so repair
+     * is always mirror ← `sumLedger`. There is no judgement in it.
+     *
+     * 🛑 But a repaired mirror hides the writer that broke it. Every drift is
+     * therefore returned for the caller to raise a `ledger_drift` case: silent
+     * self-healing would make a persistently broken write path look like a
+     * healthy system, which is the failure this whole phase exists to remove.
+     *
+     * Absence of a mirror is NOT drift. `getBalance` already falls back to
+     * summing the ledger, so a user with entries and no mirror reads correctly —
+     * it is merely uncomputed. It is still written, because paying the scan on
+     * every balance read is what the mirror exists to avoid, but it is counted
+     * separately and never reported as a fault.
+     *
+     * Saturation is reported rather than hidden: at the page limit there are more
+     * users to check than were checked, which is a fact about the programme's
+     * size, not an error — but it must not read as "all clear".
+     */
+    async reconcileLedgerMirror(limit = 500) {
+        const db = getAdminDb();
+        const mirrorSnap = await db
+            .collection(USER_COLLECTION)
+            .select("pointsBalance")
+            .limit(limit)
+            .get();
+        const ledgerSnap = await db
+            .collection(POINTS_LEDGER_COLLECTION)
+            .select(POINTS_FIELDS.USER_ID)
+            .limit(limit)
+            .get();
+        const mirrors = new Map();
+        for (const d of mirrorSnap.docs) {
+            const v = d.data()?.pointsBalance;
+            if (typeof v === "number")
+                mirrors.set(d.id, v);
+        }
+        const candidates = new Set(mirrors.keys());
+        for (const d of ledgerSnap.docs) {
+            const uid = d.data()?.[POINTS_FIELDS.USER_ID];
+            if (typeof uid === "string" && uid)
+                candidates.add(uid);
+        }
+        const drifted = [];
+        let initialised = 0;
+        for (const userId of candidates) {
+            const ledger = await this.sumLedger(userId);
+            const mirror = mirrors.get(userId);
+            if (mirror === undefined) {
+                // Uncomputed, not drifted — see the docstring.
+                if (ledger !== 0) {
+                    await db
+                        .collection(USER_COLLECTION)
+                        .doc(userId)
+                        .set({ pointsBalance: ledger }, { merge: true });
+                    initialised += 1;
+                }
+                continue;
+            }
+            /*
+             * Half-paisa epsilon, matching every other money comparison here:
+             * `0.1 + 0.2 > 0.3` is true in IEEE-754, so an exact `!==` would report
+             * drift on a balance that is correct to the last paisa — and a reconciler
+             * that cries wolf nightly is one people stop reading.
+             */
+            if (Math.abs(mirror - ledger) > 0.005) {
+                drifted.push({ userId, mirror, ledger });
+                await db
+                    .collection(USER_COLLECTION)
+                    .doc(userId)
+                    .set({ pointsBalance: ledger }, { merge: true });
+            }
+        }
+        return {
+            examined: candidates.size,
+            drifted,
+            initialised,
+            saturated: mirrorSnap.size === limit || ledgerSnap.size === limit,
+        };
+    }
 }
 export const pointsRepository = new PointsRepository();

package/dist/features/points/schemas/adjust-form.d.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+/**
+ * The write contract for a manual points adjustment.
+ *
+ * ## 🛑 This creates or destroys SPENDABLE MONEY
+ *
+ * 1 point = ₹1 against a future order, so a credit here is a liability the
+ * platform has to honour and a debit takes value a buyer already holds. That
+ * is why this is the one ledger kind whose invariant
+ * (`isPointsEntryWellFormed`) demands a reason, and why the schema adds two
+ * things the invariant cannot express.
+ *
+ * ## 🛑 A CAP, because the realistic failure is a typo
+ *
+ * The invariant checks sign and reason, not magnitude — so `50000` where `500`
+ * was meant passes every existing check and mints ₹50,000 of liability in one
+ * click. `POINTS_ADJUSTMENT_MAX` bounds a single adjustment; a genuinely larger
+ * correction is several deliberate ones, each with its own reason and its own
+ * audit row, which is the right amount of friction for a number that size.
+ *
+ * The bound is on the ABSOLUTE value, so it guards the debit direction too: a
+ * mistyped debit wipes a balance the buyer earned and there is no undo beyond
+ * another adjustment.
+ *
+ * ## The reason is for the BUYER'S case file, not for us
+ *
+ * `adminReason` is never shown to the buyer (the schema says so), so its reader
+ * is the next admin asking "why does this account have 53 points". A reason
+ * like "fix" answers nothing, which is why the floor is a length rather than
+ * mere presence — the same reasoning as `paymentCaseResolveFormSchema`'s
+ * 10-character floor, and deliberately the same number so an operator meets one
+ * rule rather than two.
+ *
+ * 🛑 `amount` is SIGNED here, unlike `redeem()` which takes a positive and
+ * stores a negative. An adjustment genuinely goes both ways and the sign IS the
+ * intent, so hiding it behind a separate direction field would mean two inputs
+ * that can disagree. `.refine` rejects zero rather than letting `append()`
+ * throw on it, so the operator gets a field error instead of a 500.
+ */
+export declare const pointsAdjustFormSchema: z.ZodObject<{
+    userId: z.ZodString;
+    amount: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodNumber, number, number>, number, number>, number, number>, number, number>;
+    /** Shown to the BUYER on their points page. */
+    description: z.ZodString;
+    /** Never shown to the buyer. The next admin's answer to "why?". */
+    adminReason: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    amount: number;
+    description: string;
+    userId: string;
+    adminReason: string;
+}, {
+    amount: number;
+    description: string;
+    userId: string;
+    adminReason: string;
+}>;
+export type PointsAdjustFormValues = z.infer<typeof pointsAdjustFormSchema>;

package/dist/features/points/schemas/adjust-form.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { POINTS_ADJUSTMENT_MAX, POINTS_ADJUSTMENT_REASON_MIN } from "./firestore.js";
+/**
+ * The write contract for a manual points adjustment.
+ *
+ * ## 🛑 This creates or destroys SPENDABLE MONEY
+ *
+ * 1 point = ₹1 against a future order, so a credit here is a liability the
+ * platform has to honour and a debit takes value a buyer already holds. That
+ * is why this is the one ledger kind whose invariant
+ * (`isPointsEntryWellFormed`) demands a reason, and why the schema adds two
+ * things the invariant cannot express.
+ *
+ * ## 🛑 A CAP, because the realistic failure is a typo
+ *
+ * The invariant checks sign and reason, not magnitude — so `50000` where `500`
+ * was meant passes every existing check and mints ₹50,000 of liability in one
+ * click. `POINTS_ADJUSTMENT_MAX` bounds a single adjustment; a genuinely larger
+ * correction is several deliberate ones, each with its own reason and its own
+ * audit row, which is the right amount of friction for a number that size.
+ *
+ * The bound is on the ABSOLUTE value, so it guards the debit direction too: a
+ * mistyped debit wipes a balance the buyer earned and there is no undo beyond
+ * another adjustment.
+ *
+ * ## The reason is for the BUYER'S case file, not for us
+ *
+ * `adminReason` is never shown to the buyer (the schema says so), so its reader
+ * is the next admin asking "why does this account have 53 points". A reason
+ * like "fix" answers nothing, which is why the floor is a length rather than
+ * mere presence — the same reasoning as `paymentCaseResolveFormSchema`'s
+ * 10-character floor, and deliberately the same number so an operator meets one
+ * rule rather than two.
+ *
+ * 🛑 `amount` is SIGNED here, unlike `redeem()` which takes a positive and
+ * stores a negative. An adjustment genuinely goes both ways and the sign IS the
+ * intent, so hiding it behind a separate direction field would mean two inputs
+ * that can disagree. `.refine` rejects zero rather than letting `append()`
+ * throw on it, so the operator gets a field error instead of a 500.
+ */
+export const pointsAdjustFormSchema = z
+    .object({
+    userId: z.string().trim().min(1, "Pick a user."),
+    amount: z
+        .number({ invalid_type_error: "Enter a number of points." })
+        .refine((v) => Number.isFinite(v), "Enter a number of points.")
+        .refine((v) => v !== 0, "An adjustment of zero does nothing.")
+        .refine((v) => Math.abs(v) <= POINTS_ADJUSTMENT_MAX, `A single adjustment is capped at ${POINTS_ADJUSTMENT_MAX} points. Split a larger correction.`)
+        .refine((v) => Number.isInteger(v), "Points are whole numbers — a fraction of a point cannot be shown to a buyer or spent."),
+    /** Shown to the BUYER on their points page. */
+    description: z
+        .string()
+        .trim()
+        .min(1, "Say what the buyer will see for this entry.")
+        .max(140, "Keep the buyer-facing line under 140 characters."),
+    /** Never shown to the buyer. The next admin's answer to "why?". */
+    adminReason: z
+        .string()
+        .trim()
+        .min(POINTS_ADJUSTMENT_REASON_MIN, `Give a reason of at least ${POINTS_ADJUSTMENT_REASON_MIN} characters — the reader is the next admin, not the buyer.`)
+        .max(500, "Keep the reason under 500 characters."),
+})
+    .strict();