@mohasinac/appkit 4.47.0 → 4.48.1

package/dist/.build-stamp.json

@@ -1,8 +1,8 @@
 {
   "stampVersion": 1,
-  "version": "4.47.0",
-  "head": "f72c5f183b70c66b626c7809ffb1a4b0112e7cb1",
+  "version": "4.48.1",
+  "head": "d711c224e6c53ee2cbca34d3b5764b448974087d",
   "branch": "main",
-  "dirty": true,
-  "builtAt": "2026-10-13T05:22:53.600Z"
+  "dirty": false,
+  "builtAt": "2026-10-14T02:40:53.091Z"
 }

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

@@ -87,6 +87,8 @@ export function expandCartLineToOrderRows(item, representative, productById) {
                 ...(representative.brand ? { brand: representative.brand } : {}),
                 ...(representative.listingType ? { listingType: representative.listingType } : {}),
                 ...(representative.condition ? { condition: representative.condition } : {}),
+                // I9 — the physical variant, for the price index's colourway slice.
+                ...(representative.colourway ? { colourway: representative.colourway } : {}),
                 // Legacy collapsed bundle rows (no groupMembers) keep their old shape so
                 // orders already in flight and their UI stay untouched.
                 ...(item.bundleCategorySlug && item.bundleProductIds
@@ -143,6 +145,7 @@ export function expandCartLineToOrderRows(item, representative, productById) {
             // Per MEMBER — a bundle can mix a sealed item with a loose one, and a
             // blended condition would describe neither.
             ...(product?.condition ? { condition: product.condition } : {}),
+            ...(product?.colourway ? { colourway: product.colourway } : {}),
             ...(gstRate != null ? { gstRate, ...(hsnCode ? { hsnCode } : {}) } : {}),
         };
     });

package/dist/_internal/server/features/messages/actions.d.ts

@@ -0,0 +1,68 @@
+import { deleteAllMessages, listAllAttachmentUrls } from "../../../../features/messages/repository/messages.repository";
+import type { ConversationDocument, MessageDocument } from "../../../../features/messages/schemas/firestore";
+/**
+ * Strips the three obvious PII shapes from a chat message before it is
+ * written. Promoted here from the item-request replies route per D9's spec —
+ * same ordering fix (specific-before-general: UPI scheme, then anything with a
+ * TLD dot is an email, then any remaining `token@token` has no dot and is
+ * therefore a VPA, only then bare digit runs), because that ordering IS the
+ * whole fix (F1 #5 — the old order let the email rule eat UPI-shaped VPAs and
+ * the phone rule mangle `9876543210@upi` before the UPI rule ever saw it).
+ */
+export declare function stripPii(input: string): string;
+export declare function createOrOpenConversation(userId: string, otherUserId: string): Promise<ConversationDocument>;
+/**
+ * D11 surfaced this gap: the backend had a full create/open path and no UI
+ * entry point ever called it — "Message Seller" did not exist anywhere. A
+ * product/store page knows `storeId` (the slug), never the seller's uid
+ * (Store Identity Architecture: storeId=storeSlug, ownerId=Auth UID), so the
+ * resolution happens here, server-side, rather than piping ownerId through
+ * every page that might want this button.
+ */
+export declare function openConversationWithSeller(buyerId: string, storeId: string): Promise<ConversationDocument>;
+export declare function listConversationsForUser(userId: string, opts?: {
+    limit?: number;
+    cursor?: string;
+}): Promise<{
+    items: ConversationDocument[];
+    nextCursor: string | null;
+}>;
+export declare function listMessagesForConversation(userId: string, conversationId: string, opts?: {
+    limit?: number;
+    cursor?: string;
+}): Promise<{
+    items: MessageDocument[];
+    nextCursor: string | null;
+}>;
+export interface SendMessageInput {
+    conversationId: string;
+    authorId: string;
+    body: string;
+    clientMessageId: string;
+    /** Already-uploaded `/media/` proxy URLs, still possibly in tmp/. */
+    attachments?: string[];
+    productId?: string;
+}
+/**
+ * The one writer path. Every mutation here runs through the Admin SDK — the
+ * old feature attempted client writes against `.write: false` and that is
+ * precisely what made it inert.
+ */
+export declare function sendMessage(input: SendMessageInput): Promise<MessageDocument>;
+export declare function markConversationRead(userId: string, conversationId: string): Promise<void>;
+export declare function blockConversationParticipant(userId: string, conversationId: string): Promise<void>;
+export declare function softDeleteOwnMessage(userId: string, conversationId: string, messageId: string): Promise<void>;
+/**
+ * Mint a per-conversation custom token, matching `{ authEventId }` /
+ * `{ paymentEventId }` / `{ bulkJobId }` — no broad token, ever. The RTDB auth
+ * app's uid is synthetic and unrelated to the user's real uid, same as the
+ * payment-event precedent: the realtime channel's identity and the user's
+ * session identity are deliberately decoupled.
+ */
+export declare function mintChatEventToken(userId: string, conversationId: string): Promise<{
+    customToken: string;
+    expiresAt: number;
+}>;
+/** Unread rollup for the nav badge — never a list query (D9 spec). */
+export declare function getUnreadConversationCount(userId: string): Promise<number>;
+export { deleteAllMessages, listAllAttachmentUrls };

