@mohasinac/appkit 4.53.0 → 4.53.2

package/dist/_internal/server/features/search/search-everything.js

@@ -1,11 +1,21 @@
 /**
  * D2 Fix 4 — CROSS-RESOURCE search.
  *
- * 🛑 `/search` is a pure REDIRECT today: it maps each of 15
- * `SearchResourceType` values to a browse route and `redirect()`s, `noindex`.
- * So there is **no cross-resource search at all** — the dropdown picks which
- * single listing page to send you to, and a buyer searching "dranzer" cannot
- * see that we have a product, an auction, a blog post and an FAQ about it.
+ * 🛑 CORRECTED 2026-10-19 — this header asserted the opposite of the truth.
+ *
+ * It read: "`/search` is a pure REDIRECT today … there is no cross-resource
+ * search at all." That described the state this module was WRITTEN to fix,
+ * and it stayed on the file after the fix shipped — so the one document
+ * explaining the feature told every later reader the feature did not exist.
+ *
+ * What is true now: `/search` is a real grouped results page, the header
+ * reaches it, and this module is TIER 2 — the authenticated, server-side
+ * half. The public half is a prebuilt artifact searched in the browser at
+ * zero Firestore reads, and this one is what serves a viewer's OWN records
+ * (`scoped-sources.ts`) and what the kill switch falls back to when the
+ * artifact is unavailable.
+ *
+ * That fallback is the reason this file is not deleted.
  *
  * ── WHY THIS IS AFFORDABLE ─────────────────────────────────────────────────
  *
@@ -30,11 +40,15 @@
  *
  * ── 🛑 WHAT IT DOES NOT REUSE, AND WHY ─────────────────────────────────────
  *
- * NOT `SearchRepository`. That class builds `title_=${q}` — a case-sensitive
+ * NOT `SearchRepository`. That class built `title_=${q}` — a case-sensitive
  * STARTS-WITH on `title` alone — so "dranzer" would not find "Beyblade
- * Original Dranzer S" and "flat" would find nothing at all. It is reachable
- * only through `/api/search`, whose own hook (`useSearch`) has zero consumers
- * outside barrel re-exports. Recorded rather than deleted here; see F1.
+ * Original Dranzer S" and "flat" would find nothing at all. It was reachable
+ * only through `/api/search`, whose own hook (`useSearch`) had zero consumers
+ * outside barrel re-exports. The whole dead subsystem — `SearchRepository`,
+ * `/api/search`, `useSearch`, `SearchView`/`SearchFiltersRow`/
+ * `SearchResultsSection`, the legacy `search-actions.ts`/`data.ts`/
+ * `actions.ts` chain — was deleted in the Wave 10 cleanup, kept only as this
+ * historical note on why `searchEverything` never called it.
  */
 import { planSearchTxt } from "../../../../utils/search-txt-query.js";
 import { parseSearchTxtQuery, SEARCH_TXT_FIELD } from "../../../../utils/search-txt.js";
@@ -44,6 +58,19 @@ import { normalizeError } from "../../../../errors/normalize.js";
 const PER_GROUP = 6;
 /** The bounded window each push-down reads before the in-memory refine. */
 const SCAN = 60;
