@mawaru/sdk 0.5.0

package/dist/_schemas/graph.d.ts

@@ -0,0 +1,226 @@
+import { z } from "zod";
+export declare const refsBagSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export type RefsBag = z.infer<typeof refsBagSchema>;
+export declare const loopRefsSchema: z.ZodObject<{
+    type: z.ZodLiteral<"object">;
+    properties: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    required: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type LoopRefs = z.infer<typeof loopRefsSchema>;
+export declare const EMPTY_LOOP_REFS: LoopRefs;
+export declare const refsDefaultsOf: (refs: LoopRefs) => RefsBag;
+export declare const editableNodeKindSchema: z.ZodEnum<{
+    ai: "ai";
+    human: "human";
+    program: "program";
+    wait: "wait";
+}>;
+export type EditableNodeKind = z.infer<typeof editableNodeKindSchema>;
+export declare const graphNodeKindSchema: z.ZodEnum<{
+    ai: "ai";
+    human: "human";
+    program: "program";
+    wait: "wait";
+    start: "start";
+    end: "end";
+}>;
+export type GraphNodeKind = z.infer<typeof graphNodeKindSchema>;
+export declare const waitConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    wait_type: z.ZodLiteral<"duration">;
+    duration_seconds: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    wait_type: z.ZodLiteral<"until">;
+    until_at: z.ZodISODateTime;
+}, z.core.$strip>, z.ZodObject<{
+    wait_type: z.ZodLiteral<"cron">;
+    cron_expr: z.ZodString;
+}, z.core.$strip>], "wait_type">;
+export type WaitConfig = z.infer<typeof waitConfigSchema>;
+export declare const programConfigSchema: z.ZodObject<{
+    program_dir: z.ZodString;
+    ref: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ProgramConfig = z.infer<typeof programConfigSchema>;
+export declare const aiConfigSchema: z.ZodObject<{
+    ai_dir: z.ZodString;
+    ref: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AiConfig = z.infer<typeof aiConfigSchema>;
+export declare const humanConfigSchema: z.ZodObject<{
+    assignment: z.ZodObject<{
+        strategy: z.ZodDefault<z.ZodEnum<{
+            fixed: "fixed";
+            round_robin: "round_robin";
+        }>>;
+        approval_mode: z.ZodDefault<z.ZodEnum<{
+            any: "any";
+            all: "all";
+        }>>;
+        units: z.ZodDefault<z.ZodArray<z.ZodArray<z.ZodUUID>>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type HumanConfig = z.infer<typeof humanConfigSchema>;
+export declare const graphNodeHookSchema: z.ZodObject<{
+    hook_dir: z.ZodString;
+    ref: z.ZodOptional<z.ZodString>;
+    on_input: z.ZodBoolean;
+    on_output: z.ZodBoolean;
+    on_signal: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type GraphNodeHook = z.infer<typeof graphNodeHookSchema>;
+export declare const graphNodeSchema: z.ZodObject<{
+    id: z.ZodUUID;
+    kind: z.ZodEnum<{
+        ai: "ai";
+        human: "human";
+        program: "program";
+        wait: "wait";
+        start: "start";
+        end: "end";
+    }>;
+    name: z.ZodString;
+    ports: z.ZodArray<z.ZodObject<{
+        id: z.ZodUUID;
+        io: z.ZodEnum<{
+            in: "in";
+            out: "out";
+        }>;
+        key: z.ZodString;
+        name: z.ZodString;
+        schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        side: z.ZodOptional<z.ZodEnum<{
+            top: "top";
+            right: "right";
+            bottom: "bottom";
+            left: "left";
+        }>>;
+        offset: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    hooks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        hook_dir: z.ZodString;
+        ref: z.ZodOptional<z.ZodString>;
+        on_input: z.ZodBoolean;
+        on_output: z.ZodBoolean;
+        on_signal: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    position_x: z.ZodNumber;
+    position_y: z.ZodNumber;
+    wait: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        wait_type: z.ZodLiteral<"duration">;
+        duration_seconds: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        wait_type: z.ZodLiteral<"until">;
+        until_at: z.ZodISODateTime;
+    }, z.core.$strip>, z.ZodObject<{
+        wait_type: z.ZodLiteral<"cron">;
+        cron_expr: z.ZodString;
+    }, z.core.$strip>], "wait_type">>;
+    program: z.ZodOptional<z.ZodObject<{
+        program_dir: z.ZodString;
+        ref: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    ai: z.ZodOptional<z.ZodObject<{
+        ai_dir: z.ZodString;
+        ref: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    human: z.ZodOptional<z.ZodObject<{
+        assignment: z.ZodObject<{
+            strategy: z.ZodDefault<z.ZodEnum<{
+                fixed: "fixed";
+                round_robin: "round_robin";
+            }>>;
+            approval_mode: z.ZodDefault<z.ZodEnum<{
+                any: "any";
+                all: "all";
+            }>>;
+            units: z.ZodDefault<z.ZodArray<z.ZodArray<z.ZodUUID>>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type GraphNode = z.infer<typeof graphNodeSchema>;
+export declare const graphConnectionSchema: z.ZodObject<{
+    from_port_id: z.ZodUUID;
+    to_port_id: z.ZodUUID;
+}, z.core.$strip>;
+export type GraphConnection = z.infer<typeof graphConnectionSchema>;
+export declare const saveGraphBodySchema: z.ZodObject<{
+    nodes: z.ZodArray<z.ZodObject<{
+        id: z.ZodUUID;
+        kind: z.ZodEnum<{
+            ai: "ai";
+            human: "human";
+            program: "program";
+            wait: "wait";
+            start: "start";
+            end: "end";
+        }>;
+        name: z.ZodString;
+        ports: z.ZodArray<z.ZodObject<{
+            id: z.ZodUUID;
+            io: z.ZodEnum<{
+                in: "in";
+                out: "out";
+            }>;
+            key: z.ZodString;
+            name: z.ZodString;
+            schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            side: z.ZodOptional<z.ZodEnum<{
+                top: "top";
+                right: "right";
+                bottom: "bottom";
+                left: "left";
+            }>>;
+            offset: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        hooks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            hook_dir: z.ZodString;
+            ref: z.ZodOptional<z.ZodString>;
+            on_input: z.ZodBoolean;
+            on_output: z.ZodBoolean;
+            on_signal: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>>;
+        position_x: z.ZodNumber;
+        position_y: z.ZodNumber;
+        wait: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            wait_type: z.ZodLiteral<"duration">;
+            duration_seconds: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            wait_type: z.ZodLiteral<"until">;
+            until_at: z.ZodISODateTime;
+        }, z.core.$strip>, z.ZodObject<{
+            wait_type: z.ZodLiteral<"cron">;
+            cron_expr: z.ZodString;
+        }, z.core.$strip>], "wait_type">>;
+        program: z.ZodOptional<z.ZodObject<{
+            program_dir: z.ZodString;
+            ref: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        ai: z.ZodOptional<z.ZodObject<{
+            ai_dir: z.ZodString;
+            ref: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        human: z.ZodOptional<z.ZodObject<{
+            assignment: z.ZodObject<{
+                strategy: z.ZodDefault<z.ZodEnum<{
+                    fixed: "fixed";
+                    round_robin: "round_robin";
+                }>>;
+                approval_mode: z.ZodDefault<z.ZodEnum<{
+                    any: "any";
+                    all: "all";
+                }>>;
+                units: z.ZodDefault<z.ZodArray<z.ZodArray<z.ZodUUID>>>;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    connections: z.ZodArray<z.ZodObject<{
+        from_port_id: z.ZodUUID;
+        to_port_id: z.ZodUUID;
+    }, z.core.$strip>>;
+    refs: z.ZodDefault<z.ZodObject<{
+        type: z.ZodLiteral<"object">;
+        properties: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        required: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SaveGraphBody = z.infer<typeof saveGraphBodySchema>;

package/dist/_schemas/graph.js

@@ -0,0 +1,372 @@
+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());
+// ループ変数の定義＝袋全体を表す 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 const EMPTY_LOOP_REFS = { type: "object", properties: {} };
+// 定義スキーマ→デフォルト値の袋（default を持つプロパティだけ集める）。
+// run 起動時のマージの土台と、実行フォームの前埋めの両方が使う
+export const refsDefaultsOf = (refs) => 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",
+]);
+// グラフ一括保存で受け付ける kind（パレット作成の4種＋構造ノード start/end）。
+// start/end はパレットに出さないが、seed 済みなので全置換ボディには常に含まれる
+export const graphNodeKindSchema = nodeKindSchema.extract([
+    "ai",
+    "human",
+    "program",
+    "wait",
+    "start",
+    "end",
+]);
+// 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),
+    }),
+]);
+// 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(),
+});
+// 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(),
+});
+// 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 が重複しています",
+                });
+            }
+        });
+    }),
+});
+// ノードにアタッチされた 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),
+});
+// 新規ノードの 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 const graphConnectionSchema = z.object({
+    from_port_id: z.uuid(),
+    to_port_id: z.uuid(),
+});
+// 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"]) {
+        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();
+    const nodeByPortId = new Map();
+    graph.nodes.forEach((node, i) => {
+        const ioKeys = new Set();
+        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();
+        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();
+    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 の入力スキーマに適合しません（伝播型 ⊆ 宣言スキーマ）",
+            });
+        }
+    });
+});

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

@@ -0,0 +1,18 @@
+import { z } from "zod";
+export declare const hookEventSchema: z.ZodEnum<{
+    output: "output";
+    input: "input";
+    signal: "signal";
+}>;
+export type HookEvent = z.infer<typeof hookEventSchema>;
+export declare const hookManifestSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    on: z.ZodArray<z.ZodEnum<{
+        output: "output";
+        input: "input";
+        signal: "signal";
+    }>>;
+    env: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type HookManifest = z.infer<typeof hookManifestSchema>;

package/dist/_schemas/hook-manifest.js

@@ -0,0 +1,21 @@
+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 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([]),
+});