@mohasinac/appkit 4.62.1 → 4.63.0

package/dist/_internal/server/features/checkout/expand-order-items.d.ts

@@ -19,8 +19,7 @@
  */
 import type { CartItemDocument } from "../../../../features/cart/schemas/firestore";
 import type { ProductDocument } from "../../../../features/products/schemas/firestore";
-import type { OrderDocumentItem } from "../../../../features/orders/schemas/firestore";
-/** A row before rule decoration — the shape `decorateOrderItem` receives. */
+import { type OrderDocumentItem } from "../../../../features/orders/schemas/firestore";
 export type BaseOrderLine = Omit<OrderDocumentItem, "listingType">;
 /**
  * Expand one cart line into the order rows it should produce.

package/dist/_internal/server/features/checkout/expand-order-items.js

@@ -17,8 +17,35 @@
  * The buyer's receipt is unaffected: `groupOrderItemsByLine` collapses these
  * rows back under one header, which it was already written to do.
  */
+import { ORDER_ITEM_DESCRIPTION_MAX, ORDER_ITEM_SPECIFICATIONS_MAX, } from "../../../../features/orders/schemas/firestore.js";
 import { lineTotalFor, allocateAcrossMembers } from "../../../shared/checkout/order-math.js";
 import { isFinalSale } from "../../../../features/products/constants/final-sale.js";
+function listingSnapshot(p) {
+    if (!p)
+        return {};
+    /*
+     * 🛑 A named Pick, not `Record<string, unknown>`. A bag of unknowns
+     * type-checks against anything, so a misspelled key — `descriptionTruncted`
+     * — would compile, spread onto the order line, and simply never be read.
+     * The field would look set and the truncation flag would be missing from
+     * every row (`audit-unknown-leakage` blocks exactly this).
+     */
+    const out = {};
+    const desc = typeof p.description === "string" ? p.description.trim() : "";
+    if (desc) {
+        out.description = desc.slice(0, ORDER_ITEM_DESCRIPTION_MAX);
+        if (desc.length > ORDER_ITEM_DESCRIPTION_MAX)
+            out.descriptionTruncated = true;
+    }
+    if (p.specifications?.length) {
+        out.specifications = p.specifications.slice(0, ORDER_ITEM_SPECIFICATIONS_MAX).map((x) => ({
+            name: x.name,
+            value: x.value,
+            ...(x.unit ? { unit: x.unit } : {}),
+        }));
+    }
+    return out;
+}
 /**
  * Expand one cart line into the order rows it should produce.
  *
@@ -89,6 +116,8 @@ export function expandCartLineToOrderRows(item, representative, productById) {
                 ...(representative.condition ? { condition: representative.condition } : {}),
                 // I9 — the physical variant, for the price index's colourway slice.
                 ...(representative.colourway ? { colourway: representative.colourway } : {}),
+                /* Part 14 — what the listing SAID, which is what a dispute argues over. */
+                ...listingSnapshot(representative),
                 // Legacy collapsed bundle rows (no groupMembers) keep their old shape so
                 // orders already in flight and their UI stay untouched.
                 ...(item.bundleCategorySlug && item.bundleProductIds
@@ -146,6 +175,9 @@ export function expandCartLineToOrderRows(item, representative, productById) {
             // blended condition would describe neither.
             ...(product?.condition ? { condition: product.condition } : {}),
             ...(product?.colourway ? { colourway: product.colourway } : {}),
+            /* Per MEMBER, same as condition above: a bundle can mix a sealed item
+             * with a loose one, and one blended description would describe neither. */
+            ...listingSnapshot(product),
             ...(gstRate != null ? { gstRate, ...(hsnCode ? { hsnCode } : {}) } : {}),
         };
     });

