@mawaru/sdk 0.5.0

package/_schemas/port-spec.ts

@@ -0,0 +1,405 @@
+import { z } from "zod"
+import type { GraphPort, JsonSchema, PortIo } from "./node.js"
+
+// ポートの kind 別型システム（docs/tasks/wip/ポートのkind別仕様.md）。
+// 型の決まり方は3分類：宣言（program / AI の in・out）／固定（human reject の
+// content 型）／導出（それ以外。接続元から伝播し、結果は ports.schema にキャッシュする）
+
+// content 型・未接続の導出ポートは any（{}）で表す。content の意味（エンジンが
+// content に変換して注入する口）はスキーマではなく kind が決める
+export const ANY_SCHEMA: JsonSchema = {}
+
+export const isAnySchema = (schema: JsonSchema): boolean =>
+  Object.keys(schema).length === 0 || schema.type === undefined
+
+// ---- file 型（AI ノードのファイル入力。docs/tasks/wip/AIノードのファイル入力（file型と添付）.md） ----
+// schema 上の file は x-mawaru-type マーカー付きの object（nominal に識別する）。値はバイト
+// ではなく storage path の参照（url は startAiStep の dispatch 時に発行して client_payload に
+// のみ載せる）。ajv は strict:false で未知キーワードを無視するので検証は素の JSON Schema のまま。
+export const FILE_SCHEMA_MARKER = "x-mawaru-type"
+export const FILE_SCHEMA_TYPE = "file"
+
+export const fileSchema = (): JsonSchema => ({
+  type: "object",
+  [FILE_SCHEMA_MARKER]: FILE_SCHEMA_TYPE,
+  properties: {
+    path: { type: "string" },
+    name: { type: "string" },
+    mime_type: { type: "string" },
+    size: { type: "number" },
+  },
+  required: ["path", "name"],
+})
+
+export const isFileSchema = (schema: JsonSchema): boolean =>
+  schema[FILE_SCHEMA_MARKER] === FILE_SCHEMA_TYPE
+
+// ---- データフォーマットカタログ ----
+// human 承認 UI の表示・編集フォームの出し分けに使う（テキスト＝string（markdown）／
+// リスト＝Array<Row>（列定義つき））。バリデーションには使わない（data は任意の型）
+
+export const LIST_COLUMN_TYPES = [
+  "string",
+  "number",
+  "boolean",
+  "date",
+] as const
+export const listColumnTypeSchema = z.enum(LIST_COLUMN_TYPES)
+export type ListColumnType = z.infer<typeof listColumnTypeSchema>
+
+export const listColumnSchema = z.object({
+  key: z.string().min(1),
+  name: z.string().min(1),
+  type: listColumnTypeSchema,
+})
+export type ListColumn = z.infer<typeof listColumnSchema>
+
+export const dataFormatSchema = z.discriminatedUnion("format", [
+  z.object({ format: z.literal("text") }),
+  z.object({
+    format: z.literal("list"),
+    columns: z.array(listColumnSchema).min(1),
+  }),
+])
+export type DataFormat = z.infer<typeof dataFormatSchema>
+
+const columnTypeToJsonSchema = (type: ListColumnType): JsonSchema =>
+  type === "date" ? { type: "string", format: "date" } : { type }
+
+const columnTypeFromJsonSchema = (
+  schema: JsonSchema,
+): ListColumnType | null => {
+  if (schema.type === "string") {
+    return schema.format === "date" ? "date" : "string"
+  }
+  if (schema.type === "number" || schema.type === "boolean") return schema.type
+  return null
+}
+
+// フォーマット → S の JSON Schema。列の表示名は title に載せる
+export const dataSchemaOf = (format: DataFormat): JsonSchema => {
+  if (format.format === "text") return { type: "string" }
+  return {
+    type: "array",
+    items: {
+      type: "object",
+      properties: Object.fromEntries(
+        format.columns.map((col) => [
+          col.key,
+          { ...columnTypeToJsonSchema(col.type), title: col.name },
+        ]),
+      ),
+      required: format.columns.map((col) => col.key),
+    },
+  }
+}
+
+// S の JSON Schema → フォーマット（構造マッチの逆引き。カタログ外は null）
+export const dataFormatOf = (schema: JsonSchema): DataFormat | null => {
+  if (schema.type === "string" && schema.format === undefined) {
+    return { format: "text" }
+  }
+  if (schema.type !== "array") return null
+  const items = schema.items as JsonSchema | undefined
+  if (items?.type !== "object") return null
+  const properties = (items.properties ?? {}) as Record<string, JsonSchema>
+  const columns: ListColumn[] = []
+  for (const [key, prop] of Object.entries(properties)) {
+    const type = columnTypeFromJsonSchema(prop)
+    if (!type) return null
+    columns.push({ key, name: (prop.title as string | undefined) ?? key, type })
+  }
+  if (columns.length === 0) return null
+  return { format: "list", columns }
+}
+
+// 封筒型 { data: T, description: string }。T は任意の JSON Schema、description は
+// AI によるデータの説明（AI が必ず生成する）。AI の全出口に強制する
+export const envelopeSchemaOf = (dataSchema: JsonSchema): JsonSchema => ({
+  type: "object",
+  properties: {
+    data: dataSchema,
+    description: { type: "string" },
+  },
+  required: ["data", "description"],
+})
+
+// 封筒型なら data のサブスキーマを返す（data キー必須の object。それ以外は null）
+export const envelopeDataSchemaOf = (schema: JsonSchema): JsonSchema | null => {
+  if (schema.type !== "object") return null
+  const properties = (schema.properties ?? {}) as Record<string, JsonSchema>
+  const required = (schema.required ?? []) as string[]
+  const data = properties.data
+  if (!data || !required.includes("data")) return null
+  return data
+}
+
+// AI の出口として妥当な封筒型か：data と description: string の両方が必須
+export const isAiEnvelopeSchema = (schema: JsonSchema): boolean => {
+  if (envelopeDataSchemaOf(schema) === null) return false
+  const properties = (schema.properties ?? {}) as Record<string, JsonSchema>
+  const required = (schema.required ?? []) as string[]
+  return (
+    properties.description?.type === "string" &&
+    required.includes("description")
+  )
+}
+
+// ---- kind 別ポート構成 ----
+// human / wait は構成（数・key・io）が固定。program / ai は in 1つ＋out 1つ以上
+// （key 自由。複数 out＝分岐。AIノードの複数出口（分岐）.md）
+
+const FIXED_PORT_KEYS: Record<string, { in: string[]; out: string[] }> = {
+  human: { in: ["in"], out: ["approve", "reject"] },
+  wait: { in: ["in"], out: ["main"] },
+  // start は in 1つ（run 入力契約）＋ out main 1つの恒等パススルー
+  start: { in: ["in"], out: ["main"] },
+}
+
+const FREE_OUT_KINDS = new Set(["program", "ai"])
+
+// kind 別のポート構成違反を返す（適合なら null）。in=1/out>=1 の構造ルールは
+// graph.ts 側の既存チェックが担い、ここは key の固定だけ見る
+export const kindPortsViolation = (
+  kind: string,
+  ports: Pick<GraphPort, "io" | "key">[],
+): string | null => {
+  // end は out が main 1つ固定・in は1つ以上（複数ルートを別々の in で集約する。
+  // 開始・終了ノードの定義.md）。in の key は自由（自動採番）
+  if (kind === "end") {
+    const outKeys = ports.filter((p) => p.io === "out").map((p) => p.key)
+    if (outKeys.length !== 1 || outKeys[0] !== "main") {
+      return `end の out ポートは "main" ちょうど1つです`
+    }
+    if (!ports.some((p) => p.io === "in")) {
+      return `end には in ポートが1つ以上必要です`
+    }
+    return null
+  }
+  const fixed = FIXED_PORT_KEYS[kind]
+  if (!fixed) {
+    // program / ai（自由 out）：in の key だけ "in" 固定
+    if (
+      FREE_OUT_KINDS.has(kind) &&
+      ports.some((p) => p.io === "in" && p.key !== "in")
+    )
+      return `${kind} の in ポートの key は "in" です`
+    return null
+  }
+  const keysOf = (io: PortIo) =>
+    ports
+      .filter((p) => p.io === io)
+      .map((p) => p.key)
+      .sort()
+  const expect = (io: PortIo) => [...fixed[io]].sort()
+  if (
+    keysOf("in").join(",") !== expect("in").join(",") ||
+    keysOf("out").join(",") !== expect("out").join(",")
+  ) {
+    return `${kind} のポート構成は in(${fixed.in.join(",")}) / out(${fixed.out.join(",")}) 固定です`
+  }
+  return null
+}
+
+// ---- 型伝播（導出ポートの解決） ----
+// 接続の両端は同じスキーマになる（値入力フォームのSchemaForm統一.md）。
+// wait / human は素通し（パラメトリック）ノード：in は接続元の out、out は in と同型。
+// 例外は human の approve：接続元が AI ノードのときだけ封筒を剥がして data 型になる。
+// human の reject は content 固定（any）。宣言 out（program / ai）は触らない。
+// program / ai の in は接続鏡映（sticky）：接続元 out が具体型のときだけ上書きし、
+// 未接続・fan-in・any は現スキーマ（宣言）を維持する（鏡映結果は repo の config.json
+// へも書き戻される。docs/tasks/wip/ポート編集のrepo書き戻し同期.md）
+
+type PropagationNode = {
+  id: string
+  kind: string
+  ports: GraphPort[]
+}
+type PortLink = { from_port_id: string; to_port_id: string }
+
+// end も導出ノード（各 in は上流から、out main は any）。個別処理は
+// resolvePortSchemas 内で行うが、初期スキーマを any にするためここに含める。
+// start も導出ノード：out main は接続先の in から逆向きに転写し、in は out と同型
+// （run 入力契約＝接続先の入力宣言。開始ノードの入力契約を接続先から導出.md）
+const DERIVED_KINDS = new Set(["wait", "human", "end", "start"])
+
+// in を接続鏡映（sticky）するノード：接続元 out が具体型のときだけ上書き
+const MIRROR_KINDS = new Set(["program", "ai"])
+
+const isDerivedPort = (kind: string, port: Pick<GraphPort, "io" | "key">) =>
+  DERIVED_KINDS.has(kind) &&
+  (port.io === "in" || port.key === "main" || port.key === "approve")
+
+// AI の in は nodes/ai/<dir>/config.json の inputs.in 由来の宣言型が初期値で、
+// 接続時は program と同じ鏡映で接続元と同値に同期される（const 扱い廃止。
+// 接続バリデーションの「ai の in は常に許可」は維持）
+const isConstPort = (kind: string, port: Pick<GraphPort, "io" | "key">) =>
+  kind === "human" && port.io === "out" && port.key === "reject"
+
+// port_id → 解決済みスキーマ。導出は接続を遡って固定点まで反復し、
+// 未接続・複数流入・純パラメトリック閉路は any に落とす（MVP の割り切り）
+export const resolvePortSchemas = <N extends PropagationNode>(
+  nodes: N[],
+  connections: PortLink[],
+): Map<string, JsonSchema> => {
+  const resolved = new Map<string, JsonSchema>()
+  const kindByPortId = new Map<string, string>()
+  for (const node of nodes) {
+    for (const port of node.ports) {
+      kindByPortId.set(port.id, node.kind)
+      resolved.set(
+        port.id,
+        isDerivedPort(node.kind, port) || isConstPort(node.kind, port)
+          ? ANY_SCHEMA
+          : port.schema,
+      )
+    }
+  }
+  // in ポートへの流入（差し戻しの fan-in があり得る。1本のときだけ型を採用）
+  const inbound = new Map<string, string[]>()
+  // out ポートからの流出（start の逆向き転写が接続先の in を引くのに使う）
+  const outbound = new Map<string, string[]>()
+  for (const conn of connections) {
+    const list = inbound.get(conn.to_port_id) ?? []
+    list.push(conn.from_port_id)
+    inbound.set(conn.to_port_id, list)
+    const outs = outbound.get(conn.from_port_id) ?? []
+    outs.push(conn.to_port_id)
+    outbound.set(conn.from_port_id, outs)
+  }
+
+  for (let i = 0; i < nodes.length + 1; i++) {
+    let changed = false
+    for (const node of nodes) {
+      const assign = (portId: string, schema: JsonSchema) => {
+        if (JSON.stringify(resolved.get(portId)) !== JSON.stringify(schema)) {
+          resolved.set(portId, schema)
+          changed = true
+        }
+      }
+      // start：out main は接続先 in の解決値を転写（逆向き導出）。fan-out は
+      // 非 any が1種類（JSON 等値）のときだけ採用し、未接続・型割れは any。
+      // in は out main と同型（恒等の向きを out→in に逆転。run 入力契約は
+      // 接続先の入力宣言から自動で決まる）
+      if (node.kind === "start") {
+        const inPort = node.ports.find((p) => p.io === "in")
+        const outMain = node.ports.find(
+          (p) => p.io === "out" && p.key === "main",
+        )
+        if (inPort && outMain) {
+          const targets = (outbound.get(outMain.id) ?? [])
+            .map((id) => resolved.get(id) ?? ANY_SCHEMA)
+            .filter((s) => !isAnySchema(s))
+            .map((s) => JSON.stringify(s))
+          const uniq = [...new Set(targets)]
+          const schema =
+            uniq.length === 1 && uniq[0] !== undefined
+              ? (JSON.parse(uniq[0]) as JsonSchema)
+              : ANY_SCHEMA
+          assign(outMain.id, schema)
+          assign(inPort.id, schema)
+        }
+        continue
+      }
+      // end：各 in を自分の単一上流から導出（複数ルートを別 in で集約）。
+      // out main は any 固定（ルートごとに型が違いうる。Loop-in-Loop で詰める）
+      if (node.kind === "end") {
+        for (const port of node.ports) {
+          if (port.io !== "in") continue
+          const srcs = inbound.get(port.id) ?? []
+          assign(
+            port.id,
+            srcs.length === 1 && srcs[0] !== undefined
+              ? (resolved.get(srcs[0]) ?? ANY_SCHEMA)
+              : ANY_SCHEMA,
+          )
+        }
+        continue
+      }
+      const isMirror = MIRROR_KINDS.has(node.kind)
+      if (!DERIVED_KINDS.has(node.kind) && !isMirror) continue
+      const inPort = node.ports.find((p) => p.io === "in")
+      if (!inPort) continue
+      const sources = inbound.get(inPort.id) ?? []
+      const inSchema =
+        sources.length === 1 && sources[0] !== undefined
+          ? (resolved.get(sources[0]) ?? ANY_SCHEMA)
+          : ANY_SCHEMA
+      // 鏡映（program）は具体型が流れてきたときだけ上書き（宣言を any で潰さない）
+      if (isMirror) {
+        if (!isAnySchema(inSchema)) assign(inPort.id, inSchema)
+        continue
+      }
+      assign(inPort.id, inSchema)
+      // human の approve：接続元が AI ノードなら封筒 { data, description } を剥がして
+      // data 型を流す（承認は data だけを下流へ渡す）。それ以外の上流は従来どおり素通し
+      const fromAiNode =
+        sources.length === 1 &&
+        sources[0] !== undefined &&
+        kindByPortId.get(sources[0]) === "ai"
+      for (const port of node.ports) {
+        if (port.io === "out" && isDerivedPort(node.kind, port)) {
+          assign(
+            port.id,
+            node.kind === "human" && port.key === "approve" && fromAiNode
+              ? (envelopeDataSchemaOf(inSchema) ?? ANY_SCHEMA)
+              : inSchema,
+          )
+        }
+      }
+    }
+    if (!changed) break
+  }
+  return resolved
+}
+
+// ノード配列へ伝播結果を書き戻す（接続変更時のポートデータ自動更新）。
+// schema が変わらないポート・ノードは同じ参照を返す
+export const propagateDerivedPorts = <N extends PropagationNode>(
+  nodes: N[],
+  connections: PortLink[],
+): N[] => {
+  const resolved = resolvePortSchemas(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
+      touched = true
+      return { ...port, schema }
+    })
+    return touched ? { ...node, ports } : node
+  })
+}
+
+// ---- 接続バリデーション（伝播型 ⊆ 宣言スキーマ） ----
+// 完全な JSON Schema 包含ではなく実用的な構造チェック：any は素通し、type 一致、
+// object は宣言側 required の存在と型互換、array は items 互換
+
+export const isSchemaSubset = (sub: JsonSchema, sup: JsonSchema): boolean => {
+  if (isAnySchema(sup) || isAnySchema(sub)) return true
+  // file は nominal：マーカー一致の file 同士だけ可（file → any は上の any 判定で許可）。
+  // 構造が同じだけの普通の object は file に繋がない／file は普通の object に繋がない
+  if (isFileSchema(sub) || isFileSchema(sup))
+    return isFileSchema(sub) && isFileSchema(sup)
+  if (sub.type !== sup.type) return false
+  if (sup.type === "object") {
+    const subProps = (sub.properties ?? {}) as Record<string, JsonSchema>
+    const subRequired = (sub.required ?? []) as string[]
+    const supProps = (sup.properties ?? {}) as Record<string, JsonSchema>
+    for (const key of (sup.required ?? []) as string[]) {
+      const subProp = subProps[key]
+      if (!subProp || !subRequired.includes(key)) return false
+      const supProp = supProps[key]
+      if (supProp && !isSchemaSubset(subProp, supProp)) return false
+    }
+    return true
+  }
+  if (sup.type === "array") {
+    const supItems = sup.items as JsonSchema | undefined
+    const subItems = sub.items as JsonSchema | undefined
+    if (!supItems || !subItems) return true
+    return isSchemaSubset(subItems, supItems)
+  }
+  return true
+}

