@mohasinac/appkit 4.45.0 → 4.47.0

package/dist/.build-stamp.json

@@ -1,8 +1,8 @@
 {
   "stampVersion": 1,
-  "version": "4.45.0",
-  "head": "e3dc5508a7fce3a3a34411ebc9f21fcd1742f070",
+  "version": "4.47.0",
+  "head": "f72c5f183b70c66b626c7809ffb1a4b0112e7cb1",
   "branch": "main",
-  "dirty": false,
-  "builtAt": "2026-10-12T01:23:27.586Z"
+  "dirty": true,
+  "builtAt": "2026-10-13T05:22:53.600Z"
 }

package/dist/_internal/server/features/categories/live-counts.d.ts

@@ -0,0 +1,41 @@
+/**
+ * G3b — read the live `categoryCounts` documents for a BOUNDED set of ids.
+ *
+ * 🛑 WHO THIS IS FOR, because it is not the category detail page.
+ * `CategoryDetailPageView` already computes its own tab counts live
+ * (`listing-tab-counts`), so its headline numbers were never stale. The stale
+ * readers are the ones that render MANY categories and therefore cannot query
+ * per category: the `/categories` grid, the homepage category tiles, the
+ * admin table, the tree, and the child chips on a category page. All five read
+ * `metrics.totalProductCount`, which only the nightly reconciler writes.
+ *
+ * 🛑 `db.getAll` — ONE round-trip for N ids, not N round-trips. That is what
+ * reconciles this with the plan's own warning that `CategoryDetailPageView` is
+ * already at Rule #6's ~3-sequential-round-trip ceiling and "a sidecar
+ * collection would add an eighth": the existing seven reads are a
+ * `Promise.all`, so an eighth PARALLEL read adds no latency. It does add N
+ * document reads of quota, bounded by the page size the caller already
+ * fetched.
+ *
+ * 🛑 A missing document is `undefined`, never 0. The caller must fall back to
+ * `metrics` — rendering a confident zero for a category whose counter has not
+ * been written yet is Root Cause #72's lesson (a count that is unknown must
+ * never be indistinguishable from a count of nothing), and it would make this
+ * change a regression on every category until its first mutation.
+ */
+export interface LiveCountsResult {
+    /** categoryId → the rolled-up total, when a counts document exists. */
+    total: Map<string, number>;
+    /** True when the id list was truncated, so the caller can stop claiming completeness. */
+    truncated: boolean;
+}
+export declare function getLiveCategoryCounts(db: {
+    collection(name: string): {
+        doc(id: string): unknown;
+    };
+    getAll(...refs: unknown[]): Promise<Array<{
+        exists: boolean;
+        id: string;
+        data(): unknown;
+    }>>;
+}, ids: readonly string[]): Promise<LiveCountsResult>;

package/dist/_internal/server/features/categories/live-counts.js

