@mohasinac/appkit 4.52.5 → 4.53.0

package/dist/_internal/server/features/sticker-trace/finalizer.js

@@ -0,0 +1,123 @@
+/*
+ * WHY: Exactly one invocation gets to say a run finished, and it is the only
+ *      place that can — it alone knows every shard is done.
+ * WHAT: Overlay, cut SVG, the run's terminal status, and task cleanup.
+ *
+ * 🛑 Owns the `exports` TRACE_STAGE for audit-sticker-trace-progress R2, which
+ * with coordinator.ts's nine and shard.ts's `parts` completes all 11.
+ *
+ * EXPORTS: runFinalizer, FinalizerDeps
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:server
+ * @tag pattern:none
+ * @tag access:server
+ * @tag consumers:functions/consumer-functions
+ * @tag sideEffects:firestore,storage,rtdb
+ */
+import { normalizeError } from "../../../../errors/normalize.js";
+import { serverLogger } from "../../../../monitoring/index.js";
+import { getAdminDb } from "../../../../providers/db-firebase/index.js";
+import { stickerTraceRunsRepository } from "../../../../features/sticker-trace/repository/sticker-trace-runs.repository.js";
+import { STICKER_TRACE_TASKS_COLLECTION, } from "../../../../features/sticker-trace/schemas/firestore.js";
+import { emitProgress, emitTerminalFailure } from "./progress.js";
+export async function runFinalizer(task, deps) {
+    const { runId, sheetId } = task;
+    let run = null;
+    try {
+        run = await stickerTraceRunsRepository.findByIdOrFail(runId);
+        await emitProgress({ runId, stage: "exports", pct: 94, prior: run });
+        /*
+         * No exporter wired yet -> the run still SUCCEEDS, with no cutSvgPath.
+         * Writing a placeholder artifact was the alternative and is worse: a zero
+         * length cut.svg is indistinguishable from a real one that failed to
+         * generate, and the review UI would offer a download that cuts nothing.
+         * An absent field is honest and is what the UI can branch on.
+         */
+        let cutSvgPath;
+        if (deps.buildCutSvg) {
+            const svg = await deps.buildCutSvg(runId, sheetId);
+            const cut = await deps.writeArtifact({
+                sheetId,
+                runId,
+                name: "cut.svg",
+                contentType: "image/svg+xml",
+                body: svg,
+            });
+            cutSvgPath = cut.assetPath;
+        }
+        else {
+            serverLogger.info("Sticker trace finished without a cut file (no exporter wired)", {
+                runId,
+            });
+        }
+        run = await stickerTraceRunsRepository.markSucceeded(runId, {
+            partCount: run.partCount,
+            groupCount: run.groupCount,
+            artifacts: {
+                ...run.artifacts,
+                ...(cutSvgPath ? { cutSvgPath } : {}),
+            },
+        }, run);
+        await emitProgress({
+            runId,
+            stage: "done",
+            pct: 100,
+            terminal: true,
+            prior: run,
+        });
+        /*
+         * 🛑 Tasks are deleted LAST, and only after the run is terminal. Deleting
+         * them first would make a redelivered finalizer re-run against a run whose
+         * election record no longer exists — the one state where `create()` at the
+         * fixed id cannot refuse it.
+         *
+         * The counter doc goes too: it is per-run bookkeeping, and leaving it
+         * behind turns `stickerTraceTasks` into the unpruned collection the
+         * Firebase budget notes are about.
+         */
+        await deleteRunTasks(runId);
+    }
+    catch (err) {
+        const n = normalizeError(err);
+        serverLogger.error("Sticker trace finalizer failed", { runId, message: n.message });
+        /*
+         * The parts ARE rendered at this point — only the export failed — so this
+         * deliberately does NOT delete the tasks. A retry can resume from
+         * `exports` rather than re-rendering everything, which is exactly what the
+         * resume clamp exists to allow.
+         */
+        await emitTerminalFailure(runId, {
+            stage: "exports",
+            code: "FINALIZER_FAILED",
+            message: "The parts were traced but the cut file could not be written. Retry from exports.",
+        }, run);
+    }
+}
+async function deleteRunTasks(runId) {
+    const db = getAdminDb();
+    const snap = await db
+        .collection(STICKER_TRACE_TASKS_COLLECTION)
+        .where("runId", "==", runId)
+        .get();
+    if (snap.empty)
+        return;
+    /*
+     * BulkWriter rather than a hand-sized batch: it sizes and retries its own
+     * requests, so it is correct regardless of document size. A 400-doc batch is
+     * a guess that broke on `categories` with `Transaction too big`.
+     */
+    const writer = db.bulkWriter();
+    /*
+     * `void` because `close()` is the await point, not each delete.
+     *
+     * BulkWriter returns a promise per operation and resolves them through
+     * `close()`, which also surfaces their failures — so awaiting each delete
+     * here would serialise the whole batch and defeat the reason BulkWriter was
+     * chosen. Marking them ignored is the rule's own prescribed form, and it is
+     * accurate: they are not unhandled, they are handled one line down.
+     */
+    for (const doc of snap.docs)
+        void writer.delete(doc.ref);
+    await writer.close();
+}

