@mcptoolshop/style-dataset-lab 3.3.0 → 3.5.0

package/lib/asset-ingest.js

@@ -0,0 +1,575 @@
+/**
+ * Asset ingest engine — register a validated asset export into a project.
+ *
+ * Sits beside lib/ingest.js (bare external images) as the manifest-driven,
+ * gated sibling: `sdlab asset ingest` consumes an export directory whose
+ * asset-source.json has passed the full contract (lib/asset-source.js), runs
+ * the ported receiving-dock gates per render, and registers records under
+ * the existing machinery.
+ *
+ * Non-negotiables inherited from lib/ingest.js, held here too:
+ *   - NEVER invents a judgment, a score, or a caption. Records land with
+ *     judgment: null, canon: null via the same buildBaseRecord. Caption
+ *     MATERIAL (subject, facing, trigger, domain tag) rides in provenance —
+ *     assembling a caption is a package-build decision, not an ingest fact.
+ *   - provenance.source is 'asset' — a third honest source alongside
+ *     'generated' and 'external', carrying the acceptance block verbatim.
+ *   - --dry-run performs zero filesystem writes.
+ *   - idempotent + crash-safe: records are skipped when already present
+ *     (same asset, same manifest hash), both images and records land via
+ *     temp-then-rename, and the receipt is written LAST — its presence
+ *     means the ingest completed. A crash mid-ingest leaves records that a
+ *     re-run skips, then finishes, then writes the receipt.
+ *   - ANDON: a render failing the asset's own declared palette gate is
+ *     REJECTED (reported, never registered). All renders failing fails the
+ *     ingest. A record-id collision with a different asset refuses loudly.
+ *
+ * Compensator (NAMED_COMPENSATORS): the receipt lists every path this
+ * ingest created. Undo = delete those paths (or `git clean` / `git revert`
+ * once committed). Owner: user.
+ */
+
+import { readFile, writeFile, mkdir, rename, unlink } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { basename, extname, join, sep } from 'node:path';
+import { buildBaseRecord, buildIdentityRecord } from './records.js';
+import { inputError } from './errors.js';
+import { decodePng } from './png-meta.js';
+import { paletteGate, classShares } from './asset-masks.js';
+import {
+  ASSET_MANIFEST_FILENAME,
+  PIXEL_ENCODINGS,
+  validateAssetSource,
+  facingFromCamera,
+} from './asset-source.js';
+
+export const ASSET_INGEST_TOOL_ID = 'sdlab-asset-ingest-v1';
+// 1.1.0: adds `notices` (provenance gaps reported, not gated) and the
+// `tone_operands` file role. Additive — a 1.0.0 receipt reads fine.
+export const ASSET_RECEIPT_SCHEMA_VERSION = '1.1.0';
+export const RECEIPT_FILENAME = 'ingest-receipt.json';
+
+const DEFAULT_DOMAIN_TAG = '3d asset'; // MVDream's verbatim render-caption tag (design doc Q4)
+
+function toPortablePath(p) {
+  return p.split(sep).join('/');
+}
+
+function sha256(buf) {
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+// Same temp-then-rename shape as lib/ingest.js / lib/runtime-runs.js /
+// lib/batch-runs.js — each module keeps its own copy by established
+// convention in this codebase.
+async function atomicWriteFile(targetPath, body) {
+  const tmpPath = `${targetPath}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    await writeFile(tmpPath, body);
+    await rename(tmpPath, targetPath);
+  } catch (err) {
+    try { await unlink(tmpPath); } catch { /* best-effort cleanup */ }
+    throw err;
+  }
+}
+
+/**
+ * Read + hash + atomically materialize a source file into the project.
+ * Returns the sha256 either way; writes only when `write` is true.
+ */
+async function hashAndMaybeCopy(absSrc, absDest, write) {
+  const buf = await readFile(absSrc);
+  const hash = sha256(buf);
+  if (write) await atomicWriteFile(absDest, buf);
+  return { hash, bytes: buf.length };
+}
+
+/**
+ * Ingest a validated asset export into a project.
+ *
+ * @param {string} projectRoot — absolute project root (resolved by caller)
+ * @param {string} sourceDir — absolute export directory (must contain asset-source.json)
+ * @param {Object} [options]
+ * @param {boolean} [options.dryRun]
+ * @returns {Promise<Object>} report — see the shape at the bottom
+ */
+export async function ingestAssetSource(projectRoot, sourceDir, options = {}) {
+  const dryRun = Boolean(options.dryRun);
+
+  const manifestPath = join(sourceDir, ASSET_MANIFEST_FILENAME);
+  const { manifest, resolved, manifestRaw } = await validateAssetSource(manifestPath);
+
+  const assetId = manifest.asset.id;
+  const manifestSha = sha256(manifestRaw);
+  const assetDir = join(projectRoot, 'assets', assetId);
+  const receiptPath = join(assetDir, RECEIPT_FILENAME);
+  const recordsDir = join(projectRoot, 'records');
+  const candidatesDir = join(projectRoot, 'outputs', 'candidates');
+
+  // ── Idempotency at the asset level ────────────────────────────────
+  if (existsSync(receiptPath)) {
+    let receipt;
+    try {
+      receipt = JSON.parse(await readFile(receiptPath, 'utf-8'));
+    } catch (err) {
+      throw inputError(
+        'ASSET_RECEIPT_CORRUPT',
+        `${receiptPath} exists but is unreadable: ${err.message}`,
+        'Inspect the assets directory; remove it explicitly (it is listed as the compensator) to re-ingest.'
+      );
+    }
+    if (receipt.manifest_sha256 === manifestSha) {
+      // Notices replay from the stored receipt rather than being recomputed —
+      // a re-run must report the same provenance gaps the original ingest did,
+      // and a receipt written before 1.2.0 honestly has none to report.
+      return { assetId, alreadyIngested: true, receiptPath: toPortablePath(join('assets', assetId, RECEIPT_FILENAME)), created: [], skipped: (receipt.records_created || []).slice(), rejected: receipt.rejected_renders || [], notices: receipt.notices || [], dryRun };
+    }
+    throw inputError(
+      'ASSET_ALREADY_INGESTED',
+      `Asset "${assetId}" was already ingested from a DIFFERENT manifest (receipt sha ${receipt.manifest_sha256?.slice(0, 12)}…, incoming ${manifestSha.slice(0, 12)}…).`,
+      `A changed export is a new truth, not an overwrite. Compensator: delete projects/<project>/assets/${assetId}/ and the records it lists, then re-run. Nothing was written.`
+    );
+  }
+
+  // ── Receiving-dock gates + measurements (pure reads) ──────────────
+  const channelDecls = new Map((manifest.channels || []).map((c) => [c.id, c]));
+  const admitted = [];
+  const rejected = [];
+
+  for (const [renderId, entry] of resolved.renders) {
+    const renderBuf = await readFile(entry.abs);
+    const renderImg = decodePng(renderBuf, entry.relPath);
+    const silhouetteImg = decodePng(await readFile(entry.silhouette.abs), entry.silhouette.relPath);
+
+    const gate = paletteGate(renderImg, silhouetteImg, manifest.palette, entry.relPath);
+
+    // Class shares are a PIXEL measurement. Since schema 1.1.0 an instance
+    // may be an npy array or a json sidecar; those carry their class facts
+    // asset-side (facet's admission sidecars already count them) and sdlab
+    // does not recompute what it would have to interpret to recompute.
+    const shares = {};
+    for (const [cid, inst] of entry.instances) {
+      const decl = channelDecls.get(cid);
+      if (!decl?.categorical || !PIXEL_ENCODINGS.has(decl.encoding)) continue;
+      const instImg = decodePng(await readFile(inst.abs), inst.relPath);
+      shares[cid] = classShares(instImg, silhouetteImg, decl, inst.relPath);
+    }
+
+    if (!gate.pass) {
+      rejected.push({ render_id: renderId, reason: 'palette-gate', gate });
+      continue;
+    }
+    admitted.push({
+      renderId,
+      entry,
+      renderBuf,
+      renderSha: sha256(renderBuf),
+      width: renderImg.width,
+      height: renderImg.height,
+      gate,
+      shares,
+    });
+  }
+
+  if (admitted.length === 0) {
+    throw inputError(
+      'ASSET_ALL_RENDERS_REJECTED',
+      `Every render of "${assetId}" failed the asset's own declared palette gate — nothing to register.`,
+      `Rejected: ${rejected.map((r) => `${r.render_id} (blob ${r.gate.largest_blob_px}px)`).join(', ')}. ` +
+      'The gate bands and thresholds come from the manifest itself; if they are wrong, that is an export-side fix.'
+    );
+  }
+
+  // ── Plan record ids; refuse collisions with foreign records ───────
+  const captionDefaults = manifest.captions || {};
+  const subjectName = manifest.identity?.subject_name ?? null;
+
+  // ── Asset-level style + tone provenance (schema 1.2.0) ─────────────
+  // Resolved ONCE here and copied onto every record, so a consumer never has
+  // to re-open the manifest (or re-derive a default) to know what register a
+  // record was painted in or whether a tone map sits under its colours.
+  const style = manifest.asset.style ?? null;
+  const styleRecord = style
+    ? {
+        register_terms: [...style.register.terms],
+        register_ruling: style.register.ruling ?? null,
+        register_record: style.register.record ?? null,
+        lora: style.lora.declared === 'none'
+          ? { declared: 'none', card: null, weight: 0 }
+          : { declared: 'card', card: style.lora.card, weight: style.lora.weight ?? null },
+      }
+    : null;
+
+  const toneDecl = manifest.asset.tone_transform ?? null;
+
+  // schema 1.3.0 — how these renders came to exist. `generated === false`
+  // means an absent generation block is CORRECT by declaration rather than a
+  // gap, so the notice below must not report one.
+  const derivationDecl = manifest.asset.render_derivation ?? null;
+  const derivationRecord = derivationDecl
+    ? { kind: derivationDecl.kind, generated: derivationDecl.generated, record: derivationDecl.record ?? null }
+    : null;
+  const plans = [];
+  const skipped = [];
+  for (const a of admitted) {
+    const recordId = `${assetId}__${a.renderId}`;
+    const recordPath = join(recordsDir, `${recordId}.json`);
+    if (existsSync(recordPath)) {
+      let existing = null;
+      try {
+        existing = JSON.parse(await readFile(recordPath, 'utf-8'));
+      } catch { /* unreadable => treated as foreign below */ }
+      const sameIngest = existing?.provenance?.source === 'asset'
+        && existing?.provenance?.asset_id === assetId
+        && existing?.provenance?.manifest_sha256 === manifestSha;
+      if (sameIngest) {
+        skipped.push(recordId); // crash-resume: record done, receipt wasn't
+        continue;
+      }
+      throw inputError(
+        'ASSET_RECORD_COLLISION',
+        `Record id "${recordId}" already exists and does not belong to this ingest (source: ${existing?.provenance?.source ?? 'unreadable'}).`,
+        'Rename the asset id or resolve the existing record explicitly. Nothing was written.'
+      );
+    }
+    plans.push({ ...a, recordId, recordPath });
+  }
+
+  // ── Provenance notices (schema 1.2.0) ──────────────────────────────
+  // NOT gates. Every one of these describes a manifest that is contract-legal
+  // and ingests fine — a 1.0.0 export declares none of it, and E11 Ruling 2
+  // named those exports as the training input, so refusing them is not on the
+  // table. What IS on the table is refusing to be quiet: an absent register or
+  // an unknown seed is a fact about the training data, and a fact nobody is
+  // told is one nobody can act on. These ride in the receipt and print at the
+  // CLI.
+  //
+  // Two kinds, and the difference matters to anything that reads them:
+  //   'gap'  — the manifest did NOT declare something a curator needs. Closing
+  //            it is export-side work.
+  //   'info' — the manifest DID declare something that changes how these
+  //            records should be read. Nothing to fix; something to know.
+  const notices = [];
+  if (!styleRecord) {
+    notices.push({
+      code: 'ASSET_STYLE_UNDECLARED',
+      kind: 'gap',
+      message: 'No asset.style — the register this subject was painted in is UNKNOWN to the lane. ' +
+        'Per facet E12 Ruling 10b the style register is subject data; a training pool mixing declared and undeclared registers cannot be filtered by it. ' +
+        'Records carry style: null, which is distinguishable from a ruled no-LoRA register.',
+    });
+  }
+  if (toneDecl) {
+    const optedOut = (manifest.renders || []).filter((r) => r.tone_transform === false).length;
+    notices.push({
+      code: 'ASSET_TONE_TRANSFORM_DECLARED',
+      kind: 'info',
+      message: `Renders derive from sources carrying a declared "${toneDecl.kind}" tone transform toward ${toneDecl.reference}` +
+        (optedOut > 0 ? ` (${optedOut} render(s) opted out)` : '') +
+        '. sdlab records the declaration and hashes the operands; it does NOT verify the transform was applied or is reversible. ' +
+        'Colour measurements on these records — palette gate, class shares, ΔE — sit downstream of it.',
+    });
+  }
+  // The generation notice is suppressed — not weakened — when the manifest
+  // DECLARES its renders are deterministic derivations. An emit render of an
+  // already-accepted asset has no seed; reporting its absence as a gap would
+  // tell an operator to go fix an export that is correct by ruling (facet E11
+  // Ruling 2), and a notice channel that cries wolf on correct data stops
+  // being read. An UNDECLARED manifest still gets the gap: saying nothing is
+  // not the same as saying "these are derivations."
+  if (derivationDecl?.generated === false) {
+    notices.push({
+      code: 'ASSET_RENDERS_ARE_DERIVATIONS',
+      kind: 'info',
+      message: `Renders are declared "${derivationDecl.kind}" derivations of the accepted asset, not generated images — so they carry no seed or generation frame, correctly. ` +
+        'Records carry generation: null by declaration rather than by omission. ' +
+        'The generating provenance of any twins these were projected from belongs to those twins, not to these records.',
+    });
+  } else {
+    const noGeneration = admitted.filter((a) => !a.entry.render.generation).length;
+    if (noGeneration > 0) {
+      notices.push({
+        code: 'ASSET_GENERATION_PROVENANCE_ABSENT',
+        kind: 'gap',
+        message: `${noGeneration} of ${admitted.length} admitted render(s) declare no generation block — frame and seed are unknown for them. ` +
+          'Both are measured curation axes (E12 Ruling 24b: crop-framed generation drifts register, 3 instances; Ruling 20a: term binding is seed-dependent). ' +
+          'Records carry generation: null. ' +
+          'If these renders are deterministic derivations rather than generated images, declare asset.render_derivation with generated: false and this stops being a gap.',
+      });
+    }
+  }
+  if (!subjectName) {
+    notices.push({
+      code: 'ASSET_SUBJECT_NAME_ABSENT',
+      kind: 'gap',
+      message: 'No identity.subject_name — lib/split.js will fall back to id-stem guessing for these records. ' +
+        'Two ingests of ONE subject then read as two families, and the same subject can land in both train and test. ' +
+        'Declare it before any split is cut.',
+    });
+  }
+
+  const wouldWrite = [];
+  const written = [];
+  const filesLedger = [];
+  const note = (role, sourceRel, destRel, materialized, hash, bytes) => {
+    filesLedger.push({
+      role,
+      source: toPortablePath(sourceRel),
+      dest: destRel ? toPortablePath(destRel) : null,
+      materialized,
+      sha256: hash ?? null,
+      bytes: bytes ?? null,
+    });
+  };
+
+  // ── Dry run: full plan, zero writes ────────────────────────────────
+  if (dryRun) {
+    for (const p of plans) {
+      wouldWrite.push(toPortablePath(join('records', `${p.recordId}.json`)));
+      wouldWrite.push(toPortablePath(join('outputs', 'candidates', `${p.recordId}.png`)));
+    }
+    wouldWrite.push(toPortablePath(join('assets', assetId, ASSET_MANIFEST_FILENAME)));
+    wouldWrite.push(toPortablePath(join('assets', assetId, RECEIPT_FILENAME)));
+    return {
+      assetId,
+      alreadyIngested: false,
+      dryRun: true,
+      created: plans.map((p) => p.recordId),
+      skipped,
+      rejected,
+      notices,
+      gates: Object.fromEntries(plans.map((p) => [p.recordId, p.gate])),
+      wouldWrite,
+    };
+  }
+
+  // ── Writes ──────────────────────────────────────────────────────────
+  await mkdir(recordsDir, { recursive: true });
+  await mkdir(candidatesDir, { recursive: true });
+  await mkdir(assetDir, { recursive: true });
+
+  // Texture-space artifacts: hashed in place, not materialized — they are
+  // provenance-of-record (mesh, atlas, texture channels), never consumed
+  // per-render by sdlab mechanism. The receipt pins them by source + hash.
+  for (const key of ['mesh', 'atlas']) {
+    const ref = resolved[key];
+    if (!ref) continue;
+    const { hash, bytes } = await hashAndMaybeCopy(ref.abs, null, false);
+    note(key, ref.relPath, null, false, hash, bytes);
+  }
+  for (const [cid, ref] of resolved.textureChannels) {
+    const { hash, bytes } = await hashAndMaybeCopy(ref.abs, null, false);
+    note(`channel:${cid}`, ref.relPath, null, false, hash, bytes);
+  }
+
+  // Tone-transform operands (schema 1.2.0) are MATERIALIZED, unlike the mesh,
+  // atlas and texture channels beside them. They are small, and they are the
+  // only record of what the upstream transform actually did to these colours
+  // — leaving them as a pointer would make the lane's audit trail depend on
+  // the export tree surviving. Copying them costs kilobytes and removes that
+  // dependency.
+  let toneOperandsRef = null;
+  if (resolved.toneOperands) {
+    const opName = basename(resolved.toneOperands.relPath);
+    const opDest = join(assetDir, opName);
+    const opRel = toPortablePath(join('assets', assetId, opName));
+    const { hash, bytes } = await hashAndMaybeCopy(resolved.toneOperands.abs, opDest, true);
+    note('tone_operands', resolved.toneOperands.relPath, opRel, true, hash, bytes);
+    written.push(opRel);
+    toneOperandsRef = { path: opRel, sha256: hash };
+  }
+
+  // Per-render artifacts: materialized into the project.
+  const subdirs = { masks: join(assetDir, 'masks'), channels: join(assetDir, 'channels'), pairs: join(assetDir, 'pairs'), loss: join(assetDir, 'loss-masks') };
+
+  const created = [];
+  for (const p of plans) {
+    const { entry } = p;
+    const candidateName = `${p.recordId}.png`;
+    const candidatePath = join(candidatesDir, candidateName);
+    const candidateRel = toPortablePath(join('outputs', 'candidates', candidateName));
+
+    if (!existsSync(candidatePath)) {
+      await atomicWriteFile(candidatePath, p.renderBuf);
+    }
+    note('render', entry.relPath, candidateRel, true, p.renderSha, p.renderBuf.length);
+    written.push(candidateRel);
+
+    const silName = `${p.renderId}${extname(entry.silhouette.relPath) || '.png'}`;
+    await mkdir(subdirs.masks, { recursive: true });
+    const silDest = join(subdirs.masks, silName);
+    const silRel = toPortablePath(join('assets', assetId, 'masks', silName));
+    const sil = await hashAndMaybeCopy(entry.silhouette.abs, silDest, true);
+    note('silhouette', entry.silhouette.relPath, silRel, true, sil.hash, sil.bytes);
+    written.push(silRel);
+
+    const channelRefs = {};
+    for (const [cid, inst] of entry.instances) {
+      await mkdir(subdirs.channels, { recursive: true });
+      const instName = `${cid}__${p.renderId}${extname(inst.relPath) || '.png'}`;
+      const instDest = join(subdirs.channels, instName);
+      const instRel = toPortablePath(join('assets', assetId, 'channels', instName));
+      const h = await hashAndMaybeCopy(inst.abs, instDest, true);
+      note(`channel:${cid}:${p.renderId}`, inst.relPath, instRel, true, h.hash, h.bytes);
+      written.push(instRel);
+      channelRefs[cid] = { path: instRel, sha256: h.hash };
+    }
+
+    let lossRef;
+    if (entry.lossMask) {
+      await mkdir(subdirs.loss, { recursive: true });
+      const lossName = `${p.renderId}${extname(entry.lossMask.relPath) || '.png'}`;
+      const lossDest = join(subdirs.loss, lossName);
+      const lossRel = toPortablePath(join('assets', assetId, 'loss-masks', lossName));
+      const h = await hashAndMaybeCopy(entry.lossMask.abs, lossDest, true);
+      note(`loss-mask:${p.renderId}`, entry.lossMask.relPath, lossRel, true, h.hash, h.bytes);
+      written.push(lossRel);
+      lossRef = { path: lossRel, sha256: h.hash };
+    }
+
+    const pairRefs = {};
+    for (const [name, pref] of entry.pairs) {
+      await mkdir(subdirs.pairs, { recursive: true });
+      const pairName = `${name}__${p.renderId}${extname(pref.relPath) || '.png'}`;
+      const pairDest = join(subdirs.pairs, pairName);
+      const pairRel = toPortablePath(join('assets', assetId, 'pairs', pairName));
+      const h = await hashAndMaybeCopy(pref.abs, pairDest, true);
+      note(`pair:${name}:${p.renderId}`, pref.relPath, pairRel, true, h.hash, h.bytes);
+      written.push(pairRel);
+      pairRefs[name] = { path: pairRel, sha256: h.hash };
+    }
+
+    const render = entry.render;
+    const facing = render.facing || facingFromCamera(render.camera);
+    const provenance = {
+      source: 'asset',
+      ingested_at: new Date().toISOString(),
+      asset_id: assetId,
+      asset_source: manifest.asset.source ?? null,
+      manifest_path: toPortablePath(join('assets', assetId, ASSET_MANIFEST_FILENAME)),
+      manifest_sha256: manifestSha,
+      acceptance: { ...manifest.acceptance },
+      render_id: p.renderId,
+      camera: { yaw_deg: render.camera.yaw_deg, elevation_deg: render.camera.elevation_deg ?? 0 },
+      light: render.light ?? null,
+      facing,
+      silhouette_mask: { path: silRel, sha256: sil.hash },
+      channels: channelRefs,
+      caption_fields: {
+        subject: captionDefaults.subject ?? null,
+        style_trigger: captionDefaults.style_trigger ?? null,
+        domain_tag: captionDefaults.domain_tag ?? DEFAULT_DOMAIN_TAG,
+        facing,
+      },
+      generation_provenance_known: true,
+      // ── schema 1.2.0 ────────────────────────────────────────────────
+      // `style` is null when the manifest declared none. That null is
+      // MEANINGFUL and is why the field is always written: a record whose
+      // register is unknown is distinguishable from one ruled no-LoRA, and a
+      // curator can filter on it. Silence would collapse the two — the exact
+      // accident E12 Ruling 10b was bought to stop.
+      style: styleRecord,
+      // The RESOLVED per-render answer, never a default the consumer re-derives:
+      // a render carries the asset's tone transform unless it opts out.
+      tone_transform: toneDecl
+        ? {
+            applied: render.tone_transform !== false,
+            kind: toneDecl.kind,
+            space: toneDecl.space ?? null,
+            scope: toneDecl.scope ?? null,
+            reference: toneDecl.reference,
+            reference_is_self: toneDecl.reference === p.renderId,
+            reversible: toneDecl.reversible ?? null,
+            record: toneDecl.record ?? null,
+            operands: toneOperandsRef,
+          }
+        : null,
+      // How this render came to exist (schema 1.3.0). Load-bearing beside
+      // `generation` below: with `generated: false`, a null generation is the
+      // asset's DECLARATION that no seed exists, not a missing field. A
+      // curator filtering for unknown-seed records must not sweep up emit
+      // derivations that never had one.
+      render_derivation: derivationRecord,
+      // Per-image curation axes. Both measured phenomena (register drift at
+      // crop frames; seed-dependent term binding) are per-image, so a record
+      // that cannot answer "what frame, what seed" cannot be curated on them.
+      generation: render.generation
+        ? {
+            frame: render.generation.frame,
+            frame_detail: render.generation.frame_detail ?? null,
+            seed: render.generation.seed ?? null,
+            stem: render.generation.stem ?? null,
+            model: render.generation.model ?? null,
+            reroll_of: render.generation.reroll_of ?? null,
+          }
+        : null,
+    };
+    if (lossRef) provenance.loss_mask = lossRef;
+    if (Object.keys(pairRefs).length > 0) provenance.pair = pairRefs;
+
+    const base = buildBaseRecord(
+      p.recordId,
+      candidateRel,
+      { width: p.width, height: p.height, bytes: p.renderBuf.length },
+      provenance
+    );
+    // identity.subject_name (schema 1.1.0) is the split engine's only
+    // AUTHORED subject-family key. Without it lib/split.js falls back to
+    // id-stem guessing, which reads two ingests of one subject as two
+    // families and will happily put the same subject in train and test.
+    // Lineage is null: an asset render is not derived from another record.
+    const record = subjectName
+      ? buildIdentityRecord(base, { subject_name: subjectName }, null)
+      : base;
+    // Distinct key from `sdlab measure`'s record.measurements, which that
+    // command overwrites wholesale — asset receiving-dock numbers must
+    // survive a later measure run.
+    record.asset_measurements = {
+      tool: ASSET_INGEST_TOOL_ID,
+      palette_gate: p.gate,
+      class_shares: p.shares,
+    };
+
+    const recordRel = toPortablePath(join('records', `${p.recordId}.json`));
+    await atomicWriteFile(p.recordPath, JSON.stringify(record, null, 2) + '\n');
+    written.push(recordRel);
+    created.push(p.recordId);
+  }
+
+  // Manifest copy — byte-identical.
+  const manifestDestRel = toPortablePath(join('assets', assetId, ASSET_MANIFEST_FILENAME));
+  await atomicWriteFile(join(assetDir, ASSET_MANIFEST_FILENAME), manifestRaw);
+  note('manifest', ASSET_MANIFEST_FILENAME, manifestDestRel, true, manifestSha, manifestRaw.length);
+  written.push(manifestDestRel);
+
+  // Receipt LAST — its presence means this ingest completed.
+  const receipt = {
+    schema_version: ASSET_RECEIPT_SCHEMA_VERSION,
+    tool: ASSET_INGEST_TOOL_ID,
+    ingested_at: new Date().toISOString(),
+    asset_id: assetId,
+    source_dir: toPortablePath(sourceDir),
+    manifest_sha256: manifestSha,
+    files: filesLedger,
+    records_created: created,
+    records_skipped: skipped,
+    rejected_renders: rejected,
+    notices,
+    written,
+  };
+  const receiptRel = toPortablePath(join('assets', assetId, RECEIPT_FILENAME));
+  await atomicWriteFile(receiptPath, JSON.stringify(receipt, null, 2) + '\n');
+
+  return {
+    assetId,
+    alreadyIngested: false,
+    dryRun: false,
+    created,
+    skipped,
+    rejected,
+    notices,
+    gates: Object.fromEntries(plans.map((p) => [p.recordId, p.gate])),
+    receiptPath: receiptRel,
+  };
+}