@mawaru/sdk 0.34.0 → 0.36.0

package/_schemas/extract-component.test.ts

@@ -417,3 +417,78 @@ describe("buildExtractPlan（子グラフと親置換の生成）", () => {
     })
   })
 })
+
+// forで配列を要素ごとに処理する（繰り返しの枠）.md：繰り返しは結果を配列で返すので出口はちょうど1つ
+describe("buildExtractPlan（singleExit：繰り返しの出口は1つ）", () => {
+  const childEndNode = (): GraphNode => ({
+    id: uuid(),
+    kind: "end",
+    name: "終了",
+    ports: [port("in", "in", {}), port("out", "main", {})],
+    hooks: [],
+    position_x: 560,
+    position_y: 200,
+  })
+  const plan = (
+    nodes: GraphNode[],
+    connections: { from_port_id: string; to_port_id: string }[],
+    selectedIds: string[],
+    childEnd = childEndNode(),
+  ) =>
+    buildExtractPlan({
+      nodes,
+      connections,
+      selectedIds,
+      name: "繰り返し",
+      componentLoopId: uuid(),
+      childStartOutPortId: uuid(),
+      childEnd,
+      newId: uuid,
+      singleExit: true,
+    })
+
+  it("外へ出る線が無ければ、線の出ていない唯一の出力を出口にする（結果を返す）", () => {
+    const { d, nodes, connections } = chain()
+    const childEnd = childEndNode()
+
+    const result = plan(nodes, connections, [d.id], childEnd)
+
+    if (!result.ok) throw new Error(result.reason)
+    const [nd] = result.childNodes
+    if (!nd) throw new Error("コピーがない")
+    expect(result.childConnections).toContainEqual({
+      from_port_id: outOf(nd).id,
+      to_port_id: inOf(childEnd).id,
+    })
+    expect(result.groupNode.ports.filter((p) => p.io === "out")).toHaveLength(1)
+  })
+
+  it("外へ出る線があればそれが出口（ふだんの抽出と同じ）", () => {
+    const { b, c, nodes, connections } = chain()
+
+    const result = plan(nodes, connections, [b.id, c.id])
+
+    if (!result.ok) throw new Error(result.reason)
+    expect(result.childEnd.ports.filter((p) => p.io === "in")).toHaveLength(1)
+  })
+
+  it("出口が2つ以上・出口にできる出力が決まらない選択は拒否する", () => {
+    const a = makeNode("program", "A")
+    const b = makeNode("program", "B")
+    const c = makeNode("program", "C")
+    const d = makeNode("program", "D")
+    // B と C を選ぶ：B → D、C → D の2つの出口
+    const twoExits = plan(
+      [a, b, c, d],
+      [connect(a, b), connect(a, c), connect(b, d), connect(c, d)],
+      [b.id, c.id],
+    )
+    expect(twoExits.ok).toBe(false)
+    if (twoExits.ok) return
+    expect(twoExits.reason).toContain("出口を1つ")
+
+    // 外へ出る線が無く、線の出ていない出力が2つ（B と C）
+    const ambiguous = plan([b, c], [], [b.id, c.id])
+    expect(ambiguous.ok).toBe(false)
+  })
+})

package/_schemas/extract-component.ts