package/dist/_internal/server/features/messages/actions.js

@@ -0,0 +1,249 @@
+import { normalizeError } from "../../../../errors/normalize.js";
+import { AuthorizationError, NotFoundError, ValidationError } from "../../../../errors/index.js";
+import { getAdminAuth, getAdminRealtimeDb } from "../../../../providers/db-firebase/index.js";
+import { RTDB_PATHS } from "../../../../providers/db-firebase/rtdb-paths.js";
+import { serverLogger } from "../../../../monitoring/index.js";
+import { userRepository } from "../../../../features/auth/repository/user.repository.js";
+import { isSoftBanned } from "../../../../features/auth/server/checkSoftBan.js";
+import { isSellerUser } from "../../../../features/auth/role-predicates.js";
+import { conversationsRepository } from "../../../../features/messages/repository/conversations.repository.js";
+import { storeRepository } from "../../../../features/stores/repository/store.repository.js";
+import { createMessage, listMessages, softDeleteMessage, deleteAllMessages, listAllAttachmentUrls, } from "../../../../features/messages/repository/messages.repository.js";
+import { finalizeStagedMediaArray } from "../../../../features/media/finalize.js";
+import { sendNotification } from "../../../../features/admin/actions/notification-actions.js";
+import { productRepository } from "../../../../features/products/repository/products.repository.js";
+import { siteSettingsRepository } from "../../../../repositories/index.js";
+const MESSAGE_MAX_LENGTH = 2000;
+/**
+ * Off by default — `undefined` reads as OFF, never a default-true `??`. A
+ * real setting with a real cost: the feature was deleted once already for
+ * shipping broken, and re-enabling it site-wide without an explicit opt-in
+ * would repeat that without the proof-of-value this plan asks for first.
+ */
+async function assertChatEnabled() {
+    const settings = await siteSettingsRepository.getSingleton();
+    if (settings?.chat?.enabled !== true) {
+        throw new AuthorizationError("Messaging is not currently available.");
+    }
+}
+/**
+ * Strips the three obvious PII shapes from a chat message before it is
+ * written. Promoted here from the item-request replies route per D9's spec —
+ * same ordering fix (specific-before-general: UPI scheme, then anything with a
+ * TLD dot is an email, then any remaining `token@token` has no dot and is
+ * therefore a VPA, only then bare digit runs), because that ordering IS the
+ * whole fix (F1 #5 — the old order let the email rule eat UPI-shaped VPAs and
+ * the phone rule mangle `9876543210@upi` before the UPI rule ever saw it).
+ */
+export function stripPii(input) {
+    return input
+        .replace(/upi:\/\/\S+/gi, "[UPI removed]")
+        .replace(/[\w.+-]+@[\w-]+\.[\w.-]+/g, "[email removed]")
+        .replace(/[\w.-]{2,}@[\w-]{2,}/g, "[UPI removed]")
+        .replace(/\b\d{10,12}\b/g, "[number removed]");
+}
+function otherParticipant(conversation, userId) {
+    const other = conversation.participantIds.find((id) => id !== userId);
+    if (!other) {
+        throw new ValidationError("Conversation has no other participant.");
+    }
+    return other;
+}
+function assertParticipant(conversation, userId) {
+    if (!conversation.participantIds.includes(userId)) {
+        throw new AuthorizationError("You are not a participant in this conversation.");
+    }
+}
+/** Shared `findById` + not-found throw — every mutator below needs both. */
+async function requireConversation(conversationId) {
+    const conversation = await conversationsRepository.findById(conversationId);
+    if (!conversation)
+        throw new NotFoundError("Conversation not found.");
+    return conversation;
+}
+/**
+ * 🛑 `send_messages` is a live `BannedAction` with no reader anywhere in the
+ * codebase (F1 #6) — an admin can set it today and nothing checks it. This is
+ * the missing reader, in the domain function per the same precedent
+ * `assertCanBid` set for `place_bids`: enforcement belongs here so every
+ * caller (route, future job) is covered by construction.
+ */
+async function assertCanSendMessages(userId) {
+    const profile = await userRepository.findById(userId);
+    if (profile && isSoftBanned(profile, "send_messages")) {
+        const ban = profile.softBans?.find((b) => b.action === "send_messages");
+        throw new AuthorizationError(`You are restricted from sending messages. Reason: ${ban?.reason ?? "Policy violation"}.`);
+    }
+}
+export async function createOrOpenConversation(userId, otherUserId) {
+    await assertChatEnabled();
+    if (userId === otherUserId) {
+        throw new ValidationError("Cannot start a conversation with yourself.");
+    }
+    const existing = await conversationsRepository.findBetween(userId, otherUserId);
+    if (existing)
+        return existing;
+    const [me, other] = await Promise.all([
+        userRepository.findById(userId),
+        userRepository.findById(otherUserId),
+    ]);
+    if (!other) {
+        throw new NotFoundError("The other participant could not be found.");
+    }
+    const roleFor = (u) => (isSellerUser(u) ? "seller" : "buyer");
+    const roles = {
+        [userId]: roleFor(me),
+        [otherUserId]: roleFor(other),
+    };
+    return conversationsRepository.createBetween(userId, otherUserId, roles);
+}
+/**
+ * D11 surfaced this gap: the backend had a full create/open path and no UI
+ * entry point ever called it — "Message Seller" did not exist anywhere. A
+ * product/store page knows `storeId` (the slug), never the seller's uid
+ * (Store Identity Architecture: storeId=storeSlug, ownerId=Auth UID), so the
+ * resolution happens here, server-side, rather than piping ownerId through
+ * every page that might want this button.
+ */
+export async function openConversationWithSeller(buyerId, storeId) {
+    const store = await storeRepository.findById(storeId);
+    if (!store)
+        throw new NotFoundError("Store not found.");
+    if (store.ownerId === buyerId) {
+        throw new ValidationError("You cannot message your own store.");
+    }
+    return createOrOpenConversation(buyerId, store.ownerId);
+}
+export async function listConversationsForUser(userId, opts = {}) {
+    return conversationsRepository.listForUser(userId, opts);
+}
+export async function listMessagesForConversation(userId, conversationId, opts = {}) {
+    const conversation = await requireConversation(conversationId);
+    assertParticipant(conversation, userId);
+    return listMessages(conversationId, opts);
+}
+/**
+ * The one writer path. Every mutation here runs through the Admin SDK — the
+ * old feature attempted client writes against `.write: false` and that is
+ * precisely what made it inert.
+ */
+export async function sendMessage(input) {
+    await assertChatEnabled();
+    const conversation = await requireConversation(input.conversationId);
+    assertParticipant(conversation, input.authorId);
+    const recipientId = otherParticipant(conversation, input.authorId);
+    if (conversation.blockedBy?.includes(recipientId)) {
+        // The recipient blocked the sender — a blocked sender gets a clear reason,
+        // not a message that silently vanishes into a thread nobody reads.
+        throw new AuthorizationError("The other participant is not accepting messages from you.");
+    }
+    await assertCanSendMessages(input.authorId);
+    const trimmed = input.body.trim();
+    if (!trimmed)
+        throw new ValidationError("Message cannot be empty.");
+    if (trimmed.length > MESSAGE_MAX_LENGTH) {
+        throw new ValidationError(`Message cannot exceed ${MESSAGE_MAX_LENGTH} characters.`);
+    }
+    const cleaned = stripPii(trimmed);
+    // Attachments finalized BEFORE the write — the working pattern is
+    // review-actions.ts, not item-requests (which calls no finalize at all, F1
+    // #8) or supportTickets (which declares attachments and reads/finalizes
+    // nothing, F1 #7).
+    const finalizedAttachments = input.attachments?.length
+        ? await finalizeStagedMediaArray(input.attachments)
+        : undefined;
+    let productRef;
+    if (input.productId) {
+        const product = await productRepository.findById(input.productId);
+        if (product) {
+            productRef = {
+                productId: product.id,
+                title: product.title,
+                image: product.images?.[0],
+                price: product.price,
+            };
+        }
+        // A missing/deleted product is not an error — the card simply doesn't
+        // attach, same honesty rule as every other "snapshot at send time" field.
+    }
+    const message = await createMessage({
+        conversationId: input.conversationId,
+        authorId: input.authorId,
+        body: cleaned,
+        clientMessageId: input.clientMessageId,
+        attachments: finalizedAttachments,
+        productRef,
+    });
+    const preview = cleaned.length > 140 ? `${cleaned.slice(0, 140)}…` : cleaned;
+    await conversationsRepository.applyNewMessage(input.conversationId, input.authorId, recipientId, {
+        body: preview,
+        authorId: input.authorId,
+        at: message.createdAt,
+        hasAttachments: Boolean(finalizedAttachments?.length),
+        productId: productRef?.productId,
+    });
+    // RTDB ping — best-effort. A failed ping degrades to "the recipient notices
+    // on their next poll/visit", never to a lost message (the message is
+    // already durably in Firestore by this point).
+    try {
+        await getAdminRealtimeDb()
+            .ref(`${RTDB_PATHS.CHAT_EVENTS}/${input.conversationId}`)
+            .set({ updatedAt: Date.now() });
+    }
+    catch (rtdbErr) {
+        void normalizeError(rtdbErr);
+        serverLogger.warn("sendMessage: chat_events ping failed (non-fatal)", {
+            conversationId: input.conversationId,
+        });
+    }
+    // Bell-only (EMAIL_ELIGIBLE_TYPES.message_received === false) — the
+    // conversation lives in the UI.
+    await sendNotification({
+        userId: recipientId,
+        type: "message_received",
+        priority: "normal",
+        title: "New message",
+        message: preview,
+        relatedId: input.conversationId,
+        relatedType: "conversation",
+    });
+    return message;
+}
+export async function markConversationRead(userId, conversationId) {
+    const conversation = await requireConversation(conversationId);
+    assertParticipant(conversation, userId);
+    await conversationsRepository.markRead(conversationId, userId);
+}
+export async function blockConversationParticipant(userId, conversationId) {
+    const conversation = await requireConversation(conversationId);
+    assertParticipant(conversation, userId);
+    await conversationsRepository.blockParticipant(conversationId, userId);
+}
+export async function softDeleteOwnMessage(userId, conversationId, messageId) {
+    const conversation = await requireConversation(conversationId);
+    assertParticipant(conversation, userId);
+    await softDeleteMessage(conversationId, messageId, userId);
+}
+/**
+ * Mint a per-conversation custom token, matching `{ authEventId }` /
+ * `{ paymentEventId }` / `{ bulkJobId }` — no broad token, ever. The RTDB auth
+ * app's uid is synthetic and unrelated to the user's real uid, same as the
+ * payment-event precedent: the realtime channel's identity and the user's
+ * session identity are deliberately decoupled.
+ */
+export async function mintChatEventToken(userId, conversationId) {
+    const conversation = await requireConversation(conversationId);
+    assertParticipant(conversation, userId);
+    const customToken = await getAdminAuth().createCustomToken(`chat_event_${conversationId}`, { conversationId });
+    return { customToken, expiresAt: Date.now() + 60 * 60 * 1000 };
+}
+/** Unread rollup for the nav badge — never a list query (D9 spec). */
+export async function getUnreadConversationCount(userId) {
+    // listForUser is already bounded (<=50); summing its unread counts avoids a
+    // second query shape while staying well inside Rule #6's per-request budget.
+    // A user with more than 50 active threads undercounts here, which is an
+    // acceptable approximation for a bell badge, not a balance.
+    const { items } = await conversationsRepository.listForUser(userId, { limit: 50 });
+    return items.reduce((sum, c) => sum + (c.unread[userId] ?? 0), 0);
+}
+export { deleteAllMessages, listAllAttachmentUrls };

