@mawaru/sdk 0.5.0 → 0.9.0

package/_schemas/port-spec.test.ts

@@ -1,18 +1,22 @@
 import { describe, expect, it } from "vitest"
 import type { GraphPort, JsonSchema } from "./node.js"
 import {
-  ANY_SCHEMA,
   dataFormatOf,
   dataSchemaOf,
   envelopeDataSchemaOf,
   envelopeSchemaOf,
   fileSchema,
+  hasInboundConflict,
+  instructionSchema,
   isAiEnvelopeSchema,
   isFileSchema,
   isSchemaSubset,
   kindPortsViolation,
+  mergeInboundSchemas,
   propagateDerivedPorts,
   resolvePortSchemas,
+  schemaFit,
+  UNDECLARED_SCHEMA,
 } from "./port-spec.js"
 
 let seq = 0
@@ -27,7 +31,7 @@ const port = (
   io,
   key,
   name: key,
-  schema: schema ?? ANY_SCHEMA,
+  schema: schema ?? UNDECLARED_SCHEMA,
 })
 
 describe("データフォーマットカタログ（S）", () => {
@@ -107,7 +111,7 @@ describe("封筒型 { data: T, description: string }", () => {
       }),
     ).toBeNull()
     expect(envelopeDataSchemaOf({ type: "string" })).toBeNull()
-    expect(envelopeDataSchemaOf(ANY_SCHEMA)).toBeNull()
+    expect(envelopeDataSchemaOf(UNDECLARED_SCHEMA)).toBeNull()
   })
 
   it("isAiEnvelopeSchema：data と description: string の両方が必須のときだけ true", () => {
@@ -141,28 +145,33 @@ describe("封筒型 { data: T, description: string }", () => {
         required: ["data", "description"],
       }),
     ).toBe(false)
-    expect(isAiEnvelopeSchema(ANY_SCHEMA)).toBe(false)
+    expect(isAiEnvelopeSchema(UNDECLARED_SCHEMA)).toBe(false)
   })
 })
 
 describe("kindPortsViolation（kind 別ポート構成）", () => {
-  it("ai は out の key 自由・複数可。in の key だけ in 固定（AI の複数出口）", () => {
-    expect(
-      kindPortsViolation("ai", [port("in", "in"), port("out", "main")]),
-    ).toBeNull()
-    expect(
-      kindPortsViolation("ai", [port("in", "in"), port("out", "draft")]),
-    ).toBeNull()
+  it("ai は out の key 自由・複数可。in は in / instruction の2口固定（AI の複数出口）", () => {
+    const ins = [port("in", "in"), port("in", "instruction")]
+    expect(kindPortsViolation("ai", [...ins, port("out", "main")])).toBeNull()
+    expect(kindPortsViolation("ai", [...ins, port("out", "draft")])).toBeNull()
     expect(
       kindPortsViolation("ai", [
-        port("in", "in"),
+        ...ins,
         port("out", "spam"),
         port("out", "sales"),
         port("out", "support"),
       ]),
     ).toBeNull()
+    // instruction が無い・key が違うのは違反
+    expect(
+      kindPortsViolation("ai", [port("in", "in"), port("out", "main")]),
+    ).toMatch(/instruction/)
     expect(
-      kindPortsViolation("ai", [port("in", "input"), port("out", "main")]),
+      kindPortsViolation("ai", [
+        port("in", "input"),
+        port("in", "instruction"),
+        port("out", "main"),
+      ]),
     ).toMatch(/ai/)
   })
 
@@ -210,9 +219,13 @@ describe("kindPortsViolation（kind 別ポート構成）", () => {
 describe("型伝播（導出ポートの解決）", () => {
   const envelope = envelopeSchemaOf({ type: "string" })
 
-  it("ai → human 直結：approve は封筒を剥がした data 型、reject は content（any）", () => {
+  it("ai → human 直結：approve は封筒を剥がした data 型、reject は指示エンベロープ", () => {
     const aiOut = port("out", "main", envelope)
-    const ai = { id: uuid(), kind: "ai", ports: [port("in", "in"), aiOut] }
+    const ai = {
+      id: uuid(),
+      kind: "ai",
+      ports: [port("in", "in"), port("in", "instruction"), aiOut],
+    }
     const humanIn = port("in", "in")
     const approve = port("out", "approve")
     const reject = port("out", "reject")
@@ -227,10 +240,10 @@ describe("型伝播（導出ポートの解決）", () => {
     )
     expect(resolved.get(humanIn.id)).toEqual(envelope)
     expect(resolved.get(approve.id)).toEqual({ type: "string" })
-    expect(resolved.get(reject.id)).toEqual(ANY_SCHEMA)
+    expect(resolved.get(reject.id)).toEqual(instructionSchema())
   })
 
-  it("ai → wait → human：素通しで封筒型が伝播し、reject は content（any）のまま", () => {
+  it("ai → wait → human：素通しで封筒型が伝播し、reject は指示エンベロープのまま", () => {
     // ai の in は宣言型（nodes/ai/<dir>/config.json の inputs.in 由来。実行repoの構造見直し）
     const aiInSchema = {
       type: "object",
@@ -244,7 +257,11 @@ describe("型伝播（導出ポートの解決）", () => {
     const humanIn = port("in", "in")
     const approve = port("out", "approve")
     const reject = port("out", "reject")
-    const ai = { id: uuid(), kind: "ai", ports: [aiIn, aiOut] }
+    const ai = {
+      id: uuid(),
+      kind: "ai",
+      ports: [aiIn, port("in", "instruction"), aiOut],
+    }
     const wait = { id: uuid(), kind: "wait", ports: [waitIn, waitOut] }
     const human = {
       id: uuid(),
@@ -261,7 +278,7 @@ describe("型伝播（導出ポートの解決）", () => {
     expect(resolved.get(humanIn.id)).toEqual(envelope)
     // 封筒剥がしは「in の直接の接続元が AI ノード」のときだけ。wait 越しは素通し
     expect(resolved.get(approve.id)).toEqual(envelope)
-    expect(resolved.get(reject.id)).toEqual(ANY_SCHEMA)
+    expect(resolved.get(reject.id)).toEqual(instructionSchema())
     // ai の in は宣言型がそのまま残る（const 扱いは廃止）
     expect(resolved.get(aiIn.id)).toEqual(aiInSchema)
   })
@@ -281,8 +298,8 @@ describe("型伝播（導出ポートの解決）", () => {
         { from_port_id: out2.id, to_port_id: in1.id },
       ],
     )
-    expect(resolved.get(out1.id)).toEqual(ANY_SCHEMA)
-    expect(resolved.get(out2.id)).toEqual(ANY_SCHEMA)
+    expect(resolved.get(out1.id)).toEqual(UNDECLARED_SCHEMA)
+    expect(resolved.get(out2.id)).toEqual(UNDECLARED_SCHEMA)
   })
 
   it("program の in は接続鏡映（sticky）：具体型の接続元だけ上書きする", () => {
@@ -292,7 +309,11 @@ describe("型伝播（導出ポートの解決）", () => {
       required: ["inquiry"],
     }
     const aiOut = port("out", "main", envelope)
-    const ai = { id: uuid(), kind: "ai", ports: [port("in", "in"), aiOut] }
+    const ai = {
+      id: uuid(),
+      kind: "ai",
+      ports: [port("in", "in"), port("in", "instruction"), aiOut],
+    }
     const progIn = port("in", "in", declared)
     const program = {
       id: uuid(),
@@ -318,7 +339,11 @@ describe("型伝播（導出ポートの解決）", () => {
       ports: [port("in", "in"), progOut],
     }
     const aiIn = port("in", "in", declared)
-    const ai = { id: uuid(), kind: "ai", ports: [aiIn, port("out", "main")] }
+    const ai = {
+      id: uuid(),
+      kind: "ai",
+      ports: [aiIn, port("in", "instruction"), port("out", "main")],
+    }
     // 具体型の接続元 → 上書き（接続両端の同値同期）
     const resolved = resolvePortSchemas(
       [program, ai],
@@ -333,7 +358,11 @@ describe("型伝播（導出ポートの解決）", () => {
       ports: [port("in", "in"), waitOut],
     }
     const aiIn2 = port("in", "in", declared)
-    const ai2 = { id: uuid(), kind: "ai", ports: [aiIn2, port("out", "main")] }
+    const ai2 = {
+      id: uuid(),
+      kind: "ai",
+      ports: [aiIn2, port("in", "instruction"), port("out", "main")],
+    }
     const kept = resolvePortSchemas(
       [wait, ai2],
       [{ from_port_id: waitOut.id, to_port_id: aiIn2.id }],
@@ -373,7 +402,11 @@ describe("型伝播（導出ポートの解決）", () => {
 
   it("program の in：wait 越しでも具体型が鏡映される（固定点反復）", () => {
     const aiOut = port("out", "main", envelope)
-    const ai = { id: uuid(), kind: "ai", ports: [port("in", "in"), aiOut] }
+    const ai = {
+      id: uuid(),
+      kind: "ai",
+      ports: [port("in", "in"), port("in", "instruction"), aiOut],
+    }
     const waitIn = port("in", "in")
     const waitOut = port("out", "main")
     const wait = { id: uuid(), kind: "wait", ports: [waitIn, waitOut] }
@@ -437,8 +470,8 @@ describe("型伝播（導出ポートの解決）", () => {
     const outMain = port("out", "main", { type: "object" })
     const start = { id: uuid(), kind: "start", ports: [inPort, outMain] }
     const resolved = resolvePortSchemas([start], [])
-    expect(resolved.get(outMain.id)).toEqual(ANY_SCHEMA)
-    expect(resolved.get(inPort.id)).toEqual(ANY_SCHEMA)
+    expect(resolved.get(outMain.id)).toEqual(UNDECLARED_SCHEMA)
+    expect(resolved.get(inPort.id)).toEqual(UNDECLARED_SCHEMA)
   })
 
   it("start：fan-out で非 any が1種類（program＋導出 wait）ならそれを採用し、wait へも流れる", () => {
@@ -483,8 +516,8 @@ describe("型伝播（導出ポートの解決）", () => {
         { from_port_id: start.outMain.id, to_port_id: b.inPort.id },
       ],
     )
-    expect(resolved.get(start.outMain.id)).toEqual(ANY_SCHEMA)
-    expect(resolved.get(start.inPort.id)).toEqual(ANY_SCHEMA)
+    expect(resolved.get(start.outMain.id)).toEqual(UNDECLARED_SCHEMA)
+    expect(resolved.get(start.inPort.id)).toEqual(UNDECLARED_SCHEMA)
   })
 
   it("start：宣言を持たない経路（start → wait → …）は any（パラメトリック閉路の割り切り）", () => {
@@ -496,8 +529,8 @@ describe("型伝播（導出ポートの解決）", () => {
       [start.node, wait],
       [{ from_port_id: start.outMain.id, to_port_id: waitIn.id }],
     )
-    expect(resolved.get(start.inPort.id)).toEqual(ANY_SCHEMA)
-    expect(resolved.get(start.outMain.id)).toEqual(ANY_SCHEMA)
+    expect(resolved.get(start.inPort.id)).toEqual(UNDECLARED_SCHEMA)
+    expect(resolved.get(start.outMain.id)).toEqual(UNDECLARED_SCHEMA)
   })
 
   it("propagateDerivedPorts：schema を書き戻し、変化のないノードは同じ参照を返す", () => {
@@ -522,8 +555,8 @@ describe("型伝播（導出ポートの解決）", () => {
     // 接続を消すと any に戻る
     const cleared = propagateDerivedPorts(next, [])
     expect(cleared[1]?.ports.map((p) => p.schema)).toEqual([
-      ANY_SCHEMA,
-      ANY_SCHEMA,
+      UNDECLARED_SCHEMA,
+      UNDECLARED_SCHEMA,
     ])
   })
 
@@ -552,6 +585,73 @@ describe("型伝播（導出ポートの解決）", () => {
   })
 })
 
+describe("型伝播：fan-in（同じ in ポートへの流入2本以上）", () => {
+  const str = { type: "string" } as const
+  const num = { type: "number" } as const
+
+  // program の out は宣言型なので、fan-in の元として具体型を持たせられる
+  const source = (schema: Record<string, unknown>) => {
+    const out = port("out", "main", schema)
+    return {
+      node: { id: uuid(), kind: "program", ports: [port("in", "in"), out] },
+      out,
+    }
+  }
+  const sink = () => {
+    const inPort = port("in", "in")
+    const out = port("out", "main")
+    return {
+      node: { id: uuid(), kind: "wait", ports: [inPort, out] },
+      inPort,
+      out,
+    }
+  }
+
+  it("流入が全部同じ型ならその型が伝播する（従来は any に落ちていた）", () => {
+    const a = source(str)
+    const b = source(str)
+    const w = sink()
+    const resolved = resolvePortSchemas(
+      [a.node, b.node, w.node],
+      [
+        { from_port_id: a.out.id, to_port_id: w.inPort.id },
+        { from_port_id: b.out.id, to_port_id: w.inPort.id },
+      ],
+    )
+    expect(resolved.get(w.inPort.id)).toEqual(str)
+    // 素通しなので下流にも伝わる
+    expect(resolved.get(w.out.id)).toEqual(str)
+  })
+
+  it("具体型1種類＋未宣言 の混在は、その具体型が採用される", () => {
+    const a = source(str)
+    const b = sink() // out main は導出＝未宣言
+    const w = sink()
+    const resolved = resolvePortSchemas(
+      [a.node, b.node, w.node],
+      [
+        { from_port_id: a.out.id, to_port_id: w.inPort.id },
+        { from_port_id: b.out.id, to_port_id: w.inPort.id },
+      ],
+    )
+    expect(resolved.get(w.inPort.id)).toEqual(str)
+  })
+
+  it("型が割れているときは未宣言に落ちる（保存時に graph が弾く）", () => {
+    const a = source(str)
+    const b = source(num)
+    const w = sink()
+    const resolved = resolvePortSchemas(
+      [a.node, b.node, w.node],
+      [
+        { from_port_id: a.out.id, to_port_id: w.inPort.id },
+        { from_port_id: b.out.id, to_port_id: w.inPort.id },
+      ],
+    )
+    expect(resolved.get(w.inPort.id)).toEqual(UNDECLARED_SCHEMA)
+  })
+})
+
 describe("file 型（nominal）", () => {
   it("fileSchema はマーカー付き object、isFileSchema で識別できる", () => {
     const schema = fileSchema()
@@ -579,8 +679,8 @@ describe("file 型（nominal）", () => {
     // file ↔ file
     expect(isSchemaSubset(file, fileSchema())).toBe(true)
     // file → any / any → file
-    expect(isSchemaSubset(file, ANY_SCHEMA)).toBe(true)
-    expect(isSchemaSubset(ANY_SCHEMA, file)).toBe(true)
+    expect(isSchemaSubset(file, UNDECLARED_SCHEMA)).toBe(true)
+    expect(isSchemaSubset(UNDECLARED_SCHEMA, file)).toBe(true)
     // 構造が同じだけの object は file に繋がない（nominal）
     expect(isSchemaSubset(lookalike, file)).toBe(false)
     expect(isSchemaSubset(file, lookalike)).toBe(false)
@@ -596,8 +696,8 @@ describe("file 型（nominal）", () => {
 
 describe("isSchemaSubset（伝播型 ⊆ 宣言スキーマ）", () => {
   it("any はどちら向きも許可", () => {
-    expect(isSchemaSubset(ANY_SCHEMA, { type: "object" })).toBe(true)
-    expect(isSchemaSubset({ type: "object" }, ANY_SCHEMA)).toBe(true)
+    expect(isSchemaSubset(UNDECLARED_SCHEMA, { type: "object" })).toBe(true)
+    expect(isSchemaSubset({ type: "object" }, UNDECLARED_SCHEMA)).toBe(true)
   })
 
   it("object：宣言側の required が伝播側に必須として存在し、型互換であること", () => {
@@ -655,3 +755,56 @@ describe("isSchemaSubset（伝播型 ⊆ 宣言スキーマ）", () => {
     ).toBe(false)
   })
 })
+
+describe("schemaFit（3値の型判定）", () => {
+  const str = { type: "string" } as const
+  const num = { type: "number" } as const
+
+  it("具体型どうしは ok / mismatch を返す", () => {
+    expect(schemaFit(str, str)).toBe("ok")
+    expect(schemaFit(str, num)).toBe("mismatch")
+  })
+
+  it("どちらかが未宣言なら unknown（適合とも不適合とも言わない）", () => {
+    expect(schemaFit(UNDECLARED_SCHEMA, str)).toBe("unknown")
+    expect(schemaFit(str, UNDECLARED_SCHEMA)).toBe("unknown")
+    expect(schemaFit(UNDECLARED_SCHEMA, UNDECLARED_SCHEMA)).toBe("unknown")
+  })
+
+  it("isSchemaSubset は unknown を通す（保存を止めない）", () => {
+    expect(isSchemaSubset(UNDECLARED_SCHEMA, str)).toBe(true)
+    expect(isSchemaSubset(str, num)).toBe(false)
+  })
+
+  it("file は nominal（file 同士だけ ok）", () => {
+    expect(schemaFit(fileSchema(), fileSchema())).toBe("ok")
+    expect(schemaFit({ type: "object" }, fileSchema())).toBe("mismatch")
+  })
+})
+
+describe("mergeInboundSchemas / hasInboundConflict（fan-in）", () => {
+  const str = { type: "string" } as const
+  const num = { type: "number" } as const
+
+  it("流入が全部同じ具体型ならその型を採用する", () => {
+    expect(mergeInboundSchemas([str, str])).toEqual(str)
+    expect(hasInboundConflict([str, str])).toBe(false)
+  })
+
+  it("具体型1種類＋未宣言 の混在は、その具体型を採用する", () => {
+    expect(mergeInboundSchemas([UNDECLARED_SCHEMA, str])).toEqual(str)
+    expect(hasInboundConflict([UNDECLARED_SCHEMA, str])).toBe(false)
+  })
+
+  it("具体型が2種類以上なら未宣言に落とし、衝突として検出する", () => {
+    expect(mergeInboundSchemas([str, num])).toEqual(UNDECLARED_SCHEMA)
+    expect(hasInboundConflict([str, num])).toBe(true)
+  })
+
+  it("すべて未宣言なら未宣言", () => {
+    expect(mergeInboundSchemas([UNDECLARED_SCHEMA, UNDECLARED_SCHEMA])).toEqual(
+      UNDECLARED_SCHEMA,
+    )
+    expect(hasInboundConflict([])).toBe(false)
+  })
+})