@mawaru/sdk 0.17.0 → 0.19.0

package/_schemas/extract-component.ts

@@ -1,5 +1,6 @@
 import type { GraphConnection, GraphNode } from "./graph.js"
 import type { GraphPort } from "./node.js"
+import { schemaTypeKey } from "./port-spec.js"
 
 // 矩形選択からのグループ化・コンポーネント化（ノードのグループ化・コンポーネント化.md／
 // コンポーネントの複数入口・複数出口.md）。
@@ -67,7 +68,7 @@ export const analyzeExtractSelection = (
   // 同じ思想を境界にも適用する（グループ化＝入口の合流の宣言）
   const entryPortIds = [...new Set(inbound.map((c) => c.to_port_id))]
   const entrySchemas = new Set(
-    entryPortIds.map((id) => JSON.stringify(portById.get(id)?.schema ?? {})),
+    entryPortIds.map((id) => schemaTypeKey(portById.get(id)?.schema ?? {})),
   )
   if (entrySchemas.size > 1) {
     return {

package/_schemas/graph.test.ts

@@ -312,7 +312,7 @@ describe("saveGraphBodySchema", () => {
   })
 
   // fan-in（同じ in ポートへの流入2本以上）は同じ型でなければならない
-  // （docs/tasks/wip/ポートスキーマのany撲滅.md）
+  // （docs/tasks/done/ポートスキーマのany撲滅.md）
   const programNode = (outSchema: GraphPort["schema"]) => ({
     ...makeNode([
       port("in", "in"),
@@ -333,6 +333,18 @@ describe("saveGraphBodySchema", () => {
     ).not.toThrow()
   })
 
+  it("fan-in：注釈（title）だけが違う流入は同じ型として受け付ける", () => {
+    const a = programNode({ type: "string", title: "回答" })
+    const b = programNode({ type: "string", title: "要開発者確認" })
+    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" })
@@ -623,7 +635,7 @@ describe("saveGraphBodySchema（kind 別ポート構成）", () => {
 describe("saveGraphBodySchema（型の接続バリデーション）", () => {
   // 接続の可否は kind ではなく型で決まる。reject / instruction の型固定は廃止され、
   // ai の in はどの口も接続鏡映（接続元の型に同期）なので接続は自明に通る
-  // → docs/tasks/wip/ポート型固定の撤去とセッション再開のポート属性化.md
+  // → docs/tasks/done/ポート型固定の撤去とセッション再開のポート属性化.md
   it("human の reject → ai の instruction を許可（kind の縛りも型固定も無い）", () => {
     const human = humanNode()
     const ai = aiNode()

package/_schemas/graph.ts

@@ -99,7 +99,7 @@ export type WaitConfig = z.infer<typeof waitConfigSchema>
 // Program ノードの kind 別設定（node_programs に対応）。実行先の repo はノード設定でなく
 // installation から `${account_login}/${GITHUB_REPO_NAME}` に固定（backend）。program_dir は nodes/program/ 直下のディレクトリ名
 // （例: sendReply。日本語可。エントリは main.ts 固定。リポジトリ規約 v2 は
-// docs/tasks/wip/プログラムのリポジトリ規約v2（ディレクトリ＋config.json）.md）。
+// docs/tasks/done/プログラムのリポジトリ規約v2（ディレクトリ＋config.json）.md）。
 // ref 省略時はデフォルトブランチ
 export const programConfigSchema = z.object({
   program_dir: z
@@ -130,7 +130,7 @@ export type AiConfig = z.infer<typeof aiConfigSchema>
 
 // 担当ユニットのメンバー：user_id の名指し、または動的な担当「ループを実行した人」
 // （run の起動者。実行時に runs.start_by で解決し、解決できなければその1人だけ落ちる。
-// docs/tasks/wip/Human担当に「ループを実行した人」を追加する.md）
+// docs/tasks/done/Human担当に「ループを実行した人」を追加する.md）
 export const RUN_STARTER = "run_starter"
 export const assignMemberSchema = z.union([z.uuid(), z.literal(RUN_STARTER)])
 export type AssignMember = z.infer<typeof assignMemberSchema>
@@ -198,7 +198,7 @@ export type HumanConfig = z.infer<typeof humanConfigSchema>
 
 // コンポーネントノードの kind 別設定（node_components に対応）。呼ぶ先は
 // kind='component' の loop。同 tenant・kind の検証と自 loop 参照の禁止は保存 API 側で行う
-// （docs/tasks/wip/コンポーネント（ループの部品化と再利用）.md）
+// （docs/tasks/done/コンポーネント（ループの部品化と再利用）.md）
 export const componentConfigSchema = z.object({
   component_loop_id: z.uuid(),
   // 配置の設定値：子 loop の refs 定義（default/required）への上書き。
@@ -211,7 +211,7 @@ export type ComponentConfig = z.infer<typeof componentConfigSchema>
 // ノードにアタッチされた IOHook（node_hooks に対応。アタッチできるのは program ノードのみ）。
 // on_input / on_output / on_signal はアタッチ時に repo の config.json（hookManifestSchema）から
 // エディタが焼き込むスナップショット。ref 省略時はデフォルトブランチ
-// （docs/tasks/wip/NodeIOHooks（ノードへのIOフックのアタッチ）.md・
+// （docs/tasks/done/NodeIOHooks（ノードへのIOフックのアタッチ）.md・
 // NodeIOHooksのonSignal（外部シグナルでのフック発火）.md）
 export const graphNodeHookSchema = z.object({
   hook_dir: z
@@ -231,7 +231,7 @@ export type GraphNodeHook = z.infer<typeof graphNodeHookSchema>
 
 // 新規ノードの id・ポートの id もクライアントが採番する（一時IDの解決を不要にする）
 // ノードの表示アイコン：プリセット・絵文字・画像 URL のいずれか一つ。
-// 未設定（省略）＝既定の kind アイコン（docs/tasks/wip/ノードのアイコン（プログラム任意設定・HUMAN担当者の自動表示）.md）。
+// 未設定（省略）＝既定の kind アイコン（docs/tasks/done/ノードのアイコン（プログラム任意設定・HUMAN担当者の自動表示）.md）。
 // preset は契約上不透明な文字列（承認ビューと同じ方式）：カタログはフロントが
 // 表示時に参照し、無い key は既定グリフへフォールバックする
 export const nodeIconSchema = z.union([
@@ -467,7 +467,7 @@ export const saveGraphBodySchema = z
 
     // fan-in（同じ in ポートへの流入が2本以上）は同じ型でなければならない。
     // 型が割れていると伝播が未宣言に落ちて下流の型チェックが効かなくなる
-    // （docs/tasks/wip/ポートスキーマのany撲滅.md）
+    // （docs/tasks/done/ポートスキーマのany撲滅.md）
     const inboundByPort = new Map<string, string[]>()
     for (const conn of graph.connections) {
       const list = inboundByPort.get(conn.to_port_id) ?? []
@@ -514,7 +514,7 @@ export const saveGraphBodySchema = z
 
       // 差し戻し（reject）と instruction の組み合わせに kind の縛りも型固定も無い：
       // reject の型はビューの宣言、instruction は ai の in の1つ（接続鏡映）でしかない
-      // → docs/tasks/wip/ポート型固定の撤去とセッション再開のポート属性化.md
+      // → docs/tasks/done/ポート型固定の撤去とセッション再開のポート属性化.md
 
       // 型検証は kind によらず常に 伝播型（out） ⊆ 伝播型（in）。
       // 未宣言は unknown＝判断できないので通す（作りかけのグラフを保存できなくしない）。

package/_schemas/hook-manifest.ts

@@ -3,7 +3,7 @@ import { z } from "zod"
 // nodes/hook/<dir>/config.json（NodeIOHooks）。フック自身が発火イベント（on）と
 // 必要 env を宣言し、エディタがアタッチ時に読んで node_hooks へ焼き込む
 // （programManifestSchema と同型の「repo が正・編集時に取り込む」方式。
-// docs/tasks/wip/NodeIOHooks（ノードへのIOフックのアタッチ）.md）。
+// docs/tasks/done/NodeIOHooks（ノードへのIOフックのアタッチ）.md）。
 // フックは任意のノードに付くため inputs / outputs のスキーマ宣言は持たない（unknown を受ける）。
 // signal は外部シグナル（signals API）での発火（NodeIOHooksのonSignal（外部シグナルでのフック発火）.md）
 export const hookEventSchema = z.enum(["input", "output", "signal"])

package/_schemas/node.ts

@@ -7,11 +7,11 @@ export const nodeKindSchema = z.enum([
   "guardrail",
   "wait",
   // 開始・終了ノード（恒等パススルー。run は必ず start から始まり end で終わる。
-  // docs/tasks/wip/開始・終了ノードの定義.md）
+  // docs/tasks/done/開始・終了ノードの定義.md）
   "start",
   "end",
   // コンポーネント（kind='component' の loop を配置して呼ぶ。子 run・戻り値あり。
-  // docs/tasks/wip/コンポーネント（ループの部品化と再利用）.md）
+  // docs/tasks/done/コンポーネント（ループの部品化と再利用）.md）
   "component",
 ])
 export type NodeKind = z.infer<typeof nodeKindSchema>
@@ -39,7 +39,7 @@ export const portSideSchema = z.enum(["top", "right", "bottom", "left"])
 export type PortSide = z.infer<typeof portSideSchema>
 
 // グラフ保存契約のポート（ports テーブルの1行。id はクライアント採番。
-// docs/tasks/wip/ポートのテーブル化.md）
+// docs/tasks/done/ポートのテーブル化.md）
 export const graphPortSchema = z
   .object({
     id: z.uuid(),

package/_schemas/port-spec.test.ts

@@ -13,6 +13,7 @@ import {
   propagateDerivedPorts,
   resolvePortSchemas,
   schemaFit,
+  schemaTypeKey,
   UNDECLARED_SCHEMA,
 } from "./port-spec.js"
 
@@ -140,7 +141,7 @@ describe("型伝播（導出ポートの解決）", () => {
 
   // human の in / approve / reject はビューの宣言をそのまま転写する（上流の kind は見ない）。
   // sdk はカタログを知らないので、呼び出し元が viewPortSchemasOf で解決して渡す
-  // → docs/tasks/wip/ポート型固定の撤去とセッション再開のポート属性化.md
+  // → docs/tasks/done/ポート型固定の撤去とセッション再開のポート属性化.md
   it("ai → human 直結（コピー宣言）：in も approve も上流の out と同型、reject はビューの宣言型", () => {
     const aiOut = port("out", "main", declaredOut)
     const ai = {
@@ -888,4 +889,77 @@ describe("mergeInboundSchemas / hasInboundConflict（fan-in）", () => {
     )
     expect(hasInboundConflict([])).toBe(false)
   })
+
+  it("注釈（title / description）だけが違う流入は同じ型として合流できる", () => {
+    const answer = {
+      type: "object",
+      required: ["answer"],
+      properties: { answer: { type: "string", description: "顧客への回答" } },
+    } as const
+    const titled = { ...answer, title: "回答" }
+    const otherTitle = {
+      type: "object",
+      title: "要開発者確認",
+      required: ["answer"],
+      properties: { answer: { type: "string", description: "回答ドラフト" } },
+    } as const
+
+    expect(hasInboundConflict([titled, otherTitle])).toBe(false)
+    expect(mergeInboundSchemas([titled, otherTitle])).not.toEqual(
+      UNDECLARED_SCHEMA,
+    )
+  })
+
+  it("キー順・required の並びが違うだけの流入は同じ型として合流できる", () => {
+    const a = {
+      type: "object",
+      required: ["answer", "reasoning"],
+      properties: { answer: { type: "string" }, reasoning: { type: "string" } },
+    } as const
+    const b = {
+      properties: { reasoning: { type: "string" }, answer: { type: "string" } },
+      required: ["reasoning", "answer"],
+      type: "object",
+    } as const
+
+    expect(hasInboundConflict([a, b])).toBe(false)
+    expect(mergeInboundSchemas([a, b])).not.toEqual(UNDECLARED_SCHEMA)
+  })
+
+  it("合流の採用値は流入の順番に依らず決まる（保存ごとに注釈が揺れない）", () => {
+    const a = { type: "object", title: "あ", properties: {} } as const
+    const b = { type: "object", title: "い", properties: {} } as const
+    expect(mergeInboundSchemas([a, b])).toEqual(mergeInboundSchemas([b, a]))
+  })
+
+  it("構造が違えば注釈を無視しても衝突のまま", () => {
+    const a = { type: "object", properties: { x: { type: "string" } } } as const
+    const b = { type: "object", properties: { x: { type: "number" } } } as const
+    expect(hasInboundConflict([a, b])).toBe(true)
+    expect(mergeInboundSchemas([a, b])).toEqual(UNDECLARED_SCHEMA)
+  })
+
+  it("file マーカーは型の一部（注釈として落とさない）", () => {
+    expect(hasInboundConflict([fileSchema(), { type: "object" }])).toBe(true)
+  })
+})
+
+describe("schemaTypeKey（型としての同一性）", () => {
+  it("注釈だけの違いは同じキーになる", () => {
+    expect(schemaTypeKey({ type: "string", title: "回答" })).toBe(
+      schemaTypeKey({ type: "string", description: "根拠", title: "報告" }),
+    )
+  })
+
+  it("default は挙動（フォームの初期値）なので型の一部として残す", () => {
+    expect(schemaTypeKey({ type: "string", default: "a" })).not.toBe(
+      schemaTypeKey({ type: "string" }),
+    )
+  })
+
+  it("配列の要素順は保つ（items のタプルは意味を持つ）", () => {
+    expect(
+      schemaTypeKey({ type: "array", items: [{ type: "string" }] }),
+    ).not.toBe(schemaTypeKey({ type: "array", items: [{ type: "number" }] }))
+  })
 })

package/_schemas/port-spec.ts

@@ -1,15 +1,15 @@
 import { z } from "zod"
 import type { GraphPort, JsonSchema, PortIo } from "./node.js"
 
-// ポートの kind 別型システム（docs/tasks/wip/ポートのkind別仕様.md）。
+// ポートの kind 別型システム（docs/tasks/done/ポートのkind別仕様.md）。
 // 型の決まり方は2分類：宣言（program / ai の in・out。human はビューの宣言を転写）／
 // 導出（それ以外。接続元から伝播し、結果は ports.schema にキャッシュする）。
 // mawaru がコードで型を固定するポートは無い
-// （docs/tasks/wip/ポート型固定の撤去とセッション再開のポート属性化.md）
+// （docs/tasks/done/ポート型固定の撤去とセッション再開のポート属性化.md）
 
 // 「まだ型が決まっていない」＝未宣言を {} で表す（未接続・上流が未宣言・fan-in の型割れ）。
 // 「何でも受ける」型は存在しない：program / ai の in は接続元の具体型を鏡映する
-// （docs/tasks/wip/ポートスキーマのany撲滅.md）
+// （docs/tasks/done/ポートスキーマのany撲滅.md）
 export const UNDECLARED_SCHEMA: JsonSchema = {}
 
 export const isUndeclaredSchema = (schema: JsonSchema): boolean =>
@@ -20,7 +20,7 @@ export const isUndeclaredSchema = (schema: JsonSchema): boolean =>
 // ではなく storage path の参照で、署名 URL はどこにも焼き込まない。
 // **file の位置は名前ではなくこのマーカーで決まる**：runner が宣言スキーマと値を並行走査して
 // 入力はワークスペースへ materialize（パスに置換）、出力はアップロード（参照に置換）する
-// （docs/tasks/wip/ポートスキーマ編集でファイル型を選べるようにする.md）。
+// （docs/tasks/done/ポートスキーマ編集でファイル型を選べるようにする.md）。
 // ajv は strict:false で未知キーワードを無視するので検証は素の JSON Schema のまま。
 export const FILE_SCHEMA_MARKER = "x-mawaru-type"
 export const FILE_SCHEMA_TYPE = "file"
@@ -236,29 +236,60 @@ export const kindPortsViolation = (
 // 宣言 out（program / ai）は触らない。
 // program / ai の in は**全ての口が**接続鏡映（sticky）：接続元 out が具体型のときだけ
 // 上書きし、未接続・型割れ・未宣言は現スキーマ（宣言）を維持する（鏡映結果は repo の
-// config.json へも書き戻される。docs/tasks/wip/ポート編集のrepo書き戻し同期.md）
+// config.json へも書き戻される。docs/tasks/done/ポート編集のrepo書き戻し同期.md）
+
+// ---- 型としての同一性（schemaTypeKey） ----
+// 「同じ型か」を判定する唯一の物差し。合流（fan-in）・end の in の畳み込み・
+// グループ化の入口・エディタの着地判定が全部これを使う。
+// 素の JSON 等値だと、意味の同じ型が **注釈の差** や **キーの並び順** だけで別型に
+// 見えて合流できなくなる（古い取り込みで ports.schema に残った title が典型）。
+// 型＝構造なので、人間向けの注釈は落とし、順序に意味の無い集合は並べ直して比べる。
+// default は「フォームの初期値」という挙動なので型の一部として残す。
+// x-mawaru-type（file の nominal マーカー）も当然残す
+const ANNOTATION_KEYWORDS = new Set([
+  "title",
+  "description",
+  "$comment",
+  "examples",
+  "deprecated",
+])
+
+// required は集合（並びに意味が無い）。properties のキー順は表示順として意味を
+// 持ちうるが、型の同一性には効かせない
+const canonicalize = (value: unknown, key?: string): unknown => {
+  if (Array.isArray(value)) {
+    const items = value.map((v) => canonicalize(v))
+    return key === "required" ? [...items].sort() : items
+  }
+  if (value === null || typeof value !== "object") return value
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>)
+      .filter(([k]) => !ANNOTATION_KEYWORDS.has(k))
+      .map(([k, v]) => [k, canonicalize(v, k)] as const)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),
+  )
+}
+
+export const schemaTypeKey = (schema: JsonSchema): string =>
+  JSON.stringify(canonicalize(schema))
 
 // 複数の流入（fan-in）から型を1つに決める：未宣言を除いて具体型が1種類ならその型、
 // 0種類なら未宣言。2種類以上は型が割れているので未宣言に落とす
-// （保存時に graph.ts が 422 で弾く。伝播は止めずに固定点へ収束させる）
+// （保存時に graph.ts が 422 で弾く。伝播は止めずに固定点へ収束させる）。
+// 注釈だけが違う流入は同じ型なので、採用する1つを JSON 等値で安定に選ぶ
+// （接続の並び順で title が揺れて repo 書き戻しが空コミットを打たないように）
 export const mergeInboundSchemas = (schemas: JsonSchema[]): JsonSchema => {
-  const uniq = [
-    ...new Set(
-      schemas
-        .filter((s) => !isUndeclaredSchema(s))
-        .map((s) => JSON.stringify(s)),
-    ),
-  ]
-  return uniq.length === 1 && uniq[0] !== undefined
-    ? (JSON.parse(uniq[0]) as JsonSchema)
-    : UNDECLARED_SCHEMA
+  const declared = schemas.filter((s) => !isUndeclaredSchema(s))
+  if (new Set(declared.map(schemaTypeKey)).size !== 1) return UNDECLARED_SCHEMA
+  return declared
+    .map((s) => [JSON.stringify(s), s] as const)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))[0]?.[1] as JsonSchema
 }
 
 // 流入の具体型が2種類以上あるか（＝同じポートに違う型を流し込んでいる）
 export const hasInboundConflict = (schemas: JsonSchema[]): boolean =>
-  new Set(
-    schemas.filter((s) => !isUndeclaredSchema(s)).map((s) => JSON.stringify(s)),
-  ).size > 1
+  new Set(schemas.filter((s) => !isUndeclaredSchema(s)).map(schemaTypeKey))
+    .size > 1
 
 type PropagationNode = {
   id: string
@@ -276,7 +307,7 @@ export type DeclaredPortSchema = JsonSchema | typeof COPY_UPSTREAM_SCHEMA
 
 // 伝播のオプション。sdk は承認ビューのカタログを知らない（非公開。企業向けビューの
 // キーが npm 公開物に載るのを避ける）ので、呼び出し元が解決して渡す
-// → docs/tasks/wip/ポート型固定の撤去とセッション再開のポート属性化.md
+// → docs/tasks/done/ポート型固定の撤去とセッション再開のポート属性化.md
 export type PropagationOptions<N> = {
   // human の in / approve / reject に転写する型（承認ビューの宣言）。null / undefined
   // ならその node は対象外（human 以外）。上流ノードの kind は一切見ない。

package/_schemas/program-manifest.ts

@@ -4,7 +4,7 @@ import { manifestInKeysViolation } from "./port-spec.js"
 
 // nodes/program/<dir>/config.json（リポジトリ規約 v2）。プログラム自身が入出力スキーマを宣言し、
 // エディタが取り込んで ports を自動生成する（実行時の正は ports テーブルのまま。
-// docs/tasks/wip/プログラムのリポジトリ規約v2（ディレクトリ＋config.json）.md）。
+// docs/tasks/done/プログラムのリポジトリ規約v2（ディレクトリ＋config.json）.md）。
 // inputs / outputs は「ポート key → JSON Schema」のマップ。将来 join（in 複数）を導入しても
 // 形式が変わらないよう最初から複数形にしてある
 export const programManifestSchema = z

package/dist/_schemas/extract-component.js

@@ -1,3 +1,4 @@
+import { schemaTypeKey } from "./port-spec.js";
 export const analyzeExtractSelection = (nodes, connections, selectedIds) => {
     const selected = new Set(selectedIds);
     // 1ノードからコンポーネント化できる（グループ化の「2つ以上」はエディタ側の
@@ -32,7 +33,7 @@ export const analyzeExtractSelection = (nodes, connections, selectedIds) => {
     // 起点（どの外部ポートから入るか）は見ない。ノードが前のノードを知らないのと
     // 同じ思想を境界にも適用する（グループ化＝入口の合流の宣言）
     const entryPortIds = [...new Set(inbound.map((c) => c.to_port_id))];
-    const entrySchemas = new Set(entryPortIds.map((id) => JSON.stringify(portById.get(id)?.schema ?? {})));
+    const entrySchemas = new Set(entryPortIds.map((id) => schemaTypeKey(portById.get(id)?.schema ?? {})));
     if (entrySchemas.size > 1) {
         return {
             ok: false,

package/dist/_schemas/graph.js

@@ -72,7 +72,7 @@ export const waitConfigSchema = z.discriminatedUnion("wait_type", [
 // Program ノードの kind 別設定（node_programs に対応）。実行先の repo はノード設定でなく
 // installation から `${account_login}/${GITHUB_REPO_NAME}` に固定（backend）。program_dir は nodes/program/ 直下のディレクトリ名
 // （例: sendReply。日本語可。エントリは main.ts 固定。リポジトリ規約 v2 は
-// docs/tasks/wip/プログラムのリポジトリ規約v2（ディレクトリ＋config.json）.md）。
+// docs/tasks/done/プログラムのリポジトリ規約v2（ディレクトリ＋config.json）.md）。
 // ref 省略時はデフォルトブランチ
 export const programConfigSchema = z.object({
     program_dir: z
@@ -93,7 +93,7 @@ export const aiConfigSchema = z.object({
 });
 // 担当ユニットのメンバー：user_id の名指し、または動的な担当「ループを実行した人」
 // （run の起動者。実行時に runs.start_by で解決し、解決できなければその1人だけ落ちる。
-// docs/tasks/wip/Human担当に「ループを実行した人」を追加する.md）
+// docs/tasks/done/Human担当に「ループを実行した人」を追加する.md）
 export const RUN_STARTER = "run_starter";
 export const assignMemberSchema = z.union([z.uuid(), z.literal(RUN_STARTER)]);
 // Human ノードの kind 別設定（node_humans ＋ node_human_assignees に対応）。
@@ -153,7 +153,7 @@ export const humanConfigSchema = z.object({
 });
 // コンポーネントノードの kind 別設定（node_components に対応）。呼ぶ先は
 // kind='component' の loop。同 tenant・kind の検証と自 loop 参照の禁止は保存 API 側で行う
-// （docs/tasks/wip/コンポーネント（ループの部品化と再利用）.md）
+// （docs/tasks/done/コンポーネント（ループの部品化と再利用）.md）
 export const componentConfigSchema = z.object({
     component_loop_id: z.uuid(),
     // 配置の設定値：子 loop の refs 定義（default/required）への上書き。
@@ -164,7 +164,7 @@ export const componentConfigSchema = z.object({
 // ノードにアタッチされた IOHook（node_hooks に対応。アタッチできるのは program ノードのみ）。
 // on_input / on_output / on_signal はアタッチ時に repo の config.json（hookManifestSchema）から
 // エディタが焼き込むスナップショット。ref 省略時はデフォルトブランチ
-// （docs/tasks/wip/NodeIOHooks（ノードへのIOフックのアタッチ）.md・
+// （docs/tasks/done/NodeIOHooks（ノードへのIOフックのアタッチ）.md・
 // NodeIOHooksのonSignal（外部シグナルでのフック発火）.md）
 export const graphNodeHookSchema = z.object({
     hook_dir: z
@@ -179,7 +179,7 @@ export const graphNodeHookSchema = z.object({
 });
 // 新規ノードの id・ポートの id もクライアントが採番する（一時IDの解決を不要にする）
 // ノードの表示アイコン：プリセット・絵文字・画像 URL のいずれか一つ。
-// 未設定（省略）＝既定の kind アイコン（docs/tasks/wip/ノードのアイコン（プログラム任意設定・HUMAN担当者の自動表示）.md）。
+// 未設定（省略）＝既定の kind アイコン（docs/tasks/done/ノードのアイコン（プログラム任意設定・HUMAN担当者の自動表示）.md）。
 // preset は契約上不透明な文字列（承認ビューと同じ方式）：カタログはフロントが
 // 表示時に参照し、無い key は既定グリフへフォールバックする
 export const nodeIconSchema = z.union([
@@ -394,7 +394,7 @@ export const saveGraphBodySchema = z
     const resolved = resolvePortSchemas(graph.nodes, graph.connections);
     // fan-in（同じ in ポートへの流入が2本以上）は同じ型でなければならない。
     // 型が割れていると伝播が未宣言に落ちて下流の型チェックが効かなくなる
-    // （docs/tasks/wip/ポートスキーマのany撲滅.md）
+    // （docs/tasks/done/ポートスキーマのany撲滅.md）
     const inboundByPort = new Map();
     for (const conn of graph.connections) {
         const list = inboundByPort.get(conn.to_port_id) ?? [];
@@ -439,7 +439,7 @@ export const saveGraphBodySchema = z
         }
         // 差し戻し（reject）と instruction の組み合わせに kind の縛りも型固定も無い：
         // reject の型はビューの宣言、instruction は ai の in の1つ（接続鏡映）でしかない
-        // → docs/tasks/wip/ポート型固定の撤去とセッション再開のポート属性化.md
+        // → docs/tasks/done/ポート型固定の撤去とセッション再開のポート属性化.md
         // 型検証は kind によらず常に 伝播型（out） ⊆ 伝播型（in）。
         // 未宣言は unknown＝判断できないので通す（作りかけのグラフを保存できなくしない）。
         // 接続鏡映する口（program / ai の in）とコピー宣言のビューは接続元の型を採用する

package/dist/_schemas/hook-manifest.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 // nodes/hook/<dir>/config.json（NodeIOHooks）。フック自身が発火イベント（on）と
 // 必要 env を宣言し、エディタがアタッチ時に読んで node_hooks へ焼き込む
 // （programManifestSchema と同型の「repo が正・編集時に取り込む」方式。
-// docs/tasks/wip/NodeIOHooks（ノードへのIOフックのアタッチ）.md）。
+// docs/tasks/done/NodeIOHooks（ノードへのIOフックのアタッチ）.md）。
 // フックは任意のノードに付くため inputs / outputs のスキーマ宣言は持たない（unknown を受ける）。
 // signal は外部シグナル（signals API）での発火（NodeIOHooksのonSignal（外部シグナルでのフック発火）.md）
 export const hookEventSchema = z.enum(["input", "output", "signal"]);

package/dist/_schemas/node.js

@@ -6,11 +6,11 @@ export const nodeKindSchema = z.enum([
     "guardrail",
     "wait",
     // 開始・終了ノード（恒等パススルー。run は必ず start から始まり end で終わる。
-    // docs/tasks/wip/開始・終了ノードの定義.md）
+    // docs/tasks/done/開始・終了ノードの定義.md）
     "start",
     "end",
     // コンポーネント（kind='component' の loop を配置して呼ぶ。子 run・戻り値あり。
-    // docs/tasks/wip/コンポーネント（ループの部品化と再利用）.md）
+    // docs/tasks/done/コンポーネント（ループの部品化と再利用）.md）
     "component",
 ]);
 // ポート key（input/output 用の参照キー）の規則（db.md §2）。
@@ -28,7 +28,7 @@ export const portIoSchema = z.enum(["in", "out"]);
 // 未指定は自動配置（先頭=右辺中央・以降=下辺等間隔）
 export const portSideSchema = z.enum(["top", "right", "bottom", "left"]);
 // グラフ保存契約のポート（ports テーブルの1行。id はクライアント採番。
-// docs/tasks/wip/ポートのテーブル化.md）
+// docs/tasks/done/ポートのテーブル化.md）
 export const graphPortSchema = z
     .object({
     id: z.uuid(),

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

@@ -47,6 +47,7 @@ export declare const dataFormatOf: (schema: JsonSchema) => DataFormat | null;
 export declare const fixedInKeysOf: (kind: string) => string[] | null;
 export declare const manifestInKeysViolation: (kind: string, keys: string[]) => string | null;
 export declare const kindPortsViolation: (kind: string, ports: Pick<GraphPort, "io" | "key">[]) => string | null;
+export declare const schemaTypeKey: (schema: JsonSchema) => string;
 export declare const mergeInboundSchemas: (schemas: JsonSchema[]) => JsonSchema;
 export declare const hasInboundConflict: (schemas: JsonSchema[]) => boolean;
 type PropagationNode = {

package/dist/_schemas/port-spec.js

@@ -1,12 +1,12 @@
 import { z } from "zod";
-// ポートの kind 別型システム（docs/tasks/wip/ポートのkind別仕様.md）。
+// ポートの kind 別型システム（docs/tasks/done/ポートのkind別仕様.md）。
 // 型の決まり方は2分類：宣言（program / ai の in・out。human はビューの宣言を転写）／
 // 導出（それ以外。接続元から伝播し、結果は ports.schema にキャッシュする）。
 // mawaru がコードで型を固定するポートは無い
-// （docs/tasks/wip/ポート型固定の撤去とセッション再開のポート属性化.md）
+// （docs/tasks/done/ポート型固定の撤去とセッション再開のポート属性化.md）
 // 「まだ型が決まっていない」＝未宣言を {} で表す（未接続・上流が未宣言・fan-in の型割れ）。
 // 「何でも受ける」型は存在しない：program / ai の in は接続元の具体型を鏡映する
-// （docs/tasks/wip/ポートスキーマのany撲滅.md）
+// （docs/tasks/done/ポートスキーマのany撲滅.md）
 export const UNDECLARED_SCHEMA = {};
 export const isUndeclaredSchema = (schema) => Object.keys(schema).length === 0 || schema.type === undefined;
 // ---- file 型（docs/tasks/done/AIノードのファイル入力（file型と添付）.md） ----
@@ -14,7 +14,7 @@ export const isUndeclaredSchema = (schema) => Object.keys(schema).length === 0 |
 // ではなく storage path の参照で、署名 URL はどこにも焼き込まない。
 // **file の位置は名前ではなくこのマーカーで決まる**：runner が宣言スキーマと値を並行走査して
 // 入力はワークスペースへ materialize（パスに置換）、出力はアップロード（参照に置換）する
-// （docs/tasks/wip/ポートスキーマ編集でファイル型を選べるようにする.md）。
+// （docs/tasks/done/ポートスキーマ編集でファイル型を選べるようにする.md）。
 // ajv は strict:false で未知キーワードを無視するので検証は素の JSON Schema のまま。
 export const FILE_SCHEMA_MARKER = "x-mawaru-type";
 export const FILE_SCHEMA_TYPE = "file";
@@ -199,22 +199,53 @@ export const kindPortsViolation = (kind, ports) => {
 // 宣言 out（program / ai）は触らない。
 // program / ai の in は**全ての口が**接続鏡映（sticky）：接続元 out が具体型のときだけ
 // 上書きし、未接続・型割れ・未宣言は現スキーマ（宣言）を維持する（鏡映結果は repo の
-// config.json へも書き戻される。docs/tasks/wip/ポート編集のrepo書き戻し同期.md）
+// config.json へも書き戻される。docs/tasks/done/ポート編集のrepo書き戻し同期.md）
+// ---- 型としての同一性（schemaTypeKey） ----
+// 「同じ型か」を判定する唯一の物差し。合流（fan-in）・end の in の畳み込み・
+// グループ化の入口・エディタの着地判定が全部これを使う。
+// 素の JSON 等値だと、意味の同じ型が **注釈の差** や **キーの並び順** だけで別型に
+// 見えて合流できなくなる（古い取り込みで ports.schema に残った title が典型）。
+// 型＝構造なので、人間向けの注釈は落とし、順序に意味の無い集合は並べ直して比べる。
+// default は「フォームの初期値」という挙動なので型の一部として残す。
+// x-mawaru-type（file の nominal マーカー）も当然残す
+const ANNOTATION_KEYWORDS = new Set([
+    "title",
+    "description",
+    "$comment",
+    "examples",
+    "deprecated",
+]);
+// required は集合（並びに意味が無い）。properties のキー順は表示順として意味を
+// 持ちうるが、型の同一性には効かせない
+const canonicalize = (value, key) => {
+    if (Array.isArray(value)) {
+        const items = value.map((v) => canonicalize(v));
+        return key === "required" ? [...items].sort() : items;
+    }
+    if (value === null || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .filter(([k]) => !ANNOTATION_KEYWORDS.has(k))
+        .map(([k, v]) => [k, canonicalize(v, k)])
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+};
+export const schemaTypeKey = (schema) => JSON.stringify(canonicalize(schema));
 // 複数の流入（fan-in）から型を1つに決める：未宣言を除いて具体型が1種類ならその型、
 // 0種類なら未宣言。2種類以上は型が割れているので未宣言に落とす
-// （保存時に graph.ts が 422 で弾く。伝播は止めずに固定点へ収束させる）
+// （保存時に graph.ts が 422 で弾く。伝播は止めずに固定点へ収束させる）。
+// 注釈だけが違う流入は同じ型なので、採用する1つを JSON 等値で安定に選ぶ
+// （接続の並び順で title が揺れて repo 書き戻しが空コミットを打たないように）
 export const mergeInboundSchemas = (schemas) => {
-    const uniq = [
-        ...new Set(schemas
-            .filter((s) => !isUndeclaredSchema(s))
-            .map((s) => JSON.stringify(s))),
-    ];
-    return uniq.length === 1 && uniq[0] !== undefined
-        ? JSON.parse(uniq[0])
-        : UNDECLARED_SCHEMA;
+    const declared = schemas.filter((s) => !isUndeclaredSchema(s));
+    if (new Set(declared.map(schemaTypeKey)).size !== 1)
+        return UNDECLARED_SCHEMA;
+    return declared
+        .map((s) => [JSON.stringify(s), s])
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))[0]?.[1];
 };
 // 流入の具体型が2種類以上あるか（＝同じポートに違う型を流し込んでいる）
-export const hasInboundConflict = (schemas) => new Set(schemas.filter((s) => !isUndeclaredSchema(s)).map((s) => JSON.stringify(s))).size > 1;
+export const hasInboundConflict = (schemas) => new Set(schemas.filter((s) => !isUndeclaredSchema(s)).map(schemaTypeKey))
+    .size > 1;
 // 「上流の out をそのままコピーする」（in）／「in と同型」（approve）を表す指示。
 // 承認ビューのカタログ（@mawaru/common）の COPY_UPSTREAM と同じ値
 export const COPY_UPSTREAM_SCHEMA = "T";

package/dist/_schemas/program-manifest.js

@@ -3,7 +3,7 @@ import { jsonSchemaSchema, portKeySchema } from "./node.js";
 import { manifestInKeysViolation } from "./port-spec.js";
 // nodes/program/<dir>/config.json（リポジトリ規約 v2）。プログラム自身が入出力スキーマを宣言し、
 // エディタが取り込んで ports を自動生成する（実行時の正は ports テーブルのまま。
-// docs/tasks/wip/プログラムのリポジトリ規約v2（ディレクトリ＋config.json）.md）。
+// docs/tasks/done/プログラムのリポジトリ規約v2（ディレクトリ＋config.json）.md）。
 // inputs / outputs は「ポート key → JSON Schema」のマップ。将来 join（in 複数）を導入しても
 // 形式が変わらないよう最初から複数形にしてある
 export const programManifestSchema = z

package/dist/typegen.js

@@ -78,6 +78,13 @@ export const tsTypeFromJsonSchema = (schema, indent = 0) => {
     if (typeof schema !== "object" || schema === null || Array.isArray(schema)) {
         return "unknown";
     }
+    // file 型（x-mawaru-type マーカー）：runner が実行前に参照を実体化し、その位置を
+    // ワークスペースのローカルパス（文字列）に置き換えて handler へ渡す／handler は
+    // 出力にローカルパスを書く契約なので、参照 object ではなく string を生成する
+    // （AI 側の schemaWithFilesAsPath と同じ規約）
+    if (schema["x-mawaru-type"] === "file") {
+        return "string";
+    }
     if ("const" in schema) {
         return literalType(schema.const);
     }

package/package.json

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