@mohasinac/appkit 4.52.4 → 4.53.0

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

@@ -0,0 +1,193 @@
+/*
+ * WHY: An exploratory run produces vector geometry and ~20 KB review
+ *      thumbnails — about 1 MB. Full-resolution parts and the print exports
+ *      cost roughly 500 MB a sheet, which is the difference between ~52 sheets
+ *      in 5 GB and about 8. So they are rendered ONCE, for the run the operator
+ *      actually chose, and this is that moment.
+ * WHAT: Accept a run as the sheet's current result, and fan out a full-
+ *       resolution render of its parts.
+ *
+ * 🛑 `promoteRun` and `markPromoted` have existed since P4 with ZERO callers.
+ * This is their first one. Anything that looked like it already worked —
+ * `isPromoted` in the run list, `promotedPartCount` in the adapter — was
+ * reading fields nothing has ever written.
+ *
+ * 🛑 TWO DIFFERENT THINGS ARE CALLED "PROMOTE" IN THIS FEATURE AND THEY MUST
+ * NOT BE CONFLATED:
+ *   - THIS one promotes a RUN onto its SHEET: the sheet now shows that run's
+ *     parts, and full-res renders are produced.
+ *   - Part Two's `promoteStickerSheetToListings` promotes a SHEET into
+ *     marketplace PRODUCTS.
+ * The second depends on the first, because `SheetPart.assetPath` does not
+ * exist until a run has been promoted here.
+ *
+ * EXPORTS: PromoteRunInput, PromoteRunResult, promoteStickerTraceRun
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:server
+ * @tag pattern:none
+ * @tag access:server
+ * @tag consumers:api/admin/sticker-sheets
+ * @tag sideEffects:firestore,rtdb
+ */
+import { ValidationError } from "../../../../errors/validation-error.js";
+import { stickerSheetsRepository } from "../../../../features/sticker-trace/repository/sticker-sheets.repository.js";
+import { stickerTraceRunsRepository } from "../../../../features/sticker-trace/repository/sticker-trace-runs.repository.js";
+import { TraceRunStatusValues } from "../../../../features/sticker-trace/schemas/firestore.js";
+import { serverLogger } from "../../../../monitoring/index.js";
+import { createShardTasks, planShards } from "./fanout.js";
+import { emitProgress } from "./progress.js";
+import { readRunGeometry } from "./storage.js";
+/**
+ * Promote fans out no wider than the trace did.
+ *
+ * A full-resolution part is a decode, a rasterise and a PNG encode at native
+ * size, so the shard budget is the same 1 GiB / 300 s. More shards than
+ * `maxInstances` (8) queue rather than run, and each one is a Firestore write
+ * plus an invocation.
+ */
+const MAX_PROMOTE_SHARDS = 8;
+/**
+ * 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 async function promoteStickerTraceRun(input) {
+    const [sheet, run] = await Promise.all([
+        stickerSheetsRepository.findByIdOrFail(input.sheetId),
+        stickerTraceRunsRepository.findByIdOrFail(input.runId),
+    ]);
+    /*
+     * The run must belong to THIS sheet. Both ids are caller-supplied, so this is
+     * the only place the pairing can be checked — without it, promoting run X of
+     * sheet A onto sheet B would copy A's parts onto B and point B's
+     * `activeRunId` at a run that is not its own.
+     */
+    if (run.sheetId !== input.sheetId) {
+        throw new ValidationError("That run belongs to a different sheet.", {
+            runId: "Run and sheet do not match.",
+        });
+    }
+    if (run.status !== TraceRunStatusValues.SUCCEEDED) {
+        throw new ValidationError(`Only a successful run can be promoted — this one is ${run.status}.`, { runId: "Re-run it, or promote a different attempt." });
+    }
+    /*
+     * 🛑 The parts come from `geometry.json`, NOT from the run document — the run
+     * carries only `partCount`. That is deliberate: sixty Bézier outlines would
+     * approach Firestore's 1 MiB document limit, which is why the geometry is an
+     * artifact in the first place.
+     */
+    const geometry = await readRunGeometry(input.runId, input.sheetId);
+    /*
+     * Millimetres only when the scan's dpi can be trusted.
+     *
+     * The geometry is in WORKING raster pixels while `dpi` describes the
+     * ORIGINAL, so the two are bridged by the downscale factor. Skipping that
+     * bridge is the subtle version of the same error the commit panel nearly
+     * shipped: every figure would be wrong by exactly the downscale ratio, and
+     * every one of them would look plausible.
+     */
+    const workingToOriginal = sheet.widthPx > 0 && geometry.workingSize.width > 0
+        ? sheet.widthPx / geometry.workingSize.width
+        : null;
+    const pxPerMm = sheet.dpi && sheet.dpi > 0 && workingToOriginal !== null
+        ? (sheet.dpi / 25.4) / workingToOriginal
+        : null;
+    /*
+     * 🛑 `groupIndex` is 0 for every part, because geometry.json does not carry a
+     * per-part cluster assignment. On a single-sheet scan that is simply correct.
+     * On a multi-sheet scan it is NOT, and it is warned about rather than quietly
+     * written — a wrong group index renders every part under one tab, which looks
+     * like a tidy result instead of a lost distinction.
+     */
+    if ((run.groupCount ?? 1) > 1) {
+        serverLogger.warn("Promoting a multi-sheet run; parts carry groupIndex 0", {
+            runId: input.runId,
+            sheetId: input.sheetId,
+            groupCount: run.groupCount,
+        });
+    }
+    const parts = geometry.parts.map((g) => {
+        const bboxMm = pxPerMm
+            ? {
+                x: g.bbox.x / pxPerMm,
+                y: g.bbox.y / pxPerMm,
+                width: g.bbox.width / pxPerMm,
+                height: g.bbox.height / pxPerMm,
+            }
+            : null;
+        return {
+            ordinal: g.ordinal,
+            // The schema's own default: the ordinal, renameable by an admin later.
+            name: String(g.ordinal),
+            groupIndex: 0,
+            bboxPx: g.bbox,
+            bboxMm,
+            // Derived from the same measurement, so it is withheld on the same terms.
+            areaMm2: bboxMm ? Math.round(bboxMm.width * bboxMm.height * 100) / 100 : null,
+        };
+    });
+    if (parts.length === 0) {
+        throw new ValidationError("That run produced no parts, so there is nothing to promote.", { runId: "Tune the parameters and try another attempt." });
+    }
+    /*
+     * Sheet first, fan-out second.
+     *
+     * The sheet's `parts[]` and geometry are what every review surface reads, and
+     * they are complete the moment the run succeeded — the fan-out only adds
+     * full-resolution PNGs. Promoting the document first means an operator sees
+     * the accepted result immediately, and a fan-out that fails leaves a sheet
+     * that is correct but missing downloads, rather than a run marked accepted on
+     * a sheet still showing the previous one.
+     */
+    await stickerSheetsRepository.promoteRun(input.sheetId, input.runId, {
+        parts,
+        groupCount: run.groupCount ?? 1,
+        artifacts: run.artifacts ?? {},
+    });
+    const ordinals = parts.map((p) => p.ordinal);
+    const shards = planShards(ordinals, MAX_PROMOTE_SHARDS);
+    /*
+     * 🛑 `mode: "full"` is what makes these DIFFERENT task documents from the
+     * trace's. `shardTaskId` keys on the mode precisely so this does not `set()`
+     * over `{runId}__part__{i}` — which would be an update, would not fire
+     * `documentCreated`, and would leave the promote silently doing nothing.
+     */
+    const shardCount = await createShardTasks({
+        runId: input.runId,
+        sheetId: input.sheetId,
+        mode: "full",
+        shards,
+    });
+    /*
+     * Best-effort, like every other progress write. The channel is the live bar;
+     * the durable record is the run document, which `markPromoted` writes when
+     * the finalizer completes. A failed ping must never fail a promotion that
+     * has already written Firestore.
+     */
+    await emitProgress({
+        runId: input.runId,
+        stage: "parts",
+        pct: 0,
+        partsDone: 0,
+        partsTotal: parts.length,
+        shardsDone: 0,
+        shardsTotal: shardCount,
+        message: `Rendering ${parts.length} part(s) at full resolution`,
+        level: "info",
+    });
+    return {
+        sheetId: input.sheetId,
+        runId: input.runId,
+        shardCount,
+        partCount: parts.length,
+    };
+}
+/** Whether this run is already the sheet's accepted result. */
+export async function isRunPromoted(sheetId, runId) {
+    const sheet = await stickerSheetsRepository.findById(sheetId);
+    return sheet?.activeRunId === runId;
+}

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