@@ -0,0 +1,72 @@
+/**
+ * G3b — read the live `categoryCounts` documents for a BOUNDED set of ids.
+ *
+ * 🛑 WHO THIS IS FOR, because it is not the category detail page.
+ * `CategoryDetailPageView` already computes its own tab counts live
+ * (`listing-tab-counts`), so its headline numbers were never stale. The stale
+ * readers are the ones that render MANY categories and therefore cannot query
+ * per category: the `/categories` grid, the homepage category tiles, the
+ * admin table, the tree, and the child chips on a category page. All five read
+ * `metrics.totalProductCount`, which only the nightly reconciler writes.
+ *
+ * 🛑 `db.getAll` — ONE round-trip for N ids, not N round-trips. That is what
+ * reconciles this with the plan's own warning that `CategoryDetailPageView` is
+ * already at Rule #6's ~3-sequential-round-trip ceiling and "a sidecar
+ * collection would add an eighth": the existing seven reads are a
+ * `Promise.all`, so an eighth PARALLEL read adds no latency. It does add N
+ * document reads of quota, bounded by the page size the caller already
+ * fetched.
+ *
+ * 🛑 A missing document is `undefined`, never 0. The caller must fall back to
+ * `metrics` — rendering a confident zero for a category whose counter has not
+ * been written yet is Root Cause #72's lesson (a count that is unknown must
+ * never be indistinguishable from a count of nothing), and it would make this
+ * change a regression on every category until its first mutation.
+ */
+import { normalizeError } from "../../../../errors/normalize.js";
+import { serverLogger } from "../../../../monitoring/server-logger.js";
+import { CATEGORY_COUNTS_COLLECTION, liveTotalFor, } from "../../../../features/categories/schemas/category-counts.js";
+/** Hard ceiling on one batch — `getAll` is a single RPC but not a free one. */
+const MAX_IDS = 200;
+export async function getLiveCategoryCounts(db, ids) {
+    const unique = Array.from(new Set(ids.filter(Boolean)));
+    const truncated = unique.length > MAX_IDS;
+    const take = truncated ? unique.slice(0, MAX_IDS) : unique;
+    const total = new Map();
+    if (take.length === 0)
+        return { total, truncated };
+    try {
+        const col = db.collection(CATEGORY_COUNTS_COLLECTION);
+        const snaps = await db.getAll(...take.map((id) => col.doc(id)));
+        for (const snap of snaps) {
+            if (!snap.exists)
+                continue;
+            const v = liveTotalFor(snap.data());
+            if (v !== undefined)
+                total.set(snap.id, v);
+        }
+    }
+    catch (err) {
+        // Typed FIRST, on the catch's own line, because `audit-catch-normalize`
+        // reads a short window after the clause and the explanation below is
+        // longer than it.
+        const e = normalizeError(err);
+        /*
+         * Fail OPEN with an empty map, so every caller falls back to `metrics` and
+         * renders exactly as it does today. A count is a display number: throwing
+         * here would take down a category page over a counter, which is the trade
+         * `.catch(() => null)` normally gets wrong — the difference is that here
+         * the fallback is a REAL alternative value, not an empty page.
+         *
+         * 🛑 But it is LOGGED, not swallowed. `void normalizeError(err)` as a
+         * catch's only statement is as silent as `catch {}` while looking handled,
+         * which is what `audit-silent-degrade` calls normalize theatre — and it
+         * caught exactly that here. Silent to the visitor, loud to the operator.
+         */
+        serverLogger.warn("categoryCounts batch read failed — falling back to metrics", {
+            ids: take.length,
+            error: e.message,
+        });
+    }
+    return { total, truncated };
+}

package/dist/_internal/server/features/checkout/expand-order-items.js

