@ssobig/writer-cli 0.2.2 → 0.3.2

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

@@ -2,7 +2,10 @@
 
 const crypto = require("node:crypto");
 const componentContract = require("../../../templates/mystery-v1/component-storage-contract.js");
+const componentCatalog = require("../../../templates/mystery-v1/component-catalog-contract.js");
+const componentRegistry = require("../../../templates/mystery-v1/component-registry.js").createDefaultRegistry();
 const viewContract = require("../../../templates/mystery-v1/view-component-contract.js");
+const timelineModel = require("../../../templates/mystery-v1/timeline-model.js");
 const projectRuntime = require("../../../project-runtime.js");
 const { applyPatch } = require("./json-patch.cjs");
 const { clone, equalJson, sha256 } = require("./json.cjs");
@@ -27,6 +30,7 @@ const BINDING_COLUMNS = "view_instance_id,binding_key,data_instance_id,access_mo
 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;
+const INSTANCE_ID_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 
 function isObject(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
@@ -77,6 +81,17 @@ function findInstance(validated, selector) {
   throw cliError("E_COMPONENT_NOT_FOUND", `활성 Component를 찾을 수 없습니다: ${value || "(비어 있음)"}`);
 }
 
+function findStoredInstance(validated, selector) {
+  const value = String(selector || "").trim();
+  const stored = validated.componentRows.map(componentContract.normalizeInstance).filter(Boolean);
+  const byId = stored.find(instance => instance.instanceId === value);
+  if (byId) return byId;
+  const byTemplate = stored.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 명령을 사용해 주세요.");
@@ -140,6 +155,166 @@ function checkpointMessage(value, fallback) {
   return message;
 }
 
+function componentViewReview(validated, descriptor, instanceId, tabLabel) {
+  const activeByTemplate = new Map();
+  for (const instance of validated.instances) {
+    if (!activeByTemplate.has(instance.templateId)) activeByTemplate.set(instance.templateId, instance);
+  }
+  activeByTemplate.set(descriptor.templateId, { instanceId, templateId: descriptor.templateId });
+  const bindings = [];
+  for (const binding of descriptor.view.bindings) {
+    const target = activeByTemplate.get(binding.dataTemplateId);
+    if (!target) {
+      if (binding.required) throw cliError("E_VALIDATION", `${descriptor.templateId} 사용에는 활성 ${binding.dataTemplateId} Component가 필요합니다.`);
+      continue;
+    }
+    bindings.push({ key: binding.key, dataInstanceId: target.instanceId, accessMode: binding.accessMode, required: binding.required });
+  }
+  const viewInstanceId = descriptor.allowMultiple ? `${instanceId}-workbench` : descriptor.view.instanceId;
+  if (!INSTANCE_ID_PATTERN.test(viewInstanceId)) throw cliError("E_VALIDATION", `생성될 View instance ID가 올바르지 않습니다: ${viewInstanceId}`);
+  return {
+    viewInstanceId,
+    viewTemplateId: descriptor.view.templateId,
+    label: `${tabLabel} 작업 화면`,
+    rendererId: descriptor.view.rendererId,
+    modes: clone(descriptor.view.supportedModes),
+    bindings
+  };
+}
+
+function componentAddReview(validated, input = {}) {
+  const templateId = String(input.templateId || "").trim();
+  const descriptor = componentCatalog.get(templateId);
+  if (!descriptor || descriptor.required || descriptor.internal || !descriptor.view) {
+    throw cliError("E_CODE_CHANGE_REQUIRED", `CLI에서 추가할 수 없는 Component Template입니다: ${templateId || "(비어 있음)"}`);
+  }
+  const requestedInstanceId = String(input.instanceId || "").trim();
+  if (descriptor.allowMultiple && !requestedInstanceId) {
+    throw cliError("E_VALIDATION", `${templateId}에는 고유한 instance ID가 필요합니다.`);
+  }
+  const instanceId = requestedInstanceId || descriptor.defaultInstanceId;
+  if (!INSTANCE_ID_PATTERN.test(instanceId)) throw cliError("E_VALIDATION", `Component instance ID가 올바르지 않습니다: ${instanceId || "(비어 있음)"}`);
+  const tabLabel = String(input.tabLabel || descriptor.tabLabel || "").trim();
+  if (!tabLabel || tabLabel.length > 120) throw cliError("E_VALIDATION", "Component label은 비어 있지 않은 120자 이하 문자열이어야 합니다.");
+
+  const conflictingRow = validated.componentRows.find(row => String(row.instance_id) === instanceId
+    || (!descriptor.allowMultiple && String(row.template_id) === templateId));
+  if (conflictingRow) {
+    const state = conflictingRow.is_archived || !conflictingRow.is_enabled ? "보관된" : "활성";
+    throw cliError("E_CONFLICT", `${state} Component가 이미 존재합니다: ${conflictingRow.instance_id}`);
+  }
+
+  const initialData = clone(descriptor.defaultData);
+  const componentSpec = componentContract.componentSpec(templateId);
+  if (!componentSpec) throw cliError("E_CODE_CHANGE_REQUIRED", `등록된 ${templateId}의 Data schema가 없습니다.`);
+  const dataError = componentSpec.validate(initialData);
+  if (dataError) throw cliError("E_CODE_CHANGE_REQUIRED", `등록된 ${templateId} 기본 data가 현재 schema와 일치하지 않습니다: ${dataError}`);
+  return Object.freeze({
+    target: {
+      templateId,
+      instanceId,
+      tabLabel,
+      expectedState: "missing",
+      allowMultiple: descriptor.allowMultiple
+    },
+    initialData,
+    composition: componentViewReview(validated, descriptor, instanceId, tabLabel)
+  });
+}
+
+function createComponentAddPlan(validated, input, actorEmail, options = {}) {
+  const review = componentAddReview(validated, input);
+  return finalizePlan({
+    ...basePlan(validated, actorEmail, "component.add", options),
+    target: review.target,
+    initialData: review.initialData,
+    initialDataHash: sha256(review.initialData),
+    composition: review.composition
+  });
+}
+
+function componentActiveReview(validated, input = {}) {
+  if (typeof input.active !== "boolean") throw cliError("E_VALIDATION", "Component 사용 여부는 true 또는 false여야 합니다.");
+  const instance = findStoredInstance(validated, input.instanceId);
+  const descriptor = componentCatalog.get(instance.templateId);
+  if (!descriptor || descriptor.required || descriptor.internal || !descriptor.view || instance.required || !instance.removable) {
+    throw cliError("E_CODE_CHANGE_REQUIRED", `사용 여부를 변경할 수 없는 Component입니다: ${instance.instanceId}`);
+  }
+  const targetActive = input.active === true;
+  const currentActive = instance.enabled === true && instance.archived === false;
+  if (currentActive === targetActive) throw cliError("E_NO_CHANGES", `Component가 이미 ${targetActive ? "사용 중" : "사용 안 함"} 상태입니다: ${instance.instanceId}`);
+  if (!targetActive) {
+    const requiredDependents = validated.views.filter(view => view.bindings.some(binding => binding.dataInstanceId === instance.instanceId
+      && binding.required && !(binding.key === "primary" && view.rendererId === instance.templateId)));
+    if (requiredDependents.length) {
+      throw cliError("E_VALIDATION", `${instance.tab}을 사용 안 함으로 전환하기 전에 필수로 의존하는 Component를 먼저 보관해야 합니다.`, {
+        dependentViews: requiredDependents.map(view => view.viewInstanceId)
+      });
+    }
+  }
+  return Object.freeze({
+    target: {
+      instanceId: instance.instanceId,
+      templateId: instance.templateId,
+      tabLabel: instance.tab,
+      expectedActive: currentActive,
+      active: targetActive,
+      expectedRevision: instance.revision,
+      expectedDataHash: sha256(instance.data)
+    },
+    composition: targetActive
+      ? componentViewReview(validated, descriptor, instance.instanceId, instance.tab)
+      : { viewInstanceId: descriptor.allowMultiple ? `${instance.instanceId}-workbench` : descriptor.view.instanceId, expectedState: "absent" }
+  });
+}
+
+function createComponentActivePlan(validated, input, actorEmail, options = {}) {
+  const review = componentActiveReview(validated, input);
+  return finalizePlan({
+    ...basePlan(validated, actorEmail, "component.set-active", options),
+    target: review.target,
+    composition: review.composition
+  });
+}
+
+function componentFieldReview(validated, selector, fieldKey, enabled) {
+  const instance = findInstance(validated, selector);
+  const definition = componentRegistry.get(instance.templateId);
+  const field = definition?.fieldConfiguration?.find(item => item.key === String(fieldKey || ""));
+  if (!field) throw cliError("E_CODE_CHANGE_REQUIRED", `등록된 속성 구성 항목이 아닙니다: ${fieldKey || "(비어 있음)"}`);
+  if (field.required) throw cliError("E_VALIDATION", `필수 속성은 사용 안 함으로 전환할 수 없습니다: ${field.label}`);
+  const optionalFields = definition.fieldConfiguration.filter(item => !item.required);
+  const hasSelection = Array.isArray(instance.data?.enabledOptionalFields);
+  const selected = new Set(hasSelection ? instance.data.enabledOptionalFields : optionalFields.map(item => item.key));
+  const beforeEnabled = selected.has(field.key);
+  if (beforeEnabled === enabled) throw cliError("E_NO_CHANGES", `${field.label} 속성이 이미 ${enabled ? "사용" : "사용 안 함"} 상태입니다.`);
+  if (enabled) selected.add(field.key);
+  else selected.delete(field.key);
+  const afterFields = optionalFields.filter(item => selected.has(item.key)).map(item => item.key);
+  const patch = hasSelection
+    ? [{ op: "test", path: "/enabledOptionalFields", value: clone(instance.data.enabledOptionalFields) }, { op: "replace", path: "/enabledOptionalFields", value: afterFields }]
+    : [{ op: "add", path: "/enabledOptionalFields", value: afterFields }];
+  return Object.freeze({ instance, field, beforeEnabled, enabled, afterFields, patch });
+}
+
+function createComponentFieldPlan(validated, selector, fieldKey, enabled, actorEmail, options = {}) {
+  const review = componentFieldReview(validated, selector, fieldKey, enabled);
+  const base = createComponentPlan(validated, review.instance.instanceId, review.patch, actorEmail, {
+    ...options,
+    checkpointMessage: options.checkpointMessage || `CLI: ${review.instance.tab} 선택 속성 ${review.field.label} ${enabled ? "사용" : "사용 안 함"}`
+  });
+  const enriched = clone(base);
+  delete enriched.digest;
+  enriched.fieldSelection = {
+    key: review.field.key,
+    label: review.field.label,
+    beforeEnabled: review.beforeEnabled,
+    enabled: review.enabled,
+    enabledOptionalFields: review.afterFields
+  };
+  return finalizePlan(enriched);
+}
+
 function createComponentPlan(validated, selector, patch, actorEmail, options = {}) {
   const instance = findInstance(validated, selector);
   assertGenericPatchAllowed(instance);
@@ -225,6 +400,50 @@ function createInvestigationBoardLayoutPlan(validated, selector, spec, actorEmai
   return finalizePlan(plan);
 }
 
+function timelineEntryCountsByCharacter(entries) {
+  const counts = new Map();
+  for (const entry of entries) {
+    if (entry.lane?.kind !== "character") continue;
+    const characterId = String(entry.lane.characterId || "");
+    counts.set(characterId, (counts.get(characterId) || 0) + 1);
+  }
+  return Object.fromEntries([...counts.keys()].sort().map(characterId => [characterId, counts.get(characterId)]));
+}
+
+function createTimelineMigrationPlan(validated, selector, actorEmail, options = {}) {
+  const instance = findInstance(validated, selector || "timeline");
+  if (instance.templateId !== "ssobig.timeline") {
+    throw cliError("E_VALIDATION", "타임라인 v2 이관은 ssobig.timeline Component에만 사용할 수 있습니다.");
+  }
+  const shape = timelineModel.detectShape(instance.data);
+  if (shape === "v2") throw cliError("E_NO_CHANGES", "타임라인 Component가 이미 v2 모양입니다.");
+  if (shape !== "legacy") throw cliError("E_VALIDATION", "타임라인 Component data가 legacy 또는 v2 모양이 아닙니다.");
+  const converted = timelineModel.convertLegacyTimeline(instance.data, { idFactory: options.idFactory });
+  const review = timelineModel.compareLegacyToV2(instance.data, converted);
+  if (!review.ok) throw cliError("E_VALIDATION", `타임라인 v2 변환이 원본과 일치하지 않습니다: ${review.mismatches.join(" / ")}`);
+  const patch = [
+    { op: "test", path: "/events", value: clone(instance.data.events) },
+    { op: "remove", path: "/events" },
+    { op: "add", path: "/timeLevels", value: clone(converted.timeLevels) },
+    { op: "add", path: "/entries", value: clone(converted.entries) }
+  ];
+  const componentPlan = createComponentPlan(validated, instance.instanceId, patch, actorEmail, {
+    ...options,
+    checkpointMessage: options.checkpointMessage || "CLI: 타임라인 v2 이관"
+  });
+  const plan = clone(componentPlan);
+  delete plan.digest;
+  plan.migration = {
+    kind: "timeline-v2",
+    counts: clone(review.counts),
+    mismatches: clone(review.mismatches),
+    levelCount: converted.timeLevels.length,
+    entryCount: converted.entries.length,
+    entryCountByCharacter: timelineEntryCountsByCharacter(converted.entries)
+  };
+  return finalizePlan(plan);
+}
+
 function createAssetPlan(validated, operation, assetId, actorEmail, options = {}) {
   const assetInstance = componentContract.assetInstance(validated.instances);
   const manifest = componentContract.assetManifest(validated.instances);
@@ -461,7 +680,7 @@ function verifyPlan(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.add", "component.set-active", "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, ""); }
@@ -502,6 +721,36 @@ function verifyPlan(plan) {
       || String(plan.target?.scaffold || "") !== target.scaffold) {
       throw cliError("E_INVALID_PLAN", "새 작품 plan의 입력값이 올바르지 않습니다.");
     }
+  } else if (plan.operation === "component.add") {
+    const descriptor = componentCatalog.get(String(plan.target?.templateId || ""));
+    if (!descriptor || descriptor.required || descriptor.internal || !descriptor.view
+      || !INSTANCE_ID_PATTERN.test(String(plan.target?.instanceId || ""))
+      || String(plan.target?.expectedState || "") !== "missing"
+      || Boolean(plan.target?.allowMultiple) !== descriptor.allowMultiple
+      || !String(plan.target?.tabLabel || "").trim()
+      || String(plan.target.tabLabel).length > 120
+      || !equalJson(plan.initialData, descriptor.defaultData)
+      || String(plan.initialDataHash || "") !== sha256(descriptor.defaultData)
+      || !isObject(plan.composition)
+      || !INSTANCE_ID_PATTERN.test(String(plan.composition.viewInstanceId || ""))
+      || String(plan.composition.viewTemplateId || "") !== descriptor.view.templateId
+      || String(plan.composition.rendererId || "") !== descriptor.view.rendererId
+      || !Array.isArray(plan.composition.bindings)) {
+      throw cliError("E_INVALID_PLAN", "Component 추가 plan의 대상 또는 구성 review가 올바르지 않습니다.");
+    }
+  } else if (plan.operation === "component.set-active") {
+    const descriptor = componentCatalog.get(String(plan.target?.templateId || ""));
+    if (!descriptor || descriptor.required || descriptor.internal || !descriptor.view
+      || !INSTANCE_ID_PATTERN.test(String(plan.target?.instanceId || ""))
+      || !String(plan.target?.tabLabel || "").trim()
+      || typeof plan.target?.expectedActive !== "boolean"
+      || typeof plan.target?.active !== "boolean"
+      || plan.target.expectedActive === plan.target.active
+      || !Number.isSafeInteger(Number(plan.target?.expectedRevision))
+      || !/^[0-9a-f]{64}$/.test(String(plan.target?.expectedDataHash || ""))
+      || !isObject(plan.composition)) {
+      throw cliError("E_INVALID_PLAN", "Component 사용 여부 plan의 대상 또는 구성 review가 올바르지 않습니다.");
+    }
   } else if (plan.operation === "project.import") {
     const target = projectCreationTarget(plan.target);
     const components = normalizeImportComponents(plan.components);
@@ -655,10 +904,50 @@ function validateComponentPlanForApply(plan, validated, actorEmail) {
       throw cliError("E_INVALID_PLAN", "추리 보드 layout plan의 spec, review 또는 생성 결과가 일치하지 않습니다.");
     }
   }
+  if (Object.hasOwn(plan, "fieldSelection")) {
+    const review = componentFieldReview(validated, instance.instanceId, plan.fieldSelection?.key, plan.fieldSelection?.enabled === true);
+    const expected = {
+      key: review.field.key,
+      label: review.field.label,
+      beforeEnabled: review.beforeEnabled,
+      enabled: review.enabled,
+      enabledOptionalFields: review.afterFields
+    };
+    if (!equalJson(plan.fieldSelection, expected) || !equalJson(plan.patch, review.patch)) {
+      throw cliError("E_INVALID_PLAN", "선택 속성 plan의 review와 patch가 현재 등록 계약과 일치하지 않습니다.");
+    }
+  }
   const nextInstance = validateHypotheticalData(validated, instance, recomputed);
   return { instance, nextInstance, payload: componentContract.instancePayload(nextInstance) };
 }
 
+function validateComponentAddPlanForApply(plan, validated, actorEmail) {
+  assertPlanContext(plan, validated, actorEmail);
+  if (plan.operation !== "component.add") throw cliError("E_INVALID_PLAN", "Component 추가 plan이 아닙니다.");
+  const current = componentAddReview(validated, {
+    templateId: plan.target?.templateId,
+    instanceId: plan.target?.instanceId,
+    tabLabel: plan.target?.tabLabel
+  });
+  if (!equalJson(plan.target, current.target)
+    || !equalJson(plan.initialData, current.initialData)
+    || plan.initialDataHash !== sha256(current.initialData)
+    || !equalJson(plan.composition, current.composition)) {
+    throw cliError("E_INVALID_PLAN", "Component 추가 plan의 review가 현재 등록 계약과 일치하지 않습니다.");
+  }
+  return current;
+}
+
+function validateComponentActivePlanForApply(plan, validated, actorEmail) {
+  assertPlanContext(plan, validated, actorEmail);
+  if (plan.operation !== "component.set-active") throw cliError("E_INVALID_PLAN", "Component 사용 여부 plan이 아닙니다.");
+  const current = componentActiveReview(validated, { instanceId: plan.target?.instanceId, active: plan.target?.active });
+  if (!equalJson(plan.target, current.target) || !equalJson(plan.composition, current.composition)) {
+    throw cliError("E_INVALID_PLAN", "Component 사용 여부 plan의 review가 현재 등록 계약과 일치하지 않습니다.");
+  }
+  return current;
+}
+
 function validateAssetPlanForApply(plan, validated, actorEmail) {
   assertPlanContext(plan, validated, actorEmail);
   if (!["asset.upload", "asset.delete"].includes(plan.operation)) throw cliError("E_INVALID_PLAN", "에셋 plan이 아닙니다.");
@@ -709,9 +998,13 @@ module.exports = Object.freeze({
   componentContract,
   validateLoadedVersion,
   findInstance,
+  createComponentActivePlan,
+  createComponentAddPlan,
+  createComponentFieldPlan,
   createComponentPlan,
   investigationBoardReferences,
   createInvestigationBoardLayoutPlan,
+  createTimelineMigrationPlan,
   createAssetPlan,
   createProjectCreationPlan,
   createProjectImportPlan,
@@ -724,6 +1017,8 @@ module.exports = Object.freeze({
   validateProjectImportPlanForApply,
   validateProjectStatusPlanForApply,
   validateCatalogDemoPlanForApply,
+  validateComponentActivePlanForApply,
+  validateComponentAddPlanForApply,
   validateComponentPlanForApply,
   validateAssetPlanForApply,
   validateCheckpointPlanForApply,

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

@@ -278,6 +278,19 @@ function createSupabaseGateway(client, options = {}) {
     return dataOrThrow(result);
   }
 
+  async function setComponentActive(input) {
+    return dataOrThrow(await client.rpc("set_somi_project_component_active", {
+      p_project_id: String(input.projectId),
+      p_version_number: Number(input.versionNumber),
+      p_expected_set_revision: Number(input.expectedSetRevision),
+      p_template_id: String(input.templateId),
+      p_instance_id: String(input.instanceId),
+      p_tab_label: String(input.tabLabel),
+      p_active: input.active === true,
+      p_updated_by_email: String(input.actorEmail || "")
+    }));
+  }
+
   async function setProjectArchived(input) {
     return dataOrThrow(await client.rpc("set_somi_project_archived", {
       p_project_id: String(input.projectId || ""),
@@ -345,6 +358,7 @@ function createSupabaseGateway(client, options = {}) {
     createCheckpoint,
     restoreCheckpoint,
     saveInstance,
+    setComponentActive,
     setProjectArchived,
     setCatalogDemoProject,
     createScaffoldProject,

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

@@ -14,6 +14,8 @@ const {
   validateProjectImportPlanForApply,
   validateProjectStatusPlanForApply,
   validateCatalogDemoPlanForApply,
+  validateComponentActivePlanForApply,
+  validateComponentAddPlanForApply,
   validateComponentPlanForApply,
   validateAssetPlanForApply,
   validateCheckpointPlanForApply,
@@ -346,6 +348,170 @@ async function verifyAutomaticCheckpoint(gateway, plan, rpcResponse, validated,
   return checkpoint;
 }
 
+async function applyComponentAddPlan(gateway, plan, actorEmail, options = {}) {
+  const before = await loadValidated(gateway, plan.project.id, plan.versionNumber);
+  validateComponentAddPlanForApply(plan, before, actorEmail);
+  let response;
+  try {
+    response = await gateway.setComponentActive({
+      projectId: before.project.id,
+      versionNumber: before.versionNumber,
+      expectedSetRevision: before.componentSet.revision,
+      templateId: plan.target.templateId,
+      instanceId: plan.target.instanceId,
+      tabLabel: plan.target.tabLabel,
+      active: true,
+      actorEmail
+    });
+  } catch (error) {
+    const normalized = normalizeError(error);
+    if (["E_CONFLICT", "E_AUTHORIZATION", "E_VALIDATION", "E_CODE_CHANGE_REQUIRED"].includes(normalized.code)) throw normalized;
+    let observed = null;
+    try {
+      const current = await gateway.loadVersion(plan.project.id, plan.versionNumber);
+      const row = current.componentRows.find(item => String(item.instance_id) === String(plan.target.instanceId));
+      if (row) observed = {
+        instanceId: String(row.instance_id),
+        templateId: String(row.template_id),
+        active: row.is_enabled === true && row.is_archived !== true,
+        revision: Number(row.revision),
+        componentSetRevision: Number(current.componentSet?.revision || 0)
+      };
+    } catch (readError) { void readError; }
+    throw cliError("E_AMBIGUOUS_SAVE", "Component 추가 요청의 결과를 확정할 수 없습니다. 같은 plan을 재적용하지 말고 Component 원본을 확인해 주세요.", {
+      requestErrorCode: normalized.code,
+      ...(observed ? { observed } : {})
+    }, normalized);
+  }
+
+  let after;
+  try { after = await loadValidated(gateway, plan.project.id, plan.versionNumber); }
+  catch (error) {
+    throw cliError("E_AMBIGUOUS_SAVE", "Component 추가 후 활성 구성을 다시 읽고 검증할 수 없습니다. 같은 plan을 재적용하지 마세요.", null, error);
+  }
+  const row = rpcRow(response);
+  const instance = findInstance(after, plan.target.instanceId);
+  const view = after.views.find(item => item.viewInstanceId === plan.composition.viewInstanceId);
+  const actualBindings = view?.bindings.map(binding => ({
+    key: binding.key,
+    dataInstanceId: binding.dataInstanceId,
+    accessMode: binding.accessMode,
+    required: binding.required
+  })) || [];
+  const responseMatches = String(row?.saved_instance_id || "") === instance.instanceId
+    && Number(row?.saved_instance_revision) === instance.revision
+    && Number(row?.saved_set_revision) === Number(after.componentSet.revision)
+    && String(row?.saved_component_checksum || "") === String(after.componentSet.component_checksum || "")
+    && row?.is_active === true;
+  const componentMatches = instance.templateId === plan.target.templateId
+    && instance.tab === plan.target.tabLabel
+    && equalJson(instance.data, plan.initialData)
+    && instance.enabled === true
+    && instance.archived === false
+    && instance.required === false
+    && instance.removable === true;
+  const compositionMatches = view
+    && view.templateId === plan.composition.viewTemplateId
+    && view.label === plan.composition.label
+    && view.rendererId === plan.composition.rendererId
+    && equalJson(view.modes, plan.composition.modes)
+    && equalJson(actualBindings, plan.composition.bindings);
+  if (!responseMatches || !componentMatches || !compositionMatches
+    || Number(after.componentSet.revision) <= Number(before.componentSet.revision)) {
+    throw cliError("E_AMBIGUOUS_SAVE", "Component 추가 RPC 응답과 authoritative Data/View/binding read-back이 일치하지 않습니다. 같은 plan을 재적용하지 마세요.");
+  }
+  return Object.freeze({
+    ...receiptBase(plan, actorEmail, options),
+    target: clone(plan.target),
+    initialDataHash: plan.initialDataHash,
+    component: {
+      instanceId: instance.instanceId,
+      templateId: instance.templateId,
+      tabLabel: instance.tab,
+      revision: instance.revision
+    },
+    composition: clone(plan.composition),
+    componentSetRevision: Number(after.componentSet.revision),
+    componentChecksum: String(after.componentSet.component_checksum),
+    recoveredFromAmbiguousResponse: false
+  });
+}
+
+async function applyComponentActivePlan(gateway, plan, actorEmail, options = {}) {
+  const before = await loadValidated(gateway, plan.project.id, plan.versionNumber);
+  validateComponentActivePlanForApply(plan, before, actorEmail);
+  let response;
+  try {
+    response = await gateway.setComponentActive({
+      projectId: before.project.id,
+      versionNumber: before.versionNumber,
+      expectedSetRevision: before.componentSet.revision,
+      templateId: plan.target.templateId,
+      instanceId: plan.target.instanceId,
+      tabLabel: plan.target.tabLabel,
+      active: plan.target.active,
+      actorEmail
+    });
+  } catch (error) {
+    const normalized = normalizeError(error);
+    if (["E_CONFLICT", "E_AUTHORIZATION", "E_VALIDATION", "E_CODE_CHANGE_REQUIRED"].includes(normalized.code)) throw normalized;
+    throw cliError("E_AMBIGUOUS_SAVE", "Component 사용 여부 변경 결과를 확정할 수 없습니다. 같은 plan을 재적용하지 말고 Component 원본을 확인해 주세요.", {
+      requestErrorCode: normalized.code
+    }, normalized);
+  }
+
+  let after;
+  try { after = await loadValidated(gateway, plan.project.id, plan.versionNumber); }
+  catch (error) {
+    throw cliError("E_AMBIGUOUS_SAVE", "Component 사용 여부 변경 후 활성 구성을 다시 읽고 검증할 수 없습니다. 같은 plan을 재적용하지 마세요.", null, error);
+  }
+  const row = rpcRow(response);
+  const storedRow = after.componentRows.find(item => String(item.instance_id) === plan.target.instanceId);
+  const activeInstance = after.instances.find(item => item.instanceId === plan.target.instanceId) || null;
+  const view = after.views.find(item => item.viewInstanceId === plan.composition.viewInstanceId) || null;
+  const actualBindings = view?.bindings.map(binding => ({
+    key: binding.key,
+    dataInstanceId: binding.dataInstanceId,
+    accessMode: binding.accessMode,
+    required: binding.required
+  })) || [];
+  const dataPreserved = storedRow && sha256(storedRow.data) === plan.target.expectedDataHash
+    && Number(storedRow.revision) === Number(plan.target.expectedRevision);
+  const responseMatches = String(row?.saved_instance_id || "") === plan.target.instanceId
+    && Number(row?.saved_instance_revision) === Number(plan.target.expectedRevision)
+    && Number(row?.saved_set_revision) === Number(after.componentSet.revision)
+    && String(row?.saved_component_checksum || "") === String(after.componentSet.component_checksum || "")
+    && row?.is_active === plan.target.active;
+  const stateMatches = plan.target.active
+    ? activeInstance && storedRow.is_enabled === true && storedRow.is_archived === false && view
+      && view.templateId === plan.composition.viewTemplateId
+      && view.label === plan.composition.label
+      && view.rendererId === plan.composition.rendererId
+      && equalJson(view.modes, plan.composition.modes)
+      && equalJson(actualBindings, plan.composition.bindings)
+    : !activeInstance && storedRow?.is_enabled === false && storedRow?.is_archived === true && !view;
+  if (!dataPreserved || !responseMatches || !stateMatches
+    || Number(after.componentSet.revision) <= Number(before.componentSet.revision)) {
+    throw cliError("E_AMBIGUOUS_SAVE", "Component 사용 여부 RPC 응답과 authoritative Data/View/binding read-back이 일치하지 않습니다. 같은 plan을 재적용하지 마세요.");
+  }
+  return Object.freeze({
+    ...receiptBase(plan, actorEmail, options),
+    target: clone(plan.target),
+    component: {
+      instanceId: plan.target.instanceId,
+      templateId: plan.target.templateId,
+      tabLabel: plan.target.tabLabel,
+      revision: Number(storedRow.revision),
+      active: plan.target.active,
+      archived: !plan.target.active,
+      dataHash: sha256(storedRow.data)
+    },
+    componentSetRevision: Number(after.componentSet.revision),
+    componentChecksum: String(after.componentSet.component_checksum),
+    recoveredFromAmbiguousResponse: false
+  });
+}
+
 async function applyComponentPlan(gateway, plan, actorEmail, options = {}) {
   const before = await loadValidated(gateway, plan.project.id, plan.versionNumber);
   const prepared = validateComponentPlanForApply(plan, before, actorEmail);
@@ -719,4 +885,4 @@ async function applyAssetPlan(gateway, plan, actorEmail, options = {}) {
   });
 }
 
-module.exports = Object.freeze({ applyProjectCreationPlan, applyProjectImportPlan, applyProjectStatusPlan, applyCatalogDemoPlan, applyComponentPlan, applyAssetPlan, applyCheckpointPlan, comparePlannedFile, assetPathPrefix });
+module.exports = Object.freeze({ applyProjectCreationPlan, applyProjectImportPlan, applyProjectStatusPlan, applyCatalogDemoPlan, applyComponentActivePlan, applyComponentAddPlan, applyComponentPlan, applyAssetPlan, applyCheckpointPlan, comparePlannedFile, assetPathPrefix });