@mawaru/sdk 0.13.0 → 0.14.1

package/dist/_schemas/port-spec.js

@@ -1,10 +1,12 @@
 import { z } from "zod";
 // ポートの kind 別型システム（docs/tasks/wip/ポートのkind別仕様.md）。
-// 型の決まり方は3分類：宣言（program / AI の in・out）／固定（human reject の
-// content 型）／導出（それ以外。接続元から伝播し、結果は ports.schema にキャッシュする）
+// 型の決まり方は2分類：宣言（program / ai の in・out。human はビューの宣言を転写）／
+// 導出（それ以外。接続元から伝播し、結果は ports.schema にキャッシュする）。
+// mawaru がコードで型を固定するポートは無い
+// （docs/tasks/wip/ポート型固定の撤去とセッション再開のポート属性化.md）
 // 「まだ型が決まっていない」＝未宣言を {} で表す（未接続・上流が未宣言・fan-in の型割れ）。
-// 「何でも受ける」型は存在しない：AI の in は接続元の具体型を鏡映し、差し戻しの指示は
-// instruction ポートの宣言型を持つ（docs/tasks/wip/ポートスキーマのany撲滅.md）
+// 「何でも受ける」型は存在しない：program / ai の in は接続元の具体型を鏡映する
+// （docs/tasks/wip/ポートスキーマの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） ----
@@ -28,13 +30,12 @@ export const fileSchema = () => ({
     required: ["path", "name"],
 });
 export const isFileSchema = (schema) => schema[FILE_SCHEMA_MARKER] === FILE_SCHEMA_TYPE;
-// ---- 差し戻しの指示（AI の instruction ポート / human の reject ポート） ----
-// AI 入力の既存エンベロープ { prompt, files } と同じ形にする。配管が効く根拠は
-// files が file 型として宣言されていることであって、キー名ではない
-// （runner がマーカーで位置を見つけて materialize する）。
-// スクリーンショットを添えて差し戻すケースがあるので文章だけにしない
-// （docs/tasks/wip/ポートスキーマのany撲滅.md）
-export const AI_INSTRUCTION_PORT_KEY = "instruction";
+// ---- 差し戻しの指示のデフォルト型 ----
+// 雛形（エディタの既定ポート・ais/create）と承認ビューの既定宣言が参照する
+// **デフォルトであって強制ではない**：ユーザーはポートの宣言を自由に変えられ、
+// 接続の成立は通常の型検証だけが決める。配管が効く根拠は files が file 型として
+// 宣言されていることであって、キー名ではない（runner がマーカーで位置を見つけて
+// materialize する）。スクリーンショットを添えて差し戻すケースがあるので文章だけにしない
 export const instructionSchema = () => ({
     type: "object",
     properties: {
@@ -116,36 +117,6 @@ export const dataFormatOf = (schema) => {
         return null;
     return { format: "list", columns };
 };
-// 封筒型 { data: T, description: string }。T は任意の JSON Schema、description は
-// AI によるデータの説明（AI が必ず生成する）。AI の全出口に強制する
-export const envelopeSchemaOf = (dataSchema) => ({
-    type: "object",
-    properties: {
-        data: dataSchema,
-        description: { type: "string" },
-    },
-    required: ["data", "description"],
-});
-// 封筒型なら data のサブスキーマを返す（data キー必須の object。それ以外は null）
-export const envelopeDataSchemaOf = (schema) => {
-    if (schema.type !== "object")
-        return null;
-    const properties = (schema.properties ?? {});
-    const required = (schema.required ?? []);
-    const data = properties.data;
-    if (!data || !required.includes("data"))
-        return null;
-    return data;
-};
-// AI の出口として妥当な封筒型か：data と description: string の両方が必須
-export const isAiEnvelopeSchema = (schema) => {
-    if (envelopeDataSchemaOf(schema) === null)
-        return false;
-    const properties = (schema.properties ?? {});
-    const required = (schema.required ?? []);
-    return (properties.description?.type === "string" &&
-        required.includes("description"));
-};
 // ---- kind 別ポート構成 ----
 // human / wait は構成（数・key・io）が固定。program / ai は in 1つ＋out 1つ以上
 // （key 自由。複数 out＝分岐。AIノードの複数出口（分岐）.md）
@@ -160,19 +131,16 @@ const FIXED_PORT_KEYS = {
     component: { in: ["in"], out: ["main"] },
 };
 const FREE_OUT_KINDS = new Set(["program", "ai"]);
-// out は自由（複数出口＝分岐）だが in の構成は固定。ai は上流データを受ける in と、
-// 差し戻しの指示を受ける instruction の2口（意味の違う入力を1つのポートに
-// fan-in させない。docs/tasks/wip/ポートスキーマのany撲滅.md）
+// out は自由（複数出口＝分岐）。program は in の構成も固定（1口）だが、
+// ai は in も自由（追加・削除・key 自由。セッション再開は key ではなくポートの
+// resume 属性で決まる。ポート型固定の撤去とセッション再開のポート属性化.md）
 const FIXED_IN_KEYS = {
     program: ["in"],
-    ai: ["in", AI_INSTRUCTION_PORT_KEY],
 };
 export const fixedInKeysOf = (kind) => FIXED_IN_KEYS[kind] ?? null;
 // config.json（manifest）の inputs 検査（適合なら null）。同じルールを二重に持たないため
-// manifest 側はここを参照する（docs/tasks/wip/manifestのin複数対応（instructionポート）.md）。
-// **必須は "in" だけ**で、kind が固定する他の in（ai の instruction）は任意：スキーマは
-// constSchemaOf が焼き込む固定型なのでエディタ側で補え、in を2口に分ける前に同期された
-// config.json もそのまま読める
+// manifest 側はここを参照する。in の構成が固定の kind（program）だけが使う
+// （ai の inputs は key 自由なので ai-manifest 側で件数と key の規則だけ見る）
 export const manifestInKeysViolation = (kind, keys) => {
     const allowed = fixedInKeysOf(kind) ?? ["in"];
     if (!keys.includes("in"))
@@ -225,13 +193,12 @@ export const kindPortsViolation = (kind, ports) => {
 };
 // ---- 型伝播（導出ポートの解決） ----
 // 接続の両端は同じスキーマになる（値入力フォームのSchemaForm統一.md）。
-// wait / human は素通し（パラメトリック）ノード：in は接続元の out、out は in と同型。
-// 例外は human の approve：接続元が AI ノードのときだけ封筒を剥がして data 型になる。
-// human の reject は未宣言のまま（段階2 で instruction エンベロープを宣言する）。
+// wait は素通し（パラメトリック）ノード：in は接続元の out、out は in と同型。
+// human はビューの宣言を転写（"T" は素通しと同じ挙動。reject もビューの宣言）。
 // 宣言 out（program / ai）は触らない。
-// program / ai の in は接続鏡映（sticky）：接続元 out が具体型のときだけ上書きし、
-// 未接続・型割れ・未宣言は現スキーマ（宣言）を維持する（鏡映結果は repo の config.json
-// へも書き戻される。docs/tasks/wip/ポート編集のrepo書き戻し同期.md）
+// program / ai の in は**全ての口が**接続鏡映（sticky）：接続元 out が具体型のときだけ
+// 上書きし、未接続・型割れ・未宣言は現スキーマ（宣言）を維持する（鏡映結果は repo の
+// config.json へも書き戻される。docs/tasks/wip/ポート編集のrepo書き戻し同期.md）
 // 複数の流入（fan-in）から型を1つに決める：未宣言を除いて具体型が1種類ならその型、
 // 0種類なら未宣言。2種類以上は型が割れているので未宣言に落とす
 // （保存時に graph.ts が 422 で弾く。伝播は止めずに固定点へ収束させる）
@@ -258,34 +225,22 @@ const DERIVED_KINDS = new Set(["wait", "human", "end", "start"]);
 // in を接続鏡映（sticky）するノード：接続元 out が具体型のときだけ上書き
 const MIRROR_KINDS = new Set(["program", "ai"]);
 const isDerivedPort = (kind, port) => 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 は常に許可」は維持）
-// 宣言型で固定されるポート（導出も鏡映もしない）。差し戻しの指示エンベロープを
-// human の出口と AI の入口の両方に焼き込むことで、両端が同じ具体型で一致する
-const constSchemaOf = (kind, port) => {
-    if (kind === "human" && port.io === "out" && port.key === "reject") {
-        return instructionSchema();
-    }
-    if (kind === "ai" &&
-        port.io === "in" &&
-        port.key === AI_INSTRUCTION_PORT_KEY) {
-        return instructionSchema();
-    }
-    return null;
-};
+    (port.io === "in" ||
+        port.key === "main" ||
+        port.key === "approve" ||
+        port.key === "reject");
 // port_id → 解決済みスキーマ。導出は接続を遡って固定点まで反復し、
-// 未接続・純パラメトリック閉路・fan-in の型割れは未宣言に落とす
+// 未接続・純パラメトリック閉路・fan-in の型割れは未宣言に落とす。
+// ai の in は nodes/ai/<dir>/config.json の inputs[key].schema 由来の宣言型が初期値で、
+// 接続時は program と同じ鏡映で接続元と同値に同期される（どの in も対等。
+// instruction への型の焼き込みは廃止）
 export const resolvePortSchemas = (nodes, connections, options) => {
     const resolved = new Map();
     const kindByPortId = new Map();
     for (const node of nodes) {
         for (const port of node.ports) {
             kindByPortId.set(port.id, node.kind);
-            const constSchema = constSchemaOf(node.kind, port);
-            resolved.set(port.id, constSchema ??
-                (isDerivedPort(node.kind, port) ? UNDECLARED_SCHEMA : port.schema));
+            resolved.set(port.id, isDerivedPort(node.kind, port) ? UNDECLARED_SCHEMA : port.schema);
         }
     }
     // in ポートへの流入（差し戻しの fan-in があり得る。1本のときだけ型を採用）
@@ -337,20 +292,28 @@ export const resolvePortSchemas = (nodes, connections, options) => {
             const isMirror = MIRROR_KINDS.has(node.kind);
             if (!DERIVED_KINDS.has(node.kind) && !isMirror)
                 continue;
-            // ai は in が2口あるので、上流データの口（key="in"）だけを鏡映・導出の対象にする
-            const inPort = node.ports.find((p) => p.io === "in" && p.key === "in");
+            // 鏡映（program / ai）：全ての in が対象。具体型が流れてきたときだけ上書きする
+            // （宣言を未宣言で潰さない）。ai の in はどの口も対等（instruction の特別扱いは無い）
+            if (isMirror) {
+                for (const port of node.ports) {
+                    if (port.io !== "in")
+                        continue;
+                    const sources = inbound.get(port.id) ?? [];
+                    const inSchema = mergeInboundSchemas(sources.map((id) => resolved.get(id) ?? UNDECLARED_SCHEMA));
+                    if (!isUndeclaredSchema(inSchema))
+                        assign(port.id, inSchema);
+                }
+                continue;
+            }
+            // 導出（wait / human）：in は上流から
+            const inPort = node.ports.find((p) => p.io === "in");
             if (!inPort)
                 continue;
             const sources = inbound.get(inPort.id) ?? [];
             const inSchema = mergeInboundSchemas(sources.map((id) => resolved.get(id) ?? UNDECLARED_SCHEMA));
-            // 鏡映（program / ai）は具体型が流れてきたときだけ上書き（宣言を未宣言で潰さない）
-            if (isMirror) {
-                if (!isUndeclaredSchema(inSchema))
-                    assign(inPort.id, inSchema);
-                continue;
-            }
             // 承認ビューの宣言を human のポートへそのまま転写する（上流ノードの kind は見ない）。
-            // "T" は「上流の out をコピー」（in）／「in と同型」（approve）。
+            // "T" は「上流の out をコピー」（in）／「in と同型」（approve）。reject は具体型の宣言
+            // のみで、宣言が無ければ未宣言のまま（mawaru が型を焼き込むことはしない）。
             // 上流の out は書き換えない：逆伝播すると fan-out 先のビューが食い違ったとき
             // 型割れが config.json へ write-through され、元の出力宣言を黙って壊す。
             // ズレは接続の型エラーで見せてユーザーの [修正する] で直す
@@ -360,11 +323,16 @@ export const resolvePortSchemas = (nodes, connections, options) => {
                 : inSchema;
             assign(inPort.id, effectiveIn);
             for (const port of node.ports) {
-                if (port.io === "out" && isDerivedPort(node.kind, port)) {
-                    assign(port.id, declared && declared.out !== COPY_UPSTREAM_SCHEMA
-                        ? declared.out
-                        : effectiveIn);
+                if (port.io !== "out" || !isDerivedPort(node.kind, port))
+                    continue;
+                if (node.kind === "human" && port.key === "reject") {
+                    if (declared)
+                        assign(port.id, declared.reject);
+                    continue;
                 }
+                assign(port.id, declared && declared.approve !== COPY_UPSTREAM_SCHEMA
+                    ? declared.approve
+                    : effectiveIn);
             }
         }
         if (!changed)

package/dist/typegen.js

@@ -108,11 +108,11 @@ export const tsTypeFromJsonSchema = (schema, indent = 0) => {
     }
     return "unknown";
 };
-// Output（run の戻り値）＝「ちょうど1つの出口ポートのキーで返す封筒」の union。
+// Output（run の戻り値）＝「ちょうど1つの出口ポートのキーで返す { <出口キー>: 値 }」の union。
 // 他ポートのキーを ?: never で締めるのは excess property check の穴
-// （union の他メンバーにあるキーは許される）を塞ぐため。複数キー封筒は
-// エンジン（resolveOutputEnvelope）が実行時に拒否する契約で、それを tsc に前倒しする
-const envelopeUnionType = (outputKeys) => {
+// （union の他メンバーにあるキーは許される）を塞ぐため。複数キーの戻り値は
+// エンジン（resolvePortKeyedOutput）が実行時に拒否する契約で、それを tsc に前倒しする
+const outputUnionType = (outputKeys) => {
     const member = (key) => {
         const props = [
             `${propertyKey(key)}: Outputs[${JSON.stringify(key)}]`,
@@ -142,8 +142,8 @@ export const renderTypesFile = (manifest, rawConfig) => {
         "",
         `export type Outputs = {\n${outputEntries.join("\n")}\n}`,
         "",
-        "// run の戻り値：ちょうど1つの出口ポートのキーで返す封筒",
-        envelopeUnionType(Object.keys(manifest.outputs)),
+        "// run の戻り値：ちょうど1つの出口ポートのキーで返す { <出口キー>: 値 }",
+        outputUnionType(Object.keys(manifest.outputs)),
         "",
         ...(refEntries.length > 0
             ? [

package/docs/development.md

@@ -27,7 +27,7 @@ skills/<dir>/      # AI ノードが参照する skill（SKILL.md）
 - `config.json` — 入出力スキーマ等の宣言。正は `_schemas/program-manifest.ts`
   （`inputs` は `"in"` の1件だけ・`outputs` は1件以上・`env` は必要な secret 名の宣言）
 - `main.ts` — `run(input, ctx)` を export する。戻り値：
-  - `{ <出口ポートのkey>: <データ> }` の**単一キー封筒**（どの出口から出るかを戻り値自身が運ぶ）
+  - `{ <出口ポートのkey>: <データ> }` の**単一キーのオブジェクト**（どの出口から出るかを戻り値自身が運ぶ）
   - `"pending"` — 完了保留（外部イベントで後から end が届く）
 - `ctx` — ループ変数の袋の読み書き：
   - `ctx.refs` — 届いた袋（loop に定義された変数の、この step 開始時点の値）
@@ -46,6 +46,10 @@ skills/<dir>/      # AI ノードが参照する skill（SKILL.md）
 
 - `config.json` — 正は `_schemas/ai-manifest.ts`。`prompt`（必須）・`model`・
   `skills`（トップレベル `skills/` 配下のディレクトリ名）・`env`・`inputs` / `outputs`
+- `inputs` は1件以上・key 自由。値は `{ "schema": <JSON Schema>, "resume": true }` の形
+  （`resume` は省略可。true の口から入力が届いた実行は、同じノードの直近セッションを
+  復元して再開する——差し戻し→修正の続き実行に使う）。旧形式（値が素の JSON Schema）も
+  読める
 - 実行時はラッパーが Claude Code（headless）を起動し、`outputs` のスキーマに適合する
   output を検証して報告する。出口が複数あれば AI が1つ選ぶ（複数出口＝分岐）
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mawaru/sdk",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "mawaru 実行 repo の開発 SDK。契約スキーマ（config.json 規約・ループ graph API）の正 ＋ typegen / validate CLI",
   "type": "module",
   "bin": {
@@ -36,7 +36,6 @@
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "test:watch": "vitest",
-    "release": "sh -c 'pnpm typecheck && pnpm test && npm version --no-git-tag-version ${1:-minor} && pnpm publish --access public --no-git-checks' release"
+    "test:watch": "vitest"
   }
 }

package/skills/create-loop/SKILL.md

@@ -49,7 +49,7 @@ secret）でも、**足りない値を推測・生成・空文字で代用しな
   ノード・接続・refs（ループ変数）・hooks の形と、superRefine 内の全整合性ルール（日本語コメント付き）
 - `node_modules/@mawaru/sdk/_schemas/node.ts` — ポートの形（`graphPortSchema`）と key の規則
 - `node_modules/@mawaru/sdk/_schemas/port-spec.ts` — **kind 別の必須ポート構成**（`kindPortsViolation`）と
-  接続の型規則（human の in はカタログ型 envelope、program の in はスキーマ包含 等）
+  接続の型規則（human の in は承認ビューの宣言型、program の in はスキーマ包含 等）
 - `node_modules/@mawaru/sdk/_schemas/program-manifest.ts` / `ai-manifest.ts` — repo 側 config.json の規約
 - 同ディレクトリの `*.test.ts` — 通る graph / 弾かれる graph の実例集として読める
 

package/templates/CLAUDE.md

@@ -7,7 +7,7 @@
 ## 構成
 
 - `nodes/program/<dir>/` — Program ノード（`config.json` ＋ `main.ts`）。`main.ts` は
-  `run(input, ctx)` を export し、戻り値は `{ <出口ポートのkey>: <データ> }` の単一キー封筒
+  `run(input, ctx)` を export し、戻り値は `{ <出口ポートのkey>: <データ> }` の単一キーのオブジェクト
 - `nodes/ai/<dir>/` — AI ノード定義（`config.json`。prompt / model / skills / 入出力スキーマ / env）
 - `.github/workflows/mawaru-runner.yml` — mawaru 所有の実行シム。**編集しない**
   （`npx @mawaru/sdk init` が再生成する）

package/templates/echo/main.ts

@@ -1,4 +1,4 @@
 // サンプル handler：入力をそのまま main 出口へ返す。
-// 戻り値は { <出口ポートのkey>: <データ> } の単一キー封筒（出口の選別を戻り値自身が運ぶ）。
+// 戻り値は { <出口ポートのkey>: <データ> } の単一キーのオブジェクト（出口の選別を戻り値自身が運ぶ）。
 // 入出力の形は同じディレクトリの config.json が正（`npx mawaru typegen` で型も生成できる）
 export const run = async (input: { message: string }) => ({ main: input })

package/templates/mawaru-runner.yml

@@ -7,7 +7,7 @@
 # 自分で分岐する。ラッパーは config.json（nodes/program/<dir>/・nodes/ai/<dir>/）の env 宣言で
 # secrets を絞り、結果を検証して end_url へ「自分で」報告する。
 # Program handler は main.ts が run(input, ctx) を export し、戻り値＝{ <出口ポートのkey>: <データ> }
-# の単一キー封筒（出口の選別を戻り値自身が運ぶ）か "pending"（完了保留）で結末を表す。
+# の単一キーのオブジェクト（出口の選別を戻り値自身が運ぶ）か "pending"（完了保留）で結末を表す。
 # ファイル I/O（input.json / output.json / pending.json）はラッパーが肩代わりする
 # （run を export しない旧スクリプト規約も後方互換で動く）。
 # client_payload.step_id は冪等キー：is_irreversible な処理は step_id で二重実行を弾くこと。