@hubfluencer/mcp 0.4.0 → 0.6.0

package/src/core.ts

@@ -10,7 +10,7 @@
 import { createHash } from "node:crypto";
 import { isAbsolute, resolve, sep } from "node:path";
 
-export type Kind = "short" | "editor";
+export type Kind = "short" | "editor" | "tracking" | "slider";
 
 /**
  * True if `hostname` is an IP literal in a private, loopback, link-local, or
@@ -29,32 +29,92 @@ export function isPrivateOrMetadataHost(hostname: string): boolean {
 	if (zone !== -1) host = host.slice(0, zone);
 
 	// IPv4 dotted-quad.
+	const v4 = parseV4Octets(host);
+	if (v4) return isPrivateV4(v4[0], v4[1]);
+
+	if (!host.includes(":")) return false;
+
+	const v6 = parseIPv6Words(host);
+	if (!v6) return false;
+
+	// IPv4 can be smuggled through several IPv6 literal forms:
+	//   ::ffff:7f00:1          IPv4-mapped (hex words)
+	//   ::7f00:1               deprecated IPv4-compatible
+	//   64:ff9b::a9fe:a9fe     NAT64 well-known prefix
+	// Treat those by the embedded IPv4 range so private/metadata literals fail
+	// closed while public mapped addresses (e.g. ::ffff:8.8.8.8) still pass.
+	const embeddedV4 = embeddedIPv4Octets(v6);
+	if (embeddedV4 && isPrivateV4(embeddedV4[0], embeddedV4[1])) return true;
+
+	if (v6.every((word) => word === 0)) return true; // unspecified
+	if (v6.slice(0, 7).every((word) => word === 0) && v6[7] === 1) {
+		return true; // loopback
+	}
+	// fc00::/7 (unique-local) and fe80::/10 (link-local).
+	if ((v6[0] & 0xfe00) === 0xfc00) return true;
+	if ((v6[0] & 0xffc0) === 0xfe80) return true;
+	return false;
+}
+
+function parseV4Octets(host: string): number[] | undefined {
 	const v4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
-	if (v4) {
-		const o = v4.slice(1).map(Number);
-		if (o.some((n) => n > 255)) return false; // not a valid IPv4 literal
-		return isPrivateV4(o[0], o[1]);
-	}
-
-	// IPv6 (anything with a colon). Normalize away an IPv4-mapped suffix first.
-	if (host.includes(":")) {
-		// ::ffff:a.b.c.d / ::a.b.c.d — judge by the embedded IPv4.
-		const mapped = /(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(host);
-		if (mapped) {
-			const o = mapped[1].split(".").map(Number);
-			if (!o.some((n) => n > 255) && isPrivateV4(o[0], o[1])) {
-				return true;
-			}
-		}
-		if (host === "::1" || host === "::") return true; // loopback / unspecified
-		if (host === "::ffff:0:0") return true;
-		// fc00::/7 (unique-local) and fe80::/10 (link-local).
-		if (/^f[cd]/.test(host)) return true;
-		if (/^fe[89ab]/.test(host)) return true;
-		return false;
+	if (!v4) return undefined;
+	const octets = v4.slice(1).map(Number);
+	return octets.some((n) => n > 255) ? undefined : octets;
+}
+
+function parseIPv6Words(host: string): number[] | undefined {
+	if (host.includes(".")) {
+		const lastColon = host.lastIndexOf(":");
+		if (lastColon === -1) return undefined;
+		const v4 = parseV4Octets(host.slice(lastColon + 1));
+		if (!v4) return undefined;
+		host = `${host.slice(0, lastColon)}:${((v4[0] << 8) | v4[1]).toString(16)}:${((v4[2] << 8) | v4[3]).toString(16)}`;
 	}
 
-	return false;
+	const halves = host.split("::");
+	if (halves.length > 2) return undefined;
+
+	const head = splitIPv6Half(halves[0]);
+	const tail = halves.length === 2 ? splitIPv6Half(halves[1]) : [];
+	if (!head || !tail) return undefined;
+
+	if (halves.length === 1) return head.length === 8 ? head : undefined;
+
+	const missing = 8 - head.length - tail.length;
+	if (missing < 1) return undefined;
+	return [...head, ...Array(missing).fill(0), ...tail];
+}
+
+function splitIPv6Half(half: string): number[] | undefined {
+	if (half === "") return [];
+	const words = half.split(":");
+	const parsed: number[] = [];
+	for (const word of words) {
+		if (!/^[0-9a-f]{1,4}$/.test(word)) return undefined;
+		parsed.push(Number.parseInt(word, 16));
+	}
+	return parsed;
+}
+
+function embeddedIPv4Octets(v6: number[]): number[] | undefined {
+	const firstFiveZero = v6.slice(0, 5).every((word) => word === 0);
+	if (firstFiveZero && v6[5] === 0xffff) return wordsToV4(v6[6], v6[7]);
+
+	const firstSixZero = v6.slice(0, 6).every((word) => word === 0);
+	if (firstSixZero && (v6[6] !== 0 || v6[7] !== 0)) {
+		return wordsToV4(v6[6], v6[7]);
+	}
+
+	const isNat64WellKnown =
+		v6[0] === 0x64 &&
+		v6[1] === 0xff9b &&
+		v6.slice(2, 6).every((word) => word === 0);
+	return isNat64WellKnown ? wordsToV4(v6[6], v6[7]) : undefined;
+}
+
+function wordsToV4(hi: number, lo: number): number[] {
+	return [hi >> 8, hi & 0xff, lo >> 8, lo & 0xff];
 }
 
 // Classifies an IPv4 address by its first two octets — all the blocked ranges
@@ -119,6 +179,84 @@ export function assertSafeFetchUrl(
 	);
 }
 
+// ── Retry / bounded backoff (idempotent GETs only) ───────────────────────────
+//
+// One transient blip — a dropped connection, a 502 from a load balancer, a brief
+// 429 — must not fail a whole tool call or, worse, an entire multi-minute poll
+// loop (every poll iteration is a fresh GET). These pure helpers decide *whether*
+// a failure is worth retrying and *how long* to wait; the actual loop lives in
+// client.ts (request) and uploads.ts (multipart parts). They are the single
+// source of truth for the policy, so it's unit-testable without the network.
+//
+// CRITICAL: retry is only ever applied to idempotent GETs (and the re-signed
+// multipart PUT of a single part, whose semantics are also idempotent). A
+// non-idempotent POST/PATCH/DELETE is NEVER auto-retried — a blind retry could
+// double-charge credits or fork a duplicate resource. That gate lives at the
+// call sites; these helpers only classify.
+
+export interface RetryOptions {
+	/** Total attempts including the first (so 3 = 1 try + 2 retries). */
+	attempts: number;
+	/** Base backoff in ms; attempt n waits ~baseMs * 2^(n-1) before retrying. */
+	baseMs: number;
+	/** Upper bound on any single backoff wait (before jitter). */
+	maxMs: number;
+}
+
+export const DEFAULT_RETRY: RetryOptions = {
+	attempts: 3,
+	baseMs: 300,
+	maxMs: 2000,
+};
+
+/**
+ * True for an HTTP status worth retrying on an idempotent GET: any 5xx (a
+ * transient server/proxy fault) or 429 (rate limited — back off and retry).
+ * 4xx other than 429 are the caller's problem (auth, not-found, validation) and
+ * must NOT be retried. NB: the AI-assist-quota 429 is a POST-only path handled by
+ * withAssist, so retrying a 429 here (GET-only) never collides with it.
+ */
+export function isRetryableStatus(status: number): boolean {
+	return status === 429 || (status >= 500 && status <= 599);
+}
+
+/**
+ * True for a thrown fetch error worth retrying: a network-layer failure
+ * (connection reset/refused, DNS blip — surfaced as a TypeError) or a request
+ * timeout (AbortSignal.timeout → TimeoutError; a plain AbortError is treated the
+ * same). Also honours an explicit `retryable:true` marker, which uploads.ts's
+ * putToPresignedUrl sets when it re-wraps a transient PUT failure into a friendly
+ * message (the original name would otherwise be lost). Our own pre-flight guards
+ * (assertSafeFetchUrl throws a plain Error with no name/marker) are deliberately
+ * NOT matched, so a refused SSRF/insecure URL fails immediately.
+ */
+export function isRetryableNetworkError(err: unknown): boolean {
+	if (!(err instanceof Error)) return false;
+	if ((err as { retryable?: boolean }).retryable === true) return true;
+	return (
+		err.name === "TypeError" ||
+		err.name === "TimeoutError" ||
+		err.name === "AbortError"
+	);
+}
+
+/**
+ * Backoff wait before the next attempt. Exponential (baseMs·2^(attempt-1)) capped
+ * at maxMs, then full-jittered into [half, full] so concurrent clients don't
+ * synchronize their retries. `attempt` is 1-based (the wait BEFORE retry #attempt,
+ * i.e. after the attempt-th failure). `rand` is injectable (defaults to
+ * Math.random) purely so the jitter is deterministic in tests.
+ */
+export function backoffDelayMs(
+	attempt: number,
+	opts: RetryOptions,
+	rand: () => number = Math.random,
+): number {
+	const capped = Math.min(opts.maxMs, opts.baseMs * 2 ** (attempt - 1));
+	// Full jitter: sleep a random duration in [capped/2, capped].
+	return Math.round(capped / 2 + rand() * (capped / 2));
+}
+
 export interface NormalizedStatus {
 	kind: Kind;
 	slug: string;
@@ -129,6 +267,41 @@ export interface NormalizedStatus {
 	error: string | null;
 }
 
+/** The structured fields of an API error envelope errMessage formats from. */
+export interface ApiErrorFields {
+	status: number;
+	code?: string;
+	message: string;
+	body?: unknown;
+}
+
+/**
+ * Formats a structured API error into a one-line agent-facing message.
+ *
+ * Lives here (not in index.ts) so the credit-field parsing — exactly the kind
+ * of string-shaped logic that silently regresses on a key rename — is unit
+ * testable: index.ts boots a live stdio MCP server at module load, so it can't
+ * be imported from a test (see this file's header). index.ts's errMessage is a
+ * thin wrapper that pulls these fields off a HubfluencerError and delegates here.
+ *
+ * For a 402 it surfaces the structured credit shortfall the server attaches so
+ * the agent can report exactly how short it is instead of a bare sentence. The
+ * canonical shape is required_credits/available_credits (tracking render +
+ * editor render); it falls back to the legacy required/available keys (older
+ * faceless 402s) so the counts always surface regardless of which the route
+ * returns.
+ */
+export function formatApiErrorMessage(f: ApiErrorFields): string {
+	const base = `API error (HTTP ${f.status}${f.code ? `, ${f.code}` : ""}): ${f.message}`;
+	const body = asRecord(f.body);
+	const req = body.required_credits ?? body.required;
+	const have = body.available_credits ?? body.available;
+	if (req != null || have != null) {
+		return `${base} (needs ${req ?? "?"} credits, have ${have ?? "?"}).`;
+	}
+	return base;
+}
+
 export function asRecord(v: unknown): Record<string, unknown> {
 	return v && typeof v === "object" ? (v as Record<string, unknown>) : {};
 }
@@ -156,6 +329,51 @@ export function normalizeStatus(
 		};
 	}
 