package/_schemas/program-manifest.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, it } from "vitest"
+import { programManifestSchema } from "./program-manifest.js"
+
+const stringSchema = { type: "string" }
+const objectSchema = {
+  type: "object",
+  properties: { to: { type: "string" } },
+  required: ["to"],
+}
+
+describe("programManifestSchema", () => {
+  it("name / description / inputs / outputs を受け付ける", () => {
+    const manifest = programManifestSchema.parse({
+      name: "返信を送る",
+      description: "問い合わせへの返信メールを送信する",
+      inputs: { in: objectSchema },
+      outputs: { main: objectSchema, bounced: stringSchema },
+    })
+    expect(manifest.name).toBe("返信を送る")
+    expect(Object.keys(manifest.outputs)).toEqual(["main", "bounced"])
+  })
+
+  it("name / description / env は省略できる（env は [] が補われる）", () => {
+    const manifest = programManifestSchema.parse({
+      inputs: { in: objectSchema },
+      outputs: { main: objectSchema },
+    })
+    expect(manifest.name).toBeUndefined()
+    expect(manifest.description).toBeUndefined()
+    expect(manifest.env).toEqual([])
+  })
+
+  it("env（使用する secret の宣言）を受け付ける・非空文字列のみ", () => {
+    const manifest = programManifestSchema.parse({
+      inputs: { in: objectSchema },
+      outputs: { main: objectSchema },
+      env: ["SENTRY_TOKEN", "SLACK_WEBHOOK_URL"],
+    })
+    expect(manifest.env).toEqual(["SENTRY_TOKEN", "SLACK_WEBHOOK_URL"])
+    expect(() =>
+      programManifestSchema.parse({
+        inputs: { in: objectSchema },
+        outputs: { main: objectSchema },
+        env: [""],
+      }),
+    ).toThrow()
+  })
+
+  it('inputs は "in" の1件だけ（join 導入まで）', () => {
+    const outputs = { main: objectSchema }
+    expect(() => programManifestSchema.parse({ inputs: {}, outputs })).toThrow()
+    expect(() =>
+      programManifestSchema.parse({ inputs: { data: objectSchema }, outputs }),
+    ).toThrow()
+    expect(() =>
+      programManifestSchema.parse({
+        inputs: { in: objectSchema, extra: objectSchema },
+        outputs,
+      }),
+    ).toThrow()
+  })
+
+  it("outputs は1件以上", () => {
+    expect(() =>
+      programManifestSchema.parse({
+        inputs: { in: objectSchema },
+        outputs: {},
+      }),
+    ).toThrow()
+  })
+
+  it("スキーマ値がオブジェクトでないものは拒否する", () => {
+    expect(() =>
+      programManifestSchema.parse({
+        inputs: { in: "string" },
+        outputs: { main: objectSchema },
+      }),
+    ).toThrow()
+  })
+
+  it("空文字の name を拒否する", () => {
+    expect(() =>
+      programManifestSchema.parse({
+        name: "",
+        inputs: { in: objectSchema },
+        outputs: { main: objectSchema },
+      }),
+    ).toThrow()
+  })
+
+  it("refs（上流出力の参照の宣言）を受け付ける・省略時は {} が補われる", () => {
+    const manifest = programManifestSchema.parse({
+      inputs: { in: objectSchema },
+      outputs: { main: objectSchema },
+      refs: { reply_to: stringSchema },
+    })
+    expect(manifest.refs).toEqual({ reply_to: stringSchema })
+    const omitted = programManifestSchema.parse({
+      inputs: { in: objectSchema },
+      outputs: { main: objectSchema },
+    })
+    expect(omitted.refs).toEqual({})
+  })
+
+  it("refs の key はポート key 規則（^[a-z][a-z0-9_]*$）", () => {
+    for (const key of ["Reply-To", "1st", "reply to"]) {
+      expect(() =>
+        programManifestSchema.parse({
+          inputs: { in: objectSchema },
+          outputs: { main: objectSchema },
+          refs: { [key]: stringSchema },
+        }),
+      ).toThrow()
+    }
+  })
+
+  it("refs のスキーマ値がオブジェクトでないものは拒否する", () => {
+    expect(() =>
+      programManifestSchema.parse({
+        inputs: { in: objectSchema },
+        outputs: { main: objectSchema },
+        refs: { reply_to: "string" },
+      }),
+    ).toThrow()
+  })
+})

