@mohasinac/appkit 4.44.0 → 4.46.0

package/dist/seed/payouts-seed-data.js

@@ -12,9 +12,9 @@
  * @tag consumers:seed/index.ts,seed/runner.ts
  * @tag sideEffects:none
  */
-import { getDefaultCurrency } from "./seed-market-config";
+import { getDefaultCurrency } from "./seed-market-config.js";
 const _CURRENCY = getDefaultCurrency();
-import { PAYOUT_FIELDS, DEFAULT_PLATFORM_FEE_RATE, } from "../features/payments/schemas";
+import { PAYOUT_FIELDS, DEFAULT_PLATFORM_FEE_RATE, } from "../features/payments/schemas/index.js";
 const NOW = new Date();
 const daysAgo = (n) => new Date(NOW.getTime() - n * 86400000);
 /**

package/dist/seed/product-features-seed-data.js

@@ -42,8 +42,8 @@
  * @tag consumers:seed/index.ts,seed/runner.ts
  * @tag sideEffects:none
  */
-import { buildSearchTxt } from "../utils/search-txt";
-import { CHARACTER_SEEDS, CHARACTER_SEED_COUNT } from "./_helpers/character-features";
+import { buildSearchTxt } from "../utils/search-txt.js";
+import { CHARACTER_SEEDS, CHARACTER_SEED_COUNT } from "./_helpers/character-features.js";
 const NOW = new Date("2026-05-11T00:00:00.000Z");
 const daysAgo = (n) => new Date(NOW.getTime() - n * 86400000);
 const STAMP = daysAgo(30);

package/dist/seed/products-art-seed-data.js

@@ -17,10 +17,10 @@
  * @tag consumers:seed/index.ts,seed/runner.ts
  * @tag sideEffects:none
  */