package/dist/_internal/server/features/checkout/freeze-parts.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Freezing a composed listing's PARTS onto its order line — Part 14.
+ *
+ * ## 🛑 Why this is a separate pass, and not inside `expand-order-items`
+ *
+ * `expandCartLineToOrderRows` is PURE: it takes a product map and returns
+ * rows, with no I/O. Composition is not on the product — it lives in
+ * `modelCompositions`, keyed by the model's CATEGORY leaf (a named model *is*
+ * a category leaf, per the parts schema). So freezing it needs a read, and a
+ * read inside that function would make the one piece of checkout arithmetic
+ * that can be reasoned about locally depend on Firestore.
+ *
+ * ## 🛑 Bounded, and usually free
+ *
+ * Two gates, in this order, because the first one is what keeps the budget:
+ *
+ * 1. **`LISTING_TYPE_HAS_COMPOSITION`** — most listing types have none, so a
+ *    typical order does zero reads. This is checked before anything else.
+ * 2. **Distinct category leaves**, capped. Several lines of the same model
+ *    share one read; `getCompositionsForCategory` is `React.cache`-wrapped, so
+ *    a repeat within one request is free anyway.
+ *
+ * Rule #6 budgets ~3 sequential round trips for a server action. The cap is
+ * what stops a 20-line order of distinct models turning checkout into twenty.
+ *
+ * ## 🛑 Failure is SILENT BY DESIGN here, which is unusual and deliberate
+ *
+ * `getCompositionsForCategory` already swallows and warns. A composition we
+ * could not read must never fail a checkout: the buyer is paying, the parts
+ * list is descriptive, and an order placed without it is complete in every
+ * way that matters. The absence is recoverable — the live category still has
+ * the data — while a refused payment is not.
+ */
+import type { OrderDocumentItem } from "../../../../features/orders/schemas/firestore";
+/**
+ * How many distinct models one order may resolve composition for.
+ *
+ * Past this the order is a bulk purchase and the parts list stops being the
+ * thing anyone disputes. Exceeding it drops the extra lines' parts rather
+ * than failing — see the header.
+ */
+export declare const COMPOSITION_LOOKUP_MAX = 8;
+/**
+ * Attach `parts` to every line whose listing type has a composition.
+ *
+ * Returns a NEW array; the input rows are not mutated, because they are built
+ * by a pure function and keeping them pure is what lets that function be
+ * reasoned about on its own.
+ */
+export declare function freezePartsOnItems(items: readonly OrderDocumentItem[]): Promise<OrderDocumentItem[]>;

package/dist/_internal/server/features/checkout/freeze-parts.js

