@mawaru/sdk 0.34.0 → 0.35.0

package/_schemas/graph.test.ts

@@ -1016,6 +1016,54 @@ describe("saveGraphBodySchema：開始/終了ノード（start/end kind）", ()
   })
 })
 
+// 合流は 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/)
+  })
+})
+
 describe("refsDefaultsOf（定義スキーマ→デフォルト値の袋）", () => {
   it("default を持つプロパティだけを値の袋に集める", () => {
     const defaults = refsDefaultsOf({

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) {

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

@@ -782,6 +782,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()

package/_schemas/port-spec.ts

@@ -198,6 +198,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 +351,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 +442,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/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つ必要です",
             });

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.js

@@ -165,6 +165,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 +274,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 +343,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.35.0",
   "description": "mawaru 実行 repo の開発 SDK。契約スキーマ（config.json 規約・ループ graph API）の正 ＋ typegen / validate CLI",
   "type": "module",
   "bin": {

package/skills/create-loop/SKILL.md

@@ -73,7 +73,10 @@ repo との矛盾・使用中ノードの削除は 409。**graph PUT は冪等
 
 ## 手順
 
-1. **設計**：要件から必要なノード（program / ai / human / wait）と流れを決め、ユーザーに一言で確認する。
+1. **設計**：要件から必要なノード（program / ai / human / wait / join）と流れを決め、ユーザーに一言で確認する。
+   1つの出口から複数の線を引くと枝が並行に走る（fan-out）。枝の結果を待ち合わせるときは
+   合流（`join`）を置く：線のつながった入口が全部揃うまで待ち、`{ [入口の key]: 値 }` にまとめて
+   `main` から流す。並行した枝を合流させずに同じノード（待機など）へ戻すと、枝の数だけ走り続ける。
 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 +87,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` はループ定義からの転写＝生成物）。