@mawaru/sdk 0.13.0 → 0.14.1

package/_schemas/ai-manifest.test.ts

@@ -1,8 +1,8 @@
 import { describe, expect, it } from "vitest"
 import { AI_MODELS, aiManifestSchema } from "./ai-manifest.js"
-import { envelopeSchemaOf, instructionSchema } from "./port-spec.js"
+import { instructionSchema } from "./port-spec.js"
 
-const envelope = envelopeSchemaOf({ type: "string" })
+const textOutput = { type: "string" }
 
 const valid = {
   name: "返信下書き",
@@ -11,8 +11,8 @@ const valid = {
   model: "claude-opus-4-8",
   skills: ["answer-faq"],
   env: ["ANTHROPIC_API_KEY"],
-  inputs: { in: {} },
-  outputs: { main: envelope },
+  inputs: { in: { schema: {} } },
+  outputs: { main: textOutput },
 }
 
 describe("aiManifestSchema", () => {
@@ -28,8 +28,8 @@ describe("aiManifestSchema", () => {
   it("name / description / model / skills / env は省略できる（既定値が補われる）", () => {
     const manifest = aiManifestSchema.parse({
       prompt: valid.prompt,
-      inputs: { in: {} },
-      outputs: { main: envelope },
+      inputs: { in: { schema: {} } },
+      outputs: { main: textOutput },
     })
     expect(manifest.name).toBeUndefined()
     expect(manifest.model).toBe("claude-opus-5")
@@ -56,90 +56,85 @@ describe("aiManifestSchema", () => {
     ).toThrow()
   })
 
-  it('inputs は "in" 必須・instruction は任意（kind が固定する2口）', () => {
-    // in は必須
+  it("inputs は key 自由・1件以上（in / instruction の固定構成は廃止）", () => {
+    // 0件は拒否
     expect(() => aiManifestSchema.parse({ ...valid, inputs: {} })).toThrow()
+    // key は自由（旧固定の in / instruction 以外も宣言できる）
     expect(() =>
-      aiManifestSchema.parse({ ...valid, inputs: { data: {} } }),
-    ).toThrow()
-    // 固定ポートの instruction も宣言に載る（ノードの現在の姿を書き出すため）
-    expect(
       aiManifestSchema.parse({
         ...valid,
-        inputs: { in: {}, instruction: instructionSchema() },
-      }).inputs.instruction,
-    ).toEqual(instructionSchema())
-    // in を2口に分ける前に同期された config.json（in だけ）もそのまま読める
+        inputs: { task: { schema: {} }, feedback: { schema: {} } },
+      }),
+    ).not.toThrow()
+    // key はポート key の規則（英小文字始まり・英数字と _）
+    for (const key of ["Bad", "1st", "a-b", ""]) {
+      expect(() =>
+        aiManifestSchema.parse({ ...valid, inputs: { [key]: { schema: {} } } }),
+      ).toThrow()
+    }
+  })
+
+  it("inputs は { schema, resume } の新形式で宣言でき、resume が読める", () => {
+    const parsed = aiManifestSchema.parse({
+      ...valid,
+      inputs: {
+        in: { schema: { type: "object" } },
+        instruction: { schema: instructionSchema(), resume: true },
+      },
+    })
+    expect(parsed.inputs.in).toEqual({ schema: { type: "object" } })
+    expect(parsed.inputs.instruction?.schema).toEqual(instructionSchema())
+    expect(parsed.inputs.instruction?.resume).toBe(true)
+  })
+
+  it("旧形式（値が素の JSON Schema）は { schema: 値 } として読める", () => {
+    const legacy = aiManifestSchema.parse({
+      ...valid,
+      inputs: { in: { type: "object" }, instruction: instructionSchema() },
+    })
+    expect(legacy.inputs.in).toEqual({ schema: { type: "object" } })
+    expect(legacy.inputs.instruction).toEqual({
+      schema: instructionSchema(),
+    })
+    // 未宣言 {} も旧形式として { schema: {} } になる
     expect(
-      Object.keys(
-        aiManifestSchema.parse({ ...valid, inputs: { in: {} } }).inputs,
-      ),
-    ).toEqual(["in"])
-    // kind が固定しない key は宣言できない
-    expect(() =>
-      aiManifestSchema.parse({ ...valid, inputs: { in: {}, extra: {} } }),
-    ).toThrow()
+      aiManifestSchema.parse({ ...valid, inputs: { in: {} } }).inputs.in,
+    ).toEqual({ schema: {} })
   })
 
   it("outputs は1件以上・key 自由（AI の複数出口＝分岐）", () => {
     expect(() => aiManifestSchema.parse({ ...valid, outputs: {} })).toThrow()
     expect(() =>
-      aiManifestSchema.parse({ ...valid, outputs: { reply: envelope } }),
+      aiManifestSchema.parse({ ...valid, outputs: { reply: textOutput } }),
     ).not.toThrow()
     expect(() =>
       aiManifestSchema.parse({
         ...valid,
-        outputs: { spam: envelope, sales: envelope, support: envelope },
+        outputs: { spam: textOutput, sales: textOutput, support: textOutput },
       }),
     ).not.toThrow()
   })
 
-  it("outputs は全出口に封筒型 { data, description } を強制する（data は任意の型）", () => {
+  it("outputs は任意の JSON Schema を受け付ける（形の強制はしない）", () => {
     for (const schema of [
       {}, // any
       { type: "string" },
-      { type: "object", properties: { text: { type: "string" } } }, // data キーなし
-      {
-        type: "object",
-        properties: { data: { type: "string" } }, // description なし
-        required: ["data"],
-      },
+      { type: "object", properties: { text: { type: "string" } } },
+      { type: "array", items: { type: "number" } },
       {
+        // かつて強制していた { data, description } もただの object として valid
         type: "object",
         properties: {
           data: { type: "string" },
-          description: { type: "string" }, // description が optional
+          description: { type: "string" },
         },
-        required: ["data"],
+        required: ["data", "description"],
       },
     ]) {
       expect(() =>
         aiManifestSchema.parse({ ...valid, outputs: { main: schema } }),
-      ).toThrow()
-      // 妥当な出口に混ざっていても、封筒型でない出口があれば弾く
-      expect(() =>
-        aiManifestSchema.parse({
-          ...valid,
-          outputs: { main: envelope, other: schema },
-        }),
-      ).toThrow()
+      ).not.toThrow()
     }
-    // data が任意の構造（カタログ外の object）でも通る
-    expect(() =>
-      aiManifestSchema.parse({
-        ...valid,
-        outputs: {
-          main: envelopeSchemaOf({
-            type: "object",
-            properties: {
-              title: { type: "string" },
-              count: { type: "number" },
-            },
-            required: ["title"],
-          }),
-        },
-      }),
-    ).not.toThrow()
   })
 
   it("ディレクトリ名として不正な skill 名を拒否する", () => {

package/_schemas/ai-manifest.ts

@@ -1,6 +1,5 @@
 import { z } from "zod"
-import { jsonSchemaSchema } from "./node.js"
-import { isAiEnvelopeSchema, manifestInKeysViolation } from "./port-spec.js"
+import { jsonSchemaSchema, PORT_KEY_PATTERN } from "./node.js"
 
 // AI ノードのモデル選択肢（既定は Opus：下書き品質が価値の中心。費用はユーザー持ち）。
 // エイリアス（"opus" 等）は採らずバージョンを固定する：実行のたびに黙って別モデルへ
@@ -15,6 +14,23 @@ export const aiModelSchema = z.enum(AI_MODELS)
 export type AiModel = z.infer<typeof aiModelSchema>
 export const DEFAULT_AI_MODEL = "claude-opus-5" satisfies AiModel
 
+// 入力口の宣言：スキーマ＋実行属性。resume: true の口から入力が届いた実行は
+// 同じノードの直近セッションを復元して再開する（backend が ports.resume へ同期して
+// payload 発行時に参照する。ポート型固定の撤去とセッション再開のポート属性化.md）
+export const aiInputDeclSchema = z.object({
+  schema: jsonSchemaSchema,
+  resume: z.boolean().optional(),
+})
+export type AiInputDecl = z.infer<typeof aiInputDeclSchema>
+
+// 旧形式（値が素の JSON Schema）は { schema: 値 } として読む。判別は「schema キーを
+// 持つか」：JSON Schema のトップレベルに "schema" キーは現れない（メタスキーマ参照は
+// "$schema"）ので実用上一意。書き戻し（backend の syncNodeConfigs）は常に新形式で書く
+const aiInputValueSchema = z.union([
+  aiInputDeclSchema,
+  jsonSchemaSchema.transform((schema): AiInputDecl => ({ schema })),
+])
+
 // nodes/ai/<dir>/config.json（実行repoの構造見直し）。AI ノードの定義（prompt/model/skills/
 // 入出力スキーマ/env）は repo 側が正で、エディタが取り込んで ports を自動生成する
 // （実行時の正は ports テーブルのまま。プログラム規約 v2 と同じ関係）。
@@ -42,38 +58,37 @@ export const aiManifestSchema = z
     // 実行中の経過（発話・ツール呼び出し）を Actions ログへ逐次出すデバッグフラグ。
     // 通常時は config.json にキーを書かない（インスペクタも false ならキーを消す）
     verbose: z.boolean().optional(),
-    inputs: z.record(z.string(), jsonSchemaSchema),
+    inputs: z.record(z.string(), aiInputValueSchema),
     outputs: z.record(z.string(), jsonSchemaSchema),
   })
   .superRefine((manifest, ctx) => {
-    // 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) {
+    // inputs は1件以上・key 自由（in / instruction の固定構成は廃止。
+    // セッション再開は key ではなく resume 属性で決まる）
+    const inKeys = Object.keys(manifest.inputs)
+    if (inKeys.length < 1) {
       ctx.addIssue({
         code: "custom",
-        path: ["outputs"],
-        message: "outputs は1件以上宣言してください",
+        path: ["inputs"],
+        message: "inputs は1件以上宣言してください",
       })
     }
-    // Human 承認 UI が依存する封筒型 { data: T, description: string } を全出口に強制
-    // （どの出口も human に接続できる、という AI ノードの不変条件。saveGraph と同じ判定。
-    // data＝T は任意の JSON Schema）
-    for (const [key, schema] of Object.entries(manifest.outputs)) {
-      if (!isAiEnvelopeSchema(schema)) {
+    for (const key of inKeys) {
+      if (!PORT_KEY_PATTERN.test(key)) {
         ctx.addIssue({
           code: "custom",
-          path: ["outputs", key],
-          message: `outputs.${key} は封筒型 { data, description } で宣言してください（両方必須・description は string）`,
+          path: ["inputs", key],
+          message: `inputs の key が不正です: ${key}（英小文字始まり・英数字と _ のみ）`,
         })
       }
     }
+    // outputs は1件以上・key 自由（複数出口＝分岐。AIノードの複数出口（分岐）.md）。
+    // スキーマは任意の JSON Schema（形の強制はしない）
+    if (Object.keys(manifest.outputs).length < 1) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["outputs"],
+        message: "outputs は1件以上宣言してください",
+      })
+    }
   })
 export type AiManifest = z.infer<typeof aiManifestSchema>

package/_schemas/extract-component.test.ts

@@ -110,10 +110,20 @@ describe("analyzeExtractSelection（境界の分類と V1 制約）", () => {
     expect(ok.ok).toBe(true)
   })
 
-  it("空・1ノードのみ・start/end 含みは拒否する", () => {
+  it("1ノード選択：そのノードが入口、その out が出口になる", () => {
+    const { a, b, c, nodes, connections } = chain()
+    const result = analyzeExtractSelection(nodes, connections, [b.id])
+    if (!result.ok) throw new Error(result.reason)
+    expect(result.entryNodeId).toBe(b.id)
+    expect(result.exitPortId).toBe(outOf(b).id)
+    expect(result.internal).toEqual([])
+    expect(result.inbound).toEqual([connect(a, b)])
+    expect(result.outbound).toEqual([connect(b, c)])
+  })
+
+  it("空・start/end 含みは拒否する", () => {
     const { b, nodes, connections } = chain()
     expect(analyzeExtractSelection(nodes, connections, []).ok).toBe(false)
-    expect(analyzeExtractSelection(nodes, connections, [b.id]).ok).toBe(false)
 
     const start = makeNode("start", "開始")
     const withStart = [...nodes, start]
@@ -217,4 +227,43 @@ describe("buildExtractPlan（子グラフと親置換の生成）", () => {
     void b
     void c
   })
+
+  it("1ノード選択：start.main → ノード → end.in と配線され、親では component ノードに置き換わる", () => {
+    const { a, b, c, nodes, connections } = chain()
+    const childStartOutPortId = uuid()
+    const childEndInPortId = uuid()
+    const plan = buildExtractPlan({
+      nodes,
+      connections,
+      selectedIds: [b.id],
+      name: "待つだけ",
+      componentLoopId: uuid(),
+      childStartOutPortId,
+      childEndInPortId,
+      newId: uuid,
+    })
+    if (!plan.ok) throw new Error(plan.reason)
+    expect(plan.childNodes).toHaveLength(1)
+    const [nb] = plan.childNodes
+    if (!nb) throw new Error("コピーがない")
+    expect(nb.wait).toEqual({ wait_type: "duration", duration_seconds: 90 })
+    expect(plan.childConnections).toContainEqual({
+      from_port_id: childStartOutPortId,
+      to_port_id: inOf(nb).id,
+    })
+    expect(plan.childConnections).toContainEqual({
+      from_port_id: outOf(nb).id,
+      to_port_id: childEndInPortId,
+    })
+    // 親：B が component ノードに置き換わり、A.main → group.in／group.main → C.in
+    expect(plan.parentNodes.some((n) => n.id === b.id)).toBe(false)
+    expect(plan.parentConnections).toContainEqual({
+      from_port_id: outOf(a).id,
+      to_port_id: inOf(plan.groupNode).id,
+    })
+    expect(plan.parentConnections).toContainEqual({
+      from_port_id: outOf(plan.groupNode).id,
+      to_port_id: inOf(c).id,
+    })
+  })
 })

package/_schemas/extract-component.ts

@@ -26,8 +26,10 @@ export const analyzeExtractSelection = (
   selectedIds: readonly string[],
 ): ExtractAnalysis => {
   const selected = new Set(selectedIds)
-  if (selected.size < 2) {
-    return { ok: false, reason: "2つ以上のノードを選択してください" }
+  // 1ノードからコンポーネント化できる（グループ化の「2つ以上」はエディタ側の
+  // 有効条件。コンポーネントの設定値（refs）と1ノードのコンポーネント化.md）
+  if (selected.size < 1) {
+    return { ok: false, reason: "ノードを選択してください" }
   }
   const selectedNodes = nodes.filter((n) => selected.has(n.id))
   const flow = selectedNodes.find((n) => n.kind === "start" || n.kind === "end")

package/_schemas/graph.test.ts

@@ -8,7 +8,7 @@ import {
   waitConfigSchema,
 } from "./graph.js"
 import type { GraphPort } from "./node.js"
-import { envelopeSchemaOf, resolvePortSchemas } from "./port-spec.js"
+import { resolvePortSchemas } from "./port-spec.js"
 
 // テスト用の決定的な uuid（common は node 型定義を持たないため crypto は使わない）
 let seq = 0
@@ -89,15 +89,14 @@ const port = (io: "in" | "out", key: string): GraphPort => ({
   schema: { type: "object" },
 })
 
-// ai の out 宣言は封筒型 { data, description } 固定なので、デフォルトノードは
-// data=テキストの封筒を持つ
-const textEnvelope = envelopeSchemaOf({ type: "string" })
+// ai の out も自由な宣言型。デフォルトノードはテキスト（string）を宣言する
+const textOutput = { type: "string" }
 
 // 既定は ai ノード。ai の in は 上流データの in ＋ 差し戻しの instruction の2口
 const aiPorts = (): GraphPort[] => [
   port("in", "in"),
   port("in", "instruction"),
-  { ...port("out", "main"), schema: textEnvelope },
+  { ...port("out", "main"), schema: textOutput },
 ]
 
 // ai 以外に流用するとき用（in は1つ）
@@ -388,17 +387,27 @@ describe("saveGraphBodySchema", () => {
     ).toThrow(/key が重複/)
   })
 
-  it("in ポートがちょうど1つでない node を拒否する（0個・2個）", () => {
+  it("in ポートの口数：ai は1つ以上（自由）、program 等は ちょうど1つ", () => {
+    // ai：0個は拒否、複数は許可（in の追加・削除は自由）
     const zero = makeNode([port("out", "main")])
     expect(() =>
       saveGraphBodySchema.parse({ nodes: [zero], connections: [] }),
     ).toThrow(/in ポート/)
-
-    const two = makeNode([
+    const many = makeNode([
       port("in", "in"),
-      port("in", "in2"),
+      port("in", "feedback"),
+      port("in", "extra"),
       port("out", "main"),
     ])
+    expect(() =>
+      saveGraphBodySchema.parse({ nodes: [many], connections: [] }),
+    ).not.toThrow()
+
+    // program：ちょうど1つ
+    const two = {
+      ...makeNode([port("in", "in"), port("in", "in2"), port("out", "main")]),
+      kind: "program" as const,
+    }
     expect(() =>
       saveGraphBodySchema.parse({ nodes: [two], connections: [] }),
     ).toThrow(/in ポート/)
@@ -497,8 +506,6 @@ describe("saveGraphBodySchema", () => {
 
 // ---- kind 別ポート構成と型の接続バリデーション（ポートのkind別仕様.md） ----
 
-const aiEnvelope = textEnvelope
-
 const humanNode = () => ({
   ...makeNode([
     port("in", "in"),
@@ -511,7 +518,7 @@ const aiNode = () => ({
   ...makeNode([
     port("in", "in"),
     port("in", "instruction"),
-    { ...port("out", "main"), schema: aiEnvelope },
+    { ...port("out", "main"), schema: textOutput },
   ]),
   kind: "ai" as const,
 })
@@ -549,27 +556,27 @@ describe("saveGraphBodySchema（kind 別ポート構成）", () => {
       ...makeNode([
         port("in", "in"),
         port("in", "instruction"),
-        { ...port("out", "spam"), schema: aiEnvelope },
-        { ...port("out", "sales"), schema: aiEnvelope },
-        { ...port("out", "support"), schema: aiEnvelope },
+        { ...port("out", "spam"), schema: textOutput },
+        { ...port("out", "sales"), schema: textOutput },
+        { ...port("out", "support"), schema: textOutput },
       ]),
       kind: "ai" as const,
     }
     expect(() =>
       saveGraphBodySchema.parse({ nodes: [multi], connections: [] }),
     ).not.toThrow()
-    // in の構成は in / instruction 固定のまま
-    const badIn = {
+    // in の key も自由（in / instruction の固定構成は廃止）
+    const freeIn = {
       ...makeNode([
         port("in", "input"),
-        port("in", "instruction"),
-        { ...port("out", "main"), schema: aiEnvelope },
+        port("in", "feedback"),
+        { ...port("out", "main"), schema: textOutput },
       ]),
       kind: "ai" as const,
     }
     expect(() =>
-      saveGraphBodySchema.parse({ nodes: [badIn], connections: [] }),
-    ).toThrow(/ai の in ポート/)
+      saveGraphBodySchema.parse({ nodes: [freeIn], connections: [] }),
+    ).not.toThrow()
   })
 
   it("program は out を複数持てる（key 自由）", () => {
@@ -586,49 +593,38 @@ describe("saveGraphBodySchema（kind 別ポート構成）", () => {
     ).not.toThrow()
   })
 
-  it("ai の出力宣言が封筒型 { data, description } でないと拒否する（全出口に適用）", () => {
-    const bad = makeNode([
-      port("in", "in"),
-      port("in", "instruction"),
-      { ...port("out", "main"), schema: { type: "object" } },
-    ])
-    expect(() =>
-      saveGraphBodySchema.parse({ nodes: [bad], connections: [] }),
-    ).toThrow(/封筒型 \{ data, description \}/)
-    // main 以外の出口も封筒型を強制する
-    const badExtra = makeNode([
-      port("in", "in"),
-      port("in", "instruction"),
-      { ...port("out", "main"), schema: aiEnvelope },
-      { ...port("out", "extra"), schema: { type: "object" } },
-    ])
-    expect(() =>
-      saveGraphBodySchema.parse({ nodes: [badExtra], connections: [] }),
-    ).toThrow(/封筒型 \{ data, description \}/)
-    // data は任意の型でよい（カタログ外の object も通る）
-    const custom = makeNode([
-      port("in", "in"),
-      port("in", "instruction"),
+  it("ai の出力宣言は任意の JSON Schema でよい（形の強制はしない）", () => {
+    for (const schema of [
+      { type: "object" },
+      { type: "string" },
+      { type: "array", items: { type: "number" } },
       {
-        ...port("out", "main"),
-        schema: envelopeSchemaOf({
-          type: "object",
-          properties: { title: { type: "string" } },
-          required: ["title"],
-        }),
+        // かつて強制していた { data, description } もただの object として valid
+        type: "object",
+        properties: {
+          data: { type: "string" },
+          description: { type: "string" },
+        },
+        required: ["data", "description"],
       },
-    ])
-    expect(() =>
-      saveGraphBodySchema.parse({ nodes: [custom], connections: [] }),
-    ).not.toThrow()
+    ]) {
+      const node = makeNode([
+        port("in", "in"),
+        port("in", "instruction"),
+        { ...port("out", "main"), schema },
+      ])
+      expect(() =>
+        saveGraphBodySchema.parse({ nodes: [node], connections: [] }),
+      ).not.toThrow()
+    }
   })
 })
 
 describe("saveGraphBodySchema（型の接続バリデーション）", () => {
-  // 接続の可否は kind ではなく型で決まる（reject と instruction は両端とも
-  // instructionSchema() で固定されているので、型検証だけで組み合わせが決まる）
-  // → docs/tasks/wip/Humanの入出力を承認ビューの宣言に一本化する.md
-  it("human の reject → ai の instruction は型が一致するので許可", () => {
+  // 接続の可否は kind ではなく型で決まる。reject / instruction の型固定は廃止され、
+  // ai の in はどの口も接続鏡映（接続元の型に同期）なので接続は自明に通る
+  // → docs/tasks/wip/ポート型固定の撤去とセッション再開のポート属性化.md
+  it("human の reject → ai の instruction を許可（kind の縛りも型固定も無い）", () => {
     const human = humanNode()
     const ai = aiNode()
     const rejectPort = outByKey(human, "reject")
@@ -645,7 +641,7 @@ describe("saveGraphBodySchema（型の接続バリデーション）", () => {
     ).not.toThrow()
   })
 
-  it("reject は ai 以外へも繋げる（接続鏡映の in が指示型を採用する）", () => {
+  it("reject は ai 以外へも繋げる（接続鏡映の in が接続元の型を採用する）", () => {
     const human = humanNode()
     const prog = programNode()
     expect(() =>
@@ -661,10 +657,11 @@ describe("saveGraphBodySchema（型の接続バリデーション）", () => {
     ).not.toThrow()
   })
 
-  it("instruction ポートには型の合わない出力を繋げない（kind ではなく型で弾く）", () => {
+  it("instruction も他の in と同じ接続鏡映：宣言と違う型の out でも同期して繋がる", () => {
     const upstream = aiNode()
     const downstream = aiNode()
-    // ai.main は封筒型 { data, description }、instruction は { prompt, files }
+    // ai.main は string、instruction の宣言は { type: "object" } だが、
+    // 鏡映で接続元に同期される（instruction の特別扱いは無い）
     expect(() =>
       saveGraphBodySchema.parse({
         nodes: [upstream, downstream],
@@ -675,10 +672,10 @@ describe("saveGraphBodySchema（型の接続バリデーション）", () => {
           },
         ],
       }),
-    ).toThrow(/適合しません/)
+    ).not.toThrow()
   })
 
-  it("human の in はどの型でも接続できる（封筒型の制約は課さない）", () => {
+  it("human の in はどの型でも接続できる（形の制約は課さない）", () => {
     const ai = aiNode()
     const human = humanNode()
     expect(() =>
@@ -688,8 +685,7 @@ describe("saveGraphBodySchema（型の接続バリデーション）", () => {
       }),
     ).not.toThrow()
 
-    // program out が封筒型でない（{ type: "object" } のまま）でも接続できる
-    // （input 全体を data として表示する）
+    // program out が素の object でも接続できる
     const human2 = humanNode()
     const progPlain = {
       ...makeNode([
@@ -707,7 +703,8 @@ describe("saveGraphBodySchema（型の接続バリデーション）", () => {
   })
 
   it("program の in への接続は 伝播型 ⊆ 宣言スキーマ（human 経由の伝播込み）", () => {
-    // ai(封筒型) → human(approve は data 型に剥がれる) → program(string を要求) は通る
+    // ai → human（approve は in と同型）→ program(string を要求) は、
+    // program の in が接続鏡映（sticky）なので通る
     const ai = aiNode()
     const human = humanNode()
     const prog = programNode({ type: "string" })
@@ -1027,6 +1024,30 @@ describe("saveGraphBodySchema：コンポーネントノード（component kind
     ).not.toThrow()
   })
 
+  it("component.refs（配置の設定値）を受け付けて保持する（省略も可）", () => {
+    const withRefs = {
+      ...componentNode(),
+      component: {
+        component_loop_id: uuid(),
+        refs: { labels: ["bug"], assignee: "kazuwombat" },
+      },
+    }
+    const parsed = saveGraphBodySchema.parse({
+      nodes: [withRefs],
+      connections: [],
+    })
+    expect(parsed.nodes[0]?.component?.refs).toEqual({
+      labels: ["bug"],
+      assignee: "kazuwombat",
+    })
+    // 省略時は undefined のまま（既存グラフの互換。保存側で {} 扱い）
+    const omitted = saveGraphBodySchema.parse({
+      nodes: [componentNode()],
+      connections: [],
+    })
+    expect(omitted.nodes[0]?.component?.refs).toBeUndefined()
+  })
+
   it("component_loop_id の無い component ノードを拒否する", () => {
     const node = { ...componentNode(), component: undefined }
     expect(() =>