+	if (kind === "tracking") {
+		// The /tracking payload nests the render under `result` (status flows
+		// pending → processing → completed | failed); `source` is the upload. The
+		// burned-in MP4 URL lives at result.video_url. Before any render the result
+		// is null, so the project is non-terminal (the factory status carries the
+		// draft/processing/ready stage).
+		const result = asRecord(d.result);
+		const renderStatus = (result.status as string) ?? null;
+		const trackingUrl = (result.video_url as string) ?? null;
+		const ready = renderStatus === "completed" && Boolean(trackingUrl);
+		return {
+			kind,
+			slug,
+			stage: renderStatus ?? (d.status as string) ?? "unknown",
+			terminal: ready || renderStatus === "failed",
+			ready,
+			video_url: trackingUrl,
+			// The /tracking serializer (result_payload/1) emits error_message on the
+			// result — null until a render fails, the failure reason once it does —
+			// so a failed render surfaces its diagnostic here.
+			error: (result.error_message as string) ?? null,
+		};
+	}
+
+	if (kind === "slider") {
+		// The /sliders payload carries a top-level status (draft → processing →
+		// completed | failed) and per-slide image_urls (no single MP4). "completed"
+		// is written in one transaction once every slide is composited, so it always
+		// implies the slides are ready — mirroring the get_slider tool's contract.
+		// video_url stays null (a carousel is stills, not a video): wait_for_completion
+		// therefore never tries to download an MP4 for it, and callers read the slide
+		// URLs via get_slider. Kept consistent with the short/tracking shape so an
+		// agent can poll any kind through the same {stage,terminal,ready} fields.
+		const stage = (d.status as string) ?? "unknown";
+		return {
+			kind,
+			slug,
+			stage,
+			terminal: stage === "completed" || stage === "failed",
+			ready: stage === "completed",
+			video_url: null,
+			error: (d.error_message as string) ?? null,
+		};
+	}
+
 	// editor
 	const autopilot = (d.autopilot_status as string) ?? "unknown";
 	const renderStatus = (latest.status as string) ?? null;
