@mawaru/sdk 0.5.0 → 0.8.0

package/_schemas/port-spec.ts

@@ -5,17 +5,21 @@ import type { GraphPort, JsonSchema, PortIo } from "./node.js"
 // 型の決まり方は3分類：宣言（program / AI の in・out）／固定（human reject の
 // content 型）／導出（それ以外。接続元から伝播し、結果は ports.schema にキャッシュする）
 
-// content 型・未接続の導出ポートは any（{}）で表す。content の意味（エンジンが
-// content に変換して注入する口）はスキーマではなく kind が決める
-export const ANY_SCHEMA: JsonSchema = {}
+// 「まだ型が決まっていない」＝未宣言を {} で表す（未接続・上流が未宣言・fan-in の型割れ）。
+// 「何でも受ける」型は存在しない：AI の in は接続元の具体型を鏡映し、差し戻しの指示は
+// instruction ポートの宣言型を持つ（docs/tasks/wip/ポートスキーマのany撲滅.md）
+export const UNDECLARED_SCHEMA: JsonSchema = {}
 
-export const isAnySchema = (schema: JsonSchema): boolean =>
+export const isUndeclaredSchema = (schema: JsonSchema): boolean =>
   Object.keys(schema).length === 0 || schema.type === undefined
 
-// ---- file 型（AI ノードのファイル入力。docs/tasks/wip/AIノードのファイル入力（file型と添付）.md） ----
+// ---- file 型（docs/tasks/done/AIノードのファイル入力（file型と添付）.md） ----
 // schema 上の file は x-mawaru-type マーカー付きの object（nominal に識別する）。値はバイト
-// ではなく storage path の参照（url は startAiStep の dispatch 時に発行して client_payload に
-// のみ載せる）。ajv は strict:false で未知キーワードを無視するので検証は素の JSON Schema のまま。
+// ではなく storage path の参照で、署名 URL はどこにも焼き込まない。
+// **file の位置は名前ではなくこのマーカーで決まる**：runner が宣言スキーマと値を並行走査して
+// 入力はワークスペースへ materialize（パスに置換）、出力はアップロード（参照に置換）する
+// （docs/tasks/wip/ポートスキーマ編集でファイル型を選べるようにする.md）。
+// ajv は strict:false で未知キーワードを無視するので検証は素の JSON Schema のまま。
 export const FILE_SCHEMA_MARKER = "x-mawaru-type"
 export const FILE_SCHEMA_TYPE = "file"
 
