@mohasinac/appkit 4.13.1 → 4.15.0

package/dist/features/lottery/types/index.d.ts

@@ -7,6 +7,8 @@
 export interface LotterySlot {
     slotNumber: number;
     name: string;
+    /** Prize photo. Public — rendered in the prize collage on the lottery detail page. */
+    image?: string;
     price: number;
     weight: number;
     isBooked: boolean;
@@ -18,6 +20,7 @@ export interface LotterySlot {
 export interface ClientLotterySlot {
     slotNumber: number;
     name: string;
+    image?: string;
     isBooked: boolean;
     bookedByUserLotteryNumber?: number;
     bookedByDisplayName?: string;

package/dist/features/media/MediaPickerModal.js

@@ -126,7 +126,11 @@ export function MediaPickerModal({ isOpen, onClose, onSelect, accept = "image/*"
                                     const isImage = (f.contentType ?? "").startsWith("image/");
                                     const isSelected = selectedExisting === f.downloadURL;
                                     return (_jsxs(Button, { type: "button", variant: "ghost", onClick: () => setSelectedExisting(f.downloadURL), className: [
-                                            "rounded-lg border overflow-hidden text-left transition p-[var(--appkit-space-0)] h-auto",
+                                            // `flex-col items-stretch` — without it the thumbnail and the
+                                            // filename lay out as row siblings inside `.appkit-button__content`
+                                            // and the square tile shrinks to a fraction of its width
+                                            // (Root Cause #68).
+                                            "flex-col items-stretch rounded-lg border overflow-hidden text-left transition p-[var(--appkit-space-0)] h-auto",
                                             isSelected
                                                 ? "border-primary-500 ring-2 ring-primary-300"
                                                 : "border-[var(--appkit-color-border)]",

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

@@ -116,8 +116,8 @@ export declare const conversationFirestoreSchema: z.ZodObject<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;
     storeId: string;
-    storeName: string;
     buyerId: string;
+    storeName: string;
     lastMessageAt: string | Date | z.objectOutputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;
@@ -149,8 +149,8 @@ export declare const conversationFirestoreSchema: z.ZodObject<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;
     storeId: string;
-    storeName: string;
     buyerId: string;
+    storeName: string;
     lastMessageAt: string | Date | z.objectInputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;

package/dist/features/orders/components/OrderScopeTabs.d.ts

@@ -0,0 +1,20 @@
+import React from "react";
+import { type OrderScope } from "../constants/order-scope";
+export declare function OrderScopeTabs({ className }: {
+    className?: string;
+}): React.JSX.Element;
+export interface OrderScopeState {
+    scope: OrderScope;
+    /** Spread into `ListingViewConfig.buildExtraParams`'s return value. */
+    extraParams: {
+        orderScope: OrderScope;
+    };
+    /** Assign to `ListingViewConfig.renderAboveContent`. */
+    renderAboveContent: () => React.ReactNode;
+}
+/**
+ * Same seam as `useAvailabilityScope`: `buildExtraParams`, not `filterKeys`.
+ * Registering the scope as a filter key would inflate the filter-drawer badge
+ * for a tab selection and let the drawer's Clear button silently reset it.
+ */
+export declare function useOrderScope(): OrderScopeState;

package/dist/features/orders/components/OrderScopeTabs.js

@@ -0,0 +1,31 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Tabs, TabsList, TabsTrigger } from "../../../ui";
+import { useUrlTable } from "../../../react/hooks/useUrlTable";
+import { TABLE_KEYS } from "../../../constants/table-keys";
+import { ORDER_SCOPE_TABS, ORDER_SCOPE_VALUES, isOrderScope, } from "../constants/order-scope";
+export function OrderScopeTabs({ className }) {
+    const table = useUrlTable();
+    const raw = table.get(TABLE_KEYS.ORDER_SCOPE);
+    const active = isOrderScope(raw) ? raw : ORDER_SCOPE_VALUES.ACTIVE;
+    return (_jsx(Tabs, { value: active, 
+        // A single `set` — `useUrlTable.set` already resets the page, and a
+        // follow-up `setPage` would read stale searchParams and overwrite this
+        // update (Root Cause #13).
+        onChange: (next) => table.set(TABLE_KEYS.ORDER_SCOPE, next), className: className, children: _jsx(TabsList, { children: ORDER_SCOPE_TABS.map((tab) => (_jsx(TabsTrigger, { value: tab.id, children: tab.label }, tab.id))) }) }));
+}
+/**
+ * Same seam as `useAvailabilityScope`: `buildExtraParams`, not `filterKeys`.
+ * Registering the scope as a filter key would inflate the filter-drawer badge
+ * for a tab selection and let the drawer's Clear button silently reset it.
+ */
+export function useOrderScope() {
+    const table = useUrlTable();
+    const raw = table.get(TABLE_KEYS.ORDER_SCOPE);
+    const scope = isOrderScope(raw) ? raw : ORDER_SCOPE_VALUES.ACTIVE;
+    return {
+        scope,
+        extraParams: { orderScope: scope },
+        renderAboveContent: () => _jsx(OrderScopeTabs, {}),
+    };
+}

package/dist/features/orders/components/OrderStatusTimeline.d.ts

@@ -1,5 +1,9 @@
+import { type TimelineEntry } from "../../status-history/components/StatusTimeline";
 export interface OrderStatusTimelineProps {
     orderStatus: string;
+    /** Recorded history. When present it wins over the scalar-date fallback. */
+    timeline?: TimelineEntry[];
+    timelineTruncated?: number;
     orderDate?: string;
     shippingDate?: string;
     deliveryDate?: string;
@@ -9,4 +13,4 @@ export interface OrderStatusTimelineProps {
     trackingUrl?: string;
     className?: string;
 }
-export declare function OrderStatusTimeline({ orderStatus, orderDate, shippingDate, deliveryDate, cancellationDate, trackingNumber, shippingCarrier, trackingUrl, className, }: OrderStatusTimelineProps): import("react").JSX.Element;
+export declare function OrderStatusTimeline({ orderStatus, timeline, timelineTruncated, orderDate, shippingDate, deliveryDate, cancellationDate, trackingNumber, shippingCarrier, trackingUrl, className, }: OrderStatusTimelineProps): import("react").JSX.Element;

package/dist/features/orders/components/OrderStatusTimeline.js

@@ -1,16 +1,25 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /**
- * OrderStatusTimeline — a genuine (not fabricated/estimated) status timeline
- * built from the real per-status timestamps already written by the
- * order-status-update path (`orderDate`/`shippingDate`/`deliveryDate`/
- * `cancellationDate`). No live courier-API integration — `trackingUrl` is
- * just the passthrough link a seller/admin entered, rendered as an external
- * link that opens in a new tab. Statuses with no dedicated date field
- * (confirmed/processing/return_requested/returned/refunded) render as a step
- * without a timestamp rather than showing a made-up date.
+ * OrderStatusTimeline — the order-shaped wrapper around `<StatusTimeline>`.
+ *
+ * Two branches, and the fallback matters as much as the primary path:
+ *
+ * **Branch A — real history.** When the order carries `timeline` entries
+ * (written by the repository since W2), each status change becomes a step
+ * dated by when it actually happened, stamped with who did it. This finally
+ * makes transitions with no dedicated date field visible at all — a payment
+ * review, a re-upload request, a partial refund.
+ *
+ * **Branch B — legacy orders.** Every order written before `statusHistory`
+ * existed has none, and back-filling one would mean inventing timestamps. So
+ * the original derivation from the four scalar dates is kept verbatim for
+ * those. Statuses with no dedicated date field render without one.
+ *
+ * No live courier API: `trackingUrl` is the passthrough link a seller entered.
  */
-import { Anchor, Badge, Div, Heading, Row, Stack, Text } from "../../../ui";
+import { Anchor, Badge, Row, Stack, Text } from "../../../ui";
+import { StatusTimeline, stepsFromEntries, } from "../../status-history/components/StatusTimeline";
 const STAGE_SEQUENCE = ["pending", "confirmed", "processing", "shipped", "delivered"];
 const STAGE_LABELS = {
     pending: "Order placed",
@@ -23,10 +32,16 @@ const STAGE_LABELS = {
     returned: "Returned",
     refunded: "Refunded",
 };
-function buildSteps(props) {
+const NEGATIVE_STATUSES = new Set(["cancelled"]);
+const labelFor = (status) => STAGE_LABELS[status] ?? status;
+const isNegative = (status) => NEGATIVE_STATUSES.has(status);
+/** Branch B — derive from the four scalar dates, for orders with no history. */
+function buildLegacySteps(props) {
     const status = (props.orderStatus ?? "").toLowerCase();
     const currentIndex = STAGE_SEQUENCE.indexOf(status);
-    const steps = [{ key: "pending", label: STAGE_LABELS.pending, date: props.orderDate }];
+    const steps = [
+        { key: "pending", label: STAGE_LABELS.pending, date: props.orderDate },
+    ];
     if ((status === "confirmed" || status === "processing") && !props.shippingDate) {
         steps.push({ key: status, label: STAGE_LABELS[status] });
     }
@@ -37,19 +52,23 @@ function buildSteps(props) {
         steps.push({ key: "delivered", label: STAGE_LABELS.delivered, date: props.deliveryDate });
     }
     if (status === "cancelled" || props.cancellationDate) {
-        steps.push({ key: "cancelled", label: STAGE_LABELS.cancelled, date: props.cancellationDate });
+        steps.push({
+            key: "cancelled",
+            label: STAGE_LABELS.cancelled,
+            date: props.cancellationDate,
+            negative: true,
+        });
     }
     else if (status === "return_requested" || status === "returned" || status === "refunded") {
         steps.push({ key: status, label: STAGE_LABELS[status] ?? status });
     }
     return steps;
 }
-export function OrderStatusTimeline({ orderStatus, orderDate, shippingDate, deliveryDate, cancellationDate, trackingNumber, shippingCarrier, trackingUrl, className = "", }) {
-    const steps = buildSteps({ orderStatus, orderDate, shippingDate, deliveryDate, cancellationDate });
-    const isTerminalNegative = steps[steps.length - 1]?.key === "cancelled";
-    return (_jsxs(Div, { className: className, rounded: "xl", padding: "md", surface: "muted", border: "default", children: [_jsx(Heading, { level: 3, size: "sm", weight: "semibold", color: "muted", className: "mb-3", children: "Tracking" }), _jsx(Stack, { gap: "none", children: steps.map((step, i) => {
-                    const isLast = i === steps.length - 1;
-                    const isNegative = step.key === "cancelled";
-                    return (_jsxs(Row, { gap: "sm", padding: isLast ? "none" : "b-md", children: [_jsxs(Stack, { gap: "none", align: "center", className: "shrink-0", children: [_jsx(Div, { className: `h-2.5 w-2.5 ${isNegative ? "" : "bg-[var(--appkit-color-primary)]"}`, rounded: "full", surface: isNegative ? "danger-surface" : "none" }), !isLast && _jsx(Div, { className: "w-px flex-1 min-h-[24px]", surface: "subtle" })] }), _jsxs(Stack, { gap: "none", className: "min-w-0 flex-1", children: [_jsx(Text, { size: "sm", weight: "medium", className: isNegative ? "text-error" : undefined, children: step.label }), _jsx(Text, { size: "xs", color: "muted", children: step.date ? new Date(step.date).toLocaleString() : "—" })] })] }, step.key));
-                }) }), (trackingNumber || shippingCarrier || trackingUrl) && !isTerminalNegative && (_jsx(Div, { className: "mt-3 border-t border-[var(--appkit-color-border)]", padding: "t-sm", children: _jsxs(Stack, { gap: "xs", children: [shippingCarrier && (_jsxs(Row, { justify: "between", children: [_jsx(Text, { size: "sm", color: "muted", children: "Carrier" }), _jsx(Text, { size: "sm", weight: "medium", children: shippingCarrier })] })), trackingNumber && (_jsxs(Row, { justify: "between", children: [_jsx(Text, { size: "sm", color: "muted", children: "Tracking number" }), _jsx(Text, { size: "sm", weight: "medium", children: trackingNumber })] })), trackingUrl && (_jsx(Row, { justify: "end", children: _jsx(Anchor, { href: trackingUrl, tone: "brand", weight: "semibold", size: "sm", children: "Track with carrier \u2192" }) }))] }) })), !trackingNumber && !trackingUrl && !isTerminalNegative && (_jsx(Badge, { variant: "default", className: "mt-3", children: "No tracking details yet" }))] }));
+export function OrderStatusTimeline({ orderStatus, timeline, timelineTruncated, orderDate, shippingDate, deliveryDate, cancellationDate, trackingNumber, shippingCarrier, trackingUrl, className = "", }) {
+    const fromHistory = stepsFromEntries(timeline, labelFor, isNegative);
+    const steps = fromHistory.length
+        ? fromHistory
+        : buildLegacySteps({ orderStatus, orderDate, shippingDate, deliveryDate, cancellationDate });
+    const hasTracking = Boolean(trackingNumber || shippingCarrier || trackingUrl);
+    return (_jsx(StatusTimeline, { title: "Tracking", steps: steps, truncatedCount: timelineTruncated, className: className, footer: hasTracking ? (_jsxs(Stack, { gap: "xs", children: [shippingCarrier && (_jsxs(Row, { justify: "between", children: [_jsx(Text, { size: "sm", color: "muted", children: "Carrier" }), _jsx(Text, { size: "sm", weight: "medium", children: shippingCarrier })] })), trackingNumber && (_jsxs(Row, { justify: "between", children: [_jsx(Text, { size: "sm", color: "muted", children: "Tracking number" }), _jsx(Text, { size: "sm", weight: "medium", children: trackingNumber })] })), trackingUrl && (_jsx(Row, { justify: "end", children: _jsx(Anchor, { href: trackingUrl, tone: "brand", weight: "semibold", size: "sm", children: "Track with carrier \u2192" }) }))] })) : (_jsx(Badge, { variant: "default", children: "No tracking details yet" })) }));
 }

package/dist/features/orders/constants/order-scope.d.ts

@@ -0,0 +1,48 @@
+import type { OrderStatus } from "../types/index";
+import { OrderStatusValues } from "../schemas/firestore";
+export declare const ORDER_SCOPE_VALUES: {
+    /** Still moving — someone (buyer, seller or admin) has something to do. */
+    readonly ACTIVE: "active";
+    /** Terminal — delivered, cancelled, refunded or returned. */
+    readonly CLOSED: "closed";
+    /** No lifecycle predicate. */
+    readonly ALL: "all";
+};
+export type OrderScope = (typeof ORDER_SCOPE_VALUES)[keyof typeof ORDER_SCOPE_VALUES];
+export declare function isOrderScope(value: string): value is OrderScope;
+/**
+ * The statuses a scope covers, or `undefined` for "all" (no filter).
+ *
+ * Emitted as a pipe-joined OR-group, which the Firebase Sieve adapter upgrades
+ * to a single Firestore "in" query — no fan-out, and it reuses the existing
+ * (status, createdAt) composite index.
+ */
+export declare function statusesForScope(scope: OrderScope): OrderStatus[] | undefined;
+/**
+ * Tab definitions for the scope bar.
+ *
+ * NOT registered in `audit-filter-tab-enums.mjs`'s REGISTRY, and deliberately
+ * so — the same reasoning its header gives for `ADMIN_ORDER_PAYMENT_REVIEW_TABS`
+ * and `ADMIN_CART_OWNERSHIP_TABS`. These ids are a DERIVED grouping, not values
+ * any Firestore field holds, so there is no backing enum to compare them
+ * against. `STATUS_SCOPE` above is what keeps them honest instead, at compile
+ * time.
+ */
+export declare const ORDER_SCOPE_TABS: readonly {
+    id: OrderScope;
+    label: string;
+}[];
+/**
+ * Fold the lifecycle scope into a caller-supplied Sieve filter string.
+ *
+ * Shared by all three order list routes rather than written three times —
+ * partly for the usual reason, but mostly because of the guard: if `filters`
+ * already carries a `status==` clause, the scope must NOT add a second one.
+ * Two equality clauses on one field are AND-ed by Sieve, and no document can
+ * satisfy both, so the list would silently return zero rows (the failure mode
+ * documented in Root Cause #59). An explicit status wins; the scope only fills
+ * the gap when the caller named none.
+ */
+export declare function mergeOrderScopeFilter(filters: string | undefined | null, scopeParam: string | undefined | null): string | undefined;
+/** Re-exported for callers that need the raw values alongside the scope. */
+export { OrderStatusValues };

package/dist/features/orders/constants/order-scope.js

@@ -0,0 +1,111 @@
+/*
+ * WHY: Filtering orders meant picking one of seven individual statuses, on
+ *      every order dashboard. The overwhelmingly common questions — "what still
+ *      needs someone to act on it" and "what is finished" — had no answer at
+ *      all, and the per-view status arrays had drifted from the real union
+ *      anyway (`SELLER_ORDER_STATUS_TABS` omitted `confirmed`, a status the
+ *      seller's own Update-Status dropdown could SET, so a seller could put an
+ *      order into a state they could then never filter for).
+ *
+ * WHAT: A lifecycle scope — Active / Closed / All — that groups the nine real
+ *       statuses. The buyer, seller and admin order lists all render the same
+ *       three tabs, and the detailed status chips remain underneath as the
+ *       drill-down.
+ *
+ * EXPORTS: ORDER_SCOPE_VALUES, OrderScope, isOrderScope, statusesForScope,
+ *          ORDER_SCOPE_TABS
+ *
+ * @tag domain:orders
+ * @tag layer:constants
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:AdminOrdersView,SellerOrdersView,UserOrdersView,api/user/orders
+ * @tag sideEffects:none
+ */
+import { OrderStatusValues } from "../schemas/firestore";
+export const ORDER_SCOPE_VALUES = {
+    /** Still moving — someone (buyer, seller or admin) has something to do. */
+    ACTIVE: "active",
+    /** Terminal — delivered, cancelled, refunded or returned. */
+    CLOSED: "closed",
+    /** No lifecycle predicate. */
+    ALL: "all",
+};
+export function isOrderScope(value) {
+    return Object.values(ORDER_SCOPE_VALUES).includes(value);
+}
+/**
+ * Every status belongs to exactly one scope.
+ *
+ * `Record<OrderStatus, …>` on purpose: adding a tenth status is then a COMPILE
+ * error rather than a status that silently belongs to neither tab and
+ * disappears from both (Root Cause #61).
+ */
+const STATUS_SCOPE = {
+    pending: "active",
+    confirmed: "active",
+    processing: "active",
+    shipped: "active",
+    // Deliberately ACTIVE: a return request is the seller's next action item,
+    // not a finished order. Grouping it under Closed would bury exactly the
+    // rows a seller most needs to see.
+    return_requested: "active",
+    delivered: "closed",
+    cancelled: "closed",
+    refunded: "closed",
+    returned: "closed",
+};
+/**
+ * The statuses a scope covers, or `undefined` for "all" (no filter).
+ *
+ * Emitted as a pipe-joined OR-group, which the Firebase Sieve adapter upgrades
+ * to a single Firestore "in" query — no fan-out, and it reuses the existing
+ * (status, createdAt) composite index.
+ */
+export function statusesForScope(scope) {
+    if (scope === ORDER_SCOPE_VALUES.ALL)
+        return undefined;
+    return Object.keys(STATUS_SCOPE).filter((status) => STATUS_SCOPE[status] === scope);
+}
+/**
+ * Tab definitions for the scope bar.
+ *
+ * NOT registered in `audit-filter-tab-enums.mjs`'s REGISTRY, and deliberately
+ * so — the same reasoning its header gives for `ADMIN_ORDER_PAYMENT_REVIEW_TABS`
+ * and `ADMIN_CART_OWNERSHIP_TABS`. These ids are a DERIVED grouping, not values
+ * any Firestore field holds, so there is no backing enum to compare them
+ * against. `STATUS_SCOPE` above is what keeps them honest instead, at compile
+ * time.
+ */
+export const ORDER_SCOPE_TABS = [
+    { id: ORDER_SCOPE_VALUES.ACTIVE, label: "Active" },
+    { id: ORDER_SCOPE_VALUES.CLOSED, label: "Closed" },
+    { id: ORDER_SCOPE_VALUES.ALL, label: "All" },
+];
+/**
+ * Fold the lifecycle scope into a caller-supplied Sieve filter string.
+ *
+ * Shared by all three order list routes rather than written three times —
+ * partly for the usual reason, but mostly because of the guard: if `filters`
+ * already carries a `status==` clause, the scope must NOT add a second one.
+ * Two equality clauses on one field are AND-ed by Sieve, and no document can
+ * satisfy both, so the list would silently return zero rows (the failure mode
+ * documented in Root Cause #59). An explicit status wins; the scope only fills
+ * the gap when the caller named none.
+ */
+export function mergeOrderScopeFilter(filters, scopeParam) {
+    const existing = (filters ?? "").trim();
+    if (!scopeParam || !isOrderScope(scopeParam))
+        return existing || undefined;
+    if (/(^|,)\s*status\s*==/.test(existing))
+        return existing || undefined;
+    const statuses = statusesForScope(scopeParam);
+    if (!statuses?.length)
+        return existing || undefined;
+    // A pipe-joined OR-group on ONE field — the Firebase Sieve adapter upgrades
+    // it to a single Firestore "in" query rather than several.
+    const clause = `status==${statuses.join("|")}`;
+    return existing ? `${existing},${clause}` : clause;
+}
+/** Re-exported for callers that need the raw values alongside the scope. */
+export { OrderStatusValues };

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

@@ -2,8 +2,27 @@ import type { DocumentReference, WriteBatch } from "firebase-admin/firestore";
 import type { FirebaseSieveResult, SieveModel } from "../../../providers/db-firebase";
 import { BaseRepository, parseSieveDateValue } from "../../../providers/db-firebase";
 import { type OrderCreateInput, type OrderDocument, type OrderRefundEvent } from "../schemas";
+import { type HistoryActor, type FieldChange } from "../../../_internal/shared/history/index";
 import type { OrderStatus, PaymentStatus } from "../types";
 import { type PaymentReviewQueueMode } from "../constants/payment-window";
+/**
+ * Who/why for a write that lands in `statusHistory`.
+ *
+ * Optional everywhere so existing callers keep compiling and record
+ * `system`; pass it wherever the acting user is known.
+ */
+export interface OrderWriteContext {
+    actor?: HistoryActor;
+    /** Overrides the default trigger label with the calling function's name. */
+    trigger?: string;
+    reason?: string;
+    note?: string;
+    /**
+     * Changes the field diff cannot express — used by `postRefundEvent` to put
+     * the refund itself on the timeline rather than an array-length delta.
+     */
+    extraChanges?: Record<string, FieldChange>;
+}
 declare class OrderRepository extends BaseRepository<OrderDocument> {
     constructor();
     private decryptOrder;
@@ -15,10 +34,23 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
     findByStatus(status: OrderStatus): Promise<OrderDocument[]>;
     findConfirmed(): Promise<OrderDocument[]>;
     findPending(): Promise<OrderDocument[]>;
-    updateStatus(orderId: string, status: OrderStatus, additionalData?: Partial<OrderDocument>): Promise<OrderDocument>;
+    /**
+     * Every write primitive below routes through this so `statusHistory` is
+     * appended at the SEVEN places a tracked field can change, rather than at
+     * the ~32 call sites above them. That is what makes order history a
+     * contained change instead of a codebase-wide sweep — and it follows the
+     * precedent `postRefundEvent` already set for append-only order data.
+     *
+     * `ctx` is optional throughout: a caller that has not been updated yet
+     * records `system` rather than failing, so this rolls out incrementally.
+     * The actor is worth passing wherever it is known — a history entry that
+     * cannot say who cancelled an order is a much weaker record.
+     */
+    private updateWithHistory;
+    updateStatus(orderId: string, status: OrderStatus, additionalData?: Partial<OrderDocument>, ctx?: OrderWriteContext): Promise<OrderDocument>;
     assignWorker(orderId: string, workerId: string): Promise<OrderDocument>;
     unassignWorker(orderId: string): Promise<OrderDocument>;
-    markPicked(orderId: string): Promise<OrderDocument>;
+    markPicked(orderId: string, ctx?: OrderWriteContext): Promise<OrderDocument>;
     markPacked(orderId: string): Promise<OrderDocument>;
     /**
      * Payment Detail Parity (Feature C) — the COD counterpart to the manual
@@ -27,10 +59,10 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
      * verify against, so `verifiedBy` is the acting user's uid and
      * `verificationMethod` is always "cod_collection".
      */
-    markCodCollected(orderId: string, verifiedBy: string, note?: string): Promise<OrderDocument>;
+    markCodCollected(orderId: string, verifiedBy: string, note?: string, ctx?: OrderWriteContext): Promise<OrderDocument>;
     findFulfillmentQueue(storeId: string): Promise<OrderDocument[]>;
-    updatePaymentStatus(orderId: string, paymentStatus: PaymentStatus, paymentId?: string): Promise<OrderDocument>;
-    cancelOrder(orderId: string, reason: string, refundAmount?: number): Promise<OrderDocument>;
+    updatePaymentStatus(orderId: string, paymentStatus: PaymentStatus, paymentId?: string, ctx?: OrderWriteContext): Promise<OrderDocument>;
+    cancelOrder(orderId: string, reason: string, refundAmount?: number, ctx?: OrderWriteContext): Promise<OrderDocument>;
     findRecentByUser(userId: string): Promise<OrderDocument[]>;
     hasUserPurchased(userId: string, productId: string): Promise<boolean>;
     /**
@@ -217,7 +249,7 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
      * Append one refund event to the order and mark it non-contestable.
      * If `becomeRefunded` is true, also transitions the order status to "refunded".
      */
-    postRefundEvent(orderId: string, event: OrderRefundEvent, becomeRefunded?: boolean): Promise<OrderDocument>;
+    postRefundEvent(orderId: string, event: OrderRefundEvent, becomeRefunded?: boolean, ctx?: OrderWriteContext): Promise<OrderDocument>;
     /** Fetch all orders sharing a paymentBatchId (for sibling-orders display). */
     findByPaymentBatchId(batchId: string): Promise<OrderDocument[]>;
     /**
@@ -327,8 +359,23 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
     markPayoutRequested(batch: WriteBatch, ref: DocumentReference, payoutId: string): void;
     /**
      * Cloud Functions: stage a cancellation update into a caller-owned WriteBatch.
+     *
+     * `fromStatus` is supplied by the caller because a batch write does no read
+     * — but the sweep that calls this already filtered on a status, so it knows
+     * the value. Passing it beats recording `null` for something that is
+     * genuinely known one stack frame up.
+     */
+    cancelInBatch(batch: WriteBatch, ref: DocumentReference, fromStatus?: OrderStatus | null): void;
+    /**
+     * History append for the two WriteBatch paths, which cannot read-then-diff.
+     *
+     * Uses `arrayUnion` so the entry lands without a prior read. The FIFO cap
+     * therefore is NOT applied here — it is enforced on the next ordinary
+     * write. That is an acceptable trade: both batch paths are terminal
+     * transitions (cancelled, payout-requested) that fire at most once per
+     * order, so they cannot be what overflows the array.
      */
-    cancelInBatch(batch: WriteBatch, ref: DocumentReference): void;
+    private batchHistoryPatch;
 }
 declare const orderRepository: OrderRepository;
 export { OrderRepository, orderRepository };