@mohasinac/appkit 4.71.0 → 4.72.0

package/dist/_internal/shared/features/payouts/destination.js

@@ -0,0 +1,221 @@
+/*
+ * WHY: A seller's payout DESTINATION was self-asserted. `updatePayoutSettings`
+ *      set `isConfigured: true` unconditionally on both arms — measured
+ *      2026-10-31 at `features/seller/actions/seller-actions.ts:404,414` — so a
+ *      store could be "payout configured" with an IFSC that is not an IFSC and
+ *      a VPA that is not a VPA. Nothing anywhere said otherwise until a payout
+ *      failed, which is the one moment it is most expensive to find out.
+ *
+ *      It mattered less while payouts were a manual bookkeeping record (an
+ *      admin read the details and transferred out of band, and a human notices
+ *      a malformed IFSC). It stops being tolerable under SPLIT SETTLEMENT: the
+ *      destination is handed to a payment aggregator at vendor-registration
+ *      time, and a gateway that refuses the vendor leaves the store
+ *      un-onboardable — i.e. unable to be paid at all — with the refusal
+ *      arriving asynchronously, long after the seller saw a success toast.
+ *
+ * WHAT: The ONE definition of "is this payout destination well-formed", plus
+ *       the verification lifecycle a gateway's own response drives.
+ *
+ * ## 🛑 FORMAT-VALID IS NOT BANK-VERIFIED, and the two must stay distinguishable
+ *
+ * `isConfigured` can only ever mean "the seller filled this in and it is the
+ * right SHAPE". Whether the account exists, is live, and belongs to the person
+ * named on it is a question only a bank (or a penny-drop, or an aggregator's
+ * own account verification) can answer. Collapsing the two into one boolean is
+ * what made `isConfigured: true` read as a guarantee it never was.
+ *
+ * So there are two fields with two owners:
+ *   · `isConfigured`       — THIS module, from the format rules below.
+ *   · `verificationStatus` — the GATEWAY, from its `createVendor` response.
+ *
+ * There is deliberately NO penny-drop here. We do not hold a banking licence
+ * and have no account-validation API; inventing a local "verified" state would
+ * be exactly the self-assertion this file exists to remove, one layer up.
+ *
+ * ## 🛑 Editing the destination RESETS the verification
+ *
+ * `resetVerificationOnChange` is applied on every write of payout details. A
+ * status that outlived the account number it referred to would be a claim about
+ * a destination nobody checked — and the direction it fails in is money leaving
+ * for an account an aggregator approved and the seller has since replaced.
+ *
+ * There is no fingerprint of the destination, on purpose: a reset on every
+ * write needs no stored hash to compare against, and a hash is one more thing
+ * that can be computed differently at the two write paths (Root Cause #42).
+ *
+ * EXPORTS:
+ *   IFSC_PATTERN, UPI_VPA_PATTERN, PAN_PATTERN,
+ *   isValidIfsc, isValidUpiVpa, isValidPan, normalisePan,
+ *   PAYOUT_VERIFICATION, PayoutVerificationStatus,
+ *   PayoutDestinationIssue, payoutDestinationIssues,
+ *   payoutDestinationIsWellFormed, resetVerificationOnChange
+ *
+ * @tag domain:payouts,payments
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:features/seller/actions,api/store/payout-settings,jobs/settlementVendorRegister
+ * @tag sideEffects:none
+ */
+/**
+ * `AAAA0XXXXXX` — four bank letters, a literal `0`, six branch characters.
+ *
+ * 🛑 This is the FIFTH place this pattern appeared and the only one intended to
+ * survive. The others, measured 2026-10-31:
+ *   · `features/seller/components/SellerPayoutSettingsView.tsx:126`
+ *   · `features/store-extensions/schemas/payout-method-form.ts:45`
+ *   · `src/actions/seller.actions.ts:122`
+ *   · `src/app/api/store/payout-settings/route.ts:101`
+ * Five copies of one format is five chances to disagree about what a valid
+ * IFSC is (Root Cause #75), and the two that mattered — the appkit write path
+ * and the action that calls it — had NO copy at all.
+ */
+export const IFSC_PATTERN = /^[A-Z]{4}0[A-Z0-9]{6}$/;
+/** `handle@psp` — the shape the existing seller form and payout-method schema both already enforce. */
+export const UPI_VPA_PATTERN = /^[\w.\-_]{2,256}@[a-zA-Z]{2,64}$/;
+/**
+ * `AAAAA9999A` — five letters, four digits, one letter.
+ *
+ * 🛑 Shape only, and there is no checksum to add: unlike a GSTIN (whose 15th
+ * character IS a base-36 check digit, which is why `isValidGstin` can verify
+ * more than a shape) a PAN carries no check character that can be recomputed.
+ * The fourth letter encodes holder type and the fifth the surname initial, and
+ * neither is something we can validate against anything we hold. So a
+ * well-formed PAN is a well-formed PAN and nothing more — do not add a
+ * "verified" meaning to this function later.
+ */
+export const PAN_PATTERN = /^[A-Z]{5}[0-9]{4}[A-Z]$/;
+export function isValidIfsc(raw) {
+    if (!raw)
+        return false;
+    return IFSC_PATTERN.test(raw.trim().toUpperCase());
+}
+export function isValidUpiVpa(raw) {
+    if (!raw)
+        return false;
+    return UPI_VPA_PATTERN.test(raw.trim());
+}
+export function isValidPan(raw) {
+    if (!raw)
+        return false;
+    return PAN_PATTERN.test(raw.trim().toUpperCase());
+}
+/** Upper-cased and trimmed, or `undefined` for a blank — a PAN is never stored mixed-case. */
+export function normalisePan(raw) {
+    const value = raw?.trim().toUpperCase();
+    return value ? value : undefined;
+}
+/**
+ * The verification lifecycle, and who writes each value.
+ *
+ * 🛑 `unverified` is the DEFAULT and an absent field means exactly that. It is
+ * not "unknown": a destination nobody has checked is unverified, and reading
+ * absence as anything better is how `isConfigured: true` came to mean nothing.
+ */
+export const PAYOUT_VERIFICATION = {
+    /** Format-valid at most. Written by this module on every destination change. */
+    UNVERIFIED: "unverified",
+    /** Handed to a gateway; its answer has not arrived. Written by the registration job. */
+    PENDING: "pending",
+    /** A gateway accepted the destination. Written ONLY from a gateway response. */
+    VERIFIED: "verified",
+    /** A gateway refused it. `verificationMessage` carries its reason verbatim. */
+    FAILED: "failed",
+};
+/**
+ * Everything wrong with this destination, as a list rather than a throw.
+ *
+ * A list because both call sites need all of it at once: the server action
+ * attaches one issue per field, and the registration job records WHY a store
+ * could not be onboarded. Stopping at the first problem would make a seller fix
+ * one field per round trip.
+ *
+ * 🛑 Reports on what is PRESENT. A bank destination with no `accountNumber` is
+ * reported as missing, because the seller form supports "leave blank to keep
+ * the saved number" and the keep-existing semantics belong to the write path —
+ * so the write path passes the RESOLVED destination (merged with what is
+ * stored), never the raw form values. Checking the form values here would
+ * reject every legitimate blank re-save.
+ */
+export function payoutDestinationIssues(details) {
+    if (!details) {
+        return [{ path: "method", message: "Payout details are required." }];
+    }
+    const issues = [];
+    if (details.method === "upi") {
+        if (!details.upiId?.trim()) {
+            issues.push({ path: "upiId", message: "A UPI ID is required." });
+        }
+        else if (!isValidUpiVpa(details.upiId)) {
+            issues.push({
+                path: "upiId",
+                message: "Please enter a valid UPI ID, e.g. name@bank.",
+            });
+        }
+        return issues;
+    }
+    const bank = details.bankAccount;
+    if (!bank) {
+        return [{ path: "bankAccount", message: "Bank account details are required." }];
+    }
+    if (!bank.accountHolderName?.trim()) {
+        issues.push({
+            path: "bankAccount.accountHolderName",
+            message: "The account holder's name is required.",
+        });
+    }
+    if (!bank.accountNumber?.trim()) {
+        issues.push({
+            path: "bankAccount.accountNumber",
+            message: "An account number is required.",
+        });
+    }
+    else if (!/^\d{9,18}$/.test(bank.accountNumber.trim())) {
+        issues.push({
+            path: "bankAccount.accountNumber",
+            message: "An account number is 9–18 digits.",
+        });
+    }
+    if (!isValidIfsc(bank.ifscCode)) {
+        issues.push({
+            path: "bankAccount.ifscCode",
+            message: "Please enter a valid IFSC code, e.g. HDFC0001234.",
+        });
+    }
+    if (!bank.bankName?.trim()) {
+        issues.push({ path: "bankAccount.bankName", message: "The bank name is required." });
+    }
+    return issues;
+}
+/**
+ * Is this destination well-formed? **This, and only this, is what
+ * `isConfigured` means.**
+ */
+export function payoutDestinationIsWellFormed(details) {
+    return payoutDestinationIssues(details).length === 0;
+}
+/**
+ * The verification fields to write alongside a CHANGED destination.
+ *
+ * Returned as an object to spread rather than applied in place, so the write
+ * path cannot forget the message and the timestamp while remembering the
+ * status — three fields that must move together or the UI shows a stale reason
+ * under a fresh status.
+ */
+export function resetVerificationOnChange() {
+    return {
+        verificationStatus: PAYOUT_VERIFICATION.UNVERIFIED,
+        /*
+         * Explicitly `undefined` rather than omitted, and the clearing works
+         * because `payoutDetails` is written as a WHOLE MAP: every write path does
+         * `userRepository.update(uid, { payoutDetails: details })`, and Firestore
+         * replaces a map field entirely, so keys absent from the new object are
+         * gone. Naming them here is what stops a caller spreading a reset and
+         * keeping the old reason — "failed: account not found" rendered under
+         * "unverified" is worse than either state alone.
+         */
+        verificationMessage: undefined,
+        verifiedAt: undefined,
+    };
+}

