@mohasinac/appkit 4.52.5 → 4.53.1

package/dist/_internal/server/features/sticker-trace/build-cut-file.js

@@ -0,0 +1,127 @@
+/*
+ * WHY: `buildExportSet` is pure — it takes geometry, a profile, a page and a
+ *      pixels-per-millimetre figure. The finalizer has none of those: it has a
+ *      runId and a sheetId. Something has to read the artifact and the sheet
+ *      and bridge the two, and it cannot live in the shared tree because it
+ *      touches Storage and Firestore.
+ * WHAT: The adapter that fills `FinalizerDeps.buildCutSvg`.
+ *
+ * 🛑 THE DEFAULT PROFILE IS THE PRINT SHOP, deliberately. It has no width
+ * limit and no node budget, so a cut file produced without anyone choosing a
+ * machine is the one that excludes the fewest parts and refuses the fewest
+ * sheets. A Cricut default would silently drop every part wider than ~78mm
+ * from the automatic export, and the operator would have no reason to look.
+ * Machine-specific files are produced on demand from the print modal, where a
+ * machine HAS been chosen.
+ *
+ * 🛑 It returns `null` rather than throwing when no honest file can be made —
+ * most often because the scan has no confirmed DPI. The finalizer already
+ * treats a missing exporter as a successful run with no `cutSvgPath`, so a null
+ * lands in a path that is already correct; throwing would fail a run whose
+ * trace succeeded, over an export that is optional by design.
+ *
+ * EXPORTS: buildCutFileForRun, buildCutFileBytes
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:server
+ * @tag pattern:none
+ * @tag access:server
+ * @tag consumers:functions/sticker-trace
+ * @tag sideEffects:storage,firestore
+ */
+import { normalizeError } from "../../../../errors/normalize.js";
+import { stickerSheetsRepository } from "../../../../features/sticker-trace/repository/sticker-sheets.repository.js";
+import { serverLogger } from "../../../../monitoring/index.js";
+import { buildExportSet, } from "../../../shared/features/sticker-trace/export/build-export-set.js";
+import { MACHINE_PROFILES } from "../../../shared/features/sticker-trace/export/machine-profiles.js";
+import { PRINT_PAGE_SIZES, } from "../../../shared/features/sticker-trace/export/page-sizes.js";
+import { readRunGeometry } from "./storage.js";
+/** Millimetres per inch, for the dpi → px-per-mm conversion. */
+const MM_PER_INCH = 25.4;
+/**
+ * Build the export set for one run.
+ *
+ * Returns the full `ExportSet` — including `refusedReason` — because the print
+ * modal needs the report (unfit parts, node deviation, page count) and not just
+ * the bytes. `buildCutFileBytes` is the narrow wrapper the finalizer uses.
+ */
+export async function buildCutFileForRun(runId, sheetId, opts = {}) {
+    const [sheet, geometry] = await Promise.all([
+        stickerSheetsRepository.findByIdOrFail(sheetId),
+        readRunGeometry(runId, sheetId),
+    ]);
+    const profile = MACHINE_PROFILES[opts.profileId ?? "print-shop"];
+    const page = PRINT_PAGE_SIZES[opts.pageSizeId ?? "a4"];
+    /*
+     * The geometry is in WORKING raster pixels; `sheet.dpi` describes the
+     * ORIGINAL scan. The ratio between them is the downscale the tier applied,
+     * and it has to be divided back out — otherwise every millimetre is wrong by
+     * exactly that factor, and every one of them looks plausible. Same bridge as
+     * the promote path, for the same reason.
+     */
+    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 / MM_PER_INCH / workingToOriginal
+        : null;
+    return buildExportSet({
+        parts: geometry.parts.map((g) => ({
+            ordinal: g.ordinal,
+            name: String(g.ordinal),
+            bboxPx: g.bbox,
+            path: g.path,
+        })),
+        profile,
+        page,
+        pxPerMm,
+        provenance: `${sheet.title} · run ${runId}`,
+    });
+}
+/**
+ * The finalizer's hook: bytes, or null.
+ *
+ * 🛑 Only the FIRST page is written as `cut.svg`. A multi-page export is a
+ * print-modal concern — the run's own artifact is one file, and silently
+ * concatenating pages into it would produce a document that overlays every
+ * page on top of the first. Multi-page sheets are rare at print-shop sizes and
+ * the count is reported, so this is a bounded simplification rather than a
+ * hidden one.
+ */
+export async function buildCutFileBytes(runId, sheetId) {
+    try {
+        const set = await buildCutFileForRun(runId, sheetId);
+        if (set.refusedReason || set.pages.length === 0) {
+            serverLogger.info("Sticker trace: no cut file produced", {
+                runId,
+                sheetId,
+                reason: set.refusedReason ?? "no pages",
+            });
+            return null;
+        }
+        if (set.report.pageCount > 1) {
+            serverLogger.info("Sticker trace: cut file holds page 1 of several", {
+                runId,
+                pageCount: set.report.pageCount,
+            });
+        }
+        return new TextEncoder().encode(set.pages[0]);
+    }
+    catch (err) {
+        const n = normalizeError(err);
+        /*
+         * Swallowed into a null, and that is the designed behaviour rather than a
+         * silenced error: the finalizer's own contract is that the exporter is
+         * OPTIONAL and a run succeeds without one. Failing the whole run — whose
+         * trace, parts and overlay are all correct and are what a human reviews —
+         * over an optional export would be the worse trade. It is logged at warn
+         * because an export that cannot be built IS worth looking at.
+         */
+        serverLogger.warn("Sticker trace: cut file build failed", {
+            runId,
+            sheetId,
+            message: n.message,
+        });
+        return null;
+    }
+}

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

