@mohasinac/appkit 4.62.1 → 4.63.0

package/dist/features/seller/schemas/order-forms.d.ts

@@ -32,10 +32,30 @@ export declare const sellerOrderUpdateSchema: z.ZodEffects<z.ZodObject<{
 }>;
 export type SellerOrderUpdateValues = z.infer<typeof sellerOrderUpdateSchema>;
 /**
- * Manual shipment entry. `method` is a literal rather than an enum because
- * `ManualShippingProvider` is the only provider — see § "Provider Resolution".
+ * Shipment entry — manual, or booked through the platform.
+ *
+ * 🛑 **`method` was `z.literal("custom")`, and that literal WAS bug 0e.**
+ *
+ * Its comment said *"a literal rather than an enum because
+ * `ManualShippingProvider` is the only provider"* — no longer true:
+ * `providers/shipping-shiprocket/` is 570 lines with all six methods, and
+ * `providers.config.ts` already resolves it from
+ * `siteSettings.shipping.provider`. The seller simply could not EXPRESS
+ * "book this through us", so there was no option to offer, and
+ * `platformBookedShipment` — which `order-math.ts` gates reimbursement on —
+ * had zero writers.
+ *
+ * A DISCRIMINATED UNION rather than an enum plus optional fields, because
+ * the two branches need different things and an optional-everything shape
+ * cannot say so:
+ *
+ * · `custom` — the seller posted it and types the carrier and tracking id.
+ *   Those are REQUIRED, which is the rule enforced in three places today.
+ * · `platform` — we book it, so there is no tracking id to type; it comes
+ *   back from the carrier. Requiring one here would be asking the seller to
+ *   invent the thing the booking produces.
  */