package/dist/_internal/shared/features/print/label-profiles.d.ts

@@ -5,7 +5,7 @@ import { MM_PER_INCH, type PrintPageSize } from "../sticker-trace/export/page-si
  */
 export declare const SAFE_MODULE_MM = 0.25;
 /**
- * The floor. Below this a symbol is a lottery: good scanners manage it under
+ * The floor. Below this a symbol is a giveaway: good scanners manage it under
  * good light at a good angle, and a receive station is none of those things.
  */
 export declare const MIN_SCANNABLE_MODULE_MM = 0.19;

package/dist/_internal/shared/features/print/label-profiles.js

@@ -31,7 +31,7 @@ import { MM_PER_INCH, PRINT_PAGE_SIZES, } from "../sticker-trace/export/page-siz
  */
 export const SAFE_MODULE_MM = 0.25;
 /**
- * The floor. Below this a symbol is a lottery: good scanners manage it under
+ * The floor. Below this a symbol is a giveaway: good scanners manage it under
  * good light at a good angle, and a receive station is none of those things.
  */
 export const MIN_SCANNABLE_MODULE_MM = 0.19;

package/dist/_internal/shared/features/products/composite.d.ts

@@ -0,0 +1,104 @@
+import type { ComponentStockPolicy, ProductComponent } from "../../../../features/products/schemas/firestore";
+/**
+ * The fields this module reads. Structural on purpose, for the same reason
+ * `readGroupRules` is: the shape arrives either as a full `ProductDocument`
+ * server-side or as a public projection client-side, and taking the feature
+ * schema here would drag it into a module a client component imports.
+ */
+export interface CompositeSource {
+    components?: ProductComponent[] | null;
+    componentStockPolicy?: ComponentStockPolicy | null;
+}
+/**
+ * Does this listing deliver other listings' goods?
+ *
+ * 🛑 Answered from the listing's own DATA — never from its type, and never from
+ * `isGroupParent`. A group parent is a listing that other listings point at for
+ * browsing; a composite is a listing that CONTAINS others. The BX-53 box
+ * happens to be both, and plenty of groups have a parent that contains nothing.
+ */
+export declare function isComposite(doc: CompositeSource | null | undefined): boolean;
+/**
+ * The composite's components, normalised and defensive.
+ *
+ * Rows with no `listingId` or a non-positive / non-integer `qty` are DROPPED
+ * rather than repaired: a component you cannot identify cannot be delivered,
+ * and inventing `qty: 1` for a malformed row would silently promise the buyer
+ * goods nobody declared. A composite whose rows are all malformed therefore
+ * reads as not-composite, which is the safe direction — it behaves as an
+ * ordinary listing rather than as a composite with wrong contents.
+ *
+ * Duplicate `listingId`s are SUMMED, not de-duplicated: two rows of the same
+ * component legitimately means "two of these", and dropping one would
+ * under-deliver.
+ */
+export declare function compositeComponents(doc: CompositeSource | null | undefined): ProductComponent[];
+/**
+ * This composite's stock policy. `null` when the listing is not a composite —
+ * the question does not apply, and answering it with a value would let a caller
+ * act on a policy for a listing that has no components.
+ *
+ * 🛑 NO DEFAULT for a composite that failed to declare one. Returning
+ * `"independent"` would be the more convenient lie and it is a money-path
+ * behaviour: guessing `independent` oversells an assembled kit, guessing
+ * `derived` makes selling one loose part silently reduce how many sealed boxes
+ * the seller appears to have. A composite with no policy is a configuration
+ * error, caught at the write boundary by `assertCompositeShape`; this returns
+ * `undefined` so a reader that somehow meets a legacy row must handle it rather
+ * than be handed a guess.
+ */
+export declare function componentStockPolicyFor(doc: CompositeSource | null | undefined): ComponentStockPolicy | null | undefined;
+/**
+ * What ONE unit of this composite consumes from its components' stock.
+ *
+ * `independent` returns an EMPTY map — deliberately, and it is the whole model:
+ * a sealed box is its own object, so buying it consumes its own count and
+ * nothing else. The caller then decrements the composite listing exactly as it
+ * would any ordinary single listing, which is what already happens today and
+ * is why `independent` needs no new decrement path.
+ *
+ * `derived` returns componentId → units, which is the same shape
+ * `getExpandedDecrements` already builds for a multi-member cart line, so the
+ * existing fan-out, the per-member GST proration and `stock-restore`'s mirror
+ * all apply unchanged.
+ *
+ * An undeclared policy returns an empty map and is NOT treated as `derived`:
+ * see `componentStockPolicyFor`. The write boundary is what prevents the case.
+ */
+export declare function compositeComponentDecrements(doc: CompositeSource | null | undefined, units?: number): Map<string, number>;
+/** Thrown by `assertCompositeShape`. Carries a code so a route can map it. */
+export declare class CompositeShapeError extends Error {
+    readonly code: "COMPOSITE_POLICY_REQUIRED" | "COMPOSITE_CONTAINS_ITSELF" | "COMPOSITE_DERIVED_UNSUPPORTED";
+    constructor(code: CompositeShapeError["code"], message: string);
+}
+/**
+ * Validate a composite at the WRITE boundary. Throws on the first problem.
+ *
+ * Checked here and not at read time because a stored composite that is wrong is
+ * already a promise made to buyers; the cheapest place to say no is the moment
+ * it is saved, which is the same reasoning as `findBundleMemberStores`.
+ *
+ * `listingId` is this listing's own id, so a composite cannot contain itself.
+ *
+ * ## 🛑 Why `derived` is REFUSED on a plain listing today
+ *
+ * `independent` needs no new machinery: the composite decrements its own count,
+ * which is what an ordinary listing already does. `derived` genuinely does — the
+ * fan-out has to resolve `components[]` and fetch those listings inside the
+ * checkout transaction, and the five `getExpandedDecrements` call sites that
+ * would have to pass them live in `checkout/actions.ts`, which another lane
+ * holds. Until that one coordinated edit lands, a listing saved with
+ * `derived` would decrement nothing but itself — and silently overselling the
+ * parts is exactly the failure this field exists to prevent.
+ *
+ * So it is REFUSED, loudly, rather than accepted and ignored. That distinction
+ * is the whole lesson of `bulkDiscounts`, which sat stored-and-never-read on
+ * this same document: a field that looks configured and does nothing is worse
+ * than one that is absent. Deleting the refusal is a one-line change the day
+ * the fan-out is wired.
+ *
+ * The existing `categoryType:"bundle"` mechanism is unaffected — it already
+ * fans out through `groupMembers` on the cart line and does not route through
+ * this field.
+ */
+export declare function assertCompositeShape(doc: CompositeSource | null | undefined, listingId: string): void;

