@ssobig/writer-cli 0.2.0

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

@@ -0,0 +1,731 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const componentContract = require("../../../templates/mystery-v1/component-storage-contract.js");
+const viewContract = require("../../../templates/mystery-v1/view-component-contract.js");
+const projectRuntime = require("../../../project-runtime.js");
+const { applyPatch } = require("./json-patch.cjs");
+const { clone, equalJson, sha256 } = require("./json.cjs");
+const { cliError } = require("./errors.cjs");
+const { layoutInvestigationBoard } = require("./investigation-board-layout.cjs");
+const {
+  IMPORT_PROFILE,
+  normalizeImportComponents,
+  importCompositionRows,
+  sourceProvenance
+} = require("./project-import.cjs");
+const { version: TOOL_VERSION } = require("../package.json");
+
+const PLAN_SCHEMA_VERSION = "ssobig-writer-change-plan-v1";
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const PROJECT_COLUMNS = "id,slug,title,summary,engine_key,storage_namespace,status,author_name,is_catalog_demo,updated_at";
+const VERSION_COLUMNS = "project_id,version_number,title,display_name,created_from_version,updated_at";
+const SET_COLUMNS = "project_id,version_number,revision,canonical_status,component_checksum,migration_metadata";
+const INSTANCE_COLUMNS = "project_id,version_number,instance_id,template_id,tab_label,sort_order,is_enabled,is_archived,is_required,is_removable,editor_view_id,preview_view_id,capabilities,config,data,revision";
+const VIEW_COLUMNS = "view_instance_id,view_template_id,label,description,renderer_id,supported_modes,sort_order,is_enabled,config,revision";
+const BINDING_COLUMNS = "view_instance_id,binding_key,data_instance_id,access_mode,is_required,sort_order";
+const CHECKPOINT_COLUMNS = "checkpoint_id,project_id,version_number,checkpoint_number,parent_checkpoint_id,restored_from_checkpoint_id,operation_id,message,source,component_set_revision,component_checksum,manifest_hash,changed_instance_ids,created_by_email,created_at";
+const CHECKPOINT_ENTRY_COLUMNS = "checkpoint_id,project_id,version_number,instance_id,template_id,tab_label,sort_order,is_enabled,is_archived,is_required,is_removable,editor_view_id,preview_view_id,capabilities,config,source_revision,data_hash,changed_from_parent";
+const CHECKPOINT_MESSAGE_MAX_LENGTH = 500;
+
+function isObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function validationError(message, cause = null) {
+  const text = String(message || "Component data가 schema를 통과하지 못했습니다.");
+  if (/파일 pointer는 ssobig\.assets/.test(text)) {
+    return cliError("E_ASSET_COMMAND_REQUIRED", `${text} asset 명령을 사용해 주세요.`, null, cause);
+  }
+  if (/지원되지 않는 (?:Component|필드)|필드는 (?:이 Component schema에서 )?지원되지/.test(text)) {
+    return cliError("E_CODE_CHANGE_REQUIRED", `${text} 기존 schema로 표현할 수 없는 변경은 코드 작업으로 진행해야 합니다.`, null, cause);
+  }
+  return cliError("E_VALIDATION", text, null, cause);
+}
+
+function validateLoadedVersion(loaded) {
+  if (!isObject(loaded?.project)) throw cliError("E_PROJECT_NOT_FOUND", "작품을 찾을 수 없습니다.");
+  if (String(loaded.project.status || "") !== "active") throw cliError("E_MIGRATION_REQUIRED", "활성 작품만 CLI에서 다룰 수 있습니다.");
+  let runtime;
+  try { runtime = projectRuntime.resolveProject(loaded.project); }
+  catch (error) { throw cliError("E_MIGRATION_REQUIRED", error.message, { field: error.field || "" }, error); }
+
+  const versionNumber = Number(loaded?.version?.version_number);
+  if (!Number.isSafeInteger(versionNumber) || versionNumber < 1
+    || String(loaded.version.project_id || "") !== String(loaded.project.id || "")) {
+    throw cliError("E_VERSION_NOT_FOUND", "선택한 작품 버전을 찾을 수 없습니다.");
+  }
+  if (String(loaded.componentSet?.project_id || "") !== String(loaded.project.id)
+    || Number(loaded.componentSet?.version_number) !== versionNumber) {
+    throw cliError("E_MIGRATION_REQUIRED", "작품 버전과 Component Set 식별자가 일치하지 않습니다.");
+  }
+
+  const composition = componentContract.validateActiveComposition(loaded.componentSet, loaded.componentRows || []);
+  if (!composition.ok) throw cliError("E_MIGRATION_REQUIRED", composition.error.message, null, composition.error);
+  const views = viewContract.validateProjectViews(loaded.viewRows || [], loaded.bindingRows || [], composition.instances);
+  if (!views.ok) throw cliError("E_MIGRATION_REQUIRED", views.error.message, null, views.error);
+  return Object.freeze({ ...loaded, runtime, versionNumber, instances: composition.instances, views: views.views });
+}
+
+function findInstance(validated, selector) {
+  const value = String(selector || "").trim();
+  const byId = validated.instances.find(instance => instance.instanceId === value);
+  if (byId) return byId;
+  const byTemplate = validated.instances.filter(instance => instance.templateId === value);
+  if (byTemplate.length === 1) return byTemplate[0];
+  if (byTemplate.length > 1) throw cliError("E_AMBIGUOUS_INSTANCE", `${value} Template의 Instance가 여러 개입니다. instance ID를 지정해 주세요.`);
+  throw cliError("E_COMPONENT_NOT_FOUND", `활성 Component를 찾을 수 없습니다: ${value || "(비어 있음)"}`);
+}
+
+function assertGenericPatchAllowed(instance) {
+  if (instance.templateId === "ssobig.assets") {
+    throw cliError("E_ASSET_COMMAND_REQUIRED", "ssobig.assets Component는 generic patch로 수정할 수 없습니다. asset 명령을 사용해 주세요.");
+  }
+  if (!componentContract.componentSpec(instance.templateId)) throw cliError("E_CODE_CHANGE_REQUIRED", `지원되지 않는 Component입니다: ${instance.templateId}`);
+}
+
+function validateHypotheticalData(validated, instance, afterData) {
+  const spec = componentContract.componentSpec(instance.templateId);
+  if (!spec) throw cliError("E_CODE_CHANGE_REQUIRED", `지원되지 않는 Component입니다: ${instance.templateId}`);
+  const invalidData = spec.validate(afterData);
+  if (invalidData) throw validationError(invalidData);
+  const nextRows = validated.componentRows.map(row => row.instance_id === instance.instanceId ? { ...row, data: clone(afterData) } : row);
+  const composition = componentContract.validateActiveComposition(validated.componentSet, nextRows);
+  if (!composition.ok) throw validationError(composition.error.message, composition.error);
+  const views = viewContract.validateProjectViews(validated.viewRows, validated.bindingRows, composition.instances);
+  if (!views.ok) throw cliError("E_MIGRATION_REQUIRED", views.error.message, null, views.error);
+  return composition.instances.find(candidate => candidate.instanceId === instance.instanceId);
+}
+
+function planDigest(plan) {
+  const source = clone(plan);
+  delete source.digest;
+  return sha256(source);
+}
+
+function finalizePlan(plan) {
+  const value = clone(plan);
+  value.digest = planDigest(value);
+  verifyPlan(value);
+  return Object.freeze(value);
+}
+
+function basePlan(validated, actorEmail, operation, options = {}) {
+  return {
+    schemaVersion: PLAN_SCHEMA_VERSION,
+    toolVersion: TOOL_VERSION,
+    planId: String(options.planId || crypto.randomUUID()),
+    createdAt: String(options.createdAt || new Date().toISOString()),
+    actorEmail: String(actorEmail || "").toLowerCase(),
+    operation,
+    project: {
+      id: String(validated.project.id),
+      slug: String(validated.project.slug),
+      storageNamespace: String(validated.project.storage_namespace),
+      authorName: String(validated.project.author_name || "")
+    },
+    versionNumber: validated.versionNumber,
+    readiness: {
+      componentSetRevision: Number(validated.componentSet.revision),
+      componentChecksum: String(validated.componentSet.component_checksum)
+    }
+  };
+}
+
+function checkpointMessage(value, fallback) {
+  const message = String(value || fallback || "").trim();
+  if (!message || message.length > CHECKPOINT_MESSAGE_MAX_LENGTH) {
+    throw cliError("E_VALIDATION", `체크포인트 메시지는 비어 있지 않은 ${CHECKPOINT_MESSAGE_MAX_LENGTH}자 이하 문자열이어야 합니다.`);
+  }
+  return message;
+}
+
+function createComponentPlan(validated, selector, patch, actorEmail, options = {}) {
+  const instance = findInstance(validated, selector);
+  assertGenericPatchAllowed(instance);
+  const afterData = applyPatch(instance.data, patch);
+  if (equalJson(instance.data, afterData)) throw cliError("E_NO_CHANGES", "Patch 적용 결과가 현재 Component data와 같습니다.");
+  const nextInstance = validateHypotheticalData(validated, instance, afterData);
+  componentContract.instancePayload(nextInstance);
+  return finalizePlan({
+    ...basePlan(validated, actorEmail, "component.patch", options),
+    checkpointMessage: checkpointMessage(
+      options.checkpointMessage,
+      `CLI: ${instance.tab || instance.instanceId} 수정 (${patch.filter(item => item.op !== "test").length}개 변경)`
+    ),
+    target: {
+      instanceId: instance.instanceId,
+      templateId: instance.templateId,
+      expectedRevision: instance.revision
+    },
+    patch: clone(patch),
+    beforeHash: sha256(instance.data),
+    afterHash: sha256(afterData),
+    beforeData: clone(instance.data),
+    afterData: clone(afterData)
+  });
+}
+
+function investigationBoardReferences(validated) {
+  const references = [];
+  const seen = new Set();
+  const add = (type, value) => {
+    const id = String(value || "").trim();
+    const key = `${type}:${id}`;
+    if (!id || seen.has(key)) return;
+    seen.add(key);
+    references.push({ type, id });
+  };
+
+  for (const instance of validated.instances) {
+    if (instance.templateId === "ssobig.character") {
+      const data = instance.data || {};
+      const characters = isObject(data.characters) ? data.characters : {};
+      const deleted = new Set(Array.isArray(data.deletedColumns) ? data.deletedColumns : []);
+      for (const id of Array.isArray(data.order) ? data.order : []) {
+        if (typeof id === "string" && Object.hasOwn(characters, id) && !deleted.has(id)) add("character", id);
+      }
+    }
+    if (instance.templateId === "ssobig.clues") {
+      for (const clue of Array.isArray(instance.data?.clues) ? instance.data.clues : []) {
+        add("clue", clue?.id);
+      }
+    }
+  }
+  return references;
+}
+
+function createInvestigationBoardLayoutPlan(validated, selector, spec, actorEmail, options = {}) {
+  const instance = findInstance(validated, selector || "investigation-board");
+  if (instance.templateId !== "ssobig.investigation-board") {
+    throw cliError("E_VALIDATION", "결정론적 추리 보드 배치는 ssobig.investigation-board Component에만 사용할 수 있습니다.");
+  }
+  const layout = layoutInvestigationBoard(spec, investigationBoardReferences(validated));
+  const patch = [
+    { op: "test", path: "/viewport", value: clone(instance.data.viewport) },
+    { op: "test", path: "/nodes", value: clone(instance.data.nodes) },
+    { op: "test", path: "/edges", value: clone(instance.data.edges) },
+    { op: "replace", path: "/viewport", value: clone(layout.data.viewport) },
+    { op: "replace", path: "/nodes", value: clone(layout.data.nodes) },
+    { op: "replace", path: "/edges", value: clone(layout.data.edges) }
+  ];
+  const componentPlan = createComponentPlan(validated, instance.instanceId, patch, actorEmail, {
+    ...options,
+    checkpointMessage: options.checkpointMessage || "CLI: 추리 보드 결정론적 초안 배치"
+  });
+  const plan = clone(componentPlan);
+  delete plan.digest;
+  plan.layout = {
+    schemaVersion: layout.spec.schemaVersion,
+    algorithmVersion: layout.review.algorithmVersion,
+    specHash: layout.specHash,
+    spec: clone(layout.spec),
+    review: clone(layout.review)
+  };
+  return finalizePlan(plan);
+}
+
+function createAssetPlan(validated, operation, assetId, actorEmail, options = {}) {
+  const assetInstance = componentContract.assetInstance(validated.instances);
+  const manifest = componentContract.assetManifest(validated.instances);
+  const normalizedOperation = String(operation || "");
+  if (!["asset.upload", "asset.delete"].includes(normalizedOperation)) throw cliError("E_USAGE", `지원하지 않는 에셋 plan입니다: ${normalizedOperation}`);
+  const previousEntry = manifest.assets?.[assetId] || null;
+  if (normalizedOperation === "asset.delete" && (!previousEntry || previousEntry.deleted === true)) {
+    throw cliError("E_ASSET_NOT_FOUND", `연결된 에셋을 찾을 수 없습니다: ${assetId}`);
+  }
+  const plan = {
+    ...basePlan(validated, actorEmail, normalizedOperation, options),
+    checkpointMessage: checkpointMessage(
+      options.checkpointMessage,
+      normalizedOperation === "asset.upload"
+        ? `CLI: 에셋 ${assetId} 업로드`
+        : `CLI: 에셋 ${assetId} 연결 해제`
+    ),
+    target: {
+      instanceId: assetInstance.instanceId,
+      templateId: assetInstance.templateId,
+      expectedRevision: assetInstance.revision,
+      assetId: String(assetId)
+    },
+    operationId: String(options.operationId || crypto.randomUUID()),
+    beforeManifestHash: sha256(manifest),
+    previousEntry: clone(previousEntry)
+  };
+  if (normalizedOperation === "asset.upload") plan.file = clone(options.file);
+  return finalizePlan(plan);
+}
+
+function normalizeCheckpoint(row, expected = {}) {
+  if (!isObject(row)
+    || !UUID_PATTERN.test(String(row.checkpoint_id || ""))
+    || !UUID_PATTERN.test(String(row.project_id || ""))
+    || !Number.isSafeInteger(Number(row.version_number))
+    || Number(row.version_number) < 1
+    || !Number.isSafeInteger(Number(row.checkpoint_number))
+    || Number(row.checkpoint_number) < 1
+    || !/^sha256:[0-9a-f]{64}$/.test(String(row.manifest_hash || ""))) {
+    throw cliError("E_CHECKPOINT_NOT_FOUND", "체크포인트 identity를 확인할 수 없습니다.");
+  }
+  if ((expected.projectId && String(row.project_id) !== String(expected.projectId))
+    || (expected.versionNumber && Number(row.version_number) !== Number(expected.versionNumber))) {
+    throw cliError("E_CHECKPOINT_NOT_FOUND", "다른 작품 workspace의 체크포인트는 사용할 수 없습니다.");
+  }
+  return Object.freeze({
+    id: String(row.checkpoint_id),
+    projectId: String(row.project_id),
+    versionNumber: Number(row.version_number),
+    number: Number(row.checkpoint_number),
+    parentId: row.parent_checkpoint_id ? String(row.parent_checkpoint_id) : null,
+    restoredFromId: row.restored_from_checkpoint_id ? String(row.restored_from_checkpoint_id) : null,
+    operationId: row.operation_id ? String(row.operation_id) : null,
+    message: String(row.message || ""),
+    source: String(row.source || ""),
+    componentSetRevision: Number(row.component_set_revision),
+    componentChecksum: String(row.component_checksum || ""),
+    manifestHash: String(row.manifest_hash),
+    changedInstanceIds: Array.isArray(row.changed_instance_ids) ? row.changed_instance_ids.map(String) : [],
+    createdByEmail: String(row.created_by_email || ""),
+    createdAt: String(row.created_at || ""),
+    ...(typeof row.is_head === "boolean" ? { isHead: row.is_head } : {}),
+    ...(typeof row.latest_changed === "boolean" ? { latestChanged: row.latest_changed } : {})
+  });
+}
+
+function createCheckpointPlan(validated, operation, message, actorEmail, options = {}) {
+  if (!["checkpoint.create", "checkpoint.restore"].includes(operation)) {
+    throw cliError("E_USAGE", `지원하지 않는 체크포인트 plan입니다: ${String(operation || "")}`);
+  }
+  const plan = {
+    ...basePlan(validated, actorEmail, operation, options),
+    operationId: String(options.operationId || crypto.randomUUID()),
+    checkpointMessage: checkpointMessage(message, "")
+  };
+  if (operation === "checkpoint.restore") {
+    const target = normalizeCheckpoint(options.target, {
+      projectId: validated.project.id,
+      versionNumber: validated.versionNumber
+    });
+    plan.target = {
+      checkpointId: target.id,
+      checkpointNumber: target.number,
+      manifestHash: target.manifestHash,
+      message: target.message,
+      source: target.source,
+      createdAt: target.createdAt
+    };
+  }
+  return finalizePlan(plan);
+}
+
+function projectStatusPair(operation) {
+  if (operation === "project.archive") return { expectedStatus: "active", targetStatus: "archived" };
+  if (operation === "project.restore") return { expectedStatus: "archived", targetStatus: "active" };
+  throw cliError("E_USAGE", `지원하지 않는 작품 상태 plan입니다: ${String(operation || "")}`);
+}
+
+function createProjectStatusPlan(project, operation, actorEmail, options = {}) {
+  if (!isObject(project)) throw cliError("E_PROJECT_NOT_FOUND", "작품을 찾을 수 없습니다.");
+  try { projectRuntime.resolveProject(project); }
+  catch (error) { throw cliError("E_MIGRATION_REQUIRED", error.message, { field: error.field || "" }, error); }
+  const pair = projectStatusPair(operation);
+  if (String(project.status || "") !== pair.expectedStatus) {
+    throw cliError("E_CONFLICT", `${pair.expectedStatus} 상태의 작품만 이 작업을 계획할 수 있습니다.`);
+  }
+  const expectedUpdatedAt = String(project.updated_at || "");
+  if (!expectedUpdatedAt || Number.isNaN(new Date(expectedUpdatedAt).getTime())) {
+    throw cliError("E_MIGRATION_REQUIRED", "작품 updated_at을 확인할 수 없습니다.");
+  }
+  return finalizePlan({
+    schemaVersion: PLAN_SCHEMA_VERSION,
+    toolVersion: TOOL_VERSION,
+    planId: String(options.planId || crypto.randomUUID()),
+    createdAt: String(options.createdAt || new Date().toISOString()),
+    actorEmail: String(actorEmail || "").toLowerCase(),
+    operation,
+    project: {
+      id: String(project.id),
+      slug: String(project.slug),
+      storageNamespace: String(project.storage_namespace),
+      authorName: String(project.author_name || "")
+    },
+    target: { ...pair, expectedUpdatedAt }
+  });
+}
+
+function createCatalogDemoPlan(project, enabled, actorEmail, options = {}) {
+  if (!isObject(project)) throw cliError("E_PROJECT_NOT_FOUND", "작품을 찾을 수 없습니다.");
+  try { projectRuntime.resolveProject(project); }
+  catch (error) { throw cliError("E_MIGRATION_REQUIRED", error.message, { field: error.field || "" }, error); }
+  const expectedUpdatedAt = String(project.updated_at || "");
+  if (!expectedUpdatedAt || Number.isNaN(new Date(expectedUpdatedAt).getTime())) {
+    throw cliError("E_MIGRATION_REQUIRED", "작품 updated_at을 확인할 수 없습니다.");
+  }
+  if (typeof enabled !== "boolean" || typeof project.is_catalog_demo !== "boolean") {
+    throw cliError("E_MIGRATION_REQUIRED", "공용 데모 상태를 확인할 수 없습니다.");
+  }
+  if (project.is_catalog_demo === enabled) throw cliError("E_NO_CHANGES", `공용 데모 상태가 이미 ${enabled ? "사용" : "사용 안 함"}입니다.`);
+  return finalizePlan({
+    schemaVersion: PLAN_SCHEMA_VERSION,
+    toolVersion: TOOL_VERSION,
+    planId: String(options.planId || crypto.randomUUID()),
+    createdAt: String(options.createdAt || new Date().toISOString()),
+    actorEmail: String(actorEmail || "").toLowerCase(),
+    operation: "project.catalog-demo",
+    project: {
+      id: String(project.id),
+      slug: String(project.slug),
+      storageNamespace: String(project.storage_namespace),
+      authorName: String(project.author_name || "")
+    },
+    target: {
+      expectedIsCatalogDemo: project.is_catalog_demo,
+      enabled,
+      expectedStatus: String(project.status || ""),
+      expectedUpdatedAt
+    }
+  });
+}
+
+function projectCreationTarget(input = {}) {
+  const slug = String(input.slug || "").trim();
+  const title = String(input.title || "").trim();
+  const authorName = String(input.authorName || "").trim();
+  if (!projectRuntime.SLUG_PATTERN.test(slug) || slug.length > 80) {
+    throw cliError("E_VALIDATION", "작품 slug는 80자 이하의 영문 소문자 kebab-case여야 합니다.");
+  }
+  if (!title || title.length > 120) {
+    throw cliError("E_VALIDATION", "작품명은 비어 있지 않은 120자 이하 문자열이어야 합니다.");
+  }
+  if (!authorName || authorName.length > 80) {
+    throw cliError("E_VALIDATION", "작가명은 비어 있지 않은 80자 이하 문자열이어야 합니다.");
+  }
+  return Object.freeze({
+    slug,
+    title,
+    authorName,
+    expectedStatus: "absent",
+    scaffold: "writer-scaffold-v1"
+  });
+}
+
+function createProjectCreationPlan(input, actorEmail, options = {}) {
+  return finalizePlan({
+    schemaVersion: PLAN_SCHEMA_VERSION,
+    toolVersion: TOOL_VERSION,
+    planId: String(options.planId || crypto.randomUUID()),
+    createdAt: String(options.createdAt || new Date().toISOString()),
+    actorEmail: String(actorEmail || "").toLowerCase(),
+    operation: "project.create",
+    target: projectCreationTarget(input)
+  });
+}
+
+function createProjectImportPlan(input, actorEmail, options = {}) {
+  const target = projectCreationTarget(input);
+  const components = normalizeImportComponents(input.components);
+  importCompositionRows(components);
+  if (!isObject(input.source) || typeof input.source.sourceHash !== "string" || !/^[0-9a-f]{64}$/.test(input.source.sourceHash)) {
+    throw cliError("E_VALIDATION", "Import source hash가 올바르지 않습니다.");
+  }
+  if (!isObject(input.coverage) || Number(input.coverage.unexplained) !== 0) {
+    throw cliError("E_VALIDATION", "Import coverage에 설명되지 않은 항목이 남아 있습니다.");
+  }
+  if (!Array.isArray(input.assets)) throw cliError("E_VALIDATION", "Import asset 목록이 필요합니다.");
+  return finalizePlan({
+    schemaVersion: PLAN_SCHEMA_VERSION,
+    toolVersion: TOOL_VERSION,
+    planId: String(options.planId || crypto.randomUUID()),
+    createdAt: String(options.createdAt || new Date().toISOString()),
+    actorEmail: String(actorEmail || "").toLowerCase(),
+    operation: "project.import",
+    target: {
+      slug: target.slug,
+      title: target.title,
+      authorName: target.authorName,
+      expectedStatus: target.expectedStatus,
+      importProfile: IMPORT_PROFILE
+    },
+    source: clone(input.source),
+    coverage: clone(input.coverage),
+    components: clone(components),
+    componentDataHash: sha256(components),
+    assets: clone(input.assets)
+  });
+}
+
+function verifyPlan(plan) {
+  if (!isObject(plan) || plan.schemaVersion !== PLAN_SCHEMA_VERSION || plan.toolVersion !== TOOL_VERSION) {
+    throw cliError("E_INVALID_PLAN", "지원하지 않는 Writer CLI plan 형식입니다.");
+  }
+  if (!UUID_PATTERN.test(String(plan.planId || "")) || typeof plan.digest !== "string" || plan.digest !== planDigest(plan)) {
+    throw cliError("E_INVALID_PLAN", "plan 식별자 또는 digest가 올바르지 않습니다.");
+  }
+  if (!["component.patch", "asset.upload", "asset.delete", "project.create", "project.import", "project.archive", "project.restore", "project.catalog-demo", "checkpoint.create", "checkpoint.restore"].includes(plan.operation)) throw cliError("E_INVALID_PLAN", "지원하지 않는 plan operation입니다.");
+  if (["component.patch", "asset.upload", "asset.delete", "checkpoint.create", "checkpoint.restore"].includes(plan.operation)) {
+    let normalizedCheckpointMessage = "";
+    try { normalizedCheckpointMessage = checkpointMessage(plan.checkpointMessage, ""); }
+    catch (error) { throw cliError("E_INVALID_PLAN", "체크포인트 메시지가 올바르지 않습니다.", null, error); }
+    if (normalizedCheckpointMessage !== plan.checkpointMessage) {
+      throw cliError("E_INVALID_PLAN", "체크포인트 메시지가 올바르지 않습니다.");
+    }
+  }
+  if (plan.operation.startsWith("asset.") && !UUID_PATTERN.test(String(plan.operationId || ""))) {
+    throw cliError("E_INVALID_PLAN", "에셋 plan의 operationId가 올바른 UUID가 아닙니다.");
+  }
+  if (plan.operation.startsWith("checkpoint.")) {
+    if (!UUID_PATTERN.test(String(plan.operationId || ""))
+      || !UUID_PATTERN.test(String(plan.project?.id || ""))
+      || !Number.isSafeInteger(Number(plan.versionNumber))
+      || Number(plan.versionNumber) < 1
+      || !Number.isSafeInteger(Number(plan.readiness?.componentSetRevision))
+      || Number(plan.readiness.componentSetRevision) < 1
+      || !String(plan.readiness?.componentChecksum || "")) {
+      throw cliError("E_INVALID_PLAN", "체크포인트 plan의 workspace identity가 올바르지 않습니다.");
+    }
+    if (plan.operation === "checkpoint.create" && Object.hasOwn(plan, "target")) {
+      throw cliError("E_INVALID_PLAN", "체크포인트 생성 plan에 복원 대상이 포함될 수 없습니다.");
+    }
+    if (plan.operation === "checkpoint.restore" && (!UUID_PATTERN.test(String(plan.target?.checkpointId || ""))
+      || !Number.isSafeInteger(Number(plan.target?.checkpointNumber))
+      || Number(plan.target.checkpointNumber) < 1
+      || !/^sha256:[0-9a-f]{64}$/.test(String(plan.target?.manifestHash || "")))) {
+      throw cliError("E_INVALID_PLAN", "체크포인트 복원 대상이 올바르지 않습니다.");
+    }
+  }
+  if (plan.operation === "project.create") {
+    const target = projectCreationTarget(plan.target);
+    if (String(plan.target?.slug || "") !== target.slug
+      || String(plan.target?.title || "") !== target.title
+      || String(plan.target?.authorName || "") !== target.authorName
+      || String(plan.target?.expectedStatus || "") !== target.expectedStatus
+      || String(plan.target?.scaffold || "") !== target.scaffold) {
+      throw cliError("E_INVALID_PLAN", "새 작품 plan의 입력값이 올바르지 않습니다.");
+    }
+  } else if (plan.operation === "project.import") {
+    const target = projectCreationTarget(plan.target);
+    const components = normalizeImportComponents(plan.components);
+    importCompositionRows(components);
+    if (String(plan.target?.slug || "") !== target.slug
+      || String(plan.target?.title || "") !== target.title
+      || String(plan.target?.authorName || "") !== target.authorName
+      || String(plan.target?.expectedStatus || "") !== target.expectedStatus
+      || String(plan.target?.importProfile || "") !== IMPORT_PROFILE
+      || Object.hasOwn(plan.target || {}, "scaffold")
+      || !equalJson(components, plan.components)
+      || String(plan.componentDataHash || "") !== sha256(components)
+      || !isObject(plan.source)
+      || !/^[0-9a-f]{64}$/.test(String(plan.source.sourceHash || ""))
+      || !isObject(plan.coverage)
+      || Number(plan.coverage.unexplained) !== 0
+      || !Array.isArray(plan.assets)) {
+      throw cliError("E_INVALID_PLAN", "작품 import plan의 입력값이 올바르지 않습니다.");
+    }
+  } else if (plan.operation === "project.catalog-demo") {
+    if (!UUID_PATTERN.test(String(plan.project?.id || ""))
+      || typeof plan.target?.expectedIsCatalogDemo !== "boolean"
+      || typeof plan.target?.enabled !== "boolean"
+      || plan.target.expectedIsCatalogDemo === plan.target.enabled
+      || String(plan.target?.expectedStatus || "") !== "active"
+      || Number.isNaN(new Date(String(plan.target?.expectedUpdatedAt || "")).getTime())) {
+      throw cliError("E_INVALID_PLAN", "공용 데모 plan의 대상 identity가 올바르지 않습니다.");
+    }
+  } else if (plan.operation.startsWith("project.")) {
+    const pair = projectStatusPair(plan.operation);
+    if (!UUID_PATTERN.test(String(plan.project?.id || ""))
+      || String(plan.target?.expectedStatus || "") !== pair.expectedStatus
+      || String(plan.target?.targetStatus || "") !== pair.targetStatus
+      || Number.isNaN(new Date(String(plan.target?.expectedUpdatedAt || "")).getTime())) {
+      throw cliError("E_INVALID_PLAN", "작품 상태 plan의 대상 identity가 올바르지 않습니다.");
+    }
+  }
+  return plan;
+}
+
+function validateProjectImportPlanForApply(plan, existingProject, actorEmail) {
+  verifyPlan(plan);
+  if (plan.operation !== "project.import") throw cliError("E_INVALID_PLAN", "작품 import plan이 아닙니다.");
+  if (String(plan.actorEmail || "").toLowerCase() !== String(actorEmail || "").toLowerCase()) {
+    throw cliError("E_PLAN_ACTOR_MISMATCH", "plan을 만든 계정과 적용 계정이 다릅니다. 현재 계정으로 plan을 다시 만들어 주세요.");
+  }
+  if (existingProject) throw cliError("E_CONFLICT", `이미 사용 중인 작품 slug입니다: ${plan.target.slug}`);
+  const target = projectCreationTarget(plan.target);
+  const components = normalizeImportComponents(plan.components);
+  importCompositionRows(components);
+  return Object.freeze({ target, components, provenance: sourceProvenance(plan.source, plan.coverage) });
+}
+
+function validateProjectCreationPlanForApply(plan, existingProject, actorEmail) {
+  verifyPlan(plan);
+  if (plan.operation !== "project.create") throw cliError("E_INVALID_PLAN", "새 작품 생성 plan이 아닙니다.");
+  if (String(plan.actorEmail || "").toLowerCase() !== String(actorEmail || "").toLowerCase()) {
+    throw cliError("E_PLAN_ACTOR_MISMATCH", "plan을 만든 계정과 적용 계정이 다릅니다. 현재 계정으로 plan을 다시 만들어 주세요.");
+  }
+  if (existingProject) throw cliError("E_CONFLICT", `이미 사용 중인 작품 slug입니다: ${plan.target.slug}`);
+  return projectCreationTarget(plan.target);
+}
+
+function validateProjectStatusPlanForApply(plan, project, actorEmail) {
+  verifyPlan(plan);
+  if (!plan.operation.startsWith("project.")) throw cliError("E_INVALID_PLAN", "작품 상태 plan이 아닙니다.");
+  if (String(plan.actorEmail || "").toLowerCase() !== String(actorEmail || "").toLowerCase()) {
+    throw cliError("E_PLAN_ACTOR_MISMATCH", "plan을 만든 계정과 적용 계정이 다릅니다. 현재 계정으로 plan을 다시 만들어 주세요.");
+  }
+  if (!isObject(project)
+    || String(plan.project?.id || "") !== String(project.id || "")
+    || String(plan.project?.slug || "") !== String(project.slug || "")
+    || String(plan.project?.storageNamespace || "") !== String(project.storage_namespace || "")
+    || String(plan.project?.authorName || "") !== String(project.author_name || "")) {
+    throw cliError("E_INVALID_PLAN", "plan의 작품 identity가 현재 DB 원본과 일치하지 않습니다.");
+  }
+  if (String(project.status || "") !== String(plan.target.expectedStatus)
+    || String(project.updated_at || "") !== String(plan.target.expectedUpdatedAt)) {
+    throw cliError("E_CONFLICT", "plan 생성 후 작품 상태가 변경되었습니다. 새 plan을 만들어 주세요.");
+  }
+  return project;
+}
+
+function validateCatalogDemoPlanForApply(plan, project, actorEmail) {
+  verifyPlan(plan);
+  if (plan.operation !== "project.catalog-demo") throw cliError("E_INVALID_PLAN", "공용 데모 plan이 아닙니다.");
+  if (String(plan.actorEmail || "").toLowerCase() !== String(actorEmail || "").toLowerCase()) {
+    throw cliError("E_PLAN_ACTOR_MISMATCH", "plan을 만든 계정과 적용 계정이 다릅니다. 현재 계정으로 plan을 다시 만들어 주세요.");
+  }
+  if (!isObject(project)
+    || String(plan.project?.id || "") !== String(project.id || "")
+    || String(plan.project?.slug || "") !== String(project.slug || "")
+    || String(plan.project?.storageNamespace || "") !== String(project.storage_namespace || "")
+    || String(plan.project?.authorName || "") !== String(project.author_name || "")) {
+    throw cliError("E_INVALID_PLAN", "plan의 작품 identity가 현재 DB 원본과 일치하지 않습니다.");
+  }
+  if (String(project.status || "") !== String(plan.target.expectedStatus)
+    || Boolean(project.is_catalog_demo) !== plan.target.expectedIsCatalogDemo
+    || String(project.updated_at || "") !== String(plan.target.expectedUpdatedAt)) {
+    throw cliError("E_CONFLICT", "plan 생성 후 작품 또는 공용 데모 상태가 변경되었습니다. 새 plan을 만들어 주세요.");
+  }
+  return project;
+}
+
+function assertPlanContext(plan, validated, actorEmail) {
+  verifyPlan(plan);
+  if (String(plan.actorEmail || "").toLowerCase() !== String(actorEmail || "").toLowerCase()) {
+    throw cliError("E_PLAN_ACTOR_MISMATCH", "plan을 만든 계정과 적용 계정이 다릅니다. 현재 계정으로 plan을 다시 만들어 주세요.");
+  }
+  if (String(plan.project?.id || "") !== String(validated.project.id)
+    || String(plan.project?.slug || "") !== String(validated.project.slug)
+    || String(plan.project?.storageNamespace || "") !== String(validated.project.storage_namespace)
+    || String(plan.project?.authorName || "") !== String(validated.project.author_name || "")
+    || Number(plan.versionNumber) !== validated.versionNumber) {
+    throw cliError("E_INVALID_PLAN", "plan의 작품 또는 버전 식별자가 현재 DB 원본과 일치하지 않습니다.");
+  }
+  if (Number(plan.readiness?.componentSetRevision) !== Number(validated.componentSet.revision)
+    || String(plan.readiness?.componentChecksum || "") !== String(validated.componentSet.component_checksum || "")) {
+    throw cliError("E_CONFLICT", "plan 생성 후 작품 Component 상태가 변경되었습니다. 새 plan을 만들어 주세요.");
+  }
+}
+
+function validateComponentPlanForApply(plan, validated, actorEmail) {
+  assertPlanContext(plan, validated, actorEmail);
+  if (plan.operation !== "component.patch") throw cliError("E_INVALID_PLAN", "Component patch plan이 아닙니다.");
+  const instance = findInstance(validated, plan.target?.instanceId);
+  assertGenericPatchAllowed(instance);
+  if (instance.templateId !== plan.target.templateId
+    || instance.revision !== Number(plan.target.expectedRevision)) {
+    throw cliError("E_CONFLICT", "plan 대상 Component의 identity 또는 revision이 변경되었습니다.");
+  }
+  if (sha256(instance.data) !== plan.beforeHash || !equalJson(instance.data, plan.beforeData)) throw cliError("E_CONFLICT", "plan 생성 후 Component data가 변경되었습니다.");
+  const recomputed = applyPatch(instance.data, plan.patch);
+  if (sha256(recomputed) !== plan.afterHash || !equalJson(recomputed, plan.afterData)) throw cliError("E_INVALID_PLAN", "plan의 patch 결과와 afterData가 일치하지 않습니다.");
+  if (Object.hasOwn(plan, "layout")) {
+    let layout;
+    try {
+      layout = layoutInvestigationBoard(plan.layout?.spec, investigationBoardReferences(validated));
+    } catch (error) {
+      if (error.code === "E_VALIDATION") {
+        throw cliError("E_CONFLICT", "plan 생성 후 추리 보드의 캐릭터·단서 참조 조건이 변경되었습니다. 새 plan을 만들어 주세요.", null, error);
+      }
+      throw error;
+    }
+    if (plan.layout.schemaVersion !== layout.spec.schemaVersion
+      || plan.layout.algorithmVersion !== layout.review.algorithmVersion
+      || plan.layout.specHash !== layout.specHash
+      || !equalJson(plan.layout.spec, layout.spec)
+      || !equalJson(plan.layout.review, layout.review)
+      || !equalJson(plan.afterData, layout.data)) {
+      throw cliError("E_INVALID_PLAN", "추리 보드 layout plan의 spec, review 또는 생성 결과가 일치하지 않습니다.");
+    }
+  }
+  const nextInstance = validateHypotheticalData(validated, instance, recomputed);
+  return { instance, nextInstance, payload: componentContract.instancePayload(nextInstance) };
+}
+
+function validateAssetPlanForApply(plan, validated, actorEmail) {
+  assertPlanContext(plan, validated, actorEmail);
+  if (!["asset.upload", "asset.delete"].includes(plan.operation)) throw cliError("E_INVALID_PLAN", "에셋 plan이 아닙니다.");
+  const instance = componentContract.assetInstance(validated.instances);
+  const manifest = componentContract.assetManifest(validated.instances);
+  if (instance.instanceId !== plan.target?.instanceId
+    || instance.templateId !== plan.target?.templateId
+    || instance.revision !== Number(plan.target?.expectedRevision)
+    || sha256(manifest) !== plan.beforeManifestHash
+    || !equalJson(manifest.assets?.[String(plan.target?.assetId)] || null, plan.previousEntry ?? null)) {
+    throw cliError("E_CONFLICT", "plan 생성 후 에셋 manifest가 변경되었습니다. 새 plan을 만들어 주세요.");
+  }
+  return { instance, manifest };
+}
+
+function validateCheckpointPlanForApply(plan, validated, actorEmail, targetRow = null) {
+  assertPlanContext(plan, validated, actorEmail);
+  if (!["checkpoint.create", "checkpoint.restore"].includes(plan.operation)) {
+    throw cliError("E_INVALID_PLAN", "체크포인트 plan이 아닙니다.");
+  }
+  if (plan.operation === "checkpoint.restore") {
+    const target = normalizeCheckpoint(targetRow, {
+      projectId: validated.project.id,
+      versionNumber: validated.versionNumber
+    });
+    if (target.id !== String(plan.target.checkpointId)
+      || target.number !== Number(plan.target.checkpointNumber)
+      || target.manifestHash !== String(plan.target.manifestHash)) {
+      throw cliError("E_CONFLICT", "복원 대상 체크포인트가 plan 생성 후 변경되었습니다.");
+    }
+    return target;
+  }
+  return null;
+}
+
+module.exports = Object.freeze({
+  PLAN_SCHEMA_VERSION,
+  TOOL_VERSION,
+  UUID_PATTERN,
+  PROJECT_COLUMNS,
+  VERSION_COLUMNS,
+  SET_COLUMNS,
+  INSTANCE_COLUMNS,
+  VIEW_COLUMNS,
+  BINDING_COLUMNS,
+  CHECKPOINT_COLUMNS,
+  CHECKPOINT_ENTRY_COLUMNS,
+  componentContract,
+  validateLoadedVersion,
+  findInstance,
+  createComponentPlan,
+  investigationBoardReferences,
+  createInvestigationBoardLayoutPlan,
+  createAssetPlan,
+  createProjectCreationPlan,
+  createProjectImportPlan,
+  createProjectStatusPlan,
+  createCatalogDemoPlan,
+  normalizeCheckpoint,
+  createCheckpointPlan,
+  verifyPlan,
+  validateProjectCreationPlanForApply,
+  validateProjectImportPlanForApply,
+  validateProjectStatusPlanForApply,
+  validateCatalogDemoPlanForApply,
+  validateComponentPlanForApply,
+  validateAssetPlanForApply,
+  validateCheckpointPlanForApply,
+  validationError
+});