@12ui/design 0.2.13 → 0.2.15

package/dist/branch-execution-types.d.ts

@@ -0,0 +1,54 @@
+import type { BranchAspect } from './branch-client.js';
+import type { BranchScope } from './branch-identity.js';
+import type { BranchDispatchEvent } from './branch-dispatch-loop.js';
+import type { BranchConversionSettings } from './branch-page-conversion.js';
+import type { BranchProgressPhase, BranchProgressScreen } from './branch-progress.js';
+import type { BranchCompletion } from './branch-run-record.js';
+import type { PackageProgressEvent } from './package-submission.js';
+/**
+ * The inputs and events of one branch run, in their own module so the phases
+ * that consume them — download, completion, the CLI — can import them without
+ * importing the orchestrator that drives them.
+ */
+export type BranchWinnerInput = {
+    kind: 'run';
+    runId: string;
+    slot: string;
+} | {
+    kind: 'image';
+    imagePath: string;
+    bytes: Uint8Array;
+    mediaType: 'image/png' | 'image/jpeg' | 'image/webp';
+    sha256: string;
+};
+export type BranchExecutionInputs = {
+    outDir: string;
+    scope: BranchScope;
+    concept: string;
+    winner: BranchWinnerInput;
+    aspect?: BranchAspect;
+    maxScreens?: number;
+    convert?: BranchConversionSettings;
+    idempotencyKey?: string;
+};
+export type BranchExecutionEvent = BranchDispatchEvent | {
+    kind: 'phase';
+    phase: string;
+    detail?: string;
+} | {
+    /** Published every loop turn so an observer always sees motion, not absence. */
+    kind: 'progress';
+    phase: BranchProgressPhase;
+    screens: BranchProgressScreen[];
+} | {
+    kind: 'package';
+    pageId: string;
+    progress: PackageProgressEvent;
+};
+export type BranchExecutionResult = {
+    completion: BranchCompletion;
+    completionPath: string;
+    /** Non-null when the run must exit non-zero. A parked partial run does not. */
+    failure: Error | null;
+};
+//# sourceMappingURL=branch-execution-types.d.ts.map

package/dist/branch-execution-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-execution-types.d.ts","sourceRoot":"","sources":["../src/branch-execution-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAC5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACtF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAEpE;;;;GAIG;AAEH,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC5C;IACA,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,UAAU,CAAC;IAClB,SAAS,EAAE,WAAW,GAAG,YAAY,GAAG,YAAY,CAAC;IACrD,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEJ,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,wBAAwB,CAAC;IACnC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAC5B,mBAAmB,GACnB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACjD;IACA,gFAAgF;IAChF,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,mBAAmB,CAAC;IAC3B,OAAO,EAAE,oBAAoB,EAAE,CAAC;CACjC,GACC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,oBAAoB,CAAA;CAAE,CAAC;AAExE,MAAM,MAAM,qBAAqB,GAAG;IAClC,UAAU,EAAE,gBAAgB,CAAC;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,OAAO,EAAE,KAAK,GAAG,IAAI,CAAC;CACvB,CAAC"}

package/dist/branch-execution-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=branch-execution-types.js.map

package/dist/branch-execution-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-execution-types.js","sourceRoot":"","sources":["../src/branch-execution-types.ts"],"names":[],"mappings":""}

package/dist/branch-execution.d.ts

@@ -0,0 +1,20 @@
+import { type TwelveUiBranchClient } from './branch-client.js';
+import { type BranchDispatchTuning } from './branch-dispatch-loop.js';
+import type { TwelveUiConversionPackageClient } from './package-client.js';
+import type { BranchExecutionEvent, BranchExecutionInputs, BranchExecutionResult } from './branch-execution-types.js';
+export type { BranchExecutionEvent, BranchExecutionInputs, BranchExecutionResult, BranchWinnerInput, } from './branch-execution-types.js';
+export declare const deriveBranchRunKey: (inputs: BranchExecutionInputs) => string;
+export declare const executeBranchRun: (args: {
+    branchClient: TwelveUiBranchClient;
+    packageClient?: TwelveUiConversionPackageClient;
+    inputs: BranchExecutionInputs;
+    origin: string;
+    resume?: boolean;
+    onEvent?: (event: BranchExecutionEvent) => void;
+    dispatch?: BranchDispatchTuning;
+    packageTimeoutMs?: number;
+    /** Pages converting at once. The account's admission cap is the real limit. */
+    pageConcurrency?: number;
+    signal?: AbortSignal;
+}) => Promise<BranchExecutionResult>;
+//# sourceMappingURL=branch-execution.d.ts.map

