@mawaru/sdk 0.5.0 → 0.8.0

package/_schemas/graph.test.ts

@@ -8,7 +8,7 @@ import {
   waitConfigSchema,
 } from "./graph.js"
 import type { GraphPort } from "./node.js"
-import { envelopeSchemaOf } from "./port-spec.js"
+import { envelopeSchemaOf, resolvePortSchemas } from "./port-spec.js"
 
 // テスト用の決定的な uuid（common は node 型定義を持たないため crypto は使わない）
 let seq = 0
@@ -93,14 +93,21 @@ const port = (io: "in" | "out", key: string): GraphPort => ({
 // data=テキストの封筒を持つ
 const textEnvelope = envelopeSchemaOf({ type: "string" })
 
+// 既定は ai ノード。ai の in は 上流データの in ＋ 差し戻しの instruction の2口
+const aiPorts = (): GraphPort[] => [
+  port("in", "in"),
+  port("in", "instruction"),
+  { ...port("out", "main"), schema: textEnvelope },
+]
+
+// ai 以外に流用するとき用（in は1つ）
+const simplePorts = (): GraphPort[] => [port("in", "in"), port("out", "main")]
+
 const makeNode = (ports?: GraphPort[]) => ({
   id: uuid(),
   kind: "ai" as const,
   name: "ノード",
-  ports: ports ?? [
-    port("in", "in"),
-    { ...port("out", "main"), schema: textEnvelope },
-  ],
+  ports: ports ?? aiPorts(),
   position_x: 0,
   position_y: 0,
 })
@@ -172,6 +179,24 @@ describe("humanConfigSchema", () => {
     })
   })
 
+  // 承認ビューは不透明なキー（program_dir / ai_dir と同じ）。実在するか・そのテナントが
+  // 選べるかは mawaru 側のカタログ（非公開）と保存 API が見るので、ここは形だけ
+  it("承認ビューとそのパラメータを受け付ける", () => {
+    const parsed = humanConfigSchema.parse({
+      assignment: {},
+      view: "acme/invoice",
+      view_config: { threshold: 1000 },
+    })
+    expect(parsed.view).toBe("acme/invoice")
+    expect(parsed.view_config).toEqual({ threshold: 1000 })
+  })
+
+  it("空のビューキーは拒否する", () => {
+    expect(() =>
+      humanConfigSchema.parse({ assignment: {}, view: "" }),
+    ).toThrow()
+  })
+
   it("fixed：1ユニット（複数人の and/or）を受け付ける", () => {
     const u1 = uuid()
     const u2 = uuid()
@@ -258,6 +283,52 @@ describe("saveGraphBodySchema", () => {
     })
   })
 
