@ssobig/writer-cli 0.2.0

package/tools/writer-cli/src/mutations.cjs

@@ -0,0 +1,722 @@
+"use strict";
+
+const { File } = require("node:buffer");
+const AssetRepositoryModule = require("../../../asset-repository.js");
+const StoragePath = require("../../../storage-path.js");
+const { sha256, equalJson, clone } = require("./json.cjs");
+const { cliError, normalizeError } = require("./errors.cjs");
+const { readAssetFile, assertAssetId } = require("./asset-policy.cjs");
+const {
+  componentContract,
+  validateLoadedVersion,
+  findInstance,
+  validateProjectCreationPlanForApply,
+  validateProjectImportPlanForApply,
+  validateProjectStatusPlanForApply,
+  validateCatalogDemoPlanForApply,
+  validateComponentPlanForApply,
+  validateAssetPlanForApply,
+  validateCheckpointPlanForApply,
+  normalizeCheckpoint
+} = require("./domain.cjs");
+const { assertSourceSnapshot, importCompositionRows } = require("./project-import.cjs");
+
+function rpcRow(value) {
+  return Array.isArray(value) ? value[0] : value;
+}
+
+function receiptBase(plan, actorEmail, options = {}) {
+  return {
+    schemaVersion: "ssobig-writer-apply-receipt-v1",
+    planId: plan.planId,
+    operation: plan.operation,
+    actorEmail,
+    project: clone(plan.project),
+    ...(Number.isSafeInteger(Number(plan.versionNumber)) ? { versionNumber: Number(plan.versionNumber) } : {}),
+    appliedAt: String(options.appliedAt || new Date().toISOString())
+  };
+}
+
+async function applyProjectCreationPlan(gateway, plan, actorEmail, options = {}) {
+  const existing = await gateway.findProjectBySlug(plan.target?.slug);
+  const target = validateProjectCreationPlanForApply(plan, existing, actorEmail);
+  let response;
+  try {
+    response = await gateway.createScaffoldProject({ slug: target.slug, title: target.title, authorName: target.authorName });
+  } catch (error) {
+    const normalized = normalizeError(error);
+    if (["E_CONFLICT", "E_AUTHORIZATION", "E_VALIDATION"].includes(normalized.code)) throw normalized;
+    let observed = null;
+    try {
+      const candidate = await gateway.findProjectBySlug(target.slug);
+      if (candidate) observed = { id: candidate.id, slug: candidate.slug, status: candidate.status, updatedAt: candidate.updated_at };
+    } catch (readError) { void readError; }
+    throw cliError("E_AMBIGUOUS_SAVE", "새 작품 생성 요청의 결과를 확정할 수 없습니다. 같은 plan을 재적용하지 말고 작품 목록을 확인해 주세요.", {
+      requestErrorCode: normalized.code,
+      ...(observed ? { observed } : {})
+    }, normalized);
+  }
+
+  const row = rpcRow(response);
+  let project;
+  try { project = await gateway.findProjectBySlug(target.slug); }
+  catch (error) {
+    throw cliError("E_AMBIGUOUS_SAVE", "새 작품 생성 후 작품 원본을 다시 읽을 수 없습니다. 같은 plan을 재적용하지 마세요.", null, error);
+  }
+  if (!project) throw cliError("E_AMBIGUOUS_SAVE", "새 작품 생성 후 작품 원본을 찾을 수 없습니다. 같은 plan을 재적용하지 마세요.");
+
+  let validated;
+  try { validated = await loadValidated(gateway, project.id, 1); }
+  catch (error) {
+    throw cliError("E_AMBIGUOUS_SAVE", "새 작품의 활성 Component 구성을 검증할 수 없습니다. 같은 plan을 재적용하지 마세요.", null, error);
+  }
+  const basic = findInstance(validated, "ssobig.basic");
+  const responseMatches = String(row?.id || "") === String(project.id)
+    && String(row?.slug || "") === target.slug;
+  const projectMatches = String(project.slug || "") === target.slug
+    && String(project.title || "") === target.title
+    && String(project.status || "") === "active"
+    && String(basic.data?.title || "") === target.title;
+  if (!responseMatches || !projectMatches) {
+    throw cliError("E_AMBIGUOUS_SAVE", "새 작품 RPC 응답과 authoritative Component read-back이 일치하지 않습니다. 같은 plan을 재적용하지 마세요.");
+  }
+
+  return Object.freeze({
+    schemaVersion: "ssobig-writer-apply-receipt-v1",
+    planId: plan.planId,
+    operation: plan.operation,
+    actorEmail,
+    appliedAt: String(options.appliedAt || new Date().toISOString()),
+    target: clone(plan.target),
+    project: {
+      id: String(project.id),
+      slug: String(project.slug),
+      storageNamespace: String(project.storage_namespace),
+      authorName: String(project.author_name),
+      status: String(project.status)
+    },
+    manuscriptTitle: String(basic.data.title),
+    versionNumber: 1,
+    componentSetRevision: Number(validated.componentSet.revision),
+    componentChecksum: String(validated.componentSet.component_checksum),
+    componentCount: validated.instances.length,
+    viewCount: validated.views.length,
+    recoveredFromAmbiguousResponse: false
+  });
+}
+
+async function applyProjectImportPlan(gateway, plan, actorEmail, options = {}) {
+  const existing = await gateway.findProjectBySlug(plan.target?.slug);
+  const prepared = validateProjectImportPlanForApply(plan, existing, actorEmail);
+  assertSourceSnapshot(plan.source, { fs: options.fs });
+  const plannedComposition = importCompositionRows(prepared.components);
+  let response;
+  try {
+    response = await gateway.createImportedProject({
+      slug: prepared.target.slug,
+      title: prepared.target.title,
+      authorName: prepared.target.authorName,
+      components: prepared.components,
+      provenance: prepared.provenance
+    });
+  } catch (error) {
+    const normalized = normalizeError(error);
+    if (["E_CONFLICT", "E_AUTHORIZATION", "E_VALIDATION"].includes(normalized.code)) throw normalized;
+    let observed = null;
+    try {
+      const candidate = await gateway.findProjectBySlug(prepared.target.slug);
+      if (candidate) observed = { id: candidate.id, slug: candidate.slug, status: candidate.status, updatedAt: candidate.updated_at };
+    } catch (readError) { void readError; }
+    throw cliError("E_AMBIGUOUS_SAVE", "작품 import 요청의 결과를 확정할 수 없습니다. 같은 plan을 재적용하지 말고 작품 목록을 확인해 주세요.", {
+      requestErrorCode: normalized.code,
+      ...(observed ? { observed } : {})
+    }, normalized);
+  }
+
+  const row = rpcRow(response);
+  let project;
+  try { project = await gateway.findProjectBySlug(prepared.target.slug); }
+  catch (error) {
+    throw cliError("E_AMBIGUOUS_SAVE", "작품 import 후 작품 원본을 다시 읽을 수 없습니다. 같은 plan을 재적용하지 마세요.", null, error);
+  }
+  if (!project) throw cliError("E_AMBIGUOUS_SAVE", "작품 import 후 작품 원본을 찾을 수 없습니다. 같은 plan을 재적용하지 마세요.");
+
+  let validated;
+  try { validated = await loadValidated(gateway, project.id, 1); }
+  catch (error) {
+    throw cliError("E_AMBIGUOUS_SAVE", "import한 작품의 활성 Component 구성을 검증할 수 없습니다. 같은 plan을 재적용하지 마세요.", null, error);
+  }
+  const basic = findInstance(validated, "ssobig.basic");
+  const actualById = new Map(validated.instances.map(instance => [instance.instanceId, instance]));
+  const componentDataMatches = prepared.components.every(expected => {
+    const actual = actualById.get(expected.instanceId);
+    return actual
+      && actual.templateId === expected.templateId
+      && equalJson(actual.data, expected.data);
+  });
+  const metadata = validated.componentSet.migration_metadata || {};
+  const responseMatches = String(row?.id || "") === String(project.id)
+    && String(row?.slug || "") === prepared.target.slug;
+  const projectMatches = String(project.slug || "") === prepared.target.slug
+    && String(project.title || "") === prepared.target.title
+    && String(project.status || "") === "active"
+    && String(basic.data?.title || "") === prepared.target.title;
+  const compositionMatches = validated.instances.length === plannedComposition.componentRows.length
+    && validated.views.length === plannedComposition.viewRows.length
+    && componentDataMatches
+    && String(metadata.operation || "") === "writer-import-v1"
+    && String(metadata.source?.sourceHash || "") === String(plan.source.sourceHash || "");
+  if (!responseMatches || !projectMatches || !compositionMatches) {
+    throw cliError("E_AMBIGUOUS_SAVE", "작품 import RPC 응답과 authoritative Component read-back이 일치하지 않습니다. 같은 plan을 재적용하지 마세요.");
+  }
+
+  return Object.freeze({
+    schemaVersion: "ssobig-writer-apply-receipt-v1",
+    planId: plan.planId,
+    operation: plan.operation,
+    actorEmail,
+    appliedAt: String(options.appliedAt || new Date().toISOString()),
+    target: clone(plan.target),
+    source: clone(prepared.provenance),
+    coverage: clone(plan.coverage),
+    project: {
+      id: String(project.id),
+      slug: String(project.slug),
+      storageNamespace: String(project.storage_namespace),
+      authorName: String(project.author_name),
+      status: String(project.status)
+    },
+    manuscriptTitle: String(basic.data.title),
+    versionNumber: 1,
+    componentSetRevision: Number(validated.componentSet.revision),
+    componentChecksum: String(validated.componentSet.component_checksum),
+    componentCount: validated.instances.length,
+    viewCount: validated.views.length,
+    pendingAssets: clone(plan.assets),
+    recoveredFromAmbiguousResponse: false
+  });
+}
+
+async function applyProjectStatusPlan(gateway, plan, actorEmail, options = {}) {
+  let before;
+  try {
+    before = await gateway.getProject(plan.project.id, plan.target.expectedStatus);
+  } catch (error) {
+    const normalized = normalizeError(error);
+    if (normalized.code === "E_PROJECT_NOT_FOUND") {
+      let moved = false;
+      try { moved = Boolean(await gateway.getProject(plan.project.id, plan.target.targetStatus)); }
+      catch (readError) { void readError; }
+      if (moved) throw cliError("E_CONFLICT", "plan 생성 후 작품 상태가 변경되었습니다. 새 plan을 만들어 주세요.");
+    }
+    throw normalized;
+  }
+  validateProjectStatusPlanForApply(plan, before, actorEmail);
+  let response;
+  try {
+    response = await gateway.setProjectArchived({
+      projectId: before.id,
+      expectedStatus: plan.target.expectedStatus,
+      expectedUpdatedAt: plan.target.expectedUpdatedAt,
+      archived: plan.target.targetStatus === "archived",
+      actorEmail
+    });
+  } catch (error) {
+    const normalized = normalizeError(error);
+    if (["E_CONFLICT", "E_AUTHORIZATION", "E_PROJECT_NOT_FOUND"].includes(normalized.code)) throw normalized;
+    let observed = null;
+    for (const status of [plan.target.targetStatus, plan.target.expectedStatus]) {
+      try {
+        const project = await gateway.getProject(plan.project.id, status);
+        observed = { status: project.status, updatedAt: project.updated_at };
+        break;
+      } catch (readError) { void readError; }
+    }
+    throw cliError("E_AMBIGUOUS_SAVE", "작품 상태 변경 요청의 결과를 확정할 수 없습니다. 같은 plan을 재적용하지 말고 작품 목록을 확인해 주세요.", {
+      requestErrorCode: normalized.code,
+      ...(observed ? { observed } : {})
+    }, normalized);
+  }
+
+  let after;
+  try { after = await gateway.getProject(plan.project.id, plan.target.targetStatus); }
+  catch (error) {
+    throw cliError("E_AMBIGUOUS_SAVE", "작품 상태 변경 후 원본을 다시 읽을 수 없습니다. 같은 plan을 재적용하지 마세요.", null, error);
+  }
+  const row = rpcRow(response);
+  if (String(after.id) !== String(plan.project.id)
+    || String(after.status) !== String(plan.target.targetStatus)
+    || String(row?.id || "") !== String(after.id)
+    || String(row?.status || "") !== String(after.status)
+    || String(row?.updated_at || "") !== String(after.updated_at || "")) {
+    throw cliError("E_AMBIGUOUS_SAVE", "작품 상태 RPC 응답과 authoritative read-back이 일치하지 않습니다. 같은 plan을 재적용하지 마세요.");
+  }
+  return Object.freeze({
+    ...receiptBase(plan, actorEmail, options),
+    target: clone(plan.target),
+    beforeStatus: String(before.status),
+    afterStatus: String(after.status),
+    beforeUpdatedAt: String(before.updated_at),
+    afterUpdatedAt: String(after.updated_at),
+    recoveredFromAmbiguousResponse: false
+  });
+}
+
+async function applyCatalogDemoPlan(gateway, plan, actorEmail, options = {}) {
+  const before = await gateway.getProject(plan.project.id, "active");
+  validateCatalogDemoPlanForApply(plan, before, actorEmail);
+  let response;
+  try {
+    response = await gateway.setCatalogDemoProject({
+      projectId: before.id,
+      expectedIsCatalogDemo: plan.target.expectedIsCatalogDemo,
+      expectedUpdatedAt: plan.target.expectedUpdatedAt,
+      enabled: plan.target.enabled
+    });
+  } catch (error) {
+    const normalized = normalizeError(error);
+    if (["E_CONFLICT", "E_AUTHORIZATION", "E_PROJECT_NOT_FOUND", "E_VALIDATION"].includes(normalized.code)) throw normalized;
+    let observed = null;
+    try {
+      const project = await gateway.getProject(plan.project.id, "active");
+      observed = { isCatalogDemo: project.is_catalog_demo === true, updatedAt: project.updated_at };
+    } catch (readError) { void readError; }
+    throw cliError("E_AMBIGUOUS_SAVE", "공용 데모 지정 결과를 확정할 수 없습니다. 같은 plan을 재적용하지 말고 작품 상태를 확인해 주세요.", {
+      requestErrorCode: normalized.code,
+      ...(observed ? { observed } : {})
+    }, normalized);
+  }
+  const after = await gateway.getProject(plan.project.id, "active");
+  const row = rpcRow(response);
+  if (String(after.id) !== String(plan.project.id)
+    || Boolean(after.is_catalog_demo) !== plan.target.enabled
+    || String(row?.id || "") !== String(after.id)
+    || Boolean(row?.is_catalog_demo) !== Boolean(after.is_catalog_demo)
+    || String(row?.updated_at || "") !== String(after.updated_at || "")) {
+    throw cliError("E_AMBIGUOUS_SAVE", "공용 데모 RPC 응답과 authoritative read-back이 일치하지 않습니다. 같은 plan을 재적용하지 마세요.");
+  }
+  return Object.freeze({
+    ...receiptBase(plan, actorEmail, options),
+    target: clone(plan.target),
+    beforeIsCatalogDemo: before.is_catalog_demo === true,
+    afterIsCatalogDemo: after.is_catalog_demo === true,
+    beforeUpdatedAt: String(before.updated_at),
+    afterUpdatedAt: String(after.updated_at),
+    recoveredFromAmbiguousResponse: false
+  });
+}
+
+async function loadValidated(gateway, projectId, versionNumber) {
+  return validateLoadedVersion(await gateway.loadVersion(projectId, versionNumber));
+}
+
+function verifyReadBack(plan, validated) {
+  const instance = findInstance(validated, plan.target.instanceId);
+  const expectedRevision = Number(plan.target.expectedRevision) + 1;
+  if (instance.revision !== expectedRevision
+    || sha256(instance.data) !== plan.afterHash
+    || Number(validated.componentSet.revision) <= Number(plan.readiness.componentSetRevision)) {
+    throw cliError("E_AMBIGUOUS_SAVE", "저장 후 Component 원본을 검증할 수 없습니다. 다시 쓰지 말고 현재 원본을 확인해 주세요.", {
+      expectedRevision,
+      actualRevision: instance.revision,
+      actualSetRevision: Number(validated.componentSet.revision)
+    });
+  }
+  return instance;
+}
+
+async function verifyAutomaticCheckpoint(gateway, plan, rpcResponse, validated, expectedInstanceIds = null) {
+  const row = rpcRow(rpcResponse);
+  let checkpointRow;
+  try { checkpointRow = await gateway.getCheckpoint(plan.project.id, plan.versionNumber, String(row?.checkpoint_id || "")); }
+  catch (error) { throw cliError("E_AMBIGUOUS_SAVE", "CLI 저장 후 자동 체크포인트를 다시 읽을 수 없습니다. 같은 plan을 재적용하지 마세요.", null, error); }
+  const checkpoint = normalizeCheckpoint(checkpointRow, { projectId: plan.project.id, versionNumber: plan.versionNumber });
+  const changedIds = Array.isArray(expectedInstanceIds)
+    ? expectedInstanceIds.map(String)
+    : plan.target?.instanceId ? [String(plan.target.instanceId)] : [];
+  if (checkpoint.id !== String(row?.checkpoint_id || "")
+    || checkpoint.number !== Number(row?.checkpoint_number)
+    || checkpoint.source !== "cli"
+    || checkpoint.message !== plan.checkpointMessage
+    || checkpoint.componentSetRevision !== Number(validated.componentSet.revision)
+    || checkpoint.componentChecksum !== String(validated.componentSet.component_checksum || "")
+    || changedIds.some(instanceId => !checkpoint.changedInstanceIds.includes(instanceId))) {
+    throw cliError("E_AMBIGUOUS_SAVE", "CLI 자동 체크포인트와 authoritative read-back이 일치하지 않습니다. 같은 plan을 재적용하지 마세요.");
+  }
+  return checkpoint;
+}
+
+async function applyComponentPlan(gateway, plan, actorEmail, options = {}) {
+  const before = await loadValidated(gateway, plan.project.id, plan.versionNumber);
+  const prepared = validateComponentPlanForApply(plan, before, actorEmail);
+  let response = null;
+  let saveError = null;
+  try {
+    response = await gateway.saveInstance({
+      projectId: before.project.id,
+      versionNumber: before.versionNumber,
+      payload: prepared.payload,
+      expectedRevision: prepared.instance.revision,
+      actorEmail,
+      checkpointMessage: plan.checkpointMessage
+    });
+  } catch (error) {
+    const normalized = normalizeError(error);
+    if (normalized.code === "E_CONFLICT" || normalized.code === "E_AUTHORIZATION") throw normalized;
+    saveError = normalized;
+  }
+
+  if (saveError) {
+    let observed = null;
+    try {
+      const current = await loadValidated(gateway, plan.project.id, plan.versionNumber);
+      const currentInstance = findInstance(current, plan.target.instanceId);
+      observed = {
+        revision: currentInstance.revision,
+        dataHash: sha256(currentInstance.data),
+        componentSetRevision: Number(current.componentSet.revision)
+      };
+    } catch (readError) { void readError; }
+    throw cliError("E_AMBIGUOUS_SAVE", "저장 요청의 결과를 확정할 수 없습니다. 같은 plan을 재적용하지 말고 현재 원본을 확인해 주세요.", {
+      requestErrorCode: saveError.code,
+      ...(observed ? { observed } : {})
+    }, saveError);
+  }
+
+  let after;
+  try { after = await loadValidated(gateway, plan.project.id, plan.versionNumber); }
+  catch (readError) {
+    throw cliError("E_AMBIGUOUS_SAVE", "저장 후 원본을 다시 읽을 수 없습니다. 같은 plan을 재적용하지 마세요.", null, readError);
+  }
+  const savedInstance = verifyReadBack(plan, after);
+  const row = rpcRow(response);
+  const responseValid = Number(row?.saved_revision) === savedInstance.revision
+    && Number(row?.component_set_revision) === Number(after.componentSet.revision)
+    && typeof row?.checkpoint_id === "string"
+    && Number.isSafeInteger(Number(row?.checkpoint_number));
+  if (!responseValid) throw cliError("E_AMBIGUOUS_SAVE", "RPC 저장 응답과 authoritative read-back이 일치하지 않습니다. 같은 plan을 재적용하지 마세요.");
+  const checkpoint = await verifyAutomaticCheckpoint(gateway, plan, response, after);
+  return Object.freeze({
+    ...receiptBase(plan, actorEmail, options),
+    target: clone(plan.target),
+    beforeHash: plan.beforeHash,
+    afterHash: plan.afterHash,
+    savedRevision: savedInstance.revision,
+    componentSetRevision: Number(after.componentSet.revision),
+    checkpoint: {
+      id: checkpoint.id,
+      number: checkpoint.number,
+      message: checkpoint.message
+    },
+    recoveredFromAmbiguousResponse: false
+  });
+}
+
+async function checkpointAfterOperation(gateway, plan) {
+  let row = null;
+  try { row = await gateway.getCheckpointByOperation(plan.project.id, plan.versionNumber, plan.operationId); }
+  catch (error) { throw cliError("E_AMBIGUOUS_SAVE", "체크포인트 적용 후 이력을 다시 읽을 수 없습니다. 같은 plan을 재적용하지 마세요.", null, error); }
+  if (!row) throw cliError("E_AMBIGUOUS_SAVE", "체크포인트 적용 후 operation ID에 해당하는 이력을 찾을 수 없습니다. 같은 plan을 재적용하지 마세요.");
+  return normalizeCheckpoint(row, { projectId: plan.project.id, versionNumber: plan.versionNumber });
+}
+
+async function applyCheckpointPlan(gateway, plan, actorEmail, options = {}) {
+  const before = await loadValidated(gateway, plan.project.id, plan.versionNumber);
+  let targetRow = null;
+  if (plan.operation === "checkpoint.restore") {
+    targetRow = await gateway.getCheckpoint(plan.project.id, plan.versionNumber, plan.target.checkpointId);
+  }
+  const target = validateCheckpointPlanForApply(plan, before, actorEmail, targetRow);
+  const targetSnapshot = target
+    ? await gateway.getCheckpointSnapshot(plan.project.id, plan.versionNumber, target.id, { includeData: true })
+    : null;
+  let response = null;
+  let requestError = null;
+  try {
+    response = plan.operation === "checkpoint.create"
+      ? await gateway.createCheckpoint({
+        projectId: plan.project.id,
+        versionNumber: plan.versionNumber,
+        expectedSetRevision: plan.readiness.componentSetRevision,
+        expectedComponentChecksum: plan.readiness.componentChecksum,
+        message: plan.checkpointMessage,
+        operationId: plan.operationId,
+        actorEmail
+      })
+      : await gateway.restoreCheckpoint({
+        projectId: plan.project.id,
+        versionNumber: plan.versionNumber,
+        checkpointId: target.id,
+        expectedSetRevision: plan.readiness.componentSetRevision,
+        expectedComponentChecksum: plan.readiness.componentChecksum,
+        message: plan.checkpointMessage,
+        operationId: plan.operationId,
+        actorEmail
+      });
+  } catch (error) {
+    const normalized = normalizeError(error);
+    if (["E_CONFLICT", "E_AUTHORIZATION", "E_VALIDATION", "E_NO_CHANGES", "E_CODE_CHANGE_REQUIRED", "E_MIGRATION_REQUIRED"].includes(normalized.code)) throw normalized;
+    requestError = normalized;
+  }
+
+  let checkpoint;
+  try { checkpoint = await checkpointAfterOperation(gateway, plan); }
+  catch (error) {
+    if (requestError) {
+      throw cliError("E_AMBIGUOUS_SAVE", "체크포인트 요청의 결과를 확정할 수 없습니다. 같은 plan을 재적용하지 말고 기록을 확인해 주세요.", {
+        requestErrorCode: requestError.code
+      }, requestError);
+    }
+    throw error;
+  }
+  const row = rpcRow(response);
+  if (checkpoint.message !== plan.checkpointMessage
+    || checkpoint.operationId !== plan.operationId
+    || (response && (String(row?.checkpoint_id || "") !== checkpoint.id
+      || Number(row?.checkpoint_number) !== checkpoint.number))) {
+    throw cliError("E_AMBIGUOUS_SAVE", "체크포인트 RPC 응답과 authoritative 이력이 일치하지 않습니다. 같은 plan을 재적용하지 마세요.");
+  }
+
+  const after = await loadValidated(gateway, plan.project.id, plan.versionNumber);
+  if (String(after.componentSet.component_checksum || "") !== String(checkpoint.componentChecksum || "")
+    || Number(after.componentSet.revision) !== Number(checkpoint.componentSetRevision)) {
+    throw cliError("E_AMBIGUOUS_SAVE", "체크포인트와 현재 Latest Component Set이 일치하지 않습니다. 같은 plan을 재적용하지 마세요.");
+  }
+  if (plan.operation === "checkpoint.create") {
+    if (checkpoint.source !== "manual"
+      || Number(after.componentSet.revision) !== Number(before.componentSet.revision)) {
+      throw cliError("E_AMBIGUOUS_SAVE", "수동 체크포인트가 Latest를 변경하지 않았는지 확인할 수 없습니다.");
+    }
+  } else {
+    if (checkpoint.source !== "restore" || checkpoint.restoredFromId !== target.id) {
+      throw cliError("E_AMBIGUOUS_SAVE", "복원 체크포인트가 목표 이력을 가리키지 않습니다.");
+    }
+    const latestById = new Map(after.componentRows.map(item => [String(item.instance_id), item]));
+    const mismatch = targetSnapshot.entries.find(entry => {
+      const latest = latestById.get(String(entry.instance_id));
+      return !latest || !equalJson(latest.data, entry.data);
+    });
+    if (mismatch || latestById.size !== targetSnapshot.entries.length) {
+      throw cliError("E_AMBIGUOUS_SAVE", "복원 후 Latest 원고가 목표 체크포인트 payload와 일치하지 않습니다.", {
+        ...(mismatch ? { instanceId: String(mismatch.instance_id) } : {})
+      });
+    }
+  }
+
+  let guardCheckpoint = null;
+  if (row?.guard_checkpoint_id) {
+    const guardRow = await gateway.getCheckpoint(plan.project.id, plan.versionNumber, String(row.guard_checkpoint_id));
+    guardCheckpoint = normalizeCheckpoint(guardRow, { projectId: plan.project.id, versionNumber: plan.versionNumber });
+  } else if (target && checkpoint.parentId) {
+    const parentRow = await gateway.getCheckpoint(plan.project.id, plan.versionNumber, checkpoint.parentId);
+    const parent = normalizeCheckpoint(parentRow, { projectId: plan.project.id, versionNumber: plan.versionNumber });
+    if (parent.source === "restore_guard") guardCheckpoint = parent;
+  }
+  if (guardCheckpoint && guardCheckpoint.source !== "restore_guard") {
+    throw cliError("E_AMBIGUOUS_SAVE", "복원 전 안전 체크포인트를 확인할 수 없습니다.");
+  }
+  return Object.freeze({
+    ...receiptBase(plan, actorEmail, options),
+    checkpoint,
+    ...(target ? { restoredFrom: target } : {}),
+    ...(guardCheckpoint ? { guardCheckpoint } : {}),
+    componentSetRevision: Number(after.componentSet.revision),
+    componentChecksum: String(after.componentSet.component_checksum),
+    recoveredFromAmbiguousResponse: Boolean(requestError)
+  });
+}
+
+function comparePlannedFile(planFile, currentFile) {
+  for (const key of ["path", "name", "type", "extension", "size", "contentHash"]) {
+    if (String(planFile?.[key]) !== String(currentFile?.[key])) throw cliError("E_CONFLICT", "plan 생성 후 업로드 파일이 변경되었습니다. 새 plan을 만들어 주세요.", { field: key });
+  }
+}
+
+function assetPathPrefix(validated) {
+  const namespace = String(validated.project.storage_namespace || "").trim();
+  if (!/^project-[0-9a-f]{32}-$/.test(namespace)) {
+    throw cliError("E_MIGRATION_REQUIRED", "작품의 불변 Storage namespace를 확인할 수 없습니다.");
+  }
+  return namespace;
+}
+
+function createAssetAdapter(gateway, plan, actorEmail, state) {
+  const prefix = assetPathPrefix(state.initial);
+  const extension = plan.file?.extension || "bin";
+  const folder = plan.file?.type === "application/json" ? `json/v${plan.versionNumber}` : `image/v${plan.versionNumber}`;
+
+  async function readSnapshot() {
+    const validated = await loadValidated(gateway, plan.project.id, plan.versionNumber);
+    const instance = componentContract.assetInstance(validated.instances);
+    return { validated, instance, manifest: componentContract.assetManifest(validated.instances) };
+  }
+
+  return new AssetRepositoryModule.AssetRepository({
+    readManifest: async () => {
+      const fresh = await readSnapshot();
+      if (!state.commitAttempted) validateAssetPlanForApply(plan, fresh.validated, actorEmail);
+      return { manifest: fresh.manifest, revision: fresh.instance.revision };
+    },
+    saveManifest: async (manifest, snapshot) => {
+      state.commitAttempted = true;
+      const fresh = await readSnapshot();
+      if (fresh.instance.instanceId !== plan.target.instanceId || fresh.instance.revision !== Number(snapshot.revision)) {
+        throw cliError("E_CONFLICT", "에셋 manifest revision이 변경되었습니다.");
+      }
+      if (Number(fresh.validated.componentSet.revision) !== Number(plan.readiness.componentSetRevision)
+        || String(fresh.validated.componentSet.component_checksum) !== String(plan.readiness.componentChecksum)) {
+        throw cliError("E_CONFLICT", "에셋 업로드 전에 작품 Component 상태가 변경되었습니다.");
+      }
+      const draft = componentContract.assetInstanceWithManifest(fresh.instance, manifest, Number(snapshot.revision));
+      const syntheticPlan = {
+        ...plan,
+        operation: "component.patch",
+        target: { ...plan.target, expectedRevision: fresh.instance.revision },
+        readiness: {
+          componentSetRevision: Number(fresh.validated.componentSet.revision),
+          componentChecksum: String(fresh.validated.componentSet.component_checksum)
+        },
+        beforeHash: sha256(fresh.instance.data),
+        afterHash: sha256(draft.data),
+        beforeData: clone(fresh.instance.data),
+        afterData: clone(draft.data)
+      };
+      const payload = componentContract.instancePayload(draft);
+      state.lastAttempt = {
+        expectedRevision: fresh.instance.revision,
+        componentSetRevision: Number(fresh.validated.componentSet.revision),
+        beforeHash: syntheticPlan.beforeHash,
+        afterHash: syntheticPlan.afterHash
+      };
+      let response;
+      try {
+        response = await gateway.saveInstance({
+          projectId: fresh.validated.project.id,
+          versionNumber: fresh.validated.versionNumber,
+          payload,
+          expectedRevision: fresh.instance.revision,
+          actorEmail,
+          checkpointMessage: plan.checkpointMessage
+        });
+      } catch (error) {
+        state.saveError = normalizeError(error);
+        throw state.saveError;
+      }
+      const after = await readSnapshot();
+      if (after.instance.revision !== fresh.instance.revision + 1
+        || Number(after.validated.componentSet.revision) <= Number(fresh.validated.componentSet.revision)
+        || !equalJson(after.manifest, manifest)) {
+        throw cliError("E_AMBIGUOUS_SAVE", "에셋 pointer 저장 결과를 검증할 수 없습니다.");
+      }
+      const row = rpcRow(response);
+      const responseValid = Number(row?.saved_revision) === after.instance.revision
+        && Number(row?.component_set_revision) === Number(after.validated.componentSet.revision)
+        && Number(row?.component_set_revision) > Number(fresh.validated.componentSet.revision)
+        && typeof row?.checkpoint_id === "string"
+        && Number.isSafeInteger(Number(row?.checkpoint_number));
+      if (!responseValid) {
+        state.invalidRpcResponse = true;
+        throw cliError("E_AMBIGUOUS_SAVE", "에셋 RPC 응답과 authoritative read-back이 일치하지 않습니다.");
+      }
+      const checkpoint = await verifyAutomaticCheckpoint(gateway, plan, response, after.validated);
+      state.lastSave = {
+        savedRevision: after.instance.revision,
+        componentSetRevision: Number(after.validated.componentSet.revision),
+        recoveredFromAmbiguousResponse: false,
+        beforeHash: syntheticPlan.beforeHash,
+        afterHash: syntheticPlan.afterHash,
+        checkpoint: {
+          id: checkpoint.id,
+          number: checkpoint.number,
+          message: checkpoint.message
+        }
+      };
+      return { manifest: after.manifest, revision: after.instance.revision };
+    },
+    uploadBlob: (objectPath, body, uploadOptions) => gateway.uploadObject(objectPath, body, uploadOptions),
+    removeBlobs: paths => gateway.removeObjects(paths),
+    buildImmutablePath: ({ assetId, contentHash, operationId }) => {
+      const safeId = StoragePath.safePathSegment(String(assetId).replaceAll(":", "-"), "asset");
+      const suffix = StoragePath.safePathSegment(String(contentHash).slice(0, 20), "hash");
+      return StoragePath.joinStoragePath(prefix, folder, `${safeId}-${suffix}-${operationId}.${extension}`);
+    },
+    operationId: () => String(plan.operationId),
+    onOrphan: orphan => state.orphans.push({ path: orphan.path, reason: orphan.reason }),
+    now: optionsNow(state)
+  });
+}
+
+function optionsNow(state) {
+  return () => Number(state.now());
+}
+
+async function applyAssetPlan(gateway, plan, actorEmail, options = {}) {
+  const initial = await loadValidated(gateway, plan.project.id, plan.versionNumber);
+  validateAssetPlanForApply(plan, initial, actorEmail);
+  const assetId = assertAssetId(plan.target.assetId);
+  let file = null;
+  if (plan.operation === "asset.upload") {
+    const inspectedFile = readAssetFile(plan.file?.path, assetId, { fs: options.fs });
+    const inspected = inspectedFile.metadata;
+    comparePlannedFile(plan.file, inspected);
+    file = new File([inspectedFile.buffer], inspected.name, { type: inspected.type });
+  }
+  const state = { initial, lastAttempt: null, lastSave: null, saveError: null, invalidRpcResponse: false, orphans: [], commitAttempted: false, now: options.now || Date.now };
+  const repository = createAssetAdapter(gateway, plan, actorEmail, state);
+  let result;
+  try {
+    result = plan.operation === "asset.upload"
+      ? await repository.upload(assetId, file, { name: plan.file.name, type: plan.file.type, metadata: { size: Number(plan.file.size) } })
+      : await repository.remove(assetId, { tombstone: true });
+  } catch (error) {
+    const normalized = normalizeError(error);
+    if (!state.orphans.length) throw normalized;
+    throw cliError(normalized.code, normalized.message, {
+      ...(normalized.details || {}),
+      orphans: clone(state.orphans)
+    }, normalized);
+  }
+  const after = await loadValidated(gateway, plan.project.id, plan.versionNumber);
+  const afterInstance = componentContract.assetInstance(after.instances);
+  const afterManifest = componentContract.assetManifest(after.instances);
+  const entry = afterManifest.assets?.[assetId] || null;
+  if (plan.operation === "asset.upload") {
+    if (!entry || entry.deleted || !equalJson(entry, result?.entry)
+      || entry.contentHash !== plan.file.contentHash
+      || (result?.unchanged !== true && (entry.operationId !== plan.operationId || entry.path !== result?.path))) {
+      throw cliError("E_AMBIGUOUS_SAVE", "업로드한 에셋 pointer를 원본에서 정확히 확인할 수 없습니다.");
+    }
+  } else if (!entry || entry.deleted !== true || entry.operationId !== plan.operationId) {
+    throw cliError("E_AMBIGUOUS_SAVE", "에셋 tombstone을 원본에서 확인할 수 없습니다.");
+  }
+  const unchanged = result?.unchanged === true;
+  if (state.invalidRpcResponse) throw cliError("E_AMBIGUOUS_SAVE", "에셋 저장 RPC 계약을 확인할 수 없어 적용 성공으로 기록하지 않습니다.");
+  if (!unchanged && !state.lastSave) {
+    const recovered = result?.recoveredCommit === true
+      && afterInstance.revision === Number(plan.target.expectedRevision) + 1
+      && Number(after.componentSet.revision) > Number(plan.readiness.componentSetRevision);
+    if (!recovered) throw cliError("E_AMBIGUOUS_SAVE", "에셋 pointer 저장 revision을 이 작업에 귀속할 수 없습니다.");
+  }
+  if (state.lastSave && (afterInstance.revision < state.lastSave.savedRevision
+    || Number(after.componentSet.revision) < state.lastSave.componentSetRevision)) {
+    throw cliError("E_AMBIGUOUS_SAVE", "에셋 pointer 저장 revision read-back이 일치하지 않습니다.");
+  }
+  const savedRevision = unchanged ? Number(plan.target.expectedRevision) : (state.lastSave?.savedRevision || afterInstance.revision);
+  const componentSetRevision = unchanged ? Number(plan.readiness.componentSetRevision) : (state.lastSave?.componentSetRevision || Number(after.componentSet.revision));
+  return Object.freeze({
+    ...receiptBase(plan, actorEmail, options),
+    target: clone(plan.target),
+    unchanged,
+    asset: clone(entry),
+    previousEntry: clone(plan.previousEntry),
+    beforeManifestHash: plan.beforeManifestHash,
+    afterManifestHash: sha256(result?.manifest || afterManifest),
+    savedRevision,
+    componentSetRevision,
+    ...(!unchanged && state.lastSave?.checkpoint?.id ? { checkpoint: clone(state.lastSave.checkpoint) } : {}),
+    recoveredFromAmbiguousResponse: Boolean(result?.recoveredCommit || state.lastSave?.recoveredFromAmbiguousResponse),
+    orphans: state.orphans
+  });
+}
+
+module.exports = Object.freeze({ applyProjectCreationPlan, applyProjectImportPlan, applyProjectStatusPlan, applyCatalogDemoPlan, applyComponentPlan, applyAssetPlan, applyCheckpointPlan, comparePlannedFile, assetPathPrefix });