@@ -0,0 +1,50 @@
+import type { StickerTraceTaskDocument } from "../../../../features/sticker-trace/schemas/firestore";
+import type { ImageCodec } from "../../../shared/features/sticker-trace/codec";
+import type { CutPath, Rect } from "../../../shared/features/sticker-trace/types";
+export interface ShardDeps {
+    codec: ImageCodec;
+    readScan: (assetPath: string) => Promise<Uint8Array>;
+    readGeometry: (runId: string, sheetId: string) => Promise<{
+        workingSize: Rect;
+        parts: {
+            ordinal: number;
+            bbox: Rect;
+            path: CutPath;
+        }[];
+    }>;
+    /**
+     * Rasterise one part's path into an alpha mask covering `bbox`.
+     *
+     * 🛑 Takes the PATH, not an ordinal. An ordinal carries no geometry, so a
+     * signature keyed on it could only be implemented by re-reading
+     * geometry.json for every part — sixty extra downloads per shard for data the
+     * caller already holds. And no `scale`: `bbox` is already in
+     * full-resolution pixels by the time this is called.
+     */
+    rasterise: (path: CutPath, bbox: Rect) => Promise<Uint8Array>;
+    writeArtifact: (input: {
+        sheetId: string;
+        runId: string;
+        name: string;
+        contentType: string;
+        body: Uint8Array;
+    }) => Promise<{
+        assetPath: string;
+    }>;
+}
+/**
+ * Render this shard's parts, then report done.
+ *
+ * 🛑 `mode` decides resolution, and that is the single decision keeping this
+ * feature inside the Storage allowance. `thumb` renders review thumbnails into
+ * ONE sprite atlas; `full` renders full-resolution parts and only runs when a
+ * human promotes a run. Rendering full-res on every run costs ~600 MB per
+ * sheet across a tuning session against ~95 MB — roughly 8 sheets inside 5 GB
+ * instead of 52.
+ *
+ * 🛑 The shard reports done even when a part THROWS. Leaving the counter short
+ * means the finalizer is never elected and the run sits RUNNING forever — a
+ * stuck run is worse than a run that completes reporting a bad part, because
+ * nothing sweeps it and the RTDB channel prunes within the hour.
+ */
+export declare function runShard(task: StickerTraceTaskDocument, deps: ShardDeps): Promise<void>;

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