package/dist/_internal/server/features/sticker-trace/mosaic-inputs.d.ts

@@ -0,0 +1,30 @@
+import { type PrintPageSizeId } from "../../../shared/features/sticker-trace/export/page-sizes";
+export interface MosaicPartInput {
+    ordinal: number;
+    name: string;
+    page: number;
+    xMm: number;
+    yMm: number;
+    widthMm: number;
+    heightMm: number;
+    rotated: boolean;
+    /** The promoted full-resolution PNG. */
+    png: Uint8Array;
+}
+export interface MosaicInputs {
+    title: string;
+    pageWidthMm: number;
+    pageHeightMm: number;
+    pageCount: number;
+    parts: MosaicPartInput[];
+    /** Parts that could not be placed on any page, named for the caller to report. */
+    unplaceable: Array<{
+        ordinal: number;
+        name: string;
+    }>;
+    /** Set when no mosaic can honestly be built; `parts` is then empty. */
+    refusedReason: string | null;
+}
+export declare function collectMosaicInputs(sheetId: string, opts?: {
+    pageSizeId?: PrintPageSizeId;
+}): Promise<MosaicInputs>;

package/dist/_internal/server/features/sticker-trace/mosaic-inputs.js

@@ -0,0 +1,112 @@
+/*
+ * WHY: The PDF mosaic needs three things that live in three different places —
+ *      the sheet's page and parts (Firestore), each part's promoted PNG
+ *      (Storage), and a layout (the shared nester). `pdfkit` is Node-only and
+ *      must stay in `functions/`, so without this the Function would reach into
+ *      all three itself and re-derive the layout, which is how a preview and a
+ *      printed sheet stop agreeing.
+ * WHAT: Everything the mosaic needs, assembled once, with the layout taken
+ *       from the same nester the print modal uses.
+ *
+ * 🛑 IT REFUSES WITHOUT MILLIMETRES. A mosaic's entire purpose is true physical
+ * scale; one built from pixel sizes would print at whatever scale the page
+ * happened to imply, look completely correct, and yield stickers the wrong
+ * size. `bboxMm` is null exactly when the scan's dpi could not be trusted, so
+ * that null is the signal — not an inconvenience to work around.
+ *
+ * EXPORTS: MosaicPartInput, MosaicInputs, collectMosaicInputs
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:server
+ * @tag pattern:none
+ * @tag access:server
+ * @tag consumers:functions/sticker-trace
+ * @tag sideEffects:storage,firestore
+ */
+import { stickerSheetsRepository } from "../../../../features/sticker-trace/repository/sticker-sheets.repository.js";
+import { nestParts } from "../../../shared/features/sticker-trace/export/nesting.js";
+import { PRINT_PAGE_SIZES, } from "../../../shared/features/sticker-trace/export/page-sizes.js";
+import { readScanBytes } from "./storage.js";
+export async function collectMosaicInputs(sheetId, opts = {}) {
+    const sheet = await stickerSheetsRepository.findByIdOrFail(sheetId);
+    const page = PRINT_PAGE_SIZES[opts.pageSizeId ?? "a4"];
+    const empty = {
+        title: sheet.title,
+        pageWidthMm: page.widthMm,
+        pageHeightMm: page.heightMm,
+        pageCount: 0,
+        parts: [],
+        unplaceable: [],
+    };
+    const parts = sheet.parts ?? [];
+    if (parts.length === 0) {
+        return { ...empty, refusedReason: "This sheet has no parts yet — promote a run first." };
+    }
+    /*
+     * 🛑 A promoted part has an `assetPath`; an unpromoted one does not. Building
+     * a mosaic from the subset that happens to have one would silently print a
+     * partial sheet — so the absence is reported as a refusal naming the fix.
+     */
+    const withAssets = parts.filter((p) => Boolean(p.assetPath));
+    if (withAssets.length === 0) {
+        return {
+            ...empty,
+            refusedReason: "These parts have not been rendered at full resolution yet. Promote the run and wait for it to finish.",
+        };
+    }
+    const measured = withAssets.filter((p) => p.bboxMm !== null);
+    if (measured.length === 0) {
+        return {
+            ...empty,
+            refusedReason: "This scan has no confirmed DPI, so its parts have no real-world size. " +
+                "A mosaic prints at true physical scale — confirm the DPI and it becomes available.",
+        };
+    }
+    /*
+     * A partial measurement is reported rather than silently dropped. Mixing
+     * measured and unmeasured parts on one sheet is the shape that makes a print
+     * look complete while missing stickers nobody noticed were absent.
+     */
+    const unmeasured = withAssets
+        .filter((p) => p.bboxMm === null)
+        .map((p) => ({ ordinal: p.ordinal, name: p.name }));
+    const nest = nestParts(measured.map((p) => ({
+        ordinal: p.ordinal,
+        name: p.name,
+        widthMm: p.bboxMm.width,
+        heightMm: p.bboxMm.height,
+    })), page);
+    /*
+     * Downloads are parallel but the list is already bounded: a sheet's parts are
+     * capped by the trace's own `maxParts`, and the minimum-area filter removes
+     * the speck storm that would otherwise reach here. Still a real cost per
+     * part, which is why the mosaic is produced on demand rather than per run.
+     */
+    const byOrdinal = new Map(measured.map((p) => [p.ordinal, p]));
+    const placed = await Promise.all(nest.placed.map(async (pl) => {
+        const part = byOrdinal.get(pl.ordinal);
+        return {
+            ordinal: pl.ordinal,
+            name: pl.name,
+            page: pl.page,
+            xMm: pl.xMm,
+            yMm: pl.yMm,
+            widthMm: pl.widthMm,
+            heightMm: pl.heightMm,
+            rotated: pl.rotated,
+            png: await readScanBytes(part.assetPath),
+        };
+    }));
+    return {
+        title: sheet.title,
+        pageWidthMm: page.widthMm,
+        pageHeightMm: page.heightMm,
+        pageCount: nest.pageCount,
+        parts: placed,
+        unplaceable: [
+            ...nest.unplaceable.map((u) => ({ ordinal: u.ordinal, name: u.name })),
+            ...unmeasured,
+        ],
+        refusedReason: null,
+    };
+}