+/**
+ * 🛑 The ceiling on what ONE viewer's scoped search may read.
+ *
+ * Σ `scanLimit` across the widest role, checked by
+ * `audit-scoped-search-ownership` R4 — which PRINTS THE ARITHMETIC on
+ * failure, because "the budget is exceeded" is useless without knowing by
+ * which source and how much.
+ *
+ * 400 against Rule #6's ~3-round-trip guidance is defensible because the
+ * sources run in ONE `Promise.all`: it is one round trip of fan-out, not
+ * twelve sequential ones. The number that matters is documents read.
+ */
+export const SCOPED_SCAN_BUDGET = 400;
 /**
  * Run every source in parallel and group the results.
  *
@@ -75,20 +102,41 @@ export async function searchEverything(db, q, sources) {
             moreHref: src.moreHref(q),
         };
         try {
+            const scan = src.scanLimit ?? SCAN;
+            const boundedMemory = src.mode === "bounded-memory";
             let ref = db.collection(src.collection);
             for (const [field, value] of src.where ?? [])
                 ref = ref.where(field, "==", value);
-            const snap = await ref
-                .where(SEARCH_TXT_FIELD, "array-contains", plan.head)
-                .select(...src.select, SEARCH_TXT_FIELD)
-                .limit(SCAN)
-                .get();
+            /*
+             * 🛑 The two modes differ in ONE clause and in nothing else.
+             *
+             * `bounded-memory` omits the `array-contains` push-down and does not
+             * project `searchTxt` — because the collections that use it do not
+             * have one, deliberately (see `mode`). Everything downstream —
+             * `toHit`, the PER_GROUP slice, the `truncated` floor — is shared, so
+             * the two paths cannot drift in how they REPORT, only in how they
+             * find.
+             */
+            const snap = boundedMemory
+                ? await (src.orderBy
+                    ? ref.orderBy(src.orderBy[0], src.orderBy[1])
+                    : ref)
+                    .select(...src.select)
+                    .limit(scan)
+                    .get()
+                : await ref
+                    .where(SEARCH_TXT_FIELD, "array-contains", plan.head)
+                    .select(...src.select, SEARCH_TXT_FIELD)
+                    .limit(scan)
+                    .get();
             // AND-refine the remaining terms in memory — one push-down per query is
             // all Firestore gives, so the rest is a filter over a bounded window.
-            const matched = snap.docs.filter((d) => {
-                const txt = d.data()[SEARCH_TXT_FIELD] ?? [];
-                return plan.rest.every((t) => txt.includes(t));
-            });
+            const matched = boundedMemory
+                ? snap.docs.filter((d) => src.matches?.(d.data(), terms) ?? false)
+                : snap.docs.filter((d) => {
+                    const txt = d.data()[SEARCH_TXT_FIELD] ?? [];
+                    return plan.rest.every((t) => txt.includes(t));
+                });
             const hits = matched
                 .map((d) => src.toHit(d.id, d.data()))
                 .filter((h) => h !== null);
