@mohasinac/appkit 4.44.0 → 4.46.0

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;
+}>;

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

@@ -0,0 +1,170 @@
+/**
+ * D12 — reads for the public part surfaces.
+ *
+ * 🛑 Wrapped in `React.cache` where a page+`generateMetadata` pair shares the
+ * call, and the NARROWEST shared call is cached rather than the exported one:
+ * `React.cache` memoises per argument list, so two call sites passing
+ * different arguments get two entries and dedupe nothing.
+ */
+import { cache } from "react";
+import { PART_GLOSSARY_COLLECTION, MODEL_COMPOSITION_COLLECTION, partGlossaryId, } from "../../../../features/parts/schemas/firestore.js";
+import { getAdminDb } from "../../../../providers/db-firebase/index.js";
+import { serverLogger } from "../../../../monitoring/server-logger.js";
+import { normalizeError } from "../../../../errors/normalize.js";
+/** The bucket cap. 87 is the largest real classification, so this clears it. */
+export const PART_SLOT_PAGE_SIZE = 120;
+/** One part, by `(slot, code|name)` — the only key this collection has. */
+export const getPartByKey = cache(async (slot, codeOrName) => {
+    try {
+        const snap = await getAdminDb()
+            .collection(PART_GLOSSARY_COLLECTION)
+            .doc(partGlossaryId(slot, codeOrName))
+            .get();
+        return snap.exists ? { id: snap.id, ...snap.data() } : null;
+    }
+    catch (err) {
+        const e = normalizeError(err);
+        serverLogger.warn("getPartByKey failed", { slot, codeOrName, error: e.message });
+        return 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 const getModelsUsingPart = cache(async (partId) => {
+    try {
+        const db = getAdminDb();
+        const part = await db.collection(PART_GLOSSARY_COLLECTION).doc(partId).get();
+        const ids = (part.data()?.usedBy ?? []).slice(0, 24);
+        if (ids.length === 0)
+            return [];
+        const col = db.collection(MODEL_COMPOSITION_COLLECTION);
+        const snaps = await db.getAll(...ids.map((id) => col.doc(id)));
+        return snaps
+            .filter((s) => s.exists)
+            .map((s) => ({ id: s.id, ...s.data() }));
+    }
+    catch (err) {
+        const e = normalizeError(err);
+        serverLogger.warn("getModelsUsingPart failed", { partId, error: e.message });
+        return [];
+    }
+});
+/** One model's composition, by the corpus doc id. */
+export const getCompositionById = cache(async (id) => {
+    try {
+        const snap = await getAdminDb().collection(MODEL_COMPOSITION_COLLECTION).doc(id).get();
+        return snap.exists ? { id: snap.id, ...snap.data() } : null;
+    }
+    catch (err) {
+        const e = normalizeError(err);
+        serverLogger.warn("getCompositionById failed", { id, error: e.message });
+        return 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 const getPartsForComposition = cache(async (compositionId) => {
+    const out = new Map();
+    try {
+        const db = getAdminDb();
+        const comp = await getCompositionById(compositionId);
+        const ids = (comp?.slots ?? [])
+            .map((s) => s.partId)
+            .filter((id) => !!id);
+        if (ids.length === 0)
+            return out;
+        const col = db.collection(PART_GLOSSARY_COLLECTION);
+        const snaps = await db.getAll(...[...new Set(ids)].map((id) => col.doc(id)));
+        for (const s of snaps) {
+            if (s.exists)
+                out.set(s.id, { id: s.id, ...s.data() });
+        }
+    }
+    catch (err) {
+        const e = normalizeError(err);
+        serverLogger.warn("getPartsForComposition failed", { compositionId, error: e.message });
+    }
+    return out;
+});
+/**
+ * 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 const getCompositionsForCategory = cache(async (categoryId) => {
+    if (!categoryId)
+        return [];
+    try {
+        const snap = await getAdminDb()
+            .collection(MODEL_COMPOSITION_COLLECTION)
+            .where("categoryId", "==", categoryId)
+            .limit(8)
+            .get();
+        return snap.docs.map((d) => ({ id: d.id, ...d.data() }));
+    }
+    catch (err) {
+        const e = normalizeError(err);
+        serverLogger.warn("getCompositionsForCategory failed", { categoryId, error: e.message });
+        return [];
+    }
+});
+/**
+ * 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 const listPartsBySlot = cache(async (slot) => {
+    try {
+        const snap = await getAdminDb()
+            .collection(PART_GLOSSARY_COLLECTION)
+            .where("slot", "==", slot)
+            .limit(PART_SLOT_PAGE_SIZE)
+            .get();
+        const parts = snap.docs
+            .map((d) => ({ id: d.id, ...d.data() }))
+            .sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""));
+        return { parts, truncated: snap.size >= PART_SLOT_PAGE_SIZE };
+    }
+    catch (err) {
+        const e = normalizeError(err);
+        serverLogger.warn("listPartsBySlot failed", { slot, error: e.message });
+        return { parts: [], truncated: false };
+    }
+});

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

@@ -0,0 +1,34 @@
+/**
+ * D12 — OG cards for the part surfaces.
+ *
+ * ── 🛑 NO IMAGE FETCHES, DELIBERATELY ──────────────────────────────────────
+ *
+ * Every other OG renderer here pulls a cover image through `resolveOgImageUrl`.
+ * These do not, and that is the one design decision worth stating: the project
+ * was suspended for **Fast Origin Transfer at 5.25× its allowance** (52.52 GB
+ * against 10 GB), traced to render-time image proxying (Root Cause #104). A
+ * glossary of 753 parts across 20 classifications is 774 OG routes; one remote
+ * fetch each, on a crawler sweep, is exactly the amplification that was just
+ * removed. Type on a gradient costs one lambda and nothing else.
+ *
+ * It also costs nothing in usefulness: a part has no photograph in our data.
+ * The honest card is its name, what kind of part it is, its weight and how
+ * many models use it — all four of which are facts we hold.
+ *
+ * ── 🛑 NO MONEY ON THE CANVAS ──────────────────────────────────────────────
+ *
+ * All eight money-bearing OG renderers were stripped for this reason: an OG
+ * image is a public image URL with the amount burned into the pixels, so no
+ * sign-in gate reaches it and no paywall markup describes it. A part card
+ * carries no price and never should, even though its page lists listings.
+ */
+import type { ReactElement } from "react";
+import { type PartGlossaryDocument, type PartSlot } from "../../../../features/parts/schemas/firestore";
+/** One part's card. */
+export declare function renderPartOg(part: PartGlossaryDocument | null | undefined, usedByCount: number, opts: {
+    siteName: string;
+}): ReactElement;
+/** One classification's card. */
+export declare function renderPartClassificationOg(slot: PartSlot, count: number, opts: {
+    siteName: string;
+}): ReactElement;