@@ -0,0 +1,94 @@
+/**
+ * Freezing a composed listing's PARTS onto its order line — Part 14.
+ *
+ * ## 🛑 Why this is a separate pass, and not inside `expand-order-items`
+ *
+ * `expandCartLineToOrderRows` is PURE: it takes a product map and returns
+ * rows, with no I/O. Composition is not on the product — it lives in
+ * `modelCompositions`, keyed by the model's CATEGORY leaf (a named model *is*
+ * a category leaf, per the parts schema). So freezing it needs a read, and a
+ * read inside that function would make the one piece of checkout arithmetic
+ * that can be reasoned about locally depend on Firestore.
+ *
+ * ## 🛑 Bounded, and usually free
+ *
+ * Two gates, in this order, because the first one is what keeps the budget:
+ *
+ * 1. **`LISTING_TYPE_HAS_COMPOSITION`** — most listing types have none, so a
+ *    typical order does zero reads. This is checked before anything else.
+ * 2. **Distinct category leaves**, capped. Several lines of the same model
+ *    share one read; `getCompositionsForCategory` is `React.cache`-wrapped, so
+ *    a repeat within one request is free anyway.
+ *
+ * Rule #6 budgets ~3 sequential round trips for a server action. The cap is
+ * what stops a 20-line order of distinct models turning checkout into twenty.
+ *
+ * ## 🛑 Failure is SILENT BY DESIGN here, which is unusual and deliberate
+ *
+ * `getCompositionsForCategory` already swallows and warns. A composition we
+ * could not read must never fail a checkout: the buyer is paying, the parts
+ * list is descriptive, and an order placed without it is complete in every
+ * way that matters. The absence is recoverable — the live category still has
+ * the data — while a refused payment is not.
+ */
+import { getCompositionsForCategory } from "../parts/data.js";
+import { LISTING_TYPE_HAS_COMPOSITION } from "../../../../features/parts/schemas/firestore.js";
+/**
+ * How many distinct models one order may resolve composition for.
+ *
+ * Past this the order is a bulk purchase and the parts list stops being the
+ * thing anyone disputes. Exceeding it drops the extra lines' parts rather
+ * than failing — see the header.
+ */
+export const COMPOSITION_LOOKUP_MAX = 8;
+/**
+ * Attach `parts` to every line whose listing type has a composition.
+ *
+ * Returns a NEW array; the input rows are not mutated, because they are built
+ * by a pure function and keeping them pure is what lets that function be
+ * reasoned about on its own.
+ */
+export async function freezePartsOnItems(items) {
+    const eligible = items.filter((i) => i.listingType && LISTING_TYPE_HAS_COMPOSITION[i.listingType] && i.categorySlug);
+    if (eligible.length === 0)
+        return [...items];
+    const leaves = [...new Set(eligible.map((i) => i.categorySlug))].slice(0, COMPOSITION_LOOKUP_MAX);
+    const byLeaf = new Map();
+    await Promise.all(leaves.map(async (leaf) => {
+        const comps = await getCompositionsForCategory(leaf);
+        /*
+         * One category can carry several compositions (a model released in
+         * variants). Flattened and de-duplicated by code: the order records
+         * which parts were CLAIMED, and two variants naming the same ring is
+         * one fact, not two.
+         */
+        const seen = new Map();
+        for (const c of comps) {
+            /*
+             * 🛑 `slots`, not `parts`. The first draft read `c.parts` — a field
+             * `ModelCompositionDocument` does not have — which would have
+             * silently frozen an empty list onto every composed line while every
+             * other part of the flow behaved correctly. Measured against the
+             * schema before shipping, not after.
+             */
+            for (const slot of c.slots ?? []) {
+                /*
+                 * `slotKey` is the stable identity (`partId` is absent whenever a
+                 * part did not resolve to a glossary row, which is common in the
+                 * corpus). `partName` is what a human reads in a dispute.
+                 */
+                const code = String(slot.partId ?? slot.slotKey ?? "");
+                if (!code || seen.has(code))
+                    continue;
+                seen.set(code, String(slot.partName ?? slot.slotLabel ?? code));
+            }
+        }
+        if (seen.size > 0) {
+            byLeaf.set(leaf, [...seen].map(([code, name]) => ({ code, name })));
+        }
+    }));
+    return items.map((i) => {
+        const parts = i.categorySlug ? byLeaf.get(i.categorySlug) : undefined;
+        return parts?.length ? { ...i, parts } : i;
+    });
+}

