@mohasinac/appkit 4.60.0 → 4.61.0

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

@@ -17,6 +17,22 @@ export interface EventDocument extends BaseDocument {
     title: string;
     description: string;
     status: EventStatus;
+    /**
+     * Lift this event to the top of `/events` and the homepage rail, ahead of
+     * the `startsAt` ASC default.
+     *
+     * 🛑 DELIBERATELY NOT IN `EVENT_INDEXED_FIELDS` AND NOT SORTABLE IN SIEVE.
+     * A Firestore `orderBy` EXCLUDES every document that lacks the ordering
+     * field (Root Cause #100), and `isPinned` is absent from all 1 live event
+     * and every seeded row that is not pinned — so ordering by it would empty
+     * the events page entirely while answering HTTP 200. The ordering is
+     * applied in memory by `sortPinnedFirst`; see the bound stated there.
+     *
+     * Absent means not pinned. Do not default it to `false` on write — a
+     * written `false` and an absent field must stay interchangeable, because
+     * every event that predates this field has the latter.
+     */
+    isPinned?: boolean;
     /** Test-data flag — set on the shared admin-seeded test event; swept by testDataCleanup. */
     isTestData?: boolean;
     /** When isTestData, the cutoff after which testDataCleanup deletes this doc. */
@@ -134,6 +150,7 @@ export declare const EVENT_FIELDS: {
     readonly WINNER_IMAGES: "winnerImages";
     readonly ADDITIONAL_IMAGES: "additionalImages";
     readonly TAGS: "tags";
+    readonly IS_PINNED: "isPinned";
     readonly ALLOW_GUEST_PARTICIPATION: "allowGuestParticipation";
     readonly CREATED_BY: "createdBy";
     readonly CREATED_AT: "createdAt";

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

@@ -38,6 +38,7 @@ export const EVENT_FIELDS = {
     WINNER_IMAGES: "winnerImages",
     ADDITIONAL_IMAGES: "additionalImages",
     TAGS: "tags",
+    IS_PINNED: "isPinned",
     ALLOW_GUEST_PARTICIPATION: "allowGuestParticipation",
     CREATED_BY: "createdBy",
     CREATED_AT: "createdAt",

package/dist/features/events/utils/sort-pinned.d.ts

@@ -0,0 +1,33 @@
+/** Just the part of an event this ordering reads. */
+export interface PinnableEvent {
+    isPinned?: boolean;
+}
+/**
+ * Lift pinned events to the front, preserving the relative order of both
+ * groups.
+ *
+ * 🛑 WHY THIS IS IN MEMORY AND NOT AN `orderBy`. Firestore's `orderBy`
+ * excludes every document that lacks the ordering field (Root Cause #100), and
+ * `isPinned` is absent from every event that is not pinned — which is all of
+ * them bar one. Sorting on it in the query would return an events page
+ * containing only the pinned row, with no error and a 200, and the failure
+ * reads as "the other events were deleted" rather than as a bad sort.
+ *
+ * A boolean is also a one-bit sort key, so it would need a composite index
+ * paired with `startsAt` for every filter combination the page offers, to buy
+ * an ordering a single pass over at most `pageSize` rows already gives.
+ *
+ * 🛑 THE BOUND, STATED RATHER THAN IMPLIED: this reorders WITHIN the page it
+ * is handed. A pinned event that falls on page 3 of a paginated result is
+ * lifted to the top of page 3, not onto page 1. That is sufficient while the
+ * whole catalogue fits one page — live holds 1 event against a pageSize of
+ * 24, and the homepage rail asks for 6 — and it is the reason to revisit this
+ * if events ever outgrow a single page. The fix then is a second bounded
+ * query on `isPinned == true` (an EQUALITY, which is index-friendly and does
+ * not have the missing-field problem an `orderBy` has) merged ahead of the
+ * main result, not an `orderBy` on this field.
+ *
+ * `Array.prototype.sort` is specified as stable, so the comparator only needs
+ * to express the pinned/unpinned difference to leave everything else alone.
+ */
+export declare function sortPinnedFirst<T extends PinnableEvent>(items: readonly T[]): T[];

package/dist/features/events/utils/sort-pinned.js

@@ -0,0 +1,46 @@
+/*
+ * WHY: One implementation of "pinned events come first", shared by the two
+ *      surfaces that render an event list.
+ * WHAT: `sortPinnedFirst` — a stable partition on `EventDocument.isPinned`.
+ *
+ * EXPORTS:
+ *   sortPinnedFirst — readonly T[] -> T[], pinned first, order otherwise kept
+ *
+ * @tag domain:events
+ * @tag layer:util
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:features/events/components/EventsListPageView.tsx,features/events/actions/event-actions.ts
+ * @tag sideEffects:none
+ */
+/**
+ * Lift pinned events to the front, preserving the relative order of both
+ * groups.
+ *
+ * 🛑 WHY THIS IS IN MEMORY AND NOT AN `orderBy`. Firestore's `orderBy`
+ * excludes every document that lacks the ordering field (Root Cause #100), and
+ * `isPinned` is absent from every event that is not pinned — which is all of
+ * them bar one. Sorting on it in the query would return an events page
+ * containing only the pinned row, with no error and a 200, and the failure
+ * reads as "the other events were deleted" rather than as a bad sort.
+ *
+ * A boolean is also a one-bit sort key, so it would need a composite index
+ * paired with `startsAt` for every filter combination the page offers, to buy
+ * an ordering a single pass over at most `pageSize` rows already gives.
+ *
+ * 🛑 THE BOUND, STATED RATHER THAN IMPLIED: this reorders WITHIN the page it
+ * is handed. A pinned event that falls on page 3 of a paginated result is
+ * lifted to the top of page 3, not onto page 1. That is sufficient while the
+ * whole catalogue fits one page — live holds 1 event against a pageSize of
+ * 24, and the homepage rail asks for 6 — and it is the reason to revisit this
+ * if events ever outgrow a single page. The fix then is a second bounded
+ * query on `isPinned == true` (an EQUALITY, which is index-friendly and does
+ * not have the missing-field problem an `orderBy` has) merged ahead of the
+ * main result, not an `orderBy` on this field.
+ *
+ * `Array.prototype.sort` is specified as stable, so the comparator only needs
+ * to express the pinned/unpinned difference to leave everything else alone.
+ */
+export function sortPinnedFirst(items) {
+    return [...items].sort((a, b) => Number(b.isPinned === true) - Number(a.isPinned === true));
+}

package/dist/features/gateway-events/repository/gateway-events.repository.js

@@ -1,46 +1,9 @@
+// One shared predicate — this file had its own copy; see firestore-codes.ts.
+import { isAlreadyExistsError } from "../../../errors/firestore-codes.js";
 import { BaseRepository, applySieveToFirestore, parseSieveDateValue, prepareForFirestore, } from "../../../providers/db-firebase/index.js";
 import { normalizeError } from "../../../errors/normalize.js";
 import { GATEWAY_EVENTS_COLLECTION, GATEWAY_EVENT_ERROR_MAX_BYTES, GATEWAY_EVENT_FIELDS, GATEWAY_EVENT_LEASE_SECONDS, GATEWAY_EVENT_RETENTION_DAYS, createGatewayEventId, } from "../schemas/firestore.js";
 /** gRPC `ALREADY_EXISTS`. The one failure of `.create()` that means "duplicate". */
-const GRPC_ALREADY_EXISTS = 6;
-/**
- * Is this the specific "a document with that id already exists" failure, as
- * opposed to any other write failure?
- *
- * 🛑 THIS DISTINCTION IS THE WHOLE POINT, and it is where the inbox differs
- * from every other `.create()` claim in the codebase.
- *
- * `refunds/actions.ts` catches *every* error from its claim and treats it as a
- * duplicate — and that is correct THERE, because the cost of being wrong is
- * issuing a second real refund, so it must fail CLOSED.
- *
- * Here the cost of being wrong is inverted: treating a permissions error or a
- * Firestore outage as "already have it" would make the route ack 200 and the
- * event would be **silently lost** — which is the exact failure this collection
- * exists to prevent. So the inbox fails OPEN: anything that is not
- * ALREADY_EXISTS propagates, the route answers 503, and the gateway sends it
- * again.
- *
- * Same primitive, opposite failure direction, because the asymmetry of harm is
- * opposite. Do not "unify" these two call sites.
- */
-function isAlreadyExists(err) {
-    if (typeof err !== "object" || err === null)
-        return false;
-    const code = err.code;
-    if (code === GRPC_ALREADY_EXISTS)
-        return true;
-    /*
-     * The Admin SDK has also surfaced this as a string code and as a plain
-     * message depending on version and transport. Checked in addition to, never
-     * instead of, the numeric code — a message test alone is the kind of
-     * stringly-typed guard that breaks silently on an SDK bump.
-     */
-    if (code === "already-exists" || code === "ALREADY_EXISTS")
-        return true;
-    const message = err.message;
-    return typeof message === "string" && message.includes("ALREADY_EXISTS");
-}
 function truncate(value, maxBytes) {
     if (!value)
         return undefined;
@@ -86,7 +49,7 @@ export class GatewayEventsRepository extends BaseRepository {
             return { claimed: true, id, doc };
         }
         catch (err) {
-            if (isAlreadyExists(err)) {
+            if (isAlreadyExistsError(err)) {
                 void normalizeError(err);
                 return { claimed: false, id };
             }

package/dist/features/gateway-events/schemas/index.d.ts

@@ -34,12 +34,12 @@ export declare const gatewayEventFirestoreSchema: z.ZodObject<{
     createdAt: Date;
     updatedAt: Date;
     expiresAt: Date;
+    claimedAt: Date;
     gateway: string;
     receivedAt: Date;
     attempts: number;
     bodySha256: string;
     leaseExpiresAt: Date;
-    claimedAt: Date;
     rawEvent: string;
     terminal?: boolean | undefined;
     amount?: number | undefined;
@@ -59,12 +59,12 @@ export declare const gatewayEventFirestoreSchema: z.ZodObject<{
     createdAt: Date;
     updatedAt: Date;
     expiresAt: Date;
+    claimedAt: Date;
     gateway: string;
     receivedAt: Date;
     attempts: number;
     bodySha256: string;
     leaseExpiresAt: Date;
-    claimedAt: Date;
     rawEvent: string;
     terminal?: boolean | undefined;
     amount?: number | undefined;

package/dist/features/inventory/components/AdminStorageBoxesView.js

@@ -16,9 +16,10 @@ import { Button, Div, Form, FieldInput, FieldSelect, Stack, Text } from "../../.
 import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints.js";
 import { apiClient } from "../../../http/index.js";
 import { sortBy } from "../../../constants/sort.js";
+import { normalizeError } from "../../../errors/normalize.js";
 import { sieveFilter, SIEVE_OP } from "../../../utils/sieve-builder.js";
 import { operatorMessage } from "./operator-message.js";
-import { BoxTypeValues } from "../schemas/firestore.js";
+import { BoxTypeValues, STORAGE_BOX_FIELDS, } from "../schemas/firestore.js";
 const TYPE_OPTIONS = BoxTypeValues.map((v) => ({ value: v, label: v }));
 /**
  * The register-a-box form.
@@ -26,47 +27,58 @@ const TYPE_OPTIONS = BoxTypeValues.map((v) => ({ value: v, label: v }));
  * Exported because it is a PAGE now, not a drawer — see the note on
  * `primaryAction` below for why create could not share the row affordance.
  */
+// audit-form-sectionised-ok: a three-field quick create (code, type, location),
+// not a multi-section editor. <SectionForm> derives its sections from a schema
+// and pins a mobile action bar for a long scroll; neither has anything to do
+// here, and sections of one field each would be chrome around three inputs.
 export function RegisterBoxForm({ onCreated }) {
     const [code, setCode] = React.useState("");
     const [boxType, setBoxType] = React.useState(BoxTypeValues[0]);
     const [location, setLocation] = React.useState("");
     const [busy, setBusy] = React.useState(false);
-    return (_jsx(Form, { onSubmit: (e) => e.preventDefault(), className: "space-y-4", children: ({ setFieldError, clearErrors }) => (_jsxs(Stack, { gap: "md", children: [_jsx(FieldInput, { name: "code", label: "Box code", required: true, value: code, onChange: setCode, placeholder: "AC60-03", hint: "Exactly what is written on the physical label." }), _jsx(FieldSelect, { name: "boxType", label: "Box type", value: boxType, onChange: setBoxType, options: TYPE_OPTIONS }), _jsx(FieldInput, { name: "location", label: "Where it is", value: location, onChange: setLocation, placeholder: "Shelf B, second from top" }), _jsx(Text, { size: "xs", color: "muted", children: "A second box with the same code is the same box \u2014 the registry refuses a duplicate rather than merging two." }), _jsx(Div, { children: _jsx(Button, { type: "submit", variant: "primary", isLoading: busy, onClick: async () => {
-                            clearErrors();
-                            if (!code.trim()) {
-                                setFieldError("code", "A box needs a code");
-                                return;
-                            }
-                            setBusy(true);
-                            try {
-                                await apiClient.post(ADMIN_ENDPOINTS.INVENTORY_BOXES, {
-                                    code: code.trim(),
-                                    boxType,
-                                    ...(location.trim() ? { location: location.trim() } : {}),
-                                });
-                                onCreated();
-                            }
-                            catch (err) {
-                                /*
-                                 * 🛑 `operatorMessage`, not a raw fallback. This read
-                                 * `toUserMessage(undefined, undefined, { fallback: e.message })`
-                                 * under a comment claiming it never showed server text —
-                                 * which is false twice over: `undefined` for the code means
-                                 * the map never runs, so the fallback is ALWAYS what shows.
-                                 * A comment asserting the fix while the code reintroduces the
-                                 * bug is how Root Cause #86 would come back, and how the seed
-                                 * `listingType` bug survived its own fix one field over.
-                                 *
-                                 * The split is on status: the 409 here ("Box AC60-03 already
-                                 * exists") is authored for this operator and must survive; a
-                                 * 5xx terminates in a constant.
-                                 */
-                                setFieldError("code", operatorMessage(err));
-                            }
-                            finally {
-                                setBusy(false);
-                            }
-                        }, children: "Register box" }) })] })) }));
+    /*
+     * Lifted out of the submit button's `onClick`, where it sat five braces deep
+     * inside the render-prop's JSX. The two `<Form>` helpers arrive as arguments
+     * rather than being captured, which is what lets this live in the component
+     * body beside the state it writes.
+     */
+    const submitBox = async (setFieldError, clearErrors) => {
+        clearErrors();
+        if (!code.trim()) {
+            setFieldError("code", "A box needs a code");
+            return;
+        }
+        setBusy(true);
+        try {
+            await apiClient.post(ADMIN_ENDPOINTS.INVENTORY_BOXES, {
+                code: code.trim(),
+                boxType,
+                ...(location.trim() ? { location: location.trim() } : {}),
+            });
+            onCreated();
+        }
+        catch (err) {
+            /*
+             * 🛑 `operatorMessage`, not a raw fallback. This read
+             * `toUserMessage(undefined, undefined, { fallback: e.message })`
+             * under a comment claiming it never showed server text — which is
+             * false twice over: `undefined` for the code means the map never
+             * runs, so the fallback is ALWAYS what shows. A comment asserting
+             * the fix while the code reintroduces the bug is how Root Cause #86
+             * would come back, and how the seed `listingType` bug survived its
+             * own fix one field over.
+             *
+             * The split is on status: the 409 here ("Box AC60-03 already
+             * exists") is authored for this operator and must survive; a 5xx
+             * terminates in a constant.
+             */
+            setFieldError("code", operatorMessage(normalizeError(err)));
+        }
+        finally {
+            setBusy(false);
+        }
+    };
+    return (_jsx(Form, { onSubmit: (e) => e.preventDefault(), className: "space-y-4", children: ({ setFieldError, clearErrors }) => (_jsxs(Stack, { gap: "md", children: [_jsx(FieldInput, { name: "code", label: "Box code", required: true, value: code, onChange: setCode, placeholder: "AC60-03", hint: "Exactly what is written on the physical label." }), _jsx(FieldSelect, { name: "boxType", label: "Box type", value: boxType, onChange: setBoxType, options: TYPE_OPTIONS }), _jsx(FieldInput, { name: "location", label: "Where it is", value: location, onChange: setLocation, placeholder: "Shelf B, second from top" }), _jsx(Text, { size: "xs", color: "muted", children: "A second box with the same code is the same box \u2014 the registry refuses a duplicate rather than merging two." }), _jsx(Div, { children: _jsx(Button, { type: "submit", variant: "primary", isLoading: busy, onClick: () => submitBox(setFieldError, clearErrors), children: "Register box" }) })] })) }));
 }
 export function AdminStorageBoxesView() {
     const config = React.useMemo(() => ({
@@ -109,9 +121,13 @@ export function AdminStorageBoxesView() {
          * AC60-2 — the kind of ordering that makes an operator distrust the
          * screen — which is why `ordinal` is denormalised on write.
          */
-        defaultSort: "ordinal",
+        defaultSort: sortBy(STORAGE_BOX_FIELDS.ORDINAL, "ASC"),
         sortOptions: [
-            { value: "ordinal", label: "Box number" },
+            // Same expression as `defaultSort`, not a matching literal beside it —
+            // `sortBy(f, "ASC")` is the bare field, so the two are identical by
+            // construction. A default that is not one of the options opens the
+            // dropdown with nothing selected (Root Cause #63).
+            { value: sortBy(STORAGE_BOX_FIELDS.ORDINAL, "ASC"), label: "Box number" },
             { value: sortBy("createdAt", "DESC"), label: "Newest" },
             { value: sortBy("code", "ASC"), label: "Code A–Z" },
         ],

package/dist/features/inventory/components/ReceiveStationView.js

@@ -31,6 +31,8 @@ import { apiClient } from "../../../http/index.js";
 import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints.js";
 import { ROUTES } from "../../../next/routing/route-map.js";
 import { operatorMessage } from "./operator-message.js";
+import { normalizeError } from "../../../errors/normalize.js";
+import { trackError, ErrorCategory, ErrorSeverity, } from "../../../monitoring/error-tracking.js";
 import { MAX_RECEIVE_ROWS } from "../schemas/firestore.js";
 /** `boxId::productId` — the staging table's natural key, mirroring `placementId`. */
 function rowKey(boxId, productId) {
@@ -67,6 +69,21 @@ export function ReceiveStationView({ shipmentId, shipmentNumber, items, unlinked
         rowsRef.current = computed;
         setRows(computed);
     }
+    /**
+     * Drop one staged row. Named rather than inline in the table's Remove
+     * button, where the updater's block body sat a brace too deep.
+     */
+    function removeRow(key) {
+        applyRows((c) => {
+            const next = { ...c };
+            delete next[key];
+            return next;
+        });
+    }
+    /** Set one staged row's quantity. Same reason as `removeRow`. */
+    function setRowQuantity(key, quantity) {
+        applyRows((c) => ({ ...c, [key]: { ...c[key], quantity } }));
+    }
     const [scan, setScan] = useState("");
     const [committing, setCommitting] = useState(false);
     /** The in-flight guard. State renders the spinner; this prevents the second send. */
@@ -197,6 +214,12 @@ export function ReceiveStationView({ shipmentId, shipmentNumber, items, unlinked
      * It runs only on a miss, so the common case stays instant and a box-arm is
      * roughly one scan in twenty anyway.
      */
+    /*
+     * Three outcomes, and the third is the point: `BoxOption` (found), `null`
+     * (asked, no such box), `undefined` (could not ask). The caller used to see
+     * only the first two and told the operator "No box registered as …" for a
+     * network failure.
+     */
     async function resolveBoxFromServer(code) {
         const bare = code.startsWith("BOX-") ? code.slice(4) : code;
         try {
@@ -206,10 +229,26 @@ export function ReceiveStationView({ shipmentId, shipmentNumber, items, unlinked
                 ? { id: hit.id, code: hit.code, location: hit.location ?? null }
                 : null;
         }
-        catch {
-            // A failed lookup must not masquerade as "no such box" — the caller
-            // distinguishes the two in what it tells the operator.
-            return null;
+        catch (err) {
+            /*
+             * 🛑 The predecessor comment here claimed "a failed lookup must not
+             * masquerade as 'no such box' — the caller distinguishes the two". It
+             * could not: the success path returns `null` on a miss and this returned
+             * the same `null`, so the two were indistinguishable by construction and
+             * a network failure WAS reported to the operator as an unrecognised
+             * code. That is the exact confusion the function's own header says it
+             * exists to prevent.
+             *
+             * Classified and recorded rather than swallowed, and `undefined` now
+             * means "could not ask" while `null` keeps meaning "asked, no such box".
+             */
+            const n = normalizeError(err);
+            trackError(n.message, ErrorCategory.API, ErrorSeverity.MEDIUM, {
+                component: "ReceiveStationView",
+                action: "resolveBoxFromServer",
+                metadata: { code: bare },
+            });
+            return undefined;
         }
     }
     async function handleScan(raw) {
@@ -235,10 +274,18 @@ export function ReceiveStationView({ shipmentId, shipmentNumber, items, unlinked
                 setLastScan({ text: `Armed ${fetched.code}`, tone: "ok" });
                 return;
             }
-            setLastScan({
-                text: `No box registered as ${code.slice(4)} — register it first`,
-                tone: "bad",
-            });
+            setLastScan(fetched === undefined
+                ? {
+                    // "Could not ask" — never "does not exist". The operator is
+                    // holding the box; telling them it is unregistered sends them
+                    // to re-register something that is already in the system.
+                    text: `Could not check ${code.slice(4)} — connection problem, scan again`,
+                    tone: "bad",
+                }
+                : {
+                    text: `No box registered as ${code.slice(4)} — register it first`,
+                    tone: "bad",
+                });
             return;
         }
         const item = byCode.get(code);
@@ -362,7 +409,11 @@ export function ReceiveStationView({ shipmentId, shipmentNumber, items, unlinked
             setLastScan({ text: "Committed. Carry on.", tone: "ok" });
         }
         catch (err) {
-            showToast(operatorMessage(err), "error");
+            // Normalized first: `operatorMessage` duck-types `.status`/`.code`/
+            // `.message`, and the api/app branches of `NormalizedError` carry exactly
+            // those three — so the 4xx passthrough still works and every other kind
+            // correctly falls through to a constant instead of server text.
+            showToast(operatorMessage(normalizeError(err)), "error");
         }
         finally {
             committingRef.current = false;
@@ -382,14 +433,7 @@ export function ReceiveStationView({ shipmentId, shipmentNumber, items, unlinked
                                         return (_jsxs(Tr, { children: [_jsx(Td, { children: _jsx(Badge, { variant: "info", children: r.boxCode }) }), _jsx(Td, { children: r.productTitle }), _jsx(Td, { children: _jsx(Text, { numeric: true, size: "sm", children: r.code ?? "—" }) }), _jsx(Td, { children: _jsx(QuantityStepper, { value: r.quantity, min: 1, max: 9999, 
                                                         // Many steppers on one page, so a bare "Quantity"
                                                         // names none of them.
-                                                        ariaLabel: `Quantity of ${r.productTitle} for ${r.boxCode}`, onChange: (n) => applyRows((c) => ({
-                                                            ...c,
-                                                            [key]: { ...c[key], quantity: n },
-                                                        })) }) }), _jsx(Td, { children: _jsx(Button, { variant: "ghost", onClick: () => applyRows((c) => {
-                                                            const next = { ...c };
-                                                            delete next[key];
-                                                            return next;
-                                                        }), children: "Remove" }) })] }, key));
+                                                        ariaLabel: `Quantity of ${r.productTitle} for ${r.boxCode}`, onChange: (n) => setRowQuantity(key, n) }) }), _jsx(Td, { children: _jsx(Button, { variant: "ghost", onClick: () => removeRow(key), children: "Remove" }) })] }, key));
                                     }) })] }))] }) }), _jsx(Card, { variant: "default", children: _jsxs(CardBody, { children: [_jsx(Heading, { level: 2, size: "lg", children: "Add by hand" }), items.length === 0 ? (_jsx(Text, { color: "muted", children: "No linked items on this shipment yet." })) : (_jsxs(Table, { children: [_jsx(Thead, { children: _jsxs(Tr, { children: [_jsx(Th, { children: "Item" }), _jsx(Th, { children: "Scan code" }), _jsx(Th, { children: "Expected" }), _jsx(Th, { children: "Add" })] }) }), _jsx(Tbody, { children: items.map((it) => (_jsxs(Tr, { children: [_jsx(Td, { children: it.productTitle }), _jsx(Td, { children: _jsx(Text, { numeric: true, size: "sm", children: it.barcodeId ??
                                                         it.sku ??
                                                         "no code yet — add by hand, or run the SKU backfill" }) }), _jsx(Td, { children: it.expectedQuantity }), _jsx(Td, { children: _jsx(Button, { variant: "outline", 

package/dist/features/inventory/repository/storage-boxes.repository.d.ts

@@ -37,7 +37,9 @@ export declare class StorageBoxesRepository extends BaseRepository<StorageBoxDoc
      * recurse, which is the entire reason for the choice.
      */
     setRollup(id: string, distinctProducts: number, totalUnits: number): Promise<void>;
-    listForAdmin(model: SieveModel): Promise<FirebaseSieveResult<StorageBoxDocument>>;
+    listForAdmin(model: SieveModel, opts?: {
+        search?: string;
+    }): Promise<FirebaseSieveResult<StorageBoxDocument>>;
     /** Every Timestamp field carries `parseSieveDateValue` — Root Cause #47. */
     static readonly SIEVE_FIELDS: {
         id: {

package/dist/features/inventory/repository/storage-boxes.repository.js

@@ -15,9 +15,13 @@
  * @tag access:server
  * @tag sideEffects:firestore
  */
-import { BaseRepository, parseSieveDateValue, } from "../../../providers/db-firebase/index.js";
+import { BaseRepository, parseSieveDateValue, applySieveToFirestore, } from "../../../providers/db-firebase/index.js";
 import { generateStorageBoxId } from "../../../utils/id-generators.js";
 import { buildStorageBoxSearchTxt } from "../../../utils/search-txt-builders.js";
+// The shared three — hand-writing them is how ten repositories each ended up
+// with two of the three, which reads as a working multi-word search and
+// silently cannot reach page 2.
+import { planSearchTxt, beginSearchWindow, emptySearchResult, } from "../../../utils/search-txt-query.js";
 import { BoxStatusValues, BoxTypeValues, STORAGE_BOXES_COLLECTION, STORAGE_BOX_FIELDS, } from "../schemas/firestore.js";
 /**
  * `AC60-03` → ordinal 3.
@@ -100,8 +104,37 @@ export class StorageBoxesRepository extends BaseRepository {
             updatedAt: new Date(),
         });
     }
-    async listForAdmin(model) {
-        return this.sieveQuery(model, StorageBoxesRepository.SIEVE_FIELDS, { defaultPageSize: 25, maxPageSize: 50 });
+    async listForAdmin(model, opts) {
+        /*
+         * 🛑 `searchTxt` HAD NO READER. `buildStorageBoxSearchTxt` wrote tokens on
+         * every create and update, `SIEVE_FIELDS` listed the field as filterable,
+         * and `AdminStorageBoxesView` rendered a search box promising "Search by
+         * code or location" — and this method ignored the term entirely. Typing in
+         * it returned the unfiltered list with a 200, which reads as "no box
+         * matches that" only if you already know the box exists.
+         *
+         * Same two-part shape as the other migrated collections: `plan.head` is
+         * one `array-contains` on the longest term, `plan.rest` is AND-refined in
+         * memory. Via `planSearchTxt` for the `empty` guard — a query that
+         * normalises to no usable token must return NOTHING, because emitting no
+         * clause returns the whole collection and calls it a search result.
+         */
+        const plan = planSearchTxt(opts?.search);
+        if (plan.empty)
+            return emptySearchResult();
+        if (!plan.head) {
+            return this.sieveQuery(model, StorageBoxesRepository.SIEVE_FIELDS, { defaultPageSize: 25, maxPageSize: 50 });
+        }
+        const baseQuery = this.getCollection().where(STORAGE_BOX_FIELDS.SEARCH_TXT, "array-contains", plan.head);
+        const win = beginSearchWindow(model, plan);
+        const result = await applySieveToFirestore({
+            baseQuery,
+            model: win.model,
+            options: { maxPageSize: win.maxPageSize(100) },
+            fields: StorageBoxesRepository.SIEVE_FIELDS,
+            mapDoc: (snap) => this.mapDoc(snap),
+        });
+        return win.finish(result);
     }
 }
 /** Every Timestamp field carries `parseSieveDateValue` — Root Cause #47. */

package/dist/features/obligations/repository/obligations.repository.js

@@ -1,5 +1,6 @@
 import { BaseRepository, prepareForFirestore } from "../../../providers/db-firebase/index.js";
 import { normalizeError } from "../../../errors/normalize.js";
+import { serverLogger } from "../../../monitoring/index.js";
 import { OBLIGATIONS_COLLECTION, OBLIGATION_ACTIVE_STATES, OBLIGATION_FIELDS, createObligationId, } from "../schemas/firestore.js";
 export class ObligationsRepository extends BaseRepository {
     /*
@@ -138,7 +139,15 @@ export class ObligationsRepository extends BaseRepository {
             });
         }
         catch (err) {
-            void normalizeError(err);
+            /*
+             * Best effort, but RECORDED. `void normalizeError(err)` alone types the
+             * error and reports it nowhere — as silent as `catch {}` while looking
+             * handled, which is what audit-silent-degrade calls normalize theatre.
+             * Swallowing is still correct here (a warning marker is a derived hint; the next order write reconciles again); losing the reason is not.
+             */
+            serverLogger.warn("obligations.warn failed", {
+                error: normalizeError(err).message,
+            });
         }
     }
     /** Refs for a subject's obligations — used when an order is hard-deleted. */

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

@@ -1080,6 +1080,25 @@ export declare const ORDER_COLLECTION: "orders";
  * only list it belongs in. (I added it to both first; R1 would have failed.)
  */
 export declare const REFUND_CLAIMS_COLLECTION: "refundClaims";
+/**
+ * Field names on a refund-claim row.
+ *
+ * 🛑 `STATE`, and it is NOT `ADDRESS_FIELDS.STATE`.
+ * `audit-route-nav-field-constants` R3 suggested exactly that for the raw
+ * `where("state", …)` in `paymentReconcile` — a POSTAL state, on an address.
+ * Borrowing it would have made a refund-claim sweep read as though it filtered
+ * addresses. The field names here are the claim's own lifecycle.
+ *
+ * The collection has no document interface (it is written ad hoc by
+ * `processRefundAction` as an idempotency record), so this is the only place
+ * its field names are stated.
+ */
+export declare const REFUND_CLAIM_FIELDS: {
+    /** `"claimed"` while a refund is in flight — the idempotency latch. */
+    readonly STATE: "state";
+    readonly CLAIMED_AT: "claimedAt";
+    readonly ORDER_ID: "orderId";
+};
 export declare const ORDER_INDEXED_FIELDS: readonly ["searchTxt", "userId", "productId", "storeId", "status", "paymentStatus", "payoutStatus", "shippingMethod", "orderDate", "createdAt", "assignedWorkerId", "pickedAt", "packedAt"];
 export declare const DEFAULT_ORDER_DATA: Partial<OrderDocument>;
 export declare const ORDER_PUBLIC_FIELDS: readonly ["id", "productId", "productTitle", "quantity", "unitPrice", "totalPrice", "currency", "status", "paymentStatus", "shippingAddress", "trackingNumber", "notes", "orderDate", "shippingDate", "deliveryDate", "createdAt"];

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

@@ -73,6 +73,25 @@ export const ORDER_COLLECTION = "orders";
  * only list it belongs in. (I added it to both first; R1 would have failed.)
  */
 export const REFUND_CLAIMS_COLLECTION = "refundClaims";
+/**
+ * Field names on a refund-claim row.
+ *
+ * 🛑 `STATE`, and it is NOT `ADDRESS_FIELDS.STATE`.
+ * `audit-route-nav-field-constants` R3 suggested exactly that for the raw
+ * `where("state", …)` in `paymentReconcile` — a POSTAL state, on an address.
+ * Borrowing it would have made a refund-claim sweep read as though it filtered
+ * addresses. The field names here are the claim's own lifecycle.
+ *
+ * The collection has no document interface (it is written ad hoc by
+ * `processRefundAction` as an idempotency record), so this is the only place
+ * its field names are stated.
+ */
+export const REFUND_CLAIM_FIELDS = {
+    /** `"claimed"` while a refund is in flight — the idempotency latch. */
+    STATE: "state",
+    CLAIMED_AT: "claimedAt",
+    ORDER_ID: "orderId",
+};
 export const ORDER_INDEXED_FIELDS = [
     "searchTxt",
     "userId",

package/dist/features/payment-cases/repository/payment-cases.repository.d.ts

@@ -2,6 +2,7 @@ import type { DocumentReference } from "firebase-admin/firestore";
 import type { FirebaseSieveFields, FirebaseSieveResult, SieveModel } from "../../../providers/db-firebase";
 import { BaseRepository } from "../../../providers/db-firebase";
 import { type PaymentCaseDocument, type PaymentCaseKind, type PaymentCaseSeverity, type PaymentCaseStatus } from "../schemas/firestore";
+/** gRPC `ALREADY_EXISTS` — the one `.create()` failure meaning "we have it". */
 export interface OpenCaseInput {
     kind: PaymentCaseKind;
     /** Identifies THE PROBLEM, not the observation — see `createPaymentCaseId`. */