-export declare const shipOrderSchema: z.ZodObject<{
+export declare const shipOrderSchema: z.ZodDiscriminatedUnion<"method", [z.ZodObject<{
     method: z.ZodLiteral<"custom">;
     shippingCarrier: z.ZodString;
     trackingNumber: z.ZodString;
@@ -50,7 +70,44 @@ export declare const shipOrderSchema: z.ZodObject<{
     shippingCarrier: string;
     trackingUrl: string;
     method: "custom";
-}>;
+}>, z.ZodObject<{
+    method: z.ZodLiteral<"platform">;
+    pickupAddressId: z.ZodString;
+    dimensions: z.ZodObject<{
+        weight: z.ZodNumber;
+        length: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        length: number;
+        weight: number;
+        height: number;
+        width: number;
+    }, {
+        length: number;
+        weight: number;
+        height: number;
+        width: number;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    pickupAddressId: string;
+    method: "platform";
+    dimensions: {
+        length: number;
+        weight: number;
+        height: number;
+        width: number;
+    };
+}, {
+    pickupAddressId: string;
+    method: "platform";
+    dimensions: {
+        length: number;
+        weight: number;
+        height: number;
+        width: number;
+    };
+}>]>;
 export type ShipOrderValues = z.infer<typeof shipOrderSchema>;
 /**
  * Marking one EMI installment paid. `installmentIndex` is 1-based, matching

package/dist/features/seller/schemas/order-forms.js

@@ -92,15 +92,48 @@ export const sellerOrderUpdateSchema = z
  * it is also called directly from a server action, where no route ran first.
  */
 /**
- * Manual shipment entry. `method` is a literal rather than an enum because
- * `ManualShippingProvider` is the only provider — see § "Provider Resolution".
+ * Shipment entry — manual, or booked through the platform.
+ *
+ * 🛑 **`method` was `z.literal("custom")`, and that literal WAS bug 0e.**
+ *
+ * Its comment said *"a literal rather than an enum because
+ * `ManualShippingProvider` is the only provider"* — no longer true:
+ * `providers/shipping-shiprocket/` is 570 lines with all six methods, and
+ * `providers.config.ts` already resolves it from
+ * `siteSettings.shipping.provider`. The seller simply could not EXPRESS
+ * "book this through us", so there was no option to offer, and
+ * `platformBookedShipment` — which `order-math.ts` gates reimbursement on —
+ * had zero writers.
+ *
+ * A DISCRIMINATED UNION rather than an enum plus optional fields, because
+ * the two branches need different things and an optional-everything shape
+ * cannot say so:
+ *
+ * · `custom` — the seller posted it and types the carrier and tracking id.
+ *   Those are REQUIRED, which is the rule enforced in three places today.
+ * · `platform` — we book it, so there is no tracking id to type; it comes
+ *   back from the carrier. Requiring one here would be asking the seller to
+ *   invent the thing the booking produces.
  */
-export const shipOrderSchema = z.object({
-    method: z.literal("custom"),
-    shippingCarrier: z.string().min(1),
-    trackingNumber: z.string().min(1),
-    trackingUrl: z.string().url(),
-});
+export const shipOrderSchema = z.discriminatedUnion("method", [
+    z.object({
+        method: z.literal("custom"),
+        shippingCarrier: z.string().min(1),
+        trackingNumber: z.string().min(1),
+        trackingUrl: z.string().url(),
+    }),
+    z.object({
+        method: z.literal("platform"),
+        /* The store address the courier collects from. */
+        pickupAddressId: z.string().min(1),
+        dimensions: z.object({
+            weight: z.number().positive().max(50),
+            length: z.number().positive().max(200),
+            width: z.number().positive().max(200),
+            height: z.number().positive().max(200),
+        }),
+    }),
+]);
 /**
  * Marking one EMI installment paid. `installmentIndex` is 1-based, matching
  * how the schedule is presented to the buyer.

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

@@ -43,7 +43,32 @@ export interface ShipmentTotals {
 export declare const DEFAULT_SHIPMENT_TOTALS: ShipmentTotals;
 export interface ShipmentDocument extends BaseDocument {
     shipmentNumber: string;
+    /**
+     * The supplier as TYPED. Kept, and kept required, for display.
+     *
+     * 🛑 It is free text, so four shipments from one supplier are four
+     * unjoined strings — "Acme Toys", "acme toys", "Acme Toys Ltd", "ACME".
+     * Nothing can total what we have spent with anyone, which is the first
+     * question anybody asks of procurement data.
+     */
     supplierName: string;
+    /**
+     * The joinable identity — a `vendors` row.
+     *
+     * 🛑 OPTIONAL, and that is deliberate rather than a migration left half
+     * done. Every existing shipment has only the string, and backfilling by
+     * fuzzy-matching names is precisely how two real suppliers get merged into
+     * one spend figure that nobody can unpick afterwards. A shipment gains an
+     * id when a human links it; until then it is honestly unattributed, and
+     * the vendor report can say how many are.
+     *
+     * 🛑 The NAME is not derived from the vendor row on read. Two reasons: a
+     * vendor rename would retroactively rewrite what every past shipment says
+     * it was bought from, and the typed string is evidence of what the invoice
+     * actually said. Same stance the order item's frozen listing snapshot
+     * takes (Part 14).
+     */
+    supplierId?: string;
     originCountry?: string;
     status: ShipmentStatus;
     trackingNumber?: string;

package/dist/features/shipping-boxes/repository/shipping-boxes.repository.d.ts

@@ -39,5 +39,44 @@ export declare class ShippingBoxesRepository extends BaseRepository<ShippingBoxD
         box: ShippingBoxDocument;
         created: boolean;
     }>;
+    /**
+     * Every preset, retired included — the staff management list.
+     *
+     * Separate from `listActive` for the same reason the dispute reasons are: the
+     * picker must never offer a retired row, and a management view must be able
+     * to find one in order to put it back.
+     */
+    listAll(model: SieveModel): Promise<FirebaseSieveResult<ShippingBoxDocument>>;
+    /**
+     * Correct a preset's dimensions. **Staff only** — enforced at the route.
+     *
+     * ## 🛑 This does NOT change any dispatched parcel, by construction
+     *
+     * The dimensions are COPIED onto the shipment at use time (the schema's own
+     * header: *"a preset is a DEFAULT, never a lock"*), so there is no stored
+     * reference for this to reach through. That is precisely why staff editing is
+     * safe to offer at all: a seller's past declaration is a snapshot, and the
+     * courier billed against the figures at dispatch.
+     *
+     * It is staff-only for the mirror reason — these numbers are what the NEXT
+     * seller's dispatch form defaults to, so a wrong edit misdeclares other
+     * people's parcels. A seller who finds a preset wrong adds a new one; staff
+     * decide whether the shared row changes.
+     *
+     * 🛑 The NAME is deliberately not editable. The id is `box-<slug of name>`,
+     * so renaming would either leave the id disagreeing with the name (the
+     * mirror-drift trap) or require a new document, which is just a create. Add
+     * the correctly-named preset and retire this one.
+     */
+    updatePreset(id: string, input: {
+        length?: number;
+        width?: number;
+        height?: number;
+        tareWeight?: number;
+    }): Promise<void>;
+    /** Soft-retire. See the schema for why this is never a delete. */
+    retire(id: string): Promise<void>;
+    /** Put a retired preset back in the picker. */
+    reactivate(id: string): Promise<void>;
 }
 export declare const shippingBoxesRepository: ShippingBoxesRepository;