package/dist/_internal/server/features/checkout/value-otp-gate.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The high-value OTP gate — one implementation, taking the amount it judges.
+ *
+ * ## Why this exists as a function rather than two `if`s
+ *
+ * There were two hand-rolled copies: one in `createOrderForGroup`'s lane
+ * block and one in `POST /api/payment/create-order`. They already disagreed
+ * on what they measured — the first summed `price × quantity` over the cart,
+ * the second used the gateway route's own `subtotalRs` — and neither could
+ * be reused by anything else, because the amount was computed inline rather
+ * than passed in. That is Root Cause #75's shape exactly: a rule reachable
+ * only by copy-paste gets copied, and a copy made before a branch was added
+ * never learns about it.
+ *
+ * ## 🛑 It takes an AMOUNT, and that is the Part 6 prerequisite
+ *
+ * `otpCheckoutThreshold` is per CHECKOUT, so three ₹4,000 checkouts clear
+ * ₹12,000 with no OTP — and splitting an order is precisely what a shared
+ * purchase does. The gate therefore cannot keep deriving its own figure from
+ * whatever cart happens to be in scope; the caller has to say what sum is
+ * being authorised. For an ordinary checkout that is the cart; for an
+ * N-party arrangement it is the ARRANGEMENT total, charged across several
+ * payments that are individually under the line.
+ *
+ * Passing the amount in is the whole change. There is no arrangement yet to
+ * pass one, which is why this lands as a prerequisite rather than as a
+ * feature — but the gate can no longer be dodged by a caller that did not
+ * exist when the rule was written.
+ */
+export interface CheckoutValueOtpGateInput {
+    uid: string;
+    /** The sum being authorised, in rupees. See the header: the CALLER decides. */
+    amount: number;
+    /** `siteSettings.payment.otpCheckoutThreshold`. Absent or ≤ 0 disables the gate. */
+    threshold: number | undefined;
+    /**
+     * 🛑 COD is exempt, and that is a real decision rather than an oversight:
+     * a physical hand-off at the door is its own verification, and nothing has
+     * been captured when the gate would fire. Pass the method so the exemption
+     * lives here instead of being re-remembered at each call site.
+     */
+    paymentMethod?: string;
+    /** The admin checkout bypass (`siteSettings.featureFlags.adminCheckoutBypass`). */
+    adminBypass?: boolean;
+}
+/**
+ * Throws **403 `CHECKOUT_VALUE_OTP_REQUIRED`** when the amount clears the
+ * threshold and the buyer has not verified. Returns silently otherwise.
+ *
+ * 🛑 Call it BEFORE creating a gateway order, never after. Verifying
+ * post-payment means charging the buyer and then asking whether they were
+ * allowed to be charged — which is what the comment at the gateway call site
+ * has always said and is the reason that copy sits where it does.
+ */
+export declare function assertCheckoutValueOtp(input: CheckoutValueOtpGateInput): Promise<void>;

package/dist/_internal/server/features/checkout/value-otp-gate.js

@@ -0,0 +1,60 @@
+/**
+ * The high-value OTP gate — one implementation, taking the amount it judges.
+ *
+ * ## Why this exists as a function rather than two `if`s
+ *
+ * There were two hand-rolled copies: one in `createOrderForGroup`'s lane
+ * block and one in `POST /api/payment/create-order`. They already disagreed
+ * on what they measured — the first summed `price × quantity` over the cart,
+ * the second used the gateway route's own `subtotalRs` — and neither could
+ * be reused by anything else, because the amount was computed inline rather
+ * than passed in. That is Root Cause #75's shape exactly: a rule reachable
+ * only by copy-paste gets copied, and a copy made before a branch was added
+ * never learns about it.
+ *
+ * ## 🛑 It takes an AMOUNT, and that is the Part 6 prerequisite
+ *
+ * `otpCheckoutThreshold` is per CHECKOUT, so three ₹4,000 checkouts clear
+ * ₹12,000 with no OTP — and splitting an order is precisely what a shared
+ * purchase does. The gate therefore cannot keep deriving its own figure from
+ * whatever cart happens to be in scope; the caller has to say what sum is
+ * being authorised. For an ordinary checkout that is the cart; for an
+ * N-party arrangement it is the ARRANGEMENT total, charged across several
+ * payments that are individually under the line.
+ *
+ * Passing the amount in is the whole change. There is no arrangement yet to
+ * pass one, which is why this lands as a prerequisite rather than as a
+ * feature — but the gate can no longer be dodged by a caller that did not
+ * exist when the rule was written.
+ */
+import { ApiError } from "../../../../errors/api-error.js";
+import { isCheckoutValueOtpVerified } from "../../../../features/checkout/actions/checkout-value-otp-actions.js";
+/**
+ * Throws **403 `CHECKOUT_VALUE_OTP_REQUIRED`** when the amount clears the
+ * threshold and the buyer has not verified. Returns silently otherwise.
+ *
+ * 🛑 Call it BEFORE creating a gateway order, never after. Verifying
+ * post-payment means charging the buyer and then asking whether they were
+ * allowed to be charged — which is what the comment at the gateway call site
+ * has always said and is the reason that copy sits where it does.
+ */
+export async function assertCheckoutValueOtp(input) {
+    const { uid, amount, threshold, paymentMethod, adminBypass } = input;
+    if (adminBypass)
+        return;
+    if (paymentMethod === "cod")
+        return;
+    if (typeof threshold !== "number" || threshold <= 0)
+        return;
+    /*
+     * `>=`, not `>`. A threshold of ₹5,000 means a ₹5,000 checkout is gated —
+     * the schema comment on `otpCheckoutThreshold` calls it a MINIMUM, and
+     * both previous copies already read it that way.
+     */
+    if (amount < threshold)
+        return;
+    const verified = await isCheckoutValueOtpVerified(uid);
+    if (!verified) {
+        throw new ApiError(403, "CHECKOUT_VALUE_OTP_REQUIRED");
+    }
+}

