@mawaru/sdk 0.37.0 → 0.39.0

package/_schemas/ai-manifest.test.ts

@@ -145,6 +145,14 @@ describe("aiManifestSchema", () => {
     expect(parsed.inputs.instruction?.resume).toBe(true)
   })
 
+  it("inputs の flexible（推奨型を維持して任意の型を受ける）が読める", () => {
+    const parsed = aiManifestSchema.parse({
+      ...valid,
+      inputs: { in: { schema: { type: "object" }, flexible: true } },
+    })
+    expect(parsed.inputs.in?.flexible).toBe(true)
+  })
+
   it("旧形式（値が素の JSON Schema）は { schema: 値 } として読める", () => {
     const legacy = aiManifestSchema.parse({
       ...valid,

package/_schemas/ai-manifest.ts

@@ -72,6 +72,8 @@ export const agentOfModel = (model: AiModel): AiAgentId =>
 export const aiInputDeclSchema = z.object({
   schema: jsonSchemaSchema,
   resume: z.boolean().optional(),
+  // 推奨型を維持して任意の型を受ける（接続で上書きされず、適合チェックもしない）
+  flexible: z.boolean().optional(),
 })
 export type AiInputDecl = z.infer<typeof aiInputDeclSchema>
 

package/_schemas/graph.test.ts

@@ -1203,6 +1203,42 @@ describe("saveGraphBodySchema：コンポーネントノード（component kind
     ).not.toThrow()
   })
 
+  it("flexible な in（契約で焼き込まれた component.in・AI の宣言 in）への接続は型が違っても保存できる", () => {
+    const prog = {
+      ...makeNode([
+        port("in", "in"),
+        { ...port("out", "main"), schema: { type: "string" } },
+      ]),
+      kind: "program" as const,
+    }
+    const comp = {
+      ...componentNode({ type: "number" }),
+    }
+    comp.ports = comp.ports.map((p) =>
+      p.io === "in" ? { ...p, flexible: true } : p,
+    )
+    expect(() =>
+      saveGraphBodySchema.parse({
+        nodes: [prog, comp],
+        connections: [connect(prog, comp)],
+      }),
+    ).not.toThrow()
+    // AI の flexible な in：鏡映されず推奨型 {type:"number"} が残るが、型が違う接続を通す
+    const ai = {
+      ...makeNode([
+        { ...port("in", "in"), schema: { type: "number" }, flexible: true },
+        port("out", "main"),
+      ]),
+      kind: "ai" as const,
+    }
+    expect(() =>
+      saveGraphBodySchema.parse({
+        nodes: [prog, ai],
+        connections: [connect(prog, ai)],
+      }),
+    ).not.toThrow()
+  })
+
   it("component の in への接続は契約への適合を検証する（伝播型 ⊆ 契約）", () => {
     // 上流 program の out {type:"string"} → component の in {type:"number"} は不適合
     const prog = {

package/_schemas/graph.ts

@@ -6,8 +6,8 @@ import {
   portKeySchema,
 } from "./node.js"
 import {
+  connectionAccepted,
   hasInboundConflict,
-  isSchemaSubset,
   kindPortsViolation,
   resolvePortSchemas,
   UNDECLARED_SCHEMA,
@@ -551,9 +551,10 @@ export const saveGraphBodySchema = z
       // 接続鏡映する口（program / ai の in）とコピー宣言のビューは接続元の型を採用する
       // ので自明に通り、実質の検証対象は宣言で固定された口
       // （component の契約・宣言のあるビューの human.in）になる
+      // flexible な in（AI の宣言 in・契約で焼き込まれた component の in）は型を問わない
       const fromSchema = resolved.get(conn.from_port_id) ?? from.schema
       const toSchema = resolved.get(conn.to_port_id) ?? to.schema
-      if (!isSchemaSubset(fromSchema, toSchema)) {
+      if (!connectionAccepted(fromSchema, { ...to, schema: toSchema })) {
         ctx.addIssue({
           code: "custom",
           path: ["connections", i, "to_port_id"],

package/_schemas/node.ts

@@ -54,6 +54,10 @@ export const graphPortSchema = z
     // 再開する（AI ノードで意味を持つ。key ではなくこの属性が再開を決める。
     // ポート型固定の撤去とセッション再開のポート属性化.md）
     resume: z.boolean().optional(),
+    // in ポートの型属性：true なら宣言（推奨型）を維持し、接続元の型による上書き・
+    // 適合チェックをしない（AI の in で設定。start / component へは導出で流れる。
+    // AIノード入力のflexible属性（任意の型で呼べるループ）.md）
+    flexible: z.boolean().optional(),
     side: portSideSchema.optional(),
     offset: z.number().min(0).max(1).optional(),
   })

package/_schemas/port-spec.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest"
 import type { GraphPort, JsonSchema } from "./node.js"
 import {
   arrayOf,
+  connectionAccepted,
   dataFormatOf,
   dataSchemaOf,
   fileSchema,
@@ -12,6 +13,7 @@ import {
   kindPortsViolation,
   mergeInboundSchemas,
   propagateDerivedPorts,
+  resolveFlexiblePorts,
   resolvePortSchemas,
   schemaFit,
   schemaTypeKey,
@@ -661,6 +663,128 @@ describe("型伝播（導出ポートの解決）", () => {
     expect(resolved.get(start.outMain.id)).toEqual(UNDECLARED_SCHEMA)
   })
 
+  // flexible：AI の in の型属性。宣言（推奨型）を維持し、接続の型を問わない。
+  // start へは型と同じ経路で導出される（AIノード入力のflexible属性（任意の型で呼べるループ）.md）
+  describe("flexible（推奨型を維持して任意の型を受ける in）", () => {
+    const flexibleAi = (declared: JsonSchema) => {
+      const inPort: GraphPort = {
+        ...port("in", "in", declared),
+        flexible: true,
+      }
+      return {
+        node: { id: uuid(), kind: "ai", ports: [inPort, port("out", "main")] },
+        inPort,
+      }
+    }
+    const recommended = {
+      type: "object",
+      properties: { prompt: { type: "string" } },
+      required: ["prompt"],
+    }
+
+    it("flexible な in は接続元の具体型で上書きしない（宣言＝推奨型を維持）", () => {
+      const program = programNode({ type: "string" })
+      const progOut = program.node.ports.find(
+        (p) => p.io === "out",
+      ) as GraphPort
+      progOut.schema = declaredOut
+      const ai = flexibleAi(recommended)
+      const resolved = resolvePortSchemas(
+        [program.node, ai.node],
+        [{ from_port_id: progOut.id, to_port_id: ai.inPort.id }],
+      )
+      expect(resolved.get(ai.inPort.id)).toEqual(recommended)
+    })
+
+    it("flexible な in は型の割れた fan-in でも推奨型を維持する", () => {
+      const a = programNode({ type: "string" })
+      const aOut = a.node.ports.find((p) => p.io === "out") as GraphPort
+      aOut.schema = { type: "string" }
+      const b = programNode({ type: "string" })
+      const bOut = b.node.ports.find((p) => p.io === "out") as GraphPort
+      bOut.schema = { type: "number" }
+      const ai = flexibleAi(recommended)
+      const resolved = resolvePortSchemas(
+        [a.node, b.node, ai.node],
+        [
+          { from_port_id: aOut.id, to_port_id: ai.inPort.id },
+          { from_port_id: bOut.id, to_port_id: ai.inPort.id },
+        ],
+      )
+      expect(resolved.get(ai.inPort.id)).toEqual(recommended)
+    })
+
+    it("start → AI(flexible) 直結：start の in / out main が推奨型で flexible になる", () => {
+      const start = startNode()
+      const ai = flexibleAi(recommended)
+      const connections = [
+        { from_port_id: start.outMain.id, to_port_id: ai.inPort.id },
+      ]
+      expect(resolveFlexiblePorts([start.node, ai.node], connections)).toEqual(
+        new Set([start.inPort.id, start.outMain.id]),
+      )
+      const propagated = propagateDerivedPorts(
+        [start.node, ai.node],
+        connections,
+      )[0]
+      if (!propagated) throw new Error("start not propagated")
+      for (const p of propagated.ports) {
+        expect(p.schema).toEqual(recommended)
+        expect(p.flexible).toBe(true)
+      }
+    })
+
+    it("start → [AI(flexible), program]：非 flexible の接続先が混ざれば start は flexible にならない", () => {
+      const start = startNode()
+      const ai = flexibleAi(recommended)
+      const program = programNode(recommended)
+      const connections = [
+        { from_port_id: start.outMain.id, to_port_id: ai.inPort.id },
+        { from_port_id: start.outMain.id, to_port_id: program.inPort.id },
+      ]
+      expect(
+        resolveFlexiblePorts([start.node, ai.node, program.node], connections),
+      ).toEqual(new Set())
+    })
+
+    it("start：未接続なら flexible にならず、ports に残った古い flexible は落とす", () => {
+      const inPort: GraphPort = { ...port("in", "in"), flexible: true }
+      const outMain: GraphPort = { ...port("out", "main"), flexible: true }
+      const start = { id: uuid(), kind: "start", ports: [inPort, outMain] }
+      const propagated = propagateDerivedPorts([start], [])[0]
+      if (!propagated) throw new Error("start not propagated")
+      for (const p of propagated.ports) expect(p.flexible).toBeUndefined()
+    })
+
+    it("component の in（契約の焼き込みで flexible）に直結した start も flexible（推移）", () => {
+      const start = startNode()
+      const compIn: GraphPort = {
+        ...port("in", "in", recommended),
+        flexible: true,
+      }
+      const component = {
+        id: uuid(),
+        kind: "component",
+        ports: [compIn, port("out", "main")],
+      }
+      expect(
+        resolveFlexiblePorts(
+          [start.node, component],
+          [{ from_port_id: start.outMain.id, to_port_id: compIn.id }],
+        ),
+      ).toEqual(new Set([start.inPort.id, start.outMain.id]))
+    })
+
+    it("connectionAccepted：受け側が flexible なら型を問わず可、そうでなければ isSchemaSubset", () => {
+      const to = port("in", "in", recommended)
+      expect(connectionAccepted({ type: "string" }, to)).toBe(false)
+      expect(
+        connectionAccepted({ type: "string" }, { ...to, flexible: true }),
+      ).toBe(true)
+      expect(connectionAccepted(recommended, to)).toBe(true)
+    })
+  })
+
   it("propagateDerivedPorts：schema を書き戻し、変化のないノードは同じ参照を返す", () => {
     const progOut = port("out", "main", declaredOut)
     const program = {

package/_schemas/port-spec.ts

@@ -487,6 +487,8 @@ export const resolvePortSchemas = <N extends PropagationNode>(
       if (isMirror) {
         for (const port of node.ports) {
           if (port.io !== "in") continue
+          // flexible な in は宣言（推奨型）を維持する（接続の型を問わない口）
+          if (port.flexible === true) continue
           const sources = inbound.get(port.id) ?? []
           const inSchema = mergeInboundSchemas(
             sources.map((id) => resolved.get(id) ?? UNDECLARED_SCHEMA),
@@ -535,19 +537,82 @@ export const resolvePortSchemas = <N extends PropagationNode>(
 
 // ノード配列へ伝播結果を書き戻す（接続変更時のポートデータ自動更新）。
 // schema が変わらないポート・ノードは同じ参照を返す
+// flexible の導出：start の in / out main は、接続先の in が1つ以上あり**全て** flexible
+// （AI の宣言 in・契約で焼き込まれた component の in）のときだけ flexible。
+// 非 flexible の接続先（program 等）が1つでも混ざれば型どおりの入力が要るので false。
+// 直結のみ（wait 等の素通し経由は型と同じく流さない）。戻りは flexible になる port_id の集合
+export const resolveFlexiblePorts = (
+  nodes: PropagationNode[],
+  connections: PortLink[],
+): Set<string> => {
+  const flexibleByPortId = new Map<string, boolean>()
+  for (const node of nodes) {
+    if (node.kind === "start") continue
+    for (const port of node.ports) {
+      if (port.io === "in")
+        flexibleByPortId.set(port.id, port.flexible === true)
+    }
+  }
+  const outbound = new Map<string, string[]>()
+  for (const conn of connections) {
+    const outs = outbound.get(conn.from_port_id) ?? []
+    outs.push(conn.to_port_id)
+    outbound.set(conn.from_port_id, outs)
+  }
+  const flexible = new Set<string>()
+  for (const node of nodes) {
+    if (node.kind !== "start") continue
+    const inPort = node.ports.find((p) => p.io === "in")
+    const outMain = node.ports.find((p) => p.io === "out" && p.key === "main")
+    if (!inPort || !outMain) continue
+    const targets = outbound.get(outMain.id) ?? []
+    if (
+      targets.length > 0 &&
+      targets.every((id) => flexibleByPortId.get(id) === true)
+    ) {
+      flexible.add(inPort.id)
+      flexible.add(outMain.id)
+    }
+  }
+  return flexible
+}
+
+// 接続の型が受け入れられるか：受け側が flexible なら常に可、それ以外は 伝播型 ⊆ 宣言。
+// sdk の保存契約・backend の保存時チェック・エディタの表示はすべてこれを使う
+// （判定が散ると表示と保存がズレる）
+export const connectionAccepted = (
+  from: JsonSchema,
+  to: Pick<GraphPort, "schema" | "flexible">,
+): boolean => to.flexible === true || isSchemaSubset(from, to.schema)
+
 export const propagateDerivedPorts = <N extends PropagationNode>(
   nodes: N[],
   connections: PortLink[],
   options?: PropagationOptions<N>,
 ): N[] => {
   const resolved = resolvePortSchemas(nodes, connections, options)
+  const flexiblePorts = resolveFlexiblePorts(nodes, connections)
   return nodes.map((node) => {
     let touched = false
     const ports = node.ports.map((port) => {
       const schema = resolved.get(port.id) ?? port.schema
-      if (JSON.stringify(schema) === JSON.stringify(port.schema)) return port
+      // start の flexible は導出結果で置き換える（false は省略＝キー無し）
+      const flexible =
+        node.kind === "start"
+          ? flexiblePorts.has(port.id) || undefined
+          : port.flexible
+      if (
+        JSON.stringify(schema) === JSON.stringify(port.schema) &&
+        flexible === port.flexible
+      )
+        return port
       touched = true
-      return { ...port, schema }
+      const { flexible: _dropped, ...rest } = port
+      return {
+        ...rest,
+        schema,
+        ...(flexible ? { flexible } : {}),
+      } as typeof port
     })
     return touched ? { ...node, ports } : node
   })

package/dist/_schemas/ai-manifest.d.ts

@@ -49,6 +49,7 @@ export declare const agentOfModel: (model: AiModel) => AiAgentId;
 export declare const aiInputDeclSchema: z.ZodObject<{
     schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     resume: z.ZodOptional<z.ZodBoolean>;
+    flexible: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type AiInputDecl = z.infer<typeof aiInputDeclSchema>;
 export declare const aiManifestSchema: z.ZodObject<{
@@ -87,9 +88,11 @@ export declare const aiManifestSchema: z.ZodObject<{
     inputs: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
         schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         resume: z.ZodOptional<z.ZodBoolean>;
+        flexible: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>, z.ZodPipe<z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodTransform<{
         schema: Record<string, unknown>;
         resume?: boolean | undefined;
+        flexible?: boolean | undefined;
     }, Record<string, unknown>>>]>>;
     outputs: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;

package/dist/_schemas/ai-manifest.js

@@ -65,6 +65,8 @@ export const agentOfModel = (model) => model.startsWith("claude-") ? "claude" :
 export const aiInputDeclSchema = z.object({
     schema: jsonSchemaSchema,
     resume: z.boolean().optional(),
+    // 推奨型を維持して任意の型を受ける（接続で上書きされず、適合チェックもしない）
+    flexible: z.boolean().optional(),
 });
 // 旧形式（値が素の JSON Schema）は { schema: 値 } として読む。判別は「schema キーを
 // 持つか」：JSON Schema のトップレベルに "schema" キーは現れない（メタスキーマ参照は

package/dist/_schemas/graph.d.ts

@@ -152,6 +152,7 @@ export declare const graphNodeSchema: z.ZodObject<{
         name: z.ZodString;
         schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         resume: z.ZodOptional<z.ZodBoolean>;
+        flexible: z.ZodOptional<z.ZodBoolean>;
         side: z.ZodOptional<z.ZodEnum<{
             top: "top";
             right: "right";
@@ -252,6 +253,7 @@ export declare const saveGraphBodySchema: z.ZodObject<{
             name: z.ZodString;
             schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
             resume: z.ZodOptional<z.ZodBoolean>;
+            flexible: z.ZodOptional<z.ZodBoolean>;
             side: z.ZodOptional<z.ZodEnum<{
                 top: "top";
                 right: "right";

package/dist/_schemas/graph.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { graphPortSchema, jsonSchemaSchema, nodeKindSchema, portKeySchema, } from "./node.js";
-import { hasInboundConflict, isSchemaSubset, kindPortsViolation, resolvePortSchemas, UNDECLARED_SCHEMA, } from "./port-spec.js";
+import { connectionAccepted, hasInboundConflict, kindPortsViolation, resolvePortSchemas, UNDECLARED_SCHEMA, } from "./port-spec.js";
 // refs＝ループ変数の袋（key→任意の JSON 値。上流出力の参照（refs）.md）。
 // run 開始時に定義から複製され、全 step に全量差し込まれる。
 // key はポート key と同じ規則（^[a-z][a-z0-9_]*$）。実行系ボディ
@@ -473,9 +473,10 @@ export const saveGraphBodySchema = z
         // 接続鏡映する口（program / ai の in）とコピー宣言のビューは接続元の型を採用する
         // ので自明に通り、実質の検証対象は宣言で固定された口
         // （component の契約・宣言のあるビューの human.in）になる
+        // flexible な in（AI の宣言 in・契約で焼き込まれた component の in）は型を問わない
         const fromSchema = resolved.get(conn.from_port_id) ?? from.schema;
         const toSchema = resolved.get(conn.to_port_id) ?? to.schema;
-        if (!isSchemaSubset(fromSchema, toSchema)) {
+        if (!connectionAccepted(fromSchema, { ...to, schema: toSchema })) {
             ctx.addIssue({
                 code: "custom",
                 path: ["connections", i, "to_port_id"],

package/dist/_schemas/node.d.ts

@@ -39,6 +39,7 @@ export declare const graphPortSchema: z.ZodObject<{
     name: z.ZodString;
     schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     resume: z.ZodOptional<z.ZodBoolean>;
+    flexible: z.ZodOptional<z.ZodBoolean>;
     side: z.ZodOptional<z.ZodEnum<{
         top: "top";
         right: "right";

package/dist/_schemas/node.js

@@ -43,6 +43,10 @@ export const graphPortSchema = z
     // 再開する（AI ノードで意味を持つ。key ではなくこの属性が再開を決める。
     // ポート型固定の撤去とセッション再開のポート属性化.md）
     resume: z.boolean().optional(),
+    // in ポートの型属性：true なら宣言（推奨型）を維持し、接続元の型による上書き・
+    // 適合チェックをしない（AI の in で設定。start / component へは導出で流れる。
+    // AIノード入力のflexible属性（任意の型で呼べるループ）.md）
+    flexible: z.boolean().optional(),
     side: portSideSchema.optional(),
     offset: z.number().min(0).max(1).optional(),
 })

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

@@ -70,6 +70,8 @@ export type PropagationOptions<N> = {
     } | null | undefined;
 };
 export declare const resolvePortSchemas: <N extends PropagationNode>(nodes: N[], connections: PortLink[], options?: PropagationOptions<N>) => Map<string, JsonSchema>;
+export declare const resolveFlexiblePorts: (nodes: PropagationNode[], connections: PortLink[]) => Set<string>;
+export declare const connectionAccepted: (from: JsonSchema, to: Pick<GraphPort, "schema" | "flexible">) => boolean;
 export declare const propagateDerivedPorts: <N extends PropagationNode>(nodes: N[], connections: PortLink[], options?: PropagationOptions<N>) => N[];
 export type SchemaFit = "ok" | "mismatch" | "unknown";
 export declare const schemaFit: (sub: JsonSchema, sup: JsonSchema) => SchemaFit;

package/dist/_schemas/port-spec.js

@@ -382,6 +382,9 @@ export const resolvePortSchemas = (nodes, connections, options) => {
                 for (const port of node.ports) {
                     if (port.io !== "in")
                         continue;
+                    // flexible な in は宣言（推奨型）を維持する（接続の型を問わない口）
+                    if (port.flexible === true)
+                        continue;
                     const sources = inbound.get(port.id) ?? [];
                     const inSchema = mergeInboundSchemas(sources.map((id) => resolved.get(id) ?? UNDECLARED_SCHEMA));
                     if (!isUndeclaredSchema(inSchema))
@@ -426,16 +429,68 @@ export const resolvePortSchemas = (nodes, connections, options) => {
 };
 // ノード配列へ伝播結果を書き戻す（接続変更時のポートデータ自動更新）。
 // schema が変わらないポート・ノードは同じ参照を返す
+// flexible の導出：start の in / out main は、接続先の in が1つ以上あり**全て** flexible
+// （AI の宣言 in・契約で焼き込まれた component の in）のときだけ flexible。
+// 非 flexible の接続先（program 等）が1つでも混ざれば型どおりの入力が要るので false。
+// 直結のみ（wait 等の素通し経由は型と同じく流さない）。戻りは flexible になる port_id の集合
+export const resolveFlexiblePorts = (nodes, connections) => {
+    const flexibleByPortId = new Map();
+    for (const node of nodes) {
+        if (node.kind === "start")
+            continue;
+        for (const port of node.ports) {
+            if (port.io === "in")
+                flexibleByPortId.set(port.id, port.flexible === true);
+        }
+    }
+    const outbound = new Map();
+    for (const conn of connections) {
+        const outs = outbound.get(conn.from_port_id) ?? [];
+        outs.push(conn.to_port_id);
+        outbound.set(conn.from_port_id, outs);
+    }
+    const flexible = new Set();
+    for (const node of nodes) {
+        if (node.kind !== "start")
+            continue;
+        const inPort = node.ports.find((p) => p.io === "in");
+        const outMain = node.ports.find((p) => p.io === "out" && p.key === "main");
+        if (!inPort || !outMain)
+            continue;
+        const targets = outbound.get(outMain.id) ?? [];
+        if (targets.length > 0 &&
+            targets.every((id) => flexibleByPortId.get(id) === true)) {
+            flexible.add(inPort.id);
+            flexible.add(outMain.id);
+        }
+    }
+    return flexible;
+};
+// 接続の型が受け入れられるか：受け側が flexible なら常に可、それ以外は 伝播型 ⊆ 宣言。
+// sdk の保存契約・backend の保存時チェック・エディタの表示はすべてこれを使う
+// （判定が散ると表示と保存がズレる）
+export const connectionAccepted = (from, to) => to.flexible === true || isSchemaSubset(from, to.schema);
 export const propagateDerivedPorts = (nodes, connections, options) => {
     const resolved = resolvePortSchemas(nodes, connections, options);
+    const flexiblePorts = resolveFlexiblePorts(nodes, connections);
     return nodes.map((node) => {
         let touched = false;
         const ports = node.ports.map((port) => {
             const schema = resolved.get(port.id) ?? port.schema;
-            if (JSON.stringify(schema) === JSON.stringify(port.schema))
+            // start の flexible は導出結果で置き換える（false は省略＝キー無し）
+            const flexible = node.kind === "start"
+                ? flexiblePorts.has(port.id) || undefined
+                : port.flexible;
+            if (JSON.stringify(schema) === JSON.stringify(port.schema) &&
+                flexible === port.flexible)
                 return port;
             touched = true;
-            return { ...port, schema };
+            const { flexible: _dropped, ...rest } = port;
+            return {
+                ...rest,
+                schema,
+                ...(flexible ? { flexible } : {}),
+            };
         });
         return touched ? { ...node, ports } : node;
     });

package/docs/development.md

@@ -56,10 +56,12 @@ views/
   走り続ける）。省略時は `claude-opus`。認証は repo の Actions secrets に置く：Claude Code は
   `ANTHROPIC_API_KEY`（または `CLAUDE_CODE_OAUTH_TOKEN`）、Codex は明示的な `auth_mode` と対応する認証情報（下記「Codex の認証方式」参照）
   （`env` に宣言しなくても渡される）
-- `inputs` は1件以上・key 自由。値は `{ "schema": <JSON Schema>, "resume": true }` の形
+- `inputs` は1件以上・key 自由。値は `{ "schema": <JSON Schema>, "resume": true, "flexible": true }` の形
   （`resume` は省略可。true の口から入力が届いた実行は、同じノードの直近セッションを
-  復元して再開する——差し戻し→修正の続き実行に使う）。旧形式（値が素の JSON Schema）も
-  読める
+  復元して再開する——差し戻し→修正の続き実行に使う。`flexible` も省略可。true の口は
+  `schema` を推奨型として維持し、接続で型が上書きされず型の違う接続も通る——この AI が
+  先頭のループを他のループや API から型を揃えずに呼べるようにする）。旧形式（値が素の
+  JSON Schema）も読める
 - 実行時はラッパーがエージェント CLI（Claude Code / Codex、非対話）を起動し、`outputs` の
   スキーマに適合する output を検証して報告する。出口が複数あれば AI が1つ選ぶ（複数出口＝分岐）
 - **文体の既定は「短く」**：出力の文章は承認画面・Slack・顧客への回答としてそのまま人が読むため、

package/package.json

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

package/skills/create-loop/SKILL.md

@@ -59,7 +59,7 @@ secret）でも、**足りない値を推測・生成・空文字で代用しな
 
 疎通確認のあと `GET {MAWARU_API_URL}/tenants/{MAWARU_TENANT_ID}/openapi.json`
 （ヘッダ `x-api-key: $MAWARU_API_KEY`）を取得すると、機械 API 面
-（loops の一覧・作成・詳細・graph PUT、runs/start、runs/{runId}/cancel、runs/{runId}/complete、members、api-keys、steps の end / decision）の
+（loops の一覧・作成・詳細・graph PUT・versions/publish、runs/start、runs/{runId} の参照・cancel・complete、members、api-keys、steps の end / decision）の
 パス・メソッド・リクエストボディ（Zod 由来の JSON Schema）が載っている。ここが常に正。
 段階導入中で未掲載のエンドポイントもある（その場合だけ `api/index.ts` 相当を辿る）。
 
@@ -73,7 +73,15 @@ repo との矛盾・使用中ノードの削除は 409。**graph PUT は冪等
 
 ## 手順
 
-1. **設計**：要件から必要なノード（program / ai / human / wait / join）と流れを決め、ユーザーに一言で確認する。
+ループは次の4段階で作る。**言われなくても必ず 1 のスケルトンから始め、段階を飛ばさない。**
+graph の保存（`PUT loops/{loopId}/graph`）は常に下書き（draft）に入り、4 で publish するまで
+本番の run には使われない。
+
+### 1. スケルトンを作って合意する
+
+ノードの配置と接続だけを下書きに保存する。中身（repo のプログラム・prompt）はまだ作らない。
+
+1. **設計**：要件から必要なノード（program / ai / human / wait / join）と流れを決める。
    1つの出口から複数の線を引くと枝が並行に走る（fan-out）。枝の結果を待ち合わせるときは
    合流（`join`）を置く：線のつながった入口が全部揃うまで待ち、`{ [入口の key]: 値 }` にまとめて
    `main` から流す。並行した枝を合流させずに同じノード（待機など）へ戻すと、枝の数だけ走り続ける。
@@ -83,26 +91,56 @@ repo との矛盾・使用中ノードの削除は 409。**graph PUT は冪等
    （`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` に書く**（下記）。
-   **作った・変えたものは GitHub へ push してから次へ進む**（mawaru は repo を GitHub 経由で
-   読むため、未 push だと graph 保存の検証・書き戻しと食い違って 409 になる）。
-3. **ループ作成**：`POST loops`。
-4. **graph ボディを組む**：
+2. **ループ作成**：`POST loops`（既存ループの更新なら不要）。
+3. **graph ボディを組む**（中身は空のまま）：
    - node / port の `id` はクライアント採番（`uuidgen` などで UUID を作る）
-   - program / ai ノードの ports は repo の config.json の inputs / outputs をそのまま写す
-     （in ポート key は `in`、out ポートは outputs の各 key）
-   - kind 別の固定ポート構成（human / wait / ai / join）は `port-spec.ts` の `kindPortsViolation` に従う。
-     join は in を枝の数だけ（key 自由。例 `in_1`, `in_2`）＋ out `main`。出口の型は自動で決まる
+   - program / ai ノードには `program` / `ai`（dir の指定）を付けない。dir 未設定のノードは
+     repo へ書き戻されないので、repo 側に何も無くても保存できる
+   - ポートは kind 別の固定構成（`port-spec.ts` の `kindPortsViolation`）と分岐する出口の key だけ
+     決め、`schema` は `{}`（未宣言）でよい。型は 2 で config.json と一緒に決める。
+     program の in は `in`。join は in を枝の数だけ（key 自由。例 `in_1`, `in_2`）＋ out `main`
+   - human は担当（`human.assignment.units`）が保存に必須なので、誰が承認するかもここで決める
    - ループ変数（refs＝run 全体で読める key→値 の袋）が要るならトップレベルの `refs` に入れる。
      ノード単位の宣言やバインドは無い。handler は実行時に `refs.json` で全量を受け取り、
      `end` の `refs` パッチで値を更新できる（config.json の `refs` はループ定義からの転写＝生成物）。
      キー `input` は予約（run の起動入力が自動で入る。定義に置くと 422）
    - `position_x` / `position_y` は左→右に流れる単純配置（例: x を 320 刻み、y は 240）
-5. **保存**：`PUT loops/{loopId}/graph`。400 / 422 / 409 ならメッセージを読んで直して再送。
-6. **報告**：エディタ URL `{MAWARU_APP_URL}/loops/{loopId}/edit` をユーザーに渡し、
-   見た目の確認と run はユーザーに委ねる。
+4. **保存**：`PUT loops/{loopId}/graph`。400 / 422 / 409 ならメッセージを読んで直して再送。
+5. **合意**：エディタ URL `{MAWARU_APP_URL}/loops/{loopId}/edit` をユーザーに渡し、ノードの並びと
+   つながりを見てもらう。**OK をもらうまで 2 へ進まない**（直しの依頼は graph を直して保存し、
+   もう一度見てもらう）。
+
+### 2. 各ノードの中身を実装し、1つずつ確かめる
+
+上流のノードから順に、1つずつ次を繰り返す：
+
+1. **repo 側の実装**：`nodes/program/<dir>/` / `nodes/ai/<dir>/` を作る
+   （config.json → `npx mawaru typegen` → main.ts 実装 → `npx mawaru validate`）。
+   config.json の inputs / outputs はスケルトンのポートの key に合わせ、ここで型を決める。
+   **AI ノードの決定論的な処理は prompt ではなく `setup.sh` に書く**（下記）。
+   **GitHub へ push してから次へ進む**（mawaru は repo を GitHub 経由で読むため、未 push だと
+   graph 保存の書き戻しと食い違って 409 になり、テスト実行も古い中身で走る）。
+2. **ノードに結びつける**：graph の該当ノードに `program.program_dir` / `ai.ai_dir` を設定し、
+   ports を config.json の inputs / outputs の写しにして保存する（in ポート key は `in`、
+   out ポートは outputs の各 key）。human は承認ビュー、wait は待ち方もここで設定する。
+3. **単体で確かめる**：そのノードだけをテスト実行する。`POST runs/start` に `kind: "test"`・
+   `test_scope: "only"`・`start_node_id`（そのノード）・`payload`（サンプル入力。上流を確かめ済みなら
+   その output を使う）・`start_by`（ユーザーの user_id。`GET members` で引く。API キー起動では必須）を
+   渡し、`GET runs/{runId}` で step の status と output を見る。下書きの program / ai は
+   ブランチ先頭の commit で走る。失敗したら直して push し、もう一度実行する。
+   human はテスト実行の担当が起動者になるので、承認・差し戻しはユーザーに操作してもらう。
+
+### 3. 全体を通して確かめる
+
+開始ノード（kind `start`）を `start_node_id` に、`test_scope: "from"` でテスト実行し、end まで
+流れることを確かめる（分岐があれば主な道を一通り）。human を通る道はユーザーに操作してもらう。
+結果をユーザーに報告する。
+
+### 4. publish して起動する
+
+ユーザーの OK をもらってから `POST loops/{loopId}/versions/publish` で下書きを公開する
+（AI / Program の実行 commit はここで固定される）。続けて `POST runs/start`（`loop_id`・`payload`。
+`kind` を省くと本番 run）で起動し、run の URL `{MAWARU_APP_URL}/runs/{runId}` をユーザーに渡す。
 
 ## AI ノード：出力は短く（既定）