package/dist/branch-execution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-execution.d.ts","sourceRoot":"","sources":["../src/branch-execution.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,oBAAoB,CAAC;AA2B5B,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,2BAA2B,CAAC;AAgBnC,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,qBAAqB,CAAC;AAC3E,OAAO,KAAK,EACV,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,EACtB,MAAM,6BAA6B,CAAC;AAErC,YAAY,EACV,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,6BAA6B,CAAC;AAiBrC,eAAO,MAAM,kBAAkB,GAAI,QAAQ,qBAAqB,KAAG,MAQlE,CAAC;AAkCF,eAAO,MAAM,gBAAgB,GAAU,MAAM;IAC3C,YAAY,EAAE,oBAAoB,CAAC;IACnC,aAAa,CAAC,EAAE,+BAA+B,CAAC;IAChD,MAAM,EAAE,qBAAqB,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAC;IAChD,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+EAA+E;IAC/E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,KAAG,OAAO,CAAC,qBAAqB,CAwVhC,CAAC"}

package/dist/branch-execution.js

@@ -0,0 +1,380 @@
+import path from 'node:path';
+import { BranchApiError, } from './branch-client.js';
+import { branchConceptDigest, branchRunKey } from './branch-identity.js';
+import { buildCompletion, terminalFailure } from './branch-completion.js';
+import { createRunMaterializer } from './branch-materialize.js';
+import { branchScreenPath } from './branch-downloads.js';
+import { createBranchPageConversions } from './branch-page-conversion.js';
+import { invalidateConversionReceipts, readConversionReceipts, writeConversionReceipts, } from './conversion-receipt.js';
+import { BRANCH_PAGE_CONCURRENCY_DEFAULT } from './cli-progress.js';
+import { applyBranchEnvelope, normalizeBranchPlan, } from './branch-plan.js';
+import { branchProgressPath, branchProgressScreens, writeBranchProgress, } from './branch-progress.js';
+import { runBranchDispatch, } from './branch-dispatch-loop.js';
+import { BRANCH_ATTEMPT_FILENAME, BRANCH_PAGES_DIRECTORY, BRANCH_SCREENS_DIRECTORY, branchAttemptPath, branchCompletionPath, branchPlanPath, readBranchAttempt, readBranchCompletion, writeBranchAttempt, writeBranchCompletion, writeBranchPlanRecord, } from './branch-run-record.js';
+/**
+ * The whole branch choreography: claim, plan, dependency-ordered dispatch,
+ * download, per-page package conversion, sentinel. Everything mechanical lives
+ * here so the model's job collapses to choosing the winner, writing the
+ * concept, and picking the scope.
+ *
+ * The two halves overlap on purpose. A page's package depends on ITS OWN
+ * screens and nothing else, so a page whose screens land in the first wave
+ * starts converting while the rest of the run is still generating, and pages
+ * convert several at a time. Measured serially, the conversion half was 8m36 of
+ * a 12m25 four-page run while the account's admission slots sat idle.
+ */
+const BUILD_PLAN_RETRIES = 3;
+export const deriveBranchRunKey = (inputs) => (inputs.idempotencyKey ?? branchRunKey({
+    winner: inputs.winner.kind === 'run'
+        ? { runId: inputs.winner.runId, slot: inputs.winner.slot }
+        : { imageSha256: inputs.winner.sha256 },
+    concept: inputs.concept,
+    scope: inputs.scope,
+}));
+const claimBuildRun = async (args) => {
+    let lastError;
+    for (let attempt = 1; attempt <= BUILD_PLAN_RETRIES; attempt += 1) {
+        try {
+            return await args.client.startBuildRun({
+                concept: args.inputs.concept,
+                ...(args.inputs.aspect ? { aspect: args.inputs.aspect } : {}),
+                ...(args.inputs.winner.kind === 'run'
+                    ? { winner: { createRunId: args.inputs.winner.runId, slot: args.inputs.winner.slot } }
+                    : {
+                        referenceImage: {
+                            data: Buffer.from(args.inputs.winner.bytes).toString('base64'),
+                            mediaType: args.inputs.winner.mediaType,
+                            sha256: args.inputs.winner.sha256,
+                        },
+                    }),
+            }, args.runKey, args.signal);
+        }
+        catch (error) {
+            lastError = error;
+            // Planning failed before any image spend, so the same key may replay.
+            const retryable = error instanceof BranchApiError && error.code === 'build_plan_failed';
+            if (!retryable || attempt === BUILD_PLAN_RETRIES)
+                throw error;
+        }
+    }
+    throw lastError;
+};
+export const executeBranchRun = async (args) => {
+    const emit = args.onEvent ?? (() => undefined);
+    const { inputs } = args;
+    const outDir = path.resolve(inputs.outDir);
+    const attemptFile = branchAttemptPath(outDir);
+    const completionFile = branchCompletionPath(outDir);
+    const screensDirectory = path.join(outDir, BRANCH_SCREENS_DIRECTORY);
+    const pagesDirectory = path.join(outDir, BRANCH_PAGES_DIRECTORY);
+    const runKey = deriveBranchRunKey(inputs);
+    const startedAt = new Date().toISOString();
+    const progressFile = branchProgressPath(outDir);
+    // Progress writes are serialized AND coalesced: the file is the one thing
+    // another session polls, so it must never be observed half-written, and a
+    // fast loop must not queue an unbounded backlog of stale snapshots. Only the
+    // newest pending snapshot is ever written.
+    let pendingProgress = null;
+    let progressWrites = Promise.resolve();
+    let progressWriting = false;
+    const drainProgress = () => {
+        if (progressWriting || !pendingProgress)
+            return;
+        progressWriting = true;
+        const record = pendingProgress;
+        pendingProgress = null;
+        progressWrites = writeBranchProgress(progressFile, record)
+            .catch(() => undefined)
+            .finally(() => {
+            progressWriting = false;
+            drainProgress();
+        });
+    };
+    // The record is assembled from the run's current state rather than from each
+    // caller's arguments, because two different things move it — the screens and
+    // the packages — and a writer that knew only its own half would erase the
+    // other's.
+    const packageProgress = new Map();
+    let progressPhase = 'claiming';
+    let progressRunId = '';
+    let progressScreens = [];
+    const publish = () => {
+        pendingProgress = {
+            version: 1,
+            runId: progressRunId,
+            phase: progressPhase,
+            startedAt,
+            updatedAt: new Date().toISOString(),
+            screens: progressScreens,
+            ...(packageProgress.size > 0 ? { packages: [...packageProgress.values()] } : {}),
+        };
+        drainProgress();
+    };
+    const publishProgress = (phase, runId, screens) => {
+        emit({ kind: 'progress', phase, screens });
+        progressPhase = phase;
+        progressRunId = runId;
+        progressScreens = screens;
+        publish();
+    };
+    const finished = await readBranchCompletion(completionFile);
+    if (finished) {
+        throw new Error(`This branch run already completed: ${completionFile} names run ${finished.runId},`
+            + ` ${finished.succeededCount} succeeded screen(s), and every page's conversion. Read it`
+            + ' rather than running the branch again, or choose a new --out-dir to start a new run.');
+    }
+    const existing = await readBranchAttempt(attemptFile);
+    if (existing && !args.resume) {
+        throw new Error(`Branch attempt evidence already exists at ${attemptFile} for run`
+            + ` ${existing.runId ?? '(unclaimed)'}. Re-run the identical command with --resume to`
+            + ' continue it: a resume replays every settled screen for free and re-dispatches only'
+            + ' what is still pending. It can never buy a screen twice.');
+    }
+    if (!existing && args.resume) {
+        // Never started, so nothing failed. This answers in a different register
+        // from a recovery report on purpose: a caller told "0 recovered" about work
+        // it never asked for concludes the service is broken and gives up.
+        throw new Error(`This branch run has never been started — there is nothing to resume, and nothing has`
+            + ` failed. There is no ${BRANCH_ATTEMPT_FILENAME} in ${outDir}. Run the same command`
+            + ' without --resume to start it; it blocks for the whole run and streams progress.');
+    }
+    if (existing && existing.runKey !== runKey) {
+        throw new Error(`Refusing to resume: ${outDir} holds run key ${existing.runKey} but these inputs derive`
+            + ` ${runKey}. A resume must replay the same winner, concept, and scope.`);
+    }
+    const attempt = existing ?? {
+        version: 1,
+        status: 'claiming',
+        runKey,
+        origin: args.origin,
+        scope: inputs.scope,
+        concept: inputs.concept,
+        conceptSha256: branchConceptDigest(inputs.concept),
+        winner: inputs.winner.kind === 'run'
+            ? { kind: 'run', runId: inputs.winner.runId, slot: inputs.winner.slot }
+            : {
+                kind: 'image',
+                imagePath: inputs.winner.imagePath,
+                sha256: inputs.winner.sha256,
+                mediaType: inputs.winner.mediaType,
+            },
+        ...(inputs.aspect ? { aspect: inputs.aspect } : {}),
+        ...(inputs.maxScreens === undefined ? {} : { maxScreens: inputs.maxScreens }),
+        ...(inputs.convert
+            ? {
+                convert: {
+                    output: inputs.convert.output,
+                    model: inputs.convert.model ?? 'standard',
+                    ...(inputs.convert.responsiveQuality
+                        ? { responsiveQuality: inputs.convert.responsiveQuality }
+                        : {}),
+                },
+            }
+            : {}),
+        ...(inputs.convert?.sourceConversionId
+            ? { sourceConversionId: inputs.convert.sourceConversionId }
+            : {}),
+        createdAt: startedAt,
+    };
+    if (existing) {
+        attempt.resumedAt = [...(attempt.resumedAt ?? []), startedAt];
+        await writeBranchAttempt(attemptFile, attempt);
+    }
+    else {
+        await writeBranchAttempt(attemptFile, attempt, true);
+    }
+    emit({ kind: 'phase', phase: 'claim', detail: 'planning the screens (10-20s, buys no image)' });
+    const envelope = attempt.runId
+        ? await args.branchClient.getRun(attempt.runId, args.signal)
+        : await claimBuildRun({
+            client: args.branchClient,
+            inputs,
+            runKey,
+            ...(args.signal ? { signal: args.signal } : {}),
+        });
+    attempt.runId = envelope.id;
+    attempt.status = 'dispatching';
+    await writeBranchAttempt(attemptFile, attempt);
+    let plan = normalizeBranchPlan(envelope, {
+        scope: inputs.scope,
+        ...(inputs.maxScreens === undefined ? {} : { maxScreens: inputs.maxScreens }),
+    });
+    await writeBranchPlanRecord(branchPlanPath(outDir), plan);
+    emit({
+        kind: 'phase',
+        phase: 'plan',
+        detail: `${plan.pages.length} page(s), ${plan.screens.length} screen(s) to generate`,
+    });
+    const convert = inputs.convert;
+    const packageClient = args.packageClient;
+    // Refused before the run buys anything rather than after every screen is paid
+    // for: a run that cannot convert should never have generated.
+    if (convert && !packageClient)
+        throw new Error('A conversion package client is required for --convert');
+    const needsWinner = Boolean(convert) && plan.pages.some((page) => page.startsFromWinner);
+    const materializer = createRunMaterializer({
+        client: args.branchClient,
+        runId: envelope.id,
+        inputs,
+        screensDirectory,
+        ...(args.signal ? { signal: args.signal } : {}),
+    });
+    // The approved design is gated by nothing the run generates, so its bytes are
+    // fetched alongside dispatch instead of after it. The rejection is handled
+    // where it is awaited — as the source page's own conversion failure.
+    const winnerBytes = needsWinner ? materializer.winner() : null;
+    winnerBytes?.catch(() => undefined);
+    const winnerReceiptTargets = [
+        branchScreenPath(screensDirectory, 'winner'),
+        ...(inputs.winner.kind === 'image' ? [inputs.winner.imagePath] : []),
+    ];
+    const winnerReceipts = convert ? await readConversionReceipts(winnerReceiptTargets) : [];
+    /**
+     * Receipt work runs one at a time. Withdrawing a disproven receipt and
+     * writing the receipt for the conversion bought in its place touch the same
+     * file, so their order is what decides whether the run ends holding the proof
+     * it just paid for or holding nothing. Serializing costs nothing — these are
+     * two small writes per run — and removes the question.
+     */
+    const receiptWrites = [];
+    const queueReceiptWork = (work) => {
+        const previous = receiptWrites[receiptWrites.length - 1] ?? Promise.resolve();
+        receiptWrites.push(previous.then(work, work));
+    };
+    const pages = convert && packageClient
+        ? createBranchPageConversions({
+            client: packageClient,
+            settings: convert,
+            pagesDirectory,
+            winnerReceipts,
+            concurrency: args.pageConcurrency ?? BRANCH_PAGE_CONCURRENCY_DEFAULT,
+            ...(args.packageTimeoutMs === undefined ? {} : { timeoutMs: args.packageTimeoutMs }),
+            prepare: async (page, livePlan) => {
+                const delivered = await materializer.ensure(livePlan.screens
+                    .filter((screen) => page.slots.includes(screen.slot) && screen.status === 'succeeded')
+                    .map((screen) => screen.slot));
+                const winner = page.startsFromWinner && winnerBytes ? await winnerBytes : undefined;
+                return { screens: delivered, ...(winner ? { winner } : {}) };
+            },
+            onProgress: (pageId, progress) => {
+                emit({ kind: 'package', pageId, progress });
+                packageProgress.set(pageId, {
+                    pageId,
+                    ...progress,
+                    updatedAt: new Date().toISOString(),
+                });
+                publish();
+            },
+            // The server read the referenced conversion's durable evidence and
+            // refused the claim, so the receipt it came from is no longer proof of
+            // anything. Withdrawing it here is what keeps the next run from paying
+            // the same refused-then-retried round trip.
+            onReuseDisproven: (disproof) => {
+                emit({
+                    kind: 'phase',
+                    phase: 'convert',
+                    detail: `the recorded conversion ${disproof.conversionId} is no longer attachable`
+                        + ` (${disproof.detail}); converting that screen again and forgetting the receipt`,
+                });
+                queueReceiptWork(async () => await invalidateConversionReceipts(winnerReceiptTargets, disproof.conversionId));
+            },
+            onWinnerConversion: (conversion) => {
+                const createdAt = new Date().toISOString();
+                queueReceiptWork(async () => await writeConversionReceipts(winnerReceiptTargets, {
+                    version: 1,
+                    sha256: conversion.sha256,
+                    conversionId: conversion.conversionId,
+                    model: conversion.model,
+                    boughtBy: envelope.id,
+                    expiresAt: conversion.expiresAt,
+                    createdAt,
+                }));
+            },
+            ...(args.signal ? { signal: args.signal } : {}),
+        })
+        : null;
+    /** A page converts the moment ITS OWN screens have all landed. */
+    const convertWholePages = (livePlan) => {
+        for (const page of livePlan.pages) {
+            const own = livePlan.screens.filter((screen) => page.slots.includes(screen.slot));
+            if (own.length === 0 || !own.every((screen) => screen.status === 'succeeded'))
+                continue;
+            pages?.start(livePlan, page);
+        }
+    };
+    let stopped = null;
+    publishProgress('dispatching', envelope.id, branchProgressScreens(plan, {}));
+    if (plan.screens.length > 0) {
+        const dispatched = await runBranchDispatch({
+            client: args.branchClient,
+            plan,
+            onEvent: emit,
+            onSnapshot: (snapshot) => {
+                publishProgress('dispatching', envelope.id, branchProgressScreens(snapshot.plan, snapshot.dispatchedAt));
+                convertWholePages(snapshot.plan);
+            },
+            ...(args.signal ? { signal: args.signal } : {}),
+            ...(args.dispatch ?? {}),
+        });
+        plan = dispatched.plan;
+        stopped = dispatched.stopped;
+    }
+    else {
+        plan = applyBranchEnvelope(plan, envelope);
+    }
+    attempt.status = 'downloading';
+    publishProgress('downloading', envelope.id, branchProgressScreens(plan, {}));
+    await writeBranchAttempt(attemptFile, attempt);
+    const screens = await materializer.ensure(plan.screens
+        .filter((screen) => screen.status === 'succeeded')
+        .map((screen) => screen.slot));
+    // The winner's staged bytes have to be in hand before the atomic pass, or the
+    // pass would leave them undelivered under a path the completion names.
+    if (winnerBytes)
+        await winnerBytes.catch(() => undefined);
+    await materializer.finish();
+    emit({ kind: 'phase', phase: 'download', detail: `${screens.size} screen(s) on disk` });
+    if (convert && !stopped) {
+        attempt.status = 'converting';
+        publishProgress('converting', envelope.id, branchProgressScreens(plan, {}));
+        await writeBranchAttempt(attemptFile, attempt);
+        emit({
+            kind: 'phase',
+            phase: 'convert',
+            detail: `one package conversion per whole page, up to ${args.pageConcurrency ?? BRANCH_PAGE_CONCURRENCY_DEFAULT} at a time`,
+        });
+        for (const page of plan.pages)
+            pages?.start(plan, page);
+    }
+    // Every page settles, including any that started while screens were still
+    // generating: paid work in flight is never abandoned.
+    const conversions = await pages?.settled() ?? new Map();
+    await Promise.allSettled(receiptWrites);
+    const winner = winnerBytes ? await winnerBytes.catch(() => undefined) : undefined;
+    const completion = buildCompletion({
+        plan,
+        inputs,
+        runKey,
+        origin: args.origin,
+        outDir,
+        attemptFile,
+        startedAt,
+        screens,
+        ...(winner ? { winner } : {}),
+        conversions,
+        stopped,
+    });
+    publishProgress('terminal', envelope.id, branchProgressScreens(plan, {}));
+    await progressWrites;
+    await writeBranchCompletion(completionFile, completion);
+    attempt.status = completion.status;
+    attempt.completedAt = completion.completedAt;
+    attempt.completionPath = completionFile;
+    await writeBranchAttempt(attemptFile, attempt);
+    return {
+        completion,
+        completionPath: completionFile,
+        failure: terminalFailure({ completion, stopped, completionFile, convert: Boolean(inputs.convert) }),
+    };
+};
+//# sourceMappingURL=branch-execution.js.map