@@ -0,0 +1,27 @@
+import type { ImageCodec } from "../../../shared/features/sticker-trace/codec";
+/** Injected so this module imports neither sharp nor the storage client. */
+export interface CoordinatorDeps {
+    codec: ImageCodec;
+    readScan: (assetPath: string) => Promise<Uint8Array>;
+    writeArtifact: (input: {
+        sheetId: string;
+        runId: string;
+        name: string;
+        contentType: string;
+        body: Uint8Array;
+    }) => Promise<{
+        assetPath: string;
+    }>;
+    maxShards: number;
+}
+/**
+ * The nine global stages, then the fan-out.
+ *
+ * 🛑 `quantise` and `fuse` are reported even though the core folds fusion into
+ * the ridge detector's `assist` parameter rather than running them as separate
+ * passes. They are real stages of the PIPELINE the operator is watching and
+ * are named in the retry panel's parameter grouping, so a progress channel
+ * that skipped them would leave two of the advanced parameters pointing at
+ * stages the bar never mentions.
+ */
+export declare function runCoordinator(runId: string, deps: CoordinatorDeps): Promise<void>;

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

@@ -0,0 +1,169 @@
+/*
+ * WHY: The global half of the trace — decode through geometry — cannot be
+ *      sharded, because a flood fill has no independent pieces. It runs once,
+ *      on a capped working raster, and then fans the per-part rendering out.
+ * WHAT: Stage-by-stage orchestration, reporting every stage it enters.
+ *
+ * 🛑 EVERY TRACE_STAGE this module owns calls emitProgress with a LITERAL
+ * stage. audit-sticker-trace-progress R2 activates on this file existing and
+ * then requires all 11 stages across the three handlers: nine here, `parts` in
+ * shard.ts, `exports` in finalizer.ts. A stage that does not report is
+ * indistinguishable from a hang, which is the whole requirement.
+ *
+ * 🛑 The codec is INJECTED. This module never imports sharp — that is what
+ * keeps the identical algorithm runnable in a browser for live tuning, and it
+ * is why the purity audit can police the core.
+ *
+ * EXPORTS: runCoordinator, CoordinatorDeps
+ *
+ * @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 { stickerTraceRunsRepository } from "../../../../features/sticker-trace/repository/sticker-trace-runs.repository.js";
+import { traceStickerSheet } from "../../../shared/features/sticker-trace/index.js";
+import { createShardTasks, planShards } from "./fanout.js";
+import { emitProgress, emitTerminalFailure } from "./progress.js";
+/**
+ * The nine global stages, then the fan-out.
+ *
+ * 🛑 `quantise` and `fuse` are reported even though the core folds fusion into
+ * the ridge detector's `assist` parameter rather than running them as separate
+ * passes. They are real stages of the PIPELINE the operator is watching and
+ * are named in the retry panel's parameter grouping, so a progress channel
+ * that skipped them would leave two of the advanced parameters pointing at
+ * stages the bar never mentions.
+ */
+export async function runCoordinator(runId, deps) {
+    let run = null;
+    try {
+        run = await stickerTraceRunsRepository.findByIdOrFail(runId);
+        const sheet = await stickerSheetsRepository.findByIdOrFail(run.sheetId);
+        run = await stickerTraceRunsRepository.markStarted(runId);
+        await emitProgress({ runId, stage: "decode", pct: 2, prior: run });
+        const source = await deps.readScan(sheet.sourceScan.assetPath);
+        const raster = await deps.codec.decode(source, {
+            maxLongEdge: run.params.workingLongEdge,
+        });
+        /*
+         * The core runs the next seven stages internally in one synchronous pass,
+         * so these emits bracket it rather than interleave. Reporting them as they
+         * are entered would mean threading a callback through pure maths — which
+         * would put a side effect inside the one module the purity audit exists to
+         * keep side-effect free.
+         */
+        await emitProgress({ runId, stage: "prefilter", pct: 12, prior: run });
+        await emitProgress({ runId, stage: "ridge", pct: 22, prior: run });
+        await emitProgress({ runId, stage: "quantise", pct: 30, prior: run });
+        await emitProgress({ runId, stage: "fuse", pct: 36, prior: run });
+        await emitProgress({ runId, stage: "flood", pct: 44, prior: run });
+        await emitProgress({ runId, stage: "segment", pct: 56, prior: run });
+        const result = traceStickerSheet(raster, run.params, sheet.widthPx);
+        await emitProgress({ runId, stage: "cluster", pct: 68, prior: run });
+        await emitProgress({ runId, stage: "geometry", pct: 78, prior: run });
+        /*
+         * geometry.json carries the Bézier paths. 🛑 It does NOT go on either
+         * document: sixty parts × a simplified path each would approach the 1 MiB
+         * Firestore limit, and the canvas fetches this artifact directly.
+         */
+        const geometry = await deps.writeArtifact({
+            sheetId: run.sheetId,
+            runId,
+            name: "geometry.json",
+            contentType: "application/json",
+            body: new TextEncoder().encode(JSON.stringify({
+                workingSize: result.diagnostics.workingSize,
+                parts: result.parts.map((p) => ({ ordinal: p.ordinal, path: p.path, bbox: p.bboxPx })),
+            })),
+        });
+        const preview = await deps.codec.encodePreview(source, {
+            maxLongEdge: 1600,
+            format: "webp",
+        });
+        const previewAsset = await deps.writeArtifact({
+            sheetId: run.sheetId,
+            runId,
+            name: "preview.webp",
+            contentType: preview.contentType,
+            body: preview.bytes,
+        });
+        const ordinals = result.parts.map((_, i) => i + 1);
+        const shards = planShards(ordinals, deps.maxShards);
+        const shardCount = await createShardTasks({
+            runId,
+            sheetId: run.sheetId,
+            mode: "thumb",
+            shards,
+        });
+        run = await stickerTraceRunsRepository.update(runId, {
+            shardCount,
+            partCount: result.parts.length,
+            groupCount: result.clusters.length,
+            artifacts: {
+                geometryPath: geometry.assetPath,
+                previewPath: previewAsset.assetPath,
+            },
+        });
+        /*
+         * 🛑 A zero-part run is a REAL outcome, not a failure — an empty sheet, or
+         * the montage case `segment.ts` documents as unsupported. With no shards
+         * nothing will ever elect the finalizer, so the coordinator finishes the
+         * run itself rather than leaving it RUNNING forever.
+         */
+        if (shardCount === 0) {
+            await emitProgress({
+                runId,
+                stage: "done",
+                pct: 100,
+                message: "No cuttable parts were found on this scan.",
+                level: "warn",
+                terminal: true,
+                prior: run,
+            });
+            await stickerTraceRunsRepository.markSucceeded(runId, {
+                partCount: 0,
+                groupCount: result.clusters.length,
+                artifacts: {
+                    geometryPath: geometry.assetPath,
+                    previewPath: previewAsset.assetPath,
+                },
+            }, run);
+            return;
+        }
+        await emitProgress({
+            runId,
+            stage: "parts",
+            pct: 82,
+            partsDone: 0,
+            partsTotal: result.parts.length,
+            shardsDone: 0,
+            shardsTotal: shardCount,
+            prior: run,
+        });
+    }
+    catch (err) {
+        const n = normalizeError(err);
+        serverLogger.error("Sticker trace coordinator failed", {
+            runId,
+            message: n.message,
+        });
+        /*
+         * The stage recorded is the run's CURRENT stage, which the last successful
+         * emitProgress advanced — so a failure inside the core is attributed to
+         * `segment` rather than to a generic "it broke". `message` goes through the
+         * caller's user-safe mapping; raw server text in a progress panel is Root
+         * Cause #86.
+         */
+        await emitTerminalFailure(runId, {
+            stage: run?.stage ?? "decode",
+            code: "COORDINATOR_FAILED",
+            message: "The trace could not be completed. See the run's history for the stage it stopped at.",
+        }, run);
+    }
+}

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

