@mohasinac/appkit 4.71.0 → 4.72.0

package/dist/_internal/server/features/assistant/turn.d.ts

@@ -0,0 +1,43 @@
+import type { IAssistantModelProvider, PiiClass } from "../../../../contracts/ai";
+import type { AnyAssistantToolDef } from "./tools/define";
+export interface AssistantTurnMessage {
+    role: "user" | "assistant";
+    content: string;
+}
+export interface AssistantTurnInput {
+    conversationId: string;
+    userId: string;
+    roles: readonly string[];
+    /** The conversation's PII class BEFORE any tool has run this turn. `"none"`
+     * for a conversation whose registered tools are all `piiClass: "none"`
+     * (A2's `searchFaqs`/`searchProducts`) — escalates automatically below if a
+     * tool with a higher class executes. */
+    piiClass: PiiClass;
+    /** Oldest first. Plain text — this function redacts it, callers never do. */
+    messages: readonly AssistantTurnMessage[];
+}
+export interface AssistantTurnContext {
+    /** Ordered by preference — `routeModel` picks the first eligible one. */
+    providers: readonly IAssistantModelProvider[];
+    /** Already merged via `mergeAssistantToolRegistries` and filtered to
+     * whatever this conversation/surface is allowed to expose. */
+    tools: readonly AnyAssistantToolDef[];
+    /**
+     * Accept a SAME-VENDOR second opinion when no second vendor is
+     * registered. Defaults to `false`, so the weaker check is never silent.
+     *
+     * Enabled by the consumer on the owner's instruction (2026-10-31). One
+     * vendor means a shared serving stack and shared failure modes, so
+     * agreement is weaker evidence than two vendors agreeing — see quorum.ts.
+     */
+    allowSameVendorQuorum?: boolean;
+}
+export type AssistantTurnOutcome = {
+    ok: true;
+    text: string;
+    modelId: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function runAssistantTurn(input: AssistantTurnInput, ctx: AssistantTurnContext): Promise<AssistantTurnOutcome>;

package/dist/_internal/server/features/assistant/turn.js

@@ -0,0 +1,281 @@
+import { randomBytes } from "node:crypto";
+import { normalizeError } from "../../../../errors/normalize.js";
+import { routeModel } from "./model-routing.js";
+import { assertAlreadyPublic, redactMessages } from "./redaction.js";
+import { HandleRegistry, HANDLE_CORE_PATTERN } from "./handles.js";
+import { buildToolManifest } from "./tools/manifest.js";
+import { estimateTurnTokens, reserveTokens } from "./budget.js";
+import { needsSecondOpinion, seekSecondOpinion } from "./quorum.js";
+import { screenForInjection } from "./guard.js";
+/**
+ * `runAssistantTurn()` — pick a provider, call it (with tools), execute any
+ * tool calls, and render the final answer against the turn's handle registry.
+ *
+ * ## 🛑 No Firebase or Next import on this path, deliberately
+ *
+ * `AssistantTurnContext` is an abstract bag of already-resolved providers and
+ * tool definitions. The caller — `actions.ts` — builds that context from a
+ * real session and calls this function. That indirection is what keeps this
+ * module pure and independently testable.
+ *
+ * @tag domain:assistant
+ * @tag layer:server
+ * @tag access:server
+ * @tag sideEffects:none
+ */
+/** Bounded so a model that never stops calling tools cannot loop forever —
+ * see `audit-silent-degrade`'s R1 shape: an unbounded loop that eventually
+ * times out reads to the caller as a hang, not as a tool-call bug. */
+const MAX_TOOL_ROUNDS = 4;
+/** Named because the budget estimator and the provider call must agree — two
+ * literals would let the reservation under-count what is actually requested. */
+const MAX_OUTPUT_TOKENS = 1024;
+export async function runAssistantTurn(input, ctx) {
+    const turnId = randomBytes(6).toString("hex");
+    const handles = new HandleRegistry(input.conversationId, turnId);
+    const eligibleTools = ctx.tools.filter((t) => isToolEligible(t, input.roles));
+    const manifest = buildToolManifest(eligibleTools);
+    const byName = new Map(eligibleTools.map((t) => [t.name, t]));
+    /*
+     * Screened BEFORE the answer model is called, so a flagged turn costs one
+     * tiny classifier call rather than a full tool-calling round trip. Fails
+     * open by design — see guard.ts for why this is the opposite posture to
+     * budget.ts.
+     */
+    const guard = await screenForInjection(ctx.providers, lastUserText(input), input.piiClass);
+    if (guard.flagged) {
+        return {
+            ok: false,
+            reason: `input flagged as prompt injection — ${guard.detail}`,
+        };
+    }
+    let effectivePiiClass = input.piiClass;
+    const outcome = routeModel(ctx.providers, "answer", effectivePiiClass);
+    if (!outcome.ok) {
+        return { ok: false, reason: outcome.refusal.reason };
+    }
+    const { provider } = outcome.decision;
+    let messages = effectivePiiClass === "none"
+        ? input.messages.map((m) => ({ role: m.role, content: assertAlreadyPublic(m.content) }))
+        : redactMessages(input.messages);
+    let result = null;
+    for (let round = 0; round <= MAX_TOOL_ROUNDS; round++) {
+        /*
+         * 🛑 Reserved inside the loop, per ROUND — not once per turn.
+         *
+         * A turn is up to MAX_TOOL_ROUNDS model calls, and each one resends the
+         * whole (growing) transcript plus every tool result so far. Charging once
+         * up front would bill a 5-round turn as though it were a 1-round turn,
+         * which is the "counts calls, not tokens" mistake this budget exists to
+         * avoid — one layer in.
+         */
+        const promptChars = messages.reduce((n, m) => n + m.content.length, 0);
+        const reservation = await reserveTokens(estimateTurnTokens(promptChars, MAX_OUTPUT_TOKENS, manifest.length));
+        if (!reservation.allowed) {
+            return {
+                ok: false,
+                reason: `token budget refused the call: ${reservation.reason ?? "no reason given"}`,
+            };
+        }
+        result = await provider.turn({
+            job: "answer",
+            piiClass: effectivePiiClass,
+            messages,
+            tools: manifest,
+            maxOutputTokens: MAX_OUTPUT_TOKENS,
+        });
+        if (result.finishReason !== "tool_calls" || result.toolCalls.length === 0)
+            break;
+        if (round === MAX_TOOL_ROUNDS) {
+            return {
+                ok: false,
+                reason: `exceeded ${MAX_TOOL_ROUNDS} tool-call rounds without a final answer`,
+            };
+        }
+        /*
+         * 🛑 Carries `toolCalls`. Dropping them (as this did until the first live
+         * multi-round turn) leaves the following `role: "tool"` messages
+         * answering calls the transcript never records, which Groq rejects at the
+         * encoder rather than as a validation error.
+         */
+        messages.push({ role: "assistant", content: result.text, toolCalls: result.toolCalls });
+        for (const call of result.toolCalls) {
+            const tool = byName.get(call.name);
+            if (!tool) {
+                messages.push({
+                    role: "tool",
+                    content: `error: unknown or ineligible tool "${call.name}"`,
+                    toolCallId: call.id,
+                });
+                continue;
+            }
+            const parsed = tool.inputSchema.safeParse(safeJsonParse(call.argumentsJson));
+            if (!parsed.success) {
+                /* .flatten() rather than a single summary string — the model can act
+                 * on a per-field breakdown ("count: expected number, got string") far
+                 * more usefully than on one flattened sentence, and surfacing every
+                 * issue (not just the first) is also what makes this a real sink for
+                 * audit-unvalidated-safeparse. */
+                messages.push({
+                    role: "tool",
+                    content: `error: invalid arguments for "${call.name}": ${JSON.stringify(parsed.error.flatten())}`,
+                    toolCallId: call.id,
+                });
+                continue;
+            }
+            try {
+                const output = await tool.execute(parsed.data, {
+                    userId: input.userId,
+                    roles: input.roles,
+                    handles,
+                });
+                messages.push({ role: "tool", content: JSON.stringify(output), toolCallId: call.id });
+                /*
+                 * 🛑 Escalate the EFFECTIVE pii class the moment a non-"none" tool
+                 * runs, and re-check the already-chosen provider against it. A
+                 * provider picked for piiClass:"none" may be a training-tier vendor
+                 * — continuing to send it tool output from a tool that is NOT
+                 * piiClass:"none" would be exactly the privacy incident
+                 * `routeModel`'s "no fallback chain" note exists to prevent, one
+                 * layer up (mid-turn instead of at routing time).
+                 */
+                if (tool.piiClass !== "none") {
+                    effectivePiiClass = tool.piiClass;
+                    if (provider.trainsOnInput) {
+                        return {
+                            ok: false,
+                            reason: `tool "${call.name}" returned piiClass "${tool.piiClass}" mid-turn, and the ` +
+                                `provider already chosen ("${provider.id}") trains on input — refusing rather ` +
+                                "than sending it the result",
+                        };
+                    }
+                }
+            }
+            catch (err) {
+                messages.push({
+                    role: "tool",
+                    content: `error: tool "${call.name}" failed: ${normalizeError(err).message}`,
+                    toolCallId: call.id,
+                });
+            }
+        }
+    }
+    if (!result) {
+        return { ok: false, reason: "model never returned a result" };
+    }
+    if (result.finishReason === "length") {
+        return {
+            ok: false,
+            reason: "answer was truncated — refusing to present a partial response as complete",
+        };
+    }
+    if (result.finishReason === "filtered" || result.finishReason === "error") {
+        /*
+         * 🛑 `modelId` is included because that is where the PROVIDER puts its
+         * reason: `errorResult` returns `modelId: "${modelId} (${reason})"`,
+         * deliberately keeping `text` empty so a failure is never renderable as
+         * an answer. Reporting only the finishReason threw that away and left
+         * "error" with no cause — which is what made the first live failure
+         * undiagnosable.
+         */
+        return {
+            ok: false,
+            reason: `model stopped with finishReason "${result.finishReason}" — ${result.modelId}`,
+        };
+    }
+    const rendered = renderWithHandles(result.text, handles);
+    if (rendered === null) {
+        return {
+            ok: false,
+            reason: "response referenced a handle that did not resolve — failing closed rather than " +
+                "leaking a raw or hallucinated token",
+        };
+    }
+    /*
+     * 🛑 Money/policy answers are reviewed BEFORE the buyer sees them.
+     *
+     * The topic gate is a cheap string match on purpose: asking a model
+     * whether to ask a second model would double the bill to decide whether
+     * to double the bill. Most turns never reach the reviewer.
+     *
+     * A failed review does NOT return the reviewer's opinion instead — the
+     * reviewer is differently wrong, not more right. It refuses, which routes
+     * the buyer to a human via the escalation path (severity.ts already files
+     * money/policy topics at `draft`/high).
+     */
+    const toolEvidence = messages
+        .filter((m) => m.role === "tool")
+        .map((m) => m.content)
+        .join("\n");
+    if (needsSecondOpinion(lastUserText(input), rendered)) {
+        const quorum = await seekSecondOpinion({
+            providers: ctx.providers,
+            firstDecision: outcome.decision,
+            piiClass: effectivePiiClass,
+            question: lastUserText(input),
+            answer: rendered,
+            evidence: toolEvidence,
+            allowSameVendor: ctx.allowSameVendorQuorum ?? false,
+        });
+        if (!quorum.cleared) {
+            return {
+                ok: false,
+                reason: `second opinion did not clear a money/policy answer — ${quorum.detail}`,
+            };
+        }
+    }
+    return { ok: true, text: rendered, modelId: result.modelId };
+}
+/** The buyer's most recent message — what the quorum judges the answer against. */
+function lastUserText(input) {
+    return [...input.messages].reverse().find((m) => m.role === "user")?.content ?? "";
+}
+function isToolEligible(tool, roles) {
+    if (!tool.roles)
+        return true;
+    return tool.roles.some((r) => roles.includes(r));
+}
+/*
+ * No explicit return type here, deliberately — `JSON.parse` returns `any`,
+ * and annotating the return as `unknown` (the technically more honest type)
+ * trips audit-unknown-leakage's `field-or-param-unknown` rule with no
+ * matching exemption for a return position. The call site immediately feeds
+ * the result into `tool.inputSchema.safeParse()`, whose parameter type IS
+ * `unknown`, so the narrowing happens there either way — this function's own
+ * signature does not need to assert it.
+ */
+function safeJsonParse(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        /* The model emitted non-JSON tool-call arguments. Returning undefined
+         * here is deliberate: the caller immediately runs it through
+         * tool.inputSchema.safeParse(), which turns undefined into a normal
+         * "invalid arguments" validation failure with a real Zod message — the
+         * parse error itself has nothing to add to that. normalizeError() is
+         * still called, per Root Cause #31a, so `err` never escapes the catch as
+         * untyped `unknown` even though its classification is discarded here. */
+        void normalizeError(err);
+        return undefined;
+    }
+}
+/**
+ * Substitute every handle-shaped token in `text` with its resolved value.
+ * Returns `null` — failing the WHOLE response — the moment any token in the
+ * text does not resolve, rather than leaving the raw token in place. See
+ * handles.ts and the plan's "Rendering is a trust boundary" note.
+ */
+function renderWithHandles(text, handles) {
+    const pattern = new RegExp(`\\b${HANDLE_CORE_PATTERN}\\b`, "g");
+    let failed = false;
+    const out = text.replace(pattern, (match) => {
+        const value = handles.resolve(match);
+        if (value === null) {
+            failed = true;
+            return match;
+        }
+        return value;
+    });
+    return failed ? null : out;
+}