@@ -0,0 +1,174 @@
+/*
+ * WHY: Rendering parts is the only embarrassingly parallel stage, and the only
+ *      one that cannot fit one invocation at `precise`/`max` on a 34 MP scan
+ *      with sixty parts.
+ * WHAT: One shard's slice of the parts, then its vote in the finalizer
+ *       election.
+ *
+ * 🛑 Owns the `parts` TRACE_STAGE for audit-sticker-trace-progress R2.
+ *
+ * 🛑 Per-part progress is RTDB-ONLY, via emitPartProgress. A Firestore event
+ * per part would be ~60 writes per run instead of ~10 — 6x the write budget to
+ * say something the live bar already shows and the history does not need.
+ *
+ * EXPORTS: runShard, ShardDeps
+ *
+ * @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 { stickerSheetsRepository } from "../../../../features/sticker-trace/repository/sticker-sheets.repository.js";
+import { completeShardAndMaybeElectFinalizer } from "./fanout.js";
+import { emitPartProgress, emitProgress } from "./progress.js";
+/**
+ * One promoted part at full resolution.
+ *
+ * Extracted because the inline version sat at brace-depth 6 and tripped
+ * audit-code-quality's DEEP_NESTING — which was a fair call: the render is a
+ * distinct step, and naming it makes the mode branch in `runShard` read as the
+ * decision it is rather than as two blocks of plumbing.
+ */
+async function writeFullPart(deps, input) {
+    const png = await deps.codec.encodePngRegion(input.source, input.region, input.alpha);
+    await deps.writeArtifact({
+        sheetId: input.sheetId,
+        runId: input.runId,
+        name: `part-${String(input.ordinal).padStart(3, "0")}.png`,
+        contentType: png.contentType,
+        body: png.bytes,
+    });
+}
+/**
+ * Render this shard's parts, then report done.
+ *
+ * 🛑 `mode` decides resolution, and that is the single decision keeping this
+ * feature inside the Storage allowance. `thumb` renders review thumbnails into
+ * ONE sprite atlas; `full` renders full-resolution parts and only runs when a
+ * human promotes a run. Rendering full-res on every run costs ~600 MB per
+ * sheet across a tuning session against ~95 MB — roughly 8 sheets inside 5 GB
+ * instead of 52.
+ *
+ * 🛑 The shard reports done even when a part THROWS. Leaving the counter short
+ * means the finalizer is never elected and the run sits RUNNING forever — a
+ * stuck run is worse than a run that completes reporting a bad part, because
+ * nothing sweeps it and the RTDB channel prunes within the hour.
+ */
+export async function runShard(task, deps) {
+    const { runId, sheetId } = task;
+    let rendered = 0;
+    const failures = [];
+    try {
+        const sheet = await stickerSheetsRepository.findByIdOrFail(sheetId);
+        const geometry = await deps.readGeometry(runId, sheetId);
+        const source = await deps.readScan(sheet.sourceScan.assetPath);
+        /*
+         * 🛑 Scale is derived from the SHEET's full width against the working
+         * raster the geometry was traced on. Carrying vectors is what makes this
+         * exact — an upscaled mask would soften every cut line by the ratio.
+         */
+        const scale = sheet.widthPx / Math.max(1, geometry.workingSize.width);
+        const mine = geometry.parts.filter((p) => task.partOrdinals.includes(p.ordinal));
+        const tiles = [];
+        for (const part of mine) {
+            try {
+                const region = {
+                    x: Math.round(part.bbox.x * scale),
+                    y: Math.round(part.bbox.y * scale),
+                    width: Math.max(1, Math.round(part.bbox.width * scale)),
+                    height: Math.max(1, Math.round(part.bbox.height * scale)),
+                };
+                const alpha = await deps.rasterise(part.path, region);
+                if (task.mode === "full") {
+                    await writeFullPart(deps, { sheetId, runId, ordinal: part.ordinal, source, region, alpha });
+                }
+                else {
+                    tiles.push({ raster: await deps.codec.decodeTile(source, region), ordinal: part.ordinal });
+                }
+                rendered++;
+            }
+            catch (partErr) {
+                const n = normalizeError(partErr);
+                failures.push(part.ordinal);
+                serverLogger.warn("Sticker trace part render failed", {
+                    runId,
+                    ordinal: part.ordinal,
+                    message: n.message,
+                });
+            }
+            /*
+             * No shard counters here on purpose. A shard knows its own index but not
+             * how many others have finished — that lives in the transactional
+             * counter — and the first draft of this call passed
+             * `task.shardIndex !== undefined ? undefined : undefined`, which is
+             * always undefined: a nonsense expression that typechecked and published
+             * nothing.
+             */
+            await emitPartProgress(runId, rendered, mine.length);
+        }
+        /*
+         * One atlas per SHARD, not per run: a shard cannot see the other shards'
+         * tiles, and waiting to combine them would need the finalizer to re-read
+         * every thumbnail. Object count stays bounded by shard count (<= 8), which
+         * is the property that mattered — sixty individual thumbnails is what this
+         * avoids.
+         */
+        if (task.mode === "thumb" && tiles.length > 0) {
+            const atlas = await deps.codec.encodeAtlas(tiles, { maxLongEdge: 1024 });
+            await deps.writeArtifact({
+                sheetId,
+                runId,
+                name: `atlas-${task.shardIndex ?? 0}.png`,
+                contentType: atlas.image.contentType,
+                body: atlas.image.bytes,
+            });
+        }
+    }
+    catch (err) {
+        const n = normalizeError(err);
+        serverLogger.error("Sticker trace shard failed", {
+            runId,
+            shardIndex: task.shardIndex,
+            message: n.message,
+        });
+    }
+    finally {
+        // See the header: report done regardless, or the run never finishes.
+        const election = await completeShardAndMaybeElectFinalizer({
+            runId,
+            sheetId,
+            shardIndex: task.shardIndex ?? 0,
+            shardCount: await resolveShardCount(runId),
+            mode: task.mode,
+        });
+        if (failures.length > 0) {
+            await emitProgress({
+                runId,
+                stage: "parts",
+                pct: 90,
+                message: `${failures.length} part(s) could not be rendered.`,
+                level: "warn",
+                durable: true,
+            });
+        }
+        if (election.electedFinalizer) {
+            serverLogger.info("Sticker trace finalizer elected", { runId });
+        }
+    }
+}
+/**
+ * The run's own `shardCount`, read rather than passed.
+ *
+ * A shard receives its task, not the run, and trusting a count copied onto the
+ * task would be a mirror that drifts the moment the coordinator retries with a
+ * different fan-out (Root Cause #42).
+ */
+async function resolveShardCount(runId) {
+    const { stickerTraceRunsRepository } = await import("../../../../features/sticker-trace/repository/sticker-trace-runs.repository.js");
+    const run = await stickerTraceRunsRepository.findById(runId);
+    return run?.shardCount ?? 1;
+}

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