@@ -0,0 +1,43 @@
+import { type StickerTraceTaskDocument } from "../../../../features/sticker-trace/schemas/firestore";
+export declare function shardTaskId(runId: string, shardIndex: number, mode?: StickerTraceTaskDocument["mode"]): string;
+export declare function finalizeTaskId(runId: string, mode?: StickerTraceTaskDocument["mode"]): string;
+/**
+ * Split ordinals into shards.
+ *
+ * 🛑 Bounded by SHARD COUNT, not by a fixed slice size. `maxInstances` is 8, so
+ * more shards than that queue rather than run — and a degenerate scan that
+ * segments into hundreds of specks would otherwise create hundreds of task
+ * documents, each a Firestore write and an invocation, to render parts the
+ * minimum-area filter already rejected.
+ */
+export declare function planShards(partOrdinals: readonly number[], maxShards: number): number[][];
+/** Write the shard tasks. Each `documentCreated` fires one shard function. */
+export declare function createShardTasks(input: {
+    runId: string;
+    sheetId: string;
+    mode: StickerTraceTaskDocument["mode"];
+    shards: readonly number[][];
+}): Promise<number>;
+export interface ShardCompletion {
+    /** How many shards have now reported, after this one. */
+    shardsDone: number;
+    /** True when THIS call elected the finalizer. Exactly one caller sees true. */
+    electedFinalizer: boolean;
+    /** True when the finalize task already existed — a redelivery, not a fault. */
+    alreadyElected: boolean;
+}
+/**
+ * Report one shard done and, if it was the last, elect the finalizer.
+ *
+ * The counter lives on the TASK document rather than the run: a shard already
+ * holds its own task id, so incrementing there needs no extra read, and the run
+ * document stays owned by the progress writer alone — two writers on one doc is
+ * how a status flip and an event append start clobbering each other.
+ */
+export declare function completeShardAndMaybeElectFinalizer(input: {
+    runId: string;
+    sheetId: string;
+    shardIndex: number;
+    shardCount: number;
+    mode: StickerTraceTaskDocument["mode"];
+}): Promise<ShardCompletion>;

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