package/dist/_internal/server/features/parts/buildable.d.ts

@@ -0,0 +1,47 @@
+/** Part listings read per store. The same cap the assembly drawer uses. */
+export declare const BUILDABLE_HOLDINGS_LIMIT = 50;
+/**
+ * Candidate models considered. A seller holding common Metal-era parts can
+ * reach several hundred compositions through `usedBy`; this bounds the second
+ * `getAll` and the answer is truncated rather than partial-and-silent.
+ */
+export declare const BUILDABLE_CANDIDATE_LIMIT = 60;
+export interface BuildableSlot {
+    slotKey: string;
+    slotLabel: string;
+    partName: string;
+    partId?: string;
+    /** The colourway THIS model needs, when the corpus distinguishes one. */
+    expectedColourway?: string;
+    /** Complete units this slot alone could supply. */
+    buildable: number;
+}
+export interface BuildableModel {
+    compositionId: string;
+    name: string;
+    /** The named-model category, when the generator joined one. */
+    categoryId?: string;
+    /**
+     * How many COMPLETE units are buildable — the MINIMUM across slots, never a
+     * sum or an average: a bey missing one tip is not 80% of a bey.
+     */
+    buildable: number;
+    slots: BuildableSlot[];
+    /** Slot labels supplying zero. Named, because that is the shopping list. */
+    blockedBy: string[];
+}
+export interface BuildableResult {
+    models: BuildableModel[];
+    /** Distinct part listings considered. */
+    holdings: number;
+    /** A cap was hit, so the answer is a floor rather than the whole truth. */
+    truncated: boolean;
+}
+/**
+ * What this store can build right now.
+ *
+ * Sorted by `buildable` descending and then by how close a blocked model is to
+ * complete, so the useful answer ("you are one Spin Track away") is near the
+ * top rather than buried under everything that is fully blocked.
+ */
+export declare function listBuildableModels(storeId: string): Promise<BuildableResult>;

