@12ui/design 0.2.14 → 0.2.16

package/dist/conversion-receipt.d.ts

@@ -0,0 +1,223 @@
+import type { ConversionOperation } from './conversion-client.js';
+import type { ConversionOutput } from './conversion-outputs.js';
+import { type ConversionReceiptKey } from './conversion-receipt-store.js';
+import type { PackageSubmissionResult } from './package-submission.js';
+/**
+ * The single owner of "an image's conversion was already bought, and here is
+ * the proof".
+ *
+ * A branch run's approved design is viewport 1 of its first page, and the
+ * common flow converts that same design on its own first
+ * (`12ui convert <winner>.png --output layerdoc --export html`), so without a
+ * receipt every branch run buys an image-to-LayerDoc conversion of bytes the
+ * account has already paid to convert. The package accepts a finished
+ * conversion for a viewport (`source_conversion_id`), and the server proves the
+ * claim against the referenced conversion's admitted evidence before it skips
+ * the upload — so a false claim is a failed page, not a cheap win.
+ *
+ * This is therefore a receipt of a proved fact, not a cache: it records the
+ * digest of the exact bytes a succeeded conversion was admitted with. A later
+ * run reuses it only when the bytes it is about to submit hash identically.
+ * Absent proof it converts fresh.
+ *
+ * The records live in the per-user store (`conversion-receipt-store.ts`), keyed
+ * by that digest and the model, because the fact is about bytes and not about
+ * where a copy of them happens to sit. `12ui convert`, `12ui convert package`,
+ * and `12ui branch execute --convert` write them, `12ui branch execute
+ * --convert` reads them, and only this module decides what counts as proof.
+ *
+ * SUNSET — legacy sidecars. Receipts shipped in 0.2.15 as
+ * `<image>.conversion.json` written beside the input image. Those files are
+ * still READ beside a winner image for one release cycle and migrated into the
+ * store the first time they are seen, so an upgrade never re-buys a conversion
+ * a 0.2.15 convert already paid for. Nothing writes them any more. Delete the
+ * legacy read path — `LEGACY_CONVERSION_RECEIPT_SUFFIX`,
+ * `legacyConversionReceiptPath`, `readLegacyConversionReceipts`, and the
+ * `legacyImagePaths` argument of `invalidateConversionReceipts` — one release
+ * after 0.2.16; by then every receipt a 0.2.15 convert wrote has long outlived
+ * the ~24h conversion it names.
+ */
+export declare const LEGACY_CONVERSION_RECEIPT_SUFFIX = ".conversion.json";
+export type { ConversionReceiptKey } from './conversion-receipt-store.js';
+export { resolveConversionReceiptStore } from './conversion-receipt-store.js';
+/**
+ * The output an attachable conversion must have produced. A package converts
+ * every viewport to a LayerDoc and buys the page export separately, so the
+ * server (`PACKAGE_VIEWPORT_CHILD_OUTPUT`) refuses any attached conversion
+ * whose own output is `html` or any other rendered document.
+ */
+export declare const REUSABLE_CONVERSION_OUTPUT: ConversionOutput;
+/**
+ * How much life the referenced conversion must have left. The server refuses an
+ * attachment expiring within this window (`PACKAGE_SOURCE_MINIMUM_REMAINING_MS`)
+ * because composition reads the source run at the END of a package drive, and
+ * that refusal fails the page after its screens are already paid for.
+ * Conversions live 24h while a stored receipt sits in the user's home
+ * indefinitely, so an expiry that is not checked here is a page failure waiting
+ * for day two.
+ */
+export declare const CONVERSION_REUSE_MINIMUM_REMAINING_MS: number;
+export type ConversionReceipt = {
+    version: 1;
+    /** Digest of the EXACT bytes the conversion was admitted with. */
+    sha256: string;
+    conversionId: string;
+    /** A reused conversion must have run the model the package declares. */
+    model: string;
+    /**
+     * The operation that bought it: a branch run id, a package id, or for
+     * `12ui convert` the conversion's own id. An operation never reuses its own
+     * receipt — a branch package key is derived per run and page, so attaching a
+     * reuse on a resume would change the request body under a key the server
+     * already settled, which is `409 idempotency_conflict` on a page that was
+     * already paid for.
+     */
+    boughtBy: string;
+    /** When the referenced conversion stops being attachable at all. */
+    expiresAt: string;
+    createdAt: string;
+};
+export type ConversionReceiptWrite = {
+    /** Where the record landed, or null when nothing was written. */
+    path: string | null;
+    failure?: {
+        path: string;
+        detail: string;
+    };
+};
+/** Where 0.2.15 wrote a receipt. Read for one release cycle, never written. */
+export declare const legacyConversionReceiptPath: (imagePath: string) => string;
+export declare const conversionReceiptKey: (receipt: ConversionReceipt) => ConversionReceiptKey;
+/**
+ * The stored record for exactly these bytes and this model, or nothing.
+ *
+ * An expired record is removed as it is read: it is the one expired record this
+ * invocation is certain about, and leaving it would have the next run read it
+ * again to reach the same conclusion.
+ */
+export declare const readStoredConversionReceipt: (key: ConversionReceiptKey, options?: {
+    store?: string;
+    now?: Date;
+}) => Promise<ConversionReceipt | undefined>;
+/**
+ * Record a proved conversion. A write that fails is not a command failure: the
+ * receipt is an optimisation, and its absence only costs one conversion.
+ * Callers that can say so report the failure; the rest ignore it.
+ */
+export declare const recordConversionReceipt: (receipt: ConversionReceipt, options?: {
+    store?: string;
+    now?: Date;
+}) => Promise<ConversionReceiptWrite>;
+/**
+ * The 0.2.15 sidecars beside these images, carried forward.
+ *
+ * Every one that is still live is copied into the store the moment it is seen,
+ * so the upgrade costs nothing and the next run finds the proof by digest no
+ * matter which copy of the image it starts from. An existing store record wins:
+ * it was written by a later command about the same bytes, and overwriting it
+ * with the sidecar would replace a fresher expiry with an older one. Migration
+ * is best-effort — the receipt is still honoured this run either way.
+ */
+export declare const readLegacyConversionReceipts: (imagePaths: readonly string[], options?: {
+    store?: string;
+    now?: Date;
+}) => Promise<ConversionReceipt[]>;
+/**
+ * The proof gate. Every condition is a fact about the bytes in hand, never an
+ * assumption about what an earlier command probably did.
+ */
+export declare const reusableConversionId: (args: {
+    receipts: readonly ConversionReceipt[];
+    /** Digest of the bytes this package is about to submit for the winner. */
+    sha256: string;
+    model: string;
+    /** The operation about to submit: its own receipt is never proof for it. */
+    boughtBy: string;
+    now?: Date;
+}) => string | undefined;
+/**
+ * The gate, over the store and over whatever the caller already holds.
+ *
+ * The store is consulted first because it is the record every command writes;
+ * the in-hand receipts are the 0.2.15 sidecars this run read beside the winner,
+ * which stay proof for one release cycle even if their migration failed.
+ */
+export declare const findReusableConversionId: (args: {
+    sha256: string;
+    model: string;
+    boughtBy: string;
+    receipts?: readonly ConversionReceipt[];
+    store?: string;
+    now?: Date;
+}) => Promise<string | undefined>;
+/**
+ * Withdraw a receipt the SERVER disproved, so the next run does not repeat the
+ * dance the last one already paid a retry for.
+ *
+ * The bar is deliberately narrow: only an explicit refusal of the attachment at
+ * admission — the server having read the referenced conversion's durable
+ * evidence and rejected the claim — is proof that this receipt is no longer
+ * proof of anything. A network error, a timeout, or any other transient failure
+ * says nothing about the referenced conversion, and deleting on one of those
+ * would throw away a live receipt and buy its conversion again for nothing.
+ *
+ * Only records naming the disproven conversion are withdrawn: a newer record
+ * under the same key describes different work and is untouched. Removal is
+ * best-effort, because a receipt that cannot be deleted only costs the next run
+ * one refused attachment and one retry — the same price this run paid.
+ */
+export declare const invalidateConversionReceipts: (args: {
+    conversionId: string;
+    /** The keys the disproven claim could have come from. */
+    keys?: readonly ConversionReceiptKey[];
+    /** Sunset: 0.2.15 sidecars beside these images, if they name it. */
+    legacyImagePaths?: readonly string[];
+    store?: string;
+}) => Promise<string[]>;
+/**
+ * What `12ui convert` leaves behind for the branch run that follows it.
+ *
+ * Only a succeeded image-to-LayerDoc conversion can stand in for a package
+ * viewport, so anything else records nothing at all: a receipt for an `html`
+ * conversion would be a claim the server refuses, and the refusal costs a whole
+ * page. The digest is of the bytes actually submitted, which is what `--width`
+ * normalization changes and what the server admitted the run with.
+ */
+export declare const recordConvertedImageReceipt: (args: {
+    /** The EXACT bytes submitted, after any `--width` normalization. */
+    bytes: Uint8Array;
+    operation: Pick<ConversionOperation, "id" | "status" | "output" | "model" | "expires_at" | "input_kind">;
+    store?: string;
+    warn?: (message: string) => void;
+    now?: Date;
+}) => Promise<ConversionReceipt | undefined>;
+/**
+ * What `12ui convert package` leaves behind: one receipt per viewport whose own
+ * child conversion the package bought.
+ *
+ * A package converts each viewport to a LayerDoc and composes the page from
+ * those children, so every viewport of a submitted page is exactly the artifact
+ * a later package can attach instead of buying — the same fact the branch path
+ * records for the winner, for every screenshot the user named.
+ *
+ * A viewport that ATTACHED a conversion bought nothing, so it records nothing.
+ * The expiry reported is the package's own, which its children cannot outlive
+ * backwards, and the model is the one the server says it ran; without either
+ * fact nothing here proves a conversion is still attachable, so nothing is
+ * recorded and the caller is told once.
+ */
+export declare const recordPackageConversionReceipts: (args: {
+    pages: readonly {
+        id: string;
+        viewports: readonly {
+            id: string;
+            bytes: Uint8Array;
+            sourceConversionId?: string;
+        }[];
+    }[];
+    result: Pick<PackageSubmissionResult, "packageId" | "model" | "expiresAt" | "pages">;
+    store?: string;
+    warn?: (message: string) => void;
+    now?: Date;
+}) => Promise<ConversionReceipt[]>;
+//# sourceMappingURL=conversion-receipt.d.ts.map

