@mohasinac/appkit 4.53.0 → 4.53.2

package/dist/features/products/repository/products.repository.d.ts

@@ -267,16 +267,106 @@ export declare class ProductRepository extends BaseRepository<ProductDocument> {
     updateAvailableQuantity(productId: string, quantity: number): Promise<void>;
     updateBid(productId: string, bidAmount: number, bidCount: number): Promise<void>;
     findAvailable(): Promise<ProductDocument[]>;
+    /**
+     * Every member of a group, UNFILTERED — drafts, and every listing type.
+     *
+     * 🛑 This is the scope `dissolveGroup` needs and the ONLY one that may be
+     * unfiltered. A filtered dissolve leaves the excluded members carrying a
+     * `groupId` pointing at a group that no longer exists, which nothing ever
+     * clears — and that orphan is invisible until someone wonders why a product
+     * claims to be in a group with no other members.
+     */
+    findAllByGroupId(groupId: string): Promise<ProductDocument[]>;
+    /**
+     * Group members a BUYER may see: eligible types, published only.
+     *
+     * 🛑 The type filter is DERIVED from `canJoinProductGroup`, not hard-coded.
+     * It used to be a literal `["standard", "pre-order"]`, which silently dropped
+     * every `stickers` / `art` member from the query — so `ShowGroupSection` saw
+     * one member and returned null, and the picker was unreachable with nothing
+     * erroring anywhere (Root Cause #58).
+     *
+     * 🛑 The `status` filter is NEW and is a leak fix, not a tightening. There
+     * was no status filter at all, so DRAFT members were reaching the public
+     * `/api/products/group/[groupId]` payload; widening the type list without
+     * this would have widened that leak at the same time.
+     */
+    findGroupMembersForPublic(groupId: string): Promise<ProductDocument[]>;
+    /**
+     * Union the child-side query with the PARENT's own `groupChildSlugs`.
+     *
+     * Mirrors `resolveBundleMemberIds`, and exists for the same reason: Root
+     * Cause #42 documented a parent carrying `groupChildSlugs` while its children
+     * had no `groupId`, so a child-side query resolved only the parent and the
+     * group rendered as one member. The repository's six mutating methods all
+     * write both sides in one batch, so code cannot produce that state — but a
+     * seeded fixture or a direct Firestore edit still can, and the READER was
+     * never made resilient. `listBundleMembers` got this fix; this did not.
+     */
+    private withParentSideFallback;
+    /**
+     * @deprecated Ambiguous about scope — say which one you mean.
+     * Kept so no caller silently changes behaviour; it resolves to the PUBLIC
+     * scope, which is what every existing caller wanted.
+     */
     findByGroupId(groupId: string): Promise<ProductDocument[]>;
     startGroup(productId: string, slug: string): Promise<void>;
     updateGroupTitle(productId: string, groupTitle: string): Promise<void>;
     dissolveGroup(groupId: string): Promise<void>;
+    /**
+     * Link ONE child into a parent's group.
+     *
+     * 🛑 `arrayUnion`, not a spread of the in-memory `parent.groupChildSlugs`.
+     *
+     * The spread read a snapshot the CALLER was holding, so linking N children in
+     * a loop produced exactly ONE entry: every iteration computed
+     * `[...(stale ?? []), child]` from the same pre-loop document and the last
+     * write won. Nothing errored — each child got its own `groupId` correctly, so
+     * `findAllByGroupId` found them all while the parent's own
+     * `groupChildSlugs` claimed one member, which is what the group picker's
+     * fallback path and `GroupSettingsPanel` read.
+     *
+     * `arrayUnion` is also idempotent, so re-linking an existing child is a
+     * no-op instead of a duplicate id.
+     *
+     * For a known set, prefer `linkChildrenToGroup` below — one batch instead of
+     * N, which matters against Rule #6's round-trip budget when promoting a
+     * 60-part sticker sheet.
+     */
     linkChildToGroup(parent: ProductDocument, child: ProductDocument): Promise<void>;
+    /**
+     * Link SEVERAL children into a parent's group in one batch.
+     *
+     * Built for `promoteStickerSheetToListings`, which links every unique part of
+     * a sheet at once — N calls to `linkChildToGroup` would be N batch commits
+     * for work that is one logical change.
+     */
+    linkChildrenToGroup(parent: ProductDocument, children: readonly ProductDocument[]): Promise<void>;
     unlinkChildFromGroup(parent: ProductDocument, child: ProductDocument): Promise<void>;
     leaveGroup(child: ProductDocument, parent: ProductDocument | null): Promise<void>;
     addChildProduct(parent: ProductDocument, child: Omit<import("../schemas/firestore").ProductCreateInput, "groupId" | "isGroupParent" | "groupParentSlug" | "groupTitle">): Promise<ProductDocument>;
     deleteByStore(storeId: string): Promise<number>;
     delete(id: string): Promise<void>;
+    /**
+     * Every live listing OF one glossary part, across all stores.
+     *
+     * 🛑 NOT filtered by `listingType`, deliberately. Both `spares` and the
+     * 972 generated per-leaf catalogue rows (which are `standard`) carry
+     * `partGlossaryId`, and a buyer on `/parts/{slot}/{code}` wants any listing
+     * of that part — not only the ones that happen to be filed under the newer
+     * type. Narrowing to `spares` would hide most of the real inventory.
+     *
+     * 🛑 `orderBy` is `createdAt`, which EVERY document carries
+     * (`BaseRepository.create` writes it). Ordering by an optional field silently
+     * excludes every row lacking it — Root Cause #100, where `itemsSold` on zero
+     * of 95 products made a store`s whole review endpoint return nothing.
+     *
+     * Availability is filtered IN MEMORY rather than in the query: "available" is
+     * negation-shaped and no query expresses it, which is the asymmetry
+     * `baseAvailable` exists for. The window is bounded, so the cost is a few
+     * rows read and discarded.
+     */
+    findByPartGlossaryId(partGlossaryId: string, limit?: number): Promise<ProductDocument[]>;
     static readonly SIEVE_FIELDS: {
         id: {
             canFilter: boolean;
@@ -330,6 +420,14 @@ export declare class ProductRepository extends BaseRepository<ProductDocument> {
             canFilter: boolean;
             canSort: boolean;
         };
+        partGlossaryId: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        colourway: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
         isPromoted: {
             canFilter: boolean;
             canSort: boolean;
@@ -596,6 +694,7 @@ export declare class ProductRepository extends BaseRepository<ProductDocument> {
         status?: string;
         categoriesIn?: string[];
         search?: string;
+        brandName?: string;
     }): Promise<FirebaseSieveResult<ProductDocument>>;
     /**
      * How many products of each listing type exist within a scope — the numbers

package/dist/features/products/repository/products.repository.js

@@ -1,5 +1,5 @@
 import { normalizeError } from "../../../errors/normalize.js";
-import { increment, serverTimestamp } from "../../../contracts/field-ops.js";
+import { arrayUnion, increment, serverTimestamp } from "../../../contracts/field-ops.js";
 // 🛑 `../../../errors` re-exports the REAL ValidationError (errors/validation-error),
 // which is the one `mapToHttpError` instanceof-checks to produce a 400. The
 // unrelated same-named class under `_internal/shared/errors` falls through every
@@ -24,7 +24,7 @@ import { planSearchTxt, beginSearchWindow, emptySearchResult, } from "../../../u
 // One definition of "which fields feed searchTxt", shared with the seed
 // wrapper. Three copies existed and two were missing the same three fields.
 import { buildProductSearchTxt } from "../../../utils/search-txt-builders.js";
-import { PRODUCT_COLLECTION, ProductStatusValues } from "../schemas/index.js";
+import { PRODUCT_COLLECTION, ProductStatusValues, toProductImages } from "../schemas/index.js";
 // Collection NAMES only — deliberately not `categoriesRepository` or
 // `taxCodesRepository`. See deriveTaxonomy()'s header for why these are raw
 // reads: no repository in this codebase imports another feature's, because of
@@ -45,6 +45,12 @@ import { MAX_FEATURES_PER_PRODUCT } from "../schemas/product-features.js";
 // The ONE `{{placeholder}}` implementation, promoted out of the FAQ schema in
 // B3. A second regex here would be Root Cause #75's shape.
 import { interpolate } from "../../../_internal/shared/templating/placeholders.js";
+/*
+ * From their DEFINING modules, not a barrel — a repository reaching the wide
+ * entry is how the Turbopack client-bundle trap gets re-opened (Root Cause #18).
+ */
+import { ALL_LISTING_TYPES } from "../../../_internal/shared/listing-types/feature-flags.js";
+import { pluginFor } from "../../../_internal/shared/listing-types/_registry.js";
 import { PRODUCT_FIELDS } from "../../../constants/field-names.js";
 /**
  * Canonical listing-kind tokens used in `listingType`. Note: the public Sieve
@@ -73,6 +79,21 @@ const LISTING_KIND_ALIAS_MAP = {
     live: LISTING_TYPE_VALUES.LIVE,
     art: LISTING_TYPE_VALUES.ART,
     stickers: LISTING_TYPE_VALUES.STICKERS,
+    /*
+     * 🛑 Root Cause #58 lives here, and it is the single most expensive line to
+     * omit in this whole change. The alias returns `""` for an unrecognised
+     * token and `expandFilterAliases` then DROPS the empty clause — so a missing
+     * entry does not error, it deletes the `listingType` filter from the query.
+     * `art` and `stickers` were added to the union, the registry and the
+     * capability map and not to this map, and every art/sticker browse page
+     * silently returned the entire catalogue until someone reported it.
+     *
+     * `Record<ProductListingKind, string>` makes it compile-checked against THAT
+     * union — but `ProductListingKind` is itself hand-written above and is not
+     * checked against `ListingType`, which is why this is still on the unchecked
+     * list.
+     */
+    spares: LISTING_TYPE_VALUES.SPARES,
     // Legacy → canonical.
     product: LISTING_TYPE_VALUES.STANDARD,
     preorder: LISTING_TYPE_VALUES.PRE_ORDER,
@@ -232,6 +253,17 @@ export class ProductRepository extends BaseRepository {
         if (!doc.categorySlugs || doc.categorySlugs.length === 0) {
             doc.categorySlugs = doc.category ? [doc.category] : [];
         }
+        /*
+         * A6 — widen a legacy `images: string[]` document to `ProductImage[]`.
+         *
+         * 🛑 This is HALF the normalisation and must stay paired with the write
+         * half in `create`/`update` below. Read-only widening is Root Cause #101
+         * exactly: the field would be the object form on every object anyone
+         * inspects and still a bare string array in Firestore, so the next write
+         * of an untouched document would persist whichever shape the caller
+         * happened to hold.
+         */
+        doc.images = toProductImages(doc.images);
         return doc;
     }
     /**
@@ -833,6 +865,13 @@ export class ProductRepository extends BaseRepository {
             ...data,
             ...derived,
             ...stock,
+            /*
+             * A6 — only when the write NAMES `images`. An unconditional
+             * `toProductImages(data.images)` would write `[]` over a real gallery on
+             * every stock decrement and status flip, because `data` does not carry
+             * the field at all on those paths.
+             */
+            ...(data.images !== undefined ? { images: toProductImages(data.images) } : {}),
             searchTxt: buildProductSearchTxt(merged),
         });
         this.cacheSet(updated);
@@ -907,7 +946,17 @@ export class ProductRepository extends BaseRepository {
         // all. A seed row already carrying the correct chain derives to the same
         // value, so this is a no-op for every existing fixture.
         const derived = await this.deriveTaxonomy(input, true);
-        const withTaxonomy = { ...input, ...derived };
+        /*
+         * A6 — the WRITE half of the `images` normalisation (the read half is in
+         * `mapDoc`). Every create path funnels through here, so a caller handing
+         * us `string[]` — a seed row, an older client, the shipment-link route —
+         * stores the object form rather than leaving the collection mixed.
+         */
+        const withTaxonomy = {
+            ...input,
+            ...derived,
+            ...(input.images !== undefined ? { images: toProductImages(input.images) } : {}),
+        };
         const productData = {
             ...withTaxonomy,
             barcodeId,
@@ -1053,17 +1102,89 @@ export class ProductRepository extends BaseRepository {
             .get();
         return snapshot.docs.map((doc) => this.mapDoc(doc));
     }
-    async findByGroupId(groupId) {
-        // Tier GP: groups may mix standard products + pre-orders (never auctions).
+    /**
+     * Every member of a group, UNFILTERED — drafts, and every listing type.
+     *
+     * 🛑 This is the scope `dissolveGroup` needs and the ONLY one that may be
+     * unfiltered. A filtered dissolve leaves the excluded members carrying a
+     * `groupId` pointing at a group that no longer exists, which nothing ever
+     * clears — and that orphan is invisible until someone wonders why a product
+     * claims to be in a group with no other members.
+     */
+    async findAllByGroupId(groupId) {
         const snapshot = await this.db
             .collection(this.collection)
             .where("groupId", "==", groupId)
-            .where(PRODUCT_FIELDS.LISTING_TYPE, "in", [
-            LISTING_TYPE_VALUES.STANDARD,
-            LISTING_TYPE_VALUES.PRE_ORDER,
-        ])
             .get();
-        return snapshot.docs.map((doc) => this.mapDoc(doc));
+        const byQuery = snapshot.docs.map((doc) => this.mapDoc(doc));
+        return this.withParentSideFallback(groupId, byQuery);
+    }
+    /**
+     * Group members a BUYER may see: eligible types, published only.
+     *
+     * 🛑 The type filter is DERIVED from `canJoinProductGroup`, not hard-coded.
+     * It used to be a literal `["standard", "pre-order"]`, which silently dropped
+     * every `stickers` / `art` member from the query — so `ShowGroupSection` saw
+     * one member and returned null, and the picker was unreachable with nothing
+     * erroring anywhere (Root Cause #58).
+     *
+     * 🛑 The `status` filter is NEW and is a leak fix, not a tightening. There
+     * was no status filter at all, so DRAFT members were reaching the public
+     * `/api/products/group/[groupId]` payload; widening the type list without
+     * this would have widened that leak at the same time.
+     */
+    async findGroupMembersForPublic(groupId) {
+        const eligible = ALL_LISTING_TYPES.filter((t) => pluginFor(t).canJoinProductGroup);
+        const snapshot = await this.db
+            .collection(this.collection)
+            .where("groupId", "==", groupId)
+            // `in` caps at 30 values; this is 4 of 9 today and cannot approach it.
+            .where(PRODUCT_FIELDS.LISTING_TYPE, "in", eligible)
+            .where(PRODUCT_FIELDS.STATUS, "==", ProductStatusValues.PUBLISHED)
+            .get();
+        const byQuery = snapshot.docs.map((doc) => this.mapDoc(doc));
+        const withFallback = await this.withParentSideFallback(groupId, byQuery);
+        /*
+         * 🛑 The fallback results are filtered TOO. Without this the fallback
+         * becomes the hole the query just closed — a draft or an ineligible member
+         * would reach the public payload through the parent's own list.
+         */
+        const eligibleSet = new Set(eligible);
+        return withFallback.filter((p) => eligibleSet.has(String(p.listingType ?? LISTING_TYPE_VALUES.STANDARD)) &&
+            p.status === ProductStatusValues.PUBLISHED);
+    }
+    /**
+     * Union the child-side query with the PARENT's own `groupChildSlugs`.
+     *
+     * Mirrors `resolveBundleMemberIds`, and exists for the same reason: Root
+     * Cause #42 documented a parent carrying `groupChildSlugs` while its children
+     * had no `groupId`, so a child-side query resolved only the parent and the
+     * group rendered as one member. The repository's six mutating methods all
+     * write both sides in one batch, so code cannot produce that state — but a
+     * seeded fixture or a direct Firestore edit still can, and the READER was
+     * never made resilient. `listBundleMembers` got this fix; this did not.
+     */
+    async withParentSideFallback(groupId, byQuery) {
+        const seen = new Set(byQuery.map((p) => p.id));
+        /*
+         * `startGroup` sets `groupId = parent.slug`, so the group id IS the
+         * parent's slug and one lookup finds it. If that ever stops being true the
+         * fallback simply finds nothing, which is the same behaviour as today.
+         */
+        const parent = byQuery.find((p) => p.isGroupParent) ?? (await this.findById(groupId));
+        const missing = (parent?.groupChildSlugs ?? []).filter((id) => !seen.has(id));
+        if (missing.length === 0)
+            return byQuery;
+        const extra = await Promise.all(missing.map((id) => this.findById(id)));
+        return [...byQuery, ...extra.filter((p) => p !== null)];
+    }
+    /**
+     * @deprecated Ambiguous about scope — say which one you mean.
+     * Kept so no caller silently changes behaviour; it resolves to the PUBLIC
+     * scope, which is what every existing caller wanted.
+     */
+    async findByGroupId(groupId) {
+        return this.findGroupMembersForPublic(groupId);
     }
     async startGroup(productId, slug) {
         await this.getCollection().doc(productId).update({
@@ -1076,7 +1197,10 @@ export class ProductRepository extends BaseRepository {
         await this.getCollection().doc(productId).update({ groupTitle });
     }
     async dissolveGroup(groupId) {
-        const members = await this.findByGroupId(groupId);
+        // UNFILTERED on purpose — see findAllByGroupId. Dissolving must clear every
+        // member's fields, including drafts and ineligible types, or they keep a
+        // groupId pointing at nothing.
+        const members = await this.findAllByGroupId(groupId);
         const batch = this.db.batch();
         const clearFields = {
             groupId: null,
@@ -1090,15 +1214,62 @@ export class ProductRepository extends BaseRepository {
         }
         await batch.commit();
     }
+    /**
+     * Link ONE child into a parent's group.
+     *
+     * 🛑 `arrayUnion`, not a spread of the in-memory `parent.groupChildSlugs`.
+     *
+     * The spread read a snapshot the CALLER was holding, so linking N children in
+     * a loop produced exactly ONE entry: every iteration computed
+     * `[...(stale ?? []), child]` from the same pre-loop document and the last
+     * write won. Nothing errored — each child got its own `groupId` correctly, so
+     * `findAllByGroupId` found them all while the parent's own
+     * `groupChildSlugs` claimed one member, which is what the group picker's
+     * fallback path and `GroupSettingsPanel` read.
+     *
+     * `arrayUnion` is also idempotent, so re-linking an existing child is a
+     * no-op instead of a duplicate id.
+     *
+     * For a known set, prefer `linkChildrenToGroup` below — one batch instead of
+     * N, which matters against Rule #6's round-trip budget when promoting a
+     * 60-part sticker sheet.
+     */
     async linkChildToGroup(parent, child) {
+        await this.linkChildrenToGroup(parent, [child]);
+    }
+    /**
+     * Link SEVERAL children into a parent's group in one batch.
+     *
+     * Built for `promoteStickerSheetToListings`, which links every unique part of
+     * a sheet at once — N calls to `linkChildToGroup` would be N batch commits
+     * for work that is one logical change.
+     */
+    async linkChildrenToGroup(parent, children) {
+        if (children.length === 0)
+            return;
         const batch = this.db.batch();
-        batch.update(this.getCollection().doc(child.id), {
-            groupId: parent.groupId,
-            groupParentSlug: parent.slug ?? parent.id,
-            groupTitle: parent.groupTitle ?? null,
-        });
+        for (const child of children) {
+            batch.update(this.getCollection().doc(child.id), {
+                groupId: parent.groupId,
+                groupParentSlug: parent.slug ?? parent.id,
+                groupTitle: parent.groupTitle ?? null,
+            });
+        }
         batch.update(this.getCollection().doc(parent.id), {
-            groupChildSlugs: [...(parent.groupChildSlugs ?? []), child.id],
+            /*
+             * Ids, matching `unlinkChildFromGroup`'s filter, which removes by id OR
+             * slug. These are pure slugs for products (`id === slug`), so the two
+             * agree — but the field name says "slugs" and the stored values are ids,
+             * which is worth knowing before writing a reader that assumes either.
+             */
+            /*
+             * 🛑 `arrayUnion` from the CONTRACTS layer, not `firebase-admin`
+             * directly. Two sibling repositories import `FieldValue` from
+             * firebase-admin and this one deliberately does not — its own imports go
+             * through `contracts/field-ops`, which is what keeps the admin SDK out of
+             * this module's static import graph (Root Cause #24/#6).
+             */
+            groupChildSlugs: arrayUnion(...children.map((c) => c.id)),
         });
         await batch.commit();
     }
@@ -1185,6 +1356,39 @@ export class ProductRepository extends BaseRepository {
         await super.delete(id);
         await this.syncCategoryCounts(prior, null);
     }
+    /**
+     * Every live listing OF one glossary part, across all stores.
+     *
+     * 🛑 NOT filtered by `listingType`, deliberately. Both `spares` and the
+     * 972 generated per-leaf catalogue rows (which are `standard`) carry
+     * `partGlossaryId`, and a buyer on `/parts/{slot}/{code}` wants any listing
+     * of that part — not only the ones that happen to be filed under the newer
+     * type. Narrowing to `spares` would hide most of the real inventory.
+     *
+     * 🛑 `orderBy` is `createdAt`, which EVERY document carries
+     * (`BaseRepository.create` writes it). Ordering by an optional field silently
+     * excludes every row lacking it — Root Cause #100, where `itemsSold` on zero
+     * of 95 products made a store`s whole review endpoint return nothing.
+     *
+     * Availability is filtered IN MEMORY rather than in the query: "available" is
+     * negation-shaped and no query expresses it, which is the asymmetry
+     * `baseAvailable` exists for. The window is bounded, so the cost is a few
+     * rows read and discarded.
+     */
+    async findByPartGlossaryId(partGlossaryId, limit = 12) {
+        if (!partGlossaryId)
+            return [];
+        const snap = await this.getCollection()
+            .where(PRODUCT_FIELDS.PART_GLOSSARY_ID, "==", partGlossaryId)
+            .where(PRODUCT_FIELDS.STATUS, "==", PRODUCT_FIELDS.STATUS_VALUES.PUBLISHED)
+            .orderBy(PRODUCT_FIELDS.CREATED_AT, "desc")
+            // Over-fetch, because the availability filter below removes rows. Taking
+            // exactly `limit` here would return fewer than `limit` buyable listings
+            // whenever any of them were sold.
+            .limit(Math.min(60, limit * 3))
+            .get();
+        return snap.docs.map((d) => this.mapDoc(d)).slice(0, limit);
+    }
     /**
      * Shared scope construction for `list()` and `countBy*()` — both must narrow
      * by exactly the same store/status/category/search predicates or a tab's
@@ -1247,7 +1451,11 @@ export class ProductRepository extends BaseRepository {
         }
         return baseQuery;
     }
-    async list(model, opts) {
+    async list(model, 
+    // `brandName` was already honoured by `buildScopedQuery` and simply not
+    // declared here, so a brand-scoped caller had to express the brand as a
+    // Sieve clause instead — a second spelling of one filter.
+    opts) {
         /*
          * 🛑 THE EMPTY GUARD — a non-blank query that yields NO usable token must
          * return nothing, not everything.
@@ -1481,6 +1689,20 @@ ProductRepository.SIEVE_FIELDS = {
     // admin and seller product lists.
     featured: { canFilter: true, canSort: true },
     listingType: { canFilter: true, canSort: false },
+    /*
+     * 🛑 Filterable so a `partGlossaryId` filter is not SILENTLY DROPPED.
+     * `sieve.ts` sets `throwExceptions: false`, so a field absent from this map
+     * does not raise — `findField` returns undefined and the clause vanishes,
+     * which on a page scoped to one part means the ENTIRE catalogue comes back
+     * (Root Cause #62). Both of these are real `ProductDocument` fields, so
+     * neither is the orphan half of that pattern.
+     *
+     * `canSort: false` on both: they are identity, not an ordering anyone wants
+     * — and a sort option whose field is `canSort: false` is dropped just as
+     * silently (Root Cause #63).
+     */
+    partGlossaryId: { canFilter: true, canSort: false },
+    colourway: { canFilter: true, canSort: false },
     isPromoted: { canFilter: true, canSort: true },
     isOnSale: { canFilter: true, canSort: false },
     price: { canFilter: true, canSort: true },

package/dist/features/products/schemas/firestore.d.ts

@@ -2,7 +2,8 @@
  * Products Firestore Document Types & Constants
  */
 import { type GenerateProductIdInput, type GenerateAuctionIdInput, type GeneratePreOrderIdInput } from "../../../utils/id-generators";
-import type { ProductStatus, ListingType } from "../types";
+import type { ProductStatus, ListingType, ProductImage } from "../types";
+export type { ProductImage };
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
 import type { LotteryConfig } from "../../lottery/types";
 export interface ProductVideoField {
@@ -12,6 +13,31 @@ export interface ProductVideoField {
     trimStart?: number;
     trimEnd?: number;
 }
+/**
+ * Whatever a document, a request body or a seed row happens to hold, as
+ * `ProductImage[]`.
+ *
+ * 🛑 This is called on the WRITE path (`ProductRepository.create`/`update`)
+ * **and** on the read path (`mapDoc`), and both are required. Root Cause #101
+ * is exactly this shape: `mapDoc` backfilled `categorySlugs` on read while the
+ * write schema stripped it, so the field was present on every object anyone
+ * inspected and absent from the stored document — invisible to every query,
+ * and latent until a human created a listing.
+ *
+ * Accepts `string`, `ProductImage`, and a mixed array of both, because a
+ * partially-migrated collection genuinely contains all three.
+ */
+export declare function toProductImages(input: unknown): ProductImage[];
+/**
+ * Just the URLs, in order — for the many call sites that only ever needed a
+ * `string[]` (a lightbox's source list, an OG image pick, a media-abort
+ * cleanup list).
+ *
+ * This is a PROJECTION, computed on demand, not a stored mirror — so it cannot
+ * drift from `images` the way a denormalised second field would (Root Cause
+ * #42). Takes `unknown` so it also works on a legacy `string[]`.
+ */
+export declare function productImageUrls(input: unknown): string[];
 export interface ProductSpecification {
     name: string;
     value: string;
@@ -256,7 +282,14 @@ export interface ProductDocument extends BaseDocument {
     stockQuantity: number;
     availableQuantity: number;
     mainImage: string;
-    images: string[];
+    /**
+     * 🛑 `ProductImage[]`, not `string[]` (changed 2026-10-20, plan A6).
+     *
+     * Normalised by `toProductImages()` on BOTH the write path and `mapDoc`, so
+     * a legacy `string[]` document widens losslessly and a new write stores the
+     * object form. Call sites that only want URLs use `productImageUrls()`.
+     */
+    images: ProductImage[];
     video?: ProductVideoField;
     status: ProductStatus;
     storeId: string;
@@ -449,6 +482,52 @@ export interface ProductDocument extends BaseDocument {
     isPromoted?: boolean;
     isOnSale?: boolean;
     isSold?: boolean;
+    /**
+     * This listing is PRINTED OR BUILT WHEN ORDERED, so stock does not gate it.
+     *
+     * A per-LISTING flag, deliberately not implied by `listingType`. A seller can
+     * hold a finite run of pre-cut sticker sheets and also offer a
+     * print-on-demand sheet, and the two must coexist on the same type — which a
+     * type-level rule cannot express. (`showsStockQuantity` on the plugin is the
+     * type-level field and must NOT be repurposed for this.)
+     *
+     * 🛑 It bypasses the stock CHECK and never the DECREMENT. `availableQuantity`
+     * going negative on a made-to-order row IS the production queue — how many
+     * are owed — and `stock-restore.ts` requires the restore to mirror the
+     * decrement exactly, so skipping the decrement would make a cancelled order
+     * restore stock that was never taken.
+     *
+     * 🛑 Not snapshotted onto `CartLineMember`. A snapshot goes stale the moment
+     * the flag is flipped, and every check site already holds the product
+     * document — so it is derived, never copied (Root Cause #42).
+     *
+     * 🛑 CHECKED, not assumed: nothing auto-sets `isSold` when quantity reaches
+     * zero, so a made-to-order listing does NOT destroy itself on its first
+     * sale. `buildStockUpdatePayload` writes `availableQuantity` and the rule's
+     * `stockDecrementExtras` and nothing else; the only two writers of
+     * `isSold: true` in the whole tree are auction settlement and the auction
+     * buyout, both of which are selling a unique lot and are correct to do it.
+     * If a future "mark sold out automatically" feature is added, it must skip
+     * made-to-order rows or every one of them dies on its first order.
+     */
+    madeToOrder?: boolean;
+    /**
+     * The `stickerSheets` document this listing was promoted from.
+     *
+     * Set on BOTH the parent (the whole sheet) and every child (one cut), so the
+     * relationship is answerable from either end without a query — "which sheet
+     * is this sticker off" and "has this sheet already been promoted" are both
+     * questions the admin UI asks.
+     */
+    sourceStickerSheetId?: string;
+    /**
+     * Which cut of that sheet, by `SheetPart.ordinal`.
+     *
+     * 🛑 The ordinal, never an array index — `parts[]` is not guaranteed dense or
+     * ordered and a re-promote rewrites it, so an index would silently point at a
+     * different sticker. Absent on the parent, which is the whole sheet.
+     */
+    sourceStickerPartOrdinal?: number;
     /** When true, an EMI order for this product ships as soon as it's confirmed instead of waiting for every installment to be paid. Default false. */
     allowShipBeforeEmiComplete?: boolean;
     /**
@@ -514,6 +593,20 @@ export interface ProductDocument extends BaseDocument {
     groupParentSlug?: string;
     groupChildSlugs?: string[];
     groupTitle?: string;
+    groupMinMembers?: number;
+    groupMaxMembers?: number;
+    groupMaxUnitsPerMember?: number;
+    groupRequiredMemberIds?: string[];
+    /**
+     * Percentage off a self-assembled selection's subtotal, 0–100.
+     *
+     * 🛑 Applied in exactly ONE place: the repository's private
+     * `deriveLinePrice`, which runs on every `groupMembers` write and feeds
+     * `expandCartLineToOrderRows`' per-member GST proration through
+     * `allocateAcrossMembers`. A second application anywhere makes the cart total
+     * disagree with the invoice (Root Cause #75).
+     */
+    groupDiscountPercent?: number;
     /**
      * W1-45 — optional icon shown as an overlay badge on every card whose
      * product belongs to this group. Set once on the group parent; cards
@@ -683,8 +776,8 @@ export declare const ProductStatusValues: {
 export declare const PRODUCT_COLLECTION: "products";
 export declare const PRODUCT_INDEXED_FIELDS: readonly ["storeId", "status", "category", "categoryIds", "featured", "listingType", "isPromoted", "isOnSale", "isSold", "searchTxt", "createdAt", "barcodeId", "physicalLocation.zone"];
 export declare const DEFAULT_PRODUCT_DATA: Partial<ProductDocument>;
-export declare const PRODUCT_PUBLIC_FIELDS: readonly ["allowOffers", "minOfferPercent", "id", "title", "description", "category", "categoryIds", "categoryIdNames", "subcategory", "brand", "price", "originalPrice", "currency", "stockQuantity", "availableQuantity", "images", "status", "storeName", "featured", "tags", "specifications", "features", "shippingInfo", "returnPolicy", "finalSale", "isLot", "lotSize", "unitLabel", "partGlossaryId", "colourway", "mouldVariant", "assembledFrom", "views7d", "views30d", "unitLabel", "partGlossaryId", "colourway", "mouldVariant", "assembledFrom", "listingType", "auctionEndDate", "startingBid", "currentBid", "bidCount", "reservePrice", "buyNowPrice", "minBidIncrement", "autoExtendable", "auctionExtensionMinutes", "auctionShippingPaidBy", "bidsHaveStarted", "grading", "card", "classified", "digitalCode", "liveItem", "catalogProductId", "preOrderDeliveryDate", "preOrderDepositPercent", "preOrderDepositAmount", "preOrderMaxQuantity", "preOrderCurrentCount", "preOrderProductionStatus", "preOrderCancellable", "condition", "insurance", "insuranceCost", "shippingPaidBy", "isPromoted", "isOnSale", "isSold", "slug", "seoTitle", "seoDescription", "seoKeywords", "viewCount", "customFields", "customSections", "sublistingCategoryId", "groupId", "isGroupParent", "groupParentSlug", "groupChildSlugs", "groupTitle", "createdAt"];
-export declare const PRODUCT_UPDATABLE_FIELDS: readonly ["title", "description", "category", "categoryIds", "subcategory", "brand", "price", "originalPrice", "stockQuantity", "images", "status", "tags", "specifications", "features", "shippingInfo", "returnPolicy", "finalSale", "isLot", "lotSize", "pickupAddressId", "condition", "insurance", "shippingPaidBy", "autoExtendable", "auctionExtensionMinutes", "auctionShippingPaidBy", "reservePrice", "buyNowPrice", "minBidIncrement", "bidsHaveStarted", "grading", "card", "classified", "digitalCode", "liveItem", "catalogProductId", "listingType", "preOrderDeliveryDate", "preOrderDepositPercent", "preOrderDepositAmount", "preOrderMaxQuantity", "preOrderProductionStatus", "preOrderCancellable", "isOnSale", "isSold", "allowShipBeforeEmiComplete", "gstRate", "hsnCode", "authenticity", "printMeta", "seoTitle", "seoDescription", "seoKeywords", "customFields", "customSections", "sublistingCategoryId", "groupId", "isGroupParent", "groupParentSlug", "groupChildSlugs", "groupTitle", "barcodeId"];
+export declare const PRODUCT_PUBLIC_FIELDS: readonly ["allowOffers", "minOfferPercent", "id", "title", "description", "category", "categoryIds", "categoryIdNames", "subcategory", "brand", "price", "originalPrice", "currency", "stockQuantity", "availableQuantity", "images", "status", "storeName", "featured", "tags", "specifications", "features", "shippingInfo", "returnPolicy", "finalSale", "isLot", "lotSize", "unitLabel", "partGlossaryId", "colourway", "mouldVariant", "assembledFrom", "views7d", "views30d", "unitLabel", "partGlossaryId", "colourway", "mouldVariant", "assembledFrom", "listingType", "auctionEndDate", "startingBid", "currentBid", "bidCount", "reservePrice", "buyNowPrice", "minBidIncrement", "autoExtendable", "auctionExtensionMinutes", "auctionShippingPaidBy", "bidsHaveStarted", "grading", "card", "classified", "digitalCode", "liveItem", "catalogProductId", "preOrderDeliveryDate", "preOrderDepositPercent", "preOrderDepositAmount", "preOrderMaxQuantity", "preOrderCurrentCount", "preOrderProductionStatus", "preOrderCancellable", "condition", "insurance", "insuranceCost", "shippingPaidBy", "isPromoted", "isOnSale", "isSold", "madeToOrder", "sourceStickerSheetId", "sourceStickerPartOrdinal", "slug", "seoTitle", "seoDescription", "seoKeywords", "viewCount", "customFields", "customSections", "sublistingCategoryId", "groupId", "isGroupParent", "groupParentSlug", "groupChildSlugs", "groupTitle", "groupMinMembers", "groupMaxMembers", "groupMaxUnitsPerMember", "groupRequiredMemberIds", "groupDiscountPercent", "createdAt"];
+export declare const PRODUCT_UPDATABLE_FIELDS: readonly ["title", "description", "category", "categoryIds", "subcategory", "brand", "price", "originalPrice", "stockQuantity", "images", "status", "tags", "specifications", "features", "shippingInfo", "returnPolicy", "finalSale", "isLot", "lotSize", "pickupAddressId", "condition", "insurance", "shippingPaidBy", "autoExtendable", "auctionExtensionMinutes", "auctionShippingPaidBy", "reservePrice", "buyNowPrice", "minBidIncrement", "bidsHaveStarted", "grading", "card", "classified", "digitalCode", "liveItem", "catalogProductId", "listingType", "preOrderDeliveryDate", "preOrderDepositPercent", "preOrderDepositAmount", "preOrderMaxQuantity", "preOrderProductionStatus", "preOrderCancellable", "isOnSale", "isSold", "madeToOrder", "sourceStickerSheetId", "sourceStickerPartOrdinal", "allowShipBeforeEmiComplete", "gstRate", "hsnCode", "authenticity", "printMeta", "seoTitle", "seoDescription", "seoKeywords", "customFields", "customSections", "sublistingCategoryId", "groupId", "isGroupParent", "groupParentSlug", "groupChildSlugs", "groupTitle", "groupMinMembers", "groupMaxMembers", "groupMaxUnitsPerMember", "groupRequiredMemberIds", "groupDiscountPercent", "barcodeId"];
 export type ProductCreateInput = Omit<ProductDocument, "id" | "createdAt" | "updatedAt" | "availableQuantity" | "bidCount" | "currentBid" | "auctionOriginalEndDate">;
 export type ProductUpdateInput = Partial<Pick<ProductDocument, (typeof PRODUCT_UPDATABLE_FIELDS)[number]>>;
 export type ProductAdminUpdateInput = Partial<Omit<ProductDocument, "id" | "createdAt">>;