package/dist/_internal/shared/features/products/composite.js

@@ -0,0 +1,188 @@
+/*
+ * WHY: The owner's requirement, 2026-11-08: *"a listing A is made of 3 listings
+ *      B C and D, if you buy A you get all 3 plus its original packaging but you
+ *      can still buy B C and D individually based on your need, the BX-53 deck
+ *      set is a great example for this"*.
+ *
+ *      The mechanism for this largely EXISTED and was spread across four names
+ *      that partly disagreed — `categoryType:"bundle"` (own price, derived
+ *      stock), the product-group parent (own price, independent stock), grouped
+ *      listings and variant groups. This module is the one place "is this
+ *      listing composite, and what does buying it consume?" is answered, so the
+ *      four stop drifting.
+ *
+ * WHAT: One reader, one guard, zero copies. Pure — no Firestore, no framework,
+ *       safe on both sides of the wire.
+ *
+ * 🛑 CONTAINMENT IS NOT SELECTION. Two different relations the schema has been
+ * conflating through a single `groupId`:
+ *
+ *   `groupId`      — "these listings are browsed and picked together"
+ *   `components[]` — "buying this one DELIVERS those others' goods"
+ *
+ * A product group expresses both at once, which is why `groupChildSlugs` has no
+ * quantities and why the parent used to be selectable inside its own contents
+ * picker (fixed in `6e8ce85b2`). Keep them apart.
+ *
+ * 🛑 A COMPOSITE IS NOT A LISTING TYPE. `"bundle"` left the `ListingType` union
+ * in SB-UNI-D and became a category type; appkit `c0f21425f` removed the last
+ * dead branch that compared a listing type against it (the comparison is spelled
+ * out in that commit, not here — a grep for the pattern is the rework's
+ * acceptance test and a comment must not add a false positive to it).
+ * Compositeness is a property of a
+ * LISTING, declared in its own data, so any type can be composite and enabling
+ * it is a data change. Nothing here compares a listing type to a string, and
+ * nothing that calls it should either.
+ *
+ * EXPORTS: CompositeSource, isComposite, compositeComponents,
+ *          componentStockPolicyFor, compositeComponentDecrements,
+ *          assertCompositeShape, CompositeShapeError
+ *
+ * @tag domain:products
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag sideEffects:none
+ */
+/**
+ * Does this listing deliver other listings' goods?
+ *
+ * 🛑 Answered from the listing's own DATA — never from its type, and never from
+ * `isGroupParent`. A group parent is a listing that other listings point at for
+ * browsing; a composite is a listing that CONTAINS others. The BX-53 box
+ * happens to be both, and plenty of groups have a parent that contains nothing.
+ */
+export function isComposite(doc) {
+    return compositeComponents(doc).length > 0;
+}
+/**
+ * The composite's components, normalised and defensive.
+ *
+ * Rows with no `listingId` or a non-positive / non-integer `qty` are DROPPED
+ * rather than repaired: a component you cannot identify cannot be delivered,
+ * and inventing `qty: 1` for a malformed row would silently promise the buyer
+ * goods nobody declared. A composite whose rows are all malformed therefore
+ * reads as not-composite, which is the safe direction — it behaves as an
+ * ordinary listing rather than as a composite with wrong contents.
+ *
+ * Duplicate `listingId`s are SUMMED, not de-duplicated: two rows of the same
+ * component legitimately means "two of these", and dropping one would
+ * under-deliver.
+ */
+export function compositeComponents(doc) {
+    const rows = doc?.components;
+    if (!Array.isArray(rows) || rows.length === 0)
+        return [];
+    const byId = new Map();
+    for (const row of rows) {
+        const id = typeof row?.listingId === "string" ? row.listingId.trim() : "";
+        if (!id)
+            continue;
+        const qty = row?.qty;
+        if (!Number.isInteger(qty) || qty < 1)
+            continue;
+        byId.set(id, (byId.get(id) ?? 0) + qty);
+    }
+    return [...byId.entries()].map(([listingId, qty]) => ({ listingId, qty }));
+}
+/**
+ * This composite's stock policy. `null` when the listing is not a composite —
+ * the question does not apply, and answering it with a value would let a caller
+ * act on a policy for a listing that has no components.
+ *
+ * 🛑 NO DEFAULT for a composite that failed to declare one. Returning
+ * `"independent"` would be the more convenient lie and it is a money-path
+ * behaviour: guessing `independent` oversells an assembled kit, guessing
+ * `derived` makes selling one loose part silently reduce how many sealed boxes
+ * the seller appears to have. A composite with no policy is a configuration
+ * error, caught at the write boundary by `assertCompositeShape`; this returns
+ * `undefined` so a reader that somehow meets a legacy row must handle it rather
+ * than be handed a guess.
+ */
+export function componentStockPolicyFor(doc) {
+    if (!isComposite(doc))
+        return null;
+    const policy = doc?.componentStockPolicy;
+    return policy === "independent" || policy === "derived" ? policy : undefined;
+}
+/**
+ * What ONE unit of this composite consumes from its components' stock.
+ *
+ * `independent` returns an EMPTY map — deliberately, and it is the whole model:
+ * a sealed box is its own object, so buying it consumes its own count and
+ * nothing else. The caller then decrements the composite listing exactly as it
+ * would any ordinary single listing, which is what already happens today and
+ * is why `independent` needs no new decrement path.
+ *
+ * `derived` returns componentId → units, which is the same shape
+ * `getExpandedDecrements` already builds for a multi-member cart line, so the
+ * existing fan-out, the per-member GST proration and `stock-restore`'s mirror
+ * all apply unchanged.
+ *
+ * An undeclared policy returns an empty map and is NOT treated as `derived`:
+ * see `componentStockPolicyFor`. The write boundary is what prevents the case.
+ */
+export function compositeComponentDecrements(doc, units = 1) {
+    const out = new Map();
+    if (componentStockPolicyFor(doc) !== "derived")
+        return out;
+    if (!Number.isFinite(units) || units < 1)
+        return out;
+    for (const component of compositeComponents(doc)) {
+        out.set(component.listingId, component.qty * units);
+    }
+    return out;
+}
+/** Thrown by `assertCompositeShape`. Carries a code so a route can map it. */
+export class CompositeShapeError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = "CompositeShapeError";
+        this.code = code;
+    }
+}
+/**
+ * Validate a composite at the WRITE boundary. Throws on the first problem.
+ *
+ * Checked here and not at read time because a stored composite that is wrong is
+ * already a promise made to buyers; the cheapest place to say no is the moment
+ * it is saved, which is the same reasoning as `findBundleMemberStores`.
+ *
+ * `listingId` is this listing's own id, so a composite cannot contain itself.
+ *
+ * ## 🛑 Why `derived` is REFUSED on a plain listing today
+ *
+ * `independent` needs no new machinery: the composite decrements its own count,
+ * which is what an ordinary listing already does. `derived` genuinely does — the
+ * fan-out has to resolve `components[]` and fetch those listings inside the
+ * checkout transaction, and the five `getExpandedDecrements` call sites that
+ * would have to pass them live in `checkout/actions.ts`, which another lane
+ * holds. Until that one coordinated edit lands, a listing saved with
+ * `derived` would decrement nothing but itself — and silently overselling the
+ * parts is exactly the failure this field exists to prevent.
+ *
+ * So it is REFUSED, loudly, rather than accepted and ignored. That distinction
+ * is the whole lesson of `bulkDiscounts`, which sat stored-and-never-read on
+ * this same document: a field that looks configured and does nothing is worse
+ * than one that is absent. Deleting the refusal is a one-line change the day
+ * the fan-out is wired.
+ *
+ * The existing `categoryType:"bundle"` mechanism is unaffected — it already
+ * fans out through `groupMembers` on the cart line and does not route through
+ * this field.
+ */
+export function assertCompositeShape(doc, listingId) {
+    const components = compositeComponents(doc);
+    if (components.length === 0)
+        return;
+    if (listingId && components.some((c) => c.listingId === listingId)) {
+        throw new CompositeShapeError("COMPOSITE_CONTAINS_ITSELF", "A listing cannot be one of its own components.");
+    }
+    const policy = componentStockPolicyFor(doc);
+    if (policy === undefined) {
+        throw new CompositeShapeError("COMPOSITE_POLICY_REQUIRED", 'A listing with components must say how its stock works: "independent" if it is a separately boxed item with its own count, or "derived" if it is assembled from those components when ordered.');
+    }
+    if (policy === "derived") {
+        throw new CompositeShapeError("COMPOSITE_DERIVED_UNSUPPORTED", 'Assembled-from-components stock ("derived") is not available on a listing yet — its stock would not be taken from the components and they would oversell. Use a bundle for an assembled kit, or set this listing to "independent" if it is a separately boxed item.');
+    }
+}

