@mawaru/sdk 0.5.0

package/_schemas/graph.ts

@@ -0,0 +1,439 @@
+import { z } from "zod"
+import {
+  graphPortSchema,
+  jsonSchemaSchema,
+  nodeKindSchema,
+  portKeySchema,
+} from "./node.js"
+import {
+  isAiEnvelopeSchema,
+  isSchemaSubset,
+  kindPortsViolation,
+  resolvePortSchemas,
+} from "./port-spec.js"
+
+// refs＝ループ変数の袋（key→任意の JSON 値。上流出力の参照（refs）.md）。
+// run 開始時に定義から複製され、全 step に全量差し込まれる。
+// key はポート key と同じ規則（^[a-z][a-z0-9_]*$）。実行系ボディ
+// （run 起動の上書き・step end のパッチ）が使う契約
+export const refsBagSchema = z.record(portKeySchema, z.unknown())
+export type RefsBag = z.infer<typeof refsBagSchema>
+
+// ループ変数の定義＝袋全体を表す 1 つの object JSON Schema
+// （ループ変数（refs）のJSON Schema化.md）。properties のキーが変数名、
+// default が静的なデフォルト値、required は「run 起動時に値が確定して
+// いなければならないキー」（実行中に handler が書くキーは required にしない）
+export const loopRefsSchema = z
+  .object({
+    type: z.literal("object"),
+    properties: z.record(portKeySchema, jsonSchemaSchema).default({}),
+    required: z.array(portKeySchema).optional(),
+  })
+  .superRefine((refs, ctx) => {
+    for (const key of refs.required ?? []) {
+      if (!(key in refs.properties)) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["required"],
+          message: `required のキー ${key} が properties にありません`,
+        })
+      }
+    }
+  })
+export type LoopRefs = z.infer<typeof loopRefsSchema>
+
+export const EMPTY_LOOP_REFS: LoopRefs = { type: "object", properties: {} }
+
+// 定義スキーマ→デフォルト値の袋（default を持つプロパティだけ集める）。
+// run 起動時のマージの土台と、実行フォームの前埋めの両方が使う
+export const refsDefaultsOf = (refs: LoopRefs): RefsBag =>
+  Object.fromEntries(
+    Object.entries(refs.properties)
+      .filter(([, schema]) => "default" in schema)
+      .map(([key, schema]) => [key, schema.default]),
+  )
+
+// パレットから作成できる kind（guardrail は後段の強化バックログ。
+// start/end は loop 作成時に seed される構造ノードなのでパレットには出さない）
+export const editableNodeKindSchema = nodeKindSchema.extract([
+  "ai",
+  "human",
+  "program",
+  "wait",
+])
+export type EditableNodeKind = z.infer<typeof editableNodeKindSchema>
+
+// グラフ一括保存で受け付ける kind（パレット作成の4種＋構造ノード start/end）。
+// start/end はパレットに出さないが、seed 済みなので全置換ボディには常に含まれる
+export const graphNodeKindSchema = nodeKindSchema.extract([
+  "ai",
+  "human",
+  "program",
+  "wait",
+  "start",
+  "end",
+])
+export type GraphNodeKind = z.infer<typeof graphNodeKindSchema>
+
+// Wait ノードの kind 別設定（node_waits の wait_type に対応する判別ユニオン）。
+// duration=経過秒、until=絶対時刻(ISO)、cron=cron 式（次回発火まで1回待つ）。
+// cron 式の妥当性は保存時に backend の cron パーサで検証する（ここは非空のみ）
+export const waitConfigSchema = z.discriminatedUnion("wait_type", [
+  z.object({
+    wait_type: z.literal("duration"),
+    duration_seconds: z.number().int().positive(),
+  }),
+  z.object({
+    wait_type: z.literal("until"),
+    until_at: z.iso.datetime({ offset: true }),
+  }),
+  z.object({
+    wait_type: z.literal("cron"),
+    cron_expr: z.string().min(1),
+  }),
+])
+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）。
+// ref 省略時はデフォルトブランチ
+export const programConfigSchema = z.object({
+  program_dir: z
+    .string()
+    .min(1)
+    .refine(
+      (v) => !v.includes("/") && !v.includes("\\") && v !== "." && v !== "..",
+      "program_dir は nodes/program/ 直下のディレクトリ名で指定してください",
+    ),
+  ref: z.string().min(1).optional(),
+})
+export type ProgramConfig = z.infer<typeof programConfigSchema>
+
+// AI ノードの kind 別設定（node_ais に対応）。定義の本体（prompt/model/skills/スキーマ/env）
+// は実行 repo の nodes/ai/<dir>/config.json が正（aiManifestSchema）で、ノードは参照だけ持つ
+// （programConfigSchema と同じ関係。実行repoの構造見直し）。ref 省略時はデフォルトブランチ
+export const aiConfigSchema = z.object({
+  ai_dir: z
+    .string()
+    .min(1)
+    .refine(
+      (v) => !v.includes("/") && !v.includes("\\") && v !== "." && v !== "..",
+      "ai_dir は nodes/ai/ 直下のディレクトリ名で指定してください",
+    ),
+  ref: z.string().min(1).optional(),
+})
+export type AiConfig = z.infer<typeof aiConfigSchema>
+
+// Human ノードの kind 別設定（node_humans ＋ node_human_assignees に対応）。
+// 担当 ＝ ユニット（1人以上のメンバー）の順序付きリスト ＋ 承認モード ＋ 選出戦略。
+// units[i] は user_id の配列（1人＝個人・複数＝グループ）。units 空 = tenant の誰でも。
+// approval_mode はノード単位（any=誰か1人 / all=全員。差し戻しは1人で成立＝veto）。
+// メンバーが tenant の membership であることの検証は保存 API 側で行う
+// （docs/tasks/backlog/Human担当者の高度化（複数人承認とラウンドロビン）.md）
+export const humanConfigSchema = z.object({
+  assignment: z
+    .object({
+      strategy: z.enum(["fixed", "round_robin"]).default("fixed"),
+      approval_mode: z.enum(["any", "all"]).default("any"),
+      units: z.array(z.array(z.uuid()).min(1)).default([]),
+    })
+    .superRefine((assignment, ctx) => {
+      if (assignment.strategy === "fixed" && assignment.units.length > 1) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["units"],
+          message: "fixed のユニットは1つまでです",
+        })
+      }
+      if (
+        assignment.strategy === "round_robin" &&
+        assignment.units.length < 2
+      ) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["units"],
+          message: "round_robin にはユニットが2つ以上必要です",
+        })
+      }
+      // ユニット内の重複は拒否（またぐ重複は「Aは毎回・相手が交代」の形があるので許す）
+      assignment.units.forEach((unit, i) => {
+        if (new Set(unit).size !== unit.length) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["units", i],
+            message: "ユニット内で user_id が重複しています",
+          })
+        }
+      })
+    }),
+})
+export type HumanConfig = z.infer<typeof humanConfigSchema>
+
+// ノードにアタッチされた IOHook（node_hooks に対応。アタッチできるのは program ノードのみ）。
+// on_input / on_output / on_signal はアタッチ時に repo の config.json（hookManifestSchema）から
+// エディタが焼き込むスナップショット。ref 省略時はデフォルトブランチ
+// （docs/tasks/wip/NodeIOHooks（ノードへのIOフックのアタッチ）.md・
+// NodeIOHooksのonSignal（外部シグナルでのフック発火）.md）
+export const graphNodeHookSchema = z.object({
+  hook_dir: z
+    .string()
+    .min(1)
+    .refine(
+      (v) => !v.includes("/") && !v.includes("\\") && v !== "." && v !== "..",
+      "hook_dir は nodes/hook/ 直下のディレクトリ名で指定してください",
+    ),
+  ref: z.string().min(1).optional(),
+  on_input: z.boolean(),
+  on_output: z.boolean(),
+  // 既存グラフ（on_signal 導入前の保存物）の互換のため省略時 false
+  on_signal: z.boolean().default(false),
+})
+export type GraphNodeHook = z.infer<typeof graphNodeHookSchema>
+
+// 新規ノードの id・ポートの id もクライアントが採番する（一時IDの解決を不要にする）
+export const graphNodeSchema = z.object({
+  id: z.uuid(),
+  kind: graphNodeKindSchema,
+  name: z.string().min(1),
+  ports: z.array(graphPortSchema),
+  hooks: z.array(graphNodeHookSchema).default([]),
+  position_x: z.number(),
+  position_y: z.number(),
+  // kind 別設定（自 kind のときだけ意味を持つ。省略時は保存側がデフォルトを補う）
+  wait: waitConfigSchema.optional(),
+  program: programConfigSchema.optional(),
+  ai: aiConfigSchema.optional(),
+  human: humanConfigSchema.optional(),
+})
+export type GraphNode = z.infer<typeof graphNodeSchema>
+
+export const graphConnectionSchema = z.object({
+  from_port_id: z.uuid(),
+  to_port_id: z.uuid(),
+})
+export type GraphConnection = z.infer<typeof graphConnectionSchema>
+
+// PUT /tenants/:tenantId/loops/:loopId/graph のボディ（グラフ一括保存）。
+// refs＝ループ変数の定義スキーマ（loops.refs）。回路と同じ「エディタの保存」で全置換する。
+// 開始/終了は専用 kind のノード（start/end）で表す（loops のカラムは廃止。
+// 開始・終了ノードの定義.md）。exactly-one と削除/追加禁止は状態依存なので put.ts が担い、
+// ここでは stateless な「各 kind 最大1つ」だけ見る
+export const saveGraphBodySchema = z
+  .object({
+    nodes: z.array(graphNodeSchema),
+    connections: z.array(graphConnectionSchema),
+    refs: loopRefsSchema.default(EMPTY_LOOP_REFS),
+  })
+  .superRefine((graph, ctx) => {
+    const nodeIds = new Set(graph.nodes.map((n) => n.id))
+    if (nodeIds.size !== graph.nodes.length) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["nodes"],
+        message: "node の id が重複しています",
+      })
+    }
+
+    // start / end は各 loop に最大1つ（seed により常にちょうど1つだが、契約としては最大1）
+    for (const kind of ["start", "end"] as const) {
+      if (graph.nodes.filter((n) => n.kind === kind).length > 1) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["nodes"],
+          message: `${kind} ノードは1つまでです`,
+        })
+      }
+    }
+
+    // ポートの形：id は全体で一意、(io, key) は node 内で一意、
+    // in ポートちょうど1つ（join 導入まで）＋ out ポート1つ以上
+    const portById = new Map<string, z.infer<typeof graphPortSchema>>()
+    const nodeByPortId = new Map<string, z.infer<typeof graphNodeSchema>>()
+    graph.nodes.forEach((node, i) => {
+      const ioKeys = new Set<string>()
+      let inCount = 0
+      let outCount = 0
+      node.ports.forEach((port, j) => {
+        if (portById.has(port.id)) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["nodes", i, "ports", j, "id"],
+            message: "port の id が重複しています",
+          })
+        }
+        portById.set(port.id, port)
+        nodeByPortId.set(port.id, node)
+
+        const ioKey = `${port.io}:${port.key}`
+        if (ioKeys.has(ioKey)) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["nodes", i, "ports", j, "key"],
+            message: "同じ io のポートで key が重複しています",
+          })
+        }
+        ioKeys.add(ioKey)
+
+        if (port.io === "in") inCount++
+        else outCount++
+      })
+      // end だけ「in は1つ以上」（複数ルートを別々の in で集約する）。
+      // start・他 kind は従来どおり1つ固定
+      if (node.kind === "end" ? inCount < 1 : inCount !== 1) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["nodes", i, "ports"],
+          message:
+            node.kind === "end"
+              ? "in ポートが1つ以上必要です"
+              : "in ポートはちょうど1つ必要です",
+        })
+      }
+      if (outCount < 1) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["nodes", i, "ports"],
+          message: "out ポートが最低1つ必要です",
+        })
+      }
+
+      // フックをアタッチできるのは program ノードのみ
+      if (node.kind !== "program" && node.hooks.length > 0) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["nodes", i, "hooks"],
+          message: "フックをアタッチできるのは program ノードだけです",
+        })
+      }
+
+      // フックの重複アタッチ（unique(node_id, hook_dir) の事前検証）
+      const hookDirs = new Set<string>()
+      node.hooks.forEach((hook, j) => {
+        if (hookDirs.has(hook.hook_dir)) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["nodes", i, "hooks", j, "hook_dir"],
+            message: "同じノードに hook_dir が重複しています",
+          })
+        }
+        hookDirs.add(hook.hook_dir)
+      })
+
+      // kind 別のポート構成（program 以外は数・key・io 固定。ポートのkind別仕様.md）
+      const violation = kindPortsViolation(node.kind, node.ports)
+      if (violation) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["nodes", i, "ports"],
+          message: violation,
+        })
+      }
+
+      // AI の出力宣言は封筒型 { data: T, description: string }（T は任意の JSON Schema）。
+      // 複数出口でも全出口に強制する（どの出口も human に接続できる不変条件）
+      if (node.kind === "ai") {
+        node.ports.forEach((port, j) => {
+          if (port.io === "out" && !isAiEnvelopeSchema(port.schema)) {
+            ctx.addIssue({
+              code: "custom",
+              path: ["nodes", i, "ports", j],
+              message:
+                "AI の出力は封筒型 { data, description } で宣言してください",
+            })
+          }
+        })
+      }
+    })
+
+    // 接続：両端がグラフ内の port を指し、from=out / to=in。
+    // 同じ out ポートから複数の in への fan-out は許す（並行分岐）。
+    // 禁止するのは完全重複（同じ from→to の2本）だけ
+    const usedPairs = new Set<string>()
+    graph.connections.forEach((conn, i) => {
+      const from = portById.get(conn.from_port_id)
+      if (!from || from.io !== "out") {
+        ctx.addIssue({
+          code: "custom",
+          path: ["connections", i, "from_port_id"],
+          message: "接続元がグラフ内の out ポートではありません",
+        })
+      }
+      const to = portById.get(conn.to_port_id)
+      if (!to || to.io !== "in") {
+        ctx.addIssue({
+          code: "custom",
+          path: ["connections", i, "to_port_id"],
+          message: "接続先がグラフ内の in ポートではありません",
+        })
+      }
+      const pair = `${conn.from_port_id}→${conn.to_port_id}`
+      if (usedPairs.has(pair)) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["connections", i, "to_port_id"],
+          message: "同じ接続が重複しています",
+        })
+      }
+      usedPairs.add(pair)
+    })
+
+    // 型の接続バリデーション（ポートのkind別仕様.md §接続バリデーション）。
+    // 導出ポートは接続から型を解決した上で判定する。ai の in・wait の in は常に許可
+    const resolved = resolvePortSchemas(graph.nodes, graph.connections)
+    graph.connections.forEach((conn, i) => {
+      const from = portById.get(conn.from_port_id)
+      const to = portById.get(conn.to_port_id)
+      const fromNode = nodeByPortId.get(conn.from_port_id)
+      const toNode = nodeByPortId.get(conn.to_port_id)
+      if (!from || !to || !fromNode || !toNode) return // 構造違反は検出済み
+
+      // start には引き込めない（run payload だけが入口）、end からは引き出せない（終端）
+      if (toNode.kind === "start") {
+        ctx.addIssue({
+          code: "custom",
+          path: ["connections", i, "to_port_id"],
+          message: "開始ノードには接続できません",
+        })
+      }
+      if (fromNode.kind === "end") {
+        ctx.addIssue({
+          code: "custom",
+          path: ["connections", i, "from_port_id"],
+          message: "終了ノードからは接続できません",
+        })
+      }
+
+      // human の reject の接続先は ai ノードのみ（kind 制約）
+      if (
+        fromNode.kind === "human" &&
+        from.key === "reject" &&
+        toNode.kind !== "ai"
+      ) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["connections", i, "to_port_id"],
+          message: "差し戻し（reject）の接続先は AI ノードのみです",
+        })
+      }
+
+      const fromSchema = resolved.get(conn.from_port_id) ?? from.schema
+
+      // human の in はどの型でも接続できる（上流が AI なら封筒 { data, description }、
+      // それ以外は input 全体を data として表示する。型制約は課さない）
+
+      // program の in への接続は 伝播型 ⊆ 宣言スキーマ。in は接続鏡映（sticky）なので
+      // 具体型の接続では自明に通り、接続元 any × 宣言維持のときだけ従来の意味を持つ
+      const toSchema = resolved.get(conn.to_port_id) ?? to.schema
+      if (toNode.kind === "program" && !isSchemaSubset(fromSchema, toSchema)) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["connections", i, "to_port_id"],
+          message:
+            "接続元の型が program の入力スキーマに適合しません（伝播型 ⊆ 宣言スキーマ）",
+        })
+      }
+    })
+  })
+export type SaveGraphBody = z.infer<typeof saveGraphBodySchema>