package/dist/branch-execution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-execution.js","sourceRoot":"","sources":["../src/branch-execution.ts"],"names":[],"mappings":"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"}

package/dist/branch-identity.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Every identity a branch run needs, derived from its inputs rather than
+ * authored. Free-text keys are load-bearing in both directions here: the same
+ * key with a changed body wedges the claim with `409 idempotency_conflict`, and
+ * a NEW key on a settled slot buys another image. Deriving them removes both
+ * failure modes from the agent's hands.
+ *
+ * Digests are truncated because `Idempotency-Key` is capped at 128 printable
+ * characters and a run id alone is 44 of them. 16 hex characters is 64 bits of
+ * collision resistance over inputs that are already scoped by run id, which is
+ * far more than the number of runs any account will ever hold.
+ */
+export declare const BRANCH_WORKFLOW_REVISION = "branch-execute-v1";
+export type BranchScope = 'page' | 'site';
+export declare const branchConceptDigest: (concept: string) => string;
+/**
+ * Same inputs -> same run, so an interrupted claim replays instead of starting
+ * a second one. A changed concept is a different design problem and therefore a
+ * different run, so it derives a new key rather than wedging the old one.
+ */
+export declare const branchRunKey: (args: {
+    winner: {
+        runId: string;
+        slot: string;
+    } | {
+        imageSha256: string;
+    };
+    concept: string;
+    scope: BranchScope;
+}) => string;
+/**
+ * The ONLY keyed dispatch. Automatic dispatch is unkeyed so every replay is
+ * free; a redraw is an explicit request for one further paid attempt and needs
+ * a key the settled slot has never seen.
+ */
+export declare const branchRedrawKey: (args: {
+    runId: string;
+    slot: string;
+    attempt: number;
+}) => string;
+/**
+ * Stable under retry and distinct per page. Keying on the ordered viewport
+ * hashes means a resumed run that downloaded the same bytes replays the same
+ * package rather than buying a second one, while a redrawn screen produces a
+ * genuinely different page and therefore a genuinely different key.
+ */
+export declare const branchPackageKey: (args: {
+    runId: string;
+    pageIndex: number;
+    viewportSha256s: readonly string[];
+    output: string;
+    model?: string;
+    responsiveQuality?: string;
+}) => string;
+/** Standalone `convert package` runs derive from the manifest they were given. */
+export declare const conversionPackageKey: (args: {
+    manifestSha256: string;
+    output: string;
+}) => string;
+/**
+ * Standalone `export` runs derive from the conversion they re-render. The
+ * export command appends the output and a digest of the request body to this
+ * base, so the base only has to pin the source: exporting the same conversion
+ * to the same format twice is the same paid work and must replay rather than
+ * buy it again, while a different format or profile lands on a different key
+ * through the suffix.
+ */
+export declare const conversionExportKey: (args: {
+    sourceConversionId: string;
+}) => string;
+//# sourceMappingURL=branch-identity.d.ts.map