@@ -0,0 +1,141 @@
+import type { DpiSource } from "../../../../features/sticker-trace/schemas/firestore";
+import type { ScanType } from "../../../shared/features/sticker-trace/types";
+import { type SignedUpload } from "./storage";
+/**
+ * 100 MB.
+ *
+ * Measured against the reference corpus rather than picked: `@ShayBlader Scan
+ * 18` is 79 MB, the largest of the nine, and it is a legitimate scan rather
+ * than an outlier to design against. The cap exists because scans are stored
+ * AS UPLOADED — no re-encode, because compression artefacts measured ±7 on the
+ * JPEG samples and the halftone scan's cut-line signal is only ~3x noise, so
+ * transcoding would attack the exact signal the detector needs.
+ */
+export declare const STICKER_SHEET_MAX_BYTES: number;
+export interface CreateStickerSheetInput {
+    /** 🛑 Mandatory — see `requireTitle`. */
+    title: string;
+    scanType?: ScanType;
+    contentType: string;
+    extension: string;
+}
+export interface CreateStickerSheetResult {
+    sheetId: string;
+    upload: SignedUpload;
+}
+/**
+ * Create the sheet row and mint the write URL for its scan, in one call.
+ *
+ * 🛑 The ROW comes first and the bytes second, which is the opposite of what
+ * feels natural. The object path contains the sheet id, so an upload signed
+ * before the row exists has nowhere to go — and a bucket object with no
+ * document pointing at it is unreachable AND unmeterable: it costs storage
+ * forever with nothing in any UI to delete it from. A document whose upload
+ * never completes is the harmless direction: `traceStatus` stays `queued`,
+ * `sourceScan.bytes` is 0, and the list can say so.
+ *
+ * 🛑 `widthPx`/`heightPx` are 0 until `attachStickerSheetScan`. appkit cannot
+ * probe an image — the codec is injected, which is what Root Cause #24 is
+ * about — so the only party that already knows the dimensions is the browser
+ * that just decoded it for live tuning. Guessing them here would put two
+ * numbers on the document that nothing measured.
+ */
+export declare function createStickerSheet(input: CreateStickerSheetInput): Promise<CreateStickerSheetResult>;
+export interface AttachScanInput {
+    sheetId: string;
+    assetPath: string;
+    widthPx: number;
+    heightPx: number;
+    dpi?: number;
+    dpiSource?: DpiSource;
+    scanType?: ScanType;
+    /** A dedupe hint the browser computed. Never trusted — see `StoredAsset`. */
+    sha256?: string;
+}
+export type AttachScanResult = {
+    ok: true;
+    bytes: number;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/**
+ * Verify the uploaded bytes and record them on the sheet.
+ *
+ * 🛑 The caller's `assetPath` is CONTAINED to this sheet's own prefix before
+ * anything reads it. Every other field here is merely wrong if wrong; this one
+ * is a capability — `readScanBytes` will later fetch whatever it names, and a
+ * path naming another sheet would turn this endpoint into a cross-sheet read
+ * primitive. `readScanBytes` has its own `SCAN_ROOT` check, which is the second
+ * layer, not the first: by the time it runs the path is already on a document.
+ *
+ * 🛑 `finalizeScanUpload` DELETES the object on a magic-byte mismatch, so a
+ * failure leaves nothing behind in the bucket. That is why the mismatch RETURNS
+ * rather than throwing: the sheet row survives and the operator re-uploads into
+ * it, instead of starting again with a fresh row and orphaning the first.
+ */
+export declare function attachStickerSheetScan(input: AttachScanInput): Promise<AttachScanResult>;
+/**
+ * The asset kinds a client may ask for.
+ *
+ * 🛑 A KIND, never a path, and this is the whole security shape of the asset
+ * endpoint: the client names WHAT it wants and the server looks the path up on
+ * the document. Accepting an `assetPath` instead would make the endpoint a
+ * signed-URL mint for any object in the bucket — including another admin's
+ * scans and, since the same bucket holds them, `private/digital-content/`.
+ * It is also what keeps every `*Path` field off the wire entirely, which is the
+ * property `PRIVATE_STICKER_SHEET_FIELDS` declares and
+ * audit-public-projection-parity enforces.
+ */
+export declare const STICKER_ASSET_KINDS: readonly ["scan", "preview", "overlay", "geometry", "cutSvg", "thumbAtlas"];
+export type StickerAssetKind = (typeof STICKER_ASSET_KINDS)[number];
+/**
+ * Mint a short-lived read URL for one asset of one sheet or run.
+ *
+ * `runId` absent means the sheet's currently-accepted artifacts; present means
+ * that specific run's, which is what makes two runs comparable side by side —
+ * the reason runs keep their own artifacts rather than overwriting the sheet's.
+ *
+ * Returns `null` for "there is no such asset", which the route maps to a 404.
+ * An absent artifact is the normal state of an unfinished or failed run, so it
+ * must not read as an error.
+ */
+export declare function resolveStickerAssetUrl(input: {
+    sheetId: string;
+    kind: StickerAssetKind;
+    runId?: string;
+}): Promise<{
+    url: string;
+    expiresAt: Date;
+} | null>;
+export interface SheetUsageRow {
+    sheetId: string;
+    title: string;
+    bytes: number;
+    objects: number;
+}
+export interface StickerStorageUsage {
+    rows: SheetUsageRow[];
+    totalBytes: number;
+    totalObjects: number;
+}
+/**
+ * Stored bytes and object count per sheet, biggest first.
+ *
+ * 🛑 Object COUNT is reported beside bytes because GCS meters them separately
+ * (Class A writes, Class B reads). The sprite-atlas decision exists precisely
+ * because sixty thumbnails per run would spend that budget sixty times faster
+ * than the same pixels in one object — a meter showing only bytes would make
+ * undoing that look free.
+ *
+ * 🛑 Retention is manual by design: nothing auto-prunes, so any past run's
+ * overlay can still be opened and compared. That is only a safe default if the
+ * cost is VISIBLE rather than discovered, which is what this is for — Root
+ * Cause #104's first signal was a billing page.
+ *
+ * 🛑 One bucket listing per sheet, so this is deliberately NOT folded into the
+ * sheet list. Twenty sheets would be twenty `getFiles` calls on every page
+ * view; it is its own endpoint an operator opens.
+ */
+export declare function measureStickerStorage(sheetIds: readonly string[]): Promise<StickerStorageUsage>;