pixelkiln 0.9.0 → 0.11.0

package/dist/cli.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import path19 from "path";
+import path20 from "path";
 import { existsSync as existsSync15 } from "fs";
-import { readFile as readFile15 } from "fs/promises";
+import { readFile as readFile16 } from "fs/promises";
 
 // src/env.ts
 import { readFileSync, existsSync } from "fs";
@@ -114,8 +114,8 @@ import { readFile } from "fs/promises";
 function sha256(data) {
   return createHash("sha256").update(data).digest("hex");
 }
-async function sha256File(path20) {
-  return sha256(await readFile(path20));
+async function sha256File(path21) {
+  return sha256(await readFile(path21));
 }
 function specHash(spec, styleImageHashes, providerOptionIdentity = spec.providerOptions) {
   return sha256(
@@ -974,9 +974,9 @@ function normalizeBaseUrl(value) {
 }
 function historyError(status) {
   const messages = Array.isArray(status.messages) ? status.messages : [];
-  for (const message2 of messages) {
-    if (!Array.isArray(message2) || message2[0] !== "execution_error" || !isObject(message2[1])) continue;
-    const detail = message2[1].exception_message;
+  for (const message3 of messages) {
+    if (!Array.isArray(message3) || message3[0] !== "execution_error" || !isObject(message3[1])) continue;
+    const detail = message3[1].exception_message;
     if (typeof detail === "string" && detail.trim()) {
       return `ComfyUI execution failed: ${detail.trim().slice(0, 300)}`;
     }
@@ -1097,8 +1097,8 @@ function validateResponse(schema, raw, operation) {
   throw new Error(`Invalid PixelLab response for ${operation}: ${issues}`);
 }
 var PixelLabError = class extends Error {
-  constructor(message2, status, body) {
-    super(message2);
+  constructor(message3, status, body) {
+    super(message3);
     this.status = status;
     this.body = body;
     this.name = "PixelLabError";
@@ -1123,11 +1123,11 @@ var PixelLabClient = class {
    * common than the failure mode of retrying (a duplicate object), and a
    * duplicate is visible and free to delete whereas a silent gap is neither.
    */
-  async request(path20, init, attempt = 0) {
+  async request(path21, init, attempt = 0) {
     const auth = this.apiKey.startsWith("Bearer ") ? this.apiKey : `Bearer ${this.apiKey}`;
     let res;
     try {
-      res = await fetch(`${BASE}${path20}`, {
+      res = await fetch(`${BASE}${path21}`, {
         ...init,
         signal: init?.signal ?? AbortSignal.timeout(this.timeoutMs),
         headers: {
@@ -1139,24 +1139,24 @@ var PixelLabClient = class {
     } catch (err) {
       if (attempt < MAX_RETRIES) {
         await sleep(backoffMs(attempt));
-        return this.request(path20, init, attempt + 1);
+        return this.request(path21, init, attempt + 1);
       }
       throw err;
     }
     if (!res.ok && shouldRetry(res.status) && attempt < MAX_RETRIES) {
       const waitMs = retryAfterMs(res.headers.get("retry-after")) ?? backoffMs(attempt);
       await sleep(waitMs);
-      return this.request(path20, init, attempt + 1);
+      return this.request(path21, init, attempt + 1);
     }
     const text = await res.text();
     if (!res.ok) {
-      throw new PixelLabError(`${init?.method ?? "GET"} ${path20} \u2192 ${res.status}`, res.status, text);
+      throw new PixelLabError(`${init?.method ?? "GET"} ${path21} \u2192 ${res.status}`, res.status, text);
     }
     if (!text) return {};
     try {
       return JSON.parse(text);
     } catch {
-      throw new Error(`${init?.method ?? "GET"} ${path20} returned invalid JSON`);
+      throw new Error(`${init?.method ?? "GET"} ${path21} returned invalid JSON`);
     }
   }
   async balance() {
@@ -1996,9 +1996,9 @@ var RetroDiffusionClient = class {
     }
     return balance;
   }
-  async call(path20, init = {}) {
+  async call(path21, init = {}) {
     if (!this.token) throw new Error("RD_API_KEY is not set");
-    const response = await this.request(`${this.baseUrl}${path20}`, {
+    const response = await this.request(`${this.baseUrl}${path21}`, {
       ...init,
       headers: {
         "Content-Type": "application/json",
@@ -2262,8 +2262,8 @@ function retroError(value) {
     if (details.length) return details.join("; ");
   }
   if (record.detail && typeof record.detail === "object") {
-    const message2 = record.detail.message;
-    if (typeof message2 === "string") return message2;
+    const message3 = record.detail.message;
+    if (typeof message3 === "string") return message3;
   }
   return JSON.stringify(value);
 }
@@ -3262,9 +3262,9 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
       );
     } catch (err) {
       failed++;
-      const message2 = err instanceof Error ? err.message : String(err);
-      upsert(lock, key, { status: "failed", error: message2, cost: 0 });
-      log2(`  FAILED ${key}: ${message2}`);
+      const message3 = err instanceof Error ? err.message : String(err);
+      upsert(lock, key, { status: "failed", error: message3, cost: 0 });
+      log2(`  FAILED ${key}: ${message3}`);
     }
     await saveLock(lockPath, lock);
   }
@@ -3452,14 +3452,14 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
         });
         result.downloaded++;
       } catch (err) {
-        const message2 = err instanceof Error ? err.message : String(err);
+        const message3 = err instanceof Error ? err.message : String(err);
         upsert(lock, key, {
           status: "download-failed",
           outputs: mergeOutputs(entry.outputs, outputs),
-          error: `download failed: ${message2}`
+          error: `download failed: ${message3}`
         });
         result.failed++;
-        log2(`  FAILED  ${key}: ${message2}`);
+        log2(`  FAILED  ${key}: ${message3}`);
       }
       await saveLock(lockPath, lock);
     }
@@ -3529,7 +3529,7 @@ import { access, stat as stat2 } from "fs/promises";
 import path10 from "path";
 async function doctor(loaded, specs, lock, lockPath, opts = {}) {
   const checks = [];
-  const add = (id, level, message2) => checks.push({ id, level, message: message2 });
+  const add = (id, level, message3) => checks.push({ id, level, message: message3 });
   add(
     "manifest",
     "ok",
@@ -3679,10 +3679,10 @@ function isSha256Hash(value) {
 function parseCache(value) {
   return HashCacheSchema.parse(value);
 }
-async function loadCache(path20) {
-  if (!existsSync8(path20)) return { version: 1, hashes: {} };
+async function loadCache(path21) {
+  if (!existsSync8(path21)) return { version: 1, hashes: {} };
   try {
-    const parsed = HashCacheSchema.safeParse(JSON.parse(await readFile6(path20, "utf8")));
+    const parsed = HashCacheSchema.safeParse(JSON.parse(await readFile6(path21, "utf8")));
     if (!parsed.success) return { version: 1, hashes: {} };
     return {
       version: 1,
@@ -3694,18 +3694,18 @@ async function loadCache(path20) {
     return { version: 1, hashes: {} };
   }
 }
-async function saveCache(path20, cache) {
+async function saveCache(path21, cache) {
   const sorted = {};
   for (const key of Object.keys(cache.hashes).sort()) {
     const hash = cache.hashes[key];
     if (!isSha256Hash(hash)) throw new Error(`Refusing to cache invalid SHA-256 for ${key}`);
     sorted[key] = hash;
   }
-  await mkdir3(pathModule.dirname(pathModule.resolve(path20)), { recursive: true });
-  const tmp = `${path20}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  await mkdir3(pathModule.dirname(pathModule.resolve(path21)), { recursive: true });
+  const tmp = `${path21}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
   try {
     await writeFile3(tmp, JSON.stringify({ version: 1, hashes: sorted }, null, 2) + "\n");
-    await rename3(tmp, path20);
+    await rename3(tmp, path21);
   } finally {
     await rm3(tmp, { force: true });
   }
@@ -4156,10 +4156,10 @@ function serveReviewPage(opts) {
           res.end(JSON.stringify(result));
           server.close(() => resolve(result));
         } catch (err) {
-          const message2 = err instanceof Error ? err.message : String(err);
-          log2(`  apply failed: ${message2}`);
+          const message3 = err instanceof Error ? err.message : String(err);
+          log2(`  apply failed: ${message3}`);
           res.writeHead(500, { "Content-Type": "text/plain" });
-          res.end(message2);
+          res.end(message3);
         }
         return;
       }
@@ -5044,938 +5044,1341 @@ async function inspectRemoteHashCache(remotePath) {
   return report;
 }
 
-// src/pipeline/tileset-export.ts
-function normalizeTileRules(raw) {
-  if (!isRecord(raw)) return null;
-  const ruleType = raw.rule_type;
-  const arity = raw.arity;
-  if (ruleType !== "edge" && ruleType !== "corner" && ruleType !== "outline") return null;
-  if (arity !== 4 && arity !== 6) return null;
-  const masks = {};
-  if (isRecord(raw.tiles)) {
-    for (const [key, value] of Object.entries(raw.tiles)) {
-      const index = tileIndex(key);
-      const mask = typeof value === "number" ? value : isRecord(value) && typeof value.bitmask === "number" ? value.bitmask : isRecord(value) && typeof value.mask === "number" ? value.mask : null;
-      if (index !== null && mask !== null && Number.isInteger(mask) && mask >= 0) masks[index] = mask;
+// src/pipeline/refine.ts
+import path18 from "path";
+import { execFile } from "child_process";
+import { mkdtemp, readFile as readFile14, rm as rm7 } from "fs/promises";
+import { tmpdir } from "os";
+import { promisify } from "util";
+
+// src/artifacts.ts
+import path17 from "path";
+import { createHash as createHash2, randomUUID as randomUUID3 } from "crypto";
+import { mkdir as mkdir5, readFile as readFile13, rename as rename5, rm as rm6, writeFile as writeFile7 } from "fs/promises";
+var activeTransactions = /* @__PURE__ */ new Set();
+function message(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function digest(data) {
+  return createHash2("sha256").update(data).digest("hex");
+}
+function portableRelative(from, to) {
+  return path17.relative(from, path17.resolve(to)).split(path17.sep).join("/") || ".";
+}
+function canonical2(value) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error("Artifact provenance numbers must be finite.");
+    return value;
+  }
+  if (Array.isArray(value)) return value.map(canonical2);
+  if (typeof value === "object") {
+    const sorted = {};
+    for (const key of Object.keys(value).sort()) {
+      const item = value[key];
+      if (item !== void 0) sorted[key] = canonical2(item);
     }
+    return sorted;
   }
-  const connectivity = raw.connectivity === "same" || raw.connectivity === "other" ? raw.connectivity : void 0;
-  const terrains = Array.isArray(raw.terrains) ? raw.terrains.filter((item) => typeof item === "string") : [];
-  return {
-    ruleType,
-    arity,
-    ...connectivity ? { connectivity } : {},
-    terrains,
-    masks,
-    raw
-  };
+  throw new Error(`Artifact provenance cannot contain ${typeof value} values.`);
 }
-function exportTileset(entry, spec, options) {
-  const outputs = resolveSpecEntryOutputs(entry, spec);
-  if (!outputs.length) throw new Error(`${spec.styleId}/${spec.assetId} has no downloaded outputs`);
-  const packed = packSprites(
-    outputs.map((output) => ({
-      id: output.role ?? fallbackOutputRole(output.index),
-      path: output.absolutePath
-    })),
-    { columns: options.columns, order: "input" }
-  );
-  if (packed.skipped.length) {
-    throw new Error(
-      `Cannot export ${spec.styleId}/${spec.assetId}: ` + packed.skipped.map((item) => `${item.id}: ${item.reason}`).join("; ")
-    );
+function fingerprint(provenance) {
+  return digest(JSON.stringify(canonical2({
+    kind: provenance.kind,
+    sources: provenance.sources,
+    options: provenance.options,
+    outputs: provenance.outputs
+  })));
+}
+function parseArtifactManifest(absolute, data) {
+  let raw;
+  try {
+    raw = JSON.parse(data);
+  } catch (error) {
+    throw new Error(`${absolute} is not valid JSON: ${message(error)}`, { cause: error });
   }
-  const metadata = entry.providerMetadata?.[entry.provider];
-  const rawRules = isRecord(metadata) ? metadata.tileRules : void 0;
-  const rules = normalizeTileRules(rawRules);
-  const frames = packed.atlas.frames;
-  const generic = buildGeneric(
-    spec,
-    options.imageName,
-    packed.atlas,
-    frames,
-    isRecord(rawRules) ? rawRules : null,
-    rules
+  if (raw.format !== "pixelkiln-artifact-bundle" || raw.version !== 1 || raw.kind !== "pack" && raw.kind !== "mount" && raw.kind !== "tileset" && raw.kind !== "refine" || typeof raw.fingerprint !== "string" || raw.options === void 0 || !Array.isArray(raw.sources) || !Array.isArray(raw.outputs)) {
+    throw new Error(`${absolute} is not a PixelKiln artifact bundle manifest.`);
+  }
+  for (const source of raw.sources) {
+    if (!source || typeof source.id !== "string" || typeof source.path !== "string" || source.sha256 !== null && typeof source.sha256 !== "string" || typeof source.included !== "boolean") {
+      throw new Error(`${absolute} contains an invalid artifact source.`);
+    }
+  }
+  for (const output of raw.outputs) {
+    if (!output || typeof output.path !== "string" || typeof output.sha256 !== "string") {
+      throw new Error(`${absolute} contains an invalid artifact output.`);
+    }
+  }
+  return raw;
+}
+async function readArtifactBundleManifest(manifestPath) {
+  const absolute = path17.resolve(manifestPath);
+  return parseArtifactManifest(absolute, await readFile13(absolute, "utf8"));
+}
+async function readOptional(file) {
+  try {
+    return await readFile13(file);
+  } catch (error) {
+    if (isCode(error, "ENOENT")) return null;
+    throw error;
+  }
+}
+function transactionMarker(journal) {
+  return `${journal}.committed`;
+}
+function processIsAlive(pid) {
+  if (!Number.isInteger(pid) || pid < 1) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return !isCode(error, "ESRCH");
+  }
+}
+function validTemporaryPath(candidate, destination, type) {
+  return path17.dirname(candidate) === path17.dirname(destination) && path17.basename(candidate).startsWith(
+    `.${path17.basename(destination)}.pixelkiln-${type}-`
   );
-  if (options.format === "generic") {
-    return {
-      png: packed.png,
-      extension: ".json",
-      document: JSON.stringify(generic, null, 2) + "\n",
-      generic,
-      sources: packed.sources
-    };
+}
+function parseTransaction(journal, data) {
+  let raw;
+  try {
+    raw = JSON.parse(data);
+  } catch (error) {
+    throw new Error(`${journal} is not valid transaction JSON: ${message(error)}`, { cause: error });
   }
-  assertUniformTiles(generic);
-  if ((rawRules !== void 0 || entry.tileFeature) && !rules) {
-    throw new Error(
-      `${options.format} export needs recognized adjacency rules; use --format generic to retain this provider rule object without guessing`
-    );
+  if (raw.format !== "pixelkiln-artifact-transaction" || raw.version !== 1 || !Number.isInteger(raw.pid) || typeof raw.createdAt !== "string" || !Array.isArray(raw.entries) || !raw.entries.length) {
+    throw new Error(`${journal} is not a PixelKiln artifact transaction.`);
   }
-  if (rules?.arity === 6) {
+  return raw;
+}
+async function removeTransactionFiles(journal) {
+  await rm6(journal, { force: true });
+  await rm6(transactionMarker(journal), { force: true });
+}
+async function recoverArtifactTransaction(recoveryFile, allowedDestinations) {
+  const journal = path17.resolve(recoveryFile);
+  const bytes = await readOptional(journal);
+  if (!bytes) {
+    await rm6(transactionMarker(journal), { force: true });
+    return;
+  }
+  if (activeTransactions.has(journal)) {
+    throw new Error(`Another artifact write in this process is already using ${journal}.`);
+  }
+  const transaction = parseTransaction(journal, bytes.toString("utf8"));
+  if (transaction.pid !== process.pid && processIsAlive(transaction.pid)) {
     throw new Error(
-      `${options.format} export does not yet map six-edge hex masks safely; use --format generic`
+      `Artifact transaction ${journal} is still owned by live process ${transaction.pid}; refusing concurrent recovery.`
     );
   }
-  if (rules?.ruleType === "outline") {
+  for (const entry of transaction.entries) {
+    if (typeof entry.destination !== "string" || typeof entry.stage !== "string" || typeof entry.sha256 !== "string" || entry.backup !== void 0 && typeof entry.backup !== "string" || !allowedDestinations.has(path17.resolve(entry.destination)) || !validTemporaryPath(entry.stage, entry.destination, "stage") || entry.backup !== void 0 && !validTemporaryPath(entry.backup, entry.destination, "backup")) {
+      throw new Error(
+        `Refusing unsafe artifact recovery from ${journal}; its destinations or temporary paths do not match the current bundle.`
+      );
+    }
+  }
+  const committed = await readOptional(transactionMarker(journal)) !== null;
+  const errors = [];
+  if (committed) {
+    for (const entry of transaction.entries) {
+      if (entry.backup) await remove2(entry.backup, errors);
+      await remove2(entry.stage, errors);
+    }
+  } else {
+    for (const entry of [...transaction.entries].reverse()) {
+      const backup = entry.backup ? await readOptional(entry.backup) : null;
+      const destination = await readOptional(entry.destination);
+      if (backup) {
+        if (destination && digest(destination) !== entry.sha256) {
+          errors.push(
+            `destination changed during interrupted recovery: ${entry.destination}; previous file remains at ${entry.backup}`
+          );
+          continue;
+        }
+        await remove2(entry.destination, errors);
+        try {
+          await rename5(entry.backup, entry.destination);
+        } catch (error) {
+          errors.push(
+            `could not restore ${entry.destination}; previous file remains at ${entry.backup}: ${message(error)}`
+          );
+        }
+      } else if (destination && digest(destination) === entry.sha256) {
+        await remove2(entry.destination, errors);
+      }
+      await remove2(entry.stage, errors);
+    }
+  }
+  if (errors.length) {
     throw new Error(
-      `${options.format} export cannot infer adjacency from outline/stamp-only rules; use --format generic`
+      `Artifact transaction recovery needs attention; journal retained at ${journal}: ` + errors.join("; ")
     );
   }
-  if (options.format === "tiled") {
-    return {
-      png: packed.png,
-      extension: ".tsj",
-      document: JSON.stringify(buildTiled(generic), null, 2) + "\n",
-      generic,
-      sources: packed.sources
-    };
-  }
-  return {
-    png: packed.png,
-    extension: ".tres",
-    document: buildGodot(generic, spec),
-    generic,
-    sources: packed.sources
-  };
+  await removeTransactionFiles(journal);
 }
-function buildGeneric(spec, imageName, atlas, frames, providerRules, rules) {
+function createArtifactBundleManifest(manifestPath, outputs, provenance) {
+  const root = path17.dirname(path17.resolve(manifestPath));
+  const sources = provenance.sources.map((source) => ({
+    ...source,
+    path: portableRelative(root, source.path)
+  }));
+  const normalized = {
+    kind: provenance.kind,
+    sources,
+    options: canonical2(provenance.options)
+  };
+  const manifestOutputs = outputs.map((output) => ({
+    path: portableRelative(root, output.path),
+    sha256: digest(output.data)
+  }));
   return {
-    format: "pixelkiln-tileset",
+    format: "pixelkiln-artifact-bundle",
     version: 1,
-    name: `${spec.styleId}/${spec.assetId}`,
-    style: spec.styleId,
-    asset: spec.assetId,
-    image: imageName,
-    tile: { ...atlas.cell },
-    sheet: { ...atlas.sheet, columns: atlas.columns },
-    tiles: frames.map((frame, index) => {
-      const sourceIndex = tileIndex(frame.id) ?? index;
-      return {
-        id: index,
-        sourceIndex,
-        role: frame.id,
-        x: frame.x,
-        y: frame.y,
-        width: frame.width,
-        height: frame.height,
-        ...rules?.masks[sourceIndex] !== void 0 ? { bitmask: rules.masks[sourceIndex] } : {},
-        stampOnly: rules ? rules.masks[sourceIndex] === void 0 : true
-      };
-    }),
-    providerRules,
-    rules
-  };
-}
-function buildTiled(generic) {
-  const rules = generic.rules;
-  const tiled = {
-    type: "tileset",
-    version: "1.10",
-    tiledversion: "1.12.2",
-    name: generic.name.replace("/", "-"),
-    tilewidth: generic.tile.width,
-    tileheight: generic.tile.height,
-    tilecount: generic.tiles.length,
-    columns: generic.sheet.columns,
-    image: generic.image,
-    imagewidth: generic.sheet.width,
-    imageheight: generic.sheet.height,
-    margin: 0,
-    spacing: 0
+    ...normalized,
+    fingerprint: fingerprint({ ...normalized, outputs: manifestOutputs }),
+    outputs: manifestOutputs
   };
-  if (!rules || rules.ruleType === "outline") return tiled;
-  const terrainNames = terrainNamesFor(rules);
-  tiled.wangsets = [{
-    name: generic.name,
-    type: rules.ruleType,
-    tile: representativeTile(generic, 0),
-    colors: terrainNames.map((name, index) => ({
-      name,
-      color: index === 0 ? "#5ab552" : "#4c78a8",
-      tile: representativeTile(generic, index),
-      probability: 1
-    })),
-    properties: rules.connectivity ? [{ name: "pixelkiln:connectivity", type: "string", value: rules.connectivity }] : [],
-    wangtiles: generic.tiles.filter((tile) => tile.bitmask !== void 0).map((tile) => ({ tileid: tile.id, wangid: tiledWangId(rules, tile.bitmask) }))
-  }];
-  return tiled;
-}
-function tiledWangId(rules, mask) {
-  const bitColor = (bit) => (mask & 1 << bit) !== 0 ? 1 : 2;
-  if (rules.ruleType === "corner") {
-    return [0, bitColor(2), 0, bitColor(0), 0, bitColor(1), 0, bitColor(3)];
-  }
-  return [bitColor(0), 0, bitColor(1), 0, bitColor(2), 0, bitColor(3), 0];
 }
-function buildGodot(generic, spec) {
-  const rules = generic.rules;
-  const lines = [
-    `[gd_resource type="TileSet" load_steps=3 format=3]`,
-    "",
-    `[ext_resource type="Texture2D" path=${JSON.stringify(`./${generic.image}`)} id="1_texture"]`,
-    "",
-    `[sub_resource type="TileSetAtlasSource" id="TileSetAtlasSource_pixelkiln"]`,
-    `texture = ExtResource("1_texture")`,
-    `texture_region_size = Vector2i(${generic.tile.width}, ${generic.tile.height})`
+function withArtifactManifest(manifestPath, outputs, provenance) {
+  const manifest = createArtifactBundleManifest(manifestPath, outputs, provenance);
+  return [
+    ...outputs,
+    { path: manifestPath, data: JSON.stringify(manifest, null, 2) + "\n" }
   ];
-  for (const tile of generic.tiles) {
-    const x = tile.id % generic.sheet.columns;
-    const y = Math.floor(tile.id / generic.sheet.columns);
-    lines.push(`${x}:${y}/0 = 0`);
-    if (!rules || tile.bitmask === void 0 || rules.ruleType === "outline") continue;
-    const values = godotTerrainBits(rules, tile.bitmask);
-    lines.push(`${x}:${y}/0/terrain_set = 0`);
-    lines.push(`${x}:${y}/0/terrain = ${dominantTerrain(values)}`);
-    for (const [side, value] of Object.entries(values)) {
-      lines.push(`${x}:${y}/0/terrains_peering_bit/${side} = ${value}`);
+}
+async function writeManagedArtifactBundle(manifestPath, outputs, provenance, options = {}) {
+  const absoluteManifest = path17.resolve(manifestPath);
+  const recoveryFile = `${absoluteManifest}.transaction`;
+  const allowedDestinations = /* @__PURE__ */ new Set([
+    absoluteManifest,
+    ...outputs.map((output) => path17.resolve(output.path))
+  ]);
+  await recoverArtifactTransaction(recoveryFile, allowedDestinations);
+  const existingManifestBytes = await readOptional(absoluteManifest);
+  let previous = null;
+  if (existingManifestBytes && !options.force) {
+    try {
+      previous = parseArtifactManifest(absoluteManifest, existingManifestBytes.toString("utf8"));
+      const valid = previous.fingerprint === fingerprint(previous);
+      if (!valid) throw new Error("its integrity fingerprint does not match");
+    } catch (error) {
+      throw new Error(
+        `Refusing to replace unrecognized or modified provenance at ${absoluteManifest}: ${message(error)}. Pass { force: true } (CLI: --force) to take ownership of this artifact bundle.`,
+        { cause: error }
+      );
     }
   }
-  lines.push("", "[resource]");
-  lines.push(`tile_size = Vector2i(${generic.tile.width}, ${generic.tile.height})`);
-  const shape = godotTileShape(spec.tileType ?? "isometric");
-  if (shape !== 0) lines.push(`tile_shape = ${shape}`);
-  if (rules && rules.ruleType !== "outline") {
-    lines.push(`terrain_set_0/mode = ${rules.ruleType === "corner" ? 1 : 2}`);
-    for (const [index, name] of terrainNamesFor(rules).entries()) {
-      lines.push(`terrain_set_0/terrain_${index}/name = ${JSON.stringify(name)}`);
-      lines.push(
-        `terrain_set_0/terrain_${index}/color = ` + (index === 0 ? "Color(0.3529, 0.7098, 0.3216, 1)" : "Color(0.298, 0.4706, 0.6588, 1)")
+  if (!options.force) {
+    const root = path17.dirname(absoluteManifest);
+    const recorded = new Map(
+      previous?.outputs.map((output) => [path17.resolve(root, output.path), output.sha256]) ?? []
+    );
+    const conflicts = [];
+    for (const output of outputs) {
+      const destination = path17.resolve(output.path);
+      const current = await readOptional(destination);
+      if (!current || digest(current) === digest(output.data)) continue;
+      const expected = recorded.get(destination);
+      if (!expected || digest(current) !== expected) conflicts.push(destination);
+    }
+    if (conflicts.length) {
+      throw new Error(
+        `Refusing to overwrite modified or unowned artifact file(s):
+` + conflicts.map((file) => `  ${file}`).join("\n") + `
+Pass { force: true } (CLI: --force) to take ownership and replace the complete bundle.`
       );
     }
   }
-  lines.push(`sources/0 = SubResource("TileSetAtlasSource_pixelkiln")`, "");
-  return lines.join("\n");
+  const { force: _force, ...bundleOptions } = options;
+  return writeArtifactBundle(
+    withArtifactManifest(absoluteManifest, outputs, provenance),
+    { ...bundleOptions, recoveryFile }
+  );
 }
-function godotTerrainBits(rules, mask) {
-  const terrain = (bit) => (mask & 1 << bit) !== 0 ? 0 : 1;
-  if (rules.ruleType === "corner") {
-    return {
-      top_left_corner: terrain(3),
-      top_right_corner: terrain(2),
-      bottom_left_corner: terrain(1),
-      bottom_right_corner: terrain(0)
-    };
+async function verifyArtifactBundle(manifestPath) {
+  const absolute = path17.resolve(manifestPath);
+  const raw = await readArtifactBundleManifest(absolute);
+  const root = path17.dirname(absolute);
+  const changedSources = [];
+  const changedOutputs = [];
+  for (const source of raw.sources) {
+    let actual = null;
+    try {
+      actual = digest(await readFile13(path17.resolve(root, source.path)));
+    } catch (error) {
+      if (!isCode(error, "ENOENT")) throw error;
+    }
+    if (actual !== source.sha256) changedSources.push(source.id);
   }
+  for (const output of raw.outputs) {
+    try {
+      if (digest(await readFile13(path17.resolve(root, output.path))) !== output.sha256) {
+        changedOutputs.push(output.path);
+      }
+    } catch (error) {
+      if (!isCode(error, "ENOENT")) throw error;
+      changedOutputs.push(output.path);
+    }
+  }
+  const fingerprintValid = raw.fingerprint === fingerprint({
+    kind: raw.kind,
+    sources: raw.sources,
+    options: raw.options,
+    outputs: raw.outputs
+  });
   return {
-    top_side: terrain(0),
-    right_side: terrain(1),
-    bottom_side: terrain(2),
-    left_side: terrain(3)
+    current: fingerprintValid && !changedSources.length && !changedOutputs.length,
+    fingerprintValid,
+    changedSources,
+    changedOutputs
   };
 }
-function dominantTerrain(values) {
-  const terrainZero = Object.values(values).filter((value) => value === 0).length;
-  return terrainZero * 2 >= Object.keys(values).length ? 0 : 1;
-}
-function godotTileShape(tileType) {
-  if (tileType === "isometric" || tileType === "oblique") return 1;
-  if (tileType === "hex" || tileType === "hex_pointy") return 3;
-  return 0;
-}
-function representativeTile(generic, terrainIndex) {
-  const rules = generic.rules;
-  const full = (1 << rules.arity) - 1;
-  const wanted = terrainIndex === 0 ? full : 0;
-  return generic.tiles.find((tile) => tile.bitmask === wanted)?.id ?? -1;
-}
-function terrainNamesFor(rules) {
-  return [rules.terrains[0] ?? "feature", rules.terrains[1] ?? "background"];
+function isCode(error, code) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
-function assertUniformTiles(generic) {
-  const mismatched = generic.tiles.filter(
-    (tile) => tile.width !== generic.tile.width || tile.height !== generic.tile.height
-  );
-  if (mismatched.length) {
-    throw new Error(
-      `Engine tilesets require uniform ${generic.tile.width}x${generic.tile.height} cells; mismatched: ${mismatched.map((tile) => tile.role).join(", ")}. Use --format generic.`
-    );
+async function remove2(file, errors) {
+  try {
+    await rm6(file, { force: true });
+  } catch (error) {
+    errors?.push(`could not remove ${file}: ${message(error)}`);
   }
 }
-function tileIndex(key) {
-  const match = key.match(/(?:^|[_-])(\d+)$/);
-  return match ? Number(match[1]) : null;
-}
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+async function rollback(prepared) {
+  const errors = [];
+  for (const artifact of [...prepared].reverse()) {
+    if (artifact.promoted) await remove2(artifact.destination, errors);
+  }
+  for (const artifact of [...prepared].reverse()) {
+    if (!artifact.backup || !artifact.backedUp) continue;
+    try {
+      await rename5(artifact.backup, artifact.destination);
+      artifact.backedUp = false;
+    } catch (error) {
+      errors.push(
+        `could not restore ${artifact.destination}; previous file remains at ${artifact.backup}: ${message(error)}`
+      );
+    }
+  }
+  for (const artifact of prepared) {
+    if (artifact.stage) await remove2(artifact.stage, errors);
+  }
+  return errors;
 }
-
-// src/pick/salvage-server.ts
-import { mkdir as mkdir5, writeFile as writeFile7, readFile as readFile13 } from "fs/promises";
-import path17 from "path";
-
-// src/pick/salvage-sheet.ts
-var escapeHtml2 = (s) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
-function renderSalvageSheet(orphans, ctx) {
-  const safe = orphans.map((o) => ({ ...o, prompt: escapeHtml2(o.prompt) }));
-  const data = JSON.stringify(safe).replace(/<\//g, "<\\/");
-  const styleId = ctx ? escapeHtml2(ctx.styleId) : null;
-  const importDir = ctx ? escapeHtml2(ctx.importDir) : null;
-  return `<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<title>pixelkiln salvage${styleId ? ` \u2014 ${styleId}` : ""}</title>
-<style>
-  :root { --bg:#0f1115; --panel:#171a21; --line:#262b36; --text:#e6e8ee; --dim:#8b93a7;
-          --import:#6ee7a8; --keep:#7cc4ff; --discard:#f87171; }
-  @media (prefers-color-scheme: light) {
-    :root { --bg:#f6f7f9; --panel:#fff; --line:#dfe3ea; --text:#1a1d23; --dim:#666e80;
-            --import:#0a8f52; --keep:#1a6fd4; --discard:#c0392b; }
+async function writeArtifactBundle(files, options = {}) {
+  if (!files.length) throw new Error("An artifact bundle must contain at least one file.");
+  const normalized = files.map((file) => {
+    if (!file.path.trim()) throw new Error("Artifact paths cannot be empty.");
+    return { destination: path17.resolve(file.path), data: Buffer.from(file.data) };
+  });
+  const destinations = /* @__PURE__ */ new Set();
+  for (const artifact of normalized) {
+    if (destinations.has(artifact.destination)) {
+      throw new Error(`Artifact bundle contains duplicate destination: ${artifact.destination}`);
+    }
+    destinations.add(artifact.destination);
   }
-  * { box-sizing:border-box; }
-  body { margin:0; background:var(--bg); color:var(--text);
-    font:14px/1.5 ui-sans-serif,-apple-system,"SF Pro Text",Inter,system-ui,sans-serif; }
-  header { position:sticky; top:0; z-index:10; background:var(--panel);
-    border-bottom:1px solid var(--line); padding:12px 20px; display:flex; gap:14px;
-    align-items:center; flex-wrap:wrap; }
-  h1 { font-size:15px; margin:0; font-weight:600; }
-  h1 .ctx { font-weight:500; color:var(--dim); }
-  h1 .dest { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:12.5px; }
-  .tally { color:var(--dim); font-variant-numeric:tabular-nums; }
-  .tally b { color:var(--text); font-weight:600; }
-  button { font:inherit; font-weight:550; border-radius:7px; padding:7px 14px;
-    border:1px solid var(--line); background:transparent; color:var(--text); cursor:pointer; }
-  button.primary { background:var(--import); border-color:var(--import); color:#08130d; }
-  button:disabled { opacity:.45; cursor:not-allowed; }
-  main { display:grid; grid-template-columns:repeat(auto-fill,minmax(190px,1fr)); gap:12px; padding:18px 20px 80px; }
-  .card { border:2px solid var(--line); border-radius:10px; background:var(--panel);
-    padding:10px; display:flex; flex-direction:column; gap:8px; }
-  .card.import { border-color:var(--import); }
-  .card.keep { border-color:var(--keep); }
-  .card.discard { border-color:var(--discard); opacity:.5; }
-  .thumb { height:120px; display:flex; align-items:center; justify-content:center;
-    border-radius:6px;
-    background-image:
-      linear-gradient(45deg,#0000 25%,#7f7f7f22 25%,#7f7f7f22 75%,#0000 75%),
-      linear-gradient(45deg,#0000 25%,#7f7f7f22 25%,#7f7f7f22 75%,#0000 75%);
-    background-size:12px 12px; background-position:0 0,6px 6px; }
-  .thumb img { image-rendering:pixelated; max-height:112px; max-width:100%; }
-  .meta { font-size:11px; color:var(--dim); font-variant-numeric:tabular-nums; }
-  .prompt { font-size:11.5px; color:var(--dim); max-height:3.2em; overflow:hidden; }
-  .acts { display:flex; gap:5px; }
-  .acts button { flex:1; padding:5px 0; font-size:11.5px; }
-  .acts button.on-import { background:var(--import); border-color:var(--import); color:#08130d; }
-  .acts button.on-keep { background:var(--keep); border-color:var(--keep); color:#04121f; }
-  .acts button.on-discard { background:var(--discard); border-color:var(--discard); color:#fff; }
-  footer { position:fixed; bottom:0; left:0; right:0; background:var(--panel);
-    border-top:1px solid var(--line); padding:10px 20px; font-size:12px; color:var(--dim); }
-  kbd { border:1px solid var(--line); border-bottom-width:2px; border-radius:4px;
-    padding:1px 5px; font-size:11px; font-family:ui-monospace,Menlo,monospace; }
-</style>
-</head>
-<body>
-<header>
-  <h1>pixelkiln salvage${styleId ? ` <span class="ctx">\u2014 ${styleId}<span class="dest"> \u2192 ${importDir}/_salvaged/</span></span>` : ""}</h1>
-  <span class="tally"><b id="ti">0</b> import \xB7 <b id="tk">0</b> keep \xB7 <b id="td">0</b> discard \xB7
-    <b id="tu">0</b> undecided</span>
-  <span style="flex:1"></span>
-  <button id="allDiscard">Discard all undecided</button>
-  <button id="allKeep">Keep all undecided</button>
-  <button id="submit" class="primary" disabled>Apply</button>
-</header>
-<main id="grid"></main>
-<footer>
-  <b>import</b> downloads it and adds it to your manifest \xB7 <b>keep</b> tags it and leaves it \xB7
-  <b>discard</b> only tags it \u2014 nothing is deleted here.
-  Hover a card and press <kbd>i</kbd> / <kbd>k</kbd> / <kbd>d</kbd>, or <kbd>u</kbd> to undo.
-</footer>
-<script>
-const ITEMS = ${data};
-const picks = new Map();
-const grid = document.getElementById('grid');
-let hovered = null;
-
-ITEMS.forEach((o, i) => {
-  const el = document.createElement('div');
-  el.className = 'card';
-  el.dataset.i = String(i);
-  el.innerHTML =
-    '<div class="thumb"><img src="' + o.previewUrl + '" loading="lazy"></div>' +
-    '<div class="meta">' + o.width + '\xD7' + o.height + ' \xB7 ' + o.createdAt.slice(0,10) + '</div>' +
-    '<div class="prompt">' + o.prompt + '</div>' +
-    '<div class="acts">' +
-      '<button data-a="import">import</button>' +
-      '<button data-a="keep">keep</button>' +
-      '<button data-a="discard">discard</button>' +
-    '</div>';
-  el.querySelectorAll('.acts button').forEach(b => {
-    b.onclick = () => choose(i, b.dataset.a);
-  });
-  el.onmouseenter = () => { hovered = i; };
-  grid.appendChild(el);
-});
-
-function choose(i, action) {
-  if (picks.get(i) === action) picks.delete(i); else picks.set(i, action);
-  const el = grid.children[i];
-  el.className = 'card' + (picks.has(i) ? ' ' + picks.get(i) : '');
-  el.querySelectorAll('.acts button').forEach(b => {
-    b.className = picks.get(i) === b.dataset.a ? 'on-' + b.dataset.a : '';
-  });
-  refresh();
-}
-
-function refresh() {
-  const c = { import: 0, keep: 0, discard: 0 };
-  for (const a of picks.values()) c[a]++;
-  ti.textContent = c.import; tk.textContent = c.keep; td.textContent = c.discard;
-  tu.textContent = ITEMS.length - picks.size;
-  document.getElementById('submit').disabled = picks.size === 0;
-}
-
-document.addEventListener('keydown', e => {
-  if (hovered === null) return;
-  const map = { i: 'import', k: 'keep', d: 'discard' };
-  if (map[e.key]) { choose(hovered, map[e.key]); e.preventDefault(); }
-  else if (e.key === 'u') { picks.delete(hovered); choose(hovered, '__none__'); }
-});
-
-document.getElementById('allKeep').onclick = () => {
-  ITEMS.forEach((_, i) => { if (!picks.has(i)) choose(i, 'keep'); });
-};
-document.getElementById('allDiscard').onclick = () => {
-  ITEMS.forEach((_, i) => { if (!picks.has(i)) choose(i, 'discard'); });
-};
-
-document.getElementById('submit').onclick = async () => {
-  const btn = document.getElementById('submit');
-  btn.disabled = true; btn.textContent = 'applying\u2026';
-  const decisions = [...picks.entries()].map(([i, action]) => ({ id: ITEMS[i].id, action }));
-  try {
-    const res = await fetch('/apply', {
-      method: 'POST', headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ decisions }),
-    });
-    if (!res.ok) throw new Error(await res.text());
-    btn.textContent = 'done \u2014 close this tab';
-    document.body.style.opacity = '.6';
-  } catch (err) {
-    btn.textContent = 'failed: ' + err.message; btn.disabled = false;
+  if (options.recoveryFile) {
+    await recoverArtifactTransaction(options.recoveryFile, destinations);
   }
-};
-refresh();
-</script>
-</body>
-</html>`;
-}
-
-// src/pick/salvage-server.ts
-var PNG_SIGNATURE2 = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
-async function runSalvage(provider, orphans, ctx, opts = {}) {
-  const log2 = opts.onProgress ?? (() => {
-  });
-  const html = renderSalvageSheet(orphans, {
-    styleId: ctx.styleId,
-    importDir: path17.relative(process.cwd(), ctx.importDir) || "."
-  });
-  const byId = new Map(orphans.map((o) => [o.id, o]));
-  const existingTags = new Map(orphans.map((o) => [o.id, o.tags]));
-  return serveReviewPage({
-    html,
-    port: opts.port,
-    open: opts.open,
-    onProgress: log2,
-    onReady: (url) => {
-      log2(`
-  ${orphans.length} unclaimed object(s) to triage: ${url}`);
-      log2(`  (nothing is deleted here \u2014 discard only tags)
-`);
-    },
-    handleApply: async (body) => {
-      const { decisions } = body;
-      const result = { imported: 0, kept: 0, discarded: 0, failed: 0 };
-      const taken = new Set(Object.keys(ctx.manifest.assets));
-      const importedAssetIds = [];
-      for (const decision of decisions) {
-        const orphan = byId.get(decision.id);
-        if (!orphan) continue;
-        if (decision.action === "import") {
-          try {
-            const buf = await provider.download(orphan.previewUrl);
-            if (!buf.subarray(0, 8).equals(PNG_SIGNATURE2)) throw new Error("not a PNG");
-            decodePng(buf);
-            const assetId = idFromPrompt(orphan.prompt, taken);
-            const rel = path17.join("_salvaged", `${assetId}.png`);
-            const outFile = path17.resolve(ctx.importDir, rel);
-            await mkdir5(path17.dirname(outFile), { recursive: true });
-            await writeFile7(outFile, buf);
-            ctx.manifest.assets[assetId] = {
-              prompt: orphan.prompt,
-              promptByStyle: {},
-              category: "_salvaged",
-              file: rel,
-              tags: ["salvaged"],
-              styles: [ctx.styleId],
-              ...orphan.width === orphan.height ? { size: orphan.width } : { width: orphan.width, height: orphan.height }
-            };
-            upsert(ctx.lock, lockKey(ctx.styleId, assetId), {
-              styleId: ctx.styleId,
-              assetId,
-              specHash: SALVAGED_SPEC_HASH,
-              generator: orphan.width === orphan.height ? "1dir" : "map",
-              prompt: orphan.prompt,
-              width: orphan.width,
-              height: orphan.height,
-              jobId: orphan.id,
-              reviewObjectId: null,
-              objectId: orphan.id,
-              candidateIndex: null,
-              status: "downloaded",
-              error: null,
-              sourceUrl: orphan.previewUrl,
-              outputs: [{
-                path: portableOutputPath(outFile, path17.dirname(ctx.manifestPath)),
-                sha256: sha256(buf)
-              }],
-              submittedAt: orphan.createdAt,
-              downloadedAt: (/* @__PURE__ */ new Date()).toISOString(),
-              cost: 0,
-              // already paid for, in an earlier period
-              costUnit: "generations",
-              provider: provider.id
-            });
-            importedAssetIds.push(assetId);
-            result.imported++;
-            log2(`  imported ${assetId} \u2190 ${orphan.id}`);
-          } catch (err) {
-            result.failed++;
-            log2(`  import failed ${orphan.id}: ${err instanceof Error ? err.message : String(err)}`);
-          }
-        } else if (decision.action === "keep") {
-          result.kept++;
-        } else {
-          result.discarded++;
-        }
+  const changed = [];
+  const unchanged = [];
+  for (const artifact of normalized) {
+    try {
+      const current = await readFile13(artifact.destination);
+      if (current.equals(artifact.data)) {
+        unchanged.push(artifact.destination);
+      } else {
+        changed.push({ ...artifact, existed: true, backedUp: false, promoted: false });
       }
-      await applyTags(provider, decisions, existingTags, { onProgress: log2 });
-      const raw = JSON.parse(await readFile13(ctx.manifestPath, "utf8"));
-      for (const id of importedAssetIds) raw.assets[id] = ctx.manifest.assets[id];
-      await writeFile7(ctx.manifestPath, JSON.stringify(raw, null, 2) + "\n");
-      await saveLock(ctx.lockPath, ctx.lock);
-      return result;
+    } catch (error) {
+      if (!isCode(error, "ENOENT")) throw error;
+      changed.push({ ...artifact, existed: false, backedUp: false, promoted: false });
     }
-  });
+  }
+  if (!changed.length) return { changed: [], unchanged };
+  const token = randomUUID3();
+  for (const [index, artifact] of changed.entries()) {
+    const basename = path17.basename(artifact.destination);
+    artifact.stage = path17.join(
+      path17.dirname(artifact.destination),
+      `.${basename}.pixelkiln-stage-${token}-${index}`
+    );
+    if (artifact.existed) {
+      artifact.backup = path17.join(
+        path17.dirname(artifact.destination),
+        `.${basename}.pixelkiln-backup-${token}-${index}`
+      );
+    }
+  }
+  const journal = options.recoveryFile ? path17.resolve(options.recoveryFile) : null;
+  if (journal) {
+    await mkdir5(path17.dirname(journal), { recursive: true });
+    const transaction = {
+      format: "pixelkiln-artifact-transaction",
+      version: 1,
+      pid: process.pid,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      entries: changed.map((artifact) => ({
+        destination: artifact.destination,
+        stage: artifact.stage,
+        ...artifact.backup ? { backup: artifact.backup } : {},
+        sha256: digest(artifact.data)
+      }))
+    };
+    try {
+      await writeFile7(journal, JSON.stringify(transaction, null, 2) + "\n", { flag: "wx" });
+      activeTransactions.add(journal);
+    } catch (error) {
+      throw new Error(
+        `Could not start durable artifact transaction at ${journal}: ${message(error)}`,
+        { cause: error }
+      );
+    }
+  }
+  try {
+    for (const [index, artifact] of changed.entries()) {
+      await mkdir5(path17.dirname(artifact.destination), { recursive: true });
+      await options.beforeStage?.(artifact.destination, index);
+      await writeFile7(artifact.stage, artifact.data, { flag: "wx" });
+    }
+  } catch (error) {
+    const cleanupErrors2 = await rollback(changed);
+    if (journal && !cleanupErrors2.length) await removeTransactionFiles(journal);
+    if (journal) activeTransactions.delete(journal);
+    const suffix = cleanupErrors2.length ? ` Cleanup also failed: ${cleanupErrors2.join("; ")}` : "";
+    throw new Error(`Could not stage artifact bundle: ${message(error)}.${suffix}`, { cause: error });
+  }
+  let durableCommit = false;
+  try {
+    for (const artifact of changed) {
+      if (!artifact.existed) continue;
+      await rename5(artifact.destination, artifact.backup);
+      artifact.backedUp = true;
+    }
+    for (const [index, artifact] of changed.entries()) {
+      await options.beforePromote?.(artifact.destination, index);
+      await rename5(artifact.stage, artifact.destination);
+      artifact.stage = void 0;
+      artifact.promoted = true;
+    }
+    if (journal) {
+      await writeFile7(transactionMarker(journal), `${token}
+`, { flag: "wx" });
+      durableCommit = true;
+      await options.afterCommit?.();
+    }
+  } catch (error) {
+    if (durableCommit) {
+      if (journal) activeTransactions.delete(journal);
+      throw new Error(
+        `Artifact bundle was committed, but final cleanup was interrupted: ${message(error)}. The next write will finish cleanup from ${journal}.`,
+        { cause: error }
+      );
+    }
+    const rollbackErrors = await rollback(changed);
+    if (journal && !rollbackErrors.length) await removeTransactionFiles(journal);
+    if (journal) activeTransactions.delete(journal);
+    const suffix = rollbackErrors.length ? ` Rollback needs attention: ${rollbackErrors.join("; ")}` : " Previous bundle restored.";
+    throw new Error(`Could not promote artifact bundle: ${message(error)}.${suffix}`, { cause: error });
+  }
+  const cleanupErrors = [];
+  for (const artifact of changed) {
+    if (artifact.backup) await remove2(artifact.backup, cleanupErrors);
+  }
+  if (cleanupErrors.length) {
+    if (journal) activeTransactions.delete(journal);
+    throw new Error(
+      `Artifact bundle was written, but old backup cleanup failed: ${cleanupErrors.join("; ")}`
+    );
+  }
+  if (journal) {
+    try {
+      await removeTransactionFiles(journal);
+    } finally {
+      activeTransactions.delete(journal);
+    }
+  }
+  return {
+    changed: changed.map((artifact) => artifact.destination),
+    unchanged
+  };
 }
 
-// src/artifacts.ts
-import path18 from "path";
-import { createHash as createHash2, randomUUID as randomUUID3 } from "crypto";
-import { mkdir as mkdir6, readFile as readFile14, rename as rename5, rm as rm6, writeFile as writeFile8 } from "fs/promises";
-var activeTransactions = /* @__PURE__ */ new Set();
-function message(error) {
+// src/pipeline/refine.ts
+var execFileAsync = promisify(execFile);
+var PIXEL_ART_FIXER_URL = "https://github.com/Retro-Diffusion/pixel-art-fixer";
+var PIXEL_ART_FIXER_REVISION = "ef376e57e1c272633ca2dbf5f29ec3fcf6596465";
+function message2(error) {
   return error instanceof Error ? error.message : String(error);
 }
-function digest(data) {
-  return createHash2("sha256").update(data).digest("hex");
-}
-function portableRelative(from, to) {
-  return path18.relative(from, path18.resolve(to)).split(path18.sep).join("/") || ".";
-}
-function canonical2(value) {
-  if (value === null || typeof value === "string" || typeof value === "boolean") return value;
-  if (typeof value === "number") {
-    if (!Number.isFinite(value)) throw new Error("Artifact provenance numbers must be finite.");
-    return value;
+function qualityRecordPath(output) {
+  if (!/\.png$/i.test(output)) throw new Error("Refined output must be a .png file.");
+  return output.replace(/\.png$/i, ".pixelkiln.json");
+}
+function confidenceFor(consensus) {
+  if (consensus.startsWith("fast:")) return "high";
+  if (consensus === "arbitrated" || consensus === "forced" || consensus.startsWith("fastmode:") && consensus.includes("+")) return "medium";
+  return "low";
+}
+var confidenceRank = { low: 0, medium: 1, high: 2 };
+function requireConfidence(value) {
+  if (value === "low" || value === "medium" || value === "high") return value;
+  throw new Error(`Unknown grid confidence "${value}"; expected low, medium, or high.`);
+}
+function firstJsonObject(text) {
+  const start = text.indexOf("{");
+  if (start < 0) throw new Error("Pixel Art Fixer did not print detection JSON.");
+  let depth = 0;
+  let string = false;
+  let escaped = false;
+  for (let i = start; i < text.length; i++) {
+    const char = text[i];
+    if (string) {
+      if (escaped) escaped = false;
+      else if (char === "\\") escaped = true;
+      else if (char === '"') string = false;
+      continue;
+    }
+    if (char === '"') string = true;
+    else if (char === "{") depth++;
+    else if (char === "}" && --depth === 0) {
+      try {
+        return JSON.parse(text.slice(start, i + 1));
+      } catch (error) {
+        throw new Error(`Pixel Art Fixer printed invalid detection JSON: ${message2(error)}`);
+      }
+    }
   }
-  if (Array.isArray(value)) return value.map(canonical2);
-  if (typeof value === "object") {
-    const sorted = {};
-    for (const key of Object.keys(value).sort()) {
-      const item = value[key];
-      if (item !== void 0) sorted[key] = canonical2(item);
+  throw new Error("Pixel Art Fixer printed incomplete detection JSON.");
+}
+var PYTHON_FIXER_BRIDGE = [
+  "import json, sys",
+  "from pixelfixer.api import process",
+  "result = process(open(sys.argv[1], 'rb').read(), mode='full')",
+  "open(sys.argv[2], 'wb').write(result.pop('png'))",
+  "print(json.dumps(result))"
+].join("; ");
+function parseDetection(raw) {
+  if (!raw || typeof raw !== "object") throw new Error("Pixel Art Fixer returned no detection result.");
+  const value = raw;
+  const stepX = Number(value.step_x);
+  const stepY = Number(value.step_y);
+  const columns = Number(value.cols);
+  const rows = Number(value.rows);
+  const consensus = value.consensus;
+  if (!Number.isFinite(stepX) || stepX <= 0 || !Number.isFinite(stepY) || stepY <= 0 || !Number.isInteger(columns) || columns < 1 || !Number.isInteger(rows) || rows < 1 || typeof consensus !== "string" || !consensus) {
+    throw new Error("Pixel Art Fixer returned an invalid grid detection result.");
+  }
+  return {
+    stepX,
+    stepY,
+    columns,
+    rows,
+    consensus,
+    confidence: confidenceFor(consensus)
+  };
+}
+function normalizePalette(values) {
+  const colors = /* @__PURE__ */ new Map();
+  for (const value of values) {
+    const rgb = parseHex(value);
+    const hex2 = `#${rgb.r.toString(16).padStart(2, "0")}${rgb.g.toString(16).padStart(2, "0")}${rgb.b.toString(16).padStart(2, "0")}`;
+    colors.set(hex2, { hex: hex2, ...rgb });
+  }
+  if (colors.size < 2 || colors.size > 256) {
+    throw new Error(`A refinement palette must contain 2\u2013256 unique colors; got ${colors.size}.`);
+  }
+  return [...colors.values()];
+}
+function quantizeToPalette(png, palette) {
+  const colors = normalizePalette(palette);
+  const pixels = Buffer.from(png.pixels);
+  for (let i = 0; i < pixels.length; i += 4) {
+    const alpha = pixels[i + 3];
+    if (alpha === 0) {
+      pixels[i] = 0;
+      pixels[i + 1] = 0;
+      pixels[i + 2] = 0;
+      continue;
     }
-    return sorted;
+    const pixel = { r: pixels[i], g: pixels[i + 1], b: pixels[i + 2] };
+    let nearest = colors[0];
+    let distance = colorDistance(pixel, nearest);
+    for (let j = 1; j < colors.length; j++) {
+      const candidate = colors[j];
+      const candidateDistance = colorDistance(pixel, candidate);
+      if (candidateDistance < distance) {
+        nearest = candidate;
+        distance = candidateDistance;
+      }
+    }
+    pixels[i] = nearest.r;
+    pixels[i + 1] = nearest.g;
+    pixels[i + 2] = nearest.b;
   }
-  throw new Error(`Artifact provenance cannot contain ${typeof value} values.`);
+  return { width: png.width, height: png.height, pixels };
 }
-function fingerprint(provenance) {
-  return digest(JSON.stringify(canonical2({
-    kind: provenance.kind,
-    sources: provenance.sources,
-    options: provenance.options,
-    outputs: provenance.outputs
-  })));
+function colorCount(png) {
+  const colors = /* @__PURE__ */ new Set();
+  for (let i = 0; i < png.pixels.length; i += 4) {
+    if (png.pixels[i + 3] < 128) continue;
+    colors.add(png.pixels[i] << 16 | png.pixels[i + 1] << 8 | png.pixels[i + 2]);
+  }
+  return colors.size;
 }
-function parseArtifactManifest(absolute, data) {
-  let raw;
-  try {
-    raw = JSON.parse(data);
-  } catch (error) {
-    throw new Error(`${absolute} is not valid JSON: ${message(error)}`, { cause: error });
+function unexpectedPaletteColors(png, palette) {
+  const allowed = new Set(palette.map((hex2) => {
+    const color = parseHex(hex2);
+    return color.r << 16 | color.g << 8 | color.b;
+  }));
+  const unexpected = /* @__PURE__ */ new Set();
+  for (let i = 0; i < png.pixels.length; i += 4) {
+    if (png.pixels[i + 3] === 0) continue;
+    const color = png.pixels[i] << 16 | png.pixels[i + 1] << 8 | png.pixels[i + 2];
+    if (!allowed.has(color)) unexpected.add(color);
+  }
+  return unexpected.size;
+}
+function auditRefinement(png, detection, palette, minTransparency, minGridConfidence) {
+  const colors = colorCount(png);
+  const unexpectedColors = unexpectedPaletteColors(png, palette);
+  const transparency = transparencyRatio(png);
+  const reasons = [];
+  if (png.width !== detection.columns || png.height !== detection.rows) {
+    reasons.push(
+      `native output is ${png.width}x${png.height}, expected detected grid ${detection.columns}x${detection.rows}`
+    );
   }
-  if (raw.format !== "pixelkiln-artifact-bundle" || raw.version !== 1 || raw.kind !== "pack" && raw.kind !== "mount" && raw.kind !== "tileset" || typeof raw.fingerprint !== "string" || raw.options === void 0 || !Array.isArray(raw.sources) || !Array.isArray(raw.outputs)) {
-    throw new Error(`${absolute} is not a PixelKiln artifact bundle manifest.`);
+  if (colors > palette.length) reasons.push(`opaque color count ${colors} exceeds ${palette.length}`);
+  if (unexpectedColors) reasons.push(`${unexpectedColors} visible color(s) are outside the final palette`);
+  if (minTransparency !== void 0 && transparency < minTransparency) {
+    reasons.push(
+      `transparency ${(transparency * 100).toFixed(1)}% is below ${(minTransparency * 100).toFixed(1)}%`
+    );
   }
-  for (const source of raw.sources) {
-    if (!source || typeof source.id !== "string" || typeof source.path !== "string" || source.sha256 !== null && typeof source.sha256 !== "string" || typeof source.included !== "boolean") {
-      throw new Error(`${absolute} contains an invalid artifact source.`);
-    }
+  if (confidenceRank[detection.confidence] < confidenceRank[minGridConfidence]) {
+    reasons.push(
+      `grid confidence ${detection.confidence} is below required ${minGridConfidence} (${detection.consensus})`
+    );
   }
-  for (const output of raw.outputs) {
-    if (!output || typeof output.path !== "string" || typeof output.sha256 !== "string") {
-      throw new Error(`${absolute} contains an invalid artifact output.`);
-    }
+  return {
+    width: png.width,
+    height: png.height,
+    colorCount: colors,
+    paletteConformant: unexpectedColors === 0,
+    transparency,
+    thresholds: {
+      maxColors: palette.length,
+      minTransparency: minTransparency ?? null,
+      minGridConfidence
+    },
+    safe: reasons.length === 0,
+    reasons
+  };
+}
+function isGridConfidence(value) {
+  return value === "low" || value === "medium" || value === "high";
+}
+function parseRecordOptions(manifest, record) {
+  if (manifest.kind !== "refine") throw new Error(`${record} is not a PixelKiln refinement record.`);
+  const raw = manifest.options;
+  if (!raw || typeof raw !== "object") throw new Error(`${record} has invalid quality metadata.`);
+  const options = raw;
+  const grid = options.nativeGrid;
+  const palette = options.palette;
+  const audit = options.audit;
+  const review = options.review;
+  if (options.schema !== "pixelkiln-quality" || options.version !== 1 || !grid || grid.tool !== "pixel-art-fixer" || grid.url !== PIXEL_ART_FIXER_URL || typeof grid.revision !== "string" || !grid.revision || grid.protocol !== "python-api-v1" && grid.protocol !== "python-cli-v1" || !isGridConfidence(grid.confidence) || typeof grid.consensus !== "string" || !Number.isFinite(grid.stepX) || !Number.isFinite(grid.stepY) || !Number.isInteger(grid.sourceWidth) || !Number.isInteger(grid.sourceHeight) || !Number.isInteger(grid.nativeWidth) || !Number.isInteger(grid.nativeHeight) || !palette || !Array.isArray(palette.colors) || palette.colors.length < 2 || !palette.colors.every((color) => typeof color === "string") || palette.dither !== "none" || palette.distance !== "redmean" || !audit || typeof audit.safe !== "boolean" || typeof audit.paletteConformant !== "boolean" || !Array.isArray(audit.reasons) || !review || review.status !== "pending" && review.status !== "approved") {
+    throw new Error(`${record} has invalid quality metadata.`);
   }
-  return raw;
+  return options;
 }
-async function readOptional(file) {
+async function refineAsset(options) {
+  const source = path18.resolve(options.source);
+  const output = path18.resolve(options.output);
+  if (source === output) throw new Error("Refinement source and output must be different files.");
+  const record = path18.resolve(qualityRecordPath(output));
+  const palette = normalizePalette(options.palette).map((color) => color.hex);
+  const minGridConfidence = requireConfidence(options.minGridConfidence ?? "high");
+  if (options.minTransparency !== void 0 && (!Number.isFinite(options.minTransparency) || options.minTransparency < 0 || options.minTransparency > 1)) throw new Error("minTransparency must be between 0 and 1.");
+  let sourcePng;
   try {
-    return await readFile14(file);
+    sourcePng = decodePng(await readFile14(source));
   } catch (error) {
-    if (isCode(error, "ENOENT")) return null;
-    throw error;
+    throw new Error(`Cannot read refinement source ${source}: ${message2(error)}`, { cause: error });
   }
+  const temp = await mkdtemp(path18.join(tmpdir(), "pixelkiln-refine-"));
+  const recovered = path18.join(temp, "native.png");
+  const compatibilityCommand = options.fixerCommand;
+  const fixerCommand = compatibilityCommand ?? options.fixerPython ?? process.env.PIXELKILN_PIXEL_FIXER_PYTHON ?? "python3";
+  const args = compatibilityCommand ? [...options.fixerArgsPrefix ?? [], source, "--extract", recovered] : ["-c", PYTHON_FIXER_BRIDGE, source, recovered];
+  try {
+    let stdout;
+    try {
+      const result = await execFileAsync(fixerCommand, args, {
+        encoding: "utf8",
+        maxBuffer: 4 * 1024 * 1024,
+        timeout: 10 * 60 * 1e3
+      });
+      stdout = result.stdout;
+    } catch (error) {
+      const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : "";
+      const install = `Install the pinned Python package from ${PIXEL_ART_FIXER_URL} at ${options.fixerRevision ?? PIXEL_ART_FIXER_REVISION}, or pass --fixer-python.`;
+      throw new Error(
+        code === "ENOENT" ? `Pixel Art Fixer command not found: ${fixerCommand}. ${install}` : `Pixel Art Fixer failed: ${message2(error)}. ${install}`,
+        { cause: error }
+      );
+    }
+    const detection = parseDetection(firstJsonObject(stdout));
+    const native = decodePng(await readFile14(recovered));
+    const quantized = quantizeToPalette(native, palette);
+    const png = encodeRgbaPng(quantized.width, quantized.height, quantized.pixels);
+    const audit = auditRefinement(
+      quantized,
+      detection,
+      palette,
+      options.minTransparency,
+      minGridConfidence
+    );
+    if (!audit.safe) {
+      throw new Error(`Refinement failed its quality audit: ${audit.reasons.join("; ")}`);
+    }
+    const provenanceSource = {
+      id: "source",
+      path: source,
+      sha256: await sha256File(source),
+      included: true
+    };
+    const recordOptions = {
+      schema: "pixelkiln-quality",
+      version: 1,
+      nativeGrid: {
+        tool: "pixel-art-fixer",
+        url: PIXEL_ART_FIXER_URL,
+        revision: options.fixerRevision ?? PIXEL_ART_FIXER_REVISION,
+        protocol: compatibilityCommand ? "python-cli-v1" : "python-api-v1",
+        confidence: detection.confidence,
+        consensus: detection.consensus,
+        stepX: detection.stepX,
+        stepY: detection.stepY,
+        sourceWidth: sourcePng.width,
+        sourceHeight: sourcePng.height,
+        nativeWidth: quantized.width,
+        nativeHeight: quantized.height
+      },
+      palette: { colors: palette, dither: "none", distance: "redmean" },
+      audit,
+      review: { status: "pending" }
+    };
+    await writeManagedArtifactBundle(
+      record,
+      [{ path: output, data: png }],
+      { kind: "refine", sources: [provenanceSource], options: recordOptions },
+      { force: options.force }
+    );
+    return { source, output, record, detection, palette, audit };
+  } finally {
+    await rm7(temp, { recursive: true, force: true });
+  }
+}
+async function checkQualityRecord(recordPath) {
+  const record = path18.resolve(recordPath);
+  const manifest = await readArtifactBundleManifest(record);
+  const options = parseRecordOptions(manifest, record);
+  const verification = await verifyArtifactBundle(record);
+  const output = manifest.outputs.length === 1 ? path18.resolve(path18.dirname(record), manifest.outputs[0].path) : "";
+  const reasons = [];
+  if (!verification.fingerprintValid) reasons.push("quality record fingerprint changed");
+  for (const source of verification.changedSources) reasons.push(`source changed: ${source}`);
+  for (const changed of verification.changedOutputs) reasons.push(`output changed: ${changed}`);
+  if (manifest.sources.length !== 1) reasons.push("quality record must contain exactly one source");
+  if (manifest.outputs.length !== 1) reasons.push("quality record must contain exactly one output");
+  if (!options.audit.safe) reasons.push(...options.audit.reasons.map((reason) => `audit: ${reason}`));
+  if (options.review.status !== "approved") reasons.push("human 1\xD7 review is pending");
+  return {
+    safe: reasons.length === 0,
+    current: verification.current,
+    approved: options.review.status === "approved",
+    auditSafe: options.audit.safe,
+    record,
+    output,
+    options,
+    reasons
+  };
 }
-function transactionMarker(journal) {
-  return `${journal}.committed`;
+async function approveQualityRecord(recordPath, approval) {
+  const reviewer = approval.reviewer.trim();
+  if (!reviewer) throw new Error("A human reviewer name is required.");
+  const record = path18.resolve(recordPath);
+  const manifest = await readArtifactBundleManifest(record);
+  const options = parseRecordOptions(manifest, record);
+  const verification = await verifyArtifactBundle(record);
+  if (!verification.current) {
+    const changes = [
+      ...verification.changedSources.map((source) => `source ${source}`),
+      ...verification.changedOutputs.map((output2) => `output ${output2}`),
+      ...!verification.fingerprintValid ? ["quality metadata"] : []
+    ];
+    throw new Error(`Cannot approve a stale refinement; changed: ${changes.join(", ")}. Run refine again.`);
+  }
+  if (!options.audit.safe) {
+    throw new Error(`Cannot approve a failed quality audit: ${options.audit.reasons.join("; ")}`);
+  }
+  if (manifest.sources.length !== 1 || manifest.outputs.length !== 1) {
+    throw new Error("A refinement record must contain exactly one source and one output.");
+  }
+  const root = path18.dirname(record);
+  const outputPath = path18.resolve(root, manifest.outputs[0].path);
+  const output = await readFile14(outputPath);
+  const sources = manifest.sources.map((source) => ({
+    ...source,
+    path: path18.resolve(root, source.path)
+  }));
+  const approved = {
+    ...options,
+    review: {
+      status: "approved",
+      reviewer,
+      approvedAt: (approval.approvedAt ?? /* @__PURE__ */ new Date()).toISOString(),
+      checklist: {
+        nativeScale: true,
+        crispEdges: true,
+        subjectReadable: true,
+        paletteSeparation: true,
+        alphaAndSeams: true
+      },
+      ...approval.note?.trim() ? { note: approval.note.trim() } : {}
+    }
+  };
+  await writeManagedArtifactBundle(
+    record,
+    [{ path: outputPath, data: output }],
+    { kind: "refine", sources, options: approved }
+  );
+  return checkQualityRecord(record);
 }
-function processIsAlive(pid) {
-  if (!Number.isInteger(pid) || pid < 1) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (error) {
-    return !isCode(error, "ESRCH");
+
+// src/pipeline/tileset-export.ts
+function normalizeTileRules(raw) {
+  if (!isRecord(raw)) return null;
+  const ruleType = raw.rule_type;
+  const arity = raw.arity;
+  if (ruleType !== "edge" && ruleType !== "corner" && ruleType !== "outline") return null;
+  if (arity !== 4 && arity !== 6) return null;
+  const masks = {};
+  if (isRecord(raw.tiles)) {
+    for (const [key, value] of Object.entries(raw.tiles)) {
+      const index = tileIndex(key);
+      const mask = typeof value === "number" ? value : isRecord(value) && typeof value.bitmask === "number" ? value.bitmask : isRecord(value) && typeof value.mask === "number" ? value.mask : null;
+      if (index !== null && mask !== null && Number.isInteger(mask) && mask >= 0) masks[index] = mask;
+    }
   }
+  const connectivity = raw.connectivity === "same" || raw.connectivity === "other" ? raw.connectivity : void 0;
+  const terrains = Array.isArray(raw.terrains) ? raw.terrains.filter((item) => typeof item === "string") : [];
+  return {
+    ruleType,
+    arity,
+    ...connectivity ? { connectivity } : {},
+    terrains,
+    masks,
+    raw
+  };
 }
-function validTemporaryPath(candidate, destination, type) {
-  return path18.dirname(candidate) === path18.dirname(destination) && path18.basename(candidate).startsWith(
-    `.${path18.basename(destination)}.pixelkiln-${type}-`
+function exportTileset(entry, spec, options) {
+  const outputs = resolveSpecEntryOutputs(entry, spec);
+  if (!outputs.length) throw new Error(`${spec.styleId}/${spec.assetId} has no downloaded outputs`);
+  const packed = packSprites(
+    outputs.map((output) => ({
+      id: output.role ?? fallbackOutputRole(output.index),
+      path: output.absolutePath
+    })),
+    { columns: options.columns, order: "input" }
   );
-}
-function parseTransaction(journal, data) {
-  let raw;
-  try {
-    raw = JSON.parse(data);
-  } catch (error) {
-    throw new Error(`${journal} is not valid transaction JSON: ${message(error)}`, { cause: error });
-  }
-  if (raw.format !== "pixelkiln-artifact-transaction" || raw.version !== 1 || !Number.isInteger(raw.pid) || typeof raw.createdAt !== "string" || !Array.isArray(raw.entries) || !raw.entries.length) {
-    throw new Error(`${journal} is not a PixelKiln artifact transaction.`);
-  }
-  return raw;
-}
-async function removeTransactionFiles(journal) {
-  await rm6(journal, { force: true });
-  await rm6(transactionMarker(journal), { force: true });
-}
-async function recoverArtifactTransaction(recoveryFile, allowedDestinations) {
-  const journal = path18.resolve(recoveryFile);
-  const bytes = await readOptional(journal);
-  if (!bytes) {
-    await rm6(transactionMarker(journal), { force: true });
-    return;
+  if (packed.skipped.length) {
+    throw new Error(
+      `Cannot export ${spec.styleId}/${spec.assetId}: ` + packed.skipped.map((item) => `${item.id}: ${item.reason}`).join("; ")
+    );
   }
-  if (activeTransactions.has(journal)) {
-    throw new Error(`Another artifact write in this process is already using ${journal}.`);
+  const metadata = entry.providerMetadata?.[entry.provider];
+  const rawRules = isRecord(metadata) ? metadata.tileRules : void 0;
+  const rules = normalizeTileRules(rawRules);
+  const frames = packed.atlas.frames;
+  const generic = buildGeneric(
+    spec,
+    options.imageName,
+    packed.atlas,
+    frames,
+    isRecord(rawRules) ? rawRules : null,
+    rules
+  );
+  if (options.format === "generic") {
+    return {
+      png: packed.png,
+      extension: ".json",
+      document: JSON.stringify(generic, null, 2) + "\n",
+      generic,
+      sources: packed.sources
+    };
   }
-  const transaction = parseTransaction(journal, bytes.toString("utf8"));
-  if (transaction.pid !== process.pid && processIsAlive(transaction.pid)) {
+  assertUniformTiles(generic);
+  if ((rawRules !== void 0 || entry.tileFeature) && !rules) {
     throw new Error(
-      `Artifact transaction ${journal} is still owned by live process ${transaction.pid}; refusing concurrent recovery.`
+      `${options.format} export needs recognized adjacency rules; use --format generic to retain this provider rule object without guessing`
     );
   }
-  for (const entry of transaction.entries) {
-    if (typeof entry.destination !== "string" || typeof entry.stage !== "string" || typeof entry.sha256 !== "string" || entry.backup !== void 0 && typeof entry.backup !== "string" || !allowedDestinations.has(path18.resolve(entry.destination)) || !validTemporaryPath(entry.stage, entry.destination, "stage") || entry.backup !== void 0 && !validTemporaryPath(entry.backup, entry.destination, "backup")) {
-      throw new Error(
-        `Refusing unsafe artifact recovery from ${journal}; its destinations or temporary paths do not match the current bundle.`
-      );
-    }
-  }
-  const committed = await readOptional(transactionMarker(journal)) !== null;
-  const errors = [];
-  if (committed) {
-    for (const entry of transaction.entries) {
-      if (entry.backup) await remove2(entry.backup, errors);
-      await remove2(entry.stage, errors);
-    }
-  } else {
-    for (const entry of [...transaction.entries].reverse()) {
-      const backup = entry.backup ? await readOptional(entry.backup) : null;
-      const destination = await readOptional(entry.destination);
-      if (backup) {
-        if (destination && digest(destination) !== entry.sha256) {
-          errors.push(
-            `destination changed during interrupted recovery: ${entry.destination}; previous file remains at ${entry.backup}`
-          );
-          continue;
-        }
-        await remove2(entry.destination, errors);
-        try {
-          await rename5(entry.backup, entry.destination);
-        } catch (error) {
-          errors.push(
-            `could not restore ${entry.destination}; previous file remains at ${entry.backup}: ${message(error)}`
-          );
-        }
-      } else if (destination && digest(destination) === entry.sha256) {
-        await remove2(entry.destination, errors);
-      }
-      await remove2(entry.stage, errors);
-    }
+  if (rules?.arity === 6) {
+    throw new Error(
+      `${options.format} export does not yet map six-edge hex masks safely; use --format generic`
+    );
   }
-  if (errors.length) {
+  if (rules?.ruleType === "outline") {
     throw new Error(
-      `Artifact transaction recovery needs attention; journal retained at ${journal}: ` + errors.join("; ")
+      `${options.format} export cannot infer adjacency from outline/stamp-only rules; use --format generic`
     );
   }
-  await removeTransactionFiles(journal);
-}
-function createArtifactBundleManifest(manifestPath, outputs, provenance) {
-  const root = path18.dirname(path18.resolve(manifestPath));
-  const sources = provenance.sources.map((source) => ({
-    ...source,
-    path: portableRelative(root, source.path)
-  }));
-  const normalized = {
-    kind: provenance.kind,
-    sources,
-    options: canonical2(provenance.options)
+  if (options.format === "tiled") {
+    return {
+      png: packed.png,
+      extension: ".tsj",
+      document: JSON.stringify(buildTiled(generic), null, 2) + "\n",
+      generic,
+      sources: packed.sources
+    };
+  }
+  return {
+    png: packed.png,
+    extension: ".tres",
+    document: buildGodot(generic, spec),
+    generic,
+    sources: packed.sources
   };
-  const manifestOutputs = outputs.map((output) => ({
-    path: portableRelative(root, output.path),
-    sha256: digest(output.data)
-  }));
+}
+function buildGeneric(spec, imageName, atlas, frames, providerRules, rules) {
   return {
-    format: "pixelkiln-artifact-bundle",
+    format: "pixelkiln-tileset",
     version: 1,
-    ...normalized,
-    fingerprint: fingerprint({ ...normalized, outputs: manifestOutputs }),
-    outputs: manifestOutputs
+    name: `${spec.styleId}/${spec.assetId}`,
+    style: spec.styleId,
+    asset: spec.assetId,
+    image: imageName,
+    tile: { ...atlas.cell },
+    sheet: { ...atlas.sheet, columns: atlas.columns },
+    tiles: frames.map((frame, index) => {
+      const sourceIndex = tileIndex(frame.id) ?? index;
+      return {
+        id: index,
+        sourceIndex,
+        role: frame.id,
+        x: frame.x,
+        y: frame.y,
+        width: frame.width,
+        height: frame.height,
+        ...rules?.masks[sourceIndex] !== void 0 ? { bitmask: rules.masks[sourceIndex] } : {},
+        stampOnly: rules ? rules.masks[sourceIndex] === void 0 : true
+      };
+    }),
+    providerRules,
+    rules
   };
 }
-function withArtifactManifest(manifestPath, outputs, provenance) {
-  const manifest = createArtifactBundleManifest(manifestPath, outputs, provenance);
-  return [
-    ...outputs,
-    { path: manifestPath, data: JSON.stringify(manifest, null, 2) + "\n" }
-  ];
+function buildTiled(generic) {
+  const rules = generic.rules;
+  const tiled = {
+    type: "tileset",
+    version: "1.10",
+    tiledversion: "1.12.2",
+    name: generic.name.replace("/", "-"),
+    tilewidth: generic.tile.width,
+    tileheight: generic.tile.height,
+    tilecount: generic.tiles.length,
+    columns: generic.sheet.columns,
+    image: generic.image,
+    imagewidth: generic.sheet.width,
+    imageheight: generic.sheet.height,
+    margin: 0,
+    spacing: 0
+  };
+  if (!rules || rules.ruleType === "outline") return tiled;
+  const terrainNames = terrainNamesFor(rules);
+  tiled.wangsets = [{
+    name: generic.name,
+    type: rules.ruleType,
+    tile: representativeTile(generic, 0),
+    colors: terrainNames.map((name, index) => ({
+      name,
+      color: index === 0 ? "#5ab552" : "#4c78a8",
+      tile: representativeTile(generic, index),
+      probability: 1
+    })),
+    properties: rules.connectivity ? [{ name: "pixelkiln:connectivity", type: "string", value: rules.connectivity }] : [],
+    wangtiles: generic.tiles.filter((tile) => tile.bitmask !== void 0).map((tile) => ({ tileid: tile.id, wangid: tiledWangId(rules, tile.bitmask) }))
+  }];
+  return tiled;
 }
-async function writeManagedArtifactBundle(manifestPath, outputs, provenance, options = {}) {
-  const absoluteManifest = path18.resolve(manifestPath);
-  const recoveryFile = `${absoluteManifest}.transaction`;
-  const allowedDestinations = /* @__PURE__ */ new Set([
-    absoluteManifest,
-    ...outputs.map((output) => path18.resolve(output.path))
-  ]);
-  await recoverArtifactTransaction(recoveryFile, allowedDestinations);
-  const existingManifestBytes = await readOptional(absoluteManifest);
-  let previous = null;
-  if (existingManifestBytes && !options.force) {
-    try {
-      previous = parseArtifactManifest(absoluteManifest, existingManifestBytes.toString("utf8"));
-      const valid = previous.fingerprint === fingerprint(previous);
-      if (!valid) throw new Error("its integrity fingerprint does not match");
-    } catch (error) {
-      throw new Error(
-        `Refusing to replace unrecognized or modified provenance at ${absoluteManifest}: ${message(error)}. Pass { force: true } (CLI: --force) to take ownership of this artifact bundle.`,
-        { cause: error }
-      );
+function tiledWangId(rules, mask) {
+  const bitColor = (bit) => (mask & 1 << bit) !== 0 ? 1 : 2;
+  if (rules.ruleType === "corner") {
+    return [0, bitColor(2), 0, bitColor(0), 0, bitColor(1), 0, bitColor(3)];
+  }
+  return [bitColor(0), 0, bitColor(1), 0, bitColor(2), 0, bitColor(3), 0];
+}
+function buildGodot(generic, spec) {
+  const rules = generic.rules;
+  const lines = [
+    `[gd_resource type="TileSet" load_steps=3 format=3]`,
+    "",
+    `[ext_resource type="Texture2D" path=${JSON.stringify(`./${generic.image}`)} id="1_texture"]`,
+    "",
+    `[sub_resource type="TileSetAtlasSource" id="TileSetAtlasSource_pixelkiln"]`,
+    `texture = ExtResource("1_texture")`,
+    `texture_region_size = Vector2i(${generic.tile.width}, ${generic.tile.height})`
+  ];
+  for (const tile of generic.tiles) {
+    const x = tile.id % generic.sheet.columns;
+    const y = Math.floor(tile.id / generic.sheet.columns);
+    lines.push(`${x}:${y}/0 = 0`);
+    if (!rules || tile.bitmask === void 0 || rules.ruleType === "outline") continue;
+    const values = godotTerrainBits(rules, tile.bitmask);
+    lines.push(`${x}:${y}/0/terrain_set = 0`);
+    lines.push(`${x}:${y}/0/terrain = ${dominantTerrain(values)}`);
+    for (const [side, value] of Object.entries(values)) {
+      lines.push(`${x}:${y}/0/terrains_peering_bit/${side} = ${value}`);
     }
   }
-  if (!options.force) {
-    const root = path18.dirname(absoluteManifest);
-    const recorded = new Map(
-      previous?.outputs.map((output) => [path18.resolve(root, output.path), output.sha256]) ?? []
-    );
-    const conflicts = [];
-    for (const output of outputs) {
-      const destination = path18.resolve(output.path);
-      const current = await readOptional(destination);
-      if (!current || digest(current) === digest(output.data)) continue;
-      const expected = recorded.get(destination);
-      if (!expected || digest(current) !== expected) conflicts.push(destination);
-    }
-    if (conflicts.length) {
-      throw new Error(
-        `Refusing to overwrite modified or unowned artifact file(s):
-` + conflicts.map((file) => `  ${file}`).join("\n") + `
-Pass { force: true } (CLI: --force) to take ownership and replace the complete bundle.`
+  lines.push("", "[resource]");
+  lines.push(`tile_size = Vector2i(${generic.tile.width}, ${generic.tile.height})`);
+  const shape = godotTileShape(spec.tileType ?? "isometric");
+  if (shape !== 0) lines.push(`tile_shape = ${shape}`);
+  if (rules && rules.ruleType !== "outline") {
+    lines.push(`terrain_set_0/mode = ${rules.ruleType === "corner" ? 1 : 2}`);
+    for (const [index, name] of terrainNamesFor(rules).entries()) {
+      lines.push(`terrain_set_0/terrain_${index}/name = ${JSON.stringify(name)}`);
+      lines.push(
+        `terrain_set_0/terrain_${index}/color = ` + (index === 0 ? "Color(0.3529, 0.7098, 0.3216, 1)" : "Color(0.298, 0.4706, 0.6588, 1)")
       );
     }
   }
-  const { force: _force, ...bundleOptions } = options;
-  return writeArtifactBundle(
-    withArtifactManifest(absoluteManifest, outputs, provenance),
-    { ...bundleOptions, recoveryFile }
-  );
-}
-function isCode(error, code) {
-  return typeof error === "object" && error !== null && "code" in error && error.code === code;
+  lines.push(`sources/0 = SubResource("TileSetAtlasSource_pixelkiln")`, "");
+  return lines.join("\n");
 }
-async function remove2(file, errors) {
-  try {
-    await rm6(file, { force: true });
-  } catch (error) {
-    errors?.push(`could not remove ${file}: ${message(error)}`);
+function godotTerrainBits(rules, mask) {
+  const terrain = (bit) => (mask & 1 << bit) !== 0 ? 0 : 1;
+  if (rules.ruleType === "corner") {
+    return {
+      top_left_corner: terrain(3),
+      top_right_corner: terrain(2),
+      bottom_left_corner: terrain(1),
+      bottom_right_corner: terrain(0)
+    };
   }
+  return {
+    top_side: terrain(0),
+    right_side: terrain(1),
+    bottom_side: terrain(2),
+    left_side: terrain(3)
+  };
 }
-async function rollback(prepared) {
-  const errors = [];
-  for (const artifact of [...prepared].reverse()) {
-    if (artifact.promoted) await remove2(artifact.destination, errors);
+function dominantTerrain(values) {
+  const terrainZero = Object.values(values).filter((value) => value === 0).length;
+  return terrainZero * 2 >= Object.keys(values).length ? 0 : 1;
+}
+function godotTileShape(tileType) {
+  if (tileType === "isometric" || tileType === "oblique") return 1;
+  if (tileType === "hex" || tileType === "hex_pointy") return 3;
+  return 0;
+}
+function representativeTile(generic, terrainIndex) {
+  const rules = generic.rules;
+  const full = (1 << rules.arity) - 1;
+  const wanted = terrainIndex === 0 ? full : 0;
+  return generic.tiles.find((tile) => tile.bitmask === wanted)?.id ?? -1;
+}
+function terrainNamesFor(rules) {
+  return [rules.terrains[0] ?? "feature", rules.terrains[1] ?? "background"];
+}
+function assertUniformTiles(generic) {
+  const mismatched = generic.tiles.filter(
+    (tile) => tile.width !== generic.tile.width || tile.height !== generic.tile.height
+  );
+  if (mismatched.length) {
+    throw new Error(
+      `Engine tilesets require uniform ${generic.tile.width}x${generic.tile.height} cells; mismatched: ${mismatched.map((tile) => tile.role).join(", ")}. Use --format generic.`
+    );
   }
-  for (const artifact of [...prepared].reverse()) {
-    if (!artifact.backup || !artifact.backedUp) continue;
-    try {
-      await rename5(artifact.backup, artifact.destination);
-      artifact.backedUp = false;
-    } catch (error) {
-      errors.push(
-        `could not restore ${artifact.destination}; previous file remains at ${artifact.backup}: ${message(error)}`
-      );
-    }
+}
+function tileIndex(key) {
+  const match = key.match(/(?:^|[_-])(\d+)$/);
+  return match ? Number(match[1]) : null;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/pick/salvage-server.ts
+import { mkdir as mkdir6, writeFile as writeFile8, readFile as readFile15 } from "fs/promises";
+import path19 from "path";
+
+// src/pick/salvage-sheet.ts
+var escapeHtml2 = (s) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+function renderSalvageSheet(orphans, ctx) {
+  const safe = orphans.map((o) => ({ ...o, prompt: escapeHtml2(o.prompt) }));
+  const data = JSON.stringify(safe).replace(/<\//g, "<\\/");
+  const styleId = ctx ? escapeHtml2(ctx.styleId) : null;
+  const importDir = ctx ? escapeHtml2(ctx.importDir) : null;
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>pixelkiln salvage${styleId ? ` \u2014 ${styleId}` : ""}</title>
+<style>
+  :root { --bg:#0f1115; --panel:#171a21; --line:#262b36; --text:#e6e8ee; --dim:#8b93a7;
+          --import:#6ee7a8; --keep:#7cc4ff; --discard:#f87171; }
+  @media (prefers-color-scheme: light) {
+    :root { --bg:#f6f7f9; --panel:#fff; --line:#dfe3ea; --text:#1a1d23; --dim:#666e80;
+            --import:#0a8f52; --keep:#1a6fd4; --discard:#c0392b; }
   }
-  for (const artifact of prepared) {
-    if (artifact.stage) await remove2(artifact.stage, errors);
+  * { box-sizing:border-box; }
+  body { margin:0; background:var(--bg); color:var(--text);
+    font:14px/1.5 ui-sans-serif,-apple-system,"SF Pro Text",Inter,system-ui,sans-serif; }
+  header { position:sticky; top:0; z-index:10; background:var(--panel);
+    border-bottom:1px solid var(--line); padding:12px 20px; display:flex; gap:14px;
+    align-items:center; flex-wrap:wrap; }
+  h1 { font-size:15px; margin:0; font-weight:600; }
+  h1 .ctx { font-weight:500; color:var(--dim); }
+  h1 .dest { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:12.5px; }
+  .tally { color:var(--dim); font-variant-numeric:tabular-nums; }
+  .tally b { color:var(--text); font-weight:600; }
+  button { font:inherit; font-weight:550; border-radius:7px; padding:7px 14px;
+    border:1px solid var(--line); background:transparent; color:var(--text); cursor:pointer; }
+  button.primary { background:var(--import); border-color:var(--import); color:#08130d; }
+  button:disabled { opacity:.45; cursor:not-allowed; }
+  main { display:grid; grid-template-columns:repeat(auto-fill,minmax(190px,1fr)); gap:12px; padding:18px 20px 80px; }
+  .card { border:2px solid var(--line); border-radius:10px; background:var(--panel);
+    padding:10px; display:flex; flex-direction:column; gap:8px; }
+  .card.import { border-color:var(--import); }
+  .card.keep { border-color:var(--keep); }
+  .card.discard { border-color:var(--discard); opacity:.5; }
+  .thumb { height:120px; display:flex; align-items:center; justify-content:center;
+    border-radius:6px;
+    background-image:
+      linear-gradient(45deg,#0000 25%,#7f7f7f22 25%,#7f7f7f22 75%,#0000 75%),
+      linear-gradient(45deg,#0000 25%,#7f7f7f22 25%,#7f7f7f22 75%,#0000 75%);
+    background-size:12px 12px; background-position:0 0,6px 6px; }
+  .thumb img { image-rendering:pixelated; max-height:112px; max-width:100%; }
+  .meta { font-size:11px; color:var(--dim); font-variant-numeric:tabular-nums; }
+  .prompt { font-size:11.5px; color:var(--dim); max-height:3.2em; overflow:hidden; }
+  .acts { display:flex; gap:5px; }
+  .acts button { flex:1; padding:5px 0; font-size:11.5px; }
+  .acts button.on-import { background:var(--import); border-color:var(--import); color:#08130d; }
+  .acts button.on-keep { background:var(--keep); border-color:var(--keep); color:#04121f; }
+  .acts button.on-discard { background:var(--discard); border-color:var(--discard); color:#fff; }
+  footer { position:fixed; bottom:0; left:0; right:0; background:var(--panel);
+    border-top:1px solid var(--line); padding:10px 20px; font-size:12px; color:var(--dim); }
+  kbd { border:1px solid var(--line); border-bottom-width:2px; border-radius:4px;
+    padding:1px 5px; font-size:11px; font-family:ui-monospace,Menlo,monospace; }
+</style>
+</head>
+<body>
+<header>
+  <h1>pixelkiln salvage${styleId ? ` <span class="ctx">\u2014 ${styleId}<span class="dest"> \u2192 ${importDir}/_salvaged/</span></span>` : ""}</h1>
+  <span class="tally"><b id="ti">0</b> import \xB7 <b id="tk">0</b> keep \xB7 <b id="td">0</b> discard \xB7
+    <b id="tu">0</b> undecided</span>
+  <span style="flex:1"></span>
+  <button id="allDiscard">Discard all undecided</button>
+  <button id="allKeep">Keep all undecided</button>
+  <button id="submit" class="primary" disabled>Apply</button>
+</header>
+<main id="grid"></main>
+<footer>
+  <b>import</b> downloads it and adds it to your manifest \xB7 <b>keep</b> tags it and leaves it \xB7
+  <b>discard</b> only tags it \u2014 nothing is deleted here.
+  Hover a card and press <kbd>i</kbd> / <kbd>k</kbd> / <kbd>d</kbd>, or <kbd>u</kbd> to undo.
+</footer>
+<script>
+const ITEMS = ${data};
+const picks = new Map();
+const grid = document.getElementById('grid');
+let hovered = null;
+
+ITEMS.forEach((o, i) => {
+  const el = document.createElement('div');
+  el.className = 'card';
+  el.dataset.i = String(i);
+  el.innerHTML =
+    '<div class="thumb"><img src="' + o.previewUrl + '" loading="lazy"></div>' +
+    '<div class="meta">' + o.width + '\xD7' + o.height + ' \xB7 ' + o.createdAt.slice(0,10) + '</div>' +
+    '<div class="prompt">' + o.prompt + '</div>' +
+    '<div class="acts">' +
+      '<button data-a="import">import</button>' +
+      '<button data-a="keep">keep</button>' +
+      '<button data-a="discard">discard</button>' +
+    '</div>';
+  el.querySelectorAll('.acts button').forEach(b => {
+    b.onclick = () => choose(i, b.dataset.a);
+  });
+  el.onmouseenter = () => { hovered = i; };
+  grid.appendChild(el);
+});
+
+function choose(i, action) {
+  if (picks.get(i) === action) picks.delete(i); else picks.set(i, action);
+  const el = grid.children[i];
+  el.className = 'card' + (picks.has(i) ? ' ' + picks.get(i) : '');
+  el.querySelectorAll('.acts button').forEach(b => {
+    b.className = picks.get(i) === b.dataset.a ? 'on-' + b.dataset.a : '';
+  });
+  refresh();
+}
+
+function refresh() {
+  const c = { import: 0, keep: 0, discard: 0 };
+  for (const a of picks.values()) c[a]++;
+  ti.textContent = c.import; tk.textContent = c.keep; td.textContent = c.discard;
+  tu.textContent = ITEMS.length - picks.size;
+  document.getElementById('submit').disabled = picks.size === 0;
+}
+
+document.addEventListener('keydown', e => {
+  if (hovered === null) return;
+  const map = { i: 'import', k: 'keep', d: 'discard' };
+  if (map[e.key]) { choose(hovered, map[e.key]); e.preventDefault(); }
+  else if (e.key === 'u') { picks.delete(hovered); choose(hovered, '__none__'); }
+});
+
+document.getElementById('allKeep').onclick = () => {
+  ITEMS.forEach((_, i) => { if (!picks.has(i)) choose(i, 'keep'); });
+};
+document.getElementById('allDiscard').onclick = () => {
+  ITEMS.forEach((_, i) => { if (!picks.has(i)) choose(i, 'discard'); });
+};
+
+document.getElementById('submit').onclick = async () => {
+  const btn = document.getElementById('submit');
+  btn.disabled = true; btn.textContent = 'applying\u2026';
+  const decisions = [...picks.entries()].map(([i, action]) => ({ id: ITEMS[i].id, action }));
+  try {
+    const res = await fetch('/apply', {
+      method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ decisions }),
+    });
+    if (!res.ok) throw new Error(await res.text());
+    btn.textContent = 'done \u2014 close this tab';
+    document.body.style.opacity = '.6';
+  } catch (err) {
+    btn.textContent = 'failed: ' + err.message; btn.disabled = false;
   }
-  return errors;
+};
+refresh();
+</script>
+</body>
+</html>`;
 }
-async function writeArtifactBundle(files, options = {}) {
-  if (!files.length) throw new Error("An artifact bundle must contain at least one file.");
-  const normalized = files.map((file) => {
-    if (!file.path.trim()) throw new Error("Artifact paths cannot be empty.");
-    return { destination: path18.resolve(file.path), data: Buffer.from(file.data) };
+
+// src/pick/salvage-server.ts
+var PNG_SIGNATURE2 = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+async function runSalvage(provider, orphans, ctx, opts = {}) {
+  const log2 = opts.onProgress ?? (() => {
   });
-  const destinations = /* @__PURE__ */ new Set();
-  for (const artifact of normalized) {
-    if (destinations.has(artifact.destination)) {
-      throw new Error(`Artifact bundle contains duplicate destination: ${artifact.destination}`);
-    }
-    destinations.add(artifact.destination);
-  }
-  if (options.recoveryFile) {
-    await recoverArtifactTransaction(options.recoveryFile, destinations);
-  }
-  const changed = [];
-  const unchanged = [];
-  for (const artifact of normalized) {
-    try {
-      const current = await readFile14(artifact.destination);
-      if (current.equals(artifact.data)) {
-        unchanged.push(artifact.destination);
-      } else {
-        changed.push({ ...artifact, existed: true, backedUp: false, promoted: false });
+  const html = renderSalvageSheet(orphans, {
+    styleId: ctx.styleId,
+    importDir: path19.relative(process.cwd(), ctx.importDir) || "."
+  });
+  const byId = new Map(orphans.map((o) => [o.id, o]));
+  const existingTags = new Map(orphans.map((o) => [o.id, o.tags]));
+  return serveReviewPage({
+    html,
+    port: opts.port,
+    open: opts.open,
+    onProgress: log2,
+    onReady: (url) => {
+      log2(`
+  ${orphans.length} unclaimed object(s) to triage: ${url}`);
+      log2(`  (nothing is deleted here \u2014 discard only tags)
+`);
+    },
+    handleApply: async (body) => {
+      const { decisions } = body;
+      const result = { imported: 0, kept: 0, discarded: 0, failed: 0 };
+      const taken = new Set(Object.keys(ctx.manifest.assets));
+      const importedAssetIds = [];
+      for (const decision of decisions) {
+        const orphan = byId.get(decision.id);
+        if (!orphan) continue;
+        if (decision.action === "import") {
+          try {
+            const buf = await provider.download(orphan.previewUrl);
+            if (!buf.subarray(0, 8).equals(PNG_SIGNATURE2)) throw new Error("not a PNG");
+            decodePng(buf);
+            const assetId = idFromPrompt(orphan.prompt, taken);
+            const rel = path19.join("_salvaged", `${assetId}.png`);
+            const outFile = path19.resolve(ctx.importDir, rel);
+            await mkdir6(path19.dirname(outFile), { recursive: true });
+            await writeFile8(outFile, buf);
+            ctx.manifest.assets[assetId] = {
+              prompt: orphan.prompt,
+              promptByStyle: {},
+              category: "_salvaged",
+              file: rel,
+              tags: ["salvaged"],
+              styles: [ctx.styleId],
+              ...orphan.width === orphan.height ? { size: orphan.width } : { width: orphan.width, height: orphan.height }
+            };
+            upsert(ctx.lock, lockKey(ctx.styleId, assetId), {
+              styleId: ctx.styleId,
+              assetId,
+              specHash: SALVAGED_SPEC_HASH,
+              generator: orphan.width === orphan.height ? "1dir" : "map",
+              prompt: orphan.prompt,
+              width: orphan.width,
+              height: orphan.height,
+              jobId: orphan.id,
+              reviewObjectId: null,
+              objectId: orphan.id,
+              candidateIndex: null,
+              status: "downloaded",
+              error: null,
+              sourceUrl: orphan.previewUrl,
+              outputs: [{
+                path: portableOutputPath(outFile, path19.dirname(ctx.manifestPath)),
+                sha256: sha256(buf)
+              }],
+              submittedAt: orphan.createdAt,
+              downloadedAt: (/* @__PURE__ */ new Date()).toISOString(),
+              cost: 0,
+              // already paid for, in an earlier period
+              costUnit: "generations",
+              provider: provider.id
+            });
+            importedAssetIds.push(assetId);
+            result.imported++;
+            log2(`  imported ${assetId} \u2190 ${orphan.id}`);
+          } catch (err) {
+            result.failed++;
+            log2(`  import failed ${orphan.id}: ${err instanceof Error ? err.message : String(err)}`);
+          }
+        } else if (decision.action === "keep") {
+          result.kept++;
+        } else {
+          result.discarded++;
+        }
       }
-    } catch (error) {
-      if (!isCode(error, "ENOENT")) throw error;
-      changed.push({ ...artifact, existed: false, backedUp: false, promoted: false });
-    }
-  }
-  if (!changed.length) return { changed: [], unchanged };
-  const token = randomUUID3();
-  for (const [index, artifact] of changed.entries()) {
-    const basename = path18.basename(artifact.destination);
-    artifact.stage = path18.join(
-      path18.dirname(artifact.destination),
-      `.${basename}.pixelkiln-stage-${token}-${index}`
-    );
-    if (artifact.existed) {
-      artifact.backup = path18.join(
-        path18.dirname(artifact.destination),
-        `.${basename}.pixelkiln-backup-${token}-${index}`
-      );
-    }
-  }
-  const journal = options.recoveryFile ? path18.resolve(options.recoveryFile) : null;
-  if (journal) {
-    await mkdir6(path18.dirname(journal), { recursive: true });
-    const transaction = {
-      format: "pixelkiln-artifact-transaction",
-      version: 1,
-      pid: process.pid,
-      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-      entries: changed.map((artifact) => ({
-        destination: artifact.destination,
-        stage: artifact.stage,
-        ...artifact.backup ? { backup: artifact.backup } : {},
-        sha256: digest(artifact.data)
-      }))
-    };
-    try {
-      await writeFile8(journal, JSON.stringify(transaction, null, 2) + "\n", { flag: "wx" });
-      activeTransactions.add(journal);
-    } catch (error) {
-      throw new Error(
-        `Could not start durable artifact transaction at ${journal}: ${message(error)}`,
-        { cause: error }
-      );
-    }
-  }
-  try {
-    for (const [index, artifact] of changed.entries()) {
-      await mkdir6(path18.dirname(artifact.destination), { recursive: true });
-      await options.beforeStage?.(artifact.destination, index);
-      await writeFile8(artifact.stage, artifact.data, { flag: "wx" });
-    }
-  } catch (error) {
-    const cleanupErrors2 = await rollback(changed);
-    if (journal && !cleanupErrors2.length) await removeTransactionFiles(journal);
-    if (journal) activeTransactions.delete(journal);
-    const suffix = cleanupErrors2.length ? ` Cleanup also failed: ${cleanupErrors2.join("; ")}` : "";
-    throw new Error(`Could not stage artifact bundle: ${message(error)}.${suffix}`, { cause: error });
-  }
-  let durableCommit = false;
-  try {
-    for (const artifact of changed) {
-      if (!artifact.existed) continue;
-      await rename5(artifact.destination, artifact.backup);
-      artifact.backedUp = true;
-    }
-    for (const [index, artifact] of changed.entries()) {
-      await options.beforePromote?.(artifact.destination, index);
-      await rename5(artifact.stage, artifact.destination);
-      artifact.stage = void 0;
-      artifact.promoted = true;
-    }
-    if (journal) {
-      await writeFile8(transactionMarker(journal), `${token}
-`, { flag: "wx" });
-      durableCommit = true;
-      await options.afterCommit?.();
-    }
-  } catch (error) {
-    if (durableCommit) {
-      if (journal) activeTransactions.delete(journal);
-      throw new Error(
-        `Artifact bundle was committed, but final cleanup was interrupted: ${message(error)}. The next write will finish cleanup from ${journal}.`,
-        { cause: error }
-      );
-    }
-    const rollbackErrors = await rollback(changed);
-    if (journal && !rollbackErrors.length) await removeTransactionFiles(journal);
-    if (journal) activeTransactions.delete(journal);
-    const suffix = rollbackErrors.length ? ` Rollback needs attention: ${rollbackErrors.join("; ")}` : " Previous bundle restored.";
-    throw new Error(`Could not promote artifact bundle: ${message(error)}.${suffix}`, { cause: error });
-  }
-  const cleanupErrors = [];
-  for (const artifact of changed) {
-    if (artifact.backup) await remove2(artifact.backup, cleanupErrors);
-  }
-  if (cleanupErrors.length) {
-    if (journal) activeTransactions.delete(journal);
-    throw new Error(
-      `Artifact bundle was written, but old backup cleanup failed: ${cleanupErrors.join("; ")}`
-    );
-  }
-  if (journal) {
-    try {
-      await removeTransactionFiles(journal);
-    } finally {
-      activeTransactions.delete(journal);
+      await applyTags(provider, decisions, existingTags, { onProgress: log2 });
+      const raw = JSON.parse(await readFile15(ctx.manifestPath, "utf8"));
+      for (const id of importedAssetIds) raw.assets[id] = ctx.manifest.assets[id];
+      await writeFile8(ctx.manifestPath, JSON.stringify(raw, null, 2) + "\n");
+      await saveLock(ctx.lockPath, ctx.lock);
+      return result;
     }
-  }
-  return {
-    changed: changed.map((artifact) => artifact.destination),
-    unchanged
-  };
+  });
 }
 
 // src/cli.ts
 var log = (msg = "") => console.log(msg);
 async function provenanceFile(id, file) {
-  const absolute = path19.resolve(file);
+  const absolute = path20.resolve(file);
   return {
     id,
     path: absolute,
@@ -6006,7 +6409,13 @@ var VALUE_FLAGS = [
   "--sigma",
   "--workspace",
   "--provider",
-  "--account"
+  "--account",
+  "--palette",
+  "--fixer-python",
+  "--fixer-revision",
+  "--min-grid-confidence",
+  "--reviewer",
+  "--note"
 ];
 var BOOL_FLAGS = [
   "--force",
@@ -6045,6 +6454,7 @@ var COMMANDS = [
   "tag",
   "balance",
   "status",
+  "refine",
   "workspace",
   "help",
   "--help",
@@ -6053,6 +6463,7 @@ var COMMANDS = [
   "-v"
 ];
 var WORKSPACE_SUBCOMMANDS = ["add", "remove", "list", "status", "claims"];
+var REFINE_SUBCOMMANDS = ["run", "approve", "check"];
 function parseArgs(argv) {
   const [command = "help"] = argv;
   if (!COMMANDS.includes(command)) {
@@ -6081,6 +6492,14 @@ function parseArgs(argv) {
       }
       rest = rest.slice(1);
     }
+  } else if (command === "refine") {
+    subcommand = rest[0]?.startsWith("-") || rest[0] === void 0 ? "run" : rest[0];
+    if (!REFINE_SUBCOMMANDS.includes(subcommand)) {
+      throw new Error(
+        `Unknown refine subcommand "${subcommand}". Known: ${REFINE_SUBCOMMANDS.join(", ")}`
+      );
+    }
+    if (rest[0] === subcommand) rest = rest.slice(1);
   }
   for (let i = 0; i < rest.length; i++) {
     const token = rest[i];
@@ -6155,10 +6574,16 @@ function parseArgs(argv) {
     }
     return value;
   };
+  const rawGridConfidence = get("--min-grid-confidence");
+  if (rawGridConfidence !== void 0 && rawGridConfidence !== "low" && rawGridConfidence !== "medium" && rawGridConfidence !== "high") {
+    throw new Error(
+      `--min-grid-confidence must be low, medium, or high, got "${rawGridConfidence}"`
+    );
+  }
   return {
     command,
     manifest,
-    lock: get("--lock") ?? path19.join(path19.dirname(path19.resolve(manifest)), "pixelkiln.lock.json"),
+    lock: get("--lock") ?? path20.join(path20.dirname(path20.resolve(manifest)), "pixelkiln.lock.json"),
     explicitLock: get("--lock"),
     styles: list("--style"),
     assets: list("--only"),
@@ -6189,6 +6614,12 @@ function parseArgs(argv) {
     minTransparency: numberOption("--min-transparency", { min: 0, max: 1 }),
     maxColors: numberOption("--max-colors", { min: 1, integer: true }),
     sigma: numberOption("--sigma", { min: Number.EPSILON }),
+    palette: list("--palette"),
+    fixerPython: get("--fixer-python"),
+    fixerRevision: get("--fixer-revision"),
+    minGridConfidence: rawGridConfidence,
+    reviewer: get("--reviewer"),
+    note: get("--note"),
     subcommand,
     workspace: get("--workspace"),
     target,
@@ -6215,6 +6646,8 @@ Commands
   salvage   Triage account objects no lockfile claims. Recovers usable art.
             One session per matching style unless --style forces a single one.
   audit     Measure how consistently a style's assets hold together. Offline.
+  refine    Recover a native pixel grid, enforce a final palette, audit it,
+            and attach a verifiable human approval. run/approve/check. Offline.
   cache     Inspect local recovery/object-hash caches; optionally verify or prune.
   pack      Composite sprites into a PNG/atlas/provenance bundle. Offline.
   mount     Write a style's sprites into their declared cells of an existing
@@ -6240,6 +6673,12 @@ Options
   --min-transparency <0..1>  audit: minimum transparent canvas share
   --max-colors <n>    audit: maximum distinct opaque colors
   --sigma <n>         audit: relative outlier cutoff (default: 1.5)
+  --palette <hexes>   refine: final comma-separated #rrggbb colors (repeatable)
+  --fixer-python <path>  refine: Python with Pixel Art Fixer installed
+  --fixer-revision <sha>  refine: Pixel Art Fixer revision to record
+  --min-grid-confidence <level>  refine: high (default), medium, or low
+  --reviewer <name>   refine approve: human reviewer recorded in provenance
+  --note <text>       refine approve: optional review note
   --prune             cache: remove invalid/unreferenced local cache data
   --manifest <path>   Default: pixelkiln.manifest.json
   --lock <path>       Default: pixelkiln.lock.json beside the manifest
@@ -6269,6 +6708,9 @@ Examples
   pixelkiln pack --inputs sprites.json --out dist/sheet   # no manifest needed
   pixelkiln mount --style ground
   pixelkiln export --style ground --only terrain --format tiled
+  pixelkiln refine --from source.png --out final.png --palette "#101820,#f2aa4c"
+  pixelkiln refine approve --from final.pixelkiln.json --reviewer "Your Name"
+  pixelkiln refine check --from final.pixelkiln.json
   pixelkiln workspace add ../other-game/pixelkiln.manifest.json
   pixelkiln workspace status --json
   pixelkiln salvage --workspace pixelkiln.workspace.json
@@ -6316,7 +6758,7 @@ async function requireCompleteWorkspaceClaims(workspacePath) {
   if (!existsSync15(workspacePath)) {
     throw new Error(`Workspace catalog not found: ${workspacePath}`);
   }
-  const dir = path19.dirname(path19.resolve(workspacePath));
+  const dir = path20.dirname(path20.resolve(workspacePath));
   const ws = await loadWorkspace(workspacePath);
   const diagnostics = validateWorkspace(ws, dir);
   const errors = diagnostics.filter((d) => d.level === "error");
@@ -6337,13 +6779,79 @@ async function main() {
   }
   if (args.command === "--version" || args.command === "-v") {
     const pkg = JSON.parse(
-      await readFile15(new URL("../package.json", import.meta.url), "utf8")
+      await readFile16(new URL("../package.json", import.meta.url), "utf8")
     );
     log(`${pkg.name} ${pkg.version}`);
     return;
   }
+  if (args.command === "refine") {
+    if (!args.from) {
+      throw new Error(
+        args.subcommand === "run" ? "refine needs --from <source.png>." : `refine ${args.subcommand} needs --from <output.pixelkiln.json>.`
+      );
+    }
+    if (args.subcommand === "run") {
+      if (!args.out) throw new Error("refine needs --out <final.png>.");
+      if (!args.palette.length) {
+        throw new Error("refine needs an explicit final palette via --palette <#rrggbb,...>.");
+      }
+      const result2 = await refineAsset({
+        source: args.from,
+        output: args.out,
+        palette: args.palette,
+        fixerPython: args.fixerPython,
+        fixerRevision: args.fixerRevision,
+        minGridConfidence: args.minGridConfidence,
+        minTransparency: args.minTransparency,
+        force: args.force
+      });
+      if (args.json) {
+        log(JSON.stringify(result2, null, 2));
+      } else {
+        log(
+          `  recovered ${result2.detection.columns}x${result2.detection.rows} native grid (${result2.detection.confidence}: ${result2.detection.consensus})`
+        );
+        log(`  enforced ${result2.palette.length}-color palette without dithering`);
+        log(`  wrote ${path20.relative(process.cwd(), result2.output)}`);
+        log(`  quality record: ${path20.relative(process.cwd(), result2.record)}`);
+        log(`
+  Automated checks passed. Human 1\xD7 review is still required:`);
+        log(
+          `    pixelkiln refine approve --from ${path20.relative(process.cwd(), result2.record)} --reviewer "Your Name"`
+        );
+      }
+      return;
+    }
+    if (args.subcommand === "approve") {
+      if (!args.reviewer?.trim()) {
+        throw new Error("refine approve needs --reviewer <name>.");
+      }
+      log(`  Inspect the final PNG at 1\xD7 and integer zoom.`);
+      log(`  Confirm crisp edges, readable forms, palette separation, alpha, and seams.`);
+      if (!await confirm("  Record this asset as human-approved?", args.yes)) {
+        log("  approval not recorded");
+        return;
+      }
+      const result2 = await approveQualityRecord(args.from, {
+        reviewer: args.reviewer,
+        note: args.note
+      });
+      if (args.json) log(JSON.stringify(result2, null, 2));
+      else log(`  approved ${path20.relative(process.cwd(), result2.output)} by ${args.reviewer.trim()}`);
+      return;
+    }
+    const result = await checkQualityRecord(args.from);
+    if (args.json) {
+      log(JSON.stringify(result, null, 2));
+    } else {
+      log(`  ${result.safe ? "release-ready" : "not release-ready"}: ${path20.relative(process.cwd(), result.output || result.record)}`);
+      for (const reason of result.reasons) log(`    ${reason}`);
+    }
+    if (!result.safe) process.exitCode = 1;
+    return;
+  }
   if (args.command === "balance") {
-    loadEnvFiles(path19.dirname(path19.resolve(args.manifest)));
+    loadEnvFiles(path20.dirname(path20.resolve(args.manifest)));
     loadEnvFiles(process.cwd());
     const loaded2 = await loadManifest(args.manifest);
     const p = createProvider(loaded2.manifest.provider, "online");
@@ -6355,31 +6863,31 @@ async function main() {
   }
   if (args.command === "init") {
     if (!args.from) throw new Error("init needs --from <dir> pointing at your existing PNGs.");
-    const root = path19.resolve(args.from);
+    const root = path20.resolve(args.from);
     if (!existsSync15(root)) throw new Error(`No directory at ${root}`);
     const generator = args.generator ?? "map";
     if (generator !== "1dir" && generator !== "map") {
       throw new Error(`--generator must be "1dir" or "map", got "${args.generator}".`);
     }
-    const target = path19.resolve(args.out ?? "pixelkiln.manifest.json");
+    const target = path20.resolve(args.out ?? "pixelkiln.manifest.json");
     const { assets, skipped } = await scanAssets(root, { exclude: args.exclude });
     if (!assets.length) throw new Error(`No PNGs found under ${root}`);
     const manifest = buildManifest(
-      args.name ?? path19.basename(path19.dirname(target)),
+      args.name ?? path20.basename(path20.dirname(target)),
       args.styles[0] ?? "base",
       generator,
-      path19.relative(path19.dirname(target), root) || ".",
+      path20.relative(path20.dirname(target), root) || ".",
       assets
     );
     await writeManifestFile(target, manifest);
-    log(`  scanned ${assets.length} PNG(s) under ${path19.relative(process.cwd(), root)}`);
+    log(`  scanned ${assets.length} PNG(s) under ${path20.relative(process.cwd(), root)}`);
     if (skipped.length) log(`  skipped ${skipped.length} unreadable file(s)`);
-    log(`  wrote ${path19.relative(process.cwd(), target)}`);
+    log(`  wrote ${path20.relative(process.cwd(), target)}`);
     log(`
   Prompts are intentionally empty. To recover the real ones from your`);
     log(`  PixelLab account instead of inventing them:`);
     log(`
-    pixelkiln adopt --manifest ${path19.relative(process.cwd(), target)} --write-prompts
+    pixelkiln adopt --manifest ${path20.relative(process.cwd(), target)} --write-prompts
 `);
     return;
   }
@@ -6427,10 +6935,10 @@ async function main() {
     if (args.primaryOnly || args.outputRoles.length) {
       throw new Error("--primary-only and --output-role require manifest-driven pack");
     }
-    const raw = JSON.parse(await readFile15(path19.resolve(args.inputs), "utf8"));
+    const raw = JSON.parse(await readFile16(path20.resolve(args.inputs), "utf8"));
     const inputs = resolvePackInputs(raw, args.inputs);
     const { png, atlas, skipped, sources } = packSprites(inputs, { columns: args.columns });
-    const base = path19.resolve(args.out.replace(/\.png$/, ""));
+    const base = path20.resolve(args.out.replace(/\.png$/, ""));
     const outputs = [
       { path: `${base}.png`, data: png },
       { path: `${base}.json`, data: JSON.stringify(atlas, null, 2) + "\n" }
@@ -6443,17 +6951,17 @@ async function main() {
     log(
       `  ${atlas.frames.length} sprite(s), ${atlas.sheet.width}x${atlas.sheet.height} in ${atlas.columns} column(s) \u2014 ${(png.length / 1024).toFixed(1)} KB`
     );
-    log(`    ${path19.relative(process.cwd(), base)}.png + .json + .pixelkiln.json`);
+    log(`    ${path20.relative(process.cwd(), base)}.png + .json + .pixelkiln.json`);
     for (const s of skipped) log(`    skipped ${s.id}: ${s.reason}`);
     return;
   }
   if (args.command === "workspace") {
-    const workspacePath = path19.resolve(args.workspace ?? "pixelkiln.workspace.json");
-    const dir = path19.dirname(workspacePath);
+    const workspacePath = path20.resolve(args.workspace ?? "pixelkiln.workspace.json");
+    const dir = path20.dirname(workspacePath);
     if (args.subcommand === "add") {
-      const manifestPath = path19.resolve(args.target);
+      const manifestPath = path20.resolve(args.target);
       const loadedTarget = await loadManifest(manifestPath);
-      const lockPath = args.explicitLock ? path19.resolve(args.explicitLock) : path19.join(path19.dirname(manifestPath), "pixelkiln.lock.json");
+      const lockPath = args.explicitLock ? path20.resolve(args.explicitLock) : path20.join(path20.dirname(manifestPath), "pixelkiln.lock.json");
       const ws = await loadWorkspace(workspacePath);
       const id = args.name ?? loadedTarget.manifest.name;
       if (ws.projects.some((p) => p.id === id)) {
@@ -6473,7 +6981,7 @@ async function main() {
         ...args.account ? { account: args.account } : {}
       };
       await saveWorkspace(workspacePath, { version: 1, projects: [...ws.projects, project] });
-      log(`  registered "${id}" in ${path19.relative(process.cwd(), workspacePath)}`);
+      log(`  registered "${id}" in ${path20.relative(process.cwd(), workspacePath)}`);
       log(`    manifest: ${project.manifest}`);
       log(`    lock:     ${project.lock}`);
       if (!existsSync15(lockPath)) {
@@ -6485,7 +6993,7 @@ async function main() {
     }
     if (args.subcommand === "remove") {
       const ws = await loadWorkspace(workspacePath);
-      const resolvedTarget = path19.resolve(args.target);
+      const resolvedTarget = path20.resolve(args.target);
       const match = ws.projects.find(
         (p) => p.id === args.target || resolveProject(dir, p).manifestPath === resolvedTarget
       );
@@ -6496,7 +7004,7 @@ async function main() {
         version: 1,
         projects: ws.projects.filter((p) => p !== match)
       });
-      log(`  removed "${match.id}" from ${path19.relative(process.cwd(), workspacePath)}`);
+      log(`  removed "${match.id}" from ${path20.relative(process.cwd(), workspacePath)}`);
       return;
     }
     if (args.subcommand === "list") {
@@ -6508,9 +7016,9 @@ async function main() {
       if (args.json) {
         log(JSON.stringify({ version: 1, workspace: workspacePath, projects: ws.projects, diagnostics }, null, 2));
       } else if (!ws.projects.length) {
-        log(`  no projects registered in ${path19.relative(process.cwd(), workspacePath)}`);
+        log(`  no projects registered in ${path20.relative(process.cwd(), workspacePath)}`);
       } else {
-        log(`  ${ws.projects.length} project(s) in ${path19.relative(process.cwd(), workspacePath)}:`);
+        log(`  ${ws.projects.length} project(s) in ${path20.relative(process.cwd(), workspacePath)}:`);
         for (const p of ws.projects) {
           log(`    ${p.id.padEnd(24)} ${p.manifest.padEnd(40)} (${p.provider}${p.account ? `, ${p.account}` : ""})`);
         }
@@ -6528,7 +7036,7 @@ async function main() {
       if (args.json) {
         log(JSON.stringify({ ...report, workspace: workspacePath }, null, 2));
       } else {
-        log(`  workspace: ${path19.relative(process.cwd(), workspacePath)}`);
+        log(`  workspace: ${path20.relative(process.cwd(), workspacePath)}`);
         for (const p of report.projects) {
           if (p.error) {
             log(`
@@ -6572,14 +7080,14 @@ async function main() {
       return;
     }
   }
-  if (!existsSync15(path19.resolve(args.manifest))) {
+  if (!existsSync15(path20.resolve(args.manifest))) {
     throw new Error(
-      `No manifest at ${path19.resolve(args.manifest)}. Pass --manifest, or run \`pixelkiln init --from <dir>\`.`
+      `No manifest at ${path20.resolve(args.manifest)}. Pass --manifest, or run \`pixelkiln init --from <dir>\`.`
     );
   }
-  const manifestDir = path19.dirname(path19.resolve(args.manifest));
+  const manifestDir = path20.dirname(path20.resolve(args.manifest));
   const envFiles = [...loadEnvFiles(manifestDir)];
-  if (path19.resolve(process.cwd()) !== manifestDir) envFiles.push(...loadEnvFiles(process.cwd()));
+  if (path20.resolve(process.cwd()) !== manifestDir) envFiles.push(...loadEnvFiles(process.cwd()));
   const loaded = await loadManifest(args.manifest);
   const estimator = createProvider(loaded.manifest.provider, "offline");
   const specs = await resolveSpecs(loaded, {
@@ -6714,7 +7222,7 @@ async function main() {
     if (args.primaryOnly && args.outputRoles.length) {
       throw new Error("pack accepts either --primary-only or --output-role, not both");
     }
-    const manifestDir2 = path19.dirname(path19.resolve(args.manifest));
+    const manifestDir2 = path20.dirname(path20.resolve(args.manifest));
     const styleIds = args.styles.length ? args.styles : Object.keys(loaded.manifest.styles);
     for (const styleId of styleIds) {
       const { png, atlas, skipped, sources } = packStyle(lock, styleId, manifestDir2, {
@@ -6723,7 +7231,7 @@ async function main() {
         primaryOnly: args.primaryOnly
       });
       const style = loaded.manifest.styles[styleId];
-      const base = args.out ? path19.resolve(args.out.replace(/\.png$/, "")) : path19.resolve(manifestDir2, style.outDir, `${styleId}-sheet`);
+      const base = args.out ? path20.resolve(args.out.replace(/\.png$/, "")) : path20.resolve(manifestDir2, style.outDir, `${styleId}-sheet`);
       const outputs = [
         { path: `${base}.png`, data: png },
         { path: `${base}.json`, data: JSON.stringify(atlas, null, 2) + "\n" }
@@ -6746,13 +7254,13 @@ async function main() {
       log(
         `  ${styleId} \u2014 ${atlas.frames.length} sprite(s), ${atlas.sheet.width}x${atlas.sheet.height} in ${atlas.columns} column(s)`
       );
-      log(`    ${path19.relative(process.cwd(), base)}.png + .json + .pixelkiln.json`);
+      log(`    ${path20.relative(process.cwd(), base)}.png + .json + .pixelkiln.json`);
       for (const s of skipped) log(`    skipped ${s.id}: ${s.reason}`);
     }
     return;
   }
   if (args.command === "mount") {
-    const manifestDir2 = path19.dirname(path19.resolve(args.manifest));
+    const manifestDir2 = path20.dirname(path20.resolve(args.manifest));
     const styleIds = args.styles.length ? args.styles : Object.keys(loaded.manifest.styles);
     for (const styleId of styleIds) {
       const style = loaded.manifest.styles[styleId];
@@ -6782,7 +7290,7 @@ async function main() {
         sources,
         outputRoles
       );
-      const out = path19.resolve(manifestDir2, style.mount.out);
+      const out = path20.resolve(manifestDir2, style.mount.out);
       const metadata = out.replace(/\.png$/, "") + ".json";
       const companion = out.replace(/\.png$/, "") + ".pixelkiln.json";
       const outputs = [
@@ -6795,7 +7303,7 @@ async function main() {
           await provenanceFile("$manifest", args.manifest),
           await provenanceFile("$lock", args.lock),
           ...artifactSources.filter(
-            (source) => source.id !== "$base" || path19.resolve(source.path) !== out
+            (source) => source.id !== "$base" || path20.resolve(source.path) !== out
           )
         ],
         options: {
@@ -6808,7 +7316,7 @@ async function main() {
       log(
         `  ${styleId} \u2014 ${atlas.frames.length} cell(s) into ${atlas.sheet.width}x${atlas.sheet.height}` + (overBase ? ` over ${style.mount.base}` : " (new sheet)")
       );
-      log(`    ${path19.relative(process.cwd(), out)} + atlas/provenance JSON`);
+      log(`    ${path20.relative(process.cwd(), out)} + atlas/provenance JSON`);
       for (const s of skipped) log(`    skipped ${s.id}: ${s.reason}`);
     }
     return;
@@ -6864,7 +7372,7 @@ async function main() {
   }
   if (args.command === "export") {
     const format = args.format ?? "generic";
-    const manifestDir2 = path19.dirname(path19.resolve(args.manifest));
+    const manifestDir2 = path20.dirname(path20.resolve(args.manifest));
     const selected = specs.filter((spec) => {
       if (spec.generator !== "tiles") return false;
       if (args.styles.length && !args.styles.includes(spec.styleId)) return false;
@@ -6880,12 +7388,12 @@ async function main() {
     for (const spec of selected) {
       const entry = lock.entries[lockKey(spec.styleId, spec.assetId)];
       const style = loaded.manifest.styles[spec.styleId];
-      const defaultBase = path19.resolve(manifestDir2, style.outDir, `${spec.assetId}-tileset`);
-      const base = args.out ? path19.resolve(args.out.replace(/\.(?:png|json|tsj|tres)$/i, "")) : defaultBase;
+      const defaultBase = path20.resolve(manifestDir2, style.outDir, `${spec.assetId}-tileset`);
+      const base = args.out ? path20.resolve(args.out.replace(/\.(?:png|json|tsj|tres)$/i, "")) : defaultBase;
       const result = exportTileset(entry, spec, {
         format,
         manifestDir: manifestDir2,
-        imageName: path19.basename(`${base}.png`),
+        imageName: path20.basename(`${base}.png`),
         columns: args.columns
       });
       const outputs = [
@@ -6903,7 +7411,7 @@ async function main() {
           asset: spec.assetId,
           columns: args.columns ?? null,
           format,
-          image: path19.basename(`${base}.png`),
+          image: path20.basename(`${base}.png`),
           providerRules: result.generic.providerRules,
           style: spec.styleId,
           tileType: spec.tileType ?? null
@@ -6913,7 +7421,7 @@ async function main() {
         `  ${spec.styleId}/${spec.assetId} \u2014 ${result.generic.tiles.length} tile(s), ${result.generic.sheet.width}x${result.generic.sheet.height} (${format})`
       );
       log(
-        `    ${path19.relative(process.cwd(), base)}.png + ${path19.basename(base)}${result.extension} + .pixelkiln.json`
+        `    ${path20.relative(process.cwd(), base)}.png + ${path20.basename(base)}${result.extension} + .pixelkiln.json`
       );
     }
     return;
@@ -6953,10 +7461,10 @@ async function main() {
   tagged ${n} object(s) upstream`);
     }
     if (args.writePrompts) {
-      const { filled, stillEmpty } = await writePromptsBack(path19.resolve(args.manifest), lock, {
+      const { filled, stillEmpty } = await writePromptsBack(path20.resolve(args.manifest), lock, {
         onProgress: log
       });
-      log(`  recovered ${filled} prompt(s) into ${path19.relative(process.cwd(), args.manifest)}`);
+      log(`  recovered ${filled} prompt(s) into ${path20.relative(process.cwd(), args.manifest)}`);
       const reloaded = await loadManifest(args.manifest);
       const rebased = await resolveSpecs(reloaded, {
         styles: args.styles,
@@ -6985,12 +7493,12 @@ async function main() {
   if (args.command === "salvage") {
     const jsonMode = args.dryRun && args.json;
     const diag = jsonMode ? (msg = "") => console.error(msg) : log;
-    const ownLock = path19.resolve(args.lock);
+    const ownLock = path20.resolve(args.lock);
     let workspaceProjects = [];
     let workspaceDir = "";
     if (args.workspace) {
-      const workspacePath = path19.resolve(args.workspace);
-      workspaceDir = path19.dirname(workspacePath);
+      const workspacePath = path20.resolve(args.workspace);
+      workspaceDir = path20.dirname(workspacePath);
       const complete = await requireCompleteWorkspaceClaims(workspacePath);
       workspaceProjects = complete.ws.projects;
       for (const d of complete.diagnostics) diag(`  WARN  ${d.id}: ${d.message}`);
@@ -7000,11 +7508,11 @@ async function main() {
       .../* @__PURE__ */ new Set([
         ...workspaceLockPaths,
         ...existsSync15(ownLock) ? [ownLock] : [],
-        ...args.claims.map((c) => path19.resolve(c))
+        ...args.claims.map((c) => path20.resolve(c))
       ])
     ];
     diag(`  claim set (${lockPaths.length} lockfile(s)):`);
-    for (const p of lockPaths) diag(`    ${path19.relative(process.cwd(), p)}`);
+    for (const p of lockPaths) diag(`    ${path20.relative(process.cwd(), p)}`);
     if (!args.claims.length && !args.workspace) {
       diag(
         `
@@ -7012,7 +7520,7 @@ async function main() {
   pass every other project's lockfile via --claims a.json,b.json, or
   register every project in a workspace catalog and pass --workspace.`
       );
-    } else if (args.workspace && !workspaceProjects.some((p) => resolveProject(workspaceDir, p).manifestPath === path19.resolve(args.manifest))) {
+    } else if (args.workspace && !workspaceProjects.some((p) => resolveProject(workspaceDir, p).manifestPath === path20.resolve(args.manifest))) {
       diag(
         `
   This project's manifest is not registered in the workspace catalog. Its own
@@ -7096,7 +7604,7 @@ async function main() {
           manifestPath: loaded.path,
           manifest: loaded.manifest,
           styleId,
-          importDir: path19.resolve(loaded.root, style.outDir),
+          importDir: path20.resolve(loaded.root, style.outDir),
           lock,
           lockPath: args.lock
         },