@mawaru/sdk 0.40.0 → 0.41.0

package/_schemas/graph.ts

@@ -1,5 +1,4 @@
 import { z } from "zod"
-import { humanDeclarationSchema } from "./human-manifest.js"
 import {
   graphPortSchema,
   jsonSchemaSchema,
@@ -170,10 +169,6 @@ export const humanConfigSchema = z.object({
     .optional(),
   // 読むブランチ（省略時はデフォルトブランチ）。publish でその先頭の commit に固定する
   ref: z.string().min(1).optional(),
-  // 宣言の写し（in / approve / reject の型）。伝播はこれを読む。human_dir を選んだときに
-  // 一覧 API（GET /tenants/:id/github/humans）の宣言を入れる。省略すると保存時に mawaru が repo の
-  // config.json から読む（下書きに同じ human_dir の同じノードがあればその写しを保つ）
-  declaration: humanDeclarationSchema.optional(),
   assignment: z
     .object({
       strategy: z.enum(["fixed", "round_robin"]).default("fixed"),

package/_schemas/human-manifest.test.ts

@@ -1,10 +1,5 @@
 import { describe, expect, it } from "vitest"
-import {
-  humanDeclarationOfManifest,
-  humanDeclarationSchema,
-  humanManifestSchema,
-  STANDARD_HUMAN_DECLARATION,
-} from "./human-manifest.js"
+import { humanManifestSchema } from "./human-manifest.js"
 import { fileSchema, instructionSchema } from "./port-spec.js"
 
 const pr = {
@@ -12,118 +7,61 @@ const pr = {
   properties: {
     title: { type: "string", description: "PR のタイトル" },
     gifs: { type: "array", items: fileSchema() },
-    count: { type: "integer" },
   },
   required: ["title"],
 }
 
-const issuesOf = (value: unknown) => {
-  const parsed = humanDeclarationSchema.safeParse(value)
-  return parsed.success
-    ? []
-    : parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`)
+const messagesOf = (value: unknown) => {
+  const parsed = humanManifestSchema.safeParse(value)
+  return parsed.success ? [] : parsed.error.issues.map((i) => i.message)
 }
 
-describe("humanDeclarationSchema（宣言の検査）", () => {
-  it("標準ビューの宣言と具体型の宣言を通す", () => {
-    expect(issuesOf(STANDARD_HUMAN_DECLARATION)).toEqual([])
-    expect(
-      issuesOf({ in: pr, approve: pr, reject: instructionSchema() }),
-    ).toEqual([])
-    // 未宣言（{}）も宣言の1つ（スキーマ未定義）
-    expect(issuesOf({ in: {}, approve: "T", reject: {} })).toEqual([])
-  })
-
-  it("type の配列（nullable）は場所つきで弾く", () => {
-    expect(
-      issuesOf({
-        in: {
-          type: "object",
-          properties: { summary: { type: ["string", "null"] } },
-        },
-        approve: "T",
+describe("humanManifestSchema（nodes/human/<dir>/config.json）", () => {
+  it("in・approve・reject を書いた宣言を通す（追加の出口も書ける）", () => {
+    const config = {
+      inputs: { in: { schema: pr } },
+      outputs: {
+        approve: { type: "array", items: pr },
         reject: instructionSchema(),
-      }),
-    ).toEqual([
-      "in.properties.summary.type: 配列（nullable）は使えません。任意の値は required から外してください",
-    ])
+        notion: pr,
+      },
+    }
+    // refs はエディタが転写する生成物なので、無ければ空になる
+    expect(humanManifestSchema.parse(config)).toEqual({ ...config, refs: {} })
   })
 
-  it("知らない type・形の崩れた properties / required / items を弾く", () => {
-    expect(
-      issuesOf({
-        in: { type: "strin" },
-        approve: { type: "object", properties: [] },
-        reject: {
-          type: "object",
-          required: [1],
-          properties: { list: { type: "array", items: "x" } },
-        },
-      }),
-    ).toEqual([
-      "in.type: type は object / array / string / number / integer / boolean のどれかにしてください（strin）",
-      "approve.properties: properties はオブジェクトで書いてください",
-      "reject.properties.list.items: items はスキーマ（オブジェクト）で書いてください",
-      "reject.required: required は文字列の配列で書いてください",
+  it("in・approve・reject のどれかが無ければ弾く（省略したときの決まりは無い）", () => {
+    const full = {
+      inputs: { in: { schema: pr } },
+      outputs: { approve: pr, reject: instructionSchema() },
+    }
+    const violation =
+      "human のポート構成は in(in) と out(approve / reject) が必須です（out は追加できます）"
+    expect(messagesOf({ ...full, inputs: {} })).toEqual([violation])
+    expect(messagesOf({ ...full, outputs: { approve: pr } })).toEqual([
+      violation,
     ])
-  })
-
-  it("type の無い構造（properties / items だけ）を弾く", () => {
     expect(
-      issuesOf({
-        in: { properties: { a: { type: "string" } } },
-        approve: "T",
-        reject: instructionSchema(),
-      }),
-    ).toEqual([
-      "in.type: properties / items を書くときは type も書いてください",
-    ])
+      messagesOf({ ...full, outputs: { reject: instructionSchema() } }),
+    ).toEqual([violation])
+    expect(humanManifestSchema.safeParse({}).success).toBe(false)
   })
 
-  it('reject は上流のコピー（"T"）にできない', () => {
-    expect(issuesOf({ in: "T", approve: "T", reject: "T" })).not.toEqual([])
-  })
-})
-
-describe("humanManifestSchema（nodes/human/<dir>/config.json）", () => {
-  it("省略した口は上流のコピー（in）・in と同型（approve）・標準の差し戻し（reject）になる", () => {
-    const config = humanManifestSchema.parse({})
-    expect(humanDeclarationOfManifest(config)).toEqual(
-      STANDARD_HUMAN_DECLARATION,
-    )
-  })
-
-  it("書いた口の型をそのまま宣言にする", () => {
-    const config = humanManifestSchema.parse({
-      inputs: { in: { schema: pr } },
-      outputs: { approve: { type: "array", items: pr }, reject: pr },
-    })
-    expect(humanDeclarationOfManifest(config)).toEqual({
-      in: pr,
-      approve: { type: "array", items: pr },
-      reject: pr,
-    })
-  })
-
-  it("in / approve / reject 以外の口・知らないキーは弾く", () => {
-    expect(
-      humanManifestSchema.safeParse({ inputs: { instruction: {} } }).success,
-    ).toBe(false)
+  it("in 以外の入口は弾く", () => {
     expect(
-      humanManifestSchema.safeParse({ outputs: { notion: {} } }).success,
+      humanManifestSchema.safeParse({
+        inputs: { in: { schema: pr }, instruction: { schema: pr } },
+        outputs: { approve: pr, reject: instructionSchema() },
+      }).success,
     ).toBe(false)
-    expect(humanManifestSchema.safeParse({ name: "x" }).success).toBe(false)
   })
 
-  it("中の型も宣言の検査を通す", () => {
-    const parsed = humanManifestSchema.safeParse({
-      inputs: { in: { schema: { type: ["string", "null"] } } },
-    })
-    expect(parsed.success).toBe(false)
+  it('上流のコピー（"T"）は書けない（型は具体的に書く）', () => {
     expect(
-      parsed.error?.issues.map((i) => `${i.path.join(".")}: ${i.message}`),
-    ).toEqual([
-      "inputs.in.schema.type: 配列（nullable）は使えません。任意の値は required から外してください",
-    ])
+      humanManifestSchema.safeParse({
+        inputs: { in: { schema: "T" } },
+        outputs: { approve: "T", reject: instructionSchema() },
+      }).success,
+    ).toBe(false)
   })
 })

package/_schemas/human-manifest.ts

@@ -1,158 +1,31 @@
 import { z } from "zod"
-import { type JsonSchema, jsonSchemaSchema } from "./node.js"
-import {
-  COPY_UPSTREAM_SCHEMA,
-  type DeclaredPortSchema,
-  instructionSchema,
-} from "./port-spec.js"
-
-// ---- human ノードの宣言（in / approve / reject の型） ----
-// 正は実装を持つ側（顧客 repo の nodes/human/<dir>/config.json。実装を指さないノードは標準の宣言）。
-// human ノードは実装を選んだ時点の写し（node_humans.declaration）を持ち、伝播はそれを読む
-// （docs/tasks/wip/承認ビューの顧客repo配置.md の「宣言（ポート型）」）。
-// "T"（COPY_UPSTREAM_SCHEMA）は「上流の out をそのまま受ける」（in）／「in と同型」（approve）。
-// reject は具体型だけ（上流のコピーは意味を持たない）
-
-export type HumanDeclaration = {
-  in: DeclaredPortSchema
-  approve: DeclaredPortSchema
-  reject: JsonSchema
-}
-
-// 宣言に書ける type。file は x-mawaru-type マーカー付きの object
-const DECLARED_TYPES = [
-  "object",
-  "array",
-  "string",
-  "number",
-  "integer",
-  "boolean",
-] as const
-
-const isPlainObject = (value: unknown): value is Record<string, unknown> =>
-  typeof value === "object" && value !== null && !Array.isArray(value)
-
-// JSON Schema の形の崩れを場所つきで返す。接続の比較（schemaFit）が扱える形だけを通す：
-// 顧客 repo の宣言は mawaru のレビューを通らないので、壊れた型がノードに写る前に止める
-const schemaIssues = (
-  schema: Record<string, unknown>,
-  path: (string | number)[],
-): { path: (string | number)[]; message: string }[] => {
-  const issues: { path: (string | number)[]; message: string }[] = []
-  const { type, properties, required, items } = schema
-  if (Array.isArray(type)) {
-    issues.push({
-      path: [...path, "type"],
-      message:
-        "配列（nullable）は使えません。任意の値は required から外してください",
-    })
-  } else if (
-    type !== undefined &&
-    !DECLARED_TYPES.includes(type as (typeof DECLARED_TYPES)[number])
-  ) {
-    issues.push({
-      path: [...path, "type"],
-      message: `type は ${DECLARED_TYPES.join(" / ")} のどれかにしてください（${String(type)}）`,
-    })
-  } else if (
-    type === undefined &&
-    (properties !== undefined || items !== undefined)
-  ) {
-    issues.push({
-      path: [...path, "type"],
-      message: "properties / items を書くときは type も書いてください",
-    })
-  }
-  if (properties !== undefined) {
-    if (!isPlainObject(properties)) {
-      issues.push({
-        path: [...path, "properties"],
-        message: "properties はオブジェクトで書いてください",
-      })
-    } else {
-      for (const [key, child] of Object.entries(properties)) {
-        if (!isPlainObject(child)) {
-          issues.push({
-            path: [...path, "properties", key],
-            message: "スキーマはオブジェクトで書いてください",
-          })
-          continue
-        }
-        issues.push(...schemaIssues(child, [...path, "properties", key]))
-      }
-    }
-  }
-  if (
-    required !== undefined &&
-    !(Array.isArray(required) && required.every((r) => typeof r === "string"))
-  ) {
-    issues.push({
-      path: [...path, "required"],
-      message: "required は文字列の配列で書いてください",
-    })
-  }
-  if (items !== undefined) {
-    if (!isPlainObject(items)) {
-      issues.push({
-        path: [...path, "items"],
-        message: "items はスキーマ（オブジェクト）で書いてください",
-      })
-    } else {
-      issues.push(...schemaIssues(items, [...path, "items"]))
-    }
-  }
-  return issues
-}
-
-// 宣言に書く1つの型（検査つき）
-const checkedSchema = jsonSchemaSchema.superRefine((schema, ctx) => {
-  for (const issue of schemaIssues(schema, []))
-    ctx.addIssue({ code: "custom", ...issue })
-})
-
-const declaredPortSchema = z.union([
-  z.literal(COPY_UPSTREAM_SCHEMA),
-  checkedSchema,
-])
-
-export const humanDeclarationSchema = z.object({
-  in: declaredPortSchema,
-  approve: declaredPortSchema,
-  reject: checkedSchema,
-}) satisfies z.ZodType<HumanDeclaration>
-
-// 標準ビュー（common/standard）の宣言：上流の型をそのまま受けて出し、差し戻しは標準の指示フォーム
-export const STANDARD_HUMAN_DECLARATION: HumanDeclaration = {
-  in: COPY_UPSTREAM_SCHEMA,
-  approve: COPY_UPSTREAM_SCHEMA,
-  reject: instructionSchema(),
-}
-
-// ---- 顧客 repo の nodes/human/<dir>/config.json ----
-// 形は AI の config.json に揃える（inputs の値は { schema }、outputs の値は素の JSON Schema）。
-// 口は in / approve / reject 固定。省略した口は STANDARD_HUMAN_DECLARATION と同じ扱い
+import { jsonSchemaSchema, portKeySchema } from "./node.js"
+import { kindPortsViolation } from "./port-spec.js"
+
+// 顧客 repo の nodes/human/<dir>/config.json（human ノードの実装の入出力の宣言）。
+// program / AI の config.json と同じく、エディタがディレクトリを選んだときに inputs / outputs から
+// ports を起こし、ポートの編集は保存時にここへ書き戻される（実行時の正は ports テーブルのまま）。
+// 形は AI に揃える（inputs の値は { schema }、outputs の値は素の JSON Schema）。
+// 口の構成（in 1つ・approve / reject は必須・追加の出口は自由）は kind のポート構成の規則をそのまま使う
 export const humanManifestSchema = z
   .object({
-    inputs: z
-      .object({ in: z.object({ schema: checkedSchema }).strict().optional() })
-      .strict()
-      .optional(),
-    outputs: z
-      .object({
-        approve: checkedSchema.optional(),
-        reject: checkedSchema.optional(),
-      })
-      .strict()
-      .optional(),
+    inputs: z.record(z.string(), z.object({ schema: jsonSchemaSchema })),
+    outputs: z.record(z.string(), jsonSchemaSchema),
+    // refs＝ループ変数の定義の転写（program と同じ。エディタのグラフ保存が一方向に書く生成物）
+    refs: z.record(portKeySchema, jsonSchemaSchema).default({}),
+  })
+  .superRefine((manifest, ctx) => {
+    const violation = kindPortsViolation("human", [
+      ...Object.keys(manifest.inputs).map((key) => ({
+        io: "in" as const,
+        key,
+      })),
+      ...Object.keys(manifest.outputs).map((key) => ({
+        io: "out" as const,
+        key,
+      })),
+    ])
+    if (violation) ctx.addIssue({ code: "custom", message: violation })
   })
-  .strict()
 
 export type HumanManifest = z.infer<typeof humanManifestSchema>
-
-export const humanDeclarationOfManifest = (
-  config: HumanManifest,
-): HumanDeclaration => ({
-  in: config.inputs?.in?.schema ?? COPY_UPSTREAM_SCHEMA,
-  approve: config.outputs?.approve ?? COPY_UPSTREAM_SCHEMA,
-  reject: config.outputs?.reject ?? instructionSchema(),
-})

package/_schemas/port-spec.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, it } from "vitest"
-import type { HumanDeclaration } from "./human-manifest.js"
 import type { GraphPort, JsonSchema } from "./node.js"
 import {
   arrayOf,
@@ -154,20 +153,17 @@ describe("kindPortsViolation（kind 別ポート構成）", () => {
   })
 })
 
-// human ノードに実装の宣言の写し（node_humans.declaration）を持たせる
-const withViewDeclaration = <N extends { kind: string }>(
-  nodes: N[],
-  declaration: HumanDeclaration,
-) =>
+// 実装（nodes/human/<dir>/）を指す human にする
+const withHumanDir = <N extends { kind: string }>(nodes: N[]) =>
   nodes.map((node) =>
-    node.kind === "human" ? { ...node, human: { declaration } } : node,
+    node.kind === "human" ? { ...node, human: { human_dir: "review" } } : node,
   )
 
 describe("型伝播（導出ポートの解決）", () => {
   it.each([
     "notion_task",
     "main",
-  ])("Humanの追加出口 %s の宣言型は承認ビューの型で上書きしない", (key) => {
+  ])("Humanの追加出口 %s の宣言型は伝播で上書きしない", (key) => {
     const extra = port("out", key, {
       type: "object",
       properties: { title: { type: "string" } },
@@ -183,15 +179,10 @@ describe("型伝播（導出ポートの解決）", () => {
         extra,
       ],
     }
-    const resolved = resolvePortSchemas(
-      withViewDeclaration([human], {
-        in: { type: "string" },
-        approve: { type: "string" },
-        reject: { type: "string" },
-      }),
-      [],
-    )
-    expect(resolved.get(extra.id)).toEqual(extra.schema)
+    for (const nodes of [[human], withHumanDir([human])]) {
+      const resolved = resolvePortSchemas(nodes, [])
+      expect(resolved.get(extra.id)).toEqual(extra.schema)
+    }
   })
 
   // 伝播テスト用の任意の宣言型（中身の形に意味はない）
@@ -201,10 +192,9 @@ describe("型伝播（導出ポートの解決）", () => {
     required: ["text"],
   }
 
-  // human の in / approve / reject はビューの宣言をそのまま転写する（上流の kind は見ない）。
-  // 宣言はノードの写し（declaration）を読む（sdk はカタログを知らない）
-  // → docs/tasks/done/ポート型固定の撤去とセッション再開のポート属性化.md
-  it("ai → human 直結（コピー宣言）：in も approve も上流の out と同型、reject はビューの宣言型", () => {
+  // 実装を指さない human（標準の承認画面）は wait と同じ素通し。上流の kind は見ない
+  // → docs/tasks/wip/承認ビューの顧客repo配置.md の「ポート型」
+  it("実装を指さない human：in も approve も上流の out と同型、reject は標準の差し戻し", () => {
     const aiOut = port("out", "main", declaredOut)
     const ai = {
       id: uuid(),
@@ -220,11 +210,7 @@ describe("型伝播（導出ポートの解決）", () => {
       ports: [humanIn, approve, reject],
     }
     const resolved = resolvePortSchemas(
-      withViewDeclaration([ai, human], {
-        in: "T",
-        approve: "T",
-        reject: instructionSchema(),
-      }),
+      [ai, human],
       [{ from_port_id: aiOut.id, to_port_id: humanIn.id }],
     )
     // 上流が AI でも中身を取り出さない：AI の出力形式がそのまま下流へ流れる
@@ -233,25 +219,17 @@ describe("型伝播（導出ポートの解決）", () => {
     expect(resolved.get(reject.id)).toEqual(instructionSchema())
   })
 
-  describe("実装の宣言を human のポートへ転写する", () => {
+  describe("実装（nodes/human/<dir>/）を指す human は program / ai と同じ", () => {
     const viewIn = {
       type: "object",
-      properties: {
-        data: {
-          type: "object",
-          properties: { prs: { type: "array", items: { type: "object" } } },
-          required: ["prs"],
-        },
-        description: { type: "string" },
-      },
-      required: ["data", "description"],
+      properties: { prs: { type: "array", items: { type: "object" } } },
+      required: ["prs"],
     }
     const viewOut = {
       type: "object",
-      properties: { prs: { type: "array", items: { type: "object" } } },
-      required: ["prs"],
+      properties: { merged: { type: "boolean" } },
+      required: ["merged"],
     }
-    // reject もビューの宣言（具体型のみ。コピー指示は意味を持たない）
     const viewReject = {
       type: "object",
       properties: { reason: { type: "string" } },
@@ -264,91 +242,54 @@ describe("型伝播（導出ポートの解決）", () => {
         kind: upstreamKind,
         ports: [port("in", "in"), out],
       }
-      const humanIn = port("in", "in")
-      const approve = port("out", "approve")
-      const reject = port("out", "reject")
+      const humanIn = port("in", "in", viewIn)
+      const approve = port("out", "approve", viewOut)
+      const reject = port("out", "reject", viewReject)
       const human = {
         id: uuid(),
         kind: "human",
+        human: { human_dir: "review" },
         ports: [humanIn, approve, reject],
       }
       return { upstream, human, out, humanIn, approve, reject }
     }
 
-    it("宣言のあるビューは上流の kind に依らず同じ型になる", () => {
+    it("out（approve・reject）は宣言のまま（上流の kind に依らない）", () => {
       for (const kind of ["ai", "program"]) {
         const { upstream, human, out, humanIn, approve, reject } = build(
           kind,
           declaredOut,
         )
         const resolved = resolvePortSchemas(
-          withViewDeclaration([upstream, human], {
-            in: viewIn,
-            approve: viewOut,
-            reject: viewReject,
-          }),
+          [upstream, human],
           [{ from_port_id: out.id, to_port_id: humanIn.id }],
         )
-        expect(resolved.get(humanIn.id)).toEqual(viewIn)
         expect(resolved.get(approve.id)).toEqual(viewOut)
         expect(resolved.get(reject.id)).toEqual(viewReject)
       }
     })
 
-    it("上流の out は書き換えない（逆伝播しない）", () => {
+    it("in は上流の具体型を写す（program / ai の in と同じ鏡映）", () => {
       const { upstream, human, out, humanIn } = build("ai", declaredOut)
       const resolved = resolvePortSchemas(
-        withViewDeclaration([upstream, human], {
-          in: viewIn,
-          approve: viewOut,
-          reject: viewReject,
-        }),
-        [{ from_port_id: out.id, to_port_id: humanIn.id }],
-      )
-      expect(resolved.get(out.id)).toEqual(declaredOut)
-    })
-
-    it("コピー宣言（標準ビュー）は上流の型をそのまま in と approve へ流す", () => {
-      const { upstream, human, out, humanIn, approve } = build(
-        "ai",
-        declaredOut,
-      )
-      const resolved = resolvePortSchemas(
-        withViewDeclaration([upstream, human], {
-          in: "T",
-          approve: "T",
-          reject: viewReject,
-        }),
+        [upstream, human],
         [{ from_port_id: out.id, to_port_id: humanIn.id }],
       )
       expect(resolved.get(humanIn.id)).toEqual(declaredOut)
-      expect(resolved.get(approve.id)).toEqual(declaredOut)
+      // 上流の out は書き換えない（逆伝播しない）
+      expect(resolved.get(out.id)).toEqual(declaredOut)
     })
 
-    it("未接続でも宣言で固定される", () => {
-      const humanIn = port("in", "in")
-      const approve = port("out", "approve")
-      const reject = port("out", "reject")
-      const human = {
-        id: uuid(),
-        kind: "human",
-        ports: [humanIn, approve, reject],
-      }
-      const resolved = resolvePortSchemas(
-        withViewDeclaration([human], {
-          in: viewIn,
-          approve: viewOut,
-          reject: viewReject,
-        }),
-        [],
-      )
+    it("未接続の in は宣言のまま", () => {
+      const { human, humanIn, approve, reject } = build("ai", declaredOut)
+      const resolved = resolvePortSchemas([human], [])
       expect(resolved.get(humanIn.id)).toEqual(viewIn)
       expect(resolved.get(approve.id)).toEqual(viewOut)
       expect(resolved.get(reject.id)).toEqual(viewReject)
     })
   })
 
-  it("ai → wait → human：素通しで上流の宣言型が伝播し、reject はビュー宣言が無ければ未宣言", () => {
+  it("ai → wait → human：素通しで上流の宣言型が伝播し、reject は標準の差し戻し", () => {
     // ai の in は宣言型（nodes/ai/<dir>/config.json の inputs.in 由来。実行repoの構造見直し）
     const aiInSchema = {
       type: "object",
@@ -383,8 +324,8 @@ describe("型伝播（導出ポートの解決）", () => {
     expect(resolved.get(humanIn.id)).toEqual(declaredOut)
     // approve は in と同型（上流の kind による中身の取り出しはしない）
     expect(resolved.get(approve.id)).toEqual(declaredOut)
-    // reject はビューの宣言でのみ決まる（sdk 単体＝カタログ無しでは未宣言。型固定は廃止）
-    expect(resolved.get(reject.id)).toEqual(UNDECLARED_SCHEMA)
+    // reject は標準の承認画面の差し戻し（指示＋参考ファイル）
+    expect(resolved.get(reject.id)).toEqual(instructionSchema())
     // ai の in は宣言型がそのまま残る（const 扱いは廃止）
     expect(resolved.get(aiIn.id)).toEqual(aiInSchema)
   })