@mawaru/sdk 0.32.0 → 0.33.0

package/_schemas/graph.test.ts

@@ -908,6 +908,16 @@ describe("saveGraphBodySchema（refs：ループ変数の定義スキーマ）",
     ).toThrow(/required/)
   })
 
+  it("properties に予約キー input（run の起動入力）は置けない", () => {
+    expect(() =>
+      saveGraphBodySchema.parse({
+        nodes: [makeNode()],
+        connections: [],
+        refs: { type: "object", properties: { input: { type: "string" } } },
+      }),
+    ).toThrow(/input/)
+  })
+
   it("object 以外の type・旧「値の袋」形は拒否する", () => {
     for (const refs of [
       { type: "string" },

package/_schemas/graph.ts

@@ -20,6 +20,12 @@ import {
 export const refsBagSchema = z.record(portKeySchema, z.unknown())
 export type RefsBag = z.infer<typeof refsBagSchema>
 
+// 予約キー：run の起動入力（runs.start_payload）。Run.start が袋に写し、全 step
+// （Program の refs.json・AI のプロンプト・承認ビューの ctx）から読める。
+// ループ定義には置けず、起動指定・end のパッチでも書けない
+// （起動入力をrefsに入れて全ノードから参照できるようにする.md）
+export const REFS_INPUT_KEY = "input"
+
 // ループ変数の定義＝袋全体を表す 1 つの object JSON Schema
 // （ループ変数（refs）のJSON Schema化.md）。properties のキーが変数名、
 // default が静的なデフォルト値、required は「run 起動時に値が確定して
@@ -31,6 +37,13 @@ export const loopRefsSchema = z
     required: z.array(portKeySchema).optional(),
   })
   .superRefine((refs, ctx) => {
+    if (REFS_INPUT_KEY in refs.properties) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["properties", REFS_INPUT_KEY],
+        message: `properties のキー ${REFS_INPUT_KEY} は予約キー（run の起動入力）です`,
+      })
+    }
     for (const key of refs.required ?? []) {
       if (!(key in refs.properties)) {
         ctx.addIssue({

package/dist/_schemas/graph.d.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 export declare const refsBagSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 export type RefsBag = z.infer<typeof refsBagSchema>;
+export declare const REFS_INPUT_KEY = "input";
 export declare const loopRefsSchema: z.ZodObject<{
     type: z.ZodLiteral<"object">;
     properties: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;

package/dist/_schemas/graph.js

@@ -6,6 +6,11 @@ import { hasInboundConflict, isSchemaSubset, kindPortsViolation, resolvePortSche
 // key はポート key と同じ規則（^[a-z][a-z0-9_]*$）。実行系ボディ
 // （run 起動の上書き・step end のパッチ）が使う契約
 export const refsBagSchema = z.record(portKeySchema, z.unknown());
+// 予約キー：run の起動入力（runs.start_payload）。Run.start が袋に写し、全 step
+// （Program の refs.json・AI のプロンプト・承認ビューの ctx）から読める。
+// ループ定義には置けず、起動指定・end のパッチでも書けない
+// （起動入力をrefsに入れて全ノードから参照できるようにする.md）
+export const REFS_INPUT_KEY = "input";
 // ループ変数の定義＝袋全体を表す 1 つの object JSON Schema
 // （ループ変数（refs）のJSON Schema化.md）。properties のキーが変数名、
 // default が静的なデフォルト値、required は「run 起動時に値が確定して
@@ -17,6 +22,13 @@ export const loopRefsSchema = z
     required: z.array(portKeySchema).optional(),
 })
     .superRefine((refs, ctx) => {
+    if (REFS_INPUT_KEY in refs.properties) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["properties", REFS_INPUT_KEY],
+            message: `properties のキー ${REFS_INPUT_KEY} は予約キー（run の起動入力）です`,
+        });
+    }
     for (const key of refs.required ?? []) {
         if (!(key in refs.properties)) {
             ctx.addIssue({

package/dist/typegen.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { REFS_INPUT_KEY } from "./_schemas/graph.js";
 import { programManifestSchema, } from "./_schemas/program-manifest.js";
 // 生成ファイルに刻む config.json 内容のハッシュ。validate が drift（config を変えて
 // typegen し忘れ）の検出に使う
@@ -139,8 +140,12 @@ export const renderTypesFile = (manifest, rawConfig) => {
     const inputSchema = manifest.inputs.in ?? {};
     const outputEntries = Object.entries(manifest.outputs).map(([key, schema]) => `  ${propertyKey(key)}: ${tsTypeFromJsonSchema(schema, 1)}`);
     // refs＝ループ変数の袋（実行時に refs.json で渡される）。config の refs はループ定義
-    // からの転写（キー→推定型）なので、宣言が無ければ型も出さない
-    const refEntries = Object.entries(manifest.refs).map(([key, schema]) => `  ${propertyKey(key)}: ${tsTypeFromJsonSchema(schema, 1)}`);
+    // からの転写（キー→推定型）。予約キー input（run の起動入力）は定義に現れないが
+    // 必ず袋に載るので、宣言が無くても Refs / Ctx を出す
+    const refEntries = [
+        `  ${propertyKey(REFS_INPUT_KEY)}: unknown`,
+        ...Object.entries(manifest.refs).map(([key, schema]) => `  ${propertyKey(key)}: ${tsTypeFromJsonSchema(schema, 1)}`),
+    ];
     return [
         "// このファイルは mawaru typegen が config.json から自動生成した（手で編集しない）",
         `${CONFIG_HASH_PREFIX}${configHash(rawConfig)}`,
@@ -152,16 +157,13 @@ export const renderTypesFile = (manifest, rawConfig) => {
         "// run の戻り値：ちょうど1つの出口ポートのキーで返す { <出口キー>: 値 }",
         outputUnionType(Object.keys(manifest.outputs)),
         "",
-        ...(refEntries.length > 0
-            ? [
-                `export type Refs = {\n${refEntries.join("\n")}\n}`,
-                "",
-                "// run の第2引数：refs＝届いた袋の読み、setRefs＝袋へのパッチの宣言",
-                "// （書いたキーだけが完了時に袋へマージされ、下流のノードから読める）",
-                "export type Ctx = { refs: Refs; setRefs: (patch: Partial<Refs>) => void }",
-                "",
-            ]
-            : []),
+        `export type Refs = {\n${refEntries.join("\n")}\n}`,
+        "",
+        "// run の第2引数：refs＝届いた袋の読み、setRefs＝袋へのパッチの宣言",
+        "// （書いたキーだけが完了時に袋へマージされ、下流のノードから読める。",
+        "// input は run の起動入力＝読み専用）",
+        "export type Ctx = { refs: Refs; setRefs: (patch: Partial<Refs>) => void }",
+        "",
     ].join("\n");
 };
 // nodes/program/ 直下の各 dir の config.json から types.d.ts を生成する

package/docs/development.md

@@ -30,7 +30,9 @@ skills/<dir>/      # AI ノードが参照する skill（SKILL.md）
   - `{ <出口ポートのkey>: <データ> }` の**単一キーのオブジェクト**（どの出口から出るかを戻り値自身が運ぶ）
   - `"pending"` — 完了保留（外部イベントで後から end が届く）
 - `ctx` — ループ変数の袋の読み書き：
-  - `ctx.refs` — 届いた袋（loop に定義された変数の、この step 開始時点の値）
+  - `ctx.refs` — 届いた袋（loop に定義された変数の、この step 開始時点の値）。
+    予約キー `ctx.refs.input` は **run の起動入力**（開始ノードに渡された値。コンポーネントの
+    中ならコンポーネントの入力）。読み専用で、loop の定義には置けず `setRefs` でも書けない
   - `ctx.setRefs({ key: value })` — 袋へのパッチの宣言。**完了時にだけ**反映され、以降の
     ノードが `ctx.refs` で読める（動的な値を下流へ渡す唯一の経路）。何度呼んでもトップレベル
     キー後勝ちで畳まれる。`"pending"` を返す実行では反映されない。loop に定義の無いキーを

package/package.json

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

package/skills/create-loop/SKILL.md

@@ -87,7 +87,8 @@ repo との矛盾・使用中ノードの削除は 409。**graph PUT は冪等
    - kind 別の固定ポート構成（human / wait / ai）は `port-spec.ts` の `kindPortsViolation` に従う
    - ループ変数（refs＝run 全体で読める key→値 の袋）が要るならトップレベルの `refs` に入れる。
      ノード単位の宣言やバインドは無い。handler は実行時に `refs.json` で全量を受け取り、
-     `end` の `refs` パッチで値を更新できる（config.json の `refs` はループ定義からの転写＝生成物）
+     `end` の `refs` パッチで値を更新できる（config.json の `refs` はループ定義からの転写＝生成物）。
+     キー `input` は予約（run の起動入力が自動で入る。定義に置くと 422）
    - `position_x` / `position_y` は左→右に流れる単純配置（例: x を 320 刻み、y は 240）
 5. **保存**：`PUT loops/{loopId}/graph`。400 / 422 / 409 ならメッセージを読んで直して再送。
 6. **報告**：エディタ URL `{MAWARU_APP_URL}/loops/{loopId}/edit` をユーザーに渡し、