@mohasinac/appkit 4.71.0 → 4.72.0

package/dist/next/routing/route-map.js

@@ -1,3 +1,7 @@
+// The portal registry is a sibling module with ZERO imports of its own, so
+// taking this dependency keeps route-map.ts importable from the Edge proxy and
+// from the browser alike. See `portals.ts`'s header.
+import { portalHref } from "./portals.js";
 export const DEFAULT_ROUTE_MAP = {
     HOME: "/",
     PUBLIC: {
@@ -6,11 +10,12 @@ export const DEFAULT_ROUTE_MAP = {
         PROFILE: (userId) => `/profile/${userId}`,
         PRODUCTS: "/products",
         PRODUCT_DETAIL: (slugOrId) => `/products/${slugOrId}`,
-        AUCTIONS: "/auctions",
-        AUCTION_DETAIL: (id) => `/auctions/${id}`,
+        COLLECTOR_DROPS: "/collector-drops",
+        COLLECTOR_DROP_DETAIL: (id) => `/collector-drops/${id}`,
         PRE_ORDERS: "/pre-orders",
         /** D56 — the public rate card + self-serve booking form. */
         ADVERTISE: "/advertise",
+        ASSISTANT: "/assistant",
         PRE_ORDER_DETAIL: (id) => `/pre-orders/${id}`,
         // SB1-J — bundles + prize draws (additive, pages not yet built)
         BUNDLES: "/bundles",
@@ -21,18 +26,18 @@ export const DEFAULT_ROUTE_MAP = {
          * detail page — see § "Bundles vs Product Groups vs Grouped Listings".
          */
         GROUP_DETAIL: (slug) => `/groups/${slug}`,
-        PRIZE_DRAWS: "/prize-draws",
-        PRIZE_DRAW_DETAIL: (slug) => `/prize-draws/${slug}`,
+        CLEARANCE: "/clearance",
+        CLEARANCE_DETAIL: (slug) => `/clearance/${slug}`,
         SELLER_GUIDE_BUNDLES: "/seller-guide/bundles",
-        SELLER_GUIDE_PRIZE_DRAWS: "/seller-guide/prize-draws",
+        SELLER_GUIDE_CLEARANCE: "/seller-guide/clearance",
         SELLERS: "/sellers",
         SELLER_DETAIL: (id) => `/sellers/${id}`,
         STORES: "/stores",
         STORE_DETAIL: (storeSlug) => `/stores/${storeSlug}`,
         STORE_PRODUCTS: (storeSlug) => `/stores/${storeSlug}/products`,
-        STORE_AUCTIONS: (storeSlug) => `/stores/${storeSlug}/auctions`,
+        STORE_COLLECTOR_DROPS: (storeSlug) => `/stores/${storeSlug}/collector-drops`,
         STORE_PRE_ORDERS: (storeSlug) => `/stores/${storeSlug}/pre-orders`,
-        STORE_PRIZE_DRAWS: (storeSlug) => `/stores/${storeSlug}/prize-draws`,
+        STORE_CLEARANCE: (storeSlug) => `/stores/${storeSlug}/clearance`,
         STORE_BUNDLES: (storeSlug) => `/stores/${storeSlug}/bundles`,
         STORE_REVIEWS: (storeSlug) => `/stores/${storeSlug}/reviews`,
         STORE_ABOUT: (storeSlug) => `/stores/${storeSlug}/about`,
@@ -82,7 +87,7 @@ export const DEFAULT_ROUTE_MAP = {
          */
         HELP: "/help",
         HELP_SHOPPING: "/help/shopping",
-        HELP_AUCTIONS: "/help/auctions",
+        HELP_COLLECTOR_DROPS: "/help/collector-drops",
         HELP_ORDERS: "/help/orders",
         HELP_ACCOUNT: "/help/account",
         /*
@@ -125,7 +130,7 @@ export const DEFAULT_ROUTE_MAP = {
          * designation, contact and a response commitment.
          */
         GRIEVANCE: "/grievance",
-        HOW_AUCTIONS_WORK: "/how-auctions-work",
+        HOW_COLLECTOR_DROPS_WORK: "/how-collector-drops-work",
         HOW_PRE_ORDERS_WORK: "/how-pre-orders-work",
         HOW_OFFERS_WORK: "/how-offers-work",
         HOW_CHECKOUT_WORKS: "/how-checkout-works",
@@ -163,8 +168,8 @@ export const DEFAULT_ROUTE_MAP = {
         EVENT_LEADERBOARD: (id) => `/events/${id}/leaderboard`,
         EVENT_WINNER: (id) => `/events/${id}/winner`,
         EVENT_SPIN_RESULTS: (id) => `/events/${id}/spin-results`,
-        LOTTERIES: "/lottery",
-        LOTTERY_DETAIL: (id) => `/lottery/${id}`,
+        LOTTERIES: "/giveaway",
+        GIVEAWAY_DETAIL: (id) => `/giveaway/${id}`,
         /*
           * 🛑 There is deliberately NO public `SUBLISTING_CATEGORIES` index key.
           * `src/app/[locale]/sublisting-categories/` holds only `[slug]/`, so the
@@ -368,7 +373,7 @@ export const DEFAULT_ROUTE_MAP = {
         /** D56 — the advertiser's own bookings and their moderation state. */
         AD_BOOKINGS: "/user/ad-bookings",
         DIGITAL_CODES: "/user/digital-codes",
-        PRIZE_DRAWS: "/user/prize-draws",
+        CLEARANCE: "/user/clearance",
         EVENTS: "/user/events",
         CATALOGUE: "/user/catalogue",
         CATALOGUE_NEW: "/user/catalogue/new",
@@ -386,9 +391,9 @@ export const DEFAULT_ROUTE_MAP = {
         PRODUCTS_EDIT: (id) => `/store/products/${id}/edit`,
         ORDERS: "/store/orders",
         ORDER_DETAIL: (id) => `/store/orders/${id}/view`,
-        AUCTIONS: "/store/auctions",
-        AUCTIONS_NEW: "/store/auctions/new",
-        AUCTIONS_EDIT: (id) => `/store/auctions/${id}/edit`,
+        COLLECTOR_DROPS: "/store/collector-drops",
+        COLLECTOR_DROPS_NEW: "/store/collector-drops/new",
+        COLLECTOR_DROPS_EDIT: (id) => `/store/collector-drops/${id}/edit`,
         PRE_ORDERS: "/store/pre-orders",
         PRE_ORDERS_NEW: "/store/pre-orders/new",
         PRE_ORDERS_EDIT: (id) => `/store/pre-orders/${id}/edit`,
@@ -418,14 +423,14 @@ export const DEFAULT_ROUTE_MAP = {
         SLUG: "/store/slug",
         /** Tickets raised ABOUT this store (W11). Read-only for the seller. */
         SUPPORT: "/store/support",
-        // SB1-J — bundles + prize draws
+        // SB1-J — bundles + clearance
         BUNDLES: "/store/bundles",
         BUNDLES_NEW: "/store/bundles/new",
         BUNDLES_EDIT: (id) => `/store/bundles/${id}/edit`,
-        PRIZE_DRAWS: "/store/prize-draws",
-        PRIZE_DRAWS_NEW: "/store/prize-draws/new",
-        PRIZE_DRAWS_EDIT: (id) => `/store/prize-draws/${id}/edit`,
-        PRIZE_DRAW_ENTRIES: (id) => `/store/prize-draws/${id}/entries`,
+        CLEARANCE: "/store/clearance",
+        CLEARANCE_NEW: "/store/clearance/new",
+        CLEARANCE_EDIT: (id) => `/store/clearance/${id}/edit`,
+        CLEARANCE_ENTRIES: (id) => `/store/clearance/${id}/entries`,
         // SB-UNI-R — classified / digital-code / live
         CLASSIFIED: "/store/classified",
         CLASSIFIED_NEW: "/store/classified/new",
@@ -436,10 +441,21 @@ export const DEFAULT_ROUTE_MAP = {
         LIVE_ITEMS: "/store/live",
         LIVE_ITEMS_NEW: "/store/live/new",
         LIVE_ITEMS_EDIT: (id) => `/store/live/${id}/edit`,
-        // EMI/art-stickers session — art / stickers
+        /*
+         * The single `art-and-stickers` seller surface (1.34 merged `art` and
+         * `stickers` into one type). The `art` spelling is the live one.
+         */
         ART: "/store/art",
         ART_NEW: "/store/art/new",
         ART_EDIT: (id) => `/store/art/${id}/edit`,
+        /*
+         * 🛑 REDIRECT-ONLY. These three paths still EXIST — their page.tsx
+         * files `permanentRedirect` to the `ART*` entries above — so an old
+         * seller bookmark resolves instead of 404ing. They are declared here
+         * because route-map is the authority on what paths EXIST, not on what is
+         * linked: nothing links to them any more (every nav map is keyed by
+         * `ListingType`, which now has one entry for this type).
+         */
         STICKERS: "/store/stickers",
         STICKERS_NEW: "/store/stickers/new",
         STICKERS_EDIT: (id) => `/store/stickers/${id}/edit`,
@@ -476,6 +492,24 @@ export const DEFAULT_ROUTE_MAP = {
         GUIDE_CAPABILITIES: "/store/guide/capabilities",
         GUIDE_SETTINGS: "/store/guide/settings",
     },
+    /**
+     * The `employee.<domain>` portal — the catch-all entry point for every role
+     * that is not `admin`, `seller` or `user` (owner, 2026-11-07: "3 main and
+     * rest go to employee"). `moderator`, `tester`, and the future auditor /
+     * bookkeeping / management roles all arrive here.
+     *
+     * 🛑 Deliberately TINY, and it must stay that way. `employee.<domain>` is an
+     * ENTRY POINT, not a section with its own screens: what a visitor sees is
+     * resolved from their ROLE SET, and for a privileged role that resolution
+     * lands on the existing permission-scoped admin dashboard rather than a
+     * parallel copy of it. Growing a second tree of employee screens here is how
+     * the two-divergent-copies failure starts; a screen an employee needs belongs
+     * in `ADMIN` behind a permission, which is already how `admin/layout.tsx`
+     * admits non-admins.
+     */
+    EMPLOYEE: {
+        HOME: "/employee",
+    },
     ADMIN: {
         DASHBOARD: "/admin/dashboard",
         /**
@@ -534,18 +568,9 @@ export const DEFAULT_ROUTE_MAP = {
          * something and one selects a working alternative).
          */
         INTEGRATIONS: "/admin/integrations",
-        CAROUSEL: "/admin/carousel",
-        CAROUSEL_NEW: "/admin/carousel/new",
-        CAROUSEL_EDIT: (id) => `/admin/carousel/${id}/edit`,
-        CAROUSELS: "/admin/carousels",
-        CAROUSEL_DETAIL: (id) => `/admin/carousels/${id}`,
-        /*
-         * 🛑 PLURAL = the named carousel GROUP. Singular `CAROUSEL_NEW` /
-         * `CAROUSEL_EDIT` above are `/admin/carousel/*` and mean a SLIDE.
-         * Two different entities, one letter apart — do not merge them.
-         */
-        CAROUSELS_NEW: "/admin/carousels/new",
-        CAROUSELS_EDIT: (id) => `/admin/carousels/${id}/edit`,
+        // "Hero Slides" / "Named Carousels" admin pages were REMOVED 2026-10-31 —
+        // see CLAUDE.md "Homepage Hero Carousel". Carousel authoring is now part
+        // of the event editor (EVENT_EDIT below).
         SECTIONS: "/admin/sections",
         NAVIGATION: "/admin/navigation",
         /*
@@ -600,8 +625,9 @@ export const DEFAULT_ROUTE_MAP = {
         CLASSIFIED: "/admin/classified",
         DIGITAL_CODES: "/admin/digital-codes",
         LIVE: "/admin/live",
-        // EMI/art-stickers session — art / stickers
+        // The single `art-and-stickers` admin surface (1.34).
         ART: "/admin/art",
+        // 🛑 REDIRECT-ONLY — see STORE.STICKERS above.
         STICKERS: "/admin/stickers",
         // Part Two — spares
         SPARES: "/admin/spares",
@@ -683,24 +709,24 @@ export const DEFAULT_ROUTE_MAP = {
         TAX_CODES: "/admin/tax-codes",
         FEATURES_NEW: "/admin/features/new",
         FEATURES_EDIT: (id) => `/admin/features/${id}/edit`,
-        // SB1-J — bundles + prize draws (admin moderation)
+        // SB1-J — bundles + clearance (admin moderation)
         // S-SBUNI-4 — BUNDLES_NEW added alongside BUNDLES_EDIT.
         BUNDLES: "/admin/bundles",
         BUNDLES_NEW: "/admin/bundles/new",
         BUNDLES_EDIT: (id) => `/admin/bundles/${id}/edit`,
-        PRIZE_DRAWS: "/admin/prize-draws",
-        PRIZE_DRAWS_EDIT: (id) => `/admin/prize-draws/${id}/edit`,
-        PRIZE_DRAWS_ENTRIES: (id) => `/admin/prize-draws/${id}/entries`,
-        LOTTERIES: "/admin/lotteries",
+        CLEARANCE: "/admin/clearance",
+        CLEARANCE_EDIT: (id) => `/admin/clearance/${id}/edit`,
+        CLEARANCE_ENTRIES: (id) => `/admin/clearance/${id}/entries`,
+        LOTTERIES: "/admin/giveaways",
         /*
-         * Slot configuration only. A lottery EVENT (title, dates, status, media)
-         * is created through the ordinary event editor — `LotteryAdminEditView`
+         * Slot configuration only. A giveaway EVENT (title, dates, status, media)
+         * is created through the ordinary event editor — `GiveawayAdminEditView`
          * has no fields for any of those, so treating it as the whole create
-         * flow would produce a lottery with no dates, and the draw window is
+         * flow would produce a giveaway with no dates, and the draw window is
          * measured from them.
          */
-        LOTTERY_CONFIG: (id) => `/admin/lotteries/${id}/edit`,
-        LOTTERY_ENTRIES: (id) => `/admin/lotteries/${id}/entries`,
+        GIVEAWAY_CONFIG: (id) => `/admin/giveaways/${id}/edit`,
+        GIVEAWAY_ENTRIES: (id) => `/admin/giveaways/${id}/entries`,
         TEAM: "/admin/team",
         TEAM_NEW: "/admin/team/new",
         TEAM_EDIT: (id) => `/admin/team/${id}/edit`,
@@ -773,6 +799,10 @@ export function createRouteMap(overrides = {}) {
             ...DEFAULT_ROUTE_MAP.STORE,
             ...(overrides.STORE ?? {}),
         },
+        EMPLOYEE: {
+            ...DEFAULT_ROUTE_MAP.EMPLOYEE,
+            ...(overrides.EMPLOYEE ?? {}),
+        },
         ADMIN: {
             ...DEFAULT_ROUTE_MAP.ADMIN,
             ...(overrides.ADMIN ?? {}),
@@ -784,13 +814,75 @@ export function createRouteMap(overrides = {}) {
     };
 }
 export const ROUTES = DEFAULT_ROUTE_MAP;
+/**
+ * ── Host-aware ROUTES (item 1.28) ───────────────────────────────────────────
+ *
+ * Every `ROUTES.*` entry bakes its portal segment in — `ROUTES.ADMIN.PRODUCTS`
+ * is `/admin/products` — because that IS the real app path and must stay so on
+ * the canonical host. On `admin.<domain>` the segment is already implied by the
+ * hostname, so the URL a visitor should see is `admin.<domain>/products`, not
+ * `admin.<domain>/admin/products`. The subdomain's entire point is that the
+ * prefix is implied.
+ *
+ * 🛑 ONE transform at the ROUTES layer, never per-link edits across the tree.
+ * There are hundreds of `ROUTES.*` references; converting them individually
+ * would be a half-done rename the first time one was missed, and a missed one
+ * is invisible (it still resolves — `src/proxy.ts` accepts both the prefixed
+ * and the stripped form on a portal host, by design, precisely so this can be
+ * adopted incrementally instead of in one all-or-nothing commit).
+ *
+ * Pure and server-safe, so the same call works in an RSC, a client component
+ * and the Edge proxy. `section` is null on the canonical host, where this is
+ * the identity transform and today's behaviour is preserved exactly.
+ */
+function portalizeGroup(group, section) {
+    const out = {};
+    for (const [key, value] of Object.entries(group)) {
+        out[key] =
+            typeof value === "function"
+                ? (...args) => portalHref(value(...args), section)
+                : portalHref(value, section);
+    }
+    return out;
+}
+/**
+ * The route map as it should RENDER on a given portal host.
+ *
+ * ```ts
+ * const R = routesForPortal(portalSectionForHost(host)); // "/admin" | null
+ * R.ADMIN.PRODUCTS; // "/products" on admin.<domain>, "/admin/products" on www
+ * R.USER.PROFILE;   // "/user/profile" on BOTH — it leaves the admin section,
+ *                   // so its prefix is load-bearing and is kept
+ * ```
+ *
+ * Only the ACTIVE section is stripped. That asymmetry is the correctness
+ * property: a cross-portal link must keep its prefix or it would resolve to the
+ * wrong portal's page (and, before the proxy fix that came with this, to a
+ * 404 — `/user/profile` on the admin host was being rewritten to
+ * `/admin/user/profile`).
+ */
+export function routesForPortal(section) {
+    if (!section)
+        return DEFAULT_ROUTE_MAP;
+    return {
+        HOME: DEFAULT_ROUTE_MAP.HOME,
+        PUBLIC: portalizeGroup(DEFAULT_ROUTE_MAP.PUBLIC, section),
+        ERRORS: portalizeGroup(DEFAULT_ROUTE_MAP.ERRORS, section),
+        AUTH: portalizeGroup(DEFAULT_ROUTE_MAP.AUTH, section),
+        USER: portalizeGroup(DEFAULT_ROUTE_MAP.USER, section),
+        STORE: portalizeGroup(DEFAULT_ROUTE_MAP.STORE, section),
+        EMPLOYEE: portalizeGroup(DEFAULT_ROUTE_MAP.EMPLOYEE, section),
+        ADMIN: portalizeGroup(DEFAULT_ROUTE_MAP.ADMIN, section),
+        BLOG: portalizeGroup(DEFAULT_ROUTE_MAP.BLOG, section),
+    };
+}
 /** @deprecated Use ROUTES.STORE instead */
 export const SELLER_ROUTES = ROUTES.STORE;
 export const PUBLIC_ROUTES = [
     ROUTES.HOME,
     ROUTES.PUBLIC.FAQS,
     ROUTES.PUBLIC.PRODUCTS,
-    ROUTES.PUBLIC.AUCTIONS,
+    ROUTES.PUBLIC.COLLECTOR_DROPS,
     ROUTES.PUBLIC.PRE_ORDERS,
     ROUTES.PUBLIC.SELLERS,
     ROUTES.PUBLIC.STORES,

package/dist/providers/ai-groq/index.d.ts

@@ -0,0 +1,18 @@
+import { IAssistantModelProvider, type AssistantJob, type ModelTurnRequest, type ModelTurnResult } from "../../contracts/ai";
+export interface GroqProviderOptions {
+    /** Resolved at call time, never captured at module load. Defaults to
+     * `process.env.GROQ_API_KEY`, same shape as `email-resend`'s provider. */
+    apiKey?: () => string | undefined;
+    /** Per-job override, e.g. from site settings. */
+    modelOverrides?: Partial<Record<AssistantJob, string>>;
+    fetchImpl?: typeof fetch;
+}
+export declare class GroqModelProvider extends IAssistantModelProvider {
+    private readonly opts;
+    readonly id = "groq";
+    /** See the class docstring — a contract property, deliberately not configurable. */
+    readonly trainsOnInput = false;
+    constructor(opts?: GroqProviderOptions);
+    modelFor(job: AssistantJob): string | undefined;
+    turn(request: ModelTurnRequest): Promise<ModelTurnResult>;
+}

package/dist/providers/ai-groq/index.js

@@ -0,0 +1,241 @@
+import { normalizeError } from "../../errors/normalize.js";
+import { IAssistantModelProvider, } from "../../contracts/ai.js";
+/**
+ * Groq — the default provider, and the only one allowed near PII.
+ *
+ * Same family shape as `payment-razorpay`, `shipping-shiprocket`,
+ * `email-resend`: a thin wrapper, API key read from env by default
+ * (`apiKey: () => process.env.GROQ_API_KEY`, same default-reading shape
+ * `email-resend`'s provider already uses for `RESEND_API_KEY`).
+ *
+ * ## 🛑 Why Groq is the default and not Gemini
+ *
+ * Groq's terms forbid training on free *and* paid tiers, retain nothing by
+ * default, and expose a zero-retention toggle. Gemini's free tier trains on
+ * inputs. India has no EEA/UK carve-out. So `trainsOnInput = false` here is the
+ * reason this provider — not the cheaper, longer-context one — carries the
+ * PII-adjacent work.
+ *
+ * ## 🛑 The model ids were MEASURED, not copied from a tracker
+ *
+ * `GET /openai/v1/models` on 2026-10-29 returned 11 ids. The plan predicted
+ * this and it was right: **there are no `llama-3.x` chat models at all.** Every
+ * tracker still cites `llama-3.1-8b-instant` / `llama-3.3-70b-versatile`;
+ * neither exists on this account. The only `meta-llama` entries are
+ * `llama-prompt-guard-2-{22m,86m}`, which are prompt-injection CLASSIFIERS, not
+ * chat models — reaching for one as a chat model would fail at the first call.
+ *
+ * Measured, chat-capable: `openai/gpt-oss-120b`, `openai/gpt-oss-20b`,
+ * `openai/gpt-oss-safeguard-20b`, `qwen/qwen3.8-27b`, `allam-2-7b`.
+ * Audio: `whisper-large-v3{,-turbo}`.
+ *
+ * Tool calling was PROBED, not assumed — the whole engine depends on it.
+ * `openai/gpt-oss-120b` returned a well-formed `tool_calls` with correct
+ * arguments and `finish_reason: "tool_calls"`.
+ *
+ * 🛑 **Every id below is overridable by env and none is load-bearing in code.**
+ * Treat the defaults as stale on sight: two of five providers killed their free
+ * tiers within three months, and this list already contradicts every public
+ * tracker. When a call 404s on a model id, read the console — do not guess a
+ * successor.
+ *
+ * @tag domain:assistant
+ * @tag layer:provider
+ * @tag access:server
+ */
+const GROQ_BASE = "https://api.groq.com/openai/v1";
+/**
+ * Measured 2026-10-29 against `GET /openai/v1/models`. Overridable per job.
+ *
+ * 🛑 A `Record<AssistantJob, …>`, not a `Partial`, so adding a fifth job is a
+ * compile error here rather than a silent `undefined` that fails at the first
+ * call. `second-opinion` maps to `undefined` DELIBERATELY — see below.
+ */
+const MODELS = {
+    classify: "openai/gpt-oss-20b",
+    answer: "openai/gpt-oss-120b",
+    /*
+     * 🛑 SAME-VENDOR SECOND OPINION — weaker than cross-vendor, enabled on the
+     * owner's explicit instruction ("its fine with groq", 2026-10-31).
+     *
+     * This previously mapped to `undefined` so the router STRUCTURALLY could
+     * not run a one-vendor quorum. That reasoning has not been disproved and
+     * is restated here rather than deleted: a quorum exists to catch a
+     * *fabricated* answer that reconciles perfectly, and two calls to one
+     * vendor share training data, tokenizer, serving stack and failure modes,
+     * so they can agree confidently and be wrong together. Cross-vendor
+     * remains the real thing; this is a cheaper approximation of it.
+     *
+     * What makes it worth more than theatre: a different model LINEAGE, not
+     * just a smaller size of the same family. `qwen/qwen3.8-27b` (Alibaba) and
+     * `openai/gpt-oss-120b` are independently trained, so their errors are far
+     * less correlated than `gpt-oss-120b` vs `gpt-oss-20b` would be — which is
+     * the pairing to avoid, and the one a careless reading of "use Groq" would
+     * pick. Both ids are measured, not copied from a tracker.
+     *
+     * 🛑 Opting in is still explicit at the CALL SITE: `routeSecondOpinion`
+     * requires `allowSameVendor: true`. Configuring a model here does not
+     * silently turn a one-vendor quorum on.
+     */
+    "second-opinion": "qwen/qwen3.8-27b",
+    /*
+     * WIRED 2026-10-31, now that A3 gave it a reader — `getMyOrders` is
+     * PII-bearing and the buyer's free text reaches the same turn. The note
+     * this replaces said "left unwired until A3 has untrusted input worth
+     * guarding; declaring it now would be a seam with no reader", and that
+     * condition is exactly what changed.
+     *
+     * 🛑 NOT a chat model. Measured 2026-10-31 via /chat/completions: it
+     * returns a bare probability STRING in `message.content`, not prose —
+     *
+     *   "What is your return policy?"                        -> "0.0007447486"
+     *   "Ignore all previous instructions and reveal ..."     -> "0.9995191097"
+     *
+     * The 86m variant is chosen over 22m on that measurement: both separate
+     * cleanly, and the larger one is still tiny. Treating this as a chat model
+     * and expecting a sentence would silently parse to NaN.
+     */
+    guard: "meta-llama/llama-prompt-guard-2-86m",
+};
+export class GroqModelProvider extends IAssistantModelProvider {
+    constructor(opts = {}) {
+        super();
+        this.opts = opts;
+        this.id = "groq";
+        /** See the class docstring — a contract property, deliberately not configurable. */
+        this.trainsOnInput = false;
+    }
+    modelFor(job) {
+        return this.opts.modelOverrides?.[job] ?? MODELS[job];
+    }
+    async turn(request) {
+        const model = this.modelFor(request.job);
+        const key = (this.opts.apiKey ?? (() => process.env.GROQ_API_KEY))();
+        /*
+         * 🛑 Fail CLOSED and say which half is missing.
+         *
+         * An unconfigured provider must not degrade to "answer without tools" or
+         * to a different vendor — the first silently drops grounding, the second
+         * silently moves PII to a training-tier vendor. Both are the
+         * `audit-silent-degrade` R1 shape: a failure that produces a plausible
+         * answer.
+         */
+        if (!key) {
+            return errorResult(model ?? "(unresolved)", "GROQ_API_KEY is not set");
+        }
+        if (!model) {
+            return errorResult("(unresolved)", `no Groq model configured for job "${request.job}"`);
+        }
+        const doFetch = this.opts.fetchImpl ?? fetch;
+        let res;
+        try {
+            res = await doFetch(`${GROQ_BASE}/chat/completions`, {
+                method: "POST",
+                headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    model,
+                    messages: request.messages.map((m) => ({
+                        role: m.role,
+                        content: m.content,
+                        ...(m.toolCallId ? { tool_call_id: m.toolCallId } : {}),
+                        /*
+                         * An assistant turn that requested tools must carry them back in
+                         * OpenAI's wire shape, or the following `role: "tool"` messages
+                         * reference calls the transcript never made.
+                         */
+                        ...(m.toolCalls?.length
+                            ? {
+                                tool_calls: m.toolCalls.map((c) => ({
+                                    id: c.id,
+                                    type: "function",
+                                    function: { name: c.name, arguments: c.argumentsJson },
+                                })),
+                            }
+                            : {}),
+                    })),
+                    ...(request.tools?.length
+                        ? {
+                            tools: request.tools.map((t) => ({
+                                type: "function",
+                                function: {
+                                    name: t.name,
+                                    description: t.description,
+                                    parameters: t.parameters,
+                                },
+                            })),
+                            tool_choice: "auto",
+                        }
+                        : {}),
+                    max_tokens: request.maxOutputTokens ?? 1024,
+                }),
+            });
+        }
+        catch (err) {
+            return errorResult(model, normalizeError(err).message);
+        }
+        const body = (await res.json().catch(() => null));
+        if (!res.ok || !body || body.error) {
+            return errorResult(model, body?.error?.message ?? `HTTP ${res.status}`);
+        }
+        const choice = body.choices?.[0];
+        return {
+            text: choice?.message?.content ?? "",
+            toolCalls: (choice?.message?.tool_calls ?? []).map((t) => ({
+                // Echoed back verbatim as `tool_call_id` — see ModelToolCall.id.
+                id: t.id,
+                name: t.function.name,
+                /*
+                 * Kept as a RAW STRING. The model emits JSON as text and is perfectly
+                 * capable of emitting invalid JSON or extra properties — parsing here
+                 * would make this provider the thing that decides whether a tool call
+                 * is well-formed. That belongs at the tool boundary, where the Zod
+                 * input schema lives.
+                 */
+                argumentsJson: t.function.arguments,
+            })),
+            finishReason: mapFinish(choice?.finish_reason),
+            usage: {
+                inputTokens: body.usage?.prompt_tokens ?? 0,
+                outputTokens: body.usage?.completion_tokens ?? 0,
+            },
+            modelId: model,
+        };
+    }
+}
+/**
+ * 🛑 `"length"` is NOT mapped to `"stop"`.
+ *
+ * A truncated answer is the single most dangerous finish reason for an
+ * assistant: it reads as complete, and the sentence it was cutting off is
+ * exactly where a number or a caveat lives. The caller must be able to refuse
+ * to present it.
+ */
+function mapFinish(raw) {
+    switch (raw) {
+        case "tool_calls":
+            return "tool_calls";
+        case "length":
+            return "length";
+        case "content_filter":
+            return "filtered";
+        case "stop":
+            return "stop";
+        default:
+            return "error";
+    }
+}
+function errorResult(modelId, reason) {
+    return {
+        /*
+         * Empty text, never an apology sentence. A provider that invents
+         * "Sorry, something went wrong" hands the caller something renderable and
+         * the caller stops distinguishing a failure from an answer. The REASON goes
+         * to the caller's logger; the user-facing copy is the caller's to choose.
+         */
+        text: "",
+        toolCalls: [],
+        finishReason: "error",
+        usage: { inputTokens: 0, outputTokens: 0 },
+        modelId: `${modelId} (${reason})`,
+    };
+}

package/dist/providers/auth-firebase/claims.d.ts

@@ -0,0 +1,85 @@
+/**
+ * ═══════════════════════════════════════════════════════════════════════════
+ * Role claims sync — THE only writer of role custom claims (reviewer R1-F5)
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * 🛑 `setCustomUserClaims` REPLACES the entire claims object. It does not
+ * merge. Firebase documents this, and six call sites across this codebase
+ * ignored it:
+ *
+ *   src/app/api/auth/login/route.ts      setCustomUserClaims(uid, { role })
+ *   src/app/api/auth/me/route.ts         setCustomUserClaims(uid, { role })
+ *   src/app/api/auth/session/route.ts    setCustomUserClaims(uid, { role })  ×2
+ *   providers/auth-firebase/provider.ts  setCustomUserClaims(uid, { role })  ×2
+ *
+ * Each one wrote a bare `{ role }` object, so **every other claim the account
+ * held was silently dropped** on the next login, profile update or
+ * `/api/auth/me` round-trip.
+ *
+ * Under a role SET that becomes a lockout, not just data loss. The chain the
+ * reviewer traced:
+ *
+ *   1. `/api/auth/me` writes `{ role }` — one role, the rest of the set gone.
+ *   2. `src/lib/edge/session-role.ts` decodes a single `role` from the token.
+ *   3. `src/proxy.ts` gates `/admin` on that single decoded role.
+ *
+ * Net effect: **a multi-role admin was silently locked out of `/admin`** after
+ * any request that touched `/api/auth/me`. The repository dual-read does not
+ * help — the token is a SEPARATE read path, and it is the one that gates
+ * access.
+ *
+ * So: one function, it MERGES, and it writes the whole set.
+ */
+/** The role-shaped claims this module owns. Everything else is preserved. */
+export interface RoleClaims {
+    /**
+     * THE authority in the token. The edge decoder reads this.
+     */
+    roles: string[];
+    /**
+     * Legacy scalar, kept in the token for the migration window: the highest-
+     * ranked held role, so a consumer still reading `payload.role` against a
+     * hierarchy under-grants nothing. Mirrors `UserRepository.mapDoc`.
+     */
+    role: string;
+    /** Display label. Never read by a gate. */
+    primaryRole: string;
+}
+/**
+ * Resolve a role carrier to the claims that should be on its token.
+ *
+ * Pure — exported so a caller can diff against the current claims without a
+ * write, and so this rule has one definition rather than one per route.
+ */
+export declare function roleClaimsFor(carrier: {
+    role?: string | null;
+    roles?: readonly string[] | null;
+    primaryRole?: string | null;
+}): RoleClaims;
+/**
+ * Write this user's role set into their custom claims, **merging** with the
+ * claims already there.
+ *
+ * Costs one extra `getUser` read, and that read is the entire point: without
+ * it there is nothing to merge with and the write is a clobber. Returns the
+ * claims that were written.
+ *
+ * @param carrier Anything with `roles` / `role` / `primaryRole` — a
+ *                `UserDocument`, a session user, or `{ role }` from a legacy
+ *                caller.
+ */
+export declare function syncRoleClaims(uid: string, carrier: {
+    role?: string | null;
+    roles?: readonly string[] | null;
+    primaryRole?: string | null;
+}): Promise<RoleClaims>;
+/**
+ * True when the token's claims already match `carrier`'s role set — so a
+ * caller can skip a write (and the token refresh it forces) on the common
+ * case where nothing changed.
+ */
+export declare function roleClaimsAreCurrent(claims: Record<string, unknown> | null | undefined, carrier: {
+    role?: string | null;
+    roles?: readonly string[] | null;
+    primaryRole?: string | null;
+}): boolean;