@@ -118,6 +118,10 @@ export const buildExtractPlan = (params: {
   childStartOutPortId: string
   childEnd: GraphNode
   newId: () => string
+  // 繰り返し（for）：結果を配列で返すので出口はちょうど1つ。外へ出る線が無ければ、
+  // 選択の中で線の出ていない唯一の出力を出口にする
+  // （forで配列を要素ごとに処理する（繰り返しの枠）.md）
+  singleExit?: boolean
 }): { ok: false; reason: string } | ({ ok: true } & ExtractPlan) => {
   const {
     nodes,
@@ -128,11 +132,30 @@ export const buildExtractPlan = (params: {
     childStartOutPortId,
     childEnd,
     newId,
+    singleExit = false,
   } = params
   const analysis = analyzeExtractSelection(nodes, connections, selectedIds)
   if (!analysis.ok) return analysis
 
   const selected = new Set(selectedIds)
+  let exitPortIds = analysis.exitPortIds
+  if (singleExit) {
+    if (exitPortIds.length === 0) {
+      const wiredOut = new Set(analysis.internal.map((c) => c.from_port_id))
+      const free = nodes
+        .filter((n) => selected.has(n.id))
+        .flatMap((n) =>
+          n.ports
+            .filter((p) => p.io === "out" && !wiredOut.has(p.id))
+            .map((p) => p.id),
+        )
+      exitPortIds = free.length === 1 ? free : []
+    }
+    if (exitPortIds.length !== 1) {
+      return { ok: false, reason: "繰り返しの出口を1つにしてください" }
+    }
+  }
+
   // ノード・ポートとも新 id を採番してコピー（kind 別設定・hooks は共有参照で問題ない
   // ＝この後 JSON 化して保存 API に渡すだけで、エディタ状態には子側を持たない）。
   // node_key は親の版の行との突き合わせ用なので子へは持ち込まない（子 loop の draft に
@@ -185,7 +208,7 @@ export const buildExtractPlan = (params: {
       }
     }
   }
-  const exits = analysis.exitPortIds.map((exitPortId, i) => {
+  const exits = exitPortIds.map((exitPortId, i) => {
     const exitName = portById.get(exitPortId)?.name ?? "出力"
     const seeded = i === 0 ? seededEndIns[0] : undefined
     const endIn: GraphPort = seeded

package/_schemas/graph.test.ts

@@ -997,22 +997,117 @@ describe("saveGraphBodySchema：開始/終了ノード（start/end kind）", ()
     ).toThrow(/in ポートはちょうど1つ/)
   })
 
-  it("start への接続・end からの接続を拒否する", () => {
-    const s = startNode()
+  it("end からの接続を拒否する", () => {
     const e = endNode()
     const other = makeNode()
+    expect(() =>
+      saveGraphBodySchema.parse({
+        nodes: [e, other],
+        connections: [connect(e, other)],
+      }),
+    ).toThrow(/終了ノード/)
+  })
+
+  // start の入口へ戻すと次の周回になる
+  // （docs/tasks/wip/startノードに入力をつないで周回する（runの周回）.md）
+  it("start の入口へ1本つなげる（周回の最後から戻す）", () => {
+    const s = startNode()
+    const other = { ...makeNode(simplePorts()), kind: "wait" }
     expect(() =>
       saveGraphBodySchema.parse({
         nodes: [s, other],
-        connections: [connect(other, s)],
+        connections: [connect(s, other), connect(other, s)],
       }),
-    ).toThrow(/開始ノード/)
+    ).not.toThrow()
+  })
+
+  it("start の入口につなげる線は1本だけ", () => {
+    const s = startNode()
+    const a = makeNode()
+    const b = makeNode()
     expect(() =>
       saveGraphBodySchema.parse({
-        nodes: [e, other],
-        connections: [connect(e, other)],
+        nodes: [s, a, b],
+        connections: [connect(a, s), connect(b, s)],
       }),
-    ).toThrow(/終了ノード/)
+    ).toThrow(/開始ノードの入口につなげる線は1本だけです/)
+  })
+
+  it("start の入口の型（直後のノードが受ける型）に合わない線を拒否する", () => {
+    const s = startNode()
+    const objectIn = {
+      type: "object",
+      properties: { title: { type: "string" } },
+      required: ["title"],
+    }
+    const next = {
+      ...makeNode([
+        { ...port("in", "in"), schema: objectIn },
+        port("out", "main"),
+      ]),
+      kind: "program",
+    }
+    const last = {
+      ...makeNode([
+        port("in", "in"),
+        { ...port("out", "main"), schema: { type: "string" } },
+      ]),
+      kind: "program",
+    }
+    expect(() =>
+      saveGraphBodySchema.parse({
+        nodes: [s, next, last],
+        connections: [connect(s, next), connect(next, last), connect(last, s)],
+      }),
+    ).toThrow(/入力スキーマに適合しません/)
+  })
+})
+
+// 合流は in を複数持てる（key 自由）＋ out(main)
+const joinNode = (inKeys: string[] = ["in_1", "in_2"]): TestNode => ({
+  ...makeNode([...inKeys.map((k) => port("in", k)), port("out", "main")]),
+  kind: "join",
+})
+
+describe("saveGraphBodySchema：合流ノード（join kind）", () => {
+  it("2本の枝を合流させるグラフを受け付ける", () => {
+    const a = makeNode(simplePorts())
+    const b = makeNode(simplePorts())
+    const j = joinNode()
+    const [in1, in2] = j.ports.filter((p) => p.io === "in")
+    const parsed = saveGraphBodySchema.parse({
+      nodes: [a, b, j],
+      connections: [
+        { from_port_id: outOf(a).id, to_port_id: in1?.id },
+        { from_port_id: outOf(b).id, to_port_id: in2?.id },
+      ],
+    })
+    expect(parsed.nodes.map((n) => n.kind)).toContain("join")
+  })
+
+  it("合流は複数置ける", () => {
+    expect(() =>
+      saveGraphBodySchema.parse({
+        nodes: [joinNode(), joinNode()],
+        connections: [],
+      }),
+    ).not.toThrow()
+  })
+
+  it("in が無い合流を拒否する", () => {
+    expect(() =>
+      saveGraphBodySchema.parse({ nodes: [joinNode([])], connections: [] }),
+    ).toThrow(/in ポートが1つ以上/)
+  })
+
+  it("out は main ちょうど1つ", () => {
+    const bad: TestNode = {
+      ...joinNode(),
+      ports: [port("in", "in_1"), port("out", "main"), port("out", "extra")],
+    }
+    expect(() =>
+      saveGraphBodySchema.parse({ nodes: [bad], connections: [] }),
+    ).toThrow(/join/)
   })
 })
 

package/_schemas/graph.ts

@@ -74,6 +74,7 @@ export const editableNodeKindSchema = nodeKindSchema.extract([
   "human",
   "program",
   "wait",
+  "join",
 ])
 export type EditableNodeKind = z.infer<typeof editableNodeKindSchema>
 
@@ -87,6 +88,7 @@ export const graphNodeKindSchema = nodeKindSchema.extract([
   "start",
   "end",
   "component",
+  "join",
 ])
 export type GraphNodeKind = z.infer<typeof graphNodeKindSchema>
 
@@ -384,18 +386,19 @@ export const saveGraphBodySchema = z
         else outCount++
       })
       // end は「in は1つ以上」（複数ルートを別々の in で集約する）。
