@mohasinac/appkit 4.71.0 → 4.72.0

package/dist/features/stores/repository/store.repository.d.ts

@@ -6,6 +6,7 @@
  */
 import { BaseRepository, type SieveModel, type FirebaseSieveResult, type DocumentSnapshot } from "../../../providers/db-firebase";
 import { StoreDocument } from "../schemas";
+import type { StoreSettlementVendor } from "../schemas/firestore";
 import { type HistoryActor } from "../../../_internal/shared/history/index";
 import type { JsonValue } from "../../../schemas/types";
 /** Who/why for a store write that lands in `statusHistory`. */
@@ -17,6 +18,23 @@ export interface StoreWriteContext {
 }
 export declare class StoreRepository extends BaseRepository<StoreDocument> {
     constructor();
+    /**
+     * `pan` — encrypted on EVERY write path by `applyWriteHooks`.
+     *
+     * 🛑 Declared here rather than encrypted at the call site, which is the whole
+     * reason the hook exists: there are ~14 store write paths and two of them
+     * (`setStatus`, `adminUpdate`) take an arbitrary `Partial<StoreDocument>`, so
+     * a per-call-site encrypt would be correct in whichever ones somebody
+     * remembered. `encryptPiiFields` is idempotent on the `enc:v1:` prefix, so a
+     * value already encrypted passes through unchanged.
+     *
+     * 🛑 `mapDoc` is deliberately NOT overridden to decrypt. This repository is
+     * ciphertext-by-default by accident of history — it never had a `mapDoc`
+     * decrypt to remove — and that is the state `audit-pii-coverage` R3
+     * prescribes, so the new field gets it for free. Plaintext is `revealPan`,
+     * named and greppable.
+     */
+    protected piiFields: readonly ["pan"];
     protected mapDoc<D = StoreDocument>(snap: DocumentSnapshot): D;
     /**
      * LIST reads never carry the WhatsApp token — not even encrypted.
@@ -73,6 +91,51 @@ export declare class StoreRepository extends BaseRepository<StoreDocument> {
      * Find the store owned by a specific user UID.
      */
     findByOwnerId(ownerId: string): Promise<StoreDocument | null>;
+    /**
+     * The store's PAN in PLAINTEXT. The only way to get it.
+     *
+     * 🛑 NAMED and opt-in, following `SiteSettingsRepository.getDecryptedCredentials`.
+     * `mapDoc` returns the `enc:v1:…` value, so every other reader of a store
+     * document holds ciphertext and cannot leak plaintext by forgetting to
+     * project. Its one legitimate caller is the vendor-registration job, which
+     * hands the PAN straight to the aggregator and never stores or logs it.
+     *
+     * 🛑 Returns `undefined` for an absent field — which is a real and common
+     * state, not an error. Most sellers have not supplied a PAN, and blocker #5
+     * means some may never be onboardable; the job records that rather than
+     * throwing.
+     *
+     * 🛑 There is no masked variant and none should be added speculatively. No
+     * surface renders a PAN today, and a `maskedPan` with no reader is the
+     * shadow-constant shape of Root Cause #53 — it would read as proof that
+     * somewhere shows one.
+     */
+    revealPan(doc: Pick<StoreDocument, "pan"> | null | undefined): string | undefined;
+    /**
+     * Record one gateway's vendor registration for this store.
+     *
+     * 🛑 A DOTTED PATH, never `update({ settlementVendors: … })`. Firestore
+     * replaces a map field entirely, so writing the object wholesale would delete
+     * every OTHER gateway's registration — the same defect
+     * `audit-pii-crypto`'s PII_MAP_WHOLESALE_UPDATE exists for, on a map that
+     * happens to hold no PII. With one splitting gateway live today the bug would
+     * be invisible and would surface on the day a second is added, which is the
+     * worst possible time to find it.
+     *
+     * 🛑 Goes through the raw collection rather than `update()`, deliberately:
+     * `BaseRepository.update` takes `Partial<Plaintext<T>>`, which cannot express
+     * a dotted key, and a cast to smuggle one past it would also smuggle past
+     * `applyWriteHooks`. Nothing in this map is PII or searchable, so there is no
+     * hook this bypass loses — `incrementTotalProducts` writes
+     * `stats.totalProducts` the same way for the same reason.
+     *
+     * Not in `STORE_TRACKED_FIELDS`: a registration attempt is an operational
+     * event with its own `attempts`/`lastAttemptAt`, and tracking it would write
+     * a timeline entry per retry and exhaust the 50-entry FIFO cap while burying
+     * the status changes a seller actually reads — the identical argument the
+     * `standing` block makes.
+     */
+    setSettlementVendor(storeSlug: string, gateway: string, record: StoreSettlementVendor): Promise<void>;
     /**
      * Update store fields (partial).
      */
@@ -92,6 +155,23 @@ export declare class StoreRepository extends BaseRepository<StoreDocument> {
      * write and a single timeline entry; `prior` keeps that entry read-free
      * for the route, which has already fetched the store to 404 on a missing
      * one (Rule #6).
+     *
+     * 🛑 **ACTIVATION SIDE EFFECTS DO NOT LIVE HERE.** Approving a store is what
+     * triggers split-settlement vendor registration, and the enqueue for it is
+     * `onStoreActivated` in
+     * `_internal/server/features/stores/activation.ts` — called by the admin
+     * PATCH route, which is this method's sole dispatcher.
+     *
+     * Two reasons it is not in this method. A repository is the data layer and no
+     * repository in this codebase imports another feature's — `enqueueJob` lives
+     * in `features/jobs/actions/` and pulls the jobs repository and the admin
+     * Auth SDK with it, which is the Turbopack import-chain trap (Root Cause
+     * #6/#18). And a job enqueued from inside a write primitive would fire for a
+     * reseed, a backfill and a test fixture, none of which is an approval.
+     *
+     * A SECOND dispatcher of this method must call `onStoreActivated` too. That
+     * is the cost of the layering, and it is stated here because this is where
+     * someone will look.
      */
     setStatus(storeSlug: string, status: StoreDocument["status"], extra?: Partial<StoreDocument>, ctx?: StoreWriteContext, prior?: StoreDocument | null): Promise<StoreDocument>;
     /**

package/dist/features/stores/repository/store.repository.js

@@ -9,12 +9,31 @@ import { increment } from "../../../contracts/field-ops.js";
 import { STORE_COLLECTION, STORE_FIELDS, DEFAULT_STORE_DATA, StoreStatusValues, STORE_TRACKED_FIELDS, STORE_HISTORY_PII_FIELDS, } from "../schemas/index.js";
 import { DatabaseError } from "../../../errors/index.js";
 import { normalizeError } from "../../../errors/normalize.js";
+import { STORE_PII_FIELDS } from "../../../security/pii-schemas.js";
+import { decryptPii } from "../../../security/pii-encrypt.js";
 import { withHistory } from "../../../_internal/shared/history/index.js";
 import { buildStoreSearchTxt } from "../../../utils/search-txt-builders.js";
 import { planSearchTxt, beginSearchWindow, emptySearchResult, } from "../../../utils/search-txt-query.js";
 export class StoreRepository extends BaseRepository {
     constructor() {
         super(STORE_COLLECTION);
+        /**
+         * `pan` — encrypted on EVERY write path by `applyWriteHooks`.
+         *
+         * 🛑 Declared here rather than encrypted at the call site, which is the whole
+         * reason the hook exists: there are ~14 store write paths and two of them
+         * (`setStatus`, `adminUpdate`) take an arbitrary `Partial<StoreDocument>`, so
+         * a per-call-site encrypt would be correct in whichever ones somebody
+         * remembered. `encryptPiiFields` is idempotent on the `enc:v1:` prefix, so a
+         * value already encrypted passes through unchanged.
+         *
+         * 🛑 `mapDoc` is deliberately NOT overridden to decrypt. This repository is
+         * ciphertext-by-default by accident of history — it never had a `mapDoc`
+         * decrypt to remove — and that is the state `audit-pii-coverage` R3
+         * prescribes, so the new field gets it for free. Plaintext is `revealPan`,
+         * named and greppable.
+         */
+        this.piiFields = STORE_PII_FIELDS;
     }
     mapDoc(snap) {
         return super.mapDoc(snap);
@@ -117,6 +136,68 @@ export class StoreRepository extends BaseRepository {
     async findByOwnerId(ownerId) {
         return this.findOneBy(STORE_FIELDS.OWNER_ID, ownerId);
     }
+    /**
+     * The store's PAN in PLAINTEXT. The only way to get it.
+     *
+     * 🛑 NAMED and opt-in, following `SiteSettingsRepository.getDecryptedCredentials`.
+     * `mapDoc` returns the `enc:v1:…` value, so every other reader of a store
+     * document holds ciphertext and cannot leak plaintext by forgetting to
+     * project. Its one legitimate caller is the vendor-registration job, which
+     * hands the PAN straight to the aggregator and never stores or logs it.
+     *
+     * 🛑 Returns `undefined` for an absent field — which is a real and common
+     * state, not an error. Most sellers have not supplied a PAN, and blocker #5
+     * means some may never be onboardable; the job records that rather than
+     * throwing.
+     *
+     * 🛑 There is no masked variant and none should be added speculatively. No
+     * surface renders a PAN today, and a `maskedPan` with no reader is the
+     * shadow-constant shape of Root Cause #53 — it would read as proof that
+     * somewhere shows one.
+     */
+    revealPan(doc) {
+        const value = doc?.pan;
+        if (!value)
+            return undefined;
+        const plain = decryptPii(value);
+        return typeof plain === "string" && plain ? plain : undefined;
+    }
+    /**
+     * Record one gateway's vendor registration for this store.
+     *
+     * 🛑 A DOTTED PATH, never `update({ settlementVendors: … })`. Firestore
+     * replaces a map field entirely, so writing the object wholesale would delete
+     * every OTHER gateway's registration — the same defect
+     * `audit-pii-crypto`'s PII_MAP_WHOLESALE_UPDATE exists for, on a map that
+     * happens to hold no PII. With one splitting gateway live today the bug would
+     * be invisible and would surface on the day a second is added, which is the
+     * worst possible time to find it.
+     *
+     * 🛑 Goes through the raw collection rather than `update()`, deliberately:
+     * `BaseRepository.update` takes `Partial<Plaintext<T>>`, which cannot express
+     * a dotted key, and a cast to smuggle one past it would also smuggle past
+     * `applyWriteHooks`. Nothing in this map is PII or searchable, so there is no
+     * hook this bypass loses — `incrementTotalProducts` writes
+     * `stats.totalProducts` the same way for the same reason.
+     *
+     * Not in `STORE_TRACKED_FIELDS`: a registration attempt is an operational
+     * event with its own `attempts`/`lastAttemptAt`, and tracking it would write
+     * a timeline entry per retry and exhaust the 50-entry FIFO cap while burying
+     * the status changes a seller actually reads — the identical argument the
+     * `standing` block makes.
+     */
+    async setSettlementVendor(storeSlug, gateway, record) {
+        if (!storeSlug || !gateway) {
+            throw new DatabaseError("setSettlementVendor requires a storeSlug and a gateway");
+        }
+        await this.db
+            .collection(this.collection)
+            .doc(storeSlug)
+            .update({
+            [`settlementVendors.${gateway}`]: record,
+            updatedAt: new Date(),
+        });
+    }
     /**
      * Update store fields (partial).
      */
@@ -141,6 +222,23 @@ export class StoreRepository extends BaseRepository {
      * write and a single timeline entry; `prior` keeps that entry read-free
      * for the route, which has already fetched the store to 404 on a missing
      * one (Rule #6).
+     *
+     * 🛑 **ACTIVATION SIDE EFFECTS DO NOT LIVE HERE.** Approving a store is what
+     * triggers split-settlement vendor registration, and the enqueue for it is
+     * `onStoreActivated` in
+     * `_internal/server/features/stores/activation.ts` — called by the admin
+     * PATCH route, which is this method's sole dispatcher.
+     *
+     * Two reasons it is not in this method. A repository is the data layer and no
+     * repository in this codebase imports another feature's — `enqueueJob` lives
+     * in `features/jobs/actions/` and pulls the jobs repository and the admin
+     * Auth SDK with it, which is the Turbopack import-chain trap (Root Cause
+     * #6/#18). And a job enqueued from inside a write primitive would fire for a
+     * reseed, a backfill and a test fixture, none of which is an approval.
+     *
+     * A SECOND dispatcher of this method must call `onStoreActivated` too. That
+     * is the cost of the layering, and it is stated here because this is where
+     * someone will look.
      */
     async setStatus(storeSlug, status, extra, ctx, prior) {
         const current = prior !== undefined ? prior : await this.findById(storeSlug);

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

@@ -66,6 +66,97 @@ export interface StoreShippingPolicyField {
     };
     /** Goods value at or above which shipping is free, whatever the mode. */
     freeAbove?: number;
+    /**
+     * The seller's TWO-AXIS shipping offer — owner, 2026-11-08.
+     *
+     * *"A seller agrees from their dashboard for the shipping option… if they are
+     * okay with our shipping providers' quotes then they must accept that as
+     * well. Both can be enabled."*
+     *
+     * 🛑 A SIBLING of `mode`, not a replacement, and deliberately on this same
+     * document rather than a new field. `mode` is single-valued and therefore
+     * structurally incapable of expressing "both enabled"; this is. But a second
+     * shipping-config FIELD would be a third shipping-config system, and this
+     * file's own `mode.ts` opens by recording what the last pair cost — *"there
+     * were two shipping-config systems and the authoritative one was the flat
+     * number, by accident."*
+     *
+     * So: one field, one reader (`toSellerShippingOffer`), and `mode` remains the
+     * fallback it derives from for every store that has not saved an explicit
+     * offer. `offerFromPolicy` is that mapping and it is lossless —
+     * `flat`→custom at that amount, `estimate`→platform quotes, `free`→custom at
+     * ₹0 — so a seller who set ₹100 on the old surface keeps charging ₹100.
+     *
+     * 🛑 `customFeePerOrder` is nullable and `null` is NOT zero. Zero is "I ship
+     * free"; `null` is an unfinished form, which
+     * `validateSellerShippingOffer` refuses to save and
+     * `buildShippingOptions` refuses to price.
+     */
+    offer?: {
+        platformQuotesAccepted: boolean;
+        customEnabled: boolean;
+        /** REQUIRED when `customEnabled`. Per ORDER, never per item. */
+        customFeePerOrder: number | null;
+        customFreeAbove: number | null;
+        customLabel: string | null;
+    };
+}
+/**
+ * Where a store's registration with ONE splitting gateway has got to.
+ *
+ * 🛑 `blocked` is NOT `rejected`, and the distinction is the whole value of
+ * this union. `rejected` means the gateway said no — retrying sends the same
+ * data and gets the same answer, so it needs a human. `blocked` means WE could
+ * not even ask, because the store has no payout destination or no PAN yet, and
+ * it clears itself the moment the seller fills the form in. A single "failed"
+ * would make the second case look like the first and send an operator to chase
+ * an aggregator about a form field.
+ *
+ * 🛑 There is no `unsupported`. If a gateway genuinely cannot onboard a seller
+ * (blocker #5 — an unregistered seller with no GSTIN may be un-onboardable for
+ * some entity types) that is the gateway's own refusal and belongs in
+ * `rejected` with its message, not in a state we invented on its behalf.
+ */
+export declare const SettlementVendorStatusValues: {
+    /** Registration has been requested; the gateway has not answered yet. */
+    readonly PENDING: "pending";
+    /** The gateway accepted the vendor. Money can be split to them. */
+    readonly ACTIVE: "active";
+    /** The gateway refused. `message` carries its reason; needs a human. */
+    readonly REJECTED: "rejected";
+    /** We could not ask — missing payout destination, PAN, or both. Self-clearing. */
+    readonly BLOCKED: "blocked";
+};
+export type SettlementVendorStatus = (typeof SettlementVendorStatusValues)[keyof typeof SettlementVendorStatusValues];
+export interface StoreSettlementVendor {
+    /**
+     * The id the GATEWAY knows this vendor by.
+     *
+     * 🛑 Always our own `storeSlug`, supplied by us rather than generated by the
+     * gateway. That makes registration idempotent without a lookup — re-running
+     * the job for a store asks the gateway about an id we can always recompute —
+     * and it keeps the split instruction buildable from a cart line's `storeId`
+     * with no extra read.
+     */
+    vendorId: string;
+    status: SettlementVendorStatus;
+    /**
+     * Why, for every status except `active`.
+     *
+     * The gateway's own sentence when it refused, or ours when we could not ask.
+     * 🛑 Never `undefined` on a non-`active` status: a store that cannot be paid
+     * with no stated reason is the failure mode this field exists to prevent.
+     */
+    message?: string;
+    /** When the gateway last ACCEPTED. Absent on every other status. */
+    registeredAt?: Date | string;
+    /** When we last tried, whatever the outcome. */
+    lastAttemptAt?: Date | string;
+    /**
+     * Attempts so far, so a repeatedly-failing registration is visible as a
+     * pattern rather than as one stale message.
+     */
+    attempts?: number;
 }
 export declare const StoreStatusValues: {
     readonly PENDING: "pending";
@@ -283,6 +374,77 @@ export interface StoreDocument extends BaseDocument {
     legalName?: string;
     /** Registered address as it should appear on the invoice. */
     registeredAddress?: string;
+    /**
+     * The seller's 10-character PAN — **CIPHERTEXT AT REST**.
+     *
+     * ## Why it exists at all
+     *
+     * A splitting aggregator needs it to onboard a vendor for most entity types,
+     * and until 2026-10-31 there was NO PAN field anywhere in this codebase: the
+     * only occurrences were redaction keys in `security/pii-redact.ts`. The
+     * seller form had PAN and business-type inputs and they were REMOVED on
+     * 2026-10-19 for exactly the right reason — *"an input that provably cannot
+     * persist is worse than no input"* — because the route's `z.object()`
+     * stripped them and a seller who typed a PAN was shown a success toast while
+     * the value went nowhere. This is the storage that removal asked for; the
+     * input comes back WITH it, in the same change.
+     *
+     * ## 🛑 Encrypted by `StoreRepository.piiFields`, and NOT decrypted on read
+     *
+     * `STORE_PII_FIELDS` names it, so every write path encrypts (create,
+     * createWithId, update, and the whole `*InTx`/`*InBatch` family — that is the
+     * point of declaring it rather than encrypting at a call site). `mapDoc` does
+     * NOT decrypt, so an ordinary read returns `enc:v1:…` and plaintext requires
+     * the named `storeRepository.revealPan(doc)`. That is the
+     * `SiteSettingsRepository` shape CLAUDE.md prescribes, adopted here for free
+     * because this repository never had a `mapDoc` decrypt to remove.
+     *
+     * 🛑 It is typed `string`, not `Encrypted<string>`, and that is a DELIBERATE
+     * omission rather than an oversight. Branding it is the correct end state,
+     * and it is half a change on its own: `StoreRepository` overrides `update`
+     * with `Partial<StoreDocument>` (not `Partial<Plaintext<StoreDocument>>`), so
+     * the brand would have to land together with a `StorePlain` write shape
+     * across every store write path in one commit. The nested payout PII sets the
+     * precedent for the interim state — `SellerBankAccount.accountNumber` and
+     * `SellerPayoutDetails.upiId` are both plain `string` and both encrypted at
+     * rest.
+     *
+     * 🛑 PRIVATE in the public projection, and it is the one field on this
+     * document where publishing it would be a disclosure with a legal dimension
+     * rather than a commercial one.
+     */
+    pan?: string;
+    /**
+     * ── Split-settlement vendor identity, PER GATEWAY ────────────────────────
+     *
+     * Under split settlement the buyer's money goes buyer → aggregator escrow →
+     * seller and never enters the platform's account. For the aggregator to send
+     * a seller their share it must know them as a VENDOR, which means a
+     * registration call and an id it hands back.
+     *
+     * 🛑 A MAP KEYED BY GATEWAY, never a bare `cashfreeVendorId`. The whole
+     * reason `supportsSplit` is a capability rather than a name test
+     * (`RegisteredPaymentGateway`, Root Cause #61) is that a second splitting
+     * gateway must be a row and not a sweep — a gateway-shaped field name would
+     * reintroduce exactly the coupling the capability removed, in the schema,
+     * where it is hardest to change.
+     *
+     * 🛑 WITHOUT THIS, REGISTRATION IS NOT IDEMPOTENT. There was nowhere to
+     * store a vendor id at all, so nothing could answer "is this store already
+     * registered" — and a job that cannot tell either re-registers on every run
+     * or never runs twice, and both are wrong in a way the gateway reports
+     * asynchronously.
+     *
+     * 🛑 Written through `storeRepository.setSettlementVendor`, which uses a
+     * DOTTED PATH (`settlementVendors.<gateway>`). A whole-map `update()`
+     * replaces the field, so writing the object wholesale would delete every
+     * OTHER gateway's registration — the same trap `audit-pii-crypto`'s
+     * PII_MAP_WHOLESALE_UPDATE exists for, on a map that happens to hold no PII.
+     *
+     * PRIVATE. A buyer learns nothing from it, and it names an external account
+     * identifier belonging to this business's aggregator relationship.
+     */
+    settlementVendors?: Record<string, StoreSettlementVendor>;
     /**
      * How this store PRICES shipping — C5b. Absent means `free`.
      *
@@ -468,7 +630,7 @@ export declare const STORE_TRACKED_FIELDS: readonly ["status", "isPublic", "isVe
  * is a live Meta credential; `mapDoc` decrypts it on EVERY read, so it is
  * present in memory whenever a diff runs.
  */
-export declare const STORE_HISTORY_PII_FIELDS: readonly ["accessToken", "payoutDetails", "upiVpa", "accountNumber"];
+export declare const STORE_HISTORY_PII_FIELDS: readonly ["accessToken", "payoutDetails", "upiVpa", "accountNumber", "pan"];
 export type { StoreCapability } from "../../auth/permissions/constants";
 export declare const STORE_COLLECTION: "stores";
 export declare const STORE_FIELDS: {
@@ -506,6 +668,13 @@ export declare const STORE_FIELDS: {
     readonly CAPABILITIES: "capabilities";
     /** Per-store WhatsApp catalogue feed kill switch. Absent means ENABLED. */
     readonly WHATSAPP_FEED_ENABLED: "whatsappFeedEnabled";
+    readonly GSTIN: "gstin";
+    readonly LEGAL_NAME: "legalName";
+    readonly REGISTERED_ADDRESS: "registeredAddress";
+    /** Ciphertext at rest — read through `storeRepository.revealPan`, never directly. */
+    readonly PAN: "pan";
+    /** Map keyed by gateway name. Write with `setSettlementVendor`, never wholesale. */
+    readonly SETTLEMENT_VENDORS: "settlementVendors";
     readonly STATUS_VALUES: {
         readonly PENDING: "pending";
         readonly ACTIVE: "active";
@@ -539,5 +708,28 @@ export declare const STORE_ADDRESS_SUBCOLLECTION: "addresses";
  * same literal already lives legitimately (`CONSIGNMENT_STORE_ID` in
  * `features/catalogue/utils/product-from-item.ts`), and this file is the one
  * that already documents the rule on `acceptsPoints` above.
+ *
+ * 🛑 THE MONEY PATH DOES NOT READ THIS, and that is not an oversight — do not
+ * "finish the job" by wiring it in. `siteSettings.payment.platformStoreId` is
+ * a SECOND, admin-owned declaration of the same store, read by
+ * `cartVendorComposition` (`_internal/shared/checkout/settlement.ts`) to decide
+ * whether a cart may be collected by a gateway that cannot split at capture.
+ *
+ * Two declarations for two different questions:
+ *
+ *  - this constant answers PRODUCT questions — which store a catalogue
+ *    consignment is listed under, which store cannot decline to fund the points
+ *    programme. A wrong answer is a mis-filed listing.
+ *  - the setting answers a COMPLIANCE question — whose money this business may
+ *    lawfully collect into its own account. A wrong answer is RBI commingling
+ *    on a real payment, and it presents as a successful checkout.
+ *
+ * So the setting FAILS CLOSED when unset (every store counts as third-party)
+ * and must never fall back to this constant: a hardcoded brand literal — one
+ * this file's own comment above describes as consumer data that does not belong
+ * in appkit, tracked for removal under A5c — would then be making an
+ * authorisation decision for every install of the package. The seed sets the
+ * setting FROM this constant, which is how they agree for this install without
+ * the compliance rule inheriting a default nobody chose.
  */
 export declare const PLATFORM_STORE_ID = "store-letitrip-official";

package/dist/features/stores/schemas/firestore.js

@@ -5,6 +5,33 @@
  * and helpers for the stores feature.
  */
 import { slugify } from "../../../utils/string.formatter.js";
+// -- Split-settlement vendor registration -------------------------------------
+/**
+ * Where a store's registration with ONE splitting gateway has got to.
+ *
+ * 🛑 `blocked` is NOT `rejected`, and the distinction is the whole value of
+ * this union. `rejected` means the gateway said no — retrying sends the same
+ * data and gets the same answer, so it needs a human. `blocked` means WE could
+ * not even ask, because the store has no payout destination or no PAN yet, and
+ * it clears itself the moment the seller fills the form in. A single "failed"
+ * would make the second case look like the first and send an operator to chase
+ * an aggregator about a form field.
+ *
+ * 🛑 There is no `unsupported`. If a gateway genuinely cannot onboard a seller
+ * (blocker #5 — an unregistered seller with no GSTIN may be un-onboardable for
+ * some entity types) that is the gateway's own refusal and belongs in
+ * `rejected` with its message, not in a state we invented on its behalf.
+ */
+export const SettlementVendorStatusValues = {
+    /** Registration has been requested; the gateway has not answered yet. */
+    PENDING: "pending",
+    /** The gateway accepted the vendor. Money can be split to them. */
+    ACTIVE: "active",
+    /** The gateway refused. `message` carries its reason; needs a human. */
+    REJECTED: "rejected",
+    /** We could not ask — missing payout destination, PAN, or both. Self-clearing. */
+    BLOCKED: "blocked",
+};
 // -- Store Document -----------------------------------------------------------
 export const StoreStatusValues = {
     PENDING: "pending",
@@ -57,6 +84,15 @@ export const STORE_HISTORY_PII_FIELDS = [
     "payoutDetails",
     "upiVpa",
     "accountNumber",
+    /*
+     * 🛑 `pan` is scrubbed from the timeline even though it is encrypted at rest
+     * by `STORE_PII_FIELDS`. Those are two different mechanisms: the repository's
+     * `piiFields` covers `pan` at the TOP LEVEL of the document, and nothing
+     * declares `statusHistory[].changes.pan` — so a diff that captured it would
+     * persist the PLAINTEXT the diff ran against, beside the ciphertext in the
+     * field it came from. Same reason the four above it are here.
+     */
+    "pan",
 ];
 export const STORE_COLLECTION = "stores";
 export const STORE_FIELDS = {
@@ -94,6 +130,13 @@ export const STORE_FIELDS = {
     CAPABILITIES: "capabilities",
     /** Per-store WhatsApp catalogue feed kill switch. Absent means ENABLED. */
     WHATSAPP_FEED_ENABLED: "whatsappFeedEnabled",
+    GSTIN: "gstin",
+    LEGAL_NAME: "legalName",
+    REGISTERED_ADDRESS: "registeredAddress",
+    /** Ciphertext at rest — read through `storeRepository.revealPan`, never directly. */
+    PAN: "pan",
+    /** Map keyed by gateway name. Write with `setSettlementVendor`, never wholesale. */
+    SETTLEMENT_VENDORS: "settlementVendors",
     STATUS_VALUES: {
         PENDING: "pending",
         ACTIVE: "active",
@@ -136,5 +179,28 @@ export const STORE_ADDRESS_SUBCOLLECTION = "addresses";
  * same literal already lives legitimately (`CONSIGNMENT_STORE_ID` in
  * `features/catalogue/utils/product-from-item.ts`), and this file is the one
  * that already documents the rule on `acceptsPoints` above.
+ *
+ * 🛑 THE MONEY PATH DOES NOT READ THIS, and that is not an oversight — do not
+ * "finish the job" by wiring it in. `siteSettings.payment.platformStoreId` is
+ * a SECOND, admin-owned declaration of the same store, read by
+ * `cartVendorComposition` (`_internal/shared/checkout/settlement.ts`) to decide
+ * whether a cart may be collected by a gateway that cannot split at capture.
+ *
+ * Two declarations for two different questions:
+ *
+ *  - this constant answers PRODUCT questions — which store a catalogue
+ *    consignment is listed under, which store cannot decline to fund the points
+ *    programme. A wrong answer is a mis-filed listing.
+ *  - the setting answers a COMPLIANCE question — whose money this business may
+ *    lawfully collect into its own account. A wrong answer is RBI commingling
+ *    on a real payment, and it presents as a successful checkout.
+ *
+ * So the setting FAILS CLOSED when unset (every store counts as third-party)
+ * and must never fall back to this constant: a hardcoded brand literal — one
+ * this file's own comment above describes as consumer data that does not belong
+ * in appkit, tracked for removal under A5c — would then be making an
+ * authorisation decision for every install of the package. The seed sets the
+ * setting FROM this constant, which is how they agree for this install without
+ * the compliance rule inheriting a default nobody chose.
  */
 export const PLATFORM_STORE_ID = "store-letitrip-official";