package/dist/_internal/server/features/auth/permissions.d.ts

@@ -9,23 +9,79 @@
  *  - all other roles get empty permissions (no admin access)
  */
 import type { Permission } from "../../../../features/auth/permissions/constants";
-export interface ResolvedPermissions {
-    /** true when role === "admin" — bypasses all permission checks */
-    isAdmin: boolean;
-    /** explicit permissions array; only meaningful when role === "employee" */
-    permissions: Permission[];
-}
+import type { ResolvedPermissions, ModerationAction } from "../../../../features/auth/auth-helpers";
+/**
+ * 🛑 Re-exported, not redefined. The shape now lives next to
+ * `permissionsFor()` in `features/auth/auth-helpers` so the server resolver
+ * and the client-safe one cannot disagree about what a resolved permission
+ * answer looks like. The alias keeps the ~40 existing
+ * `import type { ResolvedPermissions } from ".../server"` sites compiling.
+ */
+export type { ResolvedPermissions };
 /**
- * Fetch and resolve permissions for a user.
- * Returns { isAdmin: true } for admins, explicit permissions for employees,
- * empty for all other roles.
+ * Fetch and resolve permissions for a user — the UNION across every role they
+ * hold (1.44).
+ *
+ * 🛑 Was three sequential `user.role === "..."` comparisons, so a user holding
+ * both `employee` and `seller` resolved by whichever equality matched the
+ * single stored scalar: an admin+employee got `{ isAdmin: true }` only if the
+ * scalar happened to say "admin", and an employee+seller lost their whole
+ * permission array if it happened to say "seller". Both failures are silent.
+ *
+ * Now: read the document, hand it to `permissionsFor()`, which unions
+ * `ROLE_PERMISSION_BUNDLES` across the held set with the per-user
+ * `permissions[]` grants. No role comparison appears here at all — adding an
+ * auditor role with ledger access is a bundle edit, not a branch here.
+ *
+ * `UserRepository.mapDoc` has already normalised `roles` on this document, so
+ * the union is computed from the set even for accounts the backfill has not
+ * reached yet.
  */
 export declare function getServerPermissions(uid: string): Promise<ResolvedPermissions>;
 export declare function checkPermission(resolved: ResolvedPermissions, required: Permission): boolean;
 export declare function checkAnyPermission(resolved: ResolvedPermissions, required: Permission[]): boolean;