package/dist/_internal/server/features/sticker-trace/progress.d.ts

@@ -0,0 +1,81 @@
+import type { StickerTraceRunDocument, TraceRunError } from "../../../../features/sticker-trace/schemas/firestore";
+import type { TraceStage } from "../../../shared/features/sticker-trace/types";
+/** Every value `TraceRunEvent.stage` can hold — the pipeline plus its two bookends. */
+export type ProgressStage = TraceStage | "queued" | "done";
+export declare function stickerTraceChannelPath(runId: string): string;
+/**
+ * Mint the read token for one run's channel.
+ *
+ * One claim, `stickerTraceRunId`, matching the rule in
+ * `appkit/firebase/base/database.rules.json`. Modelled on `enqueueJob`'s
+ * `bulkJobId` mint and deliberately NOT a general-purpose token: a broad token
+ * enumerating everything a user may watch is a Firestore fan-out per refresh
+ * and a 1000-byte claims ceiling waiting to be hit — which is why
+ * `/api/realtime/token` was deleted.
+ *
+ * The uid is namespaced so it can never collide with a real account.
+ */
+export declare function mintStickerTraceToken(runId: string): Promise<string>;
+export interface EmitProgressInput {
+    runId: string;
+    stage: ProgressStage;
+    /** 0..100. Clamped rather than trusted — a bar that reads 140% reads as broken. */
+    pct: number;
+    message?: string;
+    level?: "info" | "warn" | "error";
+    partsDone?: number;
+    partsTotal?: number;
+    shardsDone?: number;
+    shardsTotal?: number;
+    /** Terminal nodes stop a client polling for more. */
+    terminal?: boolean;
+    /**
+     * Append to the run document too. Default TRUE — stage transitions are
+     * history. Pass `false` for per-part ticks; see the header.
+     */
+    durable?: boolean;
+    /**
+     * The run, when the caller already holds it. The coordinator and finalizer
+     * both do, so threading it makes the durable append cost ZERO extra reads
+     * (the § "Status History" discipline).
+     */
+    prior?: StickerTraceRunDocument | null;
+}
+/**
+ * Write one progress transition.
+ *
+ * 🛑 NEVER THROWS. Progress reporting is observability, not the work: a failed
+ * RTDB write must not fail a trace that is otherwise succeeding, and a failed
+ * trace must still be able to report that it failed. Both writes are
+ * independently guarded, so losing the live node does not lose the history.
+ *
+ * Returns what it managed to do, so a caller that genuinely cares (a test, a
+ * diagnostic) can tell rather than having to assume.
+ */
+export declare function emitProgress(input: EmitProgressInput): Promise<{
+    live: boolean;
+    durable: boolean;
+}>;
+/**
+ * A per-part tick: live only.
+ *
+ * Named rather than left to a `durable: false` argument at ~60 call sites,
+ * because the one that forgets is the one that costs 6x the write budget.
+ */
+export declare function emitPartProgress(runId: string, partsDone: number, partsTotal: number, extra?: {
+    shardsDone?: number;
+    shardsTotal?: number;
+}): Promise<void>;
+/**
+ * The last thing a failing run does.
+ *
+ * 🛑 `error.message` must ALREADY be user-safe — resolved through
+ * `toUserMessage`, never raw server text. A Node `MODULE_NOT_FOUND` with a full
+ * require stack rendered inside a progress panel is Root Cause #86, and it
+ * reached a buyer's bid modal once already.
+ *
+ * Writes the terminal RTDB node FIRST and the run document second, so a client
+ * watching the bar stops waiting even if the Firestore write is the thing that
+ * is failing.
+ */
+export declare function emitTerminalFailure(runId: string, error: TraceRunError, prior?: StickerTraceRunDocument | null): Promise<void>;