@@ -176,6 +394,46 @@ export function normalizeStatus(
 	};
 }
 
+/**
+ * A discriminator folded into make_video's start idempotency key so a re-run
+ * AFTER a terminal failure genuinely restarts instead of replaying the failed
+ * run's cached 202 for 24h (the server caches idempotent POSTs). Mirrors the
+ * tracking render key's anti-replay design (which folds the failed result id):
+ *
+ *   - Not terminally failed (fresh draft, in flight, or completed) → "start", a
+ *     STABLE token. A transport retry of the same start therefore reuses the key
+ *     and dedupes (a double-start is also independently blocked server-side by
+ *     the already-running / 409 gate), so no double charge.
+ *   - Terminally failed → a signature of the per-attempt-varying render
+ *     id/version (plus the failure step/stage), so a re-run reads the failed
+ *     state, mints a DIFFERENT key, and re-enqueues the pipeline. Each subsequent
+ *     rendered failure changes latest_render.id, so successive retries keep
+ *     minting fresh keys rather than replaying a dead 202.
+ *
+ * Pure: derived solely from the status payload the caller already fetched.
+ */
+export function startStateDiscriminator(kind: Kind, data: unknown): string {
+	const d = asRecord(data);
+	const latest = asRecord(d.latest_render);
+	const renderSig = `${latest.id ?? ""}:${latest.version ?? ""}`;
+
+	if (kind === "short") {
+		const stage = (d.stage as string) ?? "";
+		if (stage !== "failed") return "start";
+		return `failed:${d.failed_stage ?? ""}:${renderSig}`;
+	}
+
+	// editor
+	const autopilot = (d.autopilot_status as string) ?? "";
+	const renderStatus = (latest.status as string) ?? "";
+	const failed =
+		autopilot === "failed" ||
+		autopilot === "cancelled" ||
+		renderStatus === "failed";
+	if (!failed) return "start";
+	return `failed:${autopilot}:${d.autopilot_error_step ?? ""}:${renderSig}`;
+}
+
 /** Stable idempotency key for a logical operation, so a retried call is safe. */
 export function idemKey(...parts: string[]): string {
 	return createHash("sha256")
@@ -184,6 +442,172 @@ export function idemKey(...parts: string[]): string {
 		.slice(0, 32);
 }
 
+// ── Editor idempotency-key compositions ───────────────────────────────────────
+//
+// These are the exact `idemKey()` argument lists the editor create/start handlers
+// send, extracted so the handler AND the golden-pin test share ONE definition.
+// Previously each was hand-copied into test/handlers.test.ts, so a handler-side
+// arg reorder/add/drop silently changed the real key while the test's private
+// copy did not move — the tripwire could not fire. Keep these pure (no I/O) and
+// keep the argument ORDER/SET/prefix stable: any change here shifts the hash and
+// must be reflected in the pinned golden. The two tools deliberately use different
+// field names (make_video: prompt/aspect · create_editor_ad: product_prompt/
+// export_aspect_ratio) and orders, so they are separate functions on purpose.
+
+/** make_video's editor draft-create key (`POST /editor`). */
+export interface MakeVideoEditorCreateArgs {
+	prompt: string;
+	product_subject?: string;
+	project_intent?: string;
+	language?: string;
+	aspect?: string;
+	voice_id?: string;
+	creative_format?: string;
+	visual_language?: string;
+	theme?: string;
+}
+
+export function makeVideoEditorCreateKey(a: MakeVideoEditorCreateArgs): string {
+	return idemKey(
+		"make-editor",
+		a.prompt,
+		a.product_subject ?? "",
+		a.project_intent ?? "",
+		a.language ?? "en",
+		a.aspect ?? "",
+		a.voice_id ?? "",
+		a.creative_format ?? "",
+		a.visual_language ?? "",
+		a.theme ?? "",
+	);
+}
+
+/**
+ * make_video's autopilot-start key (`POST /editor/:slug/autopilot`). Folds the
+ * create-affecting params AND an anti-replay `startState` discriminator so a
+ * re-run after a terminal failure mints a fresh key and re-enqueues instead of
+ * replaying the server's cached 202.
+ */
+export function makeVideoAutopilotKey(
+	slug: string,
+	a: MakeVideoEditorCreateArgs,
+	startState: string,
+): string {
+	return idemKey(
+		"autopilot",
+		slug,
+		a.prompt,
+		a.product_subject ?? "",
+		a.project_intent ?? "",
+		a.language ?? "en",
+		a.aspect ?? "",
+		a.voice_id ?? "",
+		a.creative_format ?? "",
+		a.visual_language ?? "",
+		a.theme ?? "",
+		startState,
+	);
+}
+
+/** create_editor_ad's draft-create and autopilot-start key argument set. */
+export interface EditorAdKeyArgs {
+	product_prompt?: string;
+	product_subject?: string;
+	project_intent?: string;
+	language?: string;
+	creative_format?: string;
+	visual_language?: string;
+	theme?: string;
+	voice_id?: string;
+	export_aspect_ratio?: string;
+}
+
+/** create_editor_ad's editor draft-create key (`POST /editor`). */
+export function editorAdCreateKey(a: EditorAdKeyArgs): string {
+	return idemKey(
+		"create-editor",
+		a.product_prompt ?? "",
+		a.product_subject ?? "",
+		a.project_intent ?? "",
+		a.language ?? "en",
+		a.creative_format ?? "",
+		a.visual_language ?? "",
+		a.theme ?? "",
+		a.voice_id ?? "",
+		a.export_aspect_ratio ?? "",
+	);
+}
+
+/**
+ * create_editor_ad's autopilot-start key (`POST /editor/:slug/autopilot`). Folds
+ * the create params (not a startState — this tool starts right after create, so
+ * there is no prior terminal state to guard against) so it tracks the inputs, not
+ * just the slug. Self-consistent per-tool only.
+ */
+export function editorAdAutopilotKey(slug: string, a: EditorAdKeyArgs): string {
+	return idemKey(
+		"autopilot",
+		slug,
+		a.product_prompt ?? "",
+		a.product_subject ?? "",
+		a.project_intent ?? "",
+		a.language ?? "en",
+		a.creative_format ?? "",
+		a.visual_language ?? "",
+		a.theme ?? "",
+		a.voice_id ?? "",
+		a.export_aspect_ratio ?? "",
+	);
+}
+
+/** create_slider's draft-create key (`POST /sliders`). */
+export interface SliderCreateKeyArgs {
+	prompt: string;
+	mode?: string;
+	template?: string;
+	slide_count?: number;
+	aspect_ratio?: string;
+	accent_color?: string;
+	text_position?: string;
+}
+
+export function sliderCreateKey(a: SliderCreateKeyArgs): string {
+	return idemKey(
+		"create-slider",
+		a.prompt,
+		a.mode ?? "",
+		a.template ?? "",
+		a.slide_count === undefined ? "" : String(a.slide_count),
+		a.aspect_ratio ?? "",
+		a.accent_color ?? "",
+		a.text_position ?? "",
+	);
+}
+
+/**
+ * set_scene_count's per-add idempotency key for `POST /editor/:slug/segments`.
+ * The server dedupes add-segment by Idempotency-Key for 24h (a replay returns the
+ * cached 201 and inserts NOTHING). Keying only on (slug, index) meant a
+ * grow→shrink→grow on the same draft inside that window reused the earlier round's
+ * keys — the second grow replayed the cached 201s and silently added no segments.
+ *
+ * A `nonce` freshly generated ONCE per set_scene_count call salts the key so every
+ * grow round mints keys the server has never seen, so each round actually adds its
+ * segments. This does NOT weaken safety: set_scene_count re-reads the live segment
+ * count each call and only issues adds for the shortfall, so a whole-tool retry is
+ * already convergent (a repeat with the same target adds nothing because
+ * target ≤ current); the per-add key only guards a single call's individual POSTs,
+ * which the client never auto-retries anyway. `index` keeps the keys within one
+ * call distinct.
+ */
+export function addSegmentKey(
+	slug: string,
+	index: number,
+	nonce: string,
+): string {
+	return idemKey("add-segment", slug, String(index), nonce);
+}
+
 /**
  * Confines a model-supplied save_path to an allowlisted output base so a
  * prompt-injected path can't write outside it (e.g. ~/.ssh/authorized_keys).
@@ -242,3 +666,188 @@ export function inferKind(prompt: string): Kind {
 		);
 	return wantsEditor ? "editor" : "short";
 }
+
+/**
+ * Client-side guards for the autopilot pre-launch inputs (language, brief).
+ * The flat-schema tools (e.g. make_video) can't carry .min/.max chains without
+ * tripping TS2589, so these run in-code and return a clean message (or null when
+ * valid) instead of relying on a raw Zod parse error. Kept in sync with the
+ * ranges the API enforces and the create_editor_draft schema (lang 2–10,
+ * product_prompt 10–5000).
+ */
+export function validateLanguage(language: string | undefined): string | null {
+	if (language === undefined) return null;
+	const len = language.trim().length;
+	if (len < 2 || len > 10) {
+		return 'language must be a 2–10 character code (e.g. "en", "fr").';
+	}
+	return null;
+}
+
+export function validateProductPrompt(
+	prompt: string | undefined,
+): string | null {
+	// A trimmed-empty string is a no-op on every path the server exposes:
+	// pre-launch override handling drops blank values (leave the stored value
+	// untouched) and the editor prompt is valid when blank, so treat "" the same
+	// as undefined. Still reject 1–9 non-blank chars (too short to be a brief).
+	if (prompt === undefined) return null;
+	const len = prompt.trim().length;
+	if (len === 0) return null;
+	if (len < 10 || len > 5000) {
+		return "product_prompt, when provided, must be 10–5000 characters.";
+	}
+	return null;
+}
+
+/**
+ * Guards make_video's `kind`. It is a flat z.string() (the flat-schema TS2589
+ * constraint again), so validate it in code instead of silently inferring: a
+ * typo or an unsupported kind ("slider"/"tracking") would otherwise fall through
+ * to inferKind and spend on the wrong product. Accepts the documented values
+ * ("short", "editor", "auto") and undefined (→ infer); rejects everything else
+ * with a message that names the allowed values and the right tool to use.
+ */
+export function validateKind(kind: string | undefined): string | null {
+	if (
+		kind === undefined ||
+		kind === "short" ||
+		kind === "editor" ||
+		kind === "auto"
+	) {
+		return null;
+	}
+	return (
+		`kind must be one of: short, editor, auto (got "${kind}"). ` +
+		"Use create_slider for carousels or create_tracking_video for tracking overlays."
+	);
+}
+
+// ── create_tracking_video orchestration (pure decision logic) ────────────────
+//
+// The create_tracking_video handler in index.ts is one long async body that
+// interleaves I/O (create, upload, poll, render) with non-trivial branching:
+// resume-vs-fresh, whether the existing source is still live, whether to submit
+// a render, and which idempotency keys to mint. importing index.ts to unit-test
+// that branching is a non-starter (it boots a live stdio MCP server at module
+// load — see this file's header), so the branching is extracted here as pure
+// functions and the handler just calls them. Keeping these side-effect-free also
+// makes the safety-critical render-key derivation (anti-replay-of-a-dead-202)
+// directly testable.
+
+/** The shape of GET /tracking/:slug the orchestration needs to reason about. */
+export interface TrackingSnapshot {
+	source: { status: string } | null;
+	result: { id?: number; status: string; video_url?: string | null } | null;
+}
+
+/** The create_tracking_video inputs that steer the orchestration. */
+export interface TrackingArgs {
+	video_path?: string;
+	slug?: string;
+	classes?: number[];
+	color?: number[];
+}
+
+export interface TrackingPlan {
+	/**
+	 * Stable idempotency anchor for the create POST and the base from which the
+	 * render key is derived. On a resume it's keyed on the slug; on a fresh call
+	 * it folds in a per-invocation nonce so two runs over the SAME local clip path
+	 * within the 24h idempotency window fork distinct projects instead of the
+	 * second replaying the first's cached 201 (and appending an upload+render to
+	 * the stale project). See index.ts for the full rationale.
+	 */
+	idemBase: string;
+	/**
+	 * True when the project already has a source row that is NOT `failed`.
+	 * EditorUpload statuses are pending|processing|ready|failed; only `failed` is
+	 * unusable. pending/processing are progressing toward ready (the API now
+	 * surfaces an in-flight source instead of hiding it), so a live source means
+	 * "do NOT re-upload — just wait for it", never "re-upload".
+	 */
+	hasLiveSource: boolean;
+	/** True when the caller supplied classes or color (a specific overlay config). */
+	configSupplied: boolean;
+	/**
+	 * True only when resuming a COMPLETED render AND new classes/color were given
+	 * — the caller wants a different overlay than the finished video, so we hand
+	 * the dedup decision to the backend (its combination_hash replays an identical
+	 * config free or charges 1 credit for a changed one).
+	 */
+	reRenderCompletedWithNewConfig: boolean;
+	/**
+	 * Whether to (re)submit POST /tracking/:slug/render: no result yet, the prior
+	 * one failed (and was refunded), or a completed render is being re-run with a
+	 * new config. A render already in flight (pending/processing) is left alone.
+	 */
+	shouldRender: boolean;
+	/**
+	 * Per-attempt discriminator folded into the render key so it diverges exactly
+	 * when a fresh enqueue is required: "retry:<id>" after a fail+refund (a NEW key
+	 * so the worker re-enqueues instead of replaying the dead 202), "rerender:<id>"
+	 * when re-rendering a completed result with new config, "new" otherwise.
+	 */
+	renderAttempt: string;
+	/** The idempotency key for the render POST (only meaningful when shouldRender). */
+	renderKey: string;
+}
+
+/**
+ * Computes the create_tracking_video orchestration plan from the (possibly null)
+ * current project snapshot and the call args. Pure: no I/O, no clock, no env.
+ *
+ * `freshNonce` is threaded in rather than generated here so the runtime can pass
+ * randomUUID() (each fresh call forks a new project) while tests pass a fixed
+ * sentinel (so the derived goldens are reproducible). It is ignored on a resume
+ * (the slug is the stable anchor across resumes).
+ */
+export function decideTrackingPlan(
+	existing: TrackingSnapshot | null,
+	args: TrackingArgs,
+	freshNonce: string,
+): TrackingPlan {
+	const idemBase = args.slug
+		? idemKey("tracking", args.slug)
+		: idemKey("tracking", args.video_path ?? "", freshNonce);
+
+	// A source is "live" (do not re-upload) when it exists and isn't failed. The
+	// API now surfaces pending/processing sources, so an in-flight upload is
+	// observed here and routed to wait-not-reupload rather than forking a
+	// duplicate EditorUpload.
+	const hasLiveSource =
+		existing?.source != null && existing.source.status !== "failed";
+
+	const resultStatus = existing?.result?.status;
+	const configSupplied = args.classes !== undefined || args.color !== undefined;
+	const reRenderCompletedWithNewConfig =
+		resultStatus === "completed" && configSupplied;
+	const shouldRender =
+		!existing?.result ||
+		resultStatus === "failed" ||
+		reRenderCompletedWithNewConfig;
+
+	const renderAttempt =
+		resultStatus === "failed"
+			? `retry:${existing?.result?.id ?? "unknown"}`
+			: reRenderCompletedWithNewConfig
+				? `rerender:${existing?.result?.id ?? "unknown"}`
+				: "new";
+	const renderKey = idemKey(
+		idemBase,
+		"render",
+		renderAttempt,
+		JSON.stringify(args.classes ?? null),
+		JSON.stringify(args.color ?? null),
+	);
+
+	return {
+		idemBase,
+		hasLiveSource,
+		configSupplied,
+		reRenderCompletedWithNewConfig,
+		shouldRender,
+		renderAttempt,
+		renderKey,
+	};
+}