@mohasinac/appkit 4.52.4 → 4.53.0

package/dist/features/sticker-trace/hooks/useStickerTraceProgress.js

@@ -0,0 +1,106 @@
+"use client";
+/*
+ * WHY: A trace takes minutes and fans out across shards. "Even if we fail we
+ *      know" was the requirement, and a spinner cannot express which of eleven
+ *      stages a run died in.
+ * WHAT: Subscribe to one run's live progress on sticker_trace/{runId}.
+ *
+ * 🛑 Built on `useRealtimeEvent`, not on a fresh RTDB subscription. That hook
+ * already owns the per-event custom-token sign-in, the reference-counted
+ * session lease, the timeout and the unsubscribe — and `useBulkEvent` is the
+ * precedent for wrapping it per feature. Rolling a second subscription would
+ * duplicate the lease accounting, which is the part that leaks a connection
+ * when it is wrong.
+ *
+ * 🛑 This is the LIVE bar only. The durable record is the run document's capped
+ * `events[]`, which is what a post-mortem reads weeks later — and the RTDB node
+ * is pruned at 60 minutes. A UI that treats this hook as the history will show
+ * nothing for any run older than an hour.
+ *
+ * EXPORTS: useStickerTraceProgress, StickerTraceProgress
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:feature
+ * @tag pattern:hook
+ * @tag access:client
+ * @tag consumers:sticker-trace/components
+ * @tag sideEffects:none
+ */
+import { useCallback, useMemo } from "react";
+import { useRealtimeEvent } from "../../../react/hooks/useRealtimeEvent.js";
+import { RealtimeEventType } from "../../../react/hooks/realtime-event-constants.js";
+import { RTDB_PATHS } from "../../../providers/db-firebase/rtdb-paths.js";
+const BLANK = {
+    stage: null,
+    pct: 0,
+    partsDone: null,
+    partsTotal: null,
+    shardsDone: null,
+    shardsTotal: null,
+    message: null,
+    level: null,
+    terminal: false,
+};
+/**
+ * 🛑 Every field is read DEFENSIVELY, and nulls are preserved rather than
+ * defaulted to 0.
+ *
+ * The writer is the coordinator, the shards and the finalizer — three
+ * processes, writing partial payloads at different stages (a shard reports
+ * parts and knows nothing about exports). Defaulting a missing `partsTotal` to
+ * 0 would render "12 of 0 parts", which reads as a bug in the tracer rather
+ * than as a field this stage does not populate. Null means "not applicable
+ * here", and the UI can omit the clause.
+ */
+function extract(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const r = raw;
+    const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : null);
+    const str = (v) => (typeof v === "string" && v.length > 0 ? v : null);
+    return {
+        stage: str(r.stage) ?? null,
+        pct: num(r.pct) ?? 0,
+        partsDone: num(r.partsDone),
+        partsTotal: num(r.partsTotal),
+        shardsDone: num(r.shardsDone),
+        shardsTotal: num(r.shardsTotal),
+        message: str(r.message),
+        level: str(r.level) ?? null,
+        terminal: r.terminal === true,
+    };
+}
+export function useStickerTraceProgress() {
+    const { data, subscribe, error } = useRealtimeEvent({
+        type: RealtimeEventType.STICKER_TRACE,
+        rtdbPath: RTDB_PATHS.STICKER_TRACE,
+        extractData: (raw) => extract(raw),
+        /*
+         * 20 minutes. The channel's own prune window is 60, and a `max`-tier
+         * fan-out across sixty parts can run for several — so a short client
+         * timeout would report a dead run that is still working, which is the one
+         * false signal this channel exists to prevent. The run document remains
+         * authoritative either way.
+         */
+        timeoutMs: 20 * 60 * 1000,
+    });
+    const progress = data ?? BLANK;
+    /*
+     * The label names the STAGE, never just a percentage. "Processing 43%" is
+     * what a spinner says; "ridge 22%" is what lets an operator recognise that a
+     * halftone scan is stuck in the detector rather than in the upload.
+     */
+    const label = useMemo(() => {
+        if (!progress.stage)
+            return null;
+        const parts = progress.partsDone !== null && progress.partsTotal !== null
+            ? ` ${progress.partsDone}/${progress.partsTotal} parts`
+            : "";
+        const shards = progress.shardsDone !== null && progress.shardsTotal !== null
+            ? ` · shard ${progress.shardsDone}/${progress.shardsTotal}`
+            : "";
+        return `${progress.stage} ${progress.pct}%${parts}${shards}`;
+    }, [progress]);
+    const start = useCallback((runId, customToken) => subscribe(runId, customToken), [subscribe]);
+    return { progress, subscribe: start, label, error };
+}