package/dist/conversion-receipt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversion-receipt.d.ts","sourceRoot":"","sources":["../src/conversion-receipt.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAOL,KAAK,oBAAoB,EAC1B,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,eAAO,MAAM,gCAAgC,qBAAqB,CAAC;AAEnE,YAAY,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAC1E,OAAO,EAAE,6BAA6B,EAAE,MAAM,+BAA+B,CAAC;AAE9E;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,EAAE,gBAA6B,CAAC;AAEvE;;;;;;;;GAQG;AACH,eAAO,MAAM,qCAAqC,QAAc,CAAC;AAEjE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,CAAC,CAAC;IACX,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;OAOG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,iEAAiE;IACjE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5C,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,2BAA2B,GAAI,WAAW,MAAM,KAAG,MAE/D,CAAC;AAkBF,eAAO,MAAM,oBAAoB,GAAI,SAAS,iBAAiB,KAAG,oBAGhE,CAAC;AAwBH;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,GACtC,KAAK,oBAAoB,EACzB,UAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,CAAA;CAAO,KAC3C,OAAO,CAAC,iBAAiB,GAAG,SAAS,CASvC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,GAClC,SAAS,iBAAiB,EAC1B,UAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,CAAA;CAAO,KAC3C,OAAO,CAAC,sBAAsB,CA2BhC,CAAC;AAeF;;;;;;;;;GASG;AACH,eAAO,MAAM,4BAA4B,GACvC,YAAY,SAAS,MAAM,EAAE,EAC7B,UAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,CAAA;CAAO,KAC3C,OAAO,CAAC,iBAAiB,EAAE,CAkB7B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM;IACzC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACvC,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ,KAAG,MAAM,GAAG,SAQZ,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,GAAU,MAAM;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ,KAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAa7B,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,4BAA4B,GAAU,MAAM;IACvD,YAAY,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,IAAI,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACvC,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,KAAG,OAAO,CAAC,MAAM,EAAE,CAmBnB,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,GAAU,MAAM;IACtD,oEAAoE;IACpE,KAAK,EAAE,UAAU,CAAC;IAClB,SAAS,EAAE,IAAI,CACb,mBAAmB,EACnB,IAAI,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,YAAY,GAAG,YAAY,CACnE,CAAC;IACF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ,KAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAgCxC,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,+BAA+B,GAAU,MAAM;IAC1D,KAAK,EAAE,SAAS;QACd,EAAE,EAAE,MAAM,CAAC;QACX,SAAS,EAAE,SAAS;YAClB,EAAE,EAAE,MAAM,CAAC;YACX,KAAK,EAAE,UAAU,CAAC;YAClB,kBAAkB,CAAC,EAAE,MAAM,CAAC;SAC7B,EAAE,CAAC;KACL,EAAE,CAAC;IACJ,MAAM,EAAE,IAAI,CAAC,uBAAuB,EAAE,WAAW,GAAG,OAAO,GAAG,WAAW,GAAG,OAAO,CAAC,CAAC;IACrF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ,KAAG,OAAO,CAAC,iBAAiB,EAAE,CA8C9B,CAAC"}