package/dist/branch-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-identity.d.ts","sourceRoot":"","sources":["../src/branch-identity.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,wBAAwB,sBAAsB,CAAC;AAE5D,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,CAAC;AAM1C,eAAO,MAAM,mBAAmB,GAAI,SAAS,MAAM,KAAG,MAErD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM;IACjC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAClE,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,WAAW,CAAC;CACpB,KAAG,MAYH,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,KAAG,MAAoE,CAAC;AAEzE;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,KAAG,MAaO,CAAC;AAEZ,kFAAkF;AAClF,eAAO,MAAM,oBAAoB,GAAI,MAAM;IACzC,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB,KAAG,MAAiF,CAAC;AAEtF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM;IACxC,kBAAkB,EAAE,MAAM,CAAC;CAC5B,KAAG,MAAwD,CAAC"}

package/dist/branch-identity.js

@@ -0,0 +1,72 @@
+import { createHash } from 'node:crypto';
+/**
+ * Every identity a branch run needs, derived from its inputs rather than
+ * authored. Free-text keys are load-bearing in both directions here: the same
+ * key with a changed body wedges the claim with `409 idempotency_conflict`, and
+ * a NEW key on a settled slot buys another image. Deriving them removes both
+ * failure modes from the agent's hands.
+ *
+ * Digests are truncated because `Idempotency-Key` is capped at 128 printable
+ * characters and a run id alone is 44 of them. 16 hex characters is 64 bits of
+ * collision resistance over inputs that are already scoped by run id, which is
+ * far more than the number of runs any account will ever hold.
+ */
+export const BRANCH_WORKFLOW_REVISION = 'branch-execute-v1';
+const shortDigest = (value, characters = 16) => (createHash('sha256').update(value).digest('hex').slice(0, characters));
+export const branchConceptDigest = (concept) => (createHash('sha256').update(concept).digest('hex'));
+/**
+ * Same inputs -> same run, so an interrupted claim replays instead of starting
+ * a second one. A changed concept is a different design problem and therefore a
+ * different run, so it derives a new key rather than wedging the old one.
+ */
+export const branchRunKey = (args) => {
+    const origin = 'runId' in args.winner
+        ? `${args.winner.runId}:${args.winner.slot}`
+        : `img-${args.winner.imageSha256.slice(0, 32)}:-`;
+    return [
+        'branch',
+        'v1',
+        origin,
+        shortDigest(args.concept),
+        args.scope,
+        BRANCH_WORKFLOW_REVISION,
+    ].join(':');
+};
+/**
+ * The ONLY keyed dispatch. Automatic dispatch is unkeyed so every replay is
+ * free; a redraw is an explicit request for one further paid attempt and needs
+ * a key the settled slot has never seen.
+ */
+export const branchRedrawKey = (args) => `branch-screen:${args.runId}:${args.slot}:${args.attempt}`;
+/**
+ * Stable under retry and distinct per page. Keying on the ordered viewport
+ * hashes means a resumed run that downloaded the same bytes replays the same
+ * package rather than buying a second one, while a redrawn screen produces a
+ * genuinely different page and therefore a genuinely different key.
+ */
+export const branchPackageKey = (args) => [
+    'branch-package',
+    'v1',
+    args.runId,
+    String(args.pageIndex),
+    shortDigest(args.viewportSha256s.join('.'), 32),
+    args.output,
+    // Everything that changes the request body has to be in the key. Model and
+    // quality are body fields, so leaving them out turns a deliberate change of
+    // model into `409 idempotency_conflict` on a page that was never bought —
+    // measured against production while smoke-testing this command.
+    args.model ?? 'standard',
+    args.responsiveQuality ?? 'default',
+].join(':');
+/** Standalone `convert package` runs derive from the manifest they were given. */
+export const conversionPackageKey = (args) => `convert-package:v1:${args.manifestSha256.slice(0, 32)}:${args.output}`;
+/**
+ * Standalone `export` runs derive from the conversion they re-render. The
+ * export command appends the output and a digest of the request body to this
+ * base, so the base only has to pin the source: exporting the same conversion
+ * to the same format twice is the same paid work and must replay rather than
+ * buy it again, while a different format or profile lands on a different key
+ * through the suffix.
+ */
+export const conversionExportKey = (args) => `convert-export:v1:${args.sourceConversionId}`;
+//# sourceMappingURL=branch-identity.js.map