-import { PRODUCT_FIELDS } from "../constants/field-names";
-import { buildSearchTxt } from "../utils/search-txt";
-import { seedPhoto } from "./_helpers/media";
-import { withFinalSale } from "./_helpers/final-sale-fixtures";
+import { PRODUCT_FIELDS } from "../constants/field-names.js";
+import { buildSearchTxt } from "../utils/search-txt.js";
+import { seedPhoto } from "./_helpers/media.js";
+import { withFinalSale } from "./_helpers/final-sale-fixtures.js";
 const _rawProductsArtSeedData = [
     {
         id: "art-dranzer-phoenix-poster",

package/dist/seed/products-auctions-seed-data.js

@@ -22,10 +22,10 @@
  * @tag consumers:seed/index.ts,seed/runner.ts
  * @tag sideEffects:none
  */
-import { PRODUCT_FIELDS } from "../constants/field-names";
-import { buildSearchTxt } from "../utils/search-txt";
-import { seedPhoto } from "./_helpers/media";
-import { withFinalSale } from "./_helpers/final-sale-fixtures";
+import { PRODUCT_FIELDS } from "../constants/field-names.js";
+import { buildSearchTxt } from "../utils/search-txt.js";
+import { seedPhoto } from "./_helpers/media.js";
+import { withFinalSale } from "./_helpers/final-sale-fixtures.js";
 function withTokens(p) {
     return {
         tags: [],

package/dist/seed/products-classifieds-seed-data.js

@@ -24,11 +24,11 @@
  * @tag consumers:seed/index.ts,seed/runner.ts
  * @tag sideEffects:none
  */
-import { withProductSearchTxt } from "./_helpers/product-search-txt";
-import { PRODUCT_FIELDS } from "../constants/field-names";
-import { buildSearchTxt } from "../utils/search-txt";
-import { seedPhoto } from "./_helpers/media";
-import { withFinalSale } from "./_helpers/final-sale-fixtures";
+import { withProductSearchTxt } from "./_helpers/product-search-txt.js";
+import { PRODUCT_FIELDS } from "../constants/field-names.js";
+import { buildSearchTxt } from "../utils/search-txt.js";
+import { seedPhoto } from "./_helpers/media.js";
+import { withFinalSale } from "./_helpers/final-sale-fixtures.js";
 const _rawproductsClassifiedsSeedData = [
     {
         id: "classified-beyblade-stadium-set",

package/dist/seed/products-digital-codes-seed-data.js

@@ -17,11 +17,11 @@
  * @tag consumers:seed/index.ts,seed/runner.ts
  * @tag sideEffects:none
  */
-import { withProductSearchTxt } from "./_helpers/product-search-txt";
-import { PRODUCT_FIELDS } from "../constants/field-names";
-import { buildSearchTxt } from "../utils/search-txt";
-import { seedPhoto } from "./_helpers/media";
-import { withFinalSale } from "./_helpers/final-sale-fixtures";
+import { withProductSearchTxt } from "./_helpers/product-search-txt.js";
+import { PRODUCT_FIELDS } from "../constants/field-names.js";
+import { buildSearchTxt } from "../utils/search-txt.js";
+import { seedPhoto } from "./_helpers/media.js";
+import { withFinalSale } from "./_helpers/final-sale-fixtures.js";
 const _rawproductsDigitalCodesSeedData = [
     {
         id: "digitalcode-beyblade-x-app-starter-pack",

package/dist/seed/products-live-items-seed-data.js

@@ -30,11 +30,11 @@
  * @tag consumers:seed/index.ts,seed/runner.ts
  * @tag sideEffects:none
  */
-import { withProductSearchTxt } from "./_helpers/product-search-txt";
-import { PRODUCT_FIELDS } from "../constants/field-names";
-import { buildSearchTxt } from "../utils/search-txt";
-import { seedPhoto } from "./_helpers/media";
-import { withFinalSale } from "./_helpers/final-sale-fixtures";
+import { withProductSearchTxt } from "./_helpers/product-search-txt.js";
+import { PRODUCT_FIELDS } from "../constants/field-names.js";
+import { buildSearchTxt } from "../utils/search-txt.js";
+import { seedPhoto } from "./_helpers/media.js";
+import { withFinalSale } from "./_helpers/final-sale-fixtures.js";
 const _rawproductsLiveItemsSeedData = [
     {
         id: "live-golden-retriever-puppy",

package/dist/seed/products-preorders-seed-data.js

@@ -19,10 +19,10 @@
  * @tag consumers:seed/index.ts,seed/runner.ts
  * @tag sideEffects:none
  */
-import { PRODUCT_FIELDS } from "../constants/field-names";
-import { buildSearchTxt } from "../utils/search-txt";
-import { seedPhoto } from "./_helpers/media";
-import { withFinalSale } from "./_helpers/final-sale-fixtures";
+import { PRODUCT_FIELDS } from "../constants/field-names.js";
+import { buildSearchTxt } from "../utils/search-txt.js";
+import { seedPhoto } from "./_helpers/media.js";
+import { withFinalSale } from "./_helpers/final-sale-fixtures.js";
 const _rawPreordersSeedData = [
     {
         id: "preorder-beyblade-x-bx-08-wave",

package/dist/seed/products-prize-draws-seed-data.js

@@ -18,11 +18,11 @@
  * @tag consumers:seed/index.ts,seed/runner.ts
  * @tag sideEffects:none
  */
-import { withProductSearchTxt } from "./_helpers/product-search-txt";
-import { PRODUCT_FIELDS } from "../constants/field-names";
-import { buildSearchTxt } from "../utils/search-txt";
-import { seedPhoto } from "./_helpers/media";
-import { withFinalSale } from "./_helpers/final-sale-fixtures";
+import { withProductSearchTxt } from "./_helpers/product-search-txt.js";
+import { PRODUCT_FIELDS } from "../constants/field-names.js";
+import { buildSearchTxt } from "../utils/search-txt.js";
+import { seedPhoto } from "./_helpers/media.js";
+import { withFinalSale } from "./_helpers/final-sale-fixtures.js";
 const _rawproductsPrizeDrawsSeedData = [
     {
         id: "prizedraw-beyblade-mystery-box",

package/dist/seed/products-standard-seed-data.js

@@ -22,10 +22,10 @@
  * @tag consumers:seed/index.ts,seed/runner.ts
  * @tag sideEffects:none
  */
-import { PRODUCT_FIELDS } from "../constants/field-names";
-import { buildSearchTxt } from "../utils/search-txt";
-import { seedPhoto } from "./_helpers/media";
-import { withFinalSale } from "./_helpers/final-sale-fixtures";
+import { PRODUCT_FIELDS } from "../constants/field-names.js";
+import { buildSearchTxt } from "../utils/search-txt.js";
+import { seedPhoto } from "./_helpers/media.js";
+import { withFinalSale } from "./_helpers/final-sale-fixtures.js";
 /*
  * Real Beyblade attributes per fixture — Root Cause #6 (standard was the
  * "richest" seed file by fixture count but never exercised customFields/
@@ -656,6 +656,58 @@ const _rawProductsStandardSeedData = [
         createdAt: new Date("2026-08-24"),
         updatedAt: new Date("2026-08-24"),
     },
+    /*
+     * B6 — THE ONLY 18% GST ROW IN THE CATALOGUE.
+     *
+     * 🛑 `tax-hsn-95030010` (electronic toys, 18%) has existed as a `taxCodes`
+     * row since B3 with nothing referencing it, so the 18% arm of
+     * `calculateGst`, `gstByRate` (C0c defect 4), the per-rate invoice table and
+     * the blended-rate payout all had NO DATA that could exercise them. Four
+     * code paths that cannot be wrong because nothing reaches them.
+     *
+     * A BeyPointer is a battery-powered scoring device, which is what 9503 0010
+     * covers — so this is a genuinely electronic good rather than a flag planted
+     * on a convenient row.
+     *
+     * 🛑 No `gstRate`/`hsnCode` HERE, deliberately. They derive from
+     * `category-accessory-counters` through `deriveTaxonomy`, which is the path
+     * that will carry them in production. Hand-writing 18 would satisfy step 1 of
+     * the resolution order and leave the DERIVATION untested — a fixture that
+     * passes while the mechanism it exists to prove is never run, which is the
+     * shape of Root Cause #101.
+     *
+     * It is also what makes a MIXED-RATE cart possible for the first time: this
+     * row at 18% beside any bey at 5% is the one case C0c's §13 check 6b asks for
+     * and the catalogue could not previously express.
+     */
+    {
+        id: "product-beypointer-digital-battle-counter",
+        slug: "product-beypointer-digital-battle-counter",
+        barcodeId: "LIR-BEY-ACC-018",
+        title: "BeyPointer Digital Battle Counter",
+        description: "Battery-powered digital battle counter used for tournament scoring — tracks points across a best-of series, with a reset and a hold. Takes two AAA cells (not included). An electronic accessory, so it is taxed at the 18% electronic-toy rate rather than the 5% that applies to tops and parts.",
+        categorySlugs: ["category-accessory-counters", "category-accessories", "category-spinning-tops"],
+        categoryNames: ["Counters & BeyPointers", "Accessories", "Spinning Tops"],
+        brandSlug: "brand-takara-tomy",
+        brand: "Takara-Tomy",
+        price: 1299,
+        currency: "INR",
+        stockQuantity: 6,
+        availableQuantity: 6,
+        isSold: false,
+        mainImage: seedPhoto("product-image-beypointer-digital-battle-counter-1-20261012", 900, 900),
+        images: [
+            seedPhoto("product-image-beypointer-digital-battle-counter-1-20261012", 900, 900),
+            seedPhoto("product-image-beypointer-digital-battle-counter-2-20261012", 900, 900),
+        ],
+        status: PRODUCT_FIELDS.STATUS_VALUES.PUBLISHED,
+        condition: PRODUCT_FIELDS.CONDITION_VALUES.NEW,
+        tags: ["accessory"],
+        storeId: "store-beyblade-arena",
+        storeName: "Beyblade Arena",
+        createdAt: new Date("2026-10-12"),
+        updatedAt: new Date("2026-10-12"),
+    },
 ];
 export const productsStandardSeedData = [
     ..._rawProductsStandardSeedData.map((p) => withTokens({

package/dist/seed/products-stickers-seed-data.js

@@ -16,10 +16,10 @@
  * @tag consumers:seed/index.ts,seed/runner.ts
  * @tag sideEffects:none
  */
-import { PRODUCT_FIELDS } from "../constants/field-names";
-import { buildSearchTxt } from "../utils/search-txt";
-import { seedPhoto } from "./_helpers/media";
-import { withFinalSale } from "./_helpers/final-sale-fixtures";
+import { PRODUCT_FIELDS } from "../constants/field-names.js";
+import { buildSearchTxt } from "../utils/search-txt.js";
+import { seedPhoto } from "./_helpers/media.js";
+import { withFinalSale } from "./_helpers/final-sale-fixtures.js";
 const _rawProductsStickersSeedData = [
     {
         id: "stickers-beyblade-original-classic-sheet",

package/dist/seed/reviews-seed-data.js

@@ -14,8 +14,8 @@
  * @tag consumers:seed/index.ts,seed/runner.ts
  * @tag sideEffects:none
  */
-import { withReviewSearchTxt } from "./_helpers/search-txt-wrappers";
-import { seedPhoto } from "./_helpers/media";
+import { withReviewSearchTxt } from "./_helpers/search-txt-wrappers.js";
+import { seedPhoto } from "./_helpers/media.js";
 const NOW = new Date();
 const daysAgo = (n) => new Date(NOW.getTime() - n * 86400000);
 // Public, direct-playable sample MP4 — review.video.url renders through a raw

package/dist/seed/runner.js

@@ -1,5 +1,5 @@
-import { SeedAbortedError } from "./types";
-import { encryptPiiFields } from "../security/pii-encrypt";
+import { SeedAbortedError } from "./types.js";
+import { encryptPiiFields } from "../security/pii-encrypt.js";
 const BATCH_SIZE = 400; // Firestore max batch is 500
 const DEFAULT_MAX_ATTEMPTS = 2;
 /**

package/dist/seed/scammers-seed-data.js

@@ -17,9 +17,9 @@
  * @tag consumers:seed/index.ts,seed/runner.ts
  * @tag sideEffects:none
  */
-import { withScammerSearchTxt } from "./_helpers/search-txt-wrappers";
-import { SCAMMER_FIELDS } from "../constants/field-names";
-import { seedPhoto } from "./_helpers/media";
+import { withScammerSearchTxt } from "./_helpers/search-txt-wrappers.js";
+import { SCAMMER_FIELDS } from "../constants/field-names.js";
+import { seedPhoto } from "./_helpers/media.js";
 const NOW = new Date("2026-05-10T00:00:00.000Z");
 const daysAgo = (n) => new Date(NOW.getTime() - n * 86400000);
 /**

package/dist/seed/seed-market-config.js

@@ -1,8 +1,8 @@
 // appkit/src/seed/seed-market-config.ts
 // Locale-specific data pools for seed factories and fixtures.
 // Default pools match current letitrip.in baseline (Indian market).
-import { normalizeError } from "../errors/normalize";
-import { getMarketProfile, getDefaultCurrency, getDefaultCurrencySymbol, getDefaultPhonePrefix, getDefaultCountry, } from "../core/baseline-resolver";
+import { normalizeError } from "../errors/normalize.js";
+import { getMarketProfile, getDefaultCurrency, getDefaultCurrencySymbol, getDefaultPhonePrefix, getDefaultCountry, } from "../core/baseline-resolver.js";
 // ---------------------------------------------------------------------------
 // Re-export baseline accessors for convenience within seed layer
 // ---------------------------------------------------------------------------

package/dist/seed/seed-purpose.d.ts

@@ -0,0 +1,299 @@
+/**
+ * ── Seed provenance: may a purge delete this row? ───────────────────────────
+ *
+ * Every document written by `appkit-seed` carries a `seedPurpose`, and it is
+ * the ONE declaration of whether a row is real content or clearable test data.
+ * The purge reads it; nothing else decides.
+ *
+ * ## The rule this exists to enforce
+ *
+ * 🛑 **Content comes from a seed FILE, never from a direct database write.**
+ * Not a one-off script, not a console paste, not a `node -e`. A row that exists
+ * only in Firestore cannot be reviewed in a diff, cannot be recreated after a
+ * purge, and cannot be found by anyone who did not watch it being written —
+ * and when it references other rows, nothing updates it when those move.
+ *
+ * `seedPurpose` makes that rule *checkable*: a document with no `seedPurpose`
+ * was not written by the seeder, so the purge will not touch it.
+ *
+ * ## 🛑 THE DEFAULT IS `test`, AND THE OPPOSITE WAS THIS FILE'S FIRST BUG
+ *
+ * The first version of this file defaulted every collection to `permanent`,
+ * reasoning that the dangerous direction is deleting something unrecoverable.
+ * **That reasoning was wrong here, and it made the purge a no-op.**
+ *
+ * This site has never gone live. There are no real customers, no real orders
+ * and no real payouts — every user, store, listing, auction, order, bid and
+ * review in the seed was added TO EXERCISE THE PLATFORM. Classifying them
+ * `permanent` means "cannot be cleared", which is precisely the opposite of
+ * why the field was asked for.
+ *
+ * So the default is `test`, and `permanent` is the **narrow** exception: the
+ * handful of collections that are genuinely content rather than scaffolding.
+ *
+ * ## 🛑 AND `isTestData` IS NOT DERIVED FROM THIS — that was the second bug
+ *
+ * The first version wrote `isTestData: true` for every `test` row. That would
+ * have **hidden the entire demo catalogue from the public**, because
+ * `hidePublicTestData` filters on exactly that field — 70 products, 416
+ * categories and every store would have vanished from every public page while
+ * the summary line read `created 2513, errors 0`.
+ *
+ * The two concerns are orthogonal and must stay separate:
+ *
+ * | Question | Field |
+ * |---|---|
+ * | May a purge delete this row? | **`seedPurpose`** (here) |
+ * | Should the public be able to SEE this row? | **`isTestData`** + `testDataExpiresAt` |
+ *
+ * A demo product is `test` (clearable) **and visible**. A tester-sandbox
+ * cross-store fixture is `test` **and hidden**. Those are different rows with
+ * different needs, and one field cannot answer both.
+ *
+ * `isTestData` therefore stays an explicit per-row opt-in, authored via
+ * `testDataExpiresAt()` in `./test-data-ttl.ts`, and this file never writes it.
+ *
+ * ## What it replaces
+ *
+ * Measured 2026-10-12, before this file existed: **47** seed data files, of
+ * which **one** carried any permanence marker; `isTestData` declared on **5**
+ * schemas; and `TEST_DATA_COLLECTIONS` listing **`offers`**, whose schema does
+ * not declare the field at all, so that entry could only ever match zero rows.
+ * `users`, `orders`, `faqs`, `reviews`, `bids`, `payouts` and `carts` had no
+ * marker and no purge path — and users and orders are the two that were named.
+ */
+/**
+ * Why a seeded row exists — i.e. what a purge is allowed to do with it.
+ *
+ * 🛑 Not a severity scale. Three different answers to one question: never,
+ * on request, and only on an explicit full purge.
+ */
+export type SeedPurpose = 
+/**
+ * Clearable test data. **The default**, and what almost everything is.
+ *
+ * Users, stores, listings, auctions, orders, bids, reviews, offers, carts,
+ * payouts — everything seeded to exercise a path rather than to be read as
+ * content. `appkit-seed purge` removes these and nothing else.
+ *
+ * 🛑 `test` says nothing about PUBLIC VISIBILITY. A demo product is `test`
+ * and fully visible; that is what makes the demo a demo. Hiding a row from
+ * the public is `isTestData`, which is a separate decision (see the header).
+ */
+"test"
+/**
+ * Real content. **A purge must NEVER remove it**, because re-creating it is
+ * not a re-seed, it is authoring.
+ *
+ * The test to apply: *if clearing this means somebody has to WRITE it again
+ * rather than re-run a loader, it is permanent.*
+ *
+ * That is why the **tester checklist cases** are in here and not in some
+ * harness tier — they are the real catalogue of issues the testers test
+ * against and keep updating, which is authored content that happens to be
+ * about testing. Its 1,162 cases are no more disposable than the 85 FAQs.
+ */
+ | "permanent";
+/**
+ * `Record<SeedPurpose, true>`, so a third value is a compile error in every map
+ * keyed on the union rather than a silent gap (Root Cause #61).
+ */
+export declare const SEED_PURPOSE_VALUES: Record<SeedPurpose, true>;
+export declare const ALL_SEED_PURPOSES: SeedPurpose[];
+export declare function isSeedPurpose(value: unknown): value is SeedPurpose;
+/**
+ * 🛑 There is deliberately NO third `fixture` tier.
+ *
+ * An earlier draft had one, meaning "clearable but only by an explicit full
+ * purge", intended for the tester checklist. Once the cases were correctly
+ * classified as permanent content it had **nothing in it** — and a union member
+ * with no members is the dead-enum-value shape this codebase keeps paying for:
+ * a filter chip whose value no row carries returns zero rows forever and reads
+ * as a working control (Root Cause #33), and nine section types that exist in a
+ * dropdown and have never rendered (F1 #20).
+ *
+ * Two values answer the question that was actually asked. If a genuine third
+ * case appears, add it then — with a row that needs it.
+ */
+export declare const PURGEABLE: Record<SeedPurpose, boolean>;
+/**
+ * The per-collection default, keyed on `COLLECTION_MAP`'s keys in
+ * `appkit/scripts/seed-cli.mjs`.
+ *
+ * 🛑 Typed `Record<string, SeedPurpose>` rather than a closed union of
+ * collection names, and that is a deliberate trade: the collection list lives
+ * in a `.mjs` script that cannot be imported for its types, so a closed union
+ * here would be a fifth hand-written copy of it — the thing this file exists to
+ * stop. `audit-seed-purpose` cross-checks the two sets instead, which catches
+ * both a missing entry and a dead one.
+ *
+ * **Anything absent defaults to `test`**, so a collection added later is
+ * clearable rather than quietly permanent. That is the right fail direction on
+ * a site with no real data: the cost of clearing something re-seedable is one
+ * command, and the cost of being unable to clear it is the state this replaced.
+ */
+export declare const SEED_COLLECTION_PURPOSE: Record<string, SeedPurpose>;
+/**
+ * Individual rows that differ from their collection's default, by document id.
+ *
+ * 🛑 This is the "clear all out EXCEPT our admin creds and the original single
+ * store" instruction, made declarative. Both collections default to `test` —
+ * every persona and every other store is disposable — and exactly two rows are
+ * not.
+ *
+ * ✅ The precedent already existed and this replaces it: `cmdDelete` has
+ * carried `PROTECTED_USER_UIDS = new Set(["user-admin-letitrip"])` for a long
+ * time, skipping that uid on a wholesale delete. One mechanism is better than a
+ * list the purge path happens to know about privately.
+ *
+ * 🛑 Keyed **`"<collection>:<id>"`**, and the collection half is load-bearing.
+ *
+ * It was a bare id, and a live read-back caught the consequence: `carts`,
+ * `wishlists` and `history` are all keyed on the USER id (CLAUDE.md: "Doc id =
+ * userId"), so `"user-admin-letitrip"` matched the admin's **cart** as well as
+ * the admin's user row — making a disposable cart permanently unpurgeable.
+ * Subtle, silent, and it would have left a stale cart surviving every purge
+ * forever.
+ *
+ * The id half is the DOCUMENT id, which for `users` is the Auth uid (`uid` on
+ * the seed row) and for everything else is `id`. `resolveSeedPurpose` checks
+ * both, because a seeded user row carries `uid` and no `id`.
+ */
+export declare const SEED_ROW_PURPOSE: Record<string, SeedPurpose>;
+/**
+ * Collections whose purpose FOLLOWS a referenced row rather than being declared.
+ *
+ * 🛑 This exists to hold one invariant: **a `permanent` row may not reference a
+ * `test` row**, because the purge would leave it behind as a dangling FK that
+ * still looks like real config.
+ *
+ * Measured in `store-extensions-seed-data.ts`: **14** rows reference
+ * `store-beyblade-arena` (test) and **9** reference `store-letitrip-official`
+ * (permanent). So marking `shippingConfigs` / `analyticsCards` permanent at the
+ * COLLECTION level — which the user's list implies and an earlier draft of the
+ * plan did — would strand 14 rows pointing at a store the purge deletes.
+ *
+ * Deriving is better than 23 hand-maintained per-row overrides for the usual
+ * reason: a hand-kept mirror drifts the moment a store is added (Root Cause
+ * #42), and a derivation is correct for stores that do not exist yet.
+ */
+export declare const SEED_PURPOSE_DERIVED_FROM: Record<string, {
+    readonly field: SeedReferenceField;
+    readonly collection: string;
+}>;
+/** A seeded row may override its collection's default inline. */
+export interface WithSeedPurpose {
+    seedPurpose?: SeedPurpose;
+}
+/**
+ * The fields `resolveSeedPurpose` reads off a row — all optional, because it is
+ * handed rows from 47 differently-shaped collections.
+ *
+ * 🛑 Declared explicitly rather than as `Record<string, unknown>`, which
+ * `audit-unknown-leakage` blocks and which is worse anyway: an index signature
+ * accepts ANY field name, so a typo in `SEED_PURPOSE_DERIVED_FROM.field` would
+ * read `undefined` and fall through to `test` silently — the exact mistake
+ * already made once, where `analyticsCards` was declared to derive from
+ * `storeId` and the rows carry `ownerId`.
+ *
+ * `SeedReferenceField` then constrains that `field` to one of these, so the
+ * same typo becomes a compile error.
+ */
+export interface SeedRowIdentity extends WithSeedPurpose {
+    /** Document id, on every collection except `users`. */
+    id?: string;
+    /** `users` seed rows carry the Auth uid and no `id`. */
+    uid?: string;
+    storeId?: string;
+    ownerId?: string;
+    userId?: string;
+    sellerId?: string;
+}
+/** The reference fields a derived collection may follow. */
+export type SeedReferenceField = "storeId" | "ownerId" | "userId" | "sellerId";
+/**
+ * Resolution order, most specific first:
+ *
+ *   1. the row's own inline `seedPurpose`
+ *   2. a per-row override in `SEED_ROW_PURPOSE`, by `id` or `uid`
+ *   3. for a DERIVED collection, the purpose of the row it references
+ *   4. the collection default
+ *   5. `test`
+ *
+ * 🛑 Step 3 is what holds the referential invariant. A `shippingConfig` for
+ * `store-letitrip-official` resolves `permanent`; one for
+ * `store-beyblade-arena` resolves `test` and is purged alongside the store it
+ * configures, rather than outliving it.
+ */
+export declare function resolveSeedPurpose(collection: string, row?: SeedRowIdentity | null, 
+/**
+ * The document id, when the caller has it and the row does not.
+ *
+ * 🛑 Required by `loadGeneric`, which does `let { id, ...data } = docData`
+ * and therefore hands this function a row with **no `id` at all**. Without
+ * this parameter the per-row overrides silently did not apply: measured,
+ * `store-letitrip-official` loaded as `test` — i.e. the platform's own store
+ * would have been purged, which is exactly the row the keep-list exists to
+ * protect. `loadUsers` was unaffected because `{ ...u }` keeps `uid`, which
+ * is why the admin override worked and the store one did not.
+ */
+docId?: string | null): SeedPurpose;
+export interface SeedPurposeFields {
+    seedPurpose: SeedPurpose;
+}
+/**
+ * The fields to write for a purpose — exactly one.
+ *
+ * 🛑 It does **not** touch `isTestData` or `testDataExpiresAt`, and that
+ * restraint is the whole correction described in the header: deriving
+ * `isTestData` from `test` would have hidden every seeded product, category and
+ * store from the public site while reporting a clean load.
+ *
+ * Kept as a function rather than inlined so there is one place to look when
+ * someone asks "what does a purpose actually write?", and so the next field
+ * (if one is ever justified) lands in one place.
+ */
+export declare function seedPurposeFields(purpose: SeedPurpose): SeedPurposeFields;
+/**
+ * Stamp a row for writing. The one function every loader calls, so the CLI and
+ * `runSeed` cannot disagree about what a purpose means — Root Cause #75's shape
+ * on the seed axis (a rule reachable by copy-paste gets copied, and the copy
+ * made before a branch was added never learns about it).
+ *
+ * Returns a NEW object; the seed arrays are module-level constants re-imported
+ * on every CLI invocation and must not be mutated.
+ */
+export declare function stampSeedPurpose<T extends WithSeedPurpose>(collection: string, row: T, 
+/** Pass this whenever the caller holds the id and the row does not — see
+ *  `resolveSeedPurpose`'s `docId` for why `loadGeneric` must. */
+docId?: string | null): T & SeedPurposeFields;
+/**
+ * Mark a whole array as something other than its collection default — the
+ * readable way to say "this file is permanent" (or "this file is fixtures")
+ * without repeating the field on every row.
+ *
+ * Sets the row-level override, so it beats the collection default and is
+ * visible at the call site.
+ */
+export declare function asSeedPurpose<T>(purpose: SeedPurpose, rows: readonly T[]): Array<T & WithSeedPurpose>;
+/**
+ * How long a `test` row survives before a purge may take it.
+ *
+ * 🛑 STOP-GAP, added 2026-10-12 to unbreak the build — NOT a design decision,
+ * and whoever owns `seedPurpose` should replace it with the real declaration.
+ *
+ * This file arrived with `src/seed/index.ts:247` and `src/index.ts:1935` ALREADY
+ * re-exporting `SEED_TEST_TTL_DAYS` from here while nothing declared it, so
+ * `tsc` failed with TS2305 and appkit did not compile at all — the half-finished
+ * public-surface rename of Root Cause #20, where the barrel landed without the
+ * definition. (The same commit also carried `sxdexport const` on line 149,
+ * i.e. stray keystrokes, which is the likelier reading of what happened here.)
+ *
+ * Aliased to the EXISTING value rather than given a fresh number: a retention
+ * window is a product decision and inventing one would have been worse than the
+ * compile error. `TEST_DATA_TTL_DAYS` is 7 and is what `testDataExpiresAt()`
+ * already stamps on every test row, so this is behaviour-preserving by
+ * construction — and when the two names are reconciled, there is exactly one
+ * number to change.
+ */
+export { TEST_DATA_TTL_DAYS as SEED_TEST_TTL_DAYS } from "./test-data-ttl";