package/dist/conversion-receipt.js

@@ -0,0 +1,352 @@
+import { createHash } from 'node:crypto';
+import { readFile, rm } from 'node:fs/promises';
+import { conversionReceiptRecordPath, pruneConversionReceiptRecords, readConversionReceiptRecord, removeConversionReceiptRecord, resolveConversionReceiptStore, writeConversionReceiptRecord, } from './conversion-receipt-store.js';
+/**
+ * The single owner of "an image's conversion was already bought, and here is
+ * the proof".
+ *
+ * A branch run's approved design is viewport 1 of its first page, and the
+ * common flow converts that same design on its own first
+ * (`12ui convert <winner>.png --output layerdoc --export html`), so without a
+ * receipt every branch run buys an image-to-LayerDoc conversion of bytes the
+ * account has already paid to convert. The package accepts a finished
+ * conversion for a viewport (`source_conversion_id`), and the server proves the
+ * claim against the referenced conversion's admitted evidence before it skips
+ * the upload — so a false claim is a failed page, not a cheap win.
+ *
+ * This is therefore a receipt of a proved fact, not a cache: it records the
+ * digest of the exact bytes a succeeded conversion was admitted with. A later
+ * run reuses it only when the bytes it is about to submit hash identically.
+ * Absent proof it converts fresh.
+ *
+ * The records live in the per-user store (`conversion-receipt-store.ts`), keyed
+ * by that digest and the model, because the fact is about bytes and not about
+ * where a copy of them happens to sit. `12ui convert`, `12ui convert package`,
+ * and `12ui branch execute --convert` write them, `12ui branch execute
+ * --convert` reads them, and only this module decides what counts as proof.
+ *
+ * SUNSET — legacy sidecars. Receipts shipped in 0.2.15 as
+ * `<image>.conversion.json` written beside the input image. Those files are
+ * still READ beside a winner image for one release cycle and migrated into the
+ * store the first time they are seen, so an upgrade never re-buys a conversion
+ * a 0.2.15 convert already paid for. Nothing writes them any more. Delete the
+ * legacy read path — `LEGACY_CONVERSION_RECEIPT_SUFFIX`,
+ * `legacyConversionReceiptPath`, `readLegacyConversionReceipts`, and the
+ * `legacyImagePaths` argument of `invalidateConversionReceipts` — one release
+ * after 0.2.16; by then every receipt a 0.2.15 convert wrote has long outlived
+ * the ~24h conversion it names.
+ */
+export const LEGACY_CONVERSION_RECEIPT_SUFFIX = '.conversion.json';
+export { resolveConversionReceiptStore } from './conversion-receipt-store.js';
+/**
+ * The output an attachable conversion must have produced. A package converts
+ * every viewport to a LayerDoc and buys the page export separately, so the
+ * server (`PACKAGE_VIEWPORT_CHILD_OUTPUT`) refuses any attached conversion
+ * whose own output is `html` or any other rendered document.
+ */
+export const REUSABLE_CONVERSION_OUTPUT = 'layerdoc';
+/**
+ * How much life the referenced conversion must have left. The server refuses an
+ * attachment expiring within this window (`PACKAGE_SOURCE_MINIMUM_REMAINING_MS`)
+ * because composition reads the source run at the END of a package drive, and
+ * that refusal fails the page after its screens are already paid for.
+ * Conversions live 24h while a stored receipt sits in the user's home
+ * indefinitely, so an expiry that is not checked here is a page failure waiting
+ * for day two.
+ */
+export const CONVERSION_REUSE_MINIMUM_REMAINING_MS = 60 * 60_000;
+/** Where 0.2.15 wrote a receipt. Read for one release cycle, never written. */
+export const legacyConversionReceiptPath = (imagePath) => (`${imagePath}${LEGACY_CONVERSION_RECEIPT_SUFFIX}`);
+const isReceipt = (value) => {
+    if (!value || typeof value !== 'object')
+        return false;
+    const record = value;
+    return record.version === 1
+        && typeof record.sha256 === 'string'
+        && /^[a-f0-9]{64}$/u.test(record.sha256)
+        && typeof record.conversionId === 'string'
+        && record.conversionId.length > 0
+        && typeof record.model === 'string'
+        && record.model.length > 0
+        && typeof record.boughtBy === 'string'
+        && record.boughtBy.length > 0
+        && typeof record.expiresAt === 'string'
+        && Number.isFinite(Date.parse(record.expiresAt));
+};
+export const conversionReceiptKey = (receipt) => ({
+    sha256: receipt.sha256,
+    model: receipt.model,
+});
+const storeOf = (store) => store ?? resolveConversionReceiptStore();
+const expiredReceipt = (receipt, now) => (Date.parse(receipt.expiresAt) <= now.getTime());
+/**
+ * Expiry hygiene, paid for by the invocations that already write to the store.
+ *
+ * Bounded on purpose: a user who converts every day accumulates a record per
+ * distinct image, and a full sweep on a hot path would make the cheapest
+ * command the one that reads the most files. A rotating sample covers the whole
+ * store across invocations, and a record that survives one pass costs nothing
+ * but its own inode until the next.
+ */
+const pruneExpired = async (store, now) => (await pruneConversionReceiptRecords({
+    store,
+    expired: (record) => isReceipt(record) && expiredReceipt(record, now),
+}));
+/**
+ * The stored record for exactly these bytes and this model, or nothing.
+ *
+ * An expired record is removed as it is read: it is the one expired record this
+ * invocation is certain about, and leaving it would have the next run read it
+ * again to reach the same conclusion.
+ */
+export const readStoredConversionReceipt = async (key, options = {}) => {
+    const store = storeOf(options.store);
+    const record = await readConversionReceiptRecord(store, key);
+    if (!isReceipt(record))
+        return undefined;
+    if (expiredReceipt(record, options.now ?? new Date())) {
+        await removeConversionReceiptRecord(store, key).catch(() => null);
+        return undefined;
+    }
+    return record;
+};
+/**
+ * Record a proved conversion. A write that fails is not a command failure: the
+ * receipt is an optimisation, and its absence only costs one conversion.
+ * Callers that can say so report the failure; the rest ignore it.
+ */
+export const recordConversionReceipt = async (receipt, options = {}) => {
+    const store = storeOf(options.store);
+    // Never leave behind something that cannot be read back as proof: a record
+    // that fails the gate is indistinguishable from a corrupt file later.
+    if (!isReceipt(receipt)) {
+        return {
+            path: null,
+            failure: {
+                path: store,
+                detail: 'the conversion did not report the digest, id, model, and expiry a receipt proves',
+            },
+        };
+    }
+    const key = conversionReceiptKey(receipt);
+    try {
+        const written = await writeConversionReceiptRecord(store, key, receipt);
+        await pruneExpired(store, options.now ?? new Date());
+        return { path: written };
+    }
+    catch (error) {
+        return {
+            path: null,
+            failure: {
+                path: conversionReceiptRecordPath(store, key),
+                detail: error instanceof Error ? error.message : String(error),
+            },
+        };
+    }
+};
+const readLegacyConversionReceipt = async (imagePath) => {
+    try {
+        const parsed = JSON.parse(await readFile(legacyConversionReceiptPath(imagePath), 'utf8'));
+        return isReceipt(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * The 0.2.15 sidecars beside these images, carried forward.
+ *
+ * Every one that is still live is copied into the store the moment it is seen,
+ * so the upgrade costs nothing and the next run finds the proof by digest no
+ * matter which copy of the image it starts from. An existing store record wins:
+ * it was written by a later command about the same bytes, and overwriting it
+ * with the sidecar would replace a fresher expiry with an older one. Migration
+ * is best-effort — the receipt is still honoured this run either way.
+ */
+export const readLegacyConversionReceipts = async (imagePaths, options = {}) => {
+    const now = options.now ?? new Date();
+    const found = await Promise.all(imagePaths.map(readLegacyConversionReceipt));
+    const receipts = found.filter((receipt) => (receipt !== undefined && !expiredReceipt(receipt, now)));
+    const store = storeOf(options.store);
+    const migrated = new Set();
+    for (const receipt of receipts) {
+        const key = conversionReceiptKey(receipt);
+        const name = `${key.sha256}/${key.model}`;
+        if (migrated.has(name))
+            continue;
+        migrated.add(name);
+        const existing = await readStoredConversionReceipt(key, { store, now });
+        if (existing)
+            continue;
+        await writeConversionReceiptRecord(store, key, receipt).catch(() => null);
+    }
+    return receipts;
+};
+/**
+ * The proof gate. Every condition is a fact about the bytes in hand, never an
+ * assumption about what an earlier command probably did.
+ */
+export const reusableConversionId = (args) => {
+    const deadline = (args.now ?? new Date()).getTime() + CONVERSION_REUSE_MINIMUM_REMAINING_MS;
+    return args.receipts.find((receipt) => (receipt.sha256 === args.sha256
+        && receipt.model === args.model
+        && receipt.boughtBy !== args.boughtBy
+        && Date.parse(receipt.expiresAt) > deadline))?.conversionId;
+};
+/**
+ * The gate, over the store and over whatever the caller already holds.
+ *
+ * The store is consulted first because it is the record every command writes;
+ * the in-hand receipts are the 0.2.15 sidecars this run read beside the winner,
+ * which stay proof for one release cycle even if their migration failed.
+ */
+export const findReusableConversionId = async (args) => {
+    const now = args.now ?? new Date();
+    const stored = await readStoredConversionReceipt({ sha256: args.sha256, model: args.model }, { ...(args.store ? { store: args.store } : {}), now });
+    return reusableConversionId({
+        receipts: [...(stored ? [stored] : []), ...(args.receipts ?? [])],
+        sha256: args.sha256,
+        model: args.model,
+        boughtBy: args.boughtBy,
+        now,
+    });
+};
+/**
+ * Withdraw a receipt the SERVER disproved, so the next run does not repeat the
+ * dance the last one already paid a retry for.
+ *
+ * The bar is deliberately narrow: only an explicit refusal of the attachment at
+ * admission — the server having read the referenced conversion's durable
+ * evidence and rejected the claim — is proof that this receipt is no longer
+ * proof of anything. A network error, a timeout, or any other transient failure
+ * says nothing about the referenced conversion, and deleting on one of those
+ * would throw away a live receipt and buy its conversion again for nothing.
+ *
+ * Only records naming the disproven conversion are withdrawn: a newer record
+ * under the same key describes different work and is untouched. Removal is
+ * best-effort, because a receipt that cannot be deleted only costs the next run
+ * one refused attachment and one retry — the same price this run paid.
+ */
+export const invalidateConversionReceipts = async (args) => {
+    const store = storeOf(args.store);
+    const fromStore = await Promise.all((args.keys ?? []).map(async (key) => {
+        const record = await readConversionReceiptRecord(store, key);
+        if (!isReceipt(record) || record.conversionId !== args.conversionId)
+            return null;
+        return await removeConversionReceiptRecord(store, key);
+    }));
+    const fromSidecars = await Promise.all((args.legacyImagePaths ?? []).map(async (imagePath) => {
+        const receipt = await readLegacyConversionReceipt(imagePath);
+        if (receipt?.conversionId !== args.conversionId)
+            return null;
+        const receiptPath = legacyConversionReceiptPath(imagePath);
+        try {
+            await rm(receiptPath, { force: true });
+            return receiptPath;
+        }
+        catch {
+            return null;
+        }
+    }));
+    return [...fromStore, ...fromSidecars].filter((entry) => entry !== null);
+};
+/**
+ * What `12ui convert` leaves behind for the branch run that follows it.
+ *
+ * Only a succeeded image-to-LayerDoc conversion can stand in for a package
+ * viewport, so anything else records nothing at all: a receipt for an `html`
+ * conversion would be a claim the server refuses, and the refusal costs a whole
+ * page. The digest is of the bytes actually submitted, which is what `--width`
+ * normalization changes and what the server admitted the run with.
+ */
+export const recordConvertedImageReceipt = async (args) => {
+    const { operation } = args;
+    if (operation.status !== 'succeeded'
+        || operation.output !== REUSABLE_CONVERSION_OUTPUT
+        // The caller submitted image bytes; an absent input_kind (a legacy cached
+        // payload) does not contradict that, while a declared `layerdoc` does.
+        || operation.input_kind === 'layerdoc') {
+        return undefined;
+    }
+    const now = args.now ?? new Date();
+    const receipt = {
+        version: 1,
+        sha256: createHash('sha256').update(args.bytes).digest('hex'),
+        conversionId: operation.id,
+        model: operation.model,
+        boughtBy: operation.id,
+        expiresAt: operation.expires_at,
+        createdAt: now.toISOString(),
+    };
+    const write = await recordConversionReceipt(receipt, {
+        ...(args.store ? { store: args.store } : {}),
+        now,
+    });
+    if (!write.failure)
+        return receipt;
+    args.warn?.(`12ui convert: could not record the conversion receipt in ${write.failure.path}`
+        + ` (${write.failure.detail}). The conversion is unaffected; a later`
+        + ' `12ui branch execute` from this image will buy its conversion again.');
+    return undefined;
+};
+/**
+ * What `12ui convert package` leaves behind: one receipt per viewport whose own
+ * child conversion the package bought.
+ *
+ * A package converts each viewport to a LayerDoc and composes the page from
+ * those children, so every viewport of a submitted page is exactly the artifact
+ * a later package can attach instead of buying — the same fact the branch path
+ * records for the winner, for every screenshot the user named.
+ *
+ * A viewport that ATTACHED a conversion bought nothing, so it records nothing.
+ * The expiry reported is the package's own, which its children cannot outlive
+ * backwards, and the model is the one the server says it ran; without either
+ * fact nothing here proves a conversion is still attachable, so nothing is
+ * recorded and the caller is told once.
+ */
+export const recordPackageConversionReceipts = async (args) => {
+    const { result } = args;
+    if (!result.model || !result.expiresAt) {
+        args.warn?.(`12ui convert package: package ${result.packageId} answered without a`
+            + ` ${result.model ? 'viewport expiry' : 'model'}, so nothing here proves its viewport`
+            + ' conversions are still attachable. They were bought and the pages are unaffected; a'
+            + ' later run from the same screenshots will buy them again.');
+        return [];
+    }
+    const now = args.now ?? new Date();
+    const submitted = new Map(args.pages.map((page) => [page.id, page]));
+    const recorded = [];
+    for (const page of result.pages) {
+        for (const viewport of page.viewports ?? []) {
+            if (viewport.status !== 'succeeded' || !viewport.conversionId)
+                continue;
+            const source = submitted.get(page.id)?.viewports
+                .find((entry) => entry.id === viewport.id);
+            // Attached work was already proved by the receipt that named it.
+            if (!source || source.sourceConversionId)
+                continue;
+            const receipt = {
+                version: 1,
+                sha256: createHash('sha256').update(source.bytes).digest('hex'),
+                conversionId: viewport.conversionId,
+                model: result.model,
+                boughtBy: result.packageId,
+                expiresAt: result.expiresAt,
+                createdAt: now.toISOString(),
+            };
+            const write = await recordConversionReceipt(receipt, {
+                ...(args.store ? { store: args.store } : {}),
+                now,
+            });
+            if (write.failure) {
+                args.warn?.(`12ui convert package: could not record the conversion receipt for ${page.id}/`
+                    + `${viewport.id} in ${write.failure.path} (${write.failure.detail}). The package is`
+                    + ' unaffected; a later run from this screenshot will buy its conversion again.');
+                continue;
+            }
+            recorded.push(receipt);
+        }
+    }
+    return recorded;
+};
+//# sourceMappingURL=conversion-receipt.js.map

package/dist/conversion-receipt.js.map

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

package/dist/draft-adoption.d.ts

@@ -0,0 +1,48 @@
+import { type DraftPaths } from './draft-workspace.js';
+/**
+ * Which directory a `12ui draft` run continues in.
+ *
+ * MEASURED overnight 2026-08-10: a draft whose corpus search died left
+ * `…-CPcNkH` holding nothing but `references/inspire-attempt.json`, and the
+ * retry opened a NEW same-slug sibling `…-hOnLBB`. Two same-slug directories
+ * then held genuinely different candidates, so every tool that resolves a run
+ * by slug glob (`ls -dt …`) silently switched between them. The derived corpus
+ * key already stops the retry from buying the search twice, so this is a
+ * tooling-confusion hazard rather than a cost one — and the fix is to continue
+ * the stranded directory instead of stranding it.
+ *
+ * Adoption is decided on the DERIVED corpus key, never on the slug: two
+ * different design problems whose first four words match share a slug, and
+ * they must keep separate directories.
+ */
+export declare const DRAFT_CLAIM_FILENAME = "draft-claim.json";
+/**
+ * The owner marker. It is created O_EXCL the moment a run directory is created
+ * or adopted, so exactly one process can ever own a directory, and it records
+ * the derived corpus key so a run that died BEFORE writing its corpus attempt
+ * record is still adoptable on its key.
+ */
+export type DraftRunClaim = {
+    version: 1;
+    corpusKey: string;
+    pid: number;
+    hostname: string;
+    claimedAt: string;
+};
+export type AcquiredDraftRun = {
+    paths: DraftPaths;
+    /** True when this run continues an incomplete previous directory in place. */
+    adopted: boolean;
+};
+/**
+ * The run directory `12ui draft` continues in: an incomplete previous run for
+ * the same derived corpus key, adopted in place, or a fresh unique sibling.
+ */
+export declare const acquireDraftRunDirectory: (args: {
+    query: string;
+    corpusKey: string;
+    /** Overridden only by tests; production always uses the system temp root. */
+    root?: string;
+    now?: () => Date;
+}) => Promise<AcquiredDraftRun>;
+//# sourceMappingURL=draft-adoption.d.ts.map

package/dist/draft-adoption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft-adoption.d.ts","sourceRoot":"","sources":["../src/draft-adoption.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,UAAU,EAChB,MAAM,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;GAeG;AAEH,eAAO,MAAM,oBAAoB,qBAAqB,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,CAAC,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,UAAU,CAAC;IAClB,8EAA8E;IAC9E,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAkNF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,GAAU,MAAM;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB,KAAG,OAAO,CAAC,gBAAgB,CAiB3B,CAAC"}