package/dist/_internal/shared/features/products/group-rules.d.ts

@@ -27,6 +27,29 @@ export interface GroupRules {
      * only ever REPORTS the figure.
      */
     groupDiscountPercent?: number;
+    /**
+     * The COMPOSITE PARENT's own product id, when these rules came off a product
+     * group's parent listing. Absent for a `groupedListing`, which has no parent.
+     *
+     * 🛑 NOT a seller-set rule — derived, and it exists to make one selection
+     * INVALID: a selection containing the parent itself.
+     *
+     * `/api/products/group/{id}` returns the parent among the members (it carries
+     * the same `groupId`), so a self-assembled selection could include the sealed
+     * box alongside loose copies of its own contents, as one cart line. Measured
+     * live 2026-11-08 on the BX-53 set: the endpoint answered 7 items with the
+     * ₹12,500 box among them, selectable.
+     *
+     * Filtering it out of the picker is not enough — the picker is a client, and
+     * the selection is posted. It belongs here because `checkGroupRules` is the
+     * one place all three readers (picker, cart-add, checkout re-validation)
+     * agree, which is the property this module was extracted to guarantee.
+     *
+     * A composite is bought as ITSELF, on its own listing, at its own price —
+     * that is what `components[]` and `componentStockPolicy` describe. It is
+     * never a line item in a selection assembled from its own contents.
+     */
+    compositeParentId?: string;
 }
 export declare const EMPTY_GROUP_RULES: GroupRules;
 /** Whichever document the rules were read off. */