package/_schemas/hook-manifest.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest"
+import { hookManifestSchema } from "./hook-manifest.js"
+
+describe("hookManifestSchema", () => {
+  it("name / description / on / env を受け付ける", () => {
+    const manifest = hookManifestSchema.parse({
+      name: "監査ログ",
+      description: "in/out を通過したデータをスプレッドシートに追記する",
+      on: ["input", "output"],
+      env: ["SHEETS_API_KEY"],
+    })
+    expect(manifest.name).toBe("監査ログ")
+    expect(manifest.on).toEqual(["input", "output"])
+    expect(manifest.env).toEqual(["SHEETS_API_KEY"])
+  })
+
+  it("name / description / env は省略できる（env は [] が補われる）", () => {
+    const manifest = hookManifestSchema.parse({ on: ["input"] })
+    expect(manifest.name).toBeUndefined()
+    expect(manifest.env).toEqual([])
+  })
+
+  it("on は input / output / signal のみ・1件以上・重複なし", () => {
+    expect(() => hookManifestSchema.parse({ on: [] })).toThrow()
+    expect(() => hookManifestSchema.parse({ on: ["start"] })).toThrow()
+    expect(() => hookManifestSchema.parse({ on: ["input", "input"] })).toThrow()
+    expect(() => hookManifestSchema.parse({})).toThrow()
+  })
+
+  it("on: signal を受け付ける（onSignal＝外部シグナルでの発火）", () => {
+    expect(hookManifestSchema.parse({ on: ["signal"] }).on).toEqual(["signal"])
+    expect(
+      hookManifestSchema.parse({ on: ["input", "signal", "output"] }).on,
+    ).toEqual(["input", "signal", "output"])
+    expect(() =>
+      hookManifestSchema.parse({ on: ["signal", "signal"] }),
+    ).toThrow()
+  })
+
+  it("env は非空文字列のみ", () => {
+    expect(() =>
+      hookManifestSchema.parse({ on: ["input"], env: [""] }),
+    ).toThrow()
+  })
+})