@@ -34,6 +38,27 @@ export const fileSchema = (): JsonSchema => ({
 export const isFileSchema = (schema: JsonSchema): boolean =>
   schema[FILE_SCHEMA_MARKER] === FILE_SCHEMA_TYPE
 
+// ---- 差し戻しの指示（AI の instruction ポート / human の reject ポート） ----
+// AI 入力の既存エンベロープ { prompt, files } と同じ形にする。配管が効く根拠は
+// files が file 型として宣言されていることであって、キー名ではない
+// （runner がマーカーで位置を見つけて materialize する）。
+// スクリーンショットを添えて差し戻すケースがあるので文章だけにしない
+// （docs/tasks/wip/ポートスキーマのany撲滅.md）
+export const AI_INSTRUCTION_PORT_KEY = "instruction"
+
+export const instructionSchema = (): JsonSchema => ({
+  type: "object",
+  properties: {
+    prompt: { type: "string", description: "差し戻しの理由（AI への指示）" },
+    files: {
+      type: "array",
+      items: fileSchema(),
+      description: "スクリーンショットなどの参考資料",
+    },
+  },
+  required: ["prompt"],
+})
+
 // ---- データフォーマットカタログ ----
 // human 承認 UI の表示・編集フォームの出し分けに使う（テキスト＝string（markdown）／
 // リスト＝Array<Row>（列定義つき））。バリデーションには使わない（data は任意の型）
@@ -154,10 +179,42 @@ const FIXED_PORT_KEYS: Record<string, { in: string[]; out: string[] }> = {
   wait: { in: ["in"], out: ["main"] },
   // start は in 1つ（run 入力契約）＋ out main 1つの恒等パススルー
   start: { in: ["in"], out: ["main"] },
+  // component は in（子 loop の start.in 契約）＋ out main（end.out の戻り値）。
+  // スキーマは保存時にサーバが子 loop の契約から焼き込む宣言型
+  // （DERIVED/MIRROR には入れない＝接続で潰さない）
+  component: { in: ["in"], out: ["main"] },
 }
 
 const FREE_OUT_KINDS = new Set(["program", "ai"])
 
+// out は自由（複数出口＝分岐）だが in の構成は固定。ai は上流データを受ける in と、
+// 差し戻しの指示を受ける instruction の2口（意味の違う入力を1つのポートに
+// fan-in させない。docs/tasks/wip/ポートスキーマのany撲滅.md）
+const FIXED_IN_KEYS: Record<string, string[]> = {
+  program: ["in"],
+  ai: ["in", AI_INSTRUCTION_PORT_KEY],
+}
+
+export const fixedInKeysOf = (kind: string): string[] | null =>
+  FIXED_IN_KEYS[kind] ?? null
+
+// config.json（manifest）の inputs 検査（適合なら null）。同じルールを二重に持たないため
+// manifest 側はここを参照する（docs/tasks/wip/manifestのin複数対応（instructionポート）.md）。
+// **必須は "in" だけ**で、kind が固定する他の in（ai の instruction）は任意：スキーマは
+// constSchemaOf が焼き込む固定型なのでエディタ側で補え、in を2口に分ける前に同期された
+// config.json もそのまま読める
+export const manifestInKeysViolation = (
+  kind: string,
+  keys: string[],
+): string | null => {
+  const allowed = fixedInKeysOf(kind) ?? ["in"]
+  if (!keys.includes("in")) return 'inputs は "in" を宣言してください'
+  const unknown = keys.filter((key) => !allowed.includes(key))
+  return unknown.length > 0
+    ? `inputs に宣言できない key があります: ${unknown.join(" / ")}（${allowed.join(" / ")} のみ）`
+    : null
+}
+
 // kind 別のポート構成違反を返す（適合なら null）。in=1/out>=1 の構造ルールは
 // graph.ts 側の既存チェックが担い、ここは key の固定だけ見る
 export const kindPortsViolation = (
@@ -178,12 +235,17 @@ export const kindPortsViolation = (
   }
   const fixed = FIXED_PORT_KEYS[kind]
   if (!fixed) {
-    // program / ai（自由 out）：in の key だけ "in" 固定
-    if (
-      FREE_OUT_KINDS.has(kind) &&
-      ports.some((p) => p.io === "in" && p.key !== "in")
-    )
-      return `${kind} の in ポートの key は "in" です`
+    // program / ai（自由 out）：in の構成だけ固定
+    const expectIn = FIXED_IN_KEYS[kind]
+    if (FREE_OUT_KINDS.has(kind) && expectIn) {
+      const inKeys = ports
+        .filter((p) => p.io === "in")
+        .map((p) => p.key)
+        .sort()
+      if (inKeys.join(",") !== [...expectIn].sort().join(",")) {
+        return `${kind} の in ポートは ${expectIn.join(" / ")} です`
+      }
+    }
     return null
   }
   const keysOf = (io: PortIo) =>
@@ -205,11 +267,34 @@ export const kindPortsViolation = (
 // 接続の両端は同じスキーマになる（値入力フォームのSchemaForm統一.md）。
 // wait / human は素通し（パラメトリック）ノード：in は接続元の out、out は in と同型。
 // 例外は human の approve：接続元が AI ノードのときだけ封筒を剥がして data 型になる。
-// human の reject は content 固定（any）。宣言 out（program / ai）は触らない。
+// human の reject は未宣言のまま（段階2 で instruction エンベロープを宣言する）。
+// 宣言 out（program / ai）は触らない。
 // program / ai の in は接続鏡映（sticky）：接続元 out が具体型のときだけ上書きし、
-// 未接続・fan-in・any は現スキーマ（宣言）を維持する（鏡映結果は repo の config.json
+// 未接続・型割れ・未宣言は現スキーマ（宣言）を維持する（鏡映結果は repo の config.json
 // へも書き戻される。docs/tasks/wip/ポート編集のrepo書き戻し同期.md）
 
+// 複数の流入（fan-in）から型を1つに決める：未宣言を除いて具体型が1種類ならその型、
+// 0種類なら未宣言。2種類以上は型が割れているので未宣言に落とす
+// （保存時に graph.ts が 422 で弾く。伝播は止めずに固定点へ収束させる）
+export const mergeInboundSchemas = (schemas: JsonSchema[]): JsonSchema => {
+  const uniq = [
+    ...new Set(
+      schemas
+        .filter((s) => !isUndeclaredSchema(s))
+        .map((s) => JSON.stringify(s)),
+    ),
+  ]
+  return uniq.length === 1 && uniq[0] !== undefined
+    ? (JSON.parse(uniq[0]) as JsonSchema)
+    : UNDECLARED_SCHEMA
+}
+
+// 流入の具体型が2種類以上あるか（＝同じポートに違う型を流し込んでいる）
+export const hasInboundConflict = (schemas: JsonSchema[]): boolean =>
+  new Set(
+    schemas.filter((s) => !isUndeclaredSchema(s)).map((s) => JSON.stringify(s)),
+  ).size > 1
+
 type PropagationNode = {
   id: string
   kind: string
@@ -217,8 +302,8 @@ type PropagationNode = {
 }
 type PortLink = { from_port_id: string; to_port_id: string }
 
-// end も導出ノード（各 in は上流から、out main は any）。個別処理は
-// resolvePortSchemas 内で行うが、初期スキーマを any にするためここに含める。
+// end も導出ノード（各 in は上流から、out main は未宣言）。個別処理は
+// resolvePortSchemas 内で行うが、初期スキーマを未宣言にするためここに含める。
 // start も導出ノード：out main は接続先の in から逆向きに転写し、in は out と同型
 // （run 入力契約＝接続先の入力宣言。開始ノードの入力契約を接続先から導出.md）
 const DERIVED_KINDS = new Set(["wait", "human", "end", "start"])
@@ -233,11 +318,27 @@ const isDerivedPort = (kind: string, port: Pick<GraphPort, "io" | "key">) =>
 // AI の in は nodes/ai/<dir>/config.json の inputs.in 由来の宣言型が初期値で、
 // 接続時は program と同じ鏡映で接続元と同値に同期される（const 扱い廃止。
 // 接続バリデーションの「ai の in は常に許可」は維持）
-const isConstPort = (kind: string, port: Pick<GraphPort, "io" | "key">) =>
-  kind === "human" && port.io === "out" && port.key === "reject"
+// 宣言型で固定されるポート（導出も鏡映もしない）。差し戻しの指示エンベロープを
+// human の出口と AI の入口の両方に焼き込むことで、両端が同じ具体型で一致する
+const constSchemaOf = (
+  kind: string,
+  port: Pick<GraphPort, "io" | "key">,
+): JsonSchema | null => {
+  if (kind === "human" && port.io === "out" && port.key === "reject") {
+    return instructionSchema()
+  }
+  if (
+    kind === "ai" &&
+    port.io === "in" &&
+    port.key === AI_INSTRUCTION_PORT_KEY
+  ) {
+    return instructionSchema()
+  }
+  return null
+}
 
 // port_id → 解決済みスキーマ。導出は接続を遡って固定点まで反復し、
-// 未接続・複数流入・純パラメトリック閉路は any に落とす（MVP の割り切り）
+// 未接続・純パラメトリック閉路・fan-in の型割れは未宣言に落とす
 export const resolvePortSchemas = <N extends PropagationNode>(
   nodes: N[],
   connections: PortLink[],
@@ -247,11 +348,11 @@ export const resolvePortSchemas = <N extends PropagationNode>(
   for (const node of nodes) {
     for (const port of node.ports) {
       kindByPortId.set(port.id, node.kind)
+      const constSchema = constSchemaOf(node.kind, port)
       resolved.set(
         port.id,
-        isDerivedPort(node.kind, port) || isConstPort(node.kind, port)
-          ? ANY_SCHEMA
-          : port.schema,
+        constSchema ??
+          (isDerivedPort(node.kind, port) ? UNDECLARED_SCHEMA : port.schema),
       )
     }
   }
@@ -278,7 +379,7 @@ export const resolvePortSchemas = <N extends PropagationNode>(
         }
       }
       // start：out main は接続先 in の解決値を転写（逆向き導出）。fan-out は
-      // 非 any が1種類（JSON 等値）のときだけ採用し、未接続・型割れは any。
+      // 非未宣言が1種類（JSON 等値）のときだけ採用し、未接続・型割れは未宣言。
       // in は out main と同型（恒等の向きを out→in に逆転。run 入力契約は
       // 接続先の入力宣言から自動で決まる）
       if (node.kind === "start") {
@@ -287,47 +388,43 @@ export const resolvePortSchemas = <N extends PropagationNode>(
           (p) => p.io === "out" && p.key === "main",
         )
         if (inPort && outMain) {
-          const targets = (outbound.get(outMain.id) ?? [])
-            .map((id) => resolved.get(id) ?? ANY_SCHEMA)
-            .filter((s) => !isAnySchema(s))
-            .map((s) => JSON.stringify(s))
-          const uniq = [...new Set(targets)]
-          const schema =
-            uniq.length === 1 && uniq[0] !== undefined
-              ? (JSON.parse(uniq[0]) as JsonSchema)
-              : ANY_SCHEMA
+          const schema = mergeInboundSchemas(
+            (outbound.get(outMain.id) ?? []).map(
+              (id) => resolved.get(id) ?? UNDECLARED_SCHEMA,
+            ),
+          )
           assign(outMain.id, schema)
           assign(inPort.id, schema)
         }
         continue
       }
       // end：各 in を自分の単一上流から導出（複数ルートを別 in で集約）。
-      // out main は any 固定（ルートごとに型が違いうる。Loop-in-Loop で詰める）
+      // out main は未宣言固定（ルートごとに型が違いうる。Loop-in-Loop で詰める）
       if (node.kind === "end") {
         for (const port of node.ports) {
           if (port.io !== "in") continue
           const srcs = inbound.get(port.id) ?? []
           assign(
             port.id,
-            srcs.length === 1 && srcs[0] !== undefined
-              ? (resolved.get(srcs[0]) ?? ANY_SCHEMA)
-              : ANY_SCHEMA,
+            mergeInboundSchemas(
+              srcs.map((id) => resolved.get(id) ?? UNDECLARED_SCHEMA),
+            ),
           )
         }
         continue
       }
       const isMirror = MIRROR_KINDS.has(node.kind)
       if (!DERIVED_KINDS.has(node.kind) && !isMirror) continue
-      const inPort = node.ports.find((p) => p.io === "in")
+      // ai は in が2口あるので、上流データの口（key="in"）だけを鏡映・導出の対象にする
+      const inPort = node.ports.find((p) => p.io === "in" && p.key === "in")
       if (!inPort) continue
       const sources = inbound.get(inPort.id) ?? []
-      const inSchema =
-        sources.length === 1 && sources[0] !== undefined
-          ? (resolved.get(sources[0]) ?? ANY_SCHEMA)
-          : ANY_SCHEMA
-      // 鏡映（program）は具体型が流れてきたときだけ上書き（宣言を any で潰さない）
+      const inSchema = mergeInboundSchemas(
+        sources.map((id) => resolved.get(id) ?? UNDECLARED_SCHEMA),
+      )
+      // 鏡映（program / ai）は具体型が流れてきたときだけ上書き（宣言を未宣言で潰さない）
       if (isMirror) {
-        if (!isAnySchema(inSchema)) assign(inPort.id, inSchema)
+        if (!isUndeclaredSchema(inSchema)) assign(inPort.id, inSchema)
         continue
       }
       assign(inPort.id, inSchema)
@@ -342,7 +439,7 @@ export const resolvePortSchemas = <N extends PropagationNode>(
           assign(
             port.id,
             node.kind === "human" && port.key === "approve" && fromAiNode
-              ? (envelopeDataSchemaOf(inSchema) ?? ANY_SCHEMA)
+              ? (envelopeDataSchemaOf(inSchema) ?? UNDECLARED_SCHEMA)
               : inSchema,
           )
         }
@@ -373,33 +470,43 @@ export const propagateDerivedPorts = <N extends PropagationNode>(
 }
 
 // ---- 接続バリデーション（伝播型 ⊆ 宣言スキーマ） ----
-// 完全な JSON Schema 包含ではなく実用的な構造チェック：any は素通し、type 一致、
-// object は宣言側 required の存在と型互換、array は items 互換
+// 完全な JSON Schema 包含ではなく実用的な構造チェック：type 一致、
+// object は宣言側 required の存在と型互換、array は items 互換。
+// どちらかが未宣言なら「適合」でも「不適合」でもなく unknown（判断できない）を返す。
+// 保存時の接続チェックは unknown を通し、承認ビューの候補絞り込みは unknown を弾く
+
+export type SchemaFit = "ok" | "mismatch" | "unknown"
 
-export const isSchemaSubset = (sub: JsonSchema, sup: JsonSchema): boolean => {
-  if (isAnySchema(sup) || isAnySchema(sub)) return true
-  // file は nominal：マーカー一致の file 同士だけ可（file → any は上の any 判定で許可）。
+export const schemaFit = (sub: JsonSchema, sup: JsonSchema): SchemaFit => {
+  if (isUndeclaredSchema(sup) || isUndeclaredSchema(sub)) return "unknown"
+  // file は nominal：マーカー一致の file 同士だけ可。
   // 構造が同じだけの普通の object は file に繋がない／file は普通の object に繋がない
   if (isFileSchema(sub) || isFileSchema(sup))
-    return isFileSchema(sub) && isFileSchema(sup)
-  if (sub.type !== sup.type) return false
+    return isFileSchema(sub) && isFileSchema(sup) ? "ok" : "mismatch"
+  if (sub.type !== sup.type) return "mismatch"
   if (sup.type === "object") {
     const subProps = (sub.properties ?? {}) as Record<string, JsonSchema>
     const subRequired = (sub.required ?? []) as string[]
     const supProps = (sup.properties ?? {}) as Record<string, JsonSchema>
     for (const key of (sup.required ?? []) as string[]) {
       const subProp = subProps[key]
-      if (!subProp || !subRequired.includes(key)) return false
+      if (!subProp || !subRequired.includes(key)) return "mismatch"
       const supProp = supProps[key]
-      if (supProp && !isSchemaSubset(subProp, supProp)) return false
+      // ネストは「不適合でなければよい」（未宣言のプロパティで親を落とさない）
+      if (supProp && schemaFit(subProp, supProp) === "mismatch")
+        return "mismatch"
     }
-    return true
+    return "ok"
   }
   if (sup.type === "array") {
     const supItems = sup.items as JsonSchema | undefined
     const subItems = sub.items as JsonSchema | undefined
-    if (!supItems || !subItems) return true
-    return isSchemaSubset(subItems, supItems)
+    if (!supItems || !subItems) return "ok"
+    return schemaFit(subItems, supItems) === "mismatch" ? "mismatch" : "ok"
   }
-  return true
+  return "ok"
 }
+
+// 保存時の接続チェック用：判断できない（未宣言）ものは通す
+export const isSchemaSubset = (sub: JsonSchema, sup: JsonSchema): boolean =>
+  schemaFit(sub, sup) !== "mismatch"

package/_schemas/program-manifest.ts

@@ -1,5 +1,6 @@
 import { z } from "zod"
 import { jsonSchemaSchema, portKeySchema } from "./node.js"
+import { manifestInKeysViolation } from "./port-spec.js"
 
 // nodes/program/<dir>/config.json（リポジトリ規約 v2）。プログラム自身が入出力スキーマを宣言し、
 // エディタが取り込んで ports を自動生成する（実行時の正は ports テーブルのまま。
@@ -23,14 +24,14 @@ export const programManifestSchema = z
     refs: z.record(portKeySchema, jsonSchemaSchema).default({}),
   })
   .superRefine((manifest, ctx) => {
-    // グラフ側の既存制約（in ポートちょうど1つ・key "in" 固定）に整合させる
-    const inKeys = Object.keys(manifest.inputs)
-    if (inKeys.length !== 1 || inKeys[0] !== "in") {
-      ctx.addIssue({
-        code: "custom",
-        path: ["inputs"],
-        message: 'inputs は "in" の1件だけ宣言してください（join 導入まで）',
-      })
+    // in の構成は kind が固定する（program は "in" の1口）。ルールの正は
+    // port-spec 側で、ここは参照するだけ
+    const inViolation = manifestInKeysViolation(
+      "program",
+      Object.keys(manifest.inputs),
+    )
+    if (inViolation) {
+      ctx.addIssue({ code: "custom", path: ["inputs"], message: inViolation })
     }
     if (Object.keys(manifest.outputs).length < 1) {
       ctx.addIssue({

package/dist/_schemas/ai-manifest.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { jsonSchemaSchema } from "./node.js";
-import { isAiEnvelopeSchema } from "./port-spec.js";
+import { isAiEnvelopeSchema, manifestInKeysViolation } from "./port-spec.js";
 // AI ノードのモデル選択肢（既定は Opus：下書き品質が価値の中心。費用はユーザー持ち）
 export const AI_MODELS = [
     "claude-opus-4-8",
@@ -35,14 +35,11 @@ export const aiManifestSchema = z
     outputs: z.record(z.string(), jsonSchemaSchema),
 })
     .superRefine((manifest, ctx) => {
-    // グラフ側の既存制約（in ちょうど1つ・key "in"）に整合させる
-    const inKeys = Object.keys(manifest.inputs);
-    if (inKeys.length !== 1 || inKeys[0] !== "in") {
-        ctx.addIssue({
-            code: "custom",
-            path: ["inputs"],
-            message: 'inputs は "in" の1件だけ宣言してください（join 導入まで）',
-        });
+    // in の構成は kind が固定する（ai は上流データの in ＋ 差し戻しの instruction の2口）。
+    // ルールの正は port-spec 側で、ここは参照するだけ
+    const inViolation = manifestInKeysViolation("ai", Object.keys(manifest.inputs));
+    if (inViolation) {
+        ctx.addIssue({ code: "custom", path: ["inputs"], message: inViolation });
     }
     // outputs は1件以上・key 自由（複数出口＝分岐。AIノードの複数出口（分岐）.md）
     if (Object.keys(manifest.outputs).length < 1) {

package/dist/_schemas/extract-component.d.ts

@@ -0,0 +1,35 @@
+import type { GraphConnection, GraphNode } from "./graph.js";
+export type ExtractAnalysis = {
+    ok: false;
+    reason: string;
+} | {
+    ok: true;
+    entryNodeId: string | null;
+    exitPortId: string | null;
+    internal: GraphConnection[];
+    inbound: GraphConnection[];
+    outbound: GraphConnection[];
+};
+export declare const analyzeExtractSelection: (nodes: GraphNode[], connections: GraphConnection[], selectedIds: readonly string[]) => ExtractAnalysis;
+export type ExtractPlan = {
+    childNodes: GraphNode[];
+    childConnections: GraphConnection[];
+    groupNode: GraphNode;
+    parentNodes: GraphNode[];
+    parentConnections: GraphConnection[];
+};
+export declare const buildExtractPlan: (params: {
+    nodes: GraphNode[];
+    connections: GraphConnection[];
+    selectedIds: string[];
+    name: string;
+    componentLoopId: string;
+    childStartOutPortId: string;
+    childEndInPortId: string;
+    newId: () => string;
+}) => {
+    ok: false;
+    reason: string;
+} | ({
+    ok: true;
+} & ExtractPlan);

package/dist/_schemas/extract-component.js

@@ -0,0 +1,146 @@
+export const analyzeExtractSelection = (nodes, connections, selectedIds) => {
+    const selected = new Set(selectedIds);
+    if (selected.size < 2) {
+        return { ok: false, reason: "2つ以上のノードを選択してください" };
+    }
+    const selectedNodes = nodes.filter((n) => selected.has(n.id));
+    const flow = selectedNodes.find((n) => n.kind === "start" || n.kind === "end");
+    if (flow) {
+        return {
+            ok: false,
+            reason: "開始・終了ノードはグループ化できません",
+        };
+    }
+    const nodeIdByPortId = new Map(nodes.flatMap((n) => n.ports.map((p) => [p.id, n.id])));
+    const internal = [];
+    const inbound = [];
+    const outbound = [];
+    for (const conn of connections) {
+        const fromIn = selected.has(nodeIdByPortId.get(conn.from_port_id) ?? "");
+        const toIn = selected.has(nodeIdByPortId.get(conn.to_port_id) ?? "");
+        if (fromIn && toIn)
+            internal.push(conn);
+        else if (!fromIn && toIn)
+            inbound.push(conn);
+        else if (fromIn && !toIn)
+            outbound.push(conn);
+    }
+    const entryNodeIds = new Set(inbound.map((c) => nodeIdByPortId.get(c.to_port_id) ?? ""));
+    if (entryNodeIds.size > 1) {
+        return {
+            ok: false,
+            reason: "外部からの入力が複数のノードに入っています（入口は1つにしてください）",
+        };
+    }
+    const exitPortIds = new Set(outbound.map((c) => c.from_port_id));
+    if (exitPortIds.size > 1) {
+        return {
+            ok: false,
+            reason: "外部への出力が複数のポートから出ています（出口は1つにしてください）",
+        };
+    }
+    return {
+        ok: true,
+        entryNodeId: [...entryNodeIds][0] ?? null,
+        exitPortId: [...exitPortIds][0] ?? null,
+        internal,
+        inbound,
+        outbound,
+    };
+};
+export const buildExtractPlan = (params) => {
+    const { nodes, connections, selectedIds, name, componentLoopId, childStartOutPortId, childEndInPortId, newId, } = params;
+    const analysis = analyzeExtractSelection(nodes, connections, selectedIds);
+    if (!analysis.ok)
+        return analysis;
+    const selected = new Set(selectedIds);
+    // ノード・ポートとも新 id を採番してコピー（kind 別設定・hooks は共有参照で問題ない
+    // ＝この後 JSON 化して保存 API に渡すだけで、エディタ状態には子側を持たない）
+    const nodeIdMap = new Map();
+    const portIdMap = new Map();
+    const childNodes = nodes
+        .filter((n) => selected.has(n.id))
+        .map((n) => {
+        const id = newId();
+        nodeIdMap.set(n.id, id);
+        return {
+            ...n,
+            id,
+            ports: n.ports.map((p) => {
+                const portId = newId();
+                portIdMap.set(p.id, portId);
+                return { ...p, id: portId };
+            }),
+        };
+    });
+    const mapConn = (conn) => ({
+        from_port_id: portIdMap.get(conn.from_port_id) ?? conn.from_port_id,
+        to_port_id: portIdMap.get(conn.to_port_id) ?? conn.to_port_id,
+    });
+    const childConnections = analysis.internal.map(mapConn);
+    // 境界の配線：start.main → 入口ノードの in／出口ポート → end.in
+    if (analysis.entryNodeId !== null) {
+        const entry = childNodes.find((n) => n.id === nodeIdMap.get(analysis.entryNodeId ?? ""));
+        const entryIn = entry?.ports.find((p) => p.io === "in");
+        if (entryIn) {
+            childConnections.push({
+                from_port_id: childStartOutPortId,
+                to_port_id: entryIn.id,
+            });
+        }
+    }
+    if (analysis.exitPortId !== null) {
+        childConnections.push({
+            from_port_id: portIdMap.get(analysis.exitPortId) ?? analysis.exitPortId,
+            to_port_id: childEndInPortId,
+        });
+    }
+    // 親に置くノード（位置は選択の重心。ポートスキーマは保存時にサーバが契約から焼き込む）
+    const selectedNodes = nodes.filter((n) => selected.has(n.id));
+    const centroid = {
+        x: selectedNodes.reduce((sum, n) => sum + n.position_x, 0) /
+            selectedNodes.length,
+        y: selectedNodes.reduce((sum, n) => sum + n.position_y, 0) /
+            selectedNodes.length,
+    };
+    const groupNode = {
+        id: newId(),
+        kind: "component",
+        name,
+        ports: [
+            { id: newId(), io: "in", key: "in", name: "入力", schema: {} },
+            { id: newId(), io: "out", key: "main", name: "出力", schema: {} },
+        ],
+        hooks: [],
+        position_x: centroid.x,
+        position_y: centroid.y,
+        component: { component_loop_id: componentLoopId },
+    };
+    const groupIn = groupNode.ports.find((p) => p.io === "in");
+    const groupMain = groupNode.ports.find((p) => p.io === "out");
+    if (!groupIn || !groupMain) {
+        return { ok: false, reason: "groupNode のポート生成に失敗しました" };
+    }
+    // 親の置換：選択関連の線（内部・境界）を除き、境界を group の in/main へ繋ぎ直す
+    const removed = new Set([...analysis.internal, ...analysis.inbound, ...analysis.outbound].map((c) => `${c.from_port_id}→${c.to_port_id}`));
+    const parentConnections = [
+        ...connections.filter((c) => !removed.has(`${c.from_port_id}→${c.to_port_id}`)),
+        ...analysis.inbound.map((c) => ({
+            from_port_id: c.from_port_id,
+            to_port_id: groupIn.id,
+        })),
+        ...analysis.outbound.map((c) => ({
+            from_port_id: groupMain.id,
+            to_port_id: c.to_port_id,
+        })),
+    ];
+    const parentNodes = [...nodes.filter((n) => !selected.has(n.id)), groupNode];
+    return {
+        ok: true,
+        childNodes,
+        childConnections,
+        groupNode,
+        parentNodes,
+        parentConnections,
+    };
+};