package/_schemas/program-manifest.ts

@@ -0,0 +1,43 @@
+import { z } from "zod"
+import { jsonSchemaSchema, portKeySchema } from "./node.js"
+
+// nodes/program/<dir>/config.json（リポジトリ規約 v2）。プログラム自身が入出力スキーマを宣言し、
+// エディタが取り込んで ports を自動生成する（実行時の正は ports テーブルのまま。
+// docs/tasks/wip/プログラムのリポジトリ規約v2（ディレクトリ＋config.json）.md）。
+// inputs / outputs は「ポート key → JSON Schema」のマップ。将来 join（in 複数）を導入しても
+// 形式が変わらないよう最初から複数形にしてある
+export const programManifestSchema = z
+  .object({
+    // 表示名（省略時はディレクトリ名）
+    name: z.string().min(1).optional(),
+    description: z.string().optional(),
+    // 実行に必要な secret 名の宣言（runner が宣言分だけを子プロセスへ渡す。
+    // 実行repoの構造見直し）
+    env: z.array(z.string().min(1)).default([]),
+    inputs: z.record(z.string(), jsonSchemaSchema),
+    outputs: z.record(z.string(), jsonSchemaSchema),
+    // refs＝ループ変数の定義の転写（key → 値から推定した JSON Schema）。
+    // loop（エディタ）が正で、このセクションはグラフ保存が一方向に上書きする生成物。
+    // handler 実装者が「refs.json に何が来るか」を repo 側で見るためにある。
+    // 値そのものは repo に書かない（上流出力の参照（refs）.md）
+    refs: z.record(portKeySchema, jsonSchemaSchema).default({}),
+  })
+  .superRefine((manifest, ctx) => {
+    // グラフ側の既存制約（in ポートちょうど1つ・key "in" 固定）に整合させる
+    const inKeys = Object.keys(manifest.inputs)
+    if (inKeys.length !== 1 || inKeys[0] !== "in") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["inputs"],
+        message: 'inputs は "in" の1件だけ宣言してください（join 導入まで）',
+      })
+    }
+    if (Object.keys(manifest.outputs).length < 1) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["outputs"],
+        message: "outputs は1件以上宣言してください",
+      })
+    }
+  })
+export type ProgramManifest = z.infer<typeof programManifestSchema>

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