package/dist/_internal/server/features/parts/buildable.js

@@ -0,0 +1,159 @@
+/*
+ * WHY: D13's last item — "which complete beys can I build RIGHT NOW from the
+ *      parts I hold", answered server-side for one store.
+ *
+ * 🛑 THE DEFECT THIS IS SHAPED AROUND (I9). Matching a composition slot on
+ *    `partGlossaryId` alone reports *"you can build an L-Drago Guardian
+ *    S130MB"* when the only Metal Ball on the shelf is the Poison Zurafa's
+ *    transparent-black one. One glossary row, same mould, same weight, same
+ *    stats — two physical units that are not interchangeable and differ wildly
+ *    in value, with no stat to tell them apart. A confident, specific, wrong
+ *    answer with no error, discovered by the seller holding the wrong part.
+ *
+ *    So every match goes through `satisfiesSlot`, which keys on
+ *    **(partGlossaryId, colourway)** and refuses a colour-unknown holding for a
+ *    slot that names a colour — "unknown" is not evidence of the right colour.
+ *
+ * 🛑 THREE ROUND TRIPS, FLAT IN THE NUMBER OF PARTS HELD (Rule #6). The naive
+ *    shape is one `getModelsUsingPart` per held part, which is N reads for a
+ *    seller with N distinct parts. Instead: one bounded listing read, one
+ *    `getAll` over the held glossary rows (whose `usedBy` the generator already
+ *    wrote), one `getAll` over the candidate compositions. A seller with 3
+ *    parts and a seller with 40 cost the same.
+ *
+ * @tag domain:parts
+ * @tag layer:server-data
+ * @tag access:server-only
+ * @tag sideEffects:firestore-read
+ */
+import { normalizeError } from "../../../../errors/normalize.js";
+import { serverLogger } from "../../../../monitoring/server-logger.js";
+import { getAdminDb } from "../../../../providers/db-firebase/index.js";
+import { MODEL_COMPOSITION_COLLECTION, PART_GLOSSARY_COLLECTION, } from "../../../../features/parts/schemas/firestore.js";
+import { matchSlotToHoldings, } from "../../../../features/parts/utils/colourway-match.js";
+import { ANY_STATUS, listPublicProducts } from "../products/list-public.js";
+/** Part listings read per store. The same cap the assembly drawer uses. */
+export const BUILDABLE_HOLDINGS_LIMIT = 50;
+/**
+ * Candidate models considered. A seller holding common Metal-era parts can
+ * reach several hundred compositions through `usedBy`; this bounds the second
+ * `getAll` and the answer is truncated rather than partial-and-silent.
+ */
+export const BUILDABLE_CANDIDATE_LIMIT = 60;
+/** Slots that carry no glossary id cannot be matched and are not required. */
+function requiredSlots(comp) {
+    return (comp.slots ?? []).filter((s) => typeof s.partId === "string" && s.partId.length > 0);
+}
+/**
+ * What this store can build right now.
+ *
+ * Sorted by `buildable` descending and then by how close a blocked model is to
+ * complete, so the useful answer ("you are one Spin Track away") is near the
+ * top rather than buried under everything that is fully blocked.
+ */
+export async function listBuildableModels(storeId) {
+    const empty = { models: [], holdings: 0, truncated: false };
+    if (!storeId)
+        return empty;
+    try {
+        const db = getAdminDb();
+        /* 1 — the seller's own part listings, through the SHARED query. */
+        const listing = await listPublicProducts({
+            storeId,
+            status: ANY_STATUS,
+            page: 1,
+            pageSize: BUILDABLE_HOLDINGS_LIMIT,
+        });
+        const holdings = (listing?.items ?? [])
+            .filter((row) => typeof row.partGlossaryId === "string")
+            .map((row) => ({
+            productId: String(row.id),
+            partGlossaryId: String(row.partGlossaryId),
+            availableQuantity: typeof row.availableQuantity === "number" ? row.availableQuantity : 0,
+            ...(typeof row.colourway === "string" ? { colourway: row.colourway } : {}),
+        }))
+            // A listing with nothing available cannot contribute to a build, and
+            // keeping it would make `blockedBy` name a part the seller "has".
+            .filter((h) => h.availableQuantity > 0);
+        if (holdings.length === 0) {
+            return { ...empty, truncated: listing?.truncated === true };
+        }
+        /* 2 — one `getAll` over the held glossary rows for their `usedBy`. */
+        const heldIds = [...new Set(holdings.map((h) => h.partGlossaryId).filter((id) => !!id))];
+        const glossaryCol = db.collection(PART_GLOSSARY_COLLECTION);
+        const partSnaps = await db.getAll(...heldIds.map((id) => glossaryCol.doc(id)));
+        const candidateIds = new Set();
+        for (const snap of partSnaps) {
+            if (!snap.exists)
+                continue;
+            for (const id of snap.data()?.usedBy ?? []) {
+                if (id)
+                    candidateIds.add(id);
+            }
+        }
+        if (candidateIds.size === 0) {
+            return { models: [], holdings: holdings.length, truncated: listing?.truncated === true };
+        }
+        const candidates = [...candidateIds];
+        const truncatedCandidates = candidates.length > BUILDABLE_CANDIDATE_LIMIT;
+        const take = truncatedCandidates ? candidates.slice(0, BUILDABLE_CANDIDATE_LIMIT) : candidates;
+        /* 3 — one `getAll` over those compositions. */
+        const compCol = db.collection(MODEL_COMPOSITION_COLLECTION);
+        const compSnaps = await db.getAll(...take.map((id) => compCol.doc(id)));
+        const models = [];
+        for (const snap of compSnaps) {
+            if (!snap.exists)
+                continue;
+            const comp = { id: snap.id, ...snap.data() };
+            const slots = requiredSlots(comp);
+            // A composition with no resolvable slot cannot be judged; claiming it is
+            // buildable from zero requirements would be the worst possible answer.
+            if (slots.length === 0)
+                continue;
+            const matched = slots.map((s) => {
+                const m = matchSlotToHoldings({
+                    // `SlotRequirement` is deliberately narrow: the matcher's whole
+                    // input is the (part, colourway) pair, so nothing else about the
+                    // slot can accidentally influence a match.
+                    ...(s.partId ? { partId: s.partId } : {}),
+                    ...(s.expectedColourway ? { expectedColourway: s.expectedColourway } : {}),
+                }, holdings);
+                return {
+                    slotKey: String(s.slotKey),
+                    slotLabel: s.slotLabel,
+                    partName: s.partName,
+                    ...(s.partId ? { partId: s.partId } : {}),
+                    ...(s.expectedColourway ? { expectedColourway: s.expectedColourway } : {}),
+                    buildable: m.buildable,
+                };
+            });
+            models.push({
+                compositionId: comp.id,
+                name: comp.name,
+                ...(comp.categoryId ? { categoryId: comp.categoryId } : {}),
+                buildable: Math.min(...matched.map((m) => m.buildable)),
+                slots: matched,
+                blockedBy: matched.filter((m) => m.buildable === 0).map((m) => m.slotLabel),
+            });
+        }
+        models.sort((a, b) => b.buildable - a.buildable ||
+            a.blockedBy.length - b.blockedBy.length ||
+            a.name.localeCompare(b.name));
+        return {
+            models,
+            holdings: holdings.length,
+            truncated: listing?.truncated === true || truncatedCandidates,
+        };
+    }
+    catch (err) {
+        const e = normalizeError(err);
+        /*
+         * Fails CLOSED-but-loud: an empty list with `truncated: true`, so a caller
+         * renders "we could not work this out" rather than the much worse
+         * "you can build nothing" — which a seller holding a full set would read as
+         * a bug in their inventory (Root Cause #59's lesson, applied to a rollup).
+         */
+        serverLogger.warn("listBuildableModels failed", { storeId, error: e.message });
+        return { models: [], holdings: 0, truncated: true };
+    }
+}

package/dist/_internal/server/features/products/list-public.d.ts

@@ -152,6 +152,23 @@ export interface PublicProductQuery {
      * rows.
      */
     search?: string;
+    /**
+     * Category ids to scope to, carried outside `filters` for the same reason
+     * `search` is — and set ONLY when both are present.
+     *
+     * 🛑 Firestore permits one array operator per query, and the category clause
+     * (`categorySlugs` array-contains) and the search clause (`searchTxt`
+     * array-contains) are both one. So when a visitor searches inside a
+     * category, the category leaves the filter string and arrives here, where
+     * the repository can refine it in memory over the search window.
+     *
+     * 🛑 Only the DEFAULT executor honours this. The colocated Function is
+     * handed a filter string and cannot refine anything, which is why
+     * `listPublicProducts` routes this one query shape to the default executor
+     * rather than hoping a remote executor forwards the option (Root Cause #85:
+     * one query, two paths, different capabilities).
+     */
+    categoriesIn?: readonly string[];
 }
 export interface ExecutorResult {
     items: unknown[];