package/dist/_internal/server/features/sticker-trace/progress.js

@@ -0,0 +1,198 @@
+/*
+ * WHY: "Even if we fail we know which stage it died in." A trace has eleven
+ *      stages and any of them can fail; a generic spinner that stops moving is
+ *      indistinguishable from a hang, and the gap only shows up on the day
+ *      something breaks inside it.
+ * WHAT: One emitter that writes BOTH the live RTDB node and the durable run
+ *       document, plus the per-run token mint.
+ *
+ * 🛑 BOTH, because they answer different questions. RTDB answers "what is it
+ * doing right now" and is pruned at 60 minutes; the run document answers "what
+ * happened to run 2 last Tuesday" and is what the retry panel reads. Writing
+ * only the first loses the history the whole feature exists for; writing only
+ * the second means no live bar.
+ *
+ * 🛑 Per-part progress is RTDB-ONLY. A Firestore event per part would be ~60
+ * writes per run instead of ~10, i.e. 6x the write cost to tell the operator
+ * something the live bar already shows and the history does not need. The
+ * `durable` flag is what expresses that, and `emitPartProgress` is the named
+ * wrapper so a caller does not have to remember.
+ *
+ * EXPORTS: emitProgress, emitPartProgress, emitTerminalFailure,
+ *   mintStickerTraceToken, stickerTraceChannelPath
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:server
+ * @tag pattern:none
+ * @tag access:server
+ * @tag consumers:functions/sticker-trace,api/admin/sticker-sheets
+ * @tag sideEffects:rtdb,firestore
+ */
+import { normalizeError } from "../../../../errors/normalize.js";
+import { serverLogger } from "../../../../monitoring/index.js";
+import { getAdminAuth, getAdminRealtimeDb } from "../../../../providers/db-firebase/index.js";
+import { RTDB_PATHS } from "../../../../providers/db-firebase/rtdb-paths.js";
+import { stickerTraceRunsRepository } from "../../../../features/sticker-trace/repository/sticker-trace-runs.repository.js";
+export function stickerTraceChannelPath(runId) {
+    return `${RTDB_PATHS.STICKER_TRACE}/${runId}`;
+}
+/**
+ * Mint the read token for one run's channel.
+ *
+ * One claim, `stickerTraceRunId`, matching the rule in
+ * `appkit/firebase/base/database.rules.json`. Modelled on `enqueueJob`'s
+ * `bulkJobId` mint and deliberately NOT a general-purpose token: a broad token
+ * enumerating everything a user may watch is a Firestore fan-out per refresh
+ * and a 1000-byte claims ceiling waiting to be hit — which is why
+ * `/api/realtime/token` was deleted.
+ *
+ * The uid is namespaced so it can never collide with a real account.
+ */
+export async function mintStickerTraceToken(runId) {
+    return getAdminAuth().createCustomToken(`sticker_trace_${runId}`, {
+        stickerTraceRunId: runId,
+    });
+}
+/**
+ * Write one progress transition.
+ *
+ * 🛑 NEVER THROWS. Progress reporting is observability, not the work: a failed
+ * RTDB write must not fail a trace that is otherwise succeeding, and a failed
+ * trace must still be able to report that it failed. Both writes are
+ * independently guarded, so losing the live node does not lose the history.
+ *
+ * Returns what it managed to do, so a caller that genuinely cares (a test, a
+ * diagnostic) can tell rather than having to assume.
+ */
+export async function emitProgress(input) {
+    const pct = Math.max(0, Math.min(100, Math.round(input.pct)));
+    const result = { live: false, durable: false };
+    try {
+        await getAdminRealtimeDb()
+            .ref(stickerTraceChannelPath(input.runId))
+            .set({
+            stage: input.stage,
+            pct,
+            ...(input.message ? { message: input.message } : {}),
+            level: input.level ?? "info",
+            ...(input.partsDone !== undefined ? { partsDone: input.partsDone } : {}),
+            ...(input.partsTotal !== undefined ? { partsTotal: input.partsTotal } : {}),
+            ...(input.shardsDone !== undefined ? { shardsDone: input.shardsDone } : {}),
+            ...(input.shardsTotal !== undefined ? { shardsTotal: input.shardsTotal } : {}),
+            ...(input.terminal ? { terminal: true } : {}),
+            /*
+             * 🛑 Epoch MILLISECONDS, and `cleanupRtdbEvents` reads this exact key.
+             * A node with a missing or non-finite `updatedAt` is treated as stale
+             * by definition there — it can never age out on its own, so leaving it
+             * would pin the node forever.
+             */
+            updatedAt: Date.now(),
+        });
+        result.live = true;
+    }
+    catch (liveErr) {
+        const n = normalizeError(liveErr);
+        /*
+         * Logged, not swallowed. The live bar going dark while the trace keeps
+         * working is survivable — the run document still carries the history — but
+         * it is NOT nothing: it means the operator is watching a stalled bar on a
+         * healthy run, and the only way anyone learns that is this line.
+         */
+        serverLogger.warn("Sticker trace live progress write failed (non-fatal)", {
+            runId: input.runId,
+            stage: input.stage,
+            message: n.message,
+        });
+    }
+    if (input.durable !== false) {
+        try {
+            const event = {
+                at: new Date(),
+                stage: input.stage,
+                pct,
+                ...(input.message ? { message: input.message } : {}),
+                ...(input.level ? { level: input.level } : {}),
+            };
+            await stickerTraceRunsRepository.appendEvent(input.runId, event, input.prior);
+            result.durable = true;
+        }
+        catch (durableErr) {
+            const n = normalizeError(durableErr);
+            /*
+             * This one is worse than the live failure and is logged at error: the
+             * durable append is the ONLY record a post-mortem or a retry panel can
+             * read, and the RTDB node it was mirroring is pruned within the hour.
+             * A gap here means the run's own history has a hole in it.
+             */
+            serverLogger.error("Sticker trace durable event append failed", {
+                runId: input.runId,
+                stage: input.stage,
+                message: n.message,
+            });
+        }
+    }
+    return result;
+}
+/**
+ * A per-part tick: live only.
+ *
+ * Named rather than left to a `durable: false` argument at ~60 call sites,
+ * because the one that forgets is the one that costs 6x the write budget.
+ */
+export async function emitPartProgress(runId, partsDone, partsTotal, extra) {
+    // Guard the division: a run with zero parts is a real outcome (an empty
+    // sheet, or the montage case), and 0/0 would publish NaN as the bar's width.
+    const pct = partsTotal > 0 ? (partsDone / partsTotal) * 100 : 0;
+    await emitProgress({
+        runId,
+        stage: "parts",
+        pct,
+        partsDone,
+        partsTotal,
+        ...extra,
+        durable: false,
+    });
+}
+/**
+ * The last thing a failing run does.
+ *
+ * 🛑 `error.message` must ALREADY be user-safe — resolved through
+ * `toUserMessage`, never raw server text. A Node `MODULE_NOT_FOUND` with a full
+ * require stack rendered inside a progress panel is Root Cause #86, and it
+ * reached a buyer's bid modal once already.
+ *
+ * Writes the terminal RTDB node FIRST and the run document second, so a client
+ * watching the bar stops waiting even if the Firestore write is the thing that
+ * is failing.
+ */
+export async function emitTerminalFailure(runId, error, prior) {
+    await emitProgress({
+        runId,
+        stage: error.stage,
+        pct: 100,
+        message: error.message,
+        level: "error",
+        terminal: true,
+        durable: true,
+        prior,
+    });
+    try {
+        await stickerTraceRunsRepository.markFailed(runId, error, undefined, prior);
+    }
+    catch (markErr) {
+        const n = normalizeError(markErr);
+        /*
+         * 🛑 The most important log line in this file. If this write fails the run
+         * stays `running` forever: the retry panel offers nothing, the history says
+         * the trace is still going, and the RTDB node that said otherwise is gone
+         * within the hour. There is no second mechanism that notices — so the only
+         * trace of a run stuck in limbo is this.
+         */
+        serverLogger.error("Sticker trace run could not be marked failed — run left RUNNING", {
+            runId,
+            stage: error.stage,
+            code: error.code,
+            message: n.message,
+        });
+    }
+}

package/dist/_internal/server/features/sticker-trace/promote.d.ts

@@ -0,0 +1,23 @@
+export interface PromoteRunInput {
+    sheetId: string;
+    runId: string;
+    promotedBy: string;
+}
+export interface PromoteRunResult {
+    sheetId: string;
+    runId: string;
+    /** How many shards will render full-resolution parts. */
+    shardCount: number;
+    partCount: number;
+}
+/**
+ * Accept a run and start the full-resolution render.
+ *
+ * 🛑 It refuses a run that did not SUCCEED. Promoting a failed or still-running
+ * run would copy a partial `parts[]` onto the sheet and set `activeRunId` to
+ * it — the sheet would then confidently show an incomplete result, with the
+ * run's own status the only contradiction and nothing surfacing it.
+ */
+export declare function promoteStickerTraceRun(input: PromoteRunInput): Promise<PromoteRunResult>;
+/** Whether this run is already the sheet's accepted result. */
+export declare function isRunPromoted(sheetId: string, runId: string): Promise<boolean>;