-      // ai も1つ以上（in は自由ポート：追加・削除・key 自由）。他 kind は1つ固定。
+      // ai も1つ以上（in は自由ポート：追加・削除・key 自由）。join も1つ以上
+      // （待ち合わせる枝ごとに in）。他 kind は1つ固定。
       // key の妥当性は kindPortsViolation が別途見る
-      const inCountOk =
-        node.kind === "end" || node.kind === "ai" ? inCount >= 1 : inCount === 1
+      const multiIn =
+        node.kind === "end" || node.kind === "ai" || node.kind === "join"
+      const inCountOk = multiIn ? inCount >= 1 : inCount === 1
       if (!inCountOk) {
         ctx.addIssue({
           code: "custom",
           path: ["nodes", i, "ports"],
-          message:
-            node.kind === "end" || node.kind === "ai"
-              ? "in ポートが1つ以上必要です"
-              : "in ポートはちょうど1つ必要です",
+          message: multiIn
+            ? "in ポートが1つ以上必要です"
+            : "in ポートはちょうど1つ必要です",
         })
       }
       if (outCount < 1) {
@@ -518,12 +521,16 @@ export const saveGraphBodySchema = z
       const toNode = nodeByPortId.get(conn.to_port_id)
       if (!from || !to || !fromNode || !toNode) return // 構造違反は検出済み
 
-      // start には引き込めない（run payload だけが入口）、end からは引き出せない（終端）
-      if (toNode.kind === "start") {
+      // end からは引き出せない（終端）。start の入口へは戻せる（次の周回になる）が、
+      // 線は1本だけ（2本あると両方が着いたときに周回が2本並んで走る）
+      if (
+        toNode.kind === "start" &&
+        (inboundByPort.get(conn.to_port_id)?.length ?? 0) > 1
+      ) {
         ctx.addIssue({
           code: "custom",
           path: ["connections", i, "to_port_id"],
-          message: "開始ノードには接続できません",
+          message: "開始ノードの入口につなげる線は1本だけです",
         })
       }
       if (fromNode.kind === "end") {

package/_schemas/node.ts

@@ -13,6 +13,9 @@ export const nodeKindSchema = z.enum([
   // コンポーネント（kind='component' の loop を配置して呼ぶ。子 run・戻り値あり。
   // docs/tasks/done/コンポーネント（ループの部品化と再利用）.md）
   "component",
+  // 合流（線のつながった入口が全部揃うまで待ち、key ごとにまとめて流す。
+  // docs/tasks/wip/合流ノード（並行分岐の待ち合わせ）.md）
+  "join",
 ])
 export type NodeKind = z.infer<typeof nodeKindSchema>
 

package/_schemas/port-spec.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest"
 import type { GraphPort, JsonSchema } from "./node.js"
 import {
+  arrayOf,
   dataFormatOf,
   dataSchemaOf,
   fileSchema,
@@ -782,6 +783,111 @@ describe("型伝播：fan-in（同じ in ポートへの流入2本以上）", ()
   })
 })
 
+describe("合流（join）", () => {
+  const findings = {
+    type: "object",
+    properties: { findings: { type: "array" } },
+    required: ["findings"],
+  }
+  const source = (schema: JsonSchema) => {
+    const out = port("out", "main", schema)
+    return {
+      node: { id: uuid(), kind: "program", ports: [port("in", "in"), out] },
+      out,
+    }
+  }
+  const named = (key: string, name: string): GraphPort => ({
+    ...port("in", key),
+    name,
+  })
+
+  it("join は in の key 自由・1つ以上、out は main ちょうど1つ", () => {
+    expect(
+      kindPortsViolation("join", [
+        port("in", "in_1"),
+        port("in", "in_2"),
+        port("out", "main"),
+      ]),
+    ).toBeNull()
+    expect(
+      kindPortsViolation("join", [port("in", "in_1"), port("out", "done")]),
+    ).toMatch(/join/)
+    expect(
+      kindPortsViolation("join", [
+        port("in", "in_1"),
+        port("out", "main"),
+        port("out", "extra"),
+      ]),
+    ).toMatch(/join/)
+    expect(kindPortsViolation("join", [port("out", "main")])).toMatch(/join/)
+  })
+
+  it("各 in は自分の上流から、out main は線のつながった in を key ごとに持つ object", () => {
+    const a = source(findings)
+    const b = source({ type: "string" })
+    const in1 = named("in_1", "スキャン")
+    const in2 = named("in_2", "依存チェック")
+    const loose = named("in_3", "未接続")
+    const out = port("out", "main")
+    const join = { id: uuid(), kind: "join", ports: [in1, in2, loose, out] }
+    const resolved = resolvePortSchemas(
+      [a.node, b.node, join],
+      [
+        { from_port_id: a.out.id, to_port_id: in1.id },
+        { from_port_id: b.out.id, to_port_id: in2.id },
+      ],
+    )
+    expect(resolved.get(in1.id)).toEqual(findings)
+    expect(resolved.get(in2.id)).toEqual({ type: "string" })
+    // 未接続の in は待たない＝出口にも出ない
+    expect(resolved.get(out.id)).toEqual({
+      type: "object",
+      properties: {
+        in_1: { ...findings, title: "スキャン" },
+        in_2: { type: "string", title: "依存チェック" },
+      },
+      required: ["in_1", "in_2"],
+    })
+  })
+
+  it("out main の型は下流の program の in へ鏡映される", () => {
+    const a = source(findings)
+    const in1 = port("in", "in_1")
+    const out = port("out", "main")
+    const join = { id: uuid(), kind: "join", ports: [in1, out] }
+    const nextIn = port("in", "in")
+    const next = {
+      id: uuid(),
+      kind: "program",
+      ports: [nextIn, port("out", "main")],
+    }
+    const resolved = resolvePortSchemas(
+      [a.node, join, next],
+      [
+        { from_port_id: a.out.id, to_port_id: in1.id },
+        { from_port_id: out.id, to_port_id: nextIn.id },
+      ],
+    )
+    expect(resolved.get(nextIn.id)).toEqual({
+      type: "object",
+      properties: { in_1: { ...findings, title: "in_1" } },
+      required: ["in_1"],
+    })
+  })
+
+  it("線が1本も無ければ out main は未宣言", () => {
+    const out = port("out", "main")
+    const join = {
+      id: uuid(),
+      kind: "join",
+      ports: [port("in", "in_1"), out],
+    }
+    expect(resolvePortSchemas([join], []).get(out.id)).toEqual(
+      UNDECLARED_SCHEMA,
+    )
+  })
+})
+
 describe("file 型（nominal）", () => {
   it("fileSchema はマーカー付き object、isFileSchema で識別できる", () => {
     const schema = fileSchema()
@@ -1011,3 +1117,30 @@ describe("schemaTypeKey（型としての同一性）", () => {
     ).not.toBe(schemaTypeKey({ type: "array", items: [{ type: "number" }] }))
   })
 })
+
+describe("arrayOf（for の配置ポート：1件分の型を配列に包む）", () => {
+  it("宣言された型は items に入れた配列になる", () => {
+    const error = { type: "object", properties: { id: { type: "string" } } }
+    expect(arrayOf(error)).toEqual({ type: "array", items: error })
+  })
+
+  it("未宣言の型は items を持たない配列になる（要素の型は判断できないまま）", () => {
+    expect(arrayOf(UNDECLARED_SCHEMA)).toEqual({ type: "array" })
+  })
+
+  it("配列にした型同士は要素の型で適合を判定する", () => {
+    const narrow = {
+      type: "object",
+      properties: { id: { type: "string" }, title: { type: "string" } },
+      required: ["id", "title"],
+    }
+    const wide = {
+      type: "object",
+      properties: { id: { type: "string" } },
+      required: ["id"],
+    }
+    expect(schemaFit(arrayOf(narrow), arrayOf(wide))).toBe("ok")
+    expect(schemaFit(arrayOf(wide), arrayOf(narrow))).toBe("mismatch")
+    expect(schemaFit(wide, arrayOf(wide))).toBe("mismatch")
+  })
+})

package/_schemas/port-spec.ts

@@ -15,6 +15,14 @@ export const UNDECLARED_SCHEMA: JsonSchema = {}
 export const isUndeclaredSchema = (schema: JsonSchema): boolean =>
   Object.keys(schema).length === 0 || schema.type === undefined
 
+// 1件分の型を配列に包む（for の配置ポート：in ＝ 中身の start.in の配列、out ＝ 中身の
+// end の in の配列。docs/tasks/done/forで配列を要素ごとに処理する（繰り返しの枠）.md）。
+// 未宣言は items を持たせない（要素の型は判断できないまま）
+export const arrayOf = (schema: JsonSchema): JsonSchema =>
+  isUndeclaredSchema(schema)
+    ? { type: "array" }
+    : { type: "array", items: schema }
+
 // ---- file 型（docs/tasks/done/AIノードのファイル入力（file型と添付）.md） ----
 // schema 上の file は x-mawaru-type マーカー付きの object（nominal に識別する）。値はバイト
 // ではなく storage path の参照で、署名 URL はどこにも焼き込まない。
@@ -198,6 +206,19 @@ export const kindPortsViolation = (
     }
     return null
   }
+  // join は out が main 1つ固定・in は1つ以上（待ち合わせる枝ごとに in。key 自由。
+  // 合流ノード（並行分岐の待ち合わせ）.md）
+  if (kind === "join") {
+    const outKeys = ports.filter((p) => p.io === "out").map((p) => p.key)
+    if (
+      outKeys.length !== 1 ||
+      outKeys[0] !== "main" ||
+      !ports.some((p) => p.io === "in")
+    ) {
+      return `join のポート構成は in 1つ以上と out "main" ちょうど1つです`
+    }
+    return null
+  }
   if (kind === "human") {
     const inKeys = ports.filter((p) => p.io === "in").map((p) => p.key)
     const outKeys = ports.filter((p) => p.io === "out").map((p) => p.key)
@@ -338,7 +359,8 @@ export type PropagationOptions<N> = {
 // resolvePortSchemas 内で行うが、初期スキーマを未宣言にするためここに含める。
 // start も導出ノード：out main は接続先の in から逆向きに転写し、in は out と同型
 // （run 入力契約＝接続先の入力宣言。開始ノードの入力契約を接続先から導出.md）
-const DERIVED_KINDS = new Set(["wait", "human", "end", "start"])
+// join も導出ノード（各 in は上流から、out main は線のつながった in を key ごとに持つ object）
+const DERIVED_KINDS = new Set(["wait", "human", "end", "start", "join"])
 
 // in を接続鏡映（sticky）するノード：接続元 out が具体型のときだけ上書き
 const MIRROR_KINDS = new Set(["program", "ai"])
@@ -428,6 +450,36 @@ export const resolvePortSchemas = <N extends PropagationNode>(
         }
         continue
       }
+      // join：各 in を自分の上流から導出（end と同じ）。out main は線のつながった in を
+      // key ごとに持つ object（「両方」を1段入れて持つ。中身を平らに混ぜると key が
+      // ぶつかる）。待つのは線のつながった in だけなので、未接続の in は出口に出さない
+      if (node.kind === "join") {
+        const properties: Record<string, JsonSchema> = {}
+        for (const port of node.ports) {
+          if (port.io !== "in") continue
+          const srcs = inbound.get(port.id) ?? []
+          const schema = mergeInboundSchemas(
+            srcs.map((id) => resolved.get(id) ?? UNDECLARED_SCHEMA),
+          )
+          assign(port.id, schema)
+          if (srcs.length > 0) {
+            properties[port.key] = { ...schema, title: port.name }
+          }
+        }
+        const outMain = node.ports.find(
+          (p) => p.io === "out" && p.key === "main",
+        )
+        const keys = Object.keys(properties)
+        if (outMain) {
+          assign(
+            outMain.id,
+            keys.length > 0
+              ? { type: "object", properties, required: keys }
+              : UNDECLARED_SCHEMA,
+          )
+        }
+        continue
+      }
       const isMirror = MIRROR_KINDS.has(node.kind)
       if (!DERIVED_KINDS.has(node.kind) && !isMirror) continue
       // 鏡映（program / ai）：全ての in が対象。具体型が流れてきたときだけ上書きする

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

@@ -28,6 +28,7 @@ export declare const buildExtractPlan: (params: {
     childStartOutPortId: string;
     childEnd: GraphNode;
     newId: () => string;
+    singleExit?: boolean;
 }) => {
     ok: false;
     reason: string;

package/dist/_schemas/extract-component.js

@@ -55,11 +55,26 @@ export const analyzeExtractSelection = (nodes, connections, selectedIds) => {
 // end の in が1つの loop は out main の1口として振る舞う）
 const SINGLE_OUT_KEY = "main";
 export const buildExtractPlan = (params) => {
-    const { nodes, connections, selectedIds, name, componentLoopId, childStartOutPortId, childEnd, newId, } = params;
+    const { nodes, connections, selectedIds, name, componentLoopId, childStartOutPortId, childEnd, newId, singleExit = false, } = params;
     const analysis = analyzeExtractSelection(nodes, connections, selectedIds);
     if (!analysis.ok)
         return analysis;
     const selected = new Set(selectedIds);
+    let exitPortIds = analysis.exitPortIds;
+    if (singleExit) {
+        if (exitPortIds.length === 0) {
+            const wiredOut = new Set(analysis.internal.map((c) => c.from_port_id));
+            const free = nodes
+                .filter((n) => selected.has(n.id))
+                .flatMap((n) => n.ports
+                .filter((p) => p.io === "out" && !wiredOut.has(p.id))
+                .map((p) => p.id));
+            exitPortIds = free.length === 1 ? free : [];
+        }
+        if (exitPortIds.length !== 1) {
+            return { ok: false, reason: "繰り返しの出口を1つにしてください" };
+        }
+    }
     // ノード・ポートとも新 id を採番してコピー（kind 別設定・hooks は共有参照で問題ない
     // ＝この後 JSON 化して保存 API に渡すだけで、エディタ状態には子側を持たない）。
     // node_key は親の版の行との突き合わせ用なので子へは持ち込まない（子 loop の draft に
@@ -108,7 +123,7 @@ export const buildExtractPlan = (params) => {
             }
         }
     };
-    const exits = analysis.exitPortIds.map((exitPortId, i) => {
+    const exits = exitPortIds.map((exitPortId, i) => {
         const exitName = portById.get(exitPortId)?.name ?? "出力";
         const seeded = i === 0 ? seededEndIns[0] : undefined;
         const endIn = seeded

package/dist/_schemas/graph.d.ts

@@ -11,6 +11,7 @@ export type LoopRefs = z.infer<typeof loopRefsSchema>;
 export declare const EMPTY_LOOP_REFS: LoopRefs;
 export declare const refsDefaultsOf: (refs: LoopRefs) => RefsBag;
 export declare const editableNodeKindSchema: z.ZodEnum<{
+    join: "join";
     ai: "ai";
     human: "human";
     program: "program";
@@ -19,6 +20,7 @@ export declare const editableNodeKindSchema: z.ZodEnum<{
 export type EditableNodeKind = z.infer<typeof editableNodeKindSchema>;
 export declare const graphNodeKindSchema: z.ZodEnum<{
     start: "start";
+    join: "join";
     ai: "ai";
     human: "human";
     program: "program";
@@ -131,6 +133,7 @@ export declare const graphNodeSchema: z.ZodObject<{
     node_key: z.ZodOptional<z.ZodUUID>;
     kind: z.ZodEnum<{
         start: "start";
+        join: "join";
         ai: "ai";
         human: "human";
         program: "program";
@@ -230,6 +233,7 @@ export declare const saveGraphBodySchema: z.ZodObject<{
         node_key: z.ZodOptional<z.ZodUUID>;
         kind: z.ZodEnum<{
             start: "start";
+            join: "join";
             ai: "ai";
             human: "human";
             program: "program";

package/dist/_schemas/graph.js

@@ -52,6 +52,7 @@ export const editableNodeKindSchema = nodeKindSchema.extract([
     "human",
     "program",
     "wait",
+    "join",
 ]);
 // グラフ一括保存で受け付ける kind（パレット作成の4種＋構造ノード start/end）。
 // start/end はパレットに出さないが、seed 済みなので全置換ボディには常に含まれる
@@ -63,6 +64,7 @@ export const graphNodeKindSchema = nodeKindSchema.extract([
     "start",
     "end",
     "component",
+    "join",
 ]);
 // Wait ノードの kind 別設定（node_waits の wait_type に対応する判別ユニオン）。
 // duration=経過秒、cron=cron 式（次に来る該当時刻まで1回待つ）。
@@ -319,14 +321,16 @@ export const saveGraphBodySchema = z
                 outCount++;
         });
         // end は「in は1つ以上」（複数ルートを別々の in で集約する）。
-        // ai も1つ以上（in は自由ポート：追加・削除・key 自由）。他 kind は1つ固定。
+        // ai も1つ以上（in は自由ポート：追加・削除・key 自由）。join も1つ以上
+        // （待ち合わせる枝ごとに in）。他 kind は1つ固定。
         // key の妥当性は kindPortsViolation が別途見る
-        const inCountOk = node.kind === "end" || node.kind === "ai" ? inCount >= 1 : inCount === 1;
+        const multiIn = node.kind === "end" || node.kind === "ai" || node.kind === "join";
+        const inCountOk = multiIn ? inCount >= 1 : inCount === 1;
         if (!inCountOk) {
             ctx.addIssue({
                 code: "custom",
                 path: ["nodes", i, "ports"],
-                message: node.kind === "end" || node.kind === "ai"
+                message: multiIn
                     ? "in ポートが1つ以上必要です"
                     : "in ポートはちょうど1つ必要です",
             });
@@ -443,12 +447,14 @@ export const saveGraphBodySchema = z
         const toNode = nodeByPortId.get(conn.to_port_id);
         if (!from || !to || !fromNode || !toNode)
             return; // 構造違反は検出済み
-        // start には引き込めない（run payload だけが入口）、end からは引き出せない（終端）
-        if (toNode.kind === "start") {
+        // end からは引き出せない（終端）。start の入口へは戻せる（次の周回になる）が、
+        // 線は1本だけ（2本あると両方が着いたときに周回が2本並んで走る）
+        if (toNode.kind === "start" &&
+            (inboundByPort.get(conn.to_port_id)?.length ?? 0) > 1) {
             ctx.addIssue({
                 code: "custom",
                 path: ["connections", i, "to_port_id"],
-                message: "開始ノードには接続できません",
+                message: "開始ノードの入口につなげる線は1本だけです",
             });
         }
         if (fromNode.kind === "end") {

package/dist/_schemas/node.d.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 export declare const nodeKindSchema: z.ZodEnum<{
     start: "start";
+    join: "join";
     ai: "ai";
     human: "human";
     program: "program";

package/dist/_schemas/node.js

@@ -12,6 +12,9 @@ export const nodeKindSchema = z.enum([
     // コンポーネント（kind='component' の loop を配置して呼ぶ。子 run・戻り値あり。
     // docs/tasks/done/コンポーネント（ループの部品化と再利用）.md）
     "component",
+    // 合流（線のつながった入口が全部揃うまで待ち、key ごとにまとめて流す。
+    // docs/tasks/wip/合流ノード（並行分岐の待ち合わせ）.md）
+    "join",
 ]);
 // ポート key（input/output 用の参照キー）の規則（db.md §2）。
 // name（ユーザーが見る表示名）は自由テキスト

package/dist/_schemas/port-spec.d.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 import type { GraphPort, JsonSchema } from "./node.js";
 export declare const UNDECLARED_SCHEMA: JsonSchema;
 export declare const isUndeclaredSchema: (schema: JsonSchema) => boolean;
+export declare const arrayOf: (schema: JsonSchema) => JsonSchema;
 export declare const FILE_SCHEMA_MARKER = "x-mawaru-type";
 export declare const FILE_SCHEMA_TYPE = "file";
 export declare const fileSchema: () => JsonSchema;

package/dist/_schemas/port-spec.js

@@ -9,6 +9,12 @@ import { z } from "zod";
 // （docs/tasks/done/ポートスキーマのany撲滅.md）
 export const UNDECLARED_SCHEMA = {};
 export const isUndeclaredSchema = (schema) => Object.keys(schema).length === 0 || schema.type === undefined;
+// 1件分の型を配列に包む（for の配置ポート：in ＝ 中身の start.in の配列、out ＝ 中身の
+// end の in の配列。docs/tasks/done/forで配列を要素ごとに処理する（繰り返しの枠）.md）。
+// 未宣言は items を持たせない（要素の型は判断できないまま）
+export const arrayOf = (schema) => isUndeclaredSchema(schema)
+    ? { type: "array" }
+    : { type: "array", items: schema };
 // ---- file 型（docs/tasks/done/AIノードのファイル入力（file型と添付）.md） ----
 // schema 上の file は x-mawaru-type マーカー付きの object（nominal に識別する）。値はバイト
 // ではなく storage path の参照で、署名 URL はどこにも焼き込まない。
@@ -165,6 +171,17 @@ export const kindPortsViolation = (kind, ports) => {
         }
         return null;
     }
+    // join は out が main 1つ固定・in は1つ以上（待ち合わせる枝ごとに in。key 自由。
+    // 合流ノード（並行分岐の待ち合わせ）.md）
+    if (kind === "join") {
+        const outKeys = ports.filter((p) => p.io === "out").map((p) => p.key);
+        if (outKeys.length !== 1 ||
+            outKeys[0] !== "main" ||
+            !ports.some((p) => p.io === "in")) {
+            return `join のポート構成は in 1つ以上と out "main" ちょうど1つです`;
+        }
+        return null;
+    }
     if (kind === "human") {
         const inKeys = ports.filter((p) => p.io === "in").map((p) => p.key);
         const outKeys = ports.filter((p) => p.io === "out").map((p) => p.key);
@@ -263,7 +280,8 @@ export const COPY_UPSTREAM_SCHEMA = "T";
 // resolvePortSchemas 内で行うが、初期スキーマを未宣言にするためここに含める。
 // start も導出ノード：out main は接続先の in から逆向きに転写し、in は out と同型
 // （run 入力契約＝接続先の入力宣言。開始ノードの入力契約を接続先から導出.md）
-const DERIVED_KINDS = new Set(["wait", "human", "end", "start"]);
+// join も導出ノード（各 in は上流から、out main は線のつながった in を key ごとに持つ object）
+const DERIVED_KINDS = new Set(["wait", "human", "end", "start", "join"]);
 // in を接続鏡映（sticky）するノード：接続元 out が具体型のときだけ上書き
 const MIRROR_KINDS = new Set(["program", "ai"]);
 const isDerivedPort = (kind, port) => DERIVED_KINDS.has(kind) &&
@@ -331,6 +349,30 @@ export const resolvePortSchemas = (nodes, connections, options) => {
                 }
                 continue;
             }
+            // join：各 in を自分の上流から導出（end と同じ）。out main は線のつながった in を
+            // key ごとに持つ object（「両方」を1段入れて持つ。中身を平らに混ぜると key が
+            // ぶつかる）。待つのは線のつながった in だけなので、未接続の in は出口に出さない
+            if (node.kind === "join") {
+                const properties = {};
+                for (const port of node.ports) {
+                    if (port.io !== "in")
+                        continue;
+                    const srcs = inbound.get(port.id) ?? [];
+                    const schema = mergeInboundSchemas(srcs.map((id) => resolved.get(id) ?? UNDECLARED_SCHEMA));
+                    assign(port.id, schema);
+                    if (srcs.length > 0) {
+                        properties[port.key] = { ...schema, title: port.name };
+                    }
+                }
+                const outMain = node.ports.find((p) => p.io === "out" && p.key === "main");
+                const keys = Object.keys(properties);
+                if (outMain) {
+                    assign(outMain.id, keys.length > 0
+                        ? { type: "object", properties, required: keys }
+                        : UNDECLARED_SCHEMA);
+                }
+                continue;
+            }
             const isMirror = MIRROR_KINDS.has(node.kind);
             if (!DERIVED_KINDS.has(node.kind) && !isMirror)
                 continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mawaru/sdk",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "description": "mawaru 実行 repo の開発 SDK。契約スキーマ（config.json 規約・ループ graph API）の正 ＋ typegen / validate CLI",
   "type": "module",
   "bin": {

package/skills/create-loop/SKILL.md

@@ -73,7 +73,16 @@ repo との矛盾・使用中ノードの削除は 409。**graph PUT は冪等
 
 ## 手順
 
-1. **設計**：要件から必要なノード（program / ai / human / wait）と流れを決め、ユーザーに一言で確認する。
+1. **設計**：要件から必要なノード（program / ai / human / wait / join）と流れを決め、ユーザーに一言で確認する。
+   1つの出口から複数の線を引くと枝が並行に走る（fan-out）。枝の結果を待ち合わせるときは
+   合流（`join`）を置く：線のつながった入口が全部揃うまで待ち、`{ [入口の key]: 値 }` にまとめて
+   `main` から流す。並行した枝を合流させずに同じノード（待機など）へ戻すと、枝の数だけ走り続ける。
+   配列の要素ごとに同じ手順や別ループを回すときは繰り返し（for）にする：`POST loops` に
+   `kind: "for"` と `owner_loop_id`（このループ）を渡して中身の loop を作り、その graph
+   （start → 1件分の処理 → end）を保存してから、このループに component ノード
+   （`component.component_loop_id`＝作った for）を置く。配置ノードの in / out は中身の型の配列に
+   自動で焼き込まれ、全件そろうと入力と同じ順の配列で `main` から流れる（1件ずつは同時に走る）。
+   中身の出口（end につないだ in）は1つにする。
 2. **repo 側の準備**：足りない program / ai は `nodes/program/<dir>/` / `nodes/ai/<dir>/` に作る
    （config.json → `npx mawaru typegen` → main.ts 実装 → `npx mawaru validate`）。
    **AI ノードの決定論的な処理は prompt ではなく `setup.sh` に書く**（下記）。
@@ -84,7 +93,8 @@ repo との矛盾・使用中ノードの削除は 409。**graph PUT は冪等
    - node / port の `id` はクライアント採番（`uuidgen` などで UUID を作る）
    - program / ai ノードの ports は repo の config.json の inputs / outputs をそのまま写す
      （in ポート key は `in`、out ポートは outputs の各 key）
-   - kind 別の固定ポート構成（human / wait / ai）は `port-spec.ts` の `kindPortsViolation` に従う
+   - kind 別の固定ポート構成（human / wait / ai / join）は `port-spec.ts` の `kindPortsViolation` に従う。
+     join は in を枝の数だけ（key 自由。例 `in_1`, `in_2`）＋ out `main`。出口の型は自動で決まる
    - ループ変数（refs＝run 全体で読める key→値 の袋）が要るならトップレベルの `refs` に入れる。
      ノード単位の宣言やバインドは無い。handler は実行時に `refs.json` で全量を受け取り、
      `end` の `refs` パッチで値を更新できる（config.json の `refs` はループ定義からの転写＝生成物）。