package/dist/features/shipping-boxes/repository/shipping-boxes.repository.js

@@ -58,6 +58,61 @@ export class ShippingBoxesRepository extends BaseRepository {
         await this.createWithId(id, box);
         return { box, created: true };
     }
+    /**
+     * Every preset, retired included — the staff management list.
+     *
+     * Separate from `listActive` for the same reason the dispute reasons are: the
+     * picker must never offer a retired row, and a management view must be able
+     * to find one in order to put it back.
+     */
+    async listAll(model) {
+        return this.sieveQuery(model, ShippingBoxesRepository.SIEVE_FIELDS, {
+            baseQuery: this.getCollection(),
+            defaultPageSize: 20,
+            maxPageSize: 50,
+        });
+    }
+    /**
+     * Correct a preset's dimensions. **Staff only** — enforced at the route.
+     *
+     * ## 🛑 This does NOT change any dispatched parcel, by construction
+     *
+     * The dimensions are COPIED onto the shipment at use time (the schema's own
+     * header: *"a preset is a DEFAULT, never a lock"*), so there is no stored
+     * reference for this to reach through. That is precisely why staff editing is
+     * safe to offer at all: a seller's past declaration is a snapshot, and the
+     * courier billed against the figures at dispatch.
+     *
+     * It is staff-only for the mirror reason — these numbers are what the NEXT
+     * seller's dispatch form defaults to, so a wrong edit misdeclares other
+     * people's parcels. A seller who finds a preset wrong adds a new one; staff
+     * decide whether the shared row changes.
+     *
+     * 🛑 The NAME is deliberately not editable. The id is `box-<slug of name>`,
+     * so renaming would either leave the id disagreeing with the name (the
+     * mirror-drift trap) or require a new document, which is just a create. Add
+     * the correctly-named preset and retire this one.
+     */
+    async updatePreset(id, input) {
+        const patch = { updatedAt: new Date() };
+        if (input.length !== undefined)
+            patch.length = clampCm(input.length);
+        if (input.width !== undefined)
+            patch.width = clampCm(input.width);
+        if (input.height !== undefined)
+            patch.height = clampCm(input.height);
+        if (input.tareWeight !== undefined)
+            patch.tareWeight = clampKg(input.tareWeight);
+        await this.update(id, patch);
+    }
+    /** Soft-retire. See the schema for why this is never a delete. */
+    async retire(id) {
+        await this.update(id, { isActive: false, updatedAt: new Date() });
+    }
+    /** Put a retired preset back in the picker. */
+    async reactivate(id) {
+        await this.update(id, { isActive: true, updatedAt: new Date() });
+    }
 }
 ShippingBoxesRepository.SIEVE_FIELDS = {
     /*

package/dist/features/shipping-boxes/schemas/firestore.d.ts

@@ -27,10 +27,10 @@
  * cannot dispute without the parcel. The form says so rather than treating it
  * as a required field to get past.
  */
+import type { BaseDocument } from "../../../_internal/shared/types/base-document";
 /** `box-` prefixed slug, so the id reads as what it is. */
 export declare const SHIPPING_BOX_COLLECTION = "shippingBoxes";
-export interface ShippingBoxDocument {
-    id: string;
+export interface ShippingBoxDocument extends BaseDocument {
     /** What a seller picks it by: "Standard Beyblade carton", "Poly mailer S". */
     name: string;
     /** cm. */
@@ -55,8 +55,6 @@ export interface ShippingBoxDocument {
      * not vanish mid-dispatch, and a deleted row takes its author with it.
      */
     isActive: boolean;
-    createdAt: Date;
-    updatedAt: Date;
 }
 export declare const SHIPPING_BOX_FIELDS: {
     readonly ID: "id";

package/dist/features/stores/repository/store.repository.d.ts

@@ -29,6 +29,24 @@ export declare class StoreRepository extends BaseRepository<StoreDocument> {
      * Find a store by its URL slug (also the document ID).
      */
     findBySlug(storeSlug: string): Promise<StoreDocument | null>;
+    /**
+     * The slugs of every store paid at shipping rather than at delivery.
+     *
+     * 🛑 A `Set` of IDS, not the documents. The payout sweep needs only
+     * membership, and loading full store documents for a question answered by a
+     * string would spend the ~3-round-trip budget (Rule #6) on data it discards.
+     *
+     * 🛑 An EQUALITY on `trustedSeller == true`, never `!= false`. A Firestore
+     * inequality excludes every document that LACKS the field — which is every
+     * store, since the flag is new and optional — so `!=` would return the
+     * trusted set and nothing else, or everything, depending on which way you
+     * wrote it. Both are wrong and neither raises.
+     *
+     * Bounded at 500: trust is granted by hand, one store at a time, on risk
+     * grounds. If this ever saturates, the grant has stopped being deliberate
+     * and that is the thing to fix rather than the limit.
+     */
+    findTrustedStoreIds(): Promise<Set<string>>;
     /**
      * Find the store owned by a specific user UID.
      */

package/dist/features/stores/repository/store.repository.js

@@ -59,6 +59,32 @@ export class StoreRepository extends BaseRepository {
     async findBySlug(storeSlug) {
         return this.findById(storeSlug);
     }
+    /**
+     * The slugs of every store paid at shipping rather than at delivery.
+     *
+     * 🛑 A `Set` of IDS, not the documents. The payout sweep needs only
+     * membership, and loading full store documents for a question answered by a
+     * string would spend the ~3-round-trip budget (Rule #6) on data it discards.
+     *
+     * 🛑 An EQUALITY on `trustedSeller == true`, never `!= false`. A Firestore
+     * inequality excludes every document that LACKS the field — which is every
+     * store, since the flag is new and optional — so `!=` would return the
+     * trusted set and nothing else, or everything, depending on which way you
+     * wrote it. Both are wrong and neither raises.
+     *
+     * Bounded at 500: trust is granted by hand, one store at a time, on risk
+     * grounds. If this ever saturates, the grant has stopped being deliberate
+     * and that is the thing to fix rather than the limit.
+     */
+    async findTrustedStoreIds() {
+        const snap = await this.db
+            .collection(this.collection)
+            .where(STORE_FIELDS.TRUSTED_SELLER, "==", true)
+            .select()
+            .limit(500)
+            .get();
+        return new Set(snap.docs.map((d) => d.id));
+    }
     /**
      * Find the store owned by a specific user UID.
      */
@@ -117,7 +143,7 @@ export class StoreRepository extends BaseRepository {
             trigger: ctx?.trigger ?? defaultTrigger,
             reason: ctx?.reason,
             note: ctx?.note,
-            // `encryptPiiFields` never descends into arrays, so a nested secret
+            // `encryptPiiFields` covers only NAMED paths, so an undeclared nested secret
             // would be stored in plaintext — the list below is the scrub.
             piiFields: STORE_HISTORY_PII_FIELDS,
         });

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

@@ -107,6 +107,27 @@ export interface StoreDocument extends BaseDocument {
     adminNotes?: string;
     /** Admin "verified store" badge — distinct from `status`/`isPublic`. */
     isVerified?: boolean;
+    /**
+     * Paid at SHIPPING rather than at delivery.
+     *
+     * 🛑 **A risk transfer, not a courtesy or a badge.** Paying before delivery
+     * means the platform carries a lost parcel and a non-delivery dispute with
+     * the money already gone. Admin-granted only, `recordAdminAction`-logged,
+     * revocable — and **PRIVATE in the public projection**, because it describes
+     * our risk posture rather than anything a buyer should weigh. A store does
+     * not get to display that we trust it.
+     *
+     * 🛑 A faster path through the SAME machinery, never a second one. The
+     * eligibility sweep moves the delivered-status test, not the payout, the
+     * hold, the deductions or the dispatch.
+     *
+     * 🛑 **A refund after a trusted payout has no money left to net against.**
+     * The ordinary path deducts from a still-`pending` payout; once paid there
+     * is nothing to deduct from, so it becomes a `manual_refund_due` case —
+     * which already exists and already means exactly this. Never a negative
+     * payout.
+     */
+    trustedSeller?: boolean;
     /** Reason recorded when `status` is set to "suspended". */
     suspensionReason?: string;
     stats?: {
@@ -386,6 +407,7 @@ export declare const STORE_FIELDS: {
     readonly ADMIN_NOTES: "adminNotes";
     readonly IS_FEATURED: "isFeatured";
     readonly IS_VERIFIED: "isVerified";
+    readonly TRUSTED_SELLER: "trustedSeller";
     readonly SUSPENSION_REASON: "suspensionReason";
     readonly CAPABILITIES: "capabilities";
     readonly STATUS_VALUES: {
@@ -404,3 +426,22 @@ export type StoreAddressUpdateInput = _AddrUpdate;
 export { ADDRESS_FIELDS as STORE_ADDRESS_FIELDS, ADDRESS_INDEXED_FIELDS as STORE_ADDRESS_INDEXED_FIELDS, ADDRESS_PUBLIC_FIELDS as STORE_ADDRESS_PUBLIC_FIELDS, ADDRESS_UPDATABLE_FIELDS as STORE_ADDRESS_UPDATABLE_FIELDS, DEFAULT_ADDRESS_DATA as DEFAULT_STORE_ADDRESS_DATA, } from "../../addresses/schemas";
 /** @deprecated SB-UNI-A — literal alias only. Use ADDRESSES_COLLECTION. */
 export declare const STORE_ADDRESS_SUBCOLLECTION: "addresses";
+/**
+ * The platform's own storefront.
+ *
+ * An IDENTITY, not a setting — it is the same id the seed's `REAL_STORE_IDS`
+ * and `realListingsOnly` already treat as the platform's own, and resolving it
+ * in code is what stops it being switched off by an edit, a reseed, or a
+ * mis-clicked admin toggle. `storeAcceptsPoints` is the motivating reader: the
+ * one store the points programme is advertised on cannot be allowed to decline
+ * to fund it.
+ *
+ * 🛑 It lives HERE, in `features/`, and not beside its reader in
+ * `_internal/shared/features/points/` — `audit-ssr-in-appkit` Rule 3 forbids a
+ * brand-bearing literal inside `_internal/`, because a consumer of appkit would
+ * inherit OUR store id with no way to override it. `features/` is where the
+ * same literal already lives legitimately (`CONSIGNMENT_STORE_ID` in
+ * `features/catalogue/utils/product-from-item.ts`), and this file is the one
+ * that already documents the rule on `acceptsPoints` above.
+ */
+export declare const PLATFORM_STORE_ID = "store-letitrip-official";

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

@@ -74,6 +74,7 @@ export const STORE_FIELDS = {
     ADMIN_NOTES: "adminNotes",
     IS_FEATURED: "isFeatured",
     IS_VERIFIED: "isVerified",
+    TRUSTED_SELLER: "trustedSeller",
     SUSPENSION_REASON: "suspensionReason",
     CAPABILITIES: "capabilities",
     STATUS_VALUES: {
@@ -101,3 +102,22 @@ export function generateStoreSlug(storeName, ownerDisplayName) {
 export { ADDRESS_FIELDS as STORE_ADDRESS_FIELDS, ADDRESS_INDEXED_FIELDS as STORE_ADDRESS_INDEXED_FIELDS, ADDRESS_PUBLIC_FIELDS as STORE_ADDRESS_PUBLIC_FIELDS, ADDRESS_UPDATABLE_FIELDS as STORE_ADDRESS_UPDATABLE_FIELDS, DEFAULT_ADDRESS_DATA as DEFAULT_STORE_ADDRESS_DATA, } from "../../addresses/schemas/index.js";
 /** @deprecated SB-UNI-A — literal alias only. Use ADDRESSES_COLLECTION. */
 export const STORE_ADDRESS_SUBCOLLECTION = "addresses";
+/**
+ * The platform's own storefront.
+ *
+ * An IDENTITY, not a setting — it is the same id the seed's `REAL_STORE_IDS`
+ * and `realListingsOnly` already treat as the platform's own, and resolving it
+ * in code is what stops it being switched off by an edit, a reseed, or a
+ * mis-clicked admin toggle. `storeAcceptsPoints` is the motivating reader: the
+ * one store the points programme is advertised on cannot be allowed to decline
+ * to fund it.
+ *
+ * 🛑 It lives HERE, in `features/`, and not beside its reader in
+ * `_internal/shared/features/points/` — `audit-ssr-in-appkit` Rule 3 forbids a
+ * brand-bearing literal inside `_internal/`, because a consumer of appkit would
+ * inherit OUR store id with no way to override it. `features/` is where the
+ * same literal already lives legitimately (`CONSIGNMENT_STORE_ID` in
+ * `features/catalogue/utils/product-from-item.ts`), and this file is the one
+ * that already documents the rule on `acceptsPoints` above.
+ */
+export const PLATFORM_STORE_ID = "store-letitrip-official";

package/dist/features/stores/schemas/index.d.ts

@@ -218,13 +218,13 @@ export declare const storeFirestoreSchema: z.ZodObject<{
         totalReviews: z.ZodNumber;
         averageRating: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
-        itemsSold: number;
         totalProducts: number;
+        itemsSold: number;
         totalReviews: number;
         averageRating?: number | undefined;
     }, {
-        itemsSold: number;
         totalProducts: number;
+        itemsSold: number;
         totalReviews: number;
         averageRating?: number | undefined;
     }>>;
@@ -363,8 +363,8 @@ export declare const storeFirestoreSchema: z.ZodObject<{
     location?: string | undefined;
     returnPolicy?: string | undefined;
     stats?: {
-        itemsSold: number;
         totalProducts: number;
+        itemsSold: number;
         totalReviews: number;
         averageRating?: number | undefined;
     } | undefined;
@@ -432,8 +432,8 @@ export declare const storeFirestoreSchema: z.ZodObject<{
     location?: string | undefined;
     returnPolicy?: string | undefined;
     stats?: {
-        itemsSold: number;
         totalProducts: number;
+        itemsSold: number;
         totalReviews: number;
         averageRating?: number | undefined;
     } | undefined;
@@ -530,8 +530,8 @@ export declare const storeListItemSchema: z.ZodObject<{
     storeDescription?: string | undefined;
     storeLogoURL?: string | undefined;
     storeBannerURL?: string | undefined;
-    itemsSold?: number | undefined;
     totalProducts?: number | undefined;
+    itemsSold?: number | undefined;
     totalReviews?: number | undefined;
     averageRating?: number | undefined;
 }, {
@@ -546,8 +546,8 @@ export declare const storeListItemSchema: z.ZodObject<{
     storeDescription?: string | undefined;
     storeLogoURL?: string | undefined;
     storeBannerURL?: string | undefined;
-    itemsSold?: number | undefined;
     totalProducts?: number | undefined;
+    itemsSold?: number | undefined;
     totalReviews?: number | undefined;
     averageRating?: number | undefined;
 }>;

package/dist/features/support/repository/support.repository.js

@@ -9,6 +9,41 @@ import { sieveAnd, sieveFilter, SIEVE_OP } from "../../../utils/sieve-builder.js
 import { maskPii, revealPii } from "../../../security/pii-accessors.js";
 import { SUPPORT_TICKET_COLLECTION, SUPPORT_TICKET_PII_FIELDS, SUPPORT_TICKET_TRACKED_FIELDS, TicketStatusValues, ACTIVE_TICKET_STATUSES, } from "../schemas/firestore.js";
 import { withHistory } from "../../../_internal/shared/history/index.js";
+/**
+ * Who, if anyone, gets credited with resolving this ticket.
+ *
+ * 🛑 **A BUYER is never the resolver**, even though a buyer can drive the
+ * transition — replying "that's sorted, thanks" is a legitimate way for a
+ * ticket to reach `resolved`, and crediting it would put a customer's uid in
+ * a field a payslip is computed from. `system` has no uid at all, which is
+ * the other case that must not be paid.
+ *
+ * Returning `undefined` is correct and expected: the ticket is still resolved,
+ * it simply earns nobody wages. A fabricated fallback — the assignee, the
+ * ticket owner — would be a wage attributed to someone who did not do the
+ * work, and it would look exactly like a real one.
+ */
+const WAGE_EARNING_ACTOR_ROLES = new Set(["seller", "admin"]);
+function resolverUid(ctx) {
+    const actor = ctx?.actor;
+    if (!actor?.uid)
+        return undefined;
+    /*
+     * An ALLOW-LIST, not `role !== "buyer"`. A tenth actor role added later
+     * would silently start earning wages under a deny-list, which is the
+     * `Record<Union, T>`-over-`Set<string>` argument this codebase makes
+     * everywhere else — and the roles that can be credited is the shorter,
+     * more stable list.
+     *
+     * 🛑 `HistoryActorRole` has no `employee` member, and that is FINE: this
+     * field records WHO resolved it, and the payroll decides whether that
+     * person is on it. A seller resolving their own store's ticket is recorded
+     * here and appears on no payslip, because they are not an employee.
+     */
+    if (!WAGE_EARNING_ACTOR_ROLES.has(actor.role))
+        return undefined;
+    return actor.uid;
+}
 export class SupportRepository extends BaseRepository {
     constructor() {
         super(SUPPORT_TICKET_COLLECTION);
@@ -210,7 +245,7 @@ export class SupportRepository extends BaseRepository {
         // `piiFields`, which is what encrypts `assignedToName` on the way down.
         const patch = {
             ...update,
-            ...this.resolutionStamps(current, update.status),
+            ...this.resolutionStamps(current, update.status, resolverUid(ctx)),
             updatedAt: new Date(),
         };
         return this.update(ticketId, this.withTicketHistory(current, patch, ctx, "updateTicketStatus"));
@@ -233,14 +268,45 @@ export class SupportRepository extends BaseRepository {
      * against the document would poison that patch's inferred type with
      * `Encrypted<string>` members it never actually sets.
      */
-    resolutionStamps(current, next) {
+    resolutionStamps(current, next, actorUid) {
         if (!next || next === current?.status)
             return {};
         const now = new Date();
-        if (next === TicketStatusValues.RESOLVED && !current?.resolvedAt)
-            return { resolvedAt: now };
+        if (next === TicketStatusValues.RESOLVED && !current?.resolvedAt) {
+            /*
+             * 🛑 `resolvedBy` is stamped HERE and is not the same thing as
+             * `assignedTo`.
+             *
+             * `assignedTo` is the CURRENT assignee: reassign a resolved ticket for
+             * follow-up and it moves, so paying from it credits whoever happens to
+             * hold the ticket at month end rather than whoever did the work. That is
+             * the whole reason this field exists.
+             *
+             * Absent when the caller supplied no actor — a system transition has no
+             * person to pay, and a fabricated uid would be a wage attributed to
+             * somebody who did nothing.
+             */
+            return actorUid ? { resolvedAt: now, resolvedBy: actorUid } : { resolvedAt: now };
+        }
         if (next === TicketStatusValues.CLOSED && !current?.closedAt)
             return { closedAt: now };
+        /*
+         * 🛑 A REOPEN clears both, and clearing `resolvedBy` is load-bearing.
+         *
+         * Pay is computed from tickets STILL RESOLVED at period end, so a ticket
+         * that goes back to open must stop counting — otherwise close-it,
+         * let-it-reopen, close-it-again pays twice for one problem.
+         *
+         * Cleared rather than left in place with the status as the only signal,
+         * because `resolvedTicketsForPeriod` filters on all three and a stale
+         * `resolvedAt` surviving a reopen is a row that looks payable to anything
+         * that checks fewer of them.
+         */
+        const reopened = current?.resolvedAt != null &&
+            next !== TicketStatusValues.RESOLVED &&
+            next !== TicketStatusValues.CLOSED;
+        if (reopened)
+            return { resolvedAt: undefined, resolvedBy: undefined };
         return {};
     }
     /** Append a timeline entry when the patch touches a tracked field. */
@@ -259,7 +325,7 @@ export class SupportRepository extends BaseRepository {
             trigger: ctx?.trigger ?? defaultTrigger,
             reason: ctx?.reason,
             note: ctx?.note,
-            // `encryptPiiFields` never descends into arrays, so a PII-named value
+            // `encryptPiiFields` covers only NAMED paths, so an undeclared PII-named value
             // reaching `changes` would persist in PLAINTEXT inside statusHistory.
             piiFields: SUPPORT_TICKET_PII_FIELDS,
         });
@@ -288,7 +354,7 @@ export class SupportRepository extends BaseRepository {
             };
             if (newStatus) {
                 const current = prior !== undefined ? prior : await this.getTicketById(ticketId);
-                Object.assign(updateData, this.withTicketHistory(current, { status: newStatus, ...this.resolutionStamps(current, newStatus) }, ctx, "addMessage"));
+                Object.assign(updateData, this.withTicketHistory(current, { status: newStatus, ...this.resolutionStamps(current, newStatus, resolverUid(ctx)) }, ctx, "addMessage"));
             }
             await ref.update(updateData);
         }

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

@@ -196,6 +196,23 @@ export interface SupportTicketDocument extends BaseDocument {
      * `Date` field and split the collection into two shapes.
      */
     resolvedAt?: Date;
+    /**
+     * The uid of whoever moved the ticket to `resolved`.
+     *
+     * 🛑 **Not `assignedTo`.** That is the CURRENT assignee and moves on
+     * reassignment, so paying from it credits whoever holds the ticket at period
+     * end rather than whoever did the work. Employee pay is computed from this
+     * field; see `resolvedTicketsForPeriod`.
+     *
+     * Server-stamped, never client-sent, and **cleared on reopen** — pay counts
+     * tickets still resolved at period end, so a reopened ticket must stop
+     * counting or closing it twice pays twice.
+     *
+     * Absent on a system transition and on a buyer-driven one: both are real
+     * resolutions that earn nobody wages, and a fallback to the assignee would
+     * be a wage attributed to someone who did nothing.
+     */
+    resolvedBy?: string;
     closedAt?: Date;
     /** When we acknowledged receipt. Server-stamped at intake. */
     acknowledgedAt?: Date;