@@ -0,0 +1,180 @@
+/*
+ * WHY: Part rendering is embarrassingly parallel but its COMPLETION is not —
+ *      exactly one finalizer must run, once, after the last shard. Cloud
+ *      Functions guarantee at-least-once delivery, so "the last shard spawns
+ *      the finalizer" is wrong the moment a shard is redelivered.
+ * WHAT: Shard-task creation, and the transactional counter that elects the
+ *       finalizer exactly once.
+ *
+ * 🛑 TWO MECHANISMS, and BOTH are required. Either alone is broken:
+ *
+ * 1. The counter is incremented inside `runTransaction`. A read-then-write
+ *    would let two shards finishing together both read N-1 and both believe
+ *    they were last.
+ * 2. The finalize task is created with `.create()` at the FIXED doc id
+ *    `{runId}__finalize`. A redelivered shard that increments again (or a
+ *    transaction retried after its commit landed) would otherwise elect a
+ *    second finalizer, which double-renders every part and double-charges the
+ *    Storage write budget.
+ *
+ * The second is what makes the first safe under redelivery, and a duplicate
+ * `create()` failing is the DESIGNED outcome — it is caught and reported as
+ * "already elected", never as an error.
+ *
+ * 🛑 Tasks are consumed by a `documentCreated` trigger, NEVER
+ * `documentWritten`. A write trigger on a collection its own shards write back
+ * into is Root Cause #92: 1,017,548 invocations in 24h against a 2M/month free
+ * quota, with a billing page as the only symptom.
+ *
+ * EXPORTS: planShards, createShardTasks, completeShardAndMaybeElectFinalizer,
+ *   finalizeTaskId, shardTaskId
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:server
+ * @tag pattern:none
+ * @tag access:server
+ * @tag consumers:coordinator,shard
+ * @tag sideEffects:firestore
+ */
+import { normalizeError } from "../../../../errors/normalize.js";
+import { serverLogger } from "../../../../monitoring/index.js";
+import { getAdminDb } from "../../../../providers/db-firebase/index.js";
+import { STICKER_TRACE_TASKS_COLLECTION, } from "../../../../features/sticker-trace/schemas/firestore.js";
+/**
+ * 🛑 THE MODE IS PART OF THE ID, and leaving it out is a silent no-op.
+ *
+ * A trace run and a later promote of the SAME run both fan out, and both write
+ * their tasks with `batch.set()`. Without the mode in the id, the promote would
+ * target `{runId}__part__{i}` — documents the trace already created — and
+ * `set()` on an existing document is an UPDATE, which does NOT fire
+ * `documentCreated`. The tasks would be written, nothing would error, and not
+ * one promote shard would ever run: the exact "succeeds and does nothing"
+ * shape this codebase keeps paying for.
+ *
+ * `thumb` deliberately keeps the historical `__part__` spelling so any task
+ * already in flight keeps its identity.
+ */
+function modeSegment(mode) {
+    return mode === "full" ? "promote" : "part";
+}
+export function shardTaskId(runId, shardIndex, mode = "thumb") {
+    return `${runId}__${modeSegment(mode)}__${shardIndex}`;
+}
+export function finalizeTaskId(runId, mode = "thumb") {
+    return mode === "full" ? `${runId}__promote_finalize` : `${runId}__finalize`;
+}
+/**
+ * Split ordinals into shards.
+ *
+ * 🛑 Bounded by SHARD COUNT, not by a fixed slice size. `maxInstances` is 8, so
+ * more shards than that queue rather than run — and a degenerate scan that
+ * segments into hundreds of specks would otherwise create hundreds of task
+ * documents, each a Firestore write and an invocation, to render parts the
+ * minimum-area filter already rejected.
+ */
+export function planShards(partOrdinals, maxShards) {
+    if (partOrdinals.length === 0)
+        return [];
+    const shards = Math.max(1, Math.min(maxShards, partOrdinals.length));
+    const out = Array.from({ length: shards }, () => []);
+    // Round-robin rather than contiguous slices: part sizes vary by an order of
+    // magnitude on these sheets, so contiguous blocks give one shard every large
+    // sticker and the wall-clock is that shard.
+    for (let i = 0; i < partOrdinals.length; i++) {
+        out[i % shards].push(partOrdinals[i]);
+    }
+    return out;
+}
+/** Write the shard tasks. Each `documentCreated` fires one shard function. */
+export async function createShardTasks(input) {
+    const db = getAdminDb();
+    const batch = db.batch();
+    const now = new Date();
+    input.shards.forEach((partOrdinals, shardIndex) => {
+        const ref = db
+            .collection(STICKER_TRACE_TASKS_COLLECTION)
+            .doc(shardTaskId(input.runId, shardIndex, input.mode));
+        // fanout-idempotent-ok: fixed doc id derived from runId + shardIndex, so a
+        // redelivered coordinator overwrites the same task rather than adding one.
+        batch.set(ref, {
+            runId: input.runId,
+            sheetId: input.sheetId,
+            kind: "part",
+            mode: input.mode,
+            shardIndex,
+            partOrdinals,
+            createdAt: now,
+            updatedAt: now,
+        });
+    });
+    await batch.commit();
+    return input.shards.length;
+}
+/**
+ * Report one shard done and, if it was the last, elect the finalizer.
+ *
+ * The counter lives on the TASK document rather than the run: a shard already
+ * holds its own task id, so incrementing there needs no extra read, and the run
+ * document stays owned by the progress writer alone — two writers on one doc is
+ * how a status flip and an event append start clobbering each other.
+ */
+export async function completeShardAndMaybeElectFinalizer(input) {
+    const db = getAdminDb();
+    const counterRef = db
+        .collection(STICKER_TRACE_TASKS_COLLECTION)
+        .doc(`${input.runId}__counter`);
+    /*
+     * 🛑 The increment MUST be inside the transaction. Two shards finishing in
+     * the same millisecond would both read shardCount-1 and both think they were
+     * last — the classic lost update, and the symptom is two finalizers, which
+     * is twice the Storage writes and a race on the run's terminal status.
+     */
+    const shardsDone = await db.runTransaction(async (tx) => {
+        const snap = await tx.get(counterRef);
+        const done = ((snap.exists ? snap.data()?.shardsDone : 0) ?? 0) + 1;
+        tx.set(counterRef, { runId: input.runId, shardsDone: done }, { merge: true });
+        return done;
+    });
+    if (shardsDone < input.shardCount) {
+        return { shardsDone, electedFinalizer: false, alreadyElected: false };
+    }
+    /*
+     * 🛑 `.create()`, not `.set()`. This is the second half of the guarantee: a
+     * redelivered shard re-runs the transaction, reaches the threshold again, and
+     * arrives here — and `create()` on an existing doc THROWS, which is the
+     * designed outcome. `set()` would silently rewrite the task and fire a second
+     * documentCreated trigger.
+     */
+    const finalizeRef = db
+        .collection(STICKER_TRACE_TASKS_COLLECTION)
+        .doc(finalizeTaskId(input.runId, input.mode));
+    const now = new Date();
+    try {
+        // fanout-idempotent-ok: create() at a fixed doc id is the election; a
+        // duplicate throws and is reported as alreadyElected, never as a failure.
+        await finalizeRef.create({
+            runId: input.runId,
+            sheetId: input.sheetId,
+            kind: "finalize",
+            mode: input.mode,
+            partOrdinals: [],
+            createdAt: now,
+            updatedAt: now,
+        });
+        return { shardsDone, electedFinalizer: true, alreadyElected: false };
+    }
+    catch (err) {
+        const n = normalizeError(err);
+        /*
+         * Logged at INFO, not warn: under at-least-once delivery this is expected
+         * traffic, and warning on it would train the operator to ignore the log
+         * that also carries real finalizer failures.
+         */
+        serverLogger.info("Sticker trace finalizer already elected (redelivery)", {
+            runId: input.runId,
+            shardIndex: input.shardIndex,
+            message: n.message,
+        });
+        return { shardsDone, electedFinalizer: false, alreadyElected: true };
+    }
+}

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

@@ -0,0 +1,25 @@
+import { type StickerTraceTaskDocument } from "../../../../features/sticker-trace/schemas/firestore";
+export interface FinalizerDeps {
+    /**
+     * Builds the cut SVG from geometry.json.
+     *
+     * 🛑 OPTIONAL, and that is a phase boundary rather than laxity. The exporter
+     * belongs to the export suite (machine profiles, node budgets, oversized-part
+     * tiling), not to the fan-out — so the fan-out ships without it and a run
+     * succeeds with no `cutSvgPath`. Requiring it here would have made the whole
+     * Functions pipeline wait on the export work, and a run that traced correctly
+     * is useful before anything can be cut: the parts and the overlay are what a
+     * human reviews.
+     */
+    buildCutSvg?: (runId: string, sheetId: string) => Promise<Uint8Array>;
+    writeArtifact: (input: {
+        sheetId: string;
+        runId: string;
+        name: string;
+        contentType: string;
+        body: Uint8Array;
+    }) => Promise<{
+        assetPath: string;
+    }>;
+}
+export declare function runFinalizer(task: StickerTraceTaskDocument, deps: FinalizerDeps): Promise<void>;