package/dist/_internal/server/features/dashboard/attention.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Attention counts for the dashboard hubs — "how many things here are waiting
+ * for me".
+ *
+ * ## 🛑 A count that fails renders ABSENT, never `0`
+ *
+ * This is the one rule the whole module is shaped around, and it is the
+ * opposite of what `dailyStatusDigest`'s `safeCount` does. The digest returns
+ * `0` on a failed query and says so: *"a stuck zero next to live numbers
+ * elsewhere is legible as 'that one broke'"*. That is true of a table of
+ * twenty figures in an email and false of a badge on a card — there, `0` reads
+ * as **"nothing needs attention"**, which is the one wrong answer that stops
+ * the operator looking.
+ *
+ * So a failed source resolves to `null` and the card renders no badge at all.
+ * Root Cause #72: `undefined` must mean "the count failed", never "zero", and
+ * every count fails OPEN.
+ *
+ * ## Keyed by nav item id, not by section
+ *
+ * A count belongs to a SCREEN ("2 payouts are pending"), not to a section, so
+ * the key is `navItemId(portal, href)` — already derived, already stable,
+ * already the `navConfig` key. A section card sums its own items' counts, so
+ * no second keying scheme exists and a renamed group cannot orphan a count.
+ *
+ * 🛑 The ids are written as literals here and CROSS-CHECKED against the real
+ * nav by `audit-dashboard-hub-coverage`. A literal that matches no nav item is
+ * a count nothing can ever display — the silent half of Root Cause #62, where
+ * a filter is emitted on a field the allowlist omits and simply vanishes.
+ *
+ * ## 🛑 `nav-admin-admin-orders` is CORRECT. Do not "tidy" the repetition.
+ *
+ * `navItemId(portal, href)` is `nav-${portal}-${slugified href}`, and the href
+ * ALSO begins with the portal segment — so `/admin/orders` under the `admin`
+ * portal is `nav-admin-admin-orders`, and `/store/orders` is
+ * `nav-store-store-orders`. It reads like a mistake and is the live `navConfig`
+ * key.
+ *
+ * Every key in this registry was first written the way it reads — a single
+ * `nav-admin-orders` — and the consequence is worth recording because it is
+ * precisely the failure mode this registry's cross-check exists for:
+ * `collectAttentionCounts` looks each VISIBLE nav id up in here, so with the
+ * shortened keys **not one source would ever have matched**. No query would
+ * run, no badge would appear, and nothing anywhere would error — a feature
+ * that silently does nothing, which is indistinguishable from "nothing is
+ * waiting". `audit-dashboard-hub-coverage`'s R3 caught all six on its first
+ * clean run.
+ *
+ * ## Why these counts and not more
+ *
+ * Every source below is a query COPIED from one that already runs in
+ * production — four from `dailyStatusDigest`, which documents its own index
+ * story, plus the seller order count. None of them needed a new index:
+ * all are single-field equalities except the manual-payment pair (which reuses
+ * the existing `(status, paymentStatus, createdAt)` composite) and the seller
+ * pair (which is a prefix of `(storeId, status, createdAt)`). Verified against
+ * `appkit/firebase/base/firestore.indexes.json` rather than assumed.
+ *
+ * Inventing a count means choosing what "needs attention" means for a
+ * collection, and a wrong choice here is a badge that is confidently wrong
+ * forever. Adding one is a registry entry plus that decision, made once.
+ *
+ * **The user portal has no counts, deliberately.** Nothing on a buyer's
+ * dashboard is an obligation they are failing to meet — their unread count
+ * already lives in the notification bell, and duplicating it onto a card would
+ * be a second place for the same number to be stale. The registry simply has
+ * no `nav-user-*` key, so the user hubs run zero queries rather than running
+ * queries that return a number nobody acts on.
+ */
+import { getAdminDb } from "../../../../providers/db-firebase";
+/**
+ * `null` is a FAILED read; a missing key is "no count is defined for this
+ * screen". Both render as no badge, and the distinction matters only here.
+ */
+export type AttentionCounts = Record<string, number | null>;
+type CountableQuery = {
+    count(): {
+        get(): Promise<{
+            data(): {
+                count: number;
+            };
+        }>;
+    };
+};
+/**
+ * What each count needs from the viewer. A source whose requirement cannot be
+ * met is not run — it is not reported as `0` either, it is simply absent.
+ */
+interface AttentionSource {
+    /**
+     * Build the query. `storeId` is the viewer's store SLUG when they have one.
+     *
+     * 🛑 A store SLUG, not an Auth uid — `OrderDocument.storeId` holds the slug
+     * (§ "Store Identity Architecture"). Passing a uid returns zero for every
+     * seller and raises nothing, which is Root Cause #98's second bug.
+     */
+    query: (db: ReturnType<typeof getAdminDb>, storeId?: string) => CountableQuery | null;
+}
+/**
+ * nav item id → how to count what is waiting there.
+ *
+ * 🛑 Keys are cross-checked against the real nav by
+ * `audit-dashboard-hub-coverage`. A key matching no nav item is a count that
+ * can never be displayed — the silent half of Root Cause #62.
+ */
+export declare const ATTENTION_SOURCES: Record<string, AttentionSource>;
+/**
+ * Count what is waiting, for the nav items this viewer can actually see.
+ *
+ * ## 🛑 `visibleItemIds` is the gate, and it is not an optimisation
+ *
+ * The caller passes the ids that SURVIVED permission filtering, so a count is
+ * only ever computed for a card that will be rendered. Two things fall out of
+ * that which a blanket "am I staff" boolean could not give:
+ *
+ *  - An employee holding one permission pays for one count, not six. The first
+ *    draft derived staffness from `permissions.length > 0` and ran all five
+ *    admin queries for anyone with any grant at all — six reads to render one
+ *    card, and a number computed from a collection that employee has no
+ *    permission to read.
+ *  - A seller and an admin need no separate branches. The store nav contains
+ *    `nav-store-orders` and the admin nav does not, so the nav IS the scope.
+ *
+ * `Promise.all` over `.count()` aggregations: six reads worst case, none
+ * scaling with collection size, parallel rather than sequential (Rule #6).
+ */
+export declare function collectAttentionCounts(visibleItemIds: readonly string[], storeId?: string): Promise<AttentionCounts>;
+export {};

