@mohasinac/appkit 4.44.0 → 4.46.0

package/scripts/seed-cli.mjs

@@ -56,12 +56,19 @@ const BIN_ACTION_MAP = {
   "appkit-seed-status": "status",
 };
 const ACTION = BIN_ACTION_MAP[binName] ?? POSITIONAL[0];
-if (!["load", "delete", "status"].includes(ACTION)) {
+if (!["load", "delete", "status", "purge"].includes(ACTION)) {
   console.error("usage:");
-  console.error("  appkit-seed <load|delete|status> [flags]");
+  console.error("  appkit-seed <load|delete|status|purge> [flags]");
   console.error("  appkit-seed-add     [flags]   # alias for `appkit-seed load`");
   console.error("  appkit-seed-remove  [flags]   # alias for `appkit-seed delete`");
   console.error("");
+  console.error("  purge   delete every document whose seedPurpose is \"test\", and NOTHING else.");
+  console.error("          Unlike `delete`, which empties whole collections, this keeps real");
+  console.error("          content (faqs, categories, taxCodes, productFeatures, blogPosts,");
+  console.error("          carousels, homepageSections, siteSettings, the tester checklist) and");
+  console.error("          keeps the two keep-list rows: the admin account and store-letitrip-official.");
+  console.error("          Organic rows carry no seedPurpose at all and are unreachable by it.");
+  console.error("");
   console.error("flags: --collections a,b   --dry-run   --yes   --verbose   --service-account <path>");
   process.exit(2);
 }
@@ -196,6 +203,7 @@ const {
   wishlistsSeedData, historySeedData,
   groupedListingsSeedData,
   scammersSeedData, productFeaturesSeedData, taxCodesSeedData,
+  partGlossarySeedData, modelCompositionSeedData,
   testerChecklistSeedData, testerResponsesSeedData,
   supportTicketsSeedData, catalogueSeedData,
   shipmentsSeedData, shipmentLotsSeedData, shipmentItemsSeedData,
@@ -211,6 +219,8 @@ const {
   GROUPED_LISTINGS_COLLECTION, SCAMMER_COLLECTION,
   WISHLIST_COLLECTION, HISTORY_COLLECTION, PRODUCT_FEATURES_COLLECTION,
   TAX_CODES_COLLECTION,
+  PART_GLOSSARY_COLLECTION,
+  MODEL_COMPOSITION_COLLECTION,
   TESTER_CHECKLIST_ITEM_COLLECTION,
   TESTER_CHECKLIST_RESPONSE_COLLECTION,
   // PII field/index constants (plain data, still in the main barrel — the
@@ -220,6 +230,16 @@ const {
   REVIEW_PII_FIELDS, OFFER_PII_FIELDS, EVENT_ENTRY_PII_FIELDS,
   // misc
   generateFAQId,
+  /*
+   * Seed provenance. `stampSeedPurpose` is the ONE place a `seedPurpose` (and
+   * the `isTestData` / `testDataExpiresAt` derived from it) is produced, shared
+   * with `seed/runner.ts` so the two loaders cannot disagree about what a
+   * purpose means — Root Cause #75's shape on the seed axis.
+   */
+  stampSeedPurpose,
+  resolveSeedPurpose,
+  SEED_COLLECTION_PURPOSE,
+  ALL_SEED_PURPOSES,
 } = appkit;
 
 // ---------------------------------------------------------------------------
@@ -287,6 +307,9 @@ const COLLECTION_MAP = {
   scammerProfiles: SCAMMER_COLLECTION,
   productFeatures: PRODUCT_FEATURES_COLLECTION,
   taxCodes: TAX_CODES_COLLECTION,
+  // E4/D12 — extracted from the local corpus, generated into the seed.
+  partGlossary: PART_GLOSSARY_COLLECTION,
+  modelComposition: MODEL_COMPOSITION_COLLECTION,
   testerChecklistItems: TESTER_CHECKLIST_ITEM_COLLECTION,
   /*
    * Tester submissions. DERIVED tier in the tester's own map (wiped at setup so
@@ -301,6 +324,109 @@ const COLLECTION_MAP = {
   testerChecklistResponses: TESTER_CHECKLIST_RESPONSE_COLLECTION,
 };
 
+/*
+ * B6 — stamp `gstRate` + `hsnCode` onto every seeded product.
+ *
+ * 🛑 WITHOUT THIS, EVERY SEEDED PRODUCT IS TAXED AT ZERO, and the Tax row can
+ * never render no matter what the GSTIN says.
+ *
+ * The resolution order C0c settled lives in `ProductRepository.deriveTaxonomy`
+ * — product rate, else the CATEGORY's via `taxCodeId`, else a warned floor —
+ * and it runs on a repository write. **The seed writes through
+ * `set(..., { merge: true })` and never touches the repository**, so no seeded
+ * row has ever carried a rate: measured 2026-10-12, `gstRate` was absent on
+ * all 70 live products. At checkout `sumGroupGst` reads `product.gstRate`
+ * directly with a `?? 0`, so the whole catalogue would have computed GST = 0
+ * with a valid GSTIN and `gstSettings.enabled: true`.
+ *
+ * That is the same class as Root Cause #101 (a schema that strips a field plus
+ * a read-side backfill equals a field no query can see) — here it is a
+ * write-side derivation the seed path does not run.
+ *
+ * 🛑 This is NOT a second implementation of the resolution. The product seed
+ * already hand-writes the FULL `categorySlugs` chain, so there is no walk to
+ * re-derive: take the chain, find the first element whose category declares a
+ * `taxCodeId`, and read the rate off the `taxCodes` seed. Nearest-first, which
+ * is the order `resolveCategoryDefaults` uses, so a more specific category
+ * still wins.
+ *
+ * 🛑 An explicit rate on a product WINS and is never overwritten — including
+ * `gstRate: 0`, which is a deliberate exemption and not an absence
+ * (`ProductDocument.gstRate`'s own JSDoc: "undefined and 0 MEAN DIFFERENT
+ * THINGS"). The test is `== null`, never falsy.
+ *
+ * 🛑 And it REFUSES rather than defaulting. A product whose chain resolves no
+ * tax code throws at load time: C0c defines reaching the floor as a triage
+ * signal, so a silent 5% here would hide exactly what it is meant to surface —
+ * and a wrong rate on a real invoice is worse than a failed load.
+ */
+function withDerivedCategoryFields(products) {
+  const catById = new Map((categoriesSeedData || []).map((c) => [String(c.id), c]));
+  const taxById = new Map((taxCodesSeedData || []).map((t) => [String(t.id), t]));
+  const unresolved = [];
+  const out = products.map((p) => {
+    // 🛑 Must NOT early-exit on tax alone now that authenticity rides along —
+    // a product with a hand-written rate would silently keep no authenticity.
+    if (p.gstRate != null && p.hsnCode && p.authenticity) return p;
+    const chain = Array.isArray(p.categorySlugs) && p.categorySlugs.length
+      ? p.categorySlugs
+      : (p.category ? [p.category] : []);
+    let code = null;
+    for (const id of chain) {
+      const c = catById.get(String(id));
+      const t = c?.productDefaults?.taxCodeId;
+      if (t) { code = t; break; }
+    }
+    const tax = code ? taxById.get(String(code)) : null;
+    if (!tax) { unresolved.push(`${p.id} (leaf ${chain[0] ?? "none"})`); return p; }
+
+    /*
+     * 🛑 AUTHENTICITY, the same gap one field over — and it was making a HERO
+     * CLAIM false.
+     *
+     * `productDefaults.defaultAuthenticity` is declared on 122 categories and
+     * `authenticity` was absent on **all 71 live products**, because it derives
+     * on a repository write and the seed does not make one. The homepage
+     * authenticity slide says "the seller has to pick one before it can go
+     * live" — which was untrue in two ways at once: the write schema has it
+     * `.optional()`, and not one product carried a value.
+     *
+     * `unverified` is the floor, never `original`: `ProductAuthenticity`'s own
+     * docstring says that without it "an honest seller who does not know would
+     * have to pick 'original', and silence would be indistinguishable from a
+     * genuine claim." The platform must not make an authenticity claim nobody
+     * checked.
+     *
+     * An explicit product value always wins, so the 6 categories that declare
+     * `original` still reach their products.
+     */
+    let authenticity = null;
+    for (const id of chain) {
+      const c = catById.get(String(id));
+      const a = c?.productDefaults?.defaultAuthenticity;
+      if (a) { authenticity = a; break; }
+    }
+
+    return {
+      ...p,
+      gstRate: p.gstRate != null ? p.gstRate : tax.gstRate,
+      // An exempt code has no HSN, and `hsnCode: ""` would read as a declared
+      // empty code rather than as an inapplicable one.
+      ...(p.hsnCode || !tax.hsnCode ? {} : { hsnCode: tax.hsnCode }),
+      ...(p.authenticity || !authenticity ? {} : { authenticity }),
+    };
+  });
+  if (unresolved.length) {
+    const detail = unresolved.slice(0, 10).join(", ");
+    throw new Error(
+      `seed: ${unresolved.length} product(s) resolve NO taxCodeId from their category chain, ` +
+        "so they would be taxed at zero. Give the category a taxCodeId " +
+        `(the roots carry a floor - see ROOT_TAX_DEFAULTS): ${detail}`,
+    );
+  }
+  return out;
+}
+
 const SEED_DATA_MAP = {
   users: usersSeedData,
   /*
@@ -326,7 +452,7 @@ const SEED_DATA_MAP = {
   // standalone brands collection/seed exists anymore.
   categories: categoriesSeedData,
   stores: storesSeedData,
-  products: [
+  products: withDerivedCategoryFields([
     ...(productsStandardSeedData || []), ...(productsAuctionsSeedData || []), ...(productsPreordersSeedData || []),
     ...(productsPrizeDrawsSeedData || []), ...(productsClassifiedsSeedData || []), ...(productsDigitalCodesSeedData || []), ...(productsLiveItemsSeedData || []),
     // art + stickers were written, exported from the seed barrel, and then never
@@ -334,7 +460,7 @@ const SEED_DATA_MAP = {
     // /stickers were permanently empty, and listingType=art|stickers returned 0.
     // Root Cause #58's family one layer down: added everywhere except the runner.
     ...(productsArtSeedData || []), ...(productsStickersSeedData || []),
-  ],
+  ]),
   orders: ordersSeedData,
   reviews: reviewsSeedData,
   bids: bidsSeedData,
@@ -373,6 +499,8 @@ const SEED_DATA_MAP = {
   scammerProfiles: scammersSeedData,
   productFeatures: productFeaturesSeedData,
   taxCodes: taxCodesSeedData,
+  partGlossary: partGlossarySeedData,
+  modelComposition: modelCompositionSeedData,
   testerChecklistItems: testerChecklistSeedData,
   testerChecklistResponses: testerResponsesSeedData,
 };
@@ -578,7 +706,22 @@ async function loadUsers(seed, stats) {
       // The previous form relied on ordering alone (indices first, THEN
       // encrypt) — correct, but one line-swap away from spreading plaintext
       // back over ciphertext, which is why `addPiiIndices` no longer exists.
-      const plain = stripUndefined({ ...u });
+      /*
+       * 🛑 Provenance is stamped here too, and `users` is the collection the
+       * whole scheme exists for.
+       *
+       * It had no permanence marker of any kind, so a seeded persona could not
+       * be told apart from a real signup — and a seeded user is the most
+       * expensive thing to delete wrongly: it owns an **Auth record**, a
+       * `userSlugs` index entry, addresses, a cart, orders, bids and reviews,
+       * and `users` sits in the tester harness's PRESERVE tier precisely
+       * because a wrong sweep there is the only permanent damage a run can do.
+       *
+       * Stamped before the PII pass so `plain` carries it: the indices are
+       * hashed from plaintext and the encryption must not see a hashed value,
+       * so nothing may be added to `docData` after that pair runs.
+       */
+      const plain = stripUndefined(stampSeedPurpose("users", { ...u }));
       let docData = {
         ...encryptPiiFields(plain, [...USER_PII_FIELDS]),
         ...piiIndicesFor(plain, USER_PII_INDEX_MAP),
@@ -603,7 +746,15 @@ async function loadSubcollection(seed, parentColl, parentKey, subColl, idKey, pi
       if (!parent || !id) { stats.errors++; continue; }
       const { [parentKey]: _p, [idKey]: _i, ...data } = d;
       const docRef = db.collection(parentColl).doc(parent).collection(subColl).doc(id);
-      const payload = piiFields ? encryptPiiFields(stripUndefined(data), [...piiFields]) : stripUndefined(data);
+      /*
+       * Subcollection rows inherit the SUBCOLLECTION's purpose, not the
+       * parent's — `subColl` is the key in `SEED_COLLECTION_PURPOSE`. A
+       * `couponUsage` row under a permanent user is still its own record, and
+       * conflating the two would make a parent's classification silently
+       * govern children it knows nothing about.
+       */
+      const stamped = stripUndefined(stampSeedPurpose(subColl, data));
+      const payload = piiFields ? encryptPiiFields(stamped, [...piiFields]) : stamped;
       await docRef.set(payload, { merge: true });
       stats.created++;
     } catch (err) { console.error(`    ✗ ${err.message}`); stats.errors++; }
@@ -615,8 +766,25 @@ async function loadOneDocPerUser(seed, coll, stats) {
     try {
       const { id, userId, items, updatedAt } = d;
       if (!id || !userId) { stats.errors++; continue; }
+      /*
+       * 🛑 `merge: false` — this loader REPLACES the document, which is correct
+       * for a wishlist or a history list (the array IS the record), and is
+       * exactly why the stamp has to be inside the payload rather than added
+       * by a later merge-write that would be wiped on the next load.
+       *
+       * `coll` is the real Firestore collection name here rather than the seed
+       * key, and for `wishlists`/`history` the two are identical — the only two
+       * callers. `resolveSeedPurpose` falls back to `permanent` if that ever
+       * stops being true, which is the safe direction.
+       */
       await db.collection(coll).doc(id).set(
-        stripUndefined({ userId, items: items ?? [], updatedAt: updatedAt ?? new Date() }),
+        stripUndefined(
+          stampSeedPurpose(coll, {
+            userId,
+            items: items ?? [],
+            updatedAt: updatedAt ?? new Date(),
+          }),
+        ),
         { merge: false },
       );
       stats.created++;
@@ -646,17 +814,135 @@ async function loadGeneric(colName, seed, firestoreCollection, stats) {
     if (!data.slug) data.slug = docData.slug ?? docId;
     items.push({
       ref: db.collection(firestoreCollection).doc(docId),
-      data: encryptSeedPii(colName, stripUndefined(data)),
+      /*
+       * 🛑 Stamp provenance BEFORE `stripUndefined`, not after.
+       *
+       * `seedPurposeFields` deliberately OMITS `isTestData` for a `permanent`
+       * row rather than writing `false` — so stamping afterwards would be
+       * indistinguishable from not stamping, and stripping afterwards is what
+       * keeps the absence genuine instead of writing `undefined` keys.
+       *
+       * One call, one choke point: every one of the ~2,500 documents this
+       * loader writes gets a `seedPurpose`, so the purge is a query rather than
+       * a heuristic, and `users`/`orders` are reachable by it for the first
+       * time.
+       */
+      /*
+       * 🛑 `docId` is passed EXPLICITLY because this loader destructures `id`
+       * out (`let { id, ...data } = docData`), so the row it hands over has no
+       * id for the per-row overrides to match on. Measured without it:
+       * `store-letitrip-official` loaded as `test` — the platform's own store,
+       * which is one of exactly two rows the keep-list exists to protect.
+       */
+      data: encryptSeedPii(colName, stripUndefined(stampSeedPurpose(colName, data, docId))),
     });
   }
-  const BATCH = 500;
-  for (let i = 0; i < items.length; i += BATCH) {
-    const chunk = items.slice(i, i + BATCH);
+  /*
+   * 🛑 Chunk by INDEX ENTRIES, not just by operation count.
+   *
+   * This loop capped at 500 operations and nothing else. That was invisible for
+   * years because every seeded collection had small documents; B5's 416
+   * categories are the first that do not. Measured 2026-10-11: one 416-op
+   * commit failed with `INVALID_ARGUMENT: Transaction too big` and wrote
+   * **0 of 416** — not a partial load, nothing at all.
+   *
+   * 🛑 The failure mode is what makes this worth a real fix rather than a
+   * retry: `✓ Load complete — created 2097, errors 1` reads as a near-complete
+   * run, and the ONE missing collection was the taxonomy that every product's
+   * `categorySlugs` chain points into. A purge-then-load left 70 products
+   * referencing ids that did not exist, with a cheerful summary line.
+   *
+   * ## What actually binds, measured by bisection rather than assumed
+   *
+   * My first fix capped PAYLOAD BYTES, on the theory that these documents are
+   * large. They are not: 416 categories are **1.51 MiB total**, mean 3.7 KiB,
+   * largest 7.9 KiB — nowhere near the 10 MiB request limit, and the byte cap
+   * never once triggered. The commit failed anyway.
+   *
+   * Bisecting the op count found the real boundary, and counting array elements
+   * explains it exactly:
+   *
+   *     416 ops -> 60,787 array elements -> FAILS
+   *     250 ops -> 42,912               -> FAILS
+   *     100 ops -> 17,578               -> works
+   *      50 ops ->  8,791               -> works
+   *
+   * The threshold sits right at **40,000**, which is Firestore's documented
+   * maximum index entries — applied per COMMIT here, not per document. Every
+   * element of an indexed array is an index entry, and a category carries ~146
+   * of them (`searchTxt` alone is ~150 tokens, plus `parentIds`, `ancestors`,
+   * `categoryNames`, `faqs`, `highlights`, `descriptionTemplates`).
+   *
+   * So the cap is on array elements at **20,000** — half the real limit, the
+   * same margin the byte cap keeps — and it is kept alongside the op and byte
+   * caps rather than replacing them, because all three are real Firestore
+   * limits and only one of them has bitten so far.
+   *
+   * 🛑 Do NOT "simplify" this back to a lower fixed op count. 100 would work
+   * for categories and silently triple the commit count for `faqs` and the
+   * 1,337 tester checklist items, which carry almost no arrays. The cap has to
+   * key on the thing that varies.
+   */
+  const MAX_OPS = Number(process.env.SEED_BATCH_OPS ?? 500);
+  const MAX_BYTES = 4 * 1024 * 1024;
+  const MAX_INDEX_ENTRIES = Number(process.env.SEED_BATCH_INDEX_ENTRIES ?? 20_000);
+
+  /** Array elements, recursively — a proxy for index entries written. */
+  const countArrayElements = (v) => {
+    if (Array.isArray(v)) return v.length + v.reduce((s, x) => s + countArrayElements(x), 0);
+    if (v && typeof v === "object" && !(v instanceof Date)) {
+      return Object.values(v).reduce((s, x) => s + countArrayElements(x), 0);
+    }
+    return 0;
+  };
+
+  let chunk = [];
+  let chunkBytes = 0;
+  let chunkEntries = 0;
+  const flush = async () => {
+    if (chunk.length === 0) return;
     const batch = db.batch();
     for (const { ref, data } of chunk) batch.set(ref, data, { merge: true });
     await batch.commit();
     stats.created += chunk.length;
+    chunk = [];
+    chunkBytes = 0;
+    chunkEntries = 0;
+  };
+
+  for (const item of items) {
+    let size = 0;
+    try {
+      size = Buffer.byteLength(JSON.stringify(item.data), "utf8");
+    } catch {
+      /*
+       * A payload that cannot be serialised cannot be measured. Treat it as a
+       * whole chunk's worth rather than as zero — guessing small is how a
+       * commit silently grows past a limit again, and a document that resists
+       * measurement is the one most likely to be large.
+       */
+      size = MAX_BYTES;
+    }
+    const entries = countArrayElements(item.data);
+    /*
+     * A single document over any cap still has to be written, and alone: a
+     * one-document commit is the smallest thing committable, so if Firestore
+     * rejects THAT the document itself is the problem and the error says so,
+     * rather than the failure being absorbed into a chunking bug.
+     */
+    if (
+      chunk.length > 0 &&
+      (chunk.length >= MAX_OPS ||
+        chunkBytes + size > MAX_BYTES ||
+        chunkEntries + entries > MAX_INDEX_ENTRIES)
+    ) {
+      await flush();
+    }
+    chunk.push(item);
+    chunkBytes += size;
+    chunkEntries += entries;
   }
+  await flush();
 }
 
 // ---------------------------------------------------------------------------
@@ -685,7 +971,10 @@ async function cmdLoad() {
           try {
             const { id, ownerType, ownerId, ...data } = d;
             if (!id || !ownerType || !ownerId) { stats.errors++; continue; }
-            const payload = encryptPiiFields(stripUndefined({ ownerType, ownerId, ...data }), [...ADDRESS_PII_FIELDS]);
+            const payload = encryptPiiFields(
+              stripUndefined(stampSeedPurpose("addresses", { ownerType, ownerId, ...data }, id)),
+              [...ADDRESS_PII_FIELDS],
+            );
             await db.collection("addresses").doc(id).set(payload, { merge: true });
             stats.created++;
           } catch (err) { console.error(`    ✗ ${err.message}`); stats.errors++; }
@@ -699,8 +988,17 @@ async function cmdLoad() {
           try {
             const { id, storeSlug, ...data } = d;
             if (!id || !storeSlug) { stats.errors++; continue; }
+            /*
+             * Stamped under the SEED KEY `storeAddresses`, not the target
+             * collection `addresses`. Both resolve `test`, so nothing differs
+             * today — but the purpose table is keyed on the seed key, and
+             * stamping under the write target would make the two disagree the
+             * day one of them changes.
+             */
             const payload = encryptPiiFields(
-              stripUndefined({ ownerType: "store", ownerId: storeSlug, ...data }),
+              stripUndefined(
+                stampSeedPurpose("storeAddresses", { ownerType: "store", ownerId: storeSlug, ...data }, id),
+              ),
               [...ADDRESS_PII_FIELDS],
             );
             await db.collection("addresses").doc(id).set(payload, { merge: true });
@@ -714,7 +1012,10 @@ async function cmdLoad() {
             const { userId, couponId, ...data } = d;
             if (!userId || !couponId) { stats.errors++; continue; }
             await db.collection(USER_COLLECTION).doc(userId).collection("couponUsage").doc(couponId)
-              .set(stripUndefined({ couponId, ...data }), { merge: true });
+              .set(
+                stripUndefined(stampSeedPurpose("couponUsage", { couponId, ...data }, couponId)),
+                { merge: true },
+              );
             stats.created++;
           } catch (err) { console.error(`    ✗ ${err.message}`); stats.errors++; }
         }
@@ -725,7 +1026,8 @@ async function cmdLoad() {
       } else if (colName === "siteSettings") {
         const settings = seed[0];
         if (settings) {
-          await db.collection(SITE_SETTINGS_COLLECTION).doc("global").set(stripUndefined(settings), { merge: true });
+          await db.collection(SITE_SETTINGS_COLLECTION).doc("global").set(
+          stripUndefined(stampSeedPurpose("siteSettings", settings, "global")), { merge: true });
           stats.created++;
         }
       } else {
@@ -821,11 +1123,146 @@ async function cmdDryRun(intendedAction) {
 
 // ---------------------------------------------------------------------------
 // Main
+/**
+ * `appkit-seed purge` — delete every `seedPurpose: "test"` document and NOTHING
+ * else.
+ *
+ * ## Why this is not `delete`
+ *
+ * `delete` empties whole COLLECTIONS. That is the right tool for a full reset
+ * and the wrong one for "clear the test data": it would take the 85 authored
+ * FAQs, the 416-node taxonomy every product's `categorySlugs` chain points
+ * into, the real HSN tax codes, the 1,337 tester cases and the AES-encrypted
+ * site credentials with it.
+ *
+ * This is a QUERY over a declaration — `where("seedPurpose","==","test")` —
+ * which gives four properties no heuristic can:
+ *
+ *   1. **A row the seeder never wrote is unreachable.** Organic documents (a
+ *      real buyer's cart, a runtime notification, a real signup) carry no
+ *      `seedPurpose` at all, so an equality on it cannot match them. Measured
+ *      live: 64 of 84 users are organic. That is the single most important
+ *      safety property here, and it comes from the field's ABSENCE rather than
+ *      from a list someone has to maintain.
+ *   2. **The keep-list is data, not code.** `store-letitrip-official` and
+ *      `user-admin-letitrip` resolve `permanent`, so the same query skips them.
+ *      This replaces `cmdDelete`'s private `PROTECTED_USER_UIDS` set.
+ *   3. **No composite index.** A single-field equality is served by Firestore's
+ *      automatic index, so this adds nothing to `firestore.indexes.json` — the
+ *      gap that left `priceIndex` queryless.
+ *   4. **The cascade is mostly automatic.** Orders, bids, reviews, offers,
+ *      carts, payouts and notifications are all `test`, so a purged product's
+ *      dependents go in the same pass rather than needing a reference walk.
+ *
+ * 🛑 **Auth is a SECOND delete and `delete`/`purge` are the only places that
+ * know it.** A Firestore user row and its Firebase Auth record are two objects;
+ * removing the row and leaving the login is the worst of the three outcomes,
+ * because the account then looks absent and can still authenticate.
+ *
+ * 🛑 **What it deliberately does NOT do**: delete organic rows that reference a
+ * purged one. An organic notification pointing at a purged test order becomes a
+ * dangling reference — and it is a real person's record, so it is REPORTED
+ * rather than removed. Guessing in the destructive direction on someone's own
+ * data is not a trade this command gets to make.
+ */
+async function cmdPurge() {
+  const targets = collectionsToProcess;
+
+  /* Subcollections are not reachable by a top-level query, so they are walked
+   * explicitly. `couponUsage` lives at `users/{uid}/couponUsage`. */
+  const SUBCOLLECTIONS = [{ key: "couponUsage", parent: USER_COLLECTION, name: "couponUsage" }];
+
+  const plan = [];
+  for (const colName of targets) {
+    const path = COLLECTION_MAP[colName];
+    if (!path) continue;
+    const sub = SUBCOLLECTIONS.find((s) => s.key === colName);
+    try {
+      if (sub) {
+        /* A collection-group query reaches every parent at once. */
+        const snap = await db.collectionGroup(sub.name).where("seedPurpose", "==", "test").get();
+        if (snap.size > 0) plan.push({ colName, docs: snap.docs, isSub: true });
+      } else {
+        const snap = await db.collection(path).where("seedPurpose", "==", "test").get();
+        if (snap.size > 0) plan.push({ colName, docs: snap.docs, isSub: false });
+      }
+    } catch (err) {
+      console.error(`✗ ${colName}: ${err.message}`);
+    }
+  }
+
+  const total = plan.reduce((n, p) => n + p.docs.length, 0);
+  console.log(`\n${"collection".padEnd(26)} ${"purge".padStart(6)}`);
+  console.log("─".repeat(36));
+  for (const p of plan) {
+    console.log(`  ${p.colName.padEnd(24)} ${String(p.docs.length).padStart(6)}`);
+  }
+  console.log("─".repeat(36));
+  console.log(`  ${"TOTAL".padEnd(24)} ${String(total).padStart(6)}\n`);
+
+  if (total === 0) {
+    console.log("Nothing to purge — no document carries seedPurpose \"test\".");
+    return;
+  }
+
+  if (DRY_RUN) {
+    console.log("--dry-run — nothing was deleted.");
+    return;
+  }
+
+  if (
+    !(await confirm(
+      `Delete ${total} test document(s) in project '${process.env.FIREBASE_ADMIN_PROJECT_ID}'? Permanent content and organic rows are untouched.`,
+    ))
+  ) {
+    console.log("Aborted.");
+    process.exit(0);
+  }
+
+  const stats = { deleted: 0, auth: 0, errors: 0 };
+  for (const p of plan) {
+    /*
+     * 🛑 `users` first deletes the AUTH record, then the Firestore row — in that
+     * order, because the reverse can leave an authenticating account whose
+     * profile is gone, and this loop is the only thing that knows both exist.
+     */
+    if (p.colName === "users") {
+      for (const d of p.docs) {
+        try {
+          await auth.deleteUser(d.id);
+          stats.auth++;
+        } catch (e) {
+          if (e?.code !== "auth/user-not-found") console.error(`    auth ${d.id}: ${e.message}`);
+        }
+      }
+    }
+    for (let i = 0; i < p.docs.length; i += 450) {
+      const chunk = p.docs.slice(i, i + 450);
+      const batch = db.batch();
+      for (const d of chunk) batch.delete(d.ref);
+      try {
+        await batch.commit();
+        stats.deleted += chunk.length;
+        if (VERBOSE) for (const d of chunk) console.log(`    - ${p.colName}/${d.id}`);
+      } catch (err) {
+        console.error(`✗ ${p.colName}: ${err.message}`);
+        stats.errors++;
+      }
+    }
+  }
+
+  console.log(
+    `\n${stats.errors === 0 ? "✓" : "✗"} Purge complete — deleted ${stats.deleted}, auth records ${stats.auth}, errors ${stats.errors}`,
+  );
+  if (stats.errors > 0) process.exit(1);
+}
+
 // ---------------------------------------------------------------------------
 try {
   if (ACTION === "status") await cmdStatus();
   else if (ACTION === "load") await cmdLoad();
   else if (ACTION === "delete") await cmdDelete();
+  else if (ACTION === "purge") await cmdPurge();
   process.exit(0);
 } catch (err) {
   console.error("✗ Fatal:", err.message);

package/dist/core/copilot-log.repository.d.ts

@@ -1,44 +0,0 @@
-import type { IRepository } from "../contracts";
-export type CopilotFeedback = "positive" | "negative";
-export interface CopilotLogDocument {
-    id: string;
-    userId: string;
-    userName: string;
-    conversationId: string;
-    prompt: string;
-    response: string;
-    model: string;
-    promptTokens?: number;
-    responseTokens?: number;
-    durationMs?: number;
-    feedback: CopilotFeedback | null;
-    createdAt: Date;
-    updatedAt?: Date;
-}
-export interface CopilotLogCreateInput {
-    userId: string;
-    userName: string;
-    conversationId: string;
-    prompt: string;
-    response: string;
-    model: string;
-    promptTokens?: number;
-    responseTokens?: number;
-    durationMs?: number;
-}
-export declare class CopilotLogRepository {
-    private _repo;
-    private readonly _collection;
-    constructor(repoOrCollection?: IRepository<CopilotLogDocument> | string | null);
-    private get repo();
-    create(input: CopilotLogCreateInput): Promise<CopilotLogDocument>;
-    findByConversation(conversationId: string, limit?: number): Promise<CopilotLogDocument[]>;
-    setFeedback(logId: string, feedback: CopilotFeedback): Promise<void>;
-}
-export declare const copilotLogRepository: CopilotLogRepository;
-export declare const COPILOT_LOGS_COLLECTION: "copilotLogs";
-export declare const COPILOT_LOGS_INDEXED_FIELDS: readonly ["userId", "conversationId", "createdAt"];
-export declare const copilotLogQueryHelpers: {
-    readonly byUser: (userId: string) => readonly ["userId", "==", string];
-    readonly byConversation: (conversationId: string) => readonly ["conversationId", "==", string];
-};