@@ -0,0 +1,25 @@
+import { z } from "zod";
+export declare const AI_MODELS: readonly ["claude-opus-4-8", "claude-sonnet-5", "claude-haiku-4-5"];
+export declare const aiModelSchema: z.ZodEnum<{
+    "claude-opus-4-8": "claude-opus-4-8";
+    "claude-sonnet-5": "claude-sonnet-5";
+    "claude-haiku-4-5": "claude-haiku-4-5";
+}>;
+export type AiModel = z.infer<typeof aiModelSchema>;
+export declare const DEFAULT_AI_MODEL = "claude-opus-4-8";
+export declare const aiManifestSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    prompt: z.ZodString;
+    model: z.ZodDefault<z.ZodEnum<{
+        "claude-opus-4-8": "claude-opus-4-8";
+        "claude-sonnet-5": "claude-sonnet-5";
+        "claude-haiku-4-5": "claude-haiku-4-5";
+    }>>;
+    skills: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    env: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    verbose: z.ZodOptional<z.ZodBoolean>;
+    inputs: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    outputs: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type AiManifest = z.infer<typeof aiManifestSchema>;

package/dist/_schemas/ai-manifest.js

@@ -0,0 +1,67 @@
+import { z } from "zod";
+import { jsonSchemaSchema } from "./node.js";
+import { isAiEnvelopeSchema } from "./port-spec.js";
+// AI ノードのモデル選択肢（既定は Opus：下書き品質が価値の中心。費用はユーザー持ち）
+export const AI_MODELS = [
+    "claude-opus-4-8",
+    "claude-sonnet-5",
+    "claude-haiku-4-5",
+];
+export const aiModelSchema = z.enum(AI_MODELS);
+export const DEFAULT_AI_MODEL = "claude-opus-4-8";
+// nodes/ai/<dir>/config.json（実行repoの構造見直し）。AI ノードの定義（prompt/model/skills/
+// 入出力スキーマ/env）は repo 側が正で、エディタが取り込んで ports を自動生成する
+// （実行時の正は ports テーブルのまま。プログラム規約 v2 と同じ関係）。
+// env は実行に必要な secret 名の宣言（runner が宣言分だけを子プロセスへ渡す）
+export const aiManifestSchema = z
+    .object({
+    // 表示名（省略時はディレクトリ名）
+    name: z.string().min(1).optional(),
+    description: z.string().optional(),
+    // repo に置く時点で完成品なので必須（DB 時代の「書きかけ空文字」は廃止）
+    prompt: z.string().min(1),
+    model: aiModelSchema.default(DEFAULT_AI_MODEL),
+    // 同 repo のトップレベル skills/ 配下のディレクトリ名
+    skills: z
+        .array(z
+        .string()
+        .regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/, "skill 名はディレクトリ名（英数字始まり）で指定してください"))
+        .default([]),
+    env: z.array(z.string().min(1)).default([]),
+    // 実行中の経過（発話・ツール呼び出し）を Actions ログへ逐次出すデバッグフラグ。
+    // 通常時は config.json にキーを書かない（インスペクタも false ならキーを消す）
+    verbose: z.boolean().optional(),
+    inputs: z.record(z.string(), jsonSchemaSchema),
+    outputs: z.record(z.string(), jsonSchemaSchema),
+})
+    .superRefine((manifest, ctx) => {
+    // グラフ側の既存制約（in ちょうど1つ・key "in"）に整合させる
+    const inKeys = Object.keys(manifest.inputs);
+    if (inKeys.length !== 1 || inKeys[0] !== "in") {
+        ctx.addIssue({
+            code: "custom",
+            path: ["inputs"],
+            message: 'inputs は "in" の1件だけ宣言してください（join 導入まで）',
+        });
+    }
+    // outputs は1件以上・key 自由（複数出口＝分岐。AIノードの複数出口（分岐）.md）
+    if (Object.keys(manifest.outputs).length < 1) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["outputs"],
+            message: "outputs は1件以上宣言してください",
+        });
+    }
+    // Human 承認 UI が依存する封筒型 { data: T, description: string } を全出口に強制
+    // （どの出口も human に接続できる、という AI ノードの不変条件。saveGraph と同じ判定。
+    // data＝T は任意の JSON Schema）
+    for (const [key, schema] of Object.entries(manifest.outputs)) {
+        if (!isAiEnvelopeSchema(schema)) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["outputs", key],
+                message: `outputs.${key} は封筒型 { data, description } で宣言してください（両方必須・description は string）`,
+            });
+        }
+    }
+});