package/dist/_internal/server/features/dashboard/attention.js

@@ -0,0 +1,183 @@
+/**
+ * Attention counts for the dashboard hubs — "how many things here are waiting
+ * for me".
+ *
+ * ## 🛑 A count that fails renders ABSENT, never `0`
+ *
+ * This is the one rule the whole module is shaped around, and it is the
+ * opposite of what `dailyStatusDigest`'s `safeCount` does. The digest returns
+ * `0` on a failed query and says so: *"a stuck zero next to live numbers
+ * elsewhere is legible as 'that one broke'"*. That is true of a table of
+ * twenty figures in an email and false of a badge on a card — there, `0` reads
+ * as **"nothing needs attention"**, which is the one wrong answer that stops
+ * the operator looking.
+ *
+ * So a failed source resolves to `null` and the card renders no badge at all.
+ * Root Cause #72: `undefined` must mean "the count failed", never "zero", and
+ * every count fails OPEN.
+ *
+ * ## Keyed by nav item id, not by section
+ *
+ * A count belongs to a SCREEN ("2 payouts are pending"), not to a section, so
+ * the key is `navItemId(portal, href)` — already derived, already stable,
+ * already the `navConfig` key. A section card sums its own items' counts, so
+ * no second keying scheme exists and a renamed group cannot orphan a count.
+ *
+ * 🛑 The ids are written as literals here and CROSS-CHECKED against the real
+ * nav by `audit-dashboard-hub-coverage`. A literal that matches no nav item is
+ * a count nothing can ever display — the silent half of Root Cause #62, where
+ * a filter is emitted on a field the allowlist omits and simply vanishes.
+ *
+ * ## 🛑 `nav-admin-admin-orders` is CORRECT. Do not "tidy" the repetition.
+ *
+ * `navItemId(portal, href)` is `nav-${portal}-${slugified href}`, and the href
+ * ALSO begins with the portal segment — so `/admin/orders` under the `admin`
+ * portal is `nav-admin-admin-orders`, and `/store/orders` is
+ * `nav-store-store-orders`. It reads like a mistake and is the live `navConfig`
+ * key.
+ *
+ * Every key in this registry was first written the way it reads — a single
+ * `nav-admin-orders` — and the consequence is worth recording because it is
+ * precisely the failure mode this registry's cross-check exists for:
+ * `collectAttentionCounts` looks each VISIBLE nav id up in here, so with the
+ * shortened keys **not one source would ever have matched**. No query would
+ * run, no badge would appear, and nothing anywhere would error — a feature
+ * that silently does nothing, which is indistinguishable from "nothing is
+ * waiting". `audit-dashboard-hub-coverage`'s R3 caught all six on its first
+ * clean run.
+ *
+ * ## Why these counts and not more
+ *
+ * Every source below is a query COPIED from one that already runs in
+ * production — four from `dailyStatusDigest`, which documents its own index
+ * story, plus the seller order count. None of them needed a new index:
+ * all are single-field equalities except the manual-payment pair (which reuses
+ * the existing `(status, paymentStatus, createdAt)` composite) and the seller
+ * pair (which is a prefix of `(storeId, status, createdAt)`). Verified against
+ * `appkit/firebase/base/firestore.indexes.json` rather than assumed.
+ *
+ * Inventing a count means choosing what "needs attention" means for a
+ * collection, and a wrong choice here is a badge that is confidently wrong
+ * forever. Adding one is a registry entry plus that decision, made once.
+ *
+ * **The user portal has no counts, deliberately.** Nothing on a buyer's
+ * dashboard is an obligation they are failing to meet — their unread count
+ * already lives in the notification bell, and duplicating it onto a card would
+ * be a second place for the same number to be stale. The registry simply has
+ * no `nav-user-*` key, so the user hubs run zero queries rather than running
+ * queries that return a number nobody acts on.
+ */
+import { getAdminDb } from "../../../../providers/db-firebase/index.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+import { ORDER_COLLECTION, OrderStatusValues } from "../../../../features/orders/schemas/firestore.js";
+import { NOTIFICATION_FIELDS, ORDER_FIELDS } from "../../../../constants/field-names.js";
+import { PAYOUT_COLLECTION, PAYOUT_FIELDS } from "../../../../features/payments/schemas/firestore.js";
+import { SUPPORT_TICKET_COLLECTION, SUPPORT_TICKET_FIELDS, TicketStatusValues, } from "../../../../features/support/schemas/firestore.js";
+import { ADMIN_NOTIFICATIONS_COLLECTION } from "../../../../features/store-extensions/schemas/rbac.js";
+import { CATALOGUE_COLLECTION, CATALOGUE_FIELDS, } from "../../../../features/catalogue/schemas/firestore.js";
+/** `null` on any failure — see the header. */
+async function countOrNull(q) {
+    try {
+        const snap = await q.count().get();
+        return snap.data().count;
+    }
+    catch (err) {
+        void normalizeError(err);
+        return null;
+    }
+}
+/**
+ * nav item id → how to count what is waiting there.
+ *
+ * 🛑 Keys are cross-checked against the real nav by
+ * `audit-dashboard-hub-coverage`. A key matching no nav item is a count that
+ * can never be displayed — the silent half of Root Cause #62.
+ */
+export const ATTENTION_SOURCES = {
+    /*
+     * Orders awaiting a manual-payment decision. The digest's exact query —
+     * `status == pending AND paymentStatus == pending` — which is what
+     * § "Manual Payment Review Flow" calls the review queue's bounded
+     * pre-filter, and which reuses the existing
+     * `(status, paymentStatus, createdAt)` composite.
+     */
+    "nav-admin-admin-orders": {
+        query: (db) => db
+            .collection(ORDER_COLLECTION)
+            .where(ORDER_FIELDS.STATUS, "==", OrderStatusValues.PENDING)
+            .where(ORDER_FIELDS.PAYMENT_STATUS, "==", "pending"),
+    },
+    "nav-admin-admin-payouts": {
+        query: (db) => db
+            .collection(PAYOUT_COLLECTION)
+            .where(PAYOUT_FIELDS.STATUS, "==", PAYOUT_FIELDS.STATUS_VALUES.PENDING),
+    },
+    "nav-admin-admin-support-tickets": {
+        query: (db) => db
+            .collection(SUPPORT_TICKET_COLLECTION)
+            .where(SUPPORT_TICKET_FIELDS.STATUS, "==", TicketStatusValues.OPEN),
+    },
+    "nav-admin-admin-notifications": {
+        /*
+         * 🛑 `NOTIFICATION_FIELDS.IS_READ`, not the literal `"isRead"`.
+         * `dailyStatusDigest` writes the bare string with an
+         * `audit-field-name-ok` marker and a long justification — that `isRead` is
+         * a `BaseDocument` field rather than a per-feature name — but the marker
+         * is not needed here because a real constant for it exists, and a
+         * constant that exists is always better than a waiver for not using it.
+         */
+        query: (db) => db.collection(ADMIN_NOTIFICATIONS_COLLECTION).where(NOTIFICATION_FIELDS.IS_READ, "==", false),
+    },
+    "nav-admin-admin-catalogue-approvals": {
+        query: (db) => db
+            .collection(CATALOGUE_COLLECTION)
+            .where(CATALOGUE_FIELDS.LISTING_STATUS, "==", "pending_admin_approval"),
+    },
+    /* A prefix of the existing `(storeId, status, createdAt)` composite. */
+    "nav-store-store-orders": {
+        query: (db, storeId) => storeId
+            ? db
+                .collection(ORDER_COLLECTION)
+                .where(ORDER_FIELDS.STORE_ID, "==", storeId)
+                .where(ORDER_FIELDS.STATUS, "==", OrderStatusValues.PENDING)
+            : null,
+    },
+};
+/**
+ * Count what is waiting, for the nav items this viewer can actually see.
+ *
+ * ## 🛑 `visibleItemIds` is the gate, and it is not an optimisation
+ *
+ * The caller passes the ids that SURVIVED permission filtering, so a count is
+ * only ever computed for a card that will be rendered. Two things fall out of
+ * that which a blanket "am I staff" boolean could not give:
+ *
+ *  - An employee holding one permission pays for one count, not six. The first
+ *    draft derived staffness from `permissions.length > 0` and ran all five
+ *    admin queries for anyone with any grant at all — six reads to render one
+ *    card, and a number computed from a collection that employee has no
+ *    permission to read.
+ *  - A seller and an admin need no separate branches. The store nav contains
+ *    `nav-store-orders` and the admin nav does not, so the nav IS the scope.
+ *
+ * `Promise.all` over `.count()` aggregations: six reads worst case, none
+ * scaling with collection size, parallel rather than sequential (Rule #6).
+ */
+export async function collectAttentionCounts(visibleItemIds, storeId) {
+    const db = getAdminDb();
+    const runnable = [];
+    for (const id of visibleItemIds) {
+        const source = ATTENTION_SOURCES[id];
+        if (!source)
+            continue;
+        const q = source.query(db, storeId);
+        if (q)
+            runnable.push([id, q]);
+    }
+    const results = await Promise.all(runnable.map(([, q]) => countOrNull(q)));
+    const counts = {};
+    runnable.forEach(([key], i) => {
+        counts[key] = results[i] ?? null;
+    });
+    return counts;
+}