@@ -96,8 +144,10 @@ export async function searchEverything(db, q, sources) {
                 ...base,
                 hits: hits.slice(0, PER_GROUP),
                 // Saturated window OR more matches than we show — either way the
-                // count on screen is a floor.
-                truncated: snap.docs.length >= SCAN || hits.length > PER_GROUP,
+                // count on screen is a floor. Compared against THIS source's own
+                // limit, not the module default: a scoped source scanning 20 that
+                // returned 20 is saturated even though 20 < SCAN.
+                truncated: snap.docs.length >= scan || hits.length > PER_GROUP,
             };
         }
         catch (err) {

package/dist/_internal/server/features/seo/sitemap.js

@@ -141,6 +141,12 @@ function staticPages(baseUrl) {
         page(String(ROUTES.PUBLIC.DIGITAL_CODES), "daily", 0.6),
         page(String(ROUTES.PUBLIC.LIVE), "hourly", 0.7),
         page(String(ROUTES.PUBLIC.ART), "weekly", 0.6),
+        /*
+         * `daily`, matching the other one-of-a-kind types rather than `/art`'s
+         * weekly: most spares are quantity 1, so the page turns over as fast as
+         * classifieds do.
+         */
+        page(String(ROUTES.PUBLIC.SPARES), "daily", 0.6),
         page(String(ROUTES.PUBLIC.FEES), "monthly", 0.4),
         page(String(ROUTES.PUBLIC.HOW_AUCTIONS_WORK), "monthly", 0.4),
         page(String(ROUTES.PUBLIC.HOW_PRE_ORDERS_WORK), "monthly", 0.4),

package/dist/_internal/server/features/shared/listing-adapters.js

@@ -1,3 +1,4 @@
+import { productImageUrls } from "../../../../features/products/schemas/firestore.js";
 /** Maps the shared fields from a raw Firestore ProductDocument. */
 export function mapBaseListingFields(doc) {
     return {
@@ -10,8 +11,9 @@ export function mapBaseListingFields(doc) {
         // bypassing <GatedPrice> entirely — and it had zero readers, so it was
         // pure exposure. Clients format from `price` through the gate.
         currency: doc.currency ?? "INR",
-        mainImage: doc.mainImage || doc.images?.[0] || null,
-        images: doc.images ?? [],
+        mainImage: doc.mainImage || doc.images?.[0]?.url || null,
+        // A6: the client listing shape is still `string[]`; project, never mirror.
+        images: productImageUrls(doc.images),
         storeId: doc.storeId,
         storeName: doc.storeName ?? null,
         category: doc.categorySlugs?.[0] ?? doc.category ?? "",

package/dist/_internal/server/features/sticker-trace/adapters.d.ts

@@ -15,6 +15,17 @@ export interface ClientSheetPart {
     areaMm2: number | null;
     /** Whether a full-resolution render exists, NOT where it is. */
     hasAsset: boolean;
+    /**
+     * The PUBLIC `/media/{shortId}` slug, when the part has been promoted.
+     *
+     * 🛑 Public on purpose and NOT a path. A `mediaShortId` is already a public
+     * URL by construction — a `mediaAssets` row IS what mints `/media/{id}`, and
+     * `/api/media/[...slug]` serves it to anyone, watermarked. So the thing it
+     * names is public whether or not this field is projected, and the admin
+     * review UI genuinely needs it to show the marketplace copy beside the clean
+     * one. `assetPath` stays private: that is the unwatermarked original.
+     */
+    mediaShortId?: string;
     duplicateOf?: number;
 }
 export interface ClientStickerSheet {

package/dist/_internal/server/features/sticker-trace/adapters.js

@@ -105,6 +105,7 @@ function toClientPart(part) {
         bboxMm: part.bboxMm,
         areaMm2: part.areaMm2,
         hasAsset: Boolean(part.assetPath),
+        ...(part.mediaShortId !== undefined ? { mediaShortId: part.mediaShortId } : {}),
         ...(part.duplicateOf !== undefined ? { duplicateOf: part.duplicateOf } : {}),
     };
 }

package/dist/_internal/server/features/sticker-trace/promote-to-listings.d.ts

@@ -0,0 +1,26 @@
+export interface PromoteToListingsInput {
+    sheetId: string;
+    /** Owning store. The admin picks it; there is no sensible default. */
+    storeId: string;
+    /**
+     * ONE price for every part, in rupees.
+     *
+     * 🛑 Deliberately flat rather than per-part or area-derived. A cut sticker
+     * costs about the same to print whatever its size, so a size-scaled price
+     * would be a fabricated precision — and a per-part form for a 60-part sheet
+     * is 60 inputs nobody fills in honestly. Each child is an ordinary product
+     * afterwards and repriceable in the normal editor.
+     */
+    partPrice: number;
+    /** The whole sheet's price, in rupees. */
+    sheetPrice: number;
+    /** Auth UID, for the `mediaAssets` row's `uploadedBy`. */
+    actorUid: string;
+}
+export interface PromoteToListingsResult {
+    parentId: string;
+    childIds: string[];
+    /** Parts skipped as confirmed duplicates of another part. */
+    skippedDuplicates: number;
+}
+export declare function promoteStickerSheetToListings(input: PromoteToListingsInput): Promise<PromoteToListingsResult>;

package/dist/_internal/server/features/sticker-trace/promote-to-listings.js

@@ -0,0 +1,264 @@
+/*
+ * WHY: The tracer ends at extracted geometry and a promoted run's full-size
+ *      part PNGs. This is what makes that worth doing — the whole sheet becomes
+ *      one listing, each unique cut becomes its own, and they are grouped so a
+ *      buyer takes any mix ("the sheet, no; six of B; one of D").
+ * WHAT: `promoteStickerSheetToListings` — sheet → one parent product + N child
+ *       products in one product group.
+ *
+ * 🛑 DISTINCT FROM `promoteRun`, and the names are close enough to matter.
+ *   · `POST .../runs/{runId}/promote`  → `promoteRun`: run → SHEET. Renders
+ *     full-res parts and exports, sets `activeRunId`. Stays inside the tracer.
+ *   · `POST .../promote-to-listings`   → this: SHEET → MARKETPLACE. Creates
+ *     products. Runs once per sheet, after the above.
+ * Calling this without the first is refused, because `SheetPart.assetPath` is
+ * only written by the `mode: "full"` shard path.
+ *
+ * 🛑 ZERO BYTES ARE COPIED for the watermarked display image. A `mediaAssets`
+ * row pointing at the EXISTING private part PNG is enough: the row is what
+ * mints `/media/{shortId}`, and the proxy watermarks on read because the row is
+ * written with `watermarkedAt` absent. Clean original for the cut file,
+ * watermarked copy for the marketplace, one object. Object count is metered
+ * separately from bytes, which is the whole reason the thumb atlas exists.
+ *
+ * EXPORTS: PromoteToListingsInput, PromoteToListingsResult,
+ *          promoteStickerSheetToListings
+ *
+ * @tag domain:sticker-trace,products
+ * @tag layer:server
+ * @tag pattern:none
+ * @tag access:server
+ * @tag consumers:api/admin/sticker-sheets
+ * @tag sideEffects:firestore
+ */
+import { ValidationError } from "../../../../errors/validation-error.js";
+import { serverLogger } from "../../../../monitoring/server-logger.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+import { productRepository } from "../../../../repositories/index.js";
+import { mediaAssetsRepository } from "../../../../features/media/repository/media-assets.repository.js";
+import { stickerSheetsRepository } from "../../../../features/sticker-trace/repository/sticker-sheets.repository.js";
+/** A part that becomes its own listing: unique, and actually rendered. */
+function isListableUniquePart(part) {
+    /*
+     * `duplicateOf` is proposed by perceptual hash and CONFIRMED BY A HUMAN, so
+     * trusting it is safe by design — that confirmation step exists precisely so
+     * this decision can be mechanical. Two stickers that merely look alike at
+     * thumbnail size are common on these sheets.
+     */
+    return part.duplicateOf === undefined;
+}
+/**
+ * Refuse loudly, before writing anything, if the sheet is not ready.
+ *
+ * 🛑 A half-promoted sheet is the "wrong data, no error" failure this whole
+ * plan exists to avoid: some parts listed, some silently missing, and nothing
+ * anywhere saying so. Every precondition is therefore checked UP FRONT and the
+ * whole promotion refused — not checked per part inside the loop, which would
+ * leave the first N written.
+ */
+function assertPromotable(sheet) {
+    if (!sheet.activeRunId) {
+        throw new ValidationError(`"${sheet.title}" has no accepted run yet. Accept a run first, then promote it to listings.`);
+    }
+    const parts = sheet.parts ?? [];
+    if (parts.length === 0) {
+        throw new ValidationError(`"${sheet.title}" has no parts. Trace it and accept a run first.`);
+    }
+    const unique = parts.filter(isListableUniquePart);
+    if (unique.length === 0) {
+        throw new ValidationError(`Every part on "${sheet.title}" is marked a duplicate of another, so there is nothing to list.`);
+    }
+    /*
+     * `assetPath` absent means the accepted run was never PROMOTED — the
+     * full-resolution PNGs do not exist. Naming the parts rather than saying
+     * "not ready": the admin's next action is different depending on whether it
+     * is all of them (promote the run) or a few (the shard that rendered those
+     * failed, so retry).
+     */
+    const unrendered = unique.filter((p) => !p.assetPath);
+    if (unrendered.length > 0) {
+        throw new ValidationError(`${unrendered.length} of ${unique.length} parts on "${sheet.title}" have no full-resolution image yet` +
+            ` (${unrendered.slice(0, 5).map((p) => `#${p.ordinal}`).join(", ")}${unrendered.length > 5 ? ", …" : ""}).` +
+            ` Accept & render the run before promoting it to listings.`);
+    }
+    return unique;
+}
+/**
+ * Register the public, WATERMARKED display copy of one part.
+ *
+ * Reuses an existing row when the part already has one, so re-promoting a sheet
+ * does not mint a second slug for the same object and orphan the first.
+ */
+async function ensurePartMediaSlug(sheet, part, actorUid) {
+    if (part.mediaShortId)
+        return part.mediaShortId;
+    if (!part.assetPath)
+        return undefined;
+    try {
+        const asset = await mediaAssetsRepository.createAsset(
+        /*
+         * A content-derived slug, matching every other media slug in the app.
+         * `createAsset` appends a random suffix on collision, so two sheets with
+         * the same title cannot overwrite each other's parts.
+         */
+        `sticker-part-${sheet.id}-${String(part.ordinal).padStart(3, "0")}`, {
+            /*
+             * 🛑 The SAME path as the clean original. This is the no-byte-copy
+             * mechanism, and it is only safe because of the two fields below.
+             */
+            storagePath: part.assetPath,
+            uploadedBy: actorUid,
+            contentType: "image/png",
+            /*
+             * Not measured. The row's `size` is used by the media usage meter, not
+             * for serving, and reading the object's metadata here would cost a
+             * Storage round trip per part — 60 on a full sheet — for a number the
+             * sticker feature already reports from `measureSheetBytes`.
+             */
+            size: 0,
+            isPublic: true,
+            status: "finalized",
+            contextType: "sticker-part",
+            /*
+             * 🛑 `watermarkedAt` is DELIBERATELY ABSENT, and it is the whole design.
+             * The proxy skips its sharp composite only when that field is set — so
+             * leaving it unset means `/media/{shortId}` watermarks this object on
+             * every read, while `assetPath` behind a signed URL stays clean. Set it
+             * here and the marketplace would serve the unwatermarked printable
+             * original, which is the one outcome this must never produce.
+             */
+        });
+        return asset.id;
+    }
+    catch (err) {
+        const e = normalizeError(err);
+        /*
+         * Non-fatal. A part with no public slug still lists — it falls back to no
+         * image rather than blocking the whole promotion — and the admin can
+         * re-promote to fill it in. Failing the sheet over one media row would be
+         * the worse trade.
+         */
+        serverLogger.warn("sticker-promote: media row failed for part", {
+            sheetId: sheet.id,
+            ordinal: part.ordinal,
+            error: e.message,
+        });
+        return undefined;
+    }
+}
+export async function promoteStickerSheetToListings(input) {
+    const sheet = await stickerSheetsRepository.findByIdOrFail(input.sheetId);
+    const unique = assertPromotable(sheet);
+    const allParts = sheet.parts ?? [];
+    /*
+     * Media rows first, before any product write.
+     *
+     * The images are what a listing is FOR, so resolving them up front means a
+     * product is never created pointing at nothing. Sequential rather than
+     * `Promise.all`: `createAsset` does a read-then-write collision check, and 60
+     * of those in parallel is 120 concurrent operations against Rule #6's budget
+     * for an admin action that is not latency-sensitive.
+     */
+    const slugByOrdinal = new Map();
+    for (const part of unique) {
+        const slug = await ensurePartMediaSlug(sheet, part, input.actorUid);
+        if (slug)
+            slugByOrdinal.set(part.ordinal, slug);
+    }
+    const partImage = (part) => {
+        const slug = slugByOrdinal.get(part.ordinal);
+        return slug ? `/media/${slug}` : "";
+    };
+    /*
+     * The parent: the whole sheet.
+     *
+     * 🛑 `madeToOrder: true`. A sheet that has been cut into parts has no stock
+     * of its own — it is printed when ordered — so without the flag the parent is
+     * unbuyable at quantity 0 and vanishes from the default availability scope,
+     * taking the group's entry point with it.
+     */
+    const parent = (await productRepository.create({
+        title: sheet.title,
+        description: `The complete ${sheet.title} sheet. Individual stickers from this sheet are listed separately — ` +
+            `pick any mix from the group below.`,
+        categorySlugs: [],
+        price: input.sheetPrice,
+        currency: "INR",
+        stockQuantity: 0,
+        madeToOrder: true,
+        mainImage: unique[0] ? partImage(unique[0]) : "",
+        images: unique.slice(0, 4).map(partImage).filter(Boolean),
+        status: "draft",
+        storeId: input.storeId,
+        featured: false,
+        tags: ["stickers"],
+        condition: "new",
+        listingType: "stickers",
+        groupTitle: sheet.title,
+        sourceStickerSheetId: sheet.id,
+    }));
+    /*
+     * `startGroup` sets `groupId = slug`, so the group id IS the parent's slug —
+     * which is why the parent must exist before any child can name it.
+     */
+    const parentSlug = parent.slug ?? parent.id;
+    await productRepository.startGroup(parent.id, parentSlug);
+    const children = [];
+    for (const part of unique) {
+        const child = (await productRepository.create({
+            title: `${sheet.title} — ${part.name}`,
+            description: `A single kiss-cut sticker from the ${sheet.title} sheet.`,
+            categorySlugs: [],
+            price: input.partPrice,
+            currency: "INR",
+            stockQuantity: 0,
+            // Same reasoning as the parent: a cut sticker is printed on order.
+            madeToOrder: true,
+            mainImage: partImage(part),
+            images: [partImage(part)].filter(Boolean),
+            status: "draft",
+            storeId: input.storeId,
+            featured: false,
+            tags: ["stickers"],
+            condition: "new",
+            listingType: "stickers",
+            sourceStickerSheetId: sheet.id,
+            sourceStickerPartOrdinal: part.ordinal,
+        }));
+        children.push(child);
+    }
+    /*
+     * 🛑 ONE batch link, via `linkChildrenToGroup`. Calling `linkChildToGroup` in
+     * a loop was the bug this phase had to fix first: it spread the CALLER's
+     * in-memory `parent.groupChildSlugs`, so N children produced exactly one
+     * entry — every iteration computing `[...stale, child]` from the same
+     * pre-loop snapshot, last write winning. Each child still got its own
+     * `groupId`, so nothing errored and `findAllByGroupId` found them all while
+     * the parent claimed one member.
+     */
+    await productRepository.linkChildrenToGroup({ ...parent, groupId: parentSlug }, children);
+    /*
+     * Write the slugs back onto the sheet so a re-promote reuses them.
+     *
+     * 🛑 Mapped over ALL parts, keyed on `ordinal`, never on array index — and
+     * `assertPromotable` filtered to unique parts, so a plain `.map()` over
+     * `unique` here would DROP every duplicate part from the sheet. The duplicate
+     * rows carry `duplicateOf` and real geometry and must survive.
+     */
+    const updatedParts = allParts.map((p) => {
+        const slug = slugByOrdinal.get(p.ordinal);
+        return slug ? { ...p, mediaShortId: slug } : p;
+    });
+    await stickerSheetsRepository.update(sheet.id, { parts: updatedParts });
+    serverLogger.info("sticker-promote: sheet promoted to listings", {
+        sheetId: sheet.id,
+        parentId: parent.id,
+        children: children.length,
+        skippedDuplicates: allParts.length - unique.length,
+    });
+    return {
+        parentId: parent.id,
+        childIds: children.map((c) => c.id),
+        skippedDuplicates: allParts.length - unique.length,
+    };
+}

package/dist/_internal/server/features/sticker-trace/sheet-actions.d.ts

@@ -88,7 +88,7 @@ export declare function attachStickerSheetScan(input: AttachScanInput): Promise<
  * property `PRIVATE_STICKER_SHEET_FIELDS` declares and
  * audit-public-projection-parity enforces.
  */
-export declare const STICKER_ASSET_KINDS: readonly ["scan", "preview", "overlay", "geometry", "cutSvg", "thumbAtlas"];
+export declare const STICKER_ASSET_KINDS: readonly ["scan", "preview", "overlay", "geometry", "cutSvg", "thumbAtlas", "part"];
 export type StickerAssetKind = (typeof STICKER_ASSET_KINDS)[number];
 /**
  * Mint a short-lived read URL for one asset of one sheet or run.
@@ -105,6 +105,8 @@ export declare function resolveStickerAssetUrl(input: {
     sheetId: string;
     kind: StickerAssetKind;
     runId?: string;
+    /** Required for `kind: "part"`. Matched against `SheetPart.ordinal`. */
+    ordinal?: number;
 }): Promise<{
     url: string;
     expiresAt: Date;

package/dist/_internal/server/features/sticker-trace/sheet-actions.js

@@ -176,6 +176,15 @@ export const STICKER_ASSET_KINDS = [
     "geometry",
     "cutSvg",
     "thumbAtlas",
+    /*
+     * One promoted part's full-resolution PNG, by `ordinal`.
+     *
+     * 🛑 Absent until the producing run is PROMOTED — `SheetPart.assetPath` is
+     * only written by the `mode: "full"` shard path. Resolving to `null` before
+     * then is correct and must not read as an error: it is the normal state of
+     * every traced-but-unpromoted sheet.
+     */
+    "part",
 ];
 /**
  * Mint a short-lived read URL for one asset of one sheet or run.
@@ -193,6 +202,29 @@ export async function resolveStickerAssetUrl(input) {
     if (input.kind === "scan") {
         return sheet.sourceScan?.assetPath ? signedReadUrl(sheet.sourceScan.assetPath) : null;
     }
+    if (input.kind === "part") {
+        if (typeof input.ordinal !== "number")
+            return null;
+        /*
+         * 🛑 Matched on `ordinal`, NEVER on array index — the same rule
+         * `updatePart` already states. `parts[]` is not guaranteed to be dense or
+         * ordered: a part can be removed, and a re-promote rewrites the array. An
+         * index lookup would silently serve a DIFFERENT sticker's PNG, which is
+         * indistinguishable from a correct response.
+         */
+        const part = (sheet.parts ?? []).find((pt) => pt.ordinal === input.ordinal);
+        if (!part?.assetPath)
+            return null;
+        /*
+         * Still a signed-URL mint, like every other kind here —
+         * `audit-sticker-trace-egress` forbids a route under this feature
+         * returning bytes, and this is the unwatermarked printable original, which
+         * is the one thing that must not be served through a public path.
+         */
+        return signedReadUrl(part.assetPath, {
+            downloadAs: `part-${String(input.ordinal).padStart(3, "0")}.png`,
+        });
+    }
     let path;
     if (input.runId) {
         const run = await stickerTraceRunsRepository.findByIdOrFail(input.runId);

package/dist/_internal/server/features/sticker-trace/storage.d.ts

@@ -1,5 +1,24 @@
 import type { CutPath, Rect } from "../../../shared/features/sticker-trace/types";
-/** Nothing under here is reachable without a signed URL minted by this module. */
+/**
+ * Everything this feature writes lives under here.
+ *
+ * 🛑 The one-line claim this used to carry — "nothing under here is reachable
+ * without a signed URL minted by this module" — was FALSE, in the same way the
+ * identical claim on `DIGITAL_CONTENT_PREFIX` was: `/media/[...slug]`'s
+ * raw-path fallback resolved any multi-segment slug as a literal storage path,
+ * so `/media/private/sticker-sheets/...` served these objects, watermarked, to
+ * anyone. Unlike digital-content's `randomUUID()` names, a part is written as
+ * `part-003.png` — guessable on the first try.
+ *
+ * The proxy now refuses a raw `private/` path outright. What is true is
+ * narrower than the old sentence and worth stating precisely: **no public URL
+ * exists for one of these objects unless something deliberately mints a
+ * `mediaAssets` row for it.** A row is what creates a `/media/{shortId}` slug,
+ * and a resolved row is intentionally still allowed through the proxy — that is
+ * how a promoted part gets a watermarked marketplace copy with no byte
+ * duplicated. The unwatermarked printable original has no row and is reachable
+ * only by a signed URL from this module.
+ */
 export declare const SCAN_ROOT = "private/sticker-sheets";
 export declare function runPrefix(sheetId: string, runId: string): string;
 export interface SignedUpload {

package/dist/_internal/server/features/sticker-trace/storage.js

@@ -45,7 +45,26 @@
 import { normalizeError } from "../../../../errors/normalize.js";
 import { serverLogger } from "../../../../monitoring/index.js";
 import { getAdminStorage } from "../../../../providers/db-firebase/index.js";
-/** Nothing under here is reachable without a signed URL minted by this module. */
+/**
+ * Everything this feature writes lives under here.
+ *
+ * 🛑 The one-line claim this used to carry — "nothing under here is reachable
+ * without a signed URL minted by this module" — was FALSE, in the same way the
+ * identical claim on `DIGITAL_CONTENT_PREFIX` was: `/media/[...slug]`'s
+ * raw-path fallback resolved any multi-segment slug as a literal storage path,
+ * so `/media/private/sticker-sheets/...` served these objects, watermarked, to
+ * anyone. Unlike digital-content's `randomUUID()` names, a part is written as
+ * `part-003.png` — guessable on the first try.
+ *
+ * The proxy now refuses a raw `private/` path outright. What is true is
+ * narrower than the old sentence and worth stating precisely: **no public URL
+ * exists for one of these objects unless something deliberately mints a
+ * `mediaAssets` row for it.** A row is what creates a `/media/{shortId}` slug,
+ * and a resolved row is intentionally still allowed through the proxy — that is
+ * how a promoted part gets a watermarked marketplace copy with no byte
+ * duplicated. The unwatermarked printable original has no row and is reachable
+ * only by a signed URL from this module.
+ */
 export const SCAN_ROOT = "private/sticker-sheets";
 /** How long a read URL lives. Long enough to fetch, short enough to be useless if leaked. */
 const READ_TTL_MS = 5 * 60 * 1000;

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

@@ -27,7 +27,7 @@ import type { StoreDetail, StoreListItem } from "../../../../features/stores/typ
  */
 export declare const PUBLIC_STORE_FIELDS: readonly ["id", "storeSlug", "ownerId", "storeName", "storeDescription", "storeCategory", "storeLogoURL", "storeBannerURL", "status", "isPublic", "stats", "bio", "location", "website", "socialLinks", "returnPolicy", "shippingPolicy", "isVacationMode", "vacationMessage", "supportsShippingProtection", "supportsSaleProtection", "createdAt"];
 /** Everything else, with the reason it stays server-side. */
-export declare const PRIVATE_STORE_FIELDS: readonly ["searchTxt", "updatedAt", "whatsappConfig", "adminNotes", "statusHistory", "statusHistoryTruncated", "isVerified", "suspensionReason", "capabilities", "customCommissionRate", "googleReviews", "shippingConfig", "emiEnabled", "pricesIncludeGst", "shippingPricing", "returnsDirectToSeller", "isFeatured", "vacationReturnDate", "isTestData", "testDataExpiresAt"];
+export declare const PRIVATE_STORE_FIELDS: readonly ["searchTxt", "updatedAt", "whatsappConfig", "adminNotes", "statusHistory", "statusHistoryTruncated", "isVerified", "suspensionReason", "capabilities", "customCommissionRate", "googleReviews", "shippingConfig", "emiEnabled", "pricesIncludeGst", "shippingPricing", "returnsDirectToSeller", "isFeatured", "vacationReturnDate", "isTestData", "testDataExpiresAt", "gstin", "legalName", "registeredAddress"];
 /**
  * Accepted input: a `StoreDocument` (the common case) or a loosely-typed
  * Firestore row. The legacy top-level counters below predate `stats` and are

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

@@ -91,6 +91,22 @@ export const PRIVATE_STORE_FIELDS = [
     "vacationReturnDate", // not rendered by StoreAboutView; add to PUBLIC when a reader exists
     "isTestData", // tester-sandbox tagging; filtered by filterTestDataForViewer
     "testDataExpiresAt", // ditto
+    /*
+     * Tax identity (2026-10-19). Read today by exactly two server-side
+     * consumers: `resolveSupplierIdentity` (checkout, to decide whose
+     * registration an order invoices under) and the seller's own authenticated
+     * payout-settings form. Neither is a public store-profile reader.
+     *
+     * A GSTIN is not secret in the way a bank account number is — it is
+     * legally published on an invoice — but "may be disclosed" and "has a
+     * reader that needs it published on /stores/{slug}" are different
+     * questions, and only the first is true today. Move to PUBLIC_STORE_FIELDS
+     * together, with the literal in `toStoreListItem()`, once a storefront
+     * surface actually needs to show a seller's registration.
+     */
+    "gstin",
+    "legalName",
+    "registeredAddress",
 ];
 /** `createdAt` is `Date` on the document and `string` on the client types. */
 function toIsoString(value) {

package/dist/_internal/server/features/stores/index.d.ts

@@ -3,3 +3,4 @@ export { STORES_PAGE_SIZE, STORES_PRODUCTS_PAGE_SIZE, STORES_SITEMAP_LIMIT, STOR
 export { renderStoreOgImage, renderStoreOg, type StoreOgData } from "./og";
 export { resolveStoreFields, resolveStoreFieldsMany, type ProductStoreFields, } from "./denormalize";
 export { toStoreDetail, toStoreListItem, PUBLIC_STORE_FIELDS, PRIVATE_STORE_FIELDS, type ToStoreDetailOptions, type ToStoreListItemOptions, type StoreProjectionSource, } from "./adapters";
+export { resolveStoreTabs, getDefaultStoreTabPath, type ResolvedStoreTabs, type StoreTabLink, } from "./tabs";

package/dist/_internal/server/features/stores/index.js

@@ -3,3 +3,4 @@ export { STORES_PAGE_SIZE, STORES_PRODUCTS_PAGE_SIZE, STORES_SITEMAP_LIMIT, STOR
 export { renderStoreOgImage, renderStoreOg } from "./og.js";
 export { resolveStoreFields, resolveStoreFieldsMany, } from "./denormalize.js";
 export { toStoreDetail, toStoreListItem, PUBLIC_STORE_FIELDS, PRIVATE_STORE_FIELDS, } from "./adapters.js";
+export { resolveStoreTabs, getDefaultStoreTabPath, } from "./tabs.js";