+  // fan-in（同じ in ポートへの流入2本以上）は同じ型でなければならない
+  // （docs/tasks/wip/ポートスキーマのany撲滅.md）
+  const programNode = (outSchema: GraphPort["schema"]) => ({
+    ...makeNode([
+      port("in", "in"),
+      { ...port("out", "main"), schema: outSchema },
+    ]),
+    kind: "program" as const,
+  })
+
+  it("fan-in：流入の型が同じなら受け付ける", () => {
+    const a = programNode({ type: "string" })
+    const b = programNode({ type: "string" })
+    const sink = { ...makeNode(simplePorts()), kind: "wait" as const }
+    expect(() =>
+      saveGraphBodySchema.parse({
+        nodes: [a, b, sink],
+        connections: [connect(a, sink), connect(b, sink)],
+      }),
+    ).not.toThrow()
+  })
+
+  it("fan-in：異なる具体型の流入を拒否する", () => {
+    const a = programNode({ type: "string" })
+    const b = programNode({ type: "number" })
+    const sink = { ...makeNode(simplePorts()), kind: "wait" as const }
+    expect(() =>
+      saveGraphBodySchema.parse({
+        nodes: [a, b, sink],
+        connections: [connect(a, sink), connect(b, sink)],
+      }),
+    ).toThrow(/異なる型を接続できません/)
+  })
+
+  it("fan-in：具体型1種類＋未宣言 の混在は受け付ける（未宣言は判断材料にしない）", () => {
+    const a = programNode({ type: "string" })
+    const b = { ...makeNode(simplePorts()), kind: "wait" as const } // out main は導出＝未宣言
+    const sink = { ...makeNode(simplePorts()), kind: "wait" as const }
+    expect(() =>
+      saveGraphBodySchema.parse({
+        nodes: [a, b, sink],
+        connections: [connect(a, sink), connect(b, sink)],
+      }),
+    ).not.toThrow()
+  })
+
   it("node id の重複を拒否する", () => {
     const a = makeNode()
     expect(() =>
@@ -410,6 +481,7 @@ const humanNode = () => ({
 const aiNode = () => ({
   ...makeNode([
     port("in", "in"),
+    port("in", "instruction"),
     { ...port("out", "main"), schema: aiEnvelope },
   ]),
   kind: "ai" as const,
@@ -418,6 +490,11 @@ const programNode = (inSchema: GraphPort["schema"] = {}) => ({
   ...makeNode([{ ...port("in", "in"), schema: inSchema }, port("out", "main")]),
   kind: "program" as const,
 })
+const inByKey = (node: TestNode, key: string): GraphPort => {
+  const p = node.ports.find((p) => p.io === "in" && p.key === key)
+  if (!p) throw new Error(`in port not found: ${key}`)
+  return p
+}
 const outByKey = (node: TestNode, key: string): GraphPort => {
   const p = node.ports.find((p) => p.io === "out" && p.key === key)
   if (!p) throw new Error(`out port not found: ${key}`)
@@ -442,6 +519,7 @@ describe("saveGraphBodySchema（kind 別ポート構成）", () => {
     const multi = {
       ...makeNode([
         port("in", "in"),
+        port("in", "instruction"),
         { ...port("out", "spam"), schema: aiEnvelope },
         { ...port("out", "sales"), schema: aiEnvelope },
         { ...port("out", "support"), schema: aiEnvelope },
@@ -451,10 +529,11 @@ describe("saveGraphBodySchema（kind 別ポート構成）", () => {
     expect(() =>
       saveGraphBodySchema.parse({ nodes: [multi], connections: [] }),
     ).not.toThrow()
-    // in の key は "in" 固定のまま
+    // in の構成は in / instruction 固定のまま
     const badIn = {
       ...makeNode([
         port("in", "input"),
+        port("in", "instruction"),
         { ...port("out", "main"), schema: aiEnvelope },
       ]),
       kind: "ai" as const,
@@ -481,6 +560,7 @@ describe("saveGraphBodySchema（kind 別ポート構成）", () => {
   it("ai の出力宣言が封筒型 { data, description } でないと拒否する（全出口に適用）", () => {
     const bad = makeNode([
       port("in", "in"),
+      port("in", "instruction"),
       { ...port("out", "main"), schema: { type: "object" } },
     ])
     expect(() =>
@@ -489,6 +569,7 @@ describe("saveGraphBodySchema（kind 別ポート構成）", () => {
     // main 以外の出口も封筒型を強制する
     const badExtra = makeNode([
       port("in", "in"),
+      port("in", "instruction"),
       { ...port("out", "main"), schema: aiEnvelope },
       { ...port("out", "extra"), schema: { type: "object" } },
     ])
@@ -498,6 +579,7 @@ describe("saveGraphBodySchema（kind 別ポート構成）", () => {
     // data は任意の型でよい（カタログ外の object も通る）
     const custom = makeNode([
       port("in", "in"),
+      port("in", "instruction"),
       {
         ...port("out", "main"),
         schema: envelopeSchemaOf({
@@ -514,32 +596,57 @@ describe("saveGraphBodySchema（kind 別ポート構成）", () => {
 })
 
 describe("saveGraphBodySchema（型の接続バリデーション）", () => {
-  it("human の reject → ai は許可、ai 以外は拒否", () => {
+  it("human の reject → ai の instruction は許可。ai の in や ai 以外は拒否", () => {
     const human = humanNode()
     const ai = aiNode()
     const prog = programNode()
+    const rejectPort = outByKey(human, "reject")
+    // 差し戻しは指示の口（instruction）へ
     expect(() =>
       saveGraphBodySchema.parse({
         nodes: [human, ai],
         connections: [
           {
-            from_port_id: outByKey(human, "reject").id,
-            to_port_id: inOf(ai).id,
+            from_port_id: rejectPort.id,
+            to_port_id: inByKey(ai, "instruction").id,
           },
         ],
       }),
     ).not.toThrow()
+    // 上流データの口（in）には繋げない（意味の違う入力を fan-in させない）
+    expect(() =>
+      saveGraphBodySchema.parse({
+        nodes: [human, ai],
+        connections: [
+          { from_port_id: rejectPort.id, to_port_id: inByKey(ai, "in").id },
+        ],
+      }),
+    ).toThrow(/instruction/)
+    // ai 以外にも繋げない
     expect(() =>
       saveGraphBodySchema.parse({
         nodes: [human, prog],
+        connections: [
+          { from_port_id: rejectPort.id, to_port_id: inOf(prog).id },
+        ],
+      }),
+    ).toThrow(/instruction/)
+  })
+
+  it("instruction ポートに繋げるのは human の reject だけ", () => {
+    const ai = aiNode()
+    const prog = programNode()
+    expect(() =>
+      saveGraphBodySchema.parse({
+        nodes: [prog, ai],
         connections: [
           {
-            from_port_id: outByKey(human, "reject").id,
-            to_port_id: inOf(prog).id,
+            from_port_id: outOf(prog).id,
+            to_port_id: inByKey(ai, "instruction").id,
           },
         ],
       }),
-    ).toThrow(/reject.*AI ノードのみ/)
+    ).toThrow(/instruction ポートに接続できるのは/)
   })
 
   it("human の in はどの型でも接続できる（封筒型の制約は課さない）", () => {
@@ -870,3 +977,85 @@ describe("refsDefaultsOf（定義スキーマ→デフォルト値の袋）", ()
     expect(refsDefaultsOf({ type: "object", properties: {} })).toEqual({})
   })
 })
+
+describe("saveGraphBodySchema：コンポーネントノード（component kind）", () => {
+  // コンポーネント＝kind='component' の loop を配置して呼ぶノード。ポートは
+  // in/main 固定で、スキーマは子 loop の契約から保存時にサーバが焼き込む（宣言扱い）
+  const componentNode = (
+    inSchema: GraphPort["schema"] = { type: "object" },
+  ) => ({
+    ...makeNode([
+      { ...port("in", "in"), schema: inSchema },
+      port("out", "main"),
+    ]),
+    kind: "component" as const,
+    component: { component_loop_id: uuid() },
+  })
+
+  it("component ノード（in/main＋component_loop_id）を受け付ける", () => {
+    expect(() =>
+      saveGraphBodySchema.parse({ nodes: [componentNode()], connections: [] }),
+    ).not.toThrow()
+  })
+
+  it("component_loop_id の無い component ノードを拒否する", () => {
+    const node = { ...componentNode(), component: undefined }
+    expect(() =>
+      saveGraphBodySchema.parse({ nodes: [node], connections: [] }),
+    ).toThrow(/component_loop_id/)
+  })
+
+  it("ポート構成は in/main 固定（out の key 違い・複数 out を拒否）", () => {
+    const badKey = {
+      ...componentNode(),
+      ports: [port("in", "in"), port("out", "result")],
+    }
+    expect(() =>
+      saveGraphBodySchema.parse({ nodes: [badKey], connections: [] }),
+    ).toThrow(/component のポート構成/)
+    const multiOut = {
+      ...componentNode(),
+      ports: [port("in", "in"), port("out", "main"), port("out", "sub")],
+    }
+    expect(() =>
+      saveGraphBodySchema.parse({ nodes: [multiOut], connections: [] }),
+    ).toThrow(/component のポート構成/)
+  })
+
+  it("component の in への接続は契約への適合を検証する（伝播型 ⊆ 契約）", () => {
+    // 上流 program の out {type:"string"} → component の in {type:"number"} は不適合
+    const prog = {
+      ...makeNode([
+        port("in", "in"),
+        { ...port("out", "main"), schema: { type: "string" } },
+      ]),
+      kind: "program" as const,
+    }
+    const comp = componentNode({ type: "number" })
+    expect(() =>
+      saveGraphBodySchema.parse({
+        nodes: [prog, comp],
+        connections: [connect(prog, comp)],
+      }),
+    ).toThrow(/入力契約に適合しません/)
+    // 適合（string → string）なら通る
+    const okComp = componentNode({ type: "string" })
+    expect(() =>
+      saveGraphBodySchema.parse({
+        nodes: [prog, okComp],
+        connections: [connect(prog, okComp)],
+      }),
+    ).not.toThrow()
+  })
+
+  it("component の in の宣言スキーマは接続で潰されない（導出/鏡映扱いにしない）", () => {
+    const contract = {
+      type: "object",
+      properties: { pr_urls: { type: "array" } },
+      required: ["pr_urls"],
+    }
+    const comp = componentNode(contract)
+    const resolved = resolvePortSchemas([comp], [])
+    expect(resolved.get(inOf(comp).id)).toEqual(contract)
+  })
+})

package/_schemas/graph.ts

@@ -6,10 +6,13 @@ import {
   portKeySchema,
 } from "./node.js"
 import {
+  AI_INSTRUCTION_PORT_KEY,
+  hasInboundConflict,
   isAiEnvelopeSchema,
   isSchemaSubset,
   kindPortsViolation,
   resolvePortSchemas,
+  UNDECLARED_SCHEMA,
 } from "./port-spec.js"
 
 // refs＝ループ変数の袋（key→任意の JSON 値。上流出力の参照（refs）.md）。
@@ -72,6 +75,7 @@ export const graphNodeKindSchema = nodeKindSchema.extract([
   "wait",
   "start",
   "end",
+  "component",
 ])
 export type GraphNodeKind = z.infer<typeof graphNodeKindSchema>
 
@@ -133,6 +137,12 @@ export type AiConfig = z.infer<typeof aiConfigSchema>
 // メンバーが tenant の membership であることの検証は保存 API 側で行う
 // （docs/tasks/backlog/Human担当者の高度化（複数人承認とラウンドロビン）.md）
 export const humanConfigSchema = z.object({
+  // 承認 UI（承認ビュー）の識別子。program_dir / ai_dir と同じ「不透明なキー」で、
+  // どのキーが実在するか・そのテナントが選べるかは保存時に mawaru 側が検証する
+  // （カタログは非公開。@mawaru/common の approval-view.ts）。省略時は標準ビュー
+  view: z.string().min(1).optional(),
+  // ビューに渡すパラメータ（列・ラベル・閾値など）。形はビューごとに違うので任意の JSON
+  view_config: z.unknown().nullish(),
   assignment: z
     .object({
       strategy: z.enum(["fixed", "round_robin"]).default("fixed"),
@@ -171,6 +181,14 @@ export const humanConfigSchema = z.object({
 })
 export type HumanConfig = z.infer<typeof humanConfigSchema>
 
+// コンポーネントノードの kind 別設定（node_components に対応）。呼ぶ先は
+// kind='component' の loop。同 tenant・kind の検証と自 loop 参照の禁止は保存 API 側で行う
+// （docs/tasks/wip/コンポーネント（ループの部品化と再利用）.md）
+export const componentConfigSchema = z.object({
+  component_loop_id: z.uuid(),
+})
+export type ComponentConfig = z.infer<typeof componentConfigSchema>
+
 // ノードにアタッチされた IOHook（node_hooks に対応。アタッチできるのは program ノードのみ）。
 // on_input / on_output / on_signal はアタッチ時に repo の config.json（hookManifestSchema）から
 // エディタが焼き込むスナップショット。ref 省略時はデフォルトブランチ
@@ -206,6 +224,7 @@ export const graphNodeSchema = z.object({
   program: programConfigSchema.optional(),
   ai: aiConfigSchema.optional(),
   human: humanConfigSchema.optional(),
+  component: componentConfigSchema.optional(),
 })
 export type GraphNode = z.infer<typeof graphNodeSchema>
 
@@ -279,16 +298,20 @@ export const saveGraphBodySchema = z
         if (port.io === "in") inCount++
         else outCount++
       })
-      // end だけ「in は1つ以上」（複数ルートを別々の in で集約する）。
-      // start・他 kind は従来どおり1つ固定
-      if (node.kind === "end" ? inCount < 1 : inCount !== 1) {
+      // end は「in は1つ以上」（複数ルートを別々の in で集約する）。
+      // ai は2つ（上流データの in ＋ 差し戻しの instruction）。他 kind は1つ固定。
+      // key の妥当性は kindPortsViolation が別途見る
+      const expectIn = node.kind === "ai" ? 2 : 1
+      const inCountOk =
+        node.kind === "end" ? inCount >= 1 : inCount === expectIn
+      if (!inCountOk) {
         ctx.addIssue({
           code: "custom",
           path: ["nodes", i, "ports"],
           message:
             node.kind === "end"
               ? "in ポートが1つ以上必要です"
-              : "in ポートはちょうど1つ必要です",
+              : `in ポートはちょうど${expectIn}つ必要です`,
         })
       }
       if (outCount < 1) {
@@ -321,6 +344,16 @@ export const saveGraphBodySchema = z
         hookDirs.add(hook.hook_dir)
       })
 
+      // component は参照先が無いと成立しない（他 kind の設定はデフォルトで補えるが
+      // component_loop_id は補えない）
+      if (node.kind === "component" && node.component === undefined) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["nodes", i, "component"],
+          message: "component ノードには component_loop_id が必要です",
+        })
+      }
+
       // kind 別のポート構成（program 以外は数・key・io 固定。ポートのkind別仕様.md）
       const violation = kindPortsViolation(node.kind, node.ports)
       if (violation) {
@@ -353,7 +386,7 @@ export const saveGraphBodySchema = z
     const usedPairs = new Set<string>()
     graph.connections.forEach((conn, i) => {
       const from = portById.get(conn.from_port_id)
-      if (!from || from.io !== "out") {
+      if (from?.io !== "out") {
         ctx.addIssue({
           code: "custom",
           path: ["connections", i, "from_port_id"],
@@ -361,7 +394,7 @@ export const saveGraphBodySchema = z
         })
       }
       const to = portById.get(conn.to_port_id)
-      if (!to || to.io !== "in") {
+      if (to?.io !== "in") {
         ctx.addIssue({
           code: "custom",
           path: ["connections", i, "to_port_id"],
@@ -382,6 +415,31 @@ export const saveGraphBodySchema = z
     // 型の接続バリデーション（ポートのkind別仕様.md §接続バリデーション）。
     // 導出ポートは接続から型を解決した上で判定する。ai の in・wait の in は常に許可
     const resolved = resolvePortSchemas(graph.nodes, graph.connections)
+
+    // fan-in（同じ in ポートへの流入が2本以上）は同じ型でなければならない。
+    // 型が割れていると伝播が未宣言に落ちて下流の型チェックが効かなくなる
+    // （docs/tasks/wip/ポートスキーマのany撲滅.md）
+    const inboundByPort = new Map<string, string[]>()
+    for (const conn of graph.connections) {
+      const list = inboundByPort.get(conn.to_port_id) ?? []
+      list.push(conn.from_port_id)
+      inboundByPort.set(conn.to_port_id, list)
+    }
+    for (const [toPortId, fromPortIds] of inboundByPort) {
+      if (fromPortIds.length < 2) continue
+      const schemas = fromPortIds.map(
+        (id) => resolved.get(id) ?? UNDECLARED_SCHEMA,
+      )
+      if (!hasInboundConflict(schemas)) continue
+      const to = portById.get(toPortId)
+      const toNode = nodeByPortId.get(toPortId)
+      ctx.addIssue({
+        code: "custom",
+        path: ["connections"],
+        message: `同じ入力ポート（${toNode?.name ?? "?"}.${to?.key ?? "?"}）に異なる型を接続できません`,
+      })
+    }
+
     graph.connections.forEach((conn, i) => {
       const from = portById.get(conn.from_port_id)
       const to = portById.get(conn.to_port_id)
@@ -405,16 +463,33 @@ export const saveGraphBodySchema = z
         })
       }
 
-      // human の reject の接続先は ai ノードのみ（kind 制約）
+      // human の reject の接続先は AI の instruction ポートのみ。
+      // 差し戻しは「元のセッションに指示を与える」操作で、上流データの口（in）とは
+      // 意味が違う（docs/tasks/wip/ポートスキーマのany撲滅.md）
       if (
         fromNode.kind === "human" &&
         from.key === "reject" &&
-        toNode.kind !== "ai"
+        !(toNode.kind === "ai" && to.key === AI_INSTRUCTION_PORT_KEY)
       ) {
         ctx.addIssue({
           code: "custom",
           path: ["connections", i, "to_port_id"],
-          message: "差し戻し（reject）の接続先は AI ノードのみです",
+          message:
+            "差し戻し（reject）の接続先は AI ノードの instruction ポートのみです",
+        })
+      }
+
+      // instruction ポートに繋げるのは human の reject だけ（データを流し込ませない）
+      if (
+        toNode.kind === "ai" &&
+        to.key === AI_INSTRUCTION_PORT_KEY &&
+        !(fromNode.kind === "human" && from.key === "reject")
+      ) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["connections", i, "to_port_id"],
+          message:
+            "instruction ポートに接続できるのは human の差し戻し（reject）だけです",
         })
       }
 
@@ -424,7 +499,8 @@ export const saveGraphBodySchema = z
       // それ以外は input 全体を data として表示する。型制約は課さない）
 
       // program の in への接続は 伝播型 ⊆ 宣言スキーマ。in は接続鏡映（sticky）なので
-      // 具体型の接続では自明に通り、接続元 any × 宣言維持のときだけ従来の意味を持つ
+      // 具体型の接続では自明に通り、接続元が未宣言 × 宣言維持のときだけ従来の意味を持つ
+      // （未宣言は unknown＝判断できないので通す。作りかけのグラフを保存できなくしない）
       const toSchema = resolved.get(conn.to_port_id) ?? to.schema
       if (toNode.kind === "program" && !isSchemaSubset(fromSchema, toSchema)) {
         ctx.addIssue({
@@ -434,6 +510,19 @@ export const saveGraphBodySchema = z
             "接続元の型が program の入力スキーマに適合しません（伝播型 ⊆ 宣言スキーマ）",
         })
       }
+
+      // component の in は子 loop の契約（焼き込み済み宣言）。program と同じ包含チェック
+      if (
+        toNode.kind === "component" &&
+        !isSchemaSubset(fromSchema, toSchema)
+      ) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["connections", i, "to_port_id"],
+          message:
+            "接続元の型がコンポーネントの入力契約に適合しません（伝播型 ⊆ 契約）",
+        })
+      }
     })
   })
 export type SaveGraphBody = z.infer<typeof saveGraphBodySchema>

package/_schemas/node.ts

@@ -10,6 +10,9 @@ export const nodeKindSchema = z.enum([
   // docs/tasks/wip/開始・終了ノードの定義.md）
   "start",
   "end",
+  // コンポーネント（kind='component' の loop を配置して呼ぶ。子 run・戻り値あり。
+  // docs/tasks/wip/コンポーネント（ループの部品化と再利用）.md）
+  "component",
 ])
 export type NodeKind = z.infer<typeof nodeKindSchema>