slidemind 0.3.20 → 0.4.1

package/src/lib/image-intent.mjs

@@ -0,0 +1,802 @@
+// The image-intent contract, version 1 — the schema half.
+//
+// An **asset** is immutable bytes (sha256 + sniffed mime + intrinsic size +
+// a portable workspace locator). A **use** is what those bytes are for on one
+// slide: `original` (the saved picture must appear), `reconstruct` (rebuild it
+// as editable content) or `reference` (guidance only). One asset carries many
+// independent uses; the registry itself obliges nothing.
+//
+// Everything here is STRICT. The storyboard parser next door normalizes away
+// what it does not recognise — it has to, it reads a file humans edit. This one
+// must not: an unknown fidelity, a crop that leaves the image, a `fit` on a
+// reference use are all bugs in whatever wrote the record, and silently
+// dropping them is how an approved obligation disappears between the plan and
+// the .pptx. So every parser returns `{ value, issues }` with `value === null`
+// whenever `issues` is non-empty, and each issue is the typed
+// `{code, assetId?, useId?, slide?, message, action}` shape the guide's error
+// table defines.
+//
+// Canonical here; the add-in imports a byte-identical mirror (typed by its
+// `src/ui/src/shared/image-intent.ts`) through scripts/sync-transcription-runtime.mjs,
+// which also mirrors the shared fixture `test/fixtures/image-intent/contract.json`.
+//
+// NO Node builtins, and module-scope helpers carry an `ii`/`II_` prefix. That is the shape
+// `src/builders/plan.mjs` requires of anything it concatenates into the plan
+// gate's browser IIFE (imports stripped, one shared scope), which the plan-review
+// image-use summary will need. The SHA-256 half is therefore a separate module,
+// `image-intent-fingerprint.mjs`.
+
+export const IMAGE_INTENT_VERSION = 1;
+
+export const IMAGE_FIDELITIES = ["original", "reconstruct", "reference"];
+export const RECONSTRUCTION_SCOPES = ["slide", "element"];
+export const PROVENANCE_KINDS = ["attachment", "local", "engine", "generated", "web"];
+
+// What the existing image pipeline can already decode and ship. Grounded in the
+// two MIME tables both repos already keep (CLI `src/bridge/engine-download.mjs`,
+// add-in `RT/agents/design/runtime/dispatcher.ts`). Anything else is rejected at
+// registration — this contract adds no decoder.
+export const SUPPORTED_IMAGE_MIME_TYPES = [
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp",
+  "image/svg+xml",
+];
+
+export const MAX_INSTRUCTION_LENGTH = 2000;
+export const MAX_ID_LENGTH = 128;
+export const MAX_DISPLAY_NAME_LENGTH = 200;
+export const MAX_SLOT_LENGTH = 64;
+
+const II_ID = /^[A-Za-z0-9_-]+$/;
+const II_SHA256 = /^[0-9a-f]{64}$/;
+// `assets/local/<safe-id>.<ext>` and nothing else: no absolute path, no `..`,
+// no second directory. A28 (traversal) is refused here, before any byte I/O.
+const II_WORKSPACE_PATH = /^assets\/local\/[A-Za-z0-9_-]+\.[A-Za-z0-9]+$/;
+const II_DATA_URI = /^data:([a-z]+\/[a-z0-9.+-]+);base64,[A-Za-z0-9+/]+=*$/;
+
+// ---------------------------------------------------------------------------
+// issues
+// ---------------------------------------------------------------------------
+
+// The contract's WHOLE issue vocabulary, in the order the implementation
+// guide's error table lists it. Every module on either side of the wire — the
+// byte half, the derivative half, the route validators, the export checks —
+// draws its codes from here; none may invent one of its own, because a code
+// this list does not have is a code the other repository cannot recognise.
+//
+// Not every code is raised by THIS module: the schema half never touches bytes,
+// so `image_asset_changed` and `image_asset_too_large` come from
+// `image-assets.mjs`, and the `image_use_*` / `image_intent_stale` codes from
+// the later export and fingerprint checks. The vocabulary is still declared in
+// one place, and the shared fixture's `codes` array holds both repositories to
+// it (`test/fixtures/image-intent/contract.json`).
+export const IMAGE_INTENT_ISSUE_CODES = [
+  "image_intent_invalid",
+  "image_intent_conflict",
+  "image_asset_missing",
+  "image_asset_changed",
+  "image_asset_unsupported",
+  "image_asset_too_large",
+  "image_use_unresolved",
+  "image_use_mismatch",
+  "image_intent_unsupported",
+  "image_intent_stale",
+];
+
+/** One typed failure. `action` is what the agent or the user does about it. */
+function iiIssue(code, message, action, extra = {}) {
+  const issue = { code, message, action };
+  if (extra.assetId !== undefined) issue.assetId = extra.assetId;
+  if (extra.useId !== undefined) issue.useId = extra.useId;
+  if (extra.slide !== undefined) issue.slide = extra.slide;
+  return issue;
+}
+
+const II_ACTIONS = {
+  invalid: "Correct the named field and re-record the use.",
+  conflict: "Resolve the duplicate or competing record in the plan before generation.",
+  missing: "Import the source again and rebind the use.",
+  unsupported: "Supply a source in a supported image format.",
+};
+
+function iiInvalid(message, extra) {
+  return iiIssue("image_intent_invalid", message, II_ACTIONS.invalid, extra);
+}
+function iiConflict(message, extra) {
+  return iiIssue("image_intent_conflict", message, II_ACTIONS.conflict, extra);
+}
+function iiMissing(message, extra) {
+  return iiIssue("image_asset_missing", message, II_ACTIONS.missing, extra);
+}
+function iiUnsupported(message, extra) {
+  return iiIssue("image_asset_unsupported", message, II_ACTIONS.unsupported, extra);
+}
+
+/** `{ value, issues }`, with value withheld whenever anything failed. */
+function iiResult(value, issues) {
+  return issues.length ? { value: null, issues } : { value, issues: [] };
+}
+
+// ---------------------------------------------------------------------------
+// primitives
+// ---------------------------------------------------------------------------
+
+function iiIsRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function iiIsFraction(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
+}
+
+function iiIsPositiveInt(value) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+
+function iiId(value, field, issues, extra) {
+  if (typeof value !== "string" || !II_ID.test(value) || value.length > MAX_ID_LENGTH) {
+    issues.push(
+      iiInvalid(
+        `${field} must match /^[A-Za-z0-9_-]+$/ and be at most ${MAX_ID_LENGTH} characters.`,
+        extra,
+      ),
+    );
+    return null;
+  }
+  return value;
+}
+
+// ---------------------------------------------------------------------------
+// AssetUse
+// ---------------------------------------------------------------------------
+
+const II_ORIGINAL_ONLY = ["slot", "fit", "position", "crop"];
+
+/**
+ * Parse one `assetUses[]` entry.
+ *
+ * Normalization is exactly two things, both of them specified: the instruction
+ * is trimmed, and an `original` use gains its defaults (`fit: "contain"`,
+ * `position: {x: 0.5, y: 0.5}`). Nothing else is repaired.
+ *
+ * @param {unknown} raw
+ * @param {{slide?: number}} [ctx] slide number to stamp onto issues
+ */
+export function parseAssetUse(raw, ctx = {}) {
+  const issues = [];
+  const slide = ctx.slide;
+  if (!iiIsRecord(raw)) {
+    return iiResult(null, [iiInvalid("An image use must be a JSON object.", { slide })]);
+  }
+
+  const useId = iiId(raw.useId, "useId", issues, { slide });
+  const where = { slide, useId: useId ?? undefined };
+  const assetId = iiId(raw.assetId, "assetId", issues, where);
+  if (assetId) where.assetId = assetId;
+
+  const fidelity = raw.fidelity;
+  if (!IMAGE_FIDELITIES.includes(fidelity)) {
+    issues.push(
+      iiInvalid(`fidelity must be one of ${IMAGE_FIDELITIES.join(", ")}.`, where),
+    );
+  }
+
+  let instruction = null;
+  if (typeof raw.instruction !== "string") {
+    issues.push(iiInvalid("instruction must be a string.", where));
+  } else {
+    instruction = raw.instruction.trim();
+    if (!instruction) {
+      issues.push(iiInvalid("instruction must not be empty.", where));
+      instruction = null;
+    } else if (instruction.length > MAX_INSTRUCTION_LENGTH) {
+      // Not truncated: a clipped instruction is a changed obligation, and the
+      // agent that wrote it is the one that must shorten it.
+      issues.push(
+        iiInvalid(
+          `instruction must be at most ${MAX_INSTRUCTION_LENGTH} characters (got ${instruction.length}).`,
+          where,
+        ),
+      );
+      instruction = null;
+    }
+  }
+
+  const isReconstruct = fidelity === "reconstruct";
+  const isOriginal = fidelity === "original";
+
+  let reconstructionScope;
+  if (isReconstruct) {
+    if (!RECONSTRUCTION_SCOPES.includes(raw.reconstructionScope)) {
+      issues.push(
+        iiInvalid(
+          `reconstructionScope is required for a reconstruct use and must be one of ${RECONSTRUCTION_SCOPES.join(", ")}.`,
+          where,
+        ),
+      );
+    } else {
+      reconstructionScope = raw.reconstructionScope;
+    }
+  } else if (raw.reconstructionScope !== undefined) {
+    issues.push(
+      iiInvalid("reconstructionScope is only valid on a reconstruct use.", where),
+    );
+  }
+
+  const framing = {};
+  if (!isOriginal) {
+    for (const field of II_ORIGINAL_ONLY) {
+      if (raw[field] !== undefined) {
+        issues.push(iiInvalid(`${field} is only valid on an original use.`, where));
+      }
+    }
+  } else {
+    if (raw.slot !== undefined) {
+      if (
+        typeof raw.slot !== "string" ||
+        !raw.slot.trim() ||
+        raw.slot.length > MAX_SLOT_LENGTH
+      ) {
+        issues.push(
+          iiInvalid(
+            `slot must be a non-empty string of at most ${MAX_SLOT_LENGTH} characters.`,
+            where,
+          ),
+        );
+      } else {
+        framing.slot = raw.slot.trim();
+      }
+    }
+
+    if (raw.fit === undefined) {
+      framing.fit = "contain";
+    } else if (raw.fit === "contain" || raw.fit === "cover") {
+      framing.fit = raw.fit;
+    } else {
+      issues.push(iiInvalid('fit must be "contain" or "cover".', where));
+    }
+
+    if (raw.position === undefined) {
+      framing.position = { x: 0.5, y: 0.5 };
+    } else if (
+      iiIsRecord(raw.position) &&
+      iiIsFraction(raw.position.x) &&
+      iiIsFraction(raw.position.y)
+    ) {
+      framing.position = { x: raw.position.x, y: raw.position.y };
+    } else {
+      issues.push(iiInvalid("position must be {x, y} with both in [0, 1].", where));
+    }
+
+    if (raw.crop !== undefined) {
+      const c = raw.crop;
+      const shaped =
+        iiIsRecord(c) &&
+        iiIsFraction(c.x) &&
+        iiIsFraction(c.y) &&
+        iiIsFraction(c.w) &&
+        iiIsFraction(c.h);
+      if (!shaped) {
+        issues.push(
+          iiInvalid("crop must be {x, y, w, h} with every value in [0, 1].", where),
+        );
+      } else if (c.w <= 0 || c.h <= 0) {
+        issues.push(iiInvalid("crop w and h must be greater than 0.", where));
+      } else if (c.x + c.w > 1 || c.y + c.h > 1) {
+        issues.push(
+          iiInvalid("crop must stay inside the source: x+w <= 1 and y+h <= 1.", where),
+        );
+      } else {
+        framing.crop = { x: c.x, y: c.y, w: c.w, h: c.h };
+      }
+    }
+  }
+
+  if (issues.length) return iiResult(null, issues);
+
+  return iiResult(
+    {
+      useId,
+      assetId,
+      fidelity,
+      instruction,
+      ...(reconstructionScope ? { reconstructionScope } : {}),
+      ...(framing.slot ? { slot: framing.slot } : {}),
+      ...(framing.fit ? { fit: framing.fit } : {}),
+      ...(framing.position ? { position: framing.position } : {}),
+      ...(framing.crop ? { crop: framing.crop } : {}),
+    },
+    issues,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// ImageAsset / manifest
+// ---------------------------------------------------------------------------
+
+/** Parse one registry entry (`state/image-assets.json` → `assets[]`). */
+export function parseImageAsset(raw) {
+  const issues = [];
+  if (!iiIsRecord(raw)) {
+    return iiResult(null, [iiInvalid("An image asset must be a JSON object.")]);
+  }
+
+  const assetId = iiId(raw.assetId, "assetId", issues, {});
+  const where = assetId ? { assetId } : {};
+
+  if (typeof raw.sha256 !== "string" || !II_SHA256.test(raw.sha256)) {
+    issues.push(iiInvalid("sha256 must be 64 lowercase hex digits.", where));
+  }
+  if (typeof raw.mimeType !== "string") {
+    issues.push(iiInvalid("mimeType must be a string.", where));
+  } else if (!SUPPORTED_IMAGE_MIME_TYPES.includes(raw.mimeType)) {
+    issues.push(
+      iiUnsupported(
+        `mimeType ${raw.mimeType} is not one of ${SUPPORTED_IMAGE_MIME_TYPES.join(", ")}.`,
+        where,
+      ),
+    );
+  }
+  if (!iiIsPositiveInt(raw.width) || !iiIsPositiveInt(raw.height)) {
+    issues.push(iiInvalid("width and height must be positive integers.", where));
+  }
+  if (!iiIsPositiveInt(raw.byteLength)) {
+    issues.push(iiInvalid("byteLength must be a positive integer.", where));
+  }
+
+  let displayName = null;
+  if (typeof raw.displayName !== "string" || !raw.displayName.trim()) {
+    issues.push(iiInvalid("displayName must be a non-empty string.", where));
+  } else {
+    displayName = raw.displayName.trim().slice(0, MAX_DISPLAY_NAME_LENGTH);
+  }
+
+  if (typeof raw.workspacePath !== "string" || !II_WORKSPACE_PATH.test(raw.workspacePath)) {
+    issues.push(
+      iiInvalid("workspacePath must be assets/local/<id>.<ext> with no path segments.", where),
+    );
+  }
+
+  let provenance = null;
+  if (!iiIsRecord(raw.provenance) || !PROVENANCE_KINDS.includes(raw.provenance.kind)) {
+    issues.push(
+      iiInvalid(`provenance.kind must be one of ${PROVENANCE_KINDS.join(", ")}.`, where),
+    );
+  } else if (
+    raw.provenance.sourceId !== undefined &&
+    (typeof raw.provenance.sourceId !== "string" || !raw.provenance.sourceId.trim())
+  ) {
+    issues.push(iiInvalid("provenance.sourceId must be a non-empty string.", where));
+  } else {
+    provenance = { kind: raw.provenance.kind };
+    if (raw.provenance.sourceId !== undefined) {
+      provenance.sourceId = raw.provenance.sourceId.trim();
+    }
+  }
+
+  if (issues.length) return iiResult(null, issues);
+
+  return iiResult(
+    {
+      assetId,
+      sha256: raw.sha256,
+      mimeType: raw.mimeType,
+      width: raw.width,
+      height: raw.height,
+      byteLength: raw.byteLength,
+      displayName,
+      workspacePath: raw.workspacePath,
+      provenance,
+    },
+    issues,
+  );
+}
+
+/**
+ * Parse `{version: 1, assets: []}`.
+ *
+ * An unknown version is refused outright — a v2 manifest read by a v1 reader
+ * would lose whatever v2 added, which is exactly the silent downgrade the
+ * contract forbids.
+ */
+export function parseImageAssetManifest(raw) {
+  if (!iiIsRecord(raw)) {
+    return iiResult(null, [iiInvalid("The image asset manifest must be a JSON object.")]);
+  }
+  if (raw.version !== IMAGE_INTENT_VERSION) {
+    return iiResult(null, [
+      iiInvalid(
+        `Unsupported image asset manifest version ${JSON.stringify(raw.version)}; this client speaks version ${IMAGE_INTENT_VERSION}.`,
+      ),
+    ]);
+  }
+  if (!Array.isArray(raw.assets)) {
+    return iiResult(null, [iiInvalid("The image asset manifest needs an assets array.")]);
+  }
+
+  const issues = [];
+  const assets = [];
+  const seen = new Set();
+  for (const entry of raw.assets) {
+    const parsed = parseImageAsset(entry);
+    if (!parsed.value) {
+      issues.push(...parsed.issues);
+      continue;
+    }
+    if (seen.has(parsed.value.assetId)) {
+      issues.push(
+        iiConflict(`Duplicate assetId ${parsed.value.assetId} in the manifest.`, {
+          assetId: parsed.value.assetId,
+        }),
+      );
+      continue;
+    }
+    seen.add(parsed.value.assetId);
+    assets.push(parsed.value);
+  }
+
+  return iiResult({ version: IMAGE_INTENT_VERSION, assets }, issues);
+}
+
+// ---------------------------------------------------------------------------
+// slide uses
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate one slide's `assetUses[]` against the known assets.
+ *
+ * Beyond per-record validity this enforces the two whole-slide rules: use IDs
+ * are unique, and a slide has at most one whole-slide reconstruction blueprint.
+ *
+ * @param {unknown} rawUses
+ * @param {{slide?: number, assetIds?: Iterable<string>, seenUseIds?: Set<string>}} [opts]
+ *   `assetIds` cross-references the manifest (omit to skip that check);
+ *   `seenUseIds` carries deck-wide uniqueness across several slides.
+ */
+export function validateSlideUses(rawUses, opts = {}) {
+  const { slide, assetIds, seenUseIds } = opts;
+  if (rawUses === undefined) return iiResult([], []);
+  if (!Array.isArray(rawUses)) {
+    return iiResult(null, [iiInvalid("assetUses must be an array.", { slide })]);
+  }
+
+  const known = assetIds ? new Set(assetIds) : null;
+  const seen = seenUseIds ?? new Set();
+  const issues = [];
+  const uses = [];
+  let blueprint = null;
+
+  for (const raw of rawUses) {
+    const parsed = parseAssetUse(raw, { slide });
+    if (!parsed.value) {
+      issues.push(...parsed.issues);
+      continue;
+    }
+    const use = parsed.value;
+    if (seen.has(use.useId)) {
+      issues.push(
+        iiConflict(`Duplicate useId ${use.useId}.`, {
+          slide,
+          useId: use.useId,
+          assetId: use.assetId,
+        }),
+      );
+      continue;
+    }
+    if (known && !known.has(use.assetId)) {
+      issues.push(
+        iiMissing(`Use ${use.useId} references unregistered asset ${use.assetId}.`, {
+          slide,
+          useId: use.useId,
+          assetId: use.assetId,
+        }),
+      );
+      continue;
+    }
+    if (use.fidelity === "reconstruct" && use.reconstructionScope === "slide") {
+      if (blueprint) {
+        issues.push(
+          iiConflict(
+            `A slide takes at most one whole-slide reconstruction source; ${blueprint} and ${use.useId} both claim it.`,
+            { slide, useId: use.useId, assetId: use.assetId },
+          ),
+        );
+        continue;
+      }
+      blueprint = use.useId;
+    }
+    seen.add(use.useId);
+    uses.push(use);
+  }
+
+  return iiResult(uses, issues);
+}
+
+// ---------------------------------------------------------------------------
+// targeted-edit overrides and effective uses
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse `state/image-use-overrides.json` —
+ * `{version: 1, slides: [{slideId, assetUses}]}`.
+ *
+ * Each entry is a COMPLETE replacement list for that slide, never a patch, and
+ * it is keyed by the durable slide identity (CLI slide GUID / add-in slide id),
+ * never by a position that reordering invalidates. An explicit `[]` clears the
+ * slide's obligations and is therefore valid.
+ */
+export function parseImageUseOverrides(raw, opts = {}) {
+  if (!iiIsRecord(raw)) {
+    return iiResult(null, [iiInvalid("The image use overrides file must be a JSON object.")]);
+  }
+  if (raw.version !== IMAGE_INTENT_VERSION) {
+    return iiResult(null, [
+      iiInvalid(
+        `Unsupported image use overrides version ${JSON.stringify(raw.version)}; this client speaks version ${IMAGE_INTENT_VERSION}.`,
+      ),
+    ]);
+  }
+  if (!Array.isArray(raw.slides)) {
+    return iiResult(null, [iiInvalid("The image use overrides file needs a slides array.")]);
+  }
+
+  const issues = [];
+  const slides = [];
+  const seenSlideIds = new Set();
+  const seenUseIds = new Set();
+  for (const entry of raw.slides) {
+    if (!iiIsRecord(entry)) {
+      issues.push(iiInvalid("Each override entry must be a JSON object."));
+      continue;
+    }
+    if (typeof entry.slideId !== "string" || !entry.slideId.trim()) {
+      issues.push(iiInvalid("Each override entry needs a non-empty slideId."));
+      continue;
+    }
+    const slideId = entry.slideId.trim();
+    if (seenSlideIds.has(slideId)) {
+      issues.push(iiConflict(`Duplicate override entry for slide ${slideId}.`));
+      continue;
+    }
+    const uses = validateSlideUses(entry.assetUses ?? [], {
+      assetIds: opts.assetIds,
+      seenUseIds,
+    });
+    if (!uses.value) {
+      issues.push(...uses.issues);
+      continue;
+    }
+    seenSlideIds.add(slideId);
+    slides.push({ slideId, assetUses: uses.value });
+  }
+
+  return iiResult({ version: IMAGE_INTENT_VERSION, slides }, issues);
+}
+
+/**
+ * The uses that actually apply to a slide: its override if one exists (even an
+ * empty one — that is a deliberate clearing), otherwise its storyboard uses.
+ *
+ * @param {{slideId?: string|null, storyboardUses?: Array, overrides?: {slides: Array}|null}} args
+ */
+export function selectImageIntent({ slideId = null, storyboardUses = [], overrides = null }) {
+  const entry =
+    slideId && overrides?.slides
+      ? overrides.slides.find((s) => s.slideId === slideId)
+      : undefined;
+  if (entry) return { uses: entry.assetUses, source: "override" };
+  return { uses: storyboardUses ?? [], source: "storyboard" };
+}
+
+/**
+ * One use's obligation in words — for a conflict message, a plan summary, or
+ * the line that tells an agent what it must place on a slide with no mockup.
+ *
+ * The add-in says the same four things in `RT/image-intent-plan.ts`; keep them
+ * worded the same, because a user reads both.
+ */
+export function describeUse(use) {
+  if (use.fidelity === "reconstruct") {
+    return use.reconstructionScope === "slide" ? "a whole-slide rebuild" : "an element rebuild";
+  }
+  return use.fidelity === "original" ? "a placed original" : "a visual reference";
+}
+
+// ---------------------------------------------------------------------------
+// transport envelope
+// ---------------------------------------------------------------------------
+
+/** Parse one `imageIntent.assets[]` descriptor (transport, not the registry). */
+function iiParseTransportAsset(raw) {
+  const issues = [];
+  if (!iiIsRecord(raw)) {
+    return iiResult(null, [iiInvalid("An image intent asset must be a JSON object.")]);
+  }
+
+  const assetId = iiId(raw.assetId, "assetId", issues, {});
+  const where = assetId ? { assetId } : {};
+
+  if (typeof raw.sha256 !== "string" || !II_SHA256.test(raw.sha256)) {
+    issues.push(iiInvalid("sha256 must be 64 lowercase hex digits.", where));
+  }
+  if (typeof raw.mimeType !== "string") {
+    issues.push(iiInvalid("mimeType must be a string.", where));
+  } else if (!SUPPORTED_IMAGE_MIME_TYPES.includes(raw.mimeType)) {
+    issues.push(
+      iiUnsupported(
+        `mimeType ${raw.mimeType} is not one of ${SUPPORTED_IMAGE_MIME_TYPES.join(", ")}.`,
+        where,
+      ),
+    );
+  }
+  if (!iiIsPositiveInt(raw.width) || !iiIsPositiveInt(raw.height)) {
+    issues.push(iiInvalid("width and height must be positive integers.", where));
+  }
+  if (!iiIsPositiveInt(raw.byteLength)) {
+    issues.push(iiInvalid("byteLength must be a positive integer.", where));
+  }
+
+  let displayName = null;
+  if (typeof raw.displayName !== "string" || !raw.displayName.trim()) {
+    issues.push(iiInvalid("displayName must be a non-empty string.", where));
+  } else {
+    displayName = raw.displayName.trim().slice(0, MAX_DISPLAY_NAME_LENGTH);
+  }
+
+  // The concept/spec routes carry the bytes inline; render/translate resolve
+  // them from the deck's existing asset byte map. Carrying both leaves the
+  // receiver to guess which one is authoritative, so it is refused.
+  const hasImage = raw.image !== undefined;
+  const hasPath = raw.workspacePath !== undefined;
+  if (hasImage && hasPath) {
+    issues.push(
+      iiInvalid("An asset descriptor carries either image or workspacePath, not both.", where),
+    );
+  }
+  if (hasImage) {
+    const m = typeof raw.image === "string" ? II_DATA_URI.exec(raw.image) : null;
+    if (!m) {
+      issues.push(iiInvalid("image must be a data:<mime>;base64,<data> URI.", where));
+    } else if (m[1] !== raw.mimeType) {
+      issues.push(
+        iiInvalid(`image data URI declares ${m[1]} but mimeType is ${raw.mimeType}.`, where),
+      );
+    }
+  }
+  if (hasPath && (typeof raw.workspacePath !== "string" || !II_WORKSPACE_PATH.test(raw.workspacePath))) {
+    issues.push(
+      iiInvalid("workspacePath must be assets/local/<id>.<ext> with no path segments.", where),
+    );
+  }
+
+  if (issues.length) return iiResult(null, issues);
+
+  return iiResult(
+    {
+      assetId,
+      sha256: raw.sha256,
+      mimeType: raw.mimeType,
+      width: raw.width,
+      height: raw.height,
+      byteLength: raw.byteLength,
+      displayName,
+      ...(hasImage ? { image: raw.image } : {}),
+      ...(hasPath ? { workspacePath: raw.workspacePath } : {}),
+    },
+    issues,
+  );
+}
+
+/**
+ * Parse the `imageIntent` request envelope — the snapshot of effective uses a
+ * concept/spec/render call carries. Both the sync and the job handler on the
+ * add-in side, and every CLI transport builder, go through this one function.
+ */
+export function parseImageIntentEnvelope(raw) {
+  if (raw === undefined || raw === null) return iiResult(null, []);
+  if (!iiIsRecord(raw)) {
+    return iiResult(null, [iiInvalid("imageIntent must be a JSON object.")]);
+  }
+  if (raw.version !== IMAGE_INTENT_VERSION) {
+    return iiResult(null, [
+      iiInvalid(
+        `Unsupported imageIntent version ${JSON.stringify(raw.version)}; this client speaks version ${IMAGE_INTENT_VERSION}.`,
+      ),
+    ]);
+  }
+  if (!Array.isArray(raw.assets) || !Array.isArray(raw.slides)) {
+    return iiResult(null, [iiInvalid("imageIntent needs an assets array and a slides array.")]);
+  }
+
+  const issues = [];
+  const assets = [];
+  const known = new Set();
+  for (const entry of raw.assets) {
+    const parsed = iiParseTransportAsset(entry);
+    if (!parsed.value) {
+      issues.push(...parsed.issues);
+      continue;
+    }
+    if (known.has(parsed.value.assetId)) {
+      issues.push(
+        iiConflict(`Duplicate assetId ${parsed.value.assetId} in imageIntent.assets.`, {
+          assetId: parsed.value.assetId,
+        }),
+      );
+      continue;
+    }
+    known.add(parsed.value.assetId);
+    assets.push(parsed.value);
+  }
+
+  const slides = [];
+  const seenSlides = new Set();
+  const seenUseIds = new Set();
+  for (const entry of raw.slides) {
+    if (!iiIsRecord(entry)) {
+      issues.push(iiInvalid("Each imageIntent.slides entry must be a JSON object."));
+      continue;
+    }
+    if (!iiIsPositiveInt(entry.slide)) {
+      issues.push(iiInvalid("Each imageIntent.slides entry needs a positive integer slide."));
+      continue;
+    }
+    const slide = entry.slide;
+    if (seenSlides.has(slide)) {
+      issues.push(iiConflict(`Duplicate imageIntent entry for slide ${slide}.`, { slide }));
+      continue;
+    }
+    const uses = validateSlideUses(entry.uses, {
+      slide,
+      assetIds: known,
+      seenUseIds,
+    });
+    if (!uses.value) {
+      issues.push(...uses.issues);
+      continue;
+    }
+    seenSlides.add(slide);
+    slides.push({ slide, uses: uses.value });
+  }
+
+  return iiResult({ version: IMAGE_INTENT_VERSION, assets, slides }, issues);
+}
+
+// ---------------------------------------------------------------------------
+// fingerprint input (design decision 6)
+// ---------------------------------------------------------------------------
+
+// What an asset contributes to a derived output's identity: its bytes and what
+// they intrinsically are. NOT displayName, NOT workspacePath, NOT provenance —
+// renaming a file or moving a workspace must not invalidate a concept, while
+// swapping the bytes behind an unchanged filename must.
+function iiAssetFingerprint(asset) {
+  return {
+    assetId: asset.assetId,
+    sha256: asset.sha256,
+    mimeType: asset.mimeType,
+    width: asset.width,
+    height: asset.height,
+  };
+}
+
+/**
+ * The canonical object a concept/spec/evidence fingerprint is computed over.
+ *
+ * Pure and deterministic: uses sorted by `useId`, asset descriptors sorted by
+ * `assetId`, array order otherwise preserved. `context` is whatever the calling
+ * cache already keys on (slide storyboard, layout/bundle inputs, spec schema
+ * version) and is hashed alongside — never timestamps, never temporary paths.
+ *
+ * Hashing this is `imageIntentFingerprint()` in `image-intent-fingerprint.mjs`.
+ */
+export function imageIntentFingerprintInput({ uses = [], assets = [], context } = {}) {
+  return {
+    version: IMAGE_INTENT_VERSION,
+    assets: [...assets].map(iiAssetFingerprint).sort((a, b) => (a.assetId < b.assetId ? -1 : a.assetId > b.assetId ? 1 : 0)),
+    uses: [...uses].sort((a, b) => (a.useId < b.useId ? -1 : a.useId > b.useId ? 1 : 0)),
+    ...(context === undefined ? {} : { context }),
+  };
+}