@@ -72,6 +72,19 @@ export function expandCartLineToOrderRows(item, representative, productById) {
                 ...(representative.categorySlugs?.[0]
                     ? { categorySlug: representative.categorySlugs[0] }
                     : {}),
+                /*
+                 * I8 — the category and brand DISPLAY NAMES, beside the slug.
+                 *
+                 * `categoryNames[0]` is the default leaf's name, parallel to
+                 * `categorySlugs[0]`. Snapshotted for the reason the slug alone is not
+                 * enough: a slug survives a rename, but a receipt has to show a NAME, and
+                 * re-resolving it at render time would let a renamed category change what
+                 * a past invoice says.
+                 */
+                ...(representative.categoryNames?.[0]
+                    ? { categoryName: representative.categoryNames[0] }
+                    : {}),
+                ...(representative.brand ? { brand: representative.brand } : {}),
                 ...(representative.listingType ? { listingType: representative.listingType } : {}),
                 ...(representative.condition ? { condition: representative.condition } : {}),
                 // Legacy collapsed bundle rows (no groupMembers) keep their old shape so
@@ -122,6 +135,10 @@ export function expandCartLineToOrderRows(item, representative, productById) {
              * been deleted, which is the whole reason that snapshot exists.
              */
             ...(product?.categorySlugs?.[0] ? { categorySlug: product.categorySlugs[0] } : {}),
+            // I8 - the same snapshot per member. `product` may be gone by order time,
+            // which is exactly why the member snapshot exists, so both are guarded.
+            ...(product?.categoryNames?.[0] ? { categoryName: product.categoryNames[0] } : {}),
+            ...(product?.brand ? { brand: product.brand } : {}),
             ...(product?.listingType ? { listingType: product.listingType } : {}),
             // Per MEMBER — a bundle can mix a sealed item with a loose one, and a
             // blended condition would describe neither.

package/dist/_internal/server/features/orders/adapters.js

@@ -66,6 +66,35 @@ export function orderDocumentToOrder(doc) {
             // only Item / Qty / Price (Root Cause #57).
             ...(item.hsnCode ? { hsnCode: item.hsnCode } : {}),
             ...(item.gstRate != null ? { gstRate: item.gstRate } : {}),
+            /*
+             * I8 — the TAXONOMY snapshot, which this adapter dropped.
+             *
+             * 🛑 Root Cause #57's exact shape, for the THIRD time in this one
+             * mapper: the fields exist on the document, are deliberately
+             * snapshotted at order time, and never reached any client. `finalSale`
+             * and the tax pair above were each added after the same discovery.
+             *
+             * `categorySlug` has carried a reason since C1 — *"a product
+             * re-categorised next year must not retroactively move last year's sale
+             * into a band it was never part of"* — and no order surface could read
+             * it. `categoryName` and `brand` are new, because a slug survives a
+             * rename and a NAME is what a receipt has to show: the whole point of
+             * snapshotting is that the record still reads correctly after the
+             * category or product it came from is renamed or deleted.
+             */
+            ...(item.categorySlug ? { categorySlug: item.categorySlug } : {}),
+            ...(item.categoryName ? { categoryName: item.categoryName } : {}),
+            ...(item.brand ? { brand: item.brand } : {}),
+            ...(item.condition ? { condition: item.condition } : {}),
+            /*
+             * The grouped-line keys. `groupOrderItemsByLine` collapses a bundle or
+             * grouped cart line for the receipt and keys on exactly these — so
+             * without them the client saw N separate rows where the buyer bought
+             * one thing.
+             */
+            ...(item.groupSlug ? { groupSlug: item.groupSlug } : {}),
+            ...(item.groupTitle ? { groupTitle: item.groupTitle } : {}),
+            ...(item.groupSource ? { groupSource: item.groupSource } : {}),
         }))
         : [
             {

package/dist/_internal/server/features/parts/assembly.d.ts

@@ -0,0 +1,126 @@
+/** One component the assembly consumes. */
+export interface AssemblyComponent {
+    slotKey: string;
+    /** A part LISTING's id — a `ProductDocument`, not a `partGlossary` row. */
+    productId: string;
+    quantity: number;
+}
+export interface AssembleInput {
+    /** The store doing the assembly. Parts are `storeId`-scoped like any listing. */
+    storeId: string;
+    /** The complete-bey listing being created or restocked. */
+    targetProductId: string;
+    components: readonly AssemblyComponent[];
+    /** How many complete beys to build. */
+    units?: number;
+}
+export interface AssemblyResult {
+    targetProductId: string;
+    unitsBuilt: number;
+    /** Per component: what it had available, and what it has now. */
+    consumed: Array<{
+        productId: string;
+        before: number;
+        after: number;
+        taken: number;
+    }>;
+}
+/** The hard cap, matching the write schema's `.max(8)` on `assembledFrom`. */
+export declare const MAX_ASSEMBLY_COMPONENTS = 8;
+/**
+ * 🛑 The fields read inside the transaction, named once.
+ *
+ * `availableQuantity` is the gate (see the header). `stockQuantity` is read
+ * only so the reservation can be CARRIED FORWARD rather than discarded —
+ * writing `availableQuantity` without adjusting `stockQuantity` by the same
+ * amount would make `reserved` drift by exactly the units consumed, and
+ * `resolveStockResync` would then hand those units back to the shelf on the
+ * seller's next edit. That is A4's bug arriving through a new door.
+ */
+interface StockSnapshot {
+    stockQuantity: number;
+    availableQuantity: number;
+    storeId?: string;
+}
+/** What a planner decided to write, before anything touches Firestore. */
+export interface StockWrite {
+    productId: string;
+    stockQuantity: number;
+    availableQuantity: number;
+}
+export interface AssemblyPlan {
+    writes: StockWrite[];
+    consumed: AssemblyResult["consumed"];
+    /** The complete-bey listing's own new figures. */
+    target: StockWrite;
+}
+/**
+ * The whole decision, as a PURE function of the documents and the request.
+ *
+ * 🛑 Extracted because the arithmetic is the part most likely to be wrong and
+ * the transaction is the part hardest to test. A fake Firestore cannot be
+ * injected across an ESM namespace boundary — measured: `Object.defineProperty`
+ * on the imported namespace throws, so a mock-based harness reported every
+ * ordering assertion as green having executed none of them. Rather than
+ * weaken the module with a test-only injection seam, the thing worth asserting
+ * moved OUT of the transaction: which field gates the build, how the
+ * reservation is carried, and what is refused.
+ *
+ * `direction` is `-1` for an assembly (components are consumed) and `+1` for a
+ * part-out (components are produced), so there is ONE implementation of the
+ * gate and the carry rather than two that must agree.
+ */
+export declare function planAssembly(args: {
+    storeId: string;
+    /** The complete bey: consumed on part-out, produced on assembly. */
+    subject: {
+        productId: string;
+        doc: StockSnapshot | undefined;
+    };
+    components: ReadonlyArray<{
+        request: AssemblyComponent;
+        doc: StockSnapshot | undefined;
+    }>;
+    units: number;
+    /** -1 consumes the components (assemble); +1 produces them (part out). */
+    direction: -1 | 1;
+}): AssemblyPlan;
+/**
+ * The input rules, shared by both directions so they cannot drift.
+ *
+ * Runs before any Firestore access, which is also why it is separable.
+ */
+export declare function assertAssemblyInput(components: readonly AssemblyComponent[], units: number): void;
+/**
+ * Build `units` copies of a complete bey, consuming its components.
+ *
+ * A thin shell over `planAssembly`: read everything, decide purely, write.
+ *
+ * Throws rather than partially succeeding —
+ * - `ValidationError` — malformed, missing, or another store's listing.
+ * - `ConflictError`   — a component does not have enough available. 409 and
+ *   not 400: the request is well formed and the seller is not confused, the
+ *   world changed under them, so the next action is to restock rather than to
+ *   fix a field. Same distinction as removing a booked lottery slot.
+ */
+export declare function assembleFromComponents(input: AssembleInput): Promise<AssemblyResult>;
+export interface PartOutInput {
+    storeId: string;
+    /** The complete bey being broken down. */
+    sourceProductId: string;
+    /** Which component listings receive the parts. */
+    components: readonly AssemblyComponent[];
+    units?: number;
+}
+/**
+ * The inverse: decrement the bey, increment each component.
+ *
+ * 🛑 Spares arrive as whole beys too, so this is not a convenience — it is half
+ * the workflow. Without it, "part out" would only work on beys this system
+ * built, which is none of the current catalogue (GAP-10).
+ *
+ * Same planner, `direction: 1`. ONE implementation of the gate and the
+ * reservation carry rather than two that must agree.
+ */
+export declare function partOutToComponents(input: PartOutInput): Promise<AssemblyResult>;
+export {};

package/dist/_internal/server/features/parts/assembly.js

@@ -0,0 +1,246 @@
+import { unitOfWork } from "../../../../core/unit-of-work.js";
+import { PRODUCT_COLLECTION } from "../../../../features/products/schemas/firestore.js";
+import { getAdminDb } from "../../../../providers/db-firebase/index.js";
+import { serverLogger } from "../../../../monitoring/server-logger.js";
+import { ValidationError, ConflictError } from "../../../../errors/index.js";
+/** The hard cap, matching the write schema's `.max(8)` on `assembledFrom`. */
+export const MAX_ASSEMBLY_COMPONENTS = 8;
+const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+/**
+ * The whole decision, as a PURE function of the documents and the request.
+ *
+ * 🛑 Extracted because the arithmetic is the part most likely to be wrong and
+ * the transaction is the part hardest to test. A fake Firestore cannot be
+ * injected across an ESM namespace boundary — measured: `Object.defineProperty`
+ * on the imported namespace throws, so a mock-based harness reported every
+ * ordering assertion as green having executed none of them. Rather than
+ * weaken the module with a test-only injection seam, the thing worth asserting
+ * moved OUT of the transaction: which field gates the build, how the
+ * reservation is carried, and what is refused.
+ *
+ * `direction` is `-1` for an assembly (components are consumed) and `+1` for a
+ * part-out (components are produced), so there is ONE implementation of the
+ * gate and the carry rather than two that must agree.
+ */
+export function planAssembly(args) {
+    const { storeId, subject, components, units, direction } = args;
+    if (!subject.doc) {
+        throw new ValidationError(direction === -1
+            ? "The listing being assembled no longer exists."
+            : "The listing being parted out no longer exists.");
+    }
+    if (subject.doc.storeId && subject.doc.storeId !== storeId) {
+        throw new ValidationError("That listing belongs to another store.");
+    }
+    /*
+     * 🛑 On a PART-OUT the subject is what gets consumed, so it needs the same
+     * availability gate as a component: a bey with 2 in stock and 1 reserved can
+     * only have ONE parted out. On an assembly the subject only ever gains, so
+     * there is nothing to check.
+     */
+    const subjectAvailable = num(subject.doc.availableQuantity);
+    if (direction === 1 && subjectAvailable < units) {
+        throw new ConflictError(`Not enough available to part out: needs ${units}, has ${subjectAvailable}.`);
+    }
+    const consumed = [];
+    const writes = [];
+    for (const { request, doc } of components) {
+        if (!doc) {
+            throw new ValidationError(direction === -1
+                ? `A component is missing: ${request.productId}`
+                : `A destination component is missing: ${request.productId}`);
+        }
+        /*
+         * 🛑 Scoped to the caller's own store. An admin assembling from a seller's
+         * bins would be writing another store's inventory; the only legitimate
+         * version is `store-letitrip-official` using its OWN stock, which this
+         * already allows.
+         */
+        if (doc.storeId && doc.storeId !== storeId) {
+            throw new ValidationError(`A component belongs to another store: ${request.productId}`);
+        }
+        const delta = request.quantity * units * direction;
+        const available = num(doc.availableQuantity);
+        // 🛑 THE GATE, and it reads `availableQuantity` — see the file header.
+        if (direction === -1 && available < -delta) {
+            // 409, not 400: the request is well formed and the world changed.
+            // Figures in `data`, words in the client — see the part-out branch above.
+            throw new ConflictError(`component insufficient: needs ${-delta}, has ${available}`, "ASSEMBLY_INSUFFICIENT", { kind: "component", productId: request.productId, needs: -delta, has: available });
+        }
+        consumed.push({
+            productId: request.productId,
+            before: available,
+            after: available + delta,
+            taken: -delta,
+        });
+        writes.push({
+            productId: request.productId,
+            // Both fields move by the SAME amount, so an outstanding reservation is
+            // carried forward exactly rather than handed back to the shelf.
+            stockQuantity: Math.max(0, num(doc.stockQuantity) + delta),
+            availableQuantity: available + delta,
+        });
+    }
+    const subjectDelta = units * -direction;
+    return {
+        writes,
+        consumed,
+        target: {
+            productId: subject.productId,
+            stockQuantity: Math.max(0, num(subject.doc.stockQuantity) + subjectDelta),
+            availableQuantity: subjectAvailable + subjectDelta,
+        },
+    };
+}
+/**
+ * The input rules, shared by both directions so they cannot drift.
+ *
+ * Runs before any Firestore access, which is also why it is separable.
+ */
+export function assertAssemblyInput(components, units) {
+    if (!Number.isInteger(units) || units < 1 || units > 99) {
+        throw new ValidationError("Quantity must be a whole number between 1 and 99.");
+    }
+    if (components.length === 0) {
+        throw new ValidationError("An assembly needs at least one component.");
+    }
+    if (components.length > MAX_ASSEMBLY_COMPONENTS) {
+        throw new ValidationError(`An assembly may involve at most ${MAX_ASSEMBLY_COMPONENTS} components.`);
+    }
+    /*
+     * 🛑 Two entries for one product id would each be planned against the SAME
+     * read value and each subtract from it, so the second would silently
+     * overdraw. Refused rather than summed: a caller sending a product twice is
+     * describing something it does not mean, and summing would decide for them.
+     */
+    const seen = new Set();
+    for (const c of components) {
+        if (seen.has(c.productId)) {
+            throw new ValidationError("The same component appears twice. Combine it into one row with the total quantity.");
+        }
+        seen.add(c.productId);
+    }
+}
+/**
+ * Build `units` copies of a complete bey, consuming its components.
+ *
+ * A thin shell over `planAssembly`: read everything, decide purely, write.
+ *
+ * Throws rather than partially succeeding —
+ * - `ValidationError` — malformed, missing, or another store's listing.
+ * - `ConflictError`   — a component does not have enough available. 409 and
+ *   not 400: the request is well formed and the seller is not confused, the
+ *   world changed under them, so the next action is to restock rather than to
+ *   fix a field. Same distinction as removing a booked lottery slot.
+ */
+export async function assembleFromComponents(input) {
+    const units = input.units ?? 1;
+    assertAssemblyInput(input.components, units);
+    const col = getAdminDb().collection(PRODUCT_COLLECTION);
+    return unitOfWork.runTransaction(async (tx) => {
+        // ── EVERY READ FIRST. Firestore requires it, and so does correctness. ──
+        const subjectRef = col.doc(input.targetProductId);
+        const componentRefs = input.components.map((c) => col.doc(c.productId));
+        const [subjectSnap, ...componentSnaps] = await tx.getAll(subjectRef, ...componentRefs);
+        const plan = planAssembly({
+            storeId: input.storeId,
+            subject: {
+                productId: input.targetProductId,
+                doc: subjectSnap.exists ? subjectSnap.data() : undefined,
+            },
+            components: input.components.map((request, i) => ({
+                request,
+                doc: componentSnaps[i].exists
+                    ? componentSnaps[i].data()
+                    : undefined,
+            })),
+            units,
+            direction: -1,
+        });
+        // ── WRITES ONLY AFTER EVERY READ ──────────────────────────────────────
+        const now = new Date();
+        for (const w of plan.writes) {
+            tx.update(col.doc(w.productId), {
+                stockQuantity: w.stockQuantity,
+                availableQuantity: w.availableQuantity,
+                updatedAt: now,
+            });
+        }
+        tx.update(subjectRef, {
+            stockQuantity: plan.target.stockQuantity,
+            availableQuantity: plan.target.availableQuantity,
+            assembledFrom: input.components.map((c) => ({ ...c })),
+            updatedAt: now,
+        });
+        serverLogger.info("assembleFromComponents", {
+            storeId: input.storeId,
+            targetProductId: input.targetProductId,
+            units,
+            components: plan.consumed.length,
+        });
+        return {
+            targetProductId: input.targetProductId,
+            unitsBuilt: units,
+            consumed: plan.consumed,
+        };
+    });
+}
+/**
+ * The inverse: decrement the bey, increment each component.
+ *
+ * 🛑 Spares arrive as whole beys too, so this is not a convenience — it is half
+ * the workflow. Without it, "part out" would only work on beys this system
+ * built, which is none of the current catalogue (GAP-10).
+ *
+ * Same planner, `direction: 1`. ONE implementation of the gate and the
+ * reservation carry rather than two that must agree.
+ */
+export async function partOutToComponents(input) {
+    const units = input.units ?? 1;
+    assertAssemblyInput(input.components, units);
+    const col = getAdminDb().collection(PRODUCT_COLLECTION);
+    return unitOfWork.runTransaction(async (tx) => {
+        const subjectRef = col.doc(input.sourceProductId);
+        const componentRefs = input.components.map((c) => col.doc(c.productId));
+        const [subjectSnap, ...componentSnaps] = await tx.getAll(subjectRef, ...componentRefs);
+        const plan = planAssembly({
+            storeId: input.storeId,
+            subject: {
+                productId: input.sourceProductId,
+                doc: subjectSnap.exists ? subjectSnap.data() : undefined,
+            },
+            components: input.components.map((request, i) => ({
+                request,
+                doc: componentSnaps[i].exists
+                    ? componentSnaps[i].data()
+                    : undefined,
+            })),
+            units,
+            direction: 1,
+        });
+        const now = new Date();
+        for (const w of plan.writes) {
+            tx.update(col.doc(w.productId), {
+                stockQuantity: w.stockQuantity,
+                availableQuantity: w.availableQuantity,
+                updatedAt: now,
+            });
+        }
+        tx.update(subjectRef, {
+            stockQuantity: plan.target.stockQuantity,
+            availableQuantity: plan.target.availableQuantity,
+            updatedAt: now,
+        });
+        serverLogger.info("partOutToComponents", {
+            storeId: input.storeId,
+            sourceProductId: input.sourceProductId,
+            units,
+            components: plan.consumed.length,
+        });
+        return {
+            targetProductId: input.sourceProductId,
+            unitsBuilt: units,
+            consumed: plan.consumed,
+        };
+    });
+}

package/dist/_internal/server/features/parts/data.d.ts

@@ -0,0 +1,65 @@
+import { type PartGlossaryDocument, type ModelCompositionDocument, type PartSlot } from "../../../../features/parts/schemas/firestore";
+/** The bucket cap. 87 is the largest real classification, so this clears it. */
+export declare const PART_SLOT_PAGE_SIZE = 120;
+/** One part, by `(slot, code|name)` — the only key this collection has. */
+export declare const getPartByKey: (slot: PartSlot, codeOrName: string) => Promise<PartGlossaryDocument | null>;
+/**
+ * The models that use a part, hydrated.
+ *
+ * 🛑 `getAll` over the ids the part ALREADY carries, not a query. `usedBy` is
+ * written by the generator, so this is one round trip for N ids with no index
+ * and no scan — and it is bounded by how many models actually use the part
+ * (measured max: 20).
+ */
+export declare const getModelsUsingPart: (partId: string) => Promise<ModelCompositionDocument[]>;
+/** One model's composition, by the corpus doc id. */
+export declare const getCompositionById: (id: string) => Promise<ModelCompositionDocument | null>;
+/**
+ * Hydrate the glossary rows a composition's slots point at, so a model page can
+ * link each slot and show its weight.
+ *
+ * ONE `getAll` for every slot — a per-slot read would be five round trips on a
+ * page that already has its own.
+ */
+export declare const getPartsForComposition: (compositionId: string) => Promise<Map<string, PartGlossaryDocument>>;
+/**
+ * Compositions for a named-model CATEGORY.
+ *
+ * 🛑 ONE INDEXED EQUALITY on `categoryId`, joined at SEED-GENERATION time.
+ *
+ * The first version queried `searchTxt` on `modelComposition` — a field that
+ * collection does not have, so it would have matched NOTHING while looking
+ * like a working read. The two id spaces genuinely disagree
+ * (`gen1-plastic-dragoon-f` vs `category-dragoon-f`), so a join is required;
+ * doing it in the generator makes it deterministic, reviewable in the
+ * committed seed, and one equality here instead of a name query.
+ *
+ * Measured: **210 of 259** compositions join. The join is on the normalised
+ * name, and on the name with its parenthetical expansion removed — the corpus
+ * titles HMS beys `Aero Knight MS (Aero Knight Metal Sky)` where the category
+ * is "Aero Knight MS", and without that second form only 150 matched.
+ *
+ * 🛑 A non-match leaves `categoryId` unset and this returns `[]`, so the model
+ * page shows no composition. That is honest: a fuzzy match could attach
+ * ANOTHER bey's parts, and a wrong part list is worse than none. Reconciling
+ * the remaining 49 is E3's job.
+ */
+export declare const getCompositionsForCategory: (categoryId: string) => Promise<ModelCompositionDocument[]>;
+/**
+ * Every part in one classification, alphabetical.
+ *
+ * 🛑 ONE equality on `slot`, bounded. The biggest bucket is 87 rows (attack
+ * rings) and the smallest 4 (armour) — measured, not assumed — so a page size
+ * of 120 shows every one of them today without a pager, and `truncated` tells
+ * the view to stop claiming a total the moment that stops being true.
+ *
+ * Firestore needs no composite index for one equality plus an `orderBy` on
+ * the SAME field it is already keyed by document id within… except it does
+ * for `(slot ==, name asc)`. So the sort is applied IN MEMORY: 87 rows is
+ * nothing to sort, and a declared index that exists only to order a bucket
+ * this small is an index to deploy, wait on, and remember.
+ */
+export declare const listPartsBySlot: (slot: PartSlot) => Promise<{
+    parts: PartGlossaryDocument[];
+    truncated: boolean;
+}>;