@@ -40,9 +63,12 @@ export type GroupRuleSource = "product-group" | "grouped-listing";
  * GroupedListingDocument` here would drag two feature schemas into a shared
  * module for no gain — and this module is imported by a client component.
  */
-export declare function readGroupRules(doc: Partial<GroupRules> | null | undefined): GroupRules;
+export declare function readGroupRules(doc: (Partial<GroupRules> & {
+    id?: string;
+    isGroupParent?: boolean;
+}) | null | undefined): GroupRules;
 export interface GroupRuleViolation {
-    code: "GROUP_TOO_FEW_MEMBERS" | "GROUP_TOO_MANY_MEMBERS" | "GROUP_MEMBER_QTY_EXCEEDED" | "GROUP_REQUIRED_MEMBER_MISSING";
+    code: "GROUP_TOO_FEW_MEMBERS" | "GROUP_TOO_MANY_MEMBERS" | "GROUP_MEMBER_QTY_EXCEEDED" | "GROUP_REQUIRED_MEMBER_MISSING" | "GROUP_PARENT_NOT_SELECTABLE";
     /** Buyer-facing, already specific. Never a raw field name. */
     message: string;
 }

package/dist/_internal/shared/features/products/group-rules.js

@@ -59,6 +59,14 @@ export function readGroupRules(doc) {
     if (typeof doc.groupDiscountPercent === "number") {
         out.groupDiscountPercent = doc.groupDiscountPercent;
     }
+    /*
+     * Derived, not read as a rule — see `compositeParentId`. Both conditions are
+     * required: a `groupedListing` document has an `id` too, and it has no parent
+     * member to exclude, so keying off the id alone would invent a rule for it.
+     */
+    if (doc.isGroupParent === true && typeof doc.id === "string" && doc.id) {
+        out.compositeParentId = doc.id;
+    }
     return out;
 }
 /**
@@ -76,6 +84,27 @@ export function readGroupRules(doc) {
 export function checkGroupRules(rules, selection) {
     const chosen = selection.filter((e) => e.quantity > 0);
     const out = [];
+    /*
+     * 🛑 Checked FIRST, and it is a refusal rather than a silent drop.
+     *
+     * Dropping the parent from the selection would charge the buyer for the rest
+     * of what they picked without saying the box they also chose was removed —
+     * the shape of a quietly-wrong total. Refusing names it.
+     *
+     * Counted before the min/max checks for the same reason: with the parent
+     * silently dropped, a selection of "box only" would fail
+     * `groupMinMembers` with a message about picking more items, which tells the
+     * buyer nothing about the actual problem.
+     */
+    if (rules.compositeParentId) {
+        const parentEntry = chosen.find((e) => e.productId === rules.compositeParentId);
+        if (parentEntry) {
+            out.push({
+                code: "GROUP_PARENT_NOT_SELECTABLE",
+                message: `"${parentEntry.title ?? "The complete set"}" is sold as its own listing, not as part of a mix — open it to buy the set, or pick the individual items you want.`,
+            });
+        }
+    }
     if (rules.groupMinMembers !== undefined && chosen.length < rules.groupMinMembers) {
         out.push({
             code: "GROUP_TOO_FEW_MEMBERS",

package/dist/_internal/shared/features/products/pdp-section-ids.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Phase 10 ("widget descriptors") — human labels for the 5 `PdpSectionId`
+ * values, mirroring `ProductDetailPageView.tsx`'s own `renderGallery` /
+ * `renderInfo` / `renderActions` / `renderTabs` / `renderRelated` slot names
+ * 1:1 (verified against that file, 2026-11-02 — `renderBreadcrumb`,
+ * `renderSublistingSection`, `renderGroupSection`, `renderBundleSection` are
+ * real slots too but are conditional/listing-type-specific, not present on
+ * every product; the "jump to section" nav only lists the 5 that render
+ * unconditionally).
+ */
+import type { PdpSectionId } from "../dashboard/recent-entry";
+export declare const PDP_SECTION_IDS: readonly PdpSectionId[];
+export declare const PDP_SECTION_LABEL: Record<PdpSectionId, string>;

package/dist/_internal/shared/features/products/pdp-section-ids.js

@@ -0,0 +1,14 @@
+export const PDP_SECTION_IDS = [
+    "gallery",
+    "info",
+    "actions",
+    "tabs",
+    "related",
+];
+export const PDP_SECTION_LABEL = {
+    gallery: "Photos",
+    info: "Details",
+    actions: "Buy box",
+    tabs: "Description & specs",
+    related: "Related items",
+};