package/_schemas/hook-manifest.ts

@@ -0,0 +1,25 @@
+import { z } from "zod"
+
+// nodes/hook/<dir>/config.json（NodeIOHooks）。フック自身が発火イベント（on）と
+// 必要 env を宣言し、エディタがアタッチ時に読んで node_hooks へ焼き込む
+// （programManifestSchema と同型の「repo が正・編集時に取り込む」方式。
+// docs/tasks/wip/NodeIOHooks（ノードへのIOフックのアタッチ）.md）。
+// フックは任意のノードに付くため inputs / outputs のスキーマ宣言は持たない（unknown を受ける）。
+// signal は外部シグナル（signals API）での発火（NodeIOHooksのonSignal（外部シグナルでのフック発火）.md）
+export const hookEventSchema = z.enum(["input", "output", "signal"])
+export type HookEvent = z.infer<typeof hookEventSchema>
+
+export const hookManifestSchema = z.object({
+  // 表示名（省略時はディレクトリ名）
+  name: z.string().min(1).optional(),
+  description: z.string().optional(),
+  // 発火イベントの宣言。エンジンはこれを見て dispatch を絞る
+  // （onInput の無いフックのために Actions run を無駄撃ちしない）
+  on: z
+    .array(hookEventSchema)
+    .min(1)
+    .refine((on) => new Set(on).size === on.length, "on が重複しています"),
+  // 実行に必要な secret 名の宣言（runner が宣言分だけを子プロセスへ渡す。program と同じ）
+  env: z.array(z.string().min(1)).default([]),
+})
+export type HookManifest = z.infer<typeof hookManifestSchema>

package/_schemas/node.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from "vitest"
+import { graphPortSchema, nodeKindSchema } from "./node.js"
+
+describe("nodeKindSchema", () => {
+  it("5種類の kind を受け付ける", () => {
+    for (const kind of ["ai", "human", "program", "guardrail", "wait"]) {
+      expect(nodeKindSchema.parse(kind)).toBe(kind)
+    }
+  })
+
+  it("不正な kind を拒否する", () => {
+    expect(() => nodeKindSchema.parse("loop")).toThrow()
+  })
+})
+
+describe("graphPortSchema", () => {
+  const base = {
+    id: "0f0e0d0c-0b0a-4a4b-8c8d-0e0f10111213",
+    io: "out",
+    key: "ok",
+    name: "OK",
+    schema: { type: "object" },
+  }
+
+  it("in / out のポートを受け付ける", () => {
+    expect(graphPortSchema.parse(base)).toEqual(base)
+    expect(graphPortSchema.parse({ ...base, io: "in", key: "in" })).toEqual({
+      ...base,
+      io: "in",
+      key: "in",
+    })
+  })
+
+  it("io が in / out 以外を拒否する", () => {
+    expect(() => graphPortSchema.parse({ ...base, io: "inout" })).toThrow()
+  })
+
+  it("key の規則違反（大文字・ハイフン・数字始まり）を拒否する", () => {
+    for (const bad of ["OK", "ng-port", "1st"]) {
+      expect(() => graphPortSchema.parse({ ...base, key: bad })).toThrow()
+    }
+  })
+
+  it("name（表示名）は自由テキスト。空文字だけ拒否する", () => {
+    expect(graphPortSchema.parse({ ...base, name: "承認 OK！" }).name).toBe(
+      "承認 OK！",
+    )
+    expect(() => graphPortSchema.parse({ ...base, name: "" })).toThrow()
+  })
+
+  it("id が uuid でないものを拒否する（クライアント採番）", () => {
+    expect(() => graphPortSchema.parse({ ...base, id: "port-1" })).toThrow()
+  })
+
+  it("side / offset（境界上の表示位置）を受け付ける。省略も可", () => {
+    const positioned = { ...base, side: "top", offset: 0.25 }
+    expect(graphPortSchema.parse(positioned)).toEqual(positioned)
+    expect(graphPortSchema.parse(base)).toEqual(base)
+  })
+
+  it("offset の範囲外・4値以外の side を拒否する", () => {
+    for (const offset of [-0.1, 1.5]) {
+      expect(() =>
+        graphPortSchema.parse({ ...base, side: "top", offset }),
+      ).toThrow()
+    }
+    expect(() =>
+      graphPortSchema.parse({ ...base, side: "middle", offset: 0.5 }),
+    ).toThrow()
+  })
+
+  it("side / offset の片方だけの指定を拒否する", () => {
+    expect(() => graphPortSchema.parse({ ...base, side: "top" })).toThrow()
+    expect(() => graphPortSchema.parse({ ...base, offset: 0.5 })).toThrow()
+  })
+})

package/_schemas/node.ts

@@ -0,0 +1,54 @@
+import { z } from "zod"
+
+export const nodeKindSchema = z.enum([
+  "ai",
+  "human",
+  "program",
+  "guardrail",
+  "wait",
+  // 開始・終了ノード（恒等パススルー。run は必ず start から始まり end で終わる。
+  // docs/tasks/wip/開始・終了ノードの定義.md）
+  "start",
+  "end",
+])
+export type NodeKind = z.infer<typeof nodeKindSchema>
+
+// ポート key（input/output 用の参照キー）の規則（db.md §2）。
+// name（ユーザーが見る表示名）は自由テキスト
+export const PORT_KEY_PATTERN = /^[a-z][a-z0-9_]*$/
+export const portKeySchema = z.string().regex(PORT_KEY_PATTERN)
+
+// 単一出口の既定ポート key／入力ポート key（db.md §2）
+export const DEFAULT_OUTPUT_PORT = "main"
+export const DEFAULT_INPUT_PORT = "in"
+
+// JSON Schema そのもの（中身の妥当性はここでは検証しない）
+export const jsonSchemaSchema = z.record(z.string(), z.unknown())
+export type JsonSchema = z.infer<typeof jsonSchemaSchema>
+
+export const portIoSchema = z.enum(["in", "out"])
+export type PortIo = z.infer<typeof portIoSchema>
+
+// ポートの表示位置＝ノード境界上の「辺＋辺上の比率」（top/bottom は左→右、
+// left/right は上→下）。エディタの見た目のみで実行・接続の意味には関与しない。
+// 未指定は自動配置（先頭=右辺中央・以降=下辺等間隔）
+export const portSideSchema = z.enum(["top", "right", "bottom", "left"])
+export type PortSide = z.infer<typeof portSideSchema>
+
+// グラフ保存契約のポート（ports テーブルの1行。id はクライアント採番。
+// docs/tasks/wip/ポートのテーブル化.md）
+export const graphPortSchema = z
+  .object({
+    id: z.uuid(),
+    io: portIoSchema,
+    key: portKeySchema,
+    name: z.string().min(1),
+    schema: jsonSchemaSchema,
+    side: portSideSchema.optional(),
+    offset: z.number().min(0).max(1).optional(),
+  })
+  .refine((p) => (p.side === undefined) === (p.offset === undefined), {
+    message: "side と offset は両方指定するか両方省略します",
+    path: ["side"],
+  })
+export type GraphPort = z.infer<typeof graphPortSchema>