+/**
+ * ── The server-side answer to "may this user do X?" ──────────────────────────
+ *
+ * `can(user, perm)` in `features/auth/auth-helpers` is pure and reads the
+ * object it is handed. That is the wrong tool inside an API route: the session
+ * payload `createRouteHandler` builds carries `uid`, `role`, `roles` and
+ * `primaryRole` and **no `permissions` array** (see `RouteUser` — none of the
+ * fine-grained grants reach the session-cookie JWT claims). So a synchronous
+ * check there would silently ignore every per-person grant and deny a properly
+ * configured employee.
+ *
+ * This reads the document first and then applies the SAME rule —
+ * `getServerPermissions` → `permissionsFor` — so there is one resolution rule,
+ * not a server copy and a client copy that drift. `userRepository.findById` is
+ * cached per request in `BaseRepository`, so several of these in one handler
+ * cost one read.
+ *
+ * ⚠ Call it only AFTER the cheap ownership test has failed. Every gate this
+ * converts reads "the owner, or someone with the permission", and an owner must
+ * not pay a Firestore read to edit their own thing (Rule #6).
+ */
+export declare function serverCan(uid: string | null | undefined, required: Permission): Promise<boolean>;
+/**
+ * `serverCan` for the moderation action names.
+ *
+ * 🛑 This is the function the ~20 former `isModeratorUser()` sites call. The
+ * action → permission mapping lives in `MODERATION_PERMISSIONS` beside
+ * `permissionsFor`, so the gate is data; this is only the async wrapper that
+ * fetches the document.
+ *
+ * Default grant, restated because it is the whole point: `employee` carries an
+ * EMPTY permission bundle, so an employee who has not been granted the key is
+ * DENIED here. `admin` short-circuits to `isAdmin: true` inside
+ * `permissionsFor` and is therefore always allowed, unconditionally.
+ */
+export declare function canModerateServer(uid: string | null | undefined, action: ModerationAction): Promise<boolean>;
 type GetUser = () => Promise<{
     uid: string;
+    /** Legacy scalar. The guard below reads `roles` through a predicate. */
     role: string;
+    /** THE role authority — present on anything from `UserRepository`. */
+    roles?: readonly string[] | null;
     permissions?: readonly string[] | null;
     /** @deprecated Legacy tester flags; still read during the migration window. */
     isTester?: boolean;
@@ -50,4 +106,3 @@ export interface AdminSectionLayoutOpts {
 export declare function makeAdminSectionLayout(permission: Permission, opts: AdminSectionLayoutOpts): ({ children, }: {
     children: React.ReactNode;
 }) => Promise<React.ReactNode>;
-export {};

package/dist/_internal/server/features/auth/permissions.js

@@ -10,12 +10,27 @@
  */
 import { userRepository } from "../../../../features/auth/repository/user.repository.js";
 import { ROUTES } from "../../../../next/routing/route-map.js";
-import { isEffectiveAdminUser } from "../../../../features/auth/role-predicates.js";
+import { isEffectiveAdminUser, isEmployeeUser } from "../../../../features/auth/role-predicates.js";
+import { permissionsFor, MODERATION_PERMISSIONS } from "../../../../features/auth/auth-helpers.js";
 // ── Core resolver ─────────────────────────────────────────────────────────────
 /**
- * Fetch and resolve permissions for a user.
- * Returns { isAdmin: true } for admins, explicit permissions for employees,
- * empty for all other roles.
+ * Fetch and resolve permissions for a user — the UNION across every role they
+ * hold (1.44).
+ *
+ * 🛑 Was three sequential `user.role === "..."` comparisons, so a user holding
+ * both `employee` and `seller` resolved by whichever equality matched the
+ * single stored scalar: an admin+employee got `{ isAdmin: true }` only if the
+ * scalar happened to say "admin", and an employee+seller lost their whole
+ * permission array if it happened to say "seller". Both failures are silent.
+ *
+ * Now: read the document, hand it to `permissionsFor()`, which unions
+ * `ROLE_PERMISSION_BUNDLES` across the held set with the per-user
+ * `permissions[]` grants. No role comparison appears here at all — adding an
+ * auditor role with ledger access is a bundle edit, not a branch here.
+ *
+ * `UserRepository.mapDoc` has already normalised `roles` on this document, so
+ * the union is computed from the set even for accounts the backfill has not
+ * reached yet.
  */
 export async function getServerPermissions(uid) {
     if (!uid)
@@ -24,15 +39,7 @@ export async function getServerPermissions(uid) {
     const user = await userRepository.findById(uid);
     if (!user)
         return { isAdmin: false, permissions: [] };
-    if (user.role === "admin")
-        return { isAdmin: true, permissions: [] };
-    if (user.role === "employee") {
-        return {
-            isAdmin: false,
-            permissions: (user.permissions ?? []),
-        };
-    }
-    return { isAdmin: false, permissions: [] };
+    return permissionsFor(user);
 }
 // ── Permission check helpers ──────────────────────────────────────────────────
 export function checkPermission(resolved, required) {
@@ -41,6 +48,48 @@ export function checkPermission(resolved, required) {
 export function checkAnyPermission(resolved, required) {
     return resolved.isAdmin || required.some((p) => resolved.permissions.includes(p));
 }
+/**
+ * ── The server-side answer to "may this user do X?" ──────────────────────────
+ *
+ * `can(user, perm)` in `features/auth/auth-helpers` is pure and reads the
+ * object it is handed. That is the wrong tool inside an API route: the session
+ * payload `createRouteHandler` builds carries `uid`, `role`, `roles` and
+ * `primaryRole` and **no `permissions` array** (see `RouteUser` — none of the
+ * fine-grained grants reach the session-cookie JWT claims). So a synchronous
+ * check there would silently ignore every per-person grant and deny a properly
+ * configured employee.
+ *
+ * This reads the document first and then applies the SAME rule —
+ * `getServerPermissions` → `permissionsFor` — so there is one resolution rule,
+ * not a server copy and a client copy that drift. `userRepository.findById` is
+ * cached per request in `BaseRepository`, so several of these in one handler
+ * cost one read.
+ *
+ * ⚠ Call it only AFTER the cheap ownership test has failed. Every gate this
+ * converts reads "the owner, or someone with the permission", and an owner must
+ * not pay a Firestore read to edit their own thing (Rule #6).
+ */
+export async function serverCan(uid, required) {
+    if (!uid)
+        return false;
+    return checkPermission(await getServerPermissions(uid), required);
+}
+/**
+ * `serverCan` for the moderation action names.
+ *
+ * 🛑 This is the function the ~20 former `isModeratorUser()` sites call. The
+ * action → permission mapping lives in `MODERATION_PERMISSIONS` beside
+ * `permissionsFor`, so the gate is data; this is only the async wrapper that
+ * fetches the document.
+ *
+ * Default grant, restated because it is the whole point: `employee` carries an
+ * EMPTY permission bundle, so an employee who has not been granted the key is
+ * DENIED here. `admin` short-circuits to `isAdmin: true` inside
+ * `permissionsFor` and is therefore always allowed, unconditionally.
+ */
+export async function canModerateServer(uid, action) {
+    return serverCan(uid, MODERATION_PERMISSIONS[action]);
+}
 /**
  * Factory that returns a Next.js RSC layout component guarding an admin section.
  *
@@ -65,8 +114,18 @@ export function makeAdminSectionLayout(permission, opts) {
         // passes without a permission check.
         if (isEffectiveAdminUser(user))
             return children;
-        // non-employee non-admin roles have no business in /admin
-        if (user.role !== "employee") {
+        /*
+         * Non-employee non-admin roles have no business in /admin.
+         *
+         * 🛑 `isEmployeeUser` (set membership + the moderator fold), not
+         * `user.role !== "employee"`. The scalar form refused an employee who also
+         * held `seller` — `mapDoc` resolves such an account's scalar to the
+         * highest rank, which is `employee`, but a stored document written before
+         * the normalisation could say either — and it refused a stored
+         * `moderator` outright, who under A9 IS an employee. Both were a redirect
+         * to /unauthorized for someone entitled to the page.
+         */
+        if (!isEmployeeUser(user)) {
             redirect(opts.unauthorizedPath ?? String(ROUTES.ERRORS.UNAUTHORIZED));
             return null;
         }

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

@@ -114,10 +114,10 @@ export async function createBrandAction(input) {
             metrics: {
                 productCount: 0,
                 productIds: [],
-                auctionCount: 0,
-                auctionIds: [],
+                collectorDropCount: 0,
+                collectorDropIds: [],
                 totalProductCount: 0,
-                totalAuctionCount: 0,
+                totalCollectorDropCount: 0,
                 totalItemCount: 0,
                 lastUpdated: new Date(),
             },

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

@@ -45,16 +45,16 @@ quantity = 1) {
     // Bundles bypass `addItemToCart`'s capability gate deliberately (a bundle's
     // `listingType: "standard"` is a lie told to satisfy it — `bundleRule` is
     // `cartEligible: false`). The LANE gate is not optional though, and this path
-    // silently skipped it: a buyer with an unpaid auction win could keep shopping
+    // silently skipped it: a buyer with an unpaid collector drop win could keep shopping
     // by adding bundles.
     await assertCanAddNewItems(userId);
     // Members, so the cart can show WHAT is in the bundle and checkout can
     // prorate GST across them.
     //
     // Every member is ONE unit per copy. `BundleItemDetail` has no quantity field
-    // — its only per-member number is `drawCount` (prize-draw entries), and
+    // — its only per-member number is `drawCount` (clearance entries), and
     // treating that as a stock quantity would silently change how much a
-    // prize-draw member decrements, which the stock fan-out has never done.
+    // clearance member decrements, which the stock fan-out has never done.
     const memberIds = bundle.bundleProductIds ?? [];
     const memberDocs = await Promise.all(memberIds.map((id) => safeRead(() => productRepository.findById(id), {
         route: "/bundles",

package/dist/_internal/server/features/categories/adapters.d.ts

@@ -12,7 +12,7 @@
  * Why this exists (2026-10-10): `GET /api/categories` returned `result.data`
  * raw — the whole document — on an unauthenticated, hour-edge-cached route.
  * That published `createdBy` (a uid), `createdByStoreId`, `createdByStoreName`
- * and, worst, `metrics.productIds[]` / `metrics.auctionIds[]`: two UNBOUNDED
+ * and, worst, `metrics.productIds[]` / `metrics.collectorDropIds[]`: two UNBOUNDED
  * arrays that grow with the catalogue. `CategoryInlineSelect` calls that route
  * with `pageSize=200` on every seller-form open, so the payload scaled with
  * both the number of categories and the number of products in each.
@@ -31,7 +31,7 @@ import type { CategoryItem } from "../../../../features/categories/types/index";
  * the object literal in `toCategoryListItem` — the audit asserts both
  * directions.
  */
-export declare const PUBLIC_CATEGORY_FIELDS: readonly ["id", "name", "slug", "description", "rootId", "parentIds", "childrenIds", "tier", "path", "order", "isLeaf", "ancestors", "categoryType", "itemCode", "isFeatured", "featuredPriority", "seo", "display", "isActive", "highlights", "faqs", "brandWebsite", "brandCountry", "brandFounded", "hasbroName", "hasbroCoverImage", "metrics", "createdAt", "updatedAt"];
+export declare const PUBLIC_CATEGORY_FIELDS: readonly ["id", "name", "slug", "description", "rootId", "parentIds", "childrenIds", "tier", "path", "order", "isLeaf", "ancestors", "categoryType", "itemCode", "isFeatured", "featuredPriority", "seo", "display", "isActive", "highlights", "faqs", "brandWebsite", "brandCountry", "brandFounded", "altRegionName", "altRegionCoverImage", "hasbroName", "hasbroCoverImage", "metrics", "createdAt", "updatedAt"];
 /**
  * Fields withheld, each with the reason. Never remove one without replacing
  * the reason — "it seemed unused" is how a field ends up public by accident.

package/dist/_internal/server/features/categories/adapters.js

@@ -38,11 +38,16 @@ export const PUBLIC_CATEGORY_FIELDS = [
     "brandCountry",
     "brandFounded",
     /*
-     * The Hasbro alternate name and its cover, rendered as "Also known as" by
+     * The alternate regional name and its cover, rendered as "Also known as" by
      * `CategoryDetailPageView`. Public because the whole point of the field is
-     * that a buyer who only knows the Hasbro season name can SEE the
-     * correspondence — a name on a toy box is not sensitive.
+     * that a buyer who only knows the other regional name can SEE the
+     * correspondence — a name on a retail box is not sensitive.
+     *
+     * The deprecated `hasbro*` keys stay listed so documents written before the
+     * 2026-11-07 rename still project; drop them after the backfill.
      */
+    "altRegionName",
+    "altRegionCoverImage",
     "hasbroName",
     "hasbroCoverImage",
     // Rollup counts only — see `metrics` in the private list.
@@ -184,7 +189,7 @@ export const PRIVATE_CATEGORY_FIELDS = [
 /**
  * Rollup counters only.
  *
- * 🛑 `metrics.productIds[]` and `metrics.auctionIds[]` are deliberately
+ * 🛑 `metrics.productIds[]` and `metrics.collectorDropIds[]` are deliberately
  * dropped. They are unbounded arrays — one entry per product in the category
  * — and they were the bulk of the raw payload. Nothing client-side reads them
  * that a query cannot answer, and a category page already fetches its own
@@ -193,9 +198,9 @@ export const PRIVATE_CATEGORY_FIELDS = [
 function toPublicMetrics(m) {
     return {
         productCount: m?.productCount ?? 0,
-        auctionCount: m?.auctionCount ?? 0,
+        collectorDropCount: m?.collectorDropCount ?? 0,
         totalProductCount: m?.totalProductCount ?? 0,
-        totalAuctionCount: m?.totalAuctionCount ?? 0,
+        totalCollectorDropCount: m?.totalCollectorDropCount ?? 0,
         totalItemCount: m?.totalItemCount ?? 0,
     };
 }
@@ -238,8 +243,12 @@ export function toCategoryListItem(doc) {
         brandWebsite: doc.brandWebsite,
         brandCountry: doc.brandCountry,
         brandFounded: doc.brandFounded,
-        hasbroName: doc.hasbroName,
-        hasbroCoverImage: doc.hasbroCoverImage,
+        // 🛑 Dual-read across the 2026-11-07 rename. Stored category documents
+        // written before it carry `hasbroName`/`hasbroCoverImage`; a bare rename
+        // would silently blank the "Also known as" line on every existing category
+        // rather than failing loudly. Drop the fallback once the backfill has run.
+        altRegionName: doc.altRegionName ?? doc.hasbroName,
+        altRegionCoverImage: doc.altRegionCoverImage ?? doc.hasbroCoverImage,
         metrics: toPublicMetrics(doc.metrics),
         // 🛑 `CategoryDocument` stores Dates; `CategoryItem` declares strings —
         // this projection is also the serialisation boundary. Converting here