package/dist/branch-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-identity.js","sourceRoot":"","sources":["../src/branch-identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;;;;;;GAWG;AAEH,MAAM,CAAC,MAAM,wBAAwB,GAAG,mBAAmB,CAAC;AAI5D,MAAM,WAAW,GAAG,CAAC,KAAa,EAAE,UAAU,GAAG,EAAE,EAAU,EAAE,CAAC,CAC9D,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CACtE,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,OAAe,EAAU,EAAE,CAAC,CAC9D,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CACnD,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAI5B,EAAU,EAAE;IACX,MAAM,MAAM,GAAG,OAAO,IAAI,IAAI,CAAC,MAAM;QACnC,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE;QAC5C,CAAC,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC;IACpD,OAAO;QACL,QAAQ;QACR,IAAI;QACJ,MAAM;QACN,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC;QACzB,IAAI,CAAC,KAAK;QACV,wBAAwB;KACzB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,IAI/B,EAAU,EAAE,CAAC,iBAAiB,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;AAEzE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,IAOhC,EAAU,EAAE,CAAC;IACZ,gBAAgB;IAChB,IAAI;IACJ,IAAI,CAAC,KAAK;IACV,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC;IACtB,WAAW,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;IAC/C,IAAI,CAAC,MAAM;IACX,2EAA2E;IAC3E,4EAA4E;IAC5E,0EAA0E;IAC1E,gEAAgE;IAChE,IAAI,CAAC,KAAK,IAAI,UAAU;IACxB,IAAI,CAAC,iBAAiB,IAAI,SAAS;CACpC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAEZ,kFAAkF;AAClF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,IAGpC,EAAU,EAAE,CAAC,sBAAsB,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;AAEtF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,IAEnC,EAAU,EAAE,CAAC,qBAAqB,IAAI,CAAC,kBAAkB,EAAE,CAAC"}