package/dist/features/sticker-trace/repository/sticker-sheets.repository.d.ts

@@ -0,0 +1,113 @@
+import { BaseRepository, parseSieveDateValue, type SieveModel, type FirebaseSieveResult } from "../../../providers/db-firebase";
+import { type SheetArtifacts, type SheetPart, type StickerSheetDocument } from "../schemas/firestore";
+/** What a caller supplies to register a freshly uploaded scan. */
+export interface StickerSheetCreateInput {
+    title: string;
+    scanType: StickerSheetDocument["scanType"];
+    widthPx: number;
+    heightPx: number;
+    sourceScan: StickerSheetDocument["sourceScan"];
+    dpi?: number;
+    dpiSource?: StickerSheetDocument["dpiSource"];
+}
+export declare class StickerSheetsRepository extends BaseRepository<StickerSheetDocument> {
+    constructor();
+    /**
+     * The ONE create path, so a sheet cannot exist without its counters.
+     *
+     * `traceStatus` starts `queued` rather than absent: a Firestore equality
+     * cannot match a missing field, so a sheet with no status would be absent
+     * from its own admin list while rendering perfectly by id (Root Cause #101).
+     *
+     * Deliberately not `createWithId` — that does a read-after-write, costing a
+     * Firestore read on every create against Rule #6's budget, for a document
+     * this function already holds in full.
+     */
+    create(input: StickerSheetCreateInput): Promise<StickerSheetDocument>;
+    /**
+     * Accept a run's result as the sheet's current one.
+     *
+     * 🛑 `artifacts` is REPLACED, not merged. A promotion means "this run's
+     * output is what the sheet shows now", so carrying a previous run's
+     * `overlayPath` forward would leave the sheet pointing at an overlay drawn
+     * from different geometry than its own `parts` — two halves of two different
+     * runs, with nothing anywhere contradicting it (Root Cause #42's shape).
+     * The superseded run keeps its own artifacts on its own document; nothing is
+     * lost, and the history is what makes that safe.
+     */
+    promoteRun(sheetId: string, runId: string, result: {
+        parts: SheetPart[];
+        groupCount: number;
+        artifacts: SheetArtifacts;
+    }): Promise<StickerSheetDocument>;
+    /**
+     * Rename one part, or mark it a duplicate of another.
+     *
+     * Matched on `ordinal`, never on array index — removing a part shifts every
+     * later index by one, so an index-wise write renames the wrong sticker. Same
+     * rule as § "Lottery Config Writes" merges by `slotNumber`.
+     *
+     * An unknown ordinal is a no-op that throws rather than a silent miss: the
+     * caller named a part that is not on this sheet, and answering 200 to that
+     * is how a rename appears to work and does nothing (Root Cause #40).
+     */
+    updatePart(sheetId: string, ordinal: number, patch: Partial<Pick<SheetPart, "name" | "duplicateOf">>): Promise<StickerSheetDocument>;
+    listForAdmin(model: SieveModel): Promise<FirebaseSieveResult<StickerSheetDocument>>;
+    /**
+     * Every sheet's stored bytes, for the usage meter.
+     *
+     * `.select()` on the two size fields rather than a full read: the meter sums
+     * numbers and never renders a sheet's parts, and a full scan of documents
+     * carrying up to sixty `SheetPart` entries each is real payload for a figure
+     * that is two integers wide.
+     */
+    listSizes(): Promise<Array<{
+        id: string;
+        title: string;
+        bytes: number;
+    }>>;
+    /**
+     * 🛑 Every Timestamp field carries `parseSieveDateValue`.
+     *
+     * Without it a GTE/LTE filter reaches Firestore as an ISO *string* against a
+     * stored Timestamp, matches ZERO documents, and raises nothing — Root Cause
+     * #47, which cost 27 repository files to fix once.
+     */
+    static readonly SIEVE_FIELDS: {
+        id: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        title: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        scanType: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        traceStatus: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        activeRunId: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        partCount: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        createdAt: {
+            canFilter: boolean;
+            canSort: boolean;
+            parseValue: typeof parseSieveDateValue;
+        };
+        updatedAt: {
+            canFilter: boolean;
+            canSort: boolean;
+            parseValue: typeof parseSieveDateValue;
+        };
+    };
+}
+export declare const stickerSheetsRepository: StickerSheetsRepository;

package/dist/features/sticker-trace/repository/sticker-sheets.repository.js

@@ -0,0 +1,146 @@
+/*
+ * WHY: One scanned sheet, and the CURRENT accepted result for it. Every
+ *      attempt that produced that result lives in `stickerTraceRuns` — this
+ *      document only ever holds the one a human chose.
+ * WHAT: Reads, the create funnel, and promotion of a run's artifacts onto the
+ *       sheet.
+ *
+ * 🛑 This repository holds NO PII and declares no `piiFields`. A sticker sheet
+ * is an admin's own scan: the only person-shaped field anywhere near it is
+ * `PromotedArtifacts.by`, which is an Auth UID — the same thing every
+ * `actorUid` in § "Status History" is, and explicitly NOT PII there either.
+ * Declaring a `piiFields` list for a document with nothing to encrypt is the
+ * fiction Root Cause #50 is about: a named mechanism whose name is the only
+ * evidence it does anything.
+ *
+ * EXPORTS: StickerSheetsRepository, stickerSheetsRepository
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:feature
+ * @tag pattern:repository
+ * @tag access:server
+ * @tag consumers:sticker-trace/actions,api/admin/sticker-sheets
+ * @tag sideEffects:firestore
+ */
+import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase/index.js";
+import { generateStickerSheetId } from "../../../utils/id-generators.js";
+import { STICKER_SHEETS_COLLECTION, STICKER_SHEET_FIELDS, TraceRunStatusValues, } from "../schemas/firestore.js";
+export class StickerSheetsRepository extends BaseRepository {
+    constructor() {
+        super(STICKER_SHEETS_COLLECTION);
+    }
+    /**
+     * The ONE create path, so a sheet cannot exist without its counters.
+     *
+     * `traceStatus` starts `queued` rather than absent: a Firestore equality
+     * cannot match a missing field, so a sheet with no status would be absent
+     * from its own admin list while rendering perfectly by id (Root Cause #101).
+     *
+     * Deliberately not `createWithId` — that does a read-after-write, costing a
+     * Firestore read on every create against Rule #6's budget, for a document
+     * this function already holds in full.
+     */
+    async create(input) {
+        const id = generateStickerSheetId({ title: input.title });
+        const now = new Date();
+        const data = {
+            ...input,
+            traceStatus: TraceRunStatusValues.QUEUED,
+            partCount: 0,
+            groupCount: 0,
+            artifacts: {},
+            parts: [],
+            createdAt: now,
+            updatedAt: now,
+        };
+        await this.getCollection().doc(id).set(prepareForFirestore(data));
+        return { id, ...data };
+    }
+    /**
+     * Accept a run's result as the sheet's current one.
+     *
+     * 🛑 `artifacts` is REPLACED, not merged. A promotion means "this run's
+     * output is what the sheet shows now", so carrying a previous run's
+     * `overlayPath` forward would leave the sheet pointing at an overlay drawn
+     * from different geometry than its own `parts` — two halves of two different
+     * runs, with nothing anywhere contradicting it (Root Cause #42's shape).
+     * The superseded run keeps its own artifacts on its own document; nothing is
+     * lost, and the history is what makes that safe.
+     */
+    async promoteRun(sheetId, runId, result) {
+        return this.update(sheetId, {
+            activeRunId: runId,
+            traceStatus: TraceRunStatusValues.SUCCEEDED,
+            partCount: result.parts.length,
+            groupCount: result.groupCount,
+            parts: result.parts,
+            artifacts: result.artifacts,
+        });
+    }
+    /**
+     * Rename one part, or mark it a duplicate of another.
+     *
+     * Matched on `ordinal`, never on array index — removing a part shifts every
+     * later index by one, so an index-wise write renames the wrong sticker. Same
+     * rule as § "Lottery Config Writes" merges by `slotNumber`.
+     *
+     * An unknown ordinal is a no-op that throws rather than a silent miss: the
+     * caller named a part that is not on this sheet, and answering 200 to that
+     * is how a rename appears to work and does nothing (Root Cause #40).
+     */
+    async updatePart(sheetId, ordinal, patch) {
+        const sheet = await this.findByIdOrFail(sheetId);
+        const index = sheet.parts.findIndex((p) => p.ordinal === ordinal);
+        if (index === -1) {
+            throw new Error(`Sticker sheet ${sheetId} has no part with ordinal ${ordinal}`);
+        }
+        const parts = [...sheet.parts];
+        parts[index] = { ...parts[index], ...patch };
+        return this.update(sheetId, { parts });
+    }
+    async listForAdmin(model) {
+        return this.sieveQuery(model, StickerSheetsRepository.SIEVE_FIELDS, {
+            defaultPageSize: 25,
+            maxPageSize: 50,
+        });
+    }
+    /**
+     * Every sheet's stored bytes, for the usage meter.
+     *
+     * `.select()` on the two size fields rather than a full read: the meter sums
+     * numbers and never renders a sheet's parts, and a full scan of documents
+     * carrying up to sixty `SheetPart` entries each is real payload for a figure
+     * that is two integers wide.
+     */
+    async listSizes() {
+        const snap = await this.getCollection()
+            .select(STICKER_SHEET_FIELDS.TITLE, "sourceScan")
+            .get();
+        return snap.docs.map((doc) => {
+            const data = doc.data();
+            return {
+                id: doc.id,
+                title: data.title ?? doc.id,
+                bytes: data.sourceScan?.bytes ?? 0,
+            };
+        });
+    }
+}
+/**
+ * 🛑 Every Timestamp field carries `parseSieveDateValue`.
+ *
+ * Without it a GTE/LTE filter reaches Firestore as an ISO *string* against a
+ * stored Timestamp, matches ZERO documents, and raises nothing — Root Cause
+ * #47, which cost 27 repository files to fix once.
+ */
+StickerSheetsRepository.SIEVE_FIELDS = {
+    id: { canFilter: true, canSort: false },
+    title: { canFilter: true, canSort: true },
+    scanType: { canFilter: true, canSort: false },
+    traceStatus: { canFilter: true, canSort: false },
+    activeRunId: { canFilter: true, canSort: false },
+    partCount: { canFilter: true, canSort: true },
+    createdAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
+    updatedAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
+};
+export const stickerSheetsRepository = new StickerSheetsRepository();

package/dist/features/sticker-trace/repository/sticker-trace-runs.repository.d.ts

@@ -0,0 +1,132 @@
+import { BaseRepository, parseSieveDateValue, type SieveModel, type FirebaseSieveResult } from "../../../providers/db-firebase";
+import { type PromotedArtifacts, type RunArtifacts, type StickerTraceRunDocument, type TraceRunError, type TraceRunEvent } from "../schemas/firestore";
+export interface StickerTraceRunCreateInput {
+    sheetId: string;
+    /** 🛑 Mandatory. The reason history is worth keeping is being able to tell runs apart. */
+    name: string;
+    tier: StickerTraceRunDocument["tier"];
+    params: StickerTraceRunDocument["params"];
+    requestedBy: string;
+}
+export declare class StickerTraceRunsRepository extends BaseRepository<StickerTraceRunDocument> {
+    constructor();
+    /**
+     * A run is born `queued` with an empty event log and zeroed counts.
+     *
+     * Firestore assigns the id (the § "Slug Prefix System" convention for
+     * `carts` / `jobs` / `notifications`): a run carries a mandatory human NAME,
+     * which is what anyone reads, so a second slug prefix would add a parse
+     * surface and a collision story for no reader. The id appears only in a
+     * Storage path and an RTDB channel key.
+     */
+    create(input: StickerTraceRunCreateInput): Promise<StickerTraceRunDocument>;
+    /**
+     * Append one progress transition, FIFO-capped.
+     *
+     * 🛑 `arrayUnion` cannot enforce a cap, so this folds in memory and writes
+     * the whole array — the same constraint § "Status History" records, and the
+     * reason `prior` exists here: the coordinator and the finalizer each hold
+     * the run already, so threading it costs **zero extra reads**. Omitting it
+     * is legal and pays one read.
+     *
+     * 🛑 Truncation is RECORDED, never silent. `eventsTruncated` is what lets a
+     * reader say "earlier progress trimmed" instead of implying a `max`-tier run
+     * with sixty shards simply had ten events.
+     */
+    appendEvent(runId: string, event: TraceRunEvent, prior?: StickerTraceRunDocument | null): Promise<StickerTraceRunDocument>;
+    /** `queued` → `running`, stamping the clock the duration is measured from. */
+    markStarted(runId: string, shardCount?: number): Promise<StickerTraceRunDocument>;
+    /**
+     * Terminal success.
+     *
+     * `durationMs` is computed from the run's own `startedAt` rather than
+     * accepted from the caller — two call sites each subtracting their own pair
+     * of timestamps is how the number ends up meaning different things on
+     * different runs (Root Cause #75).
+     */
+    markSucceeded(runId: string, result: {
+        partCount: number;
+        groupCount: number;
+        artifacts: RunArtifacts;
+    }, prior?: StickerTraceRunDocument | null): Promise<StickerTraceRunDocument>;
+    /**
+     * Terminal failure, naming the stage it died in.
+     *
+     * 🛑 `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.
+     *
+     * Partial artifacts are KEPT when the caller has them: a run that failed at
+     * `parts` still produced a preview and an overlay, and those are exactly
+     * what makes the failure diagnosable.
+     */
+    markFailed(runId: string, error: TraceRunError, partial?: Partial<Pick<StickerTraceRunDocument, "artifacts" | "partCount" | "groupCount">>, prior?: StickerTraceRunDocument | null): Promise<StickerTraceRunDocument>;
+    /** Records that this run's full-resolution parts and exports now exist. */
+    markPromoted(runId: string, promoted: PromotedArtifacts): Promise<StickerTraceRunDocument>;
+    /**
+     * One sheet's attempt history, newest first.
+     *
+     * A single equality plus one `orderBy` on `createdAt`, which every document
+     * carries — `BaseRepository.create` writes it. Ordering by an OPTIONAL field
+     * (`startedAt`, `finishedAt`) would silently drop every queued run from its
+     * own history, which is Root Cause #100.
+     */
+    listBySheet(sheetId: string, limit?: number): Promise<StickerTraceRunDocument[]>;
+    listForAdmin(model: SieveModel): Promise<FirebaseSieveResult<StickerTraceRunDocument>>;
+    /** Every Timestamp field carries `parseSieveDateValue` — Root Cause #47. */
+    static readonly SIEVE_FIELDS: {
+        id: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        sheetId: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        name: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        tier: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        status: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        stage: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        requestedBy: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        partCount: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        durationMs: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        startedAt: {
+            canFilter: boolean;
+            canSort: boolean;
+            parseValue: typeof parseSieveDateValue;
+        };
+        finishedAt: {
+            canFilter: boolean;
+            canSort: boolean;
+            parseValue: typeof parseSieveDateValue;
+        };
+        createdAt: {
+            canFilter: boolean;
+            canSort: boolean;
+            parseValue: typeof parseSieveDateValue;
+        };
+    };
+}
+export declare const stickerTraceRunsRepository: StickerTraceRunsRepository;

package/dist/features/sticker-trace/repository/sticker-trace-runs.repository.js

@@ -0,0 +1,174 @@
+/*
+ * WHY: An attempt is a RECORD, not an overwrite. Tuning a halftone scan takes
+ *      several runs, and the whole value of keeping them is being able to ask
+ *      weeks later what run 2 did differently and which stage run 3 died in.
+ * WHAT: Create, the capped event log, terminal transitions, and per-sheet
+ *       history.
+ *
+ * 🛑 A finished run is never edited. `markSucceeded` / `markFailed` are the
+ * last writes it takes; a re-trace creates a NEW document. Promotion writes to
+ * the SHEET (`promoteRun`) plus this run's own `promoted` block, and nothing
+ * else about the run moves.
+ *
+ * Holds no PII — see the same note on `sticker-sheets.repository`.
+ *
+ * EXPORTS: StickerTraceRunsRepository, stickerTraceRunsRepository,
+ *   StickerTraceRunCreateInput
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:feature
+ * @tag pattern:repository
+ * @tag access:server
+ * @tag consumers:sticker-trace/actions,functions/sticker-trace
+ * @tag sideEffects:firestore
+ */
+import { BaseRepository, parseSieveDateValue, } from "../../../providers/db-firebase/index.js";
+import { RUN_EVENTS_MAX, STICKER_TRACE_RUNS_COLLECTION, STICKER_TRACE_RUN_FIELDS, TraceRunStatusValues, } from "../schemas/firestore.js";
+export class StickerTraceRunsRepository extends BaseRepository {
+    constructor() {
+        super(STICKER_TRACE_RUNS_COLLECTION);
+    }
+    /**
+     * A run is born `queued` with an empty event log and zeroed counts.
+     *
+     * Firestore assigns the id (the § "Slug Prefix System" convention for
+     * `carts` / `jobs` / `notifications`): a run carries a mandatory human NAME,
+     * which is what anyone reads, so a second slug prefix would add a parse
+     * surface and a collision story for no reader. The id appears only in a
+     * Storage path and an RTDB channel key.
+     */
+    async create(input) {
+        return super.create({
+            ...input,
+            status: TraceRunStatusValues.QUEUED,
+            stage: "queued",
+            events: [],
+            partCount: 0,
+            groupCount: 0,
+            artifacts: {},
+            promoted: null,
+        });
+    }
+    /**
+     * Append one progress transition, FIFO-capped.
+     *
+     * 🛑 `arrayUnion` cannot enforce a cap, so this folds in memory and writes
+     * the whole array — the same constraint § "Status History" records, and the
+     * reason `prior` exists here: the coordinator and the finalizer each hold
+     * the run already, so threading it costs **zero extra reads**. Omitting it
+     * is legal and pays one read.
+     *
+     * 🛑 Truncation is RECORDED, never silent. `eventsTruncated` is what lets a
+     * reader say "earlier progress trimmed" instead of implying a `max`-tier run
+     * with sixty shards simply had ten events.
+     */
+    async appendEvent(runId, event, prior) {
+        const current = prior !== undefined && prior !== null ? prior : await this.findByIdOrFail(runId);
+        const merged = [...(current.events ?? []), event];
+        const overflow = Math.max(0, merged.length - RUN_EVENTS_MAX);
+        return this.update(runId, {
+            events: overflow > 0 ? merged.slice(overflow) : merged,
+            ...(overflow > 0
+                ? { eventsTruncated: (current.eventsTruncated ?? 0) + overflow }
+                : {}),
+            stage: event.stage,
+        });
+    }
+    /** `queued` → `running`, stamping the clock the duration is measured from. */
+    async markStarted(runId, shardCount) {
+        return this.update(runId, {
+            status: TraceRunStatusValues.RUNNING,
+            startedAt: new Date(),
+            ...(shardCount !== undefined ? { shardCount } : {}),
+        });
+    }
+    /**
+     * Terminal success.
+     *
+     * `durationMs` is computed from the run's own `startedAt` rather than
+     * accepted from the caller — two call sites each subtracting their own pair
+     * of timestamps is how the number ends up meaning different things on
+     * different runs (Root Cause #75).
+     */
+    async markSucceeded(runId, result, prior) {
+        const current = prior !== undefined && prior !== null ? prior : await this.findByIdOrFail(runId);
+        const finishedAt = new Date();
+        return this.update(runId, {
+            status: TraceRunStatusValues.SUCCEEDED,
+            stage: "done",
+            finishedAt,
+            ...(current.startedAt
+                ? { durationMs: finishedAt.getTime() - current.startedAt.getTime() }
+                : {}),
+            ...result,
+        });
+    }
+    /**
+     * Terminal failure, naming the stage it died in.
+     *
+     * 🛑 `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.
+     *
+     * Partial artifacts are KEPT when the caller has them: a run that failed at
+     * `parts` still produced a preview and an overlay, and those are exactly
+     * what makes the failure diagnosable.
+     */
+    async markFailed(runId, error, partial, prior) {
+        const current = prior !== undefined && prior !== null ? prior : await this.findByIdOrFail(runId);
+        const finishedAt = new Date();
+        return this.update(runId, {
+            status: TraceRunStatusValues.FAILED,
+            stage: error.stage,
+            finishedAt,
+            ...(current.startedAt
+                ? { durationMs: finishedAt.getTime() - current.startedAt.getTime() }
+                : {}),
+            error,
+            ...(partial ?? {}),
+        });
+    }
+    /** Records that this run's full-resolution parts and exports now exist. */
+    async markPromoted(runId, promoted) {
+        return this.update(runId, { promoted });
+    }
+    /**
+     * One sheet's attempt history, newest first.
+     *
+     * A single equality plus one `orderBy` on `createdAt`, which every document
+     * carries — `BaseRepository.create` writes it. Ordering by an OPTIONAL field
+     * (`startedAt`, `finishedAt`) would silently drop every queued run from its
+     * own history, which is Root Cause #100.
+     */
+    async listBySheet(sheetId, limit = 50) {
+        const snap = await this.getCollection()
+            .where(STICKER_TRACE_RUN_FIELDS.SHEET_ID, "==", sheetId)
+            .orderBy(STICKER_TRACE_RUN_FIELDS.CREATED_AT, "desc")
+            .limit(limit)
+            .get();
+        return snap.docs.map((doc) => this.mapDoc(doc));
+    }
+    async listForAdmin(model) {
+        return this.sieveQuery(model, StickerTraceRunsRepository.SIEVE_FIELDS, {
+            defaultPageSize: 25,
+            maxPageSize: 50,
+        });
+    }
+}
+/** Every Timestamp field carries `parseSieveDateValue` — Root Cause #47. */
+StickerTraceRunsRepository.SIEVE_FIELDS = {
+    id: { canFilter: true, canSort: false },
+    sheetId: { canFilter: true, canSort: false },
+    name: { canFilter: true, canSort: true },
+    tier: { canFilter: true, canSort: false },
+    status: { canFilter: true, canSort: false },
+    stage: { canFilter: true, canSort: false },
+    requestedBy: { canFilter: true, canSort: false },
+    partCount: { canFilter: true, canSort: true },
+    durationMs: { canFilter: true, canSort: true },
+    startedAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
+    finishedAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
+    createdAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
+};
+export const stickerTraceRunsRepository = new StickerTraceRunsRepository();