@mawaru/sdk 0.8.0 → 0.9.0

package/_schemas/graph.test.ts

@@ -261,6 +261,37 @@ describe("humanConfigSchema", () => {
       humanConfigSchema.parse({ assignment: { units: [["not-a-uuid"]] } }),
     ).toThrow()
   })
+
+  it("run_starter：固定メンバーと混ぜて受け付ける（実行時に start_by で解決）", () => {
+    const u1 = uuid()
+    const parsed = humanConfigSchema.parse({
+      assignment: {
+        strategy: "fixed",
+        approval_mode: "all",
+        units: [["run_starter", u1]],
+      },
+    })
+    expect(parsed.assignment.units).toEqual([["run_starter", u1]])
+  })
+
+  it("run_starter：交代制（round_robin）との併用を拒否する", () => {
+    expect(() =>
+      humanConfigSchema.parse({
+        assignment: {
+          strategy: "round_robin",
+          units: [["run_starter"], [uuid()]],
+        },
+      }),
+    ).toThrow()
+  })
+
+  it("run_starter：ユニット内の重複を拒否する", () => {
+    expect(() =>
+      humanConfigSchema.parse({
+        assignment: { units: [["run_starter", "run_starter"]] },
+      }),
+    ).toThrow()
+  })
 })
 
 describe("saveGraphBodySchema", () => {

package/_schemas/graph.ts

@@ -130,9 +130,16 @@ export const aiConfigSchema = z.object({
 })
 export type AiConfig = z.infer<typeof aiConfigSchema>
 
+// 担当ユニットのメンバー：user_id の名指し、または動的な担当「ループを実行した人」
+// （run の起動者。実行時に runs.start_by で解決し、解決できなければその1人だけ落ちる。
+// docs/tasks/wip/Human担当に「ループを実行した人」を追加する.md）
+export const RUN_STARTER = "run_starter"
+export const assignMemberSchema = z.union([z.uuid(), z.literal(RUN_STARTER)])
+export type AssignMember = z.infer<typeof assignMemberSchema>
+
 // Human ノードの kind 別設定（node_humans ＋ node_human_assignees に対応）。
 // 担当 ＝ ユニット（1人以上のメンバー）の順序付きリスト ＋ 承認モード ＋ 選出戦略。
-// units[i] は user_id の配列（1人＝個人・複数＝グループ）。units 空 = tenant の誰でも。
+// units[i] はメンバーの配列（1人＝個人・複数＝グループ）。units 空 = tenant の誰でも。
 // approval_mode はノード単位（any=誰か1人 / all=全員。差し戻しは1人で成立＝veto）。
 // メンバーが tenant の membership であることの検証は保存 API 側で行う
 // （docs/tasks/backlog/Human担当者の高度化（複数人承認とラウンドロビン）.md）
@@ -147,7 +154,7 @@ export const humanConfigSchema = z.object({
     .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([]),
+      units: z.array(z.array(assignMemberSchema).min(1)).default([]),
     })
     .superRefine((assignment, ctx) => {
       if (assignment.strategy === "fixed" && assignment.units.length > 1) {
@@ -167,13 +174,25 @@ export const humanConfigSchema = z.object({
           message: "round_robin にはユニットが2つ以上必要です",
         })
       }
+      // 交代制と「ループを実行した人」は排他：どの回に誰が担当かが起動者と交代位置の
+      // 掛け算になって読めなくなるため、設定できる形の方を減らす
+      if (
+        assignment.strategy === "round_robin" &&
+        assignment.units.some((unit) => unit.includes(RUN_STARTER))
+      ) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["units"],
+          message: "round_robin の担当に「ループを実行した人」は入れられません",
+        })
+      }
       // ユニット内の重複は拒否（またぐ重複は「Aは毎回・相手が交代」の形があるので許す）
       assignment.units.forEach((unit, i) => {
         if (new Set(unit).size !== unit.length) {
           ctx.addIssue({
             code: "custom",
             path: ["units", i],
-            message: "ユニット内で user_id が重複しています",
+            message: "ユニット内で担当が重複しています",
           })
         }
       })

package/dist/_schemas/graph.d.ts

@@ -47,6 +47,9 @@ export declare const aiConfigSchema: z.ZodObject<{
     ref: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type AiConfig = z.infer<typeof aiConfigSchema>;
+export declare const RUN_STARTER = "run_starter";
+export declare const assignMemberSchema: z.ZodUnion<readonly [z.ZodUUID, z.ZodLiteral<"run_starter">]>;
+export type AssignMember = z.infer<typeof assignMemberSchema>;
 export declare const humanConfigSchema: z.ZodObject<{
     view: z.ZodOptional<z.ZodString>;
     view_config: z.ZodOptional<z.ZodNullable<z.ZodUnknown>>;
@@ -59,7 +62,7 @@ export declare const humanConfigSchema: z.ZodObject<{
             any: "any";
             all: "all";
         }>>;
-        units: z.ZodDefault<z.ZodArray<z.ZodArray<z.ZodUUID>>>;
+        units: z.ZodDefault<z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodUUID, z.ZodLiteral<"run_starter">]>>>>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 export type HumanConfig = z.infer<typeof humanConfigSchema>;
@@ -143,7 +146,7 @@ export declare const graphNodeSchema: z.ZodObject<{
                 any: "any";
                 all: "all";
             }>>;
-            units: z.ZodDefault<z.ZodArray<z.ZodArray<z.ZodUUID>>>;
+            units: z.ZodDefault<z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodUUID, z.ZodLiteral<"run_starter">]>>>>;
         }, z.core.$strip>;
     }, z.core.$strip>>;
     component: z.ZodOptional<z.ZodObject<{
@@ -225,7 +228,7 @@ export declare const saveGraphBodySchema: z.ZodObject<{
                     any: "any";
                     all: "all";
                 }>>;
-                units: z.ZodDefault<z.ZodArray<z.ZodArray<z.ZodUUID>>>;
+                units: z.ZodDefault<z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodUUID, z.ZodLiteral<"run_starter">]>>>>;
             }, z.core.$strip>;
         }, z.core.$strip>>;
         component: z.ZodOptional<z.ZodObject<{

package/dist/_schemas/graph.js

@@ -91,9 +91,14 @@ export const aiConfigSchema = z.object({
         .refine((v) => !v.includes("/") && !v.includes("\\") && v !== "." && v !== "..", "ai_dir は nodes/ai/ 直下のディレクトリ名で指定してください"),
     ref: z.string().min(1).optional(),
 });
+// 担当ユニットのメンバー：user_id の名指し、または動的な担当「ループを実行した人」
+// （run の起動者。実行時に runs.start_by で解決し、解決できなければその1人だけ落ちる。
+// docs/tasks/wip/Human担当に「ループを実行した人」を追加する.md）
+export const RUN_STARTER = "run_starter";
+export const assignMemberSchema = z.union([z.uuid(), z.literal(RUN_STARTER)]);
 // Human ノードの kind 別設定（node_humans ＋ node_human_assignees に対応）。
 // 担当 ＝ ユニット（1人以上のメンバー）の順序付きリスト ＋ 承認モード ＋ 選出戦略。
-// units[i] は user_id の配列（1人＝個人・複数＝グループ）。units 空 = tenant の誰でも。
+// units[i] はメンバーの配列（1人＝個人・複数＝グループ）。units 空 = tenant の誰でも。
 // approval_mode はノード単位（any=誰か1人 / all=全員。差し戻しは1人で成立＝veto）。
 // メンバーが tenant の membership であることの検証は保存 API 側で行う
 // （docs/tasks/backlog/Human担当者の高度化（複数人承認とラウンドロビン）.md）
@@ -108,7 +113,7 @@ export const humanConfigSchema = z.object({
         .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([]),
+        units: z.array(z.array(assignMemberSchema).min(1)).default([]),
     })
         .superRefine((assignment, ctx) => {
         if (assignment.strategy === "fixed" && assignment.units.length > 1) {
@@ -126,13 +131,23 @@ export const humanConfigSchema = z.object({
                 message: "round_robin にはユニットが2つ以上必要です",
             });
         }
+        // 交代制と「ループを実行した人」は排他：どの回に誰が担当かが起動者と交代位置の
+        // 掛け算になって読めなくなるため、設定できる形の方を減らす
+        if (assignment.strategy === "round_robin" &&
+            assignment.units.some((unit) => unit.includes(RUN_STARTER))) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["units"],
+                message: "round_robin の担当に「ループを実行した人」は入れられません",
+            });
+        }
         // ユニット内の重複は拒否（またぐ重複は「Aは毎回・相手が交代」の形があるので許す）
         assignment.units.forEach((unit, i) => {
             if (new Set(unit).size !== unit.length) {
                 ctx.addIssue({
                     code: "custom",
                     path: ["units", i],
-                    message: "ユニット内で user_id が重複しています",
+                    message: "ユニット内で担当が重複しています",
                 });
             }
         });

package/dist/typegen.js

@@ -146,7 +146,14 @@ export const renderTypesFile = (manifest, rawConfig) => {
         envelopeUnionType(Object.keys(manifest.outputs)),
         "",
         ...(refEntries.length > 0
-            ? [`export type Refs = {\n${refEntries.join("\n")}\n}`, ""]
+            ? [
+                `export type Refs = {\n${refEntries.join("\n")}\n}`,
+                "",
+                "// run の第2引数：refs＝届いた袋の読み、setRefs＝袋へのパッチの宣言",
+                "// （書いたキーだけが完了時に袋へマージされ、下流のノードから読める）",
+                "export type Ctx = { refs: Refs; setRefs: (patch: Partial<Refs>) => void }",
+                "",
+            ]
             : []),
     ].join("\n");
 };

package/docs/development.md

@@ -26,10 +26,17 @@ 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 する。`ctx.refs` にループ変数が入る。戻り値：
+- `main.ts` — `run(input, ctx)` を export する。戻り値：
   - `{ <出口ポートのkey>: <データ> }` の**単一キー封筒**（どの出口から出るかを戻り値自身が運ぶ）
   - `"pending"` — 完了保留（外部イベントで後から end が届く）
-- 型生成：`npx mawaru typegen` が config.json から `types.d.ts`（Input / Outputs 型）を生成する
+- `ctx` — ループ変数の袋の読み書き：
+  - `ctx.refs` — 届いた袋（loop に定義された変数の、この step 開始時点の値）
+  - `ctx.setRefs({ key: value })` — 袋へのパッチの宣言。**完了時にだけ**反映され、以降の
+    ノードが `ctx.refs` で読める（動的な値を下流へ渡す唯一の経路）。何度呼んでもトップレベル
+    キー後勝ちで畳まれる。`"pending"` を返す実行では反映されない。loop に定義の無いキーを
+    書くと step は failed になる
+- 型生成：`npx mawaru typegen` が config.json から `types.d.ts`（Input / Outputs / Refs / Ctx 型）を
+  生成する
 - **ノード単位の npm 依存**：`<dir>/package.json` を置けば実行前にそのディレクトリで
   `npm ci` される。`package-lock.json` の commit が必須（無いと明瞭に失敗する）
 - 環境変数：`config.json` の `env` に宣言した secret（repo の Actions secrets）だけが

package/package.json

@@ -1,20 +1,15 @@
 {
   "name": "@mawaru/sdk",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "mawaru 実行 repo の開発 SDK。契約スキーマ（config.json 規約・ループ graph API）の正 ＋ typegen / validate CLI",
   "type": "module",
   "bin": {
     "mawaru": "dist/cli.js"
   },
   "exports": {
-    ".": "./index.ts"
-  },
-  "publishConfig": {
-    "exports": {
-      ".": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      }
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   },
   "files": [
@@ -28,13 +23,6 @@
   "engines": {
     "node": ">=20"
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "prepack": "pnpm build",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
   "dependencies": {
     "zod": "^4.4.3",
     "zod-from-json-schema": "^0.5.3"
@@ -43,5 +31,11 @@
     "@types/node": "^26.1.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}