概念とドメインモデル

import { z } from "zod";

/**
 * 小さな JSON Schema（Draft 2020-12）のサブセット: tool/flow の I/O slot が
 * 取り得る型。スカラー、配列、オブジェクトを扱えるため、入力は単なる
 * スカラーに限定されません（tool はオブジェクト body や配列などを宣言できます）。
 */
export type JsonSchema =
  | { type: "string" | "number" | "boolean" | "null" }
  | { type: "array"; items: JsonSchema }
  | {
      type: "object";
      properties: Record<string, JsonSchema>;
      required?: string[];
      additionalProperties?: boolean;
    };

export const JsonSchemaSchema: z.ZodType<JsonSchema> = z.lazy(() =>
  z.union([
    z.object({ type: z.enum(["string", "number", "boolean", "null"]) }).strict(),
    z.object({ type: z.literal("array"), items: JsonSchemaSchema }).strict(),
    z
      .object({
        type: z.literal("object"),
        properties: z.record(z.string(), JsonSchemaSchema),
        required: z.array(z.string()).optional(),
        additionalProperties: z.boolean().optional(),
      })
      .strict(),
  ]),
);

/**
 * 式: `${{ … }}` の内側（またはリテラル）に現れるソーステキスト。
 * コンパイラが生の文字列と、解析・検証済みの式を区別できるよう
 * branded されています。Grammar: [02 — Authoring](02-authoring.md#expression-language)。
 */
export const ExprSchema = z.string().brand<"Expr">();
export type Expr = z.infer<typeof ExprSchema>;

/** Step ごとの retry policy。デフォルトは tool の `kind` から導かれます（[04 §4](04-execution.md#4-retries-timeouts-idempotency)）。 */
export const RetryPolicySchema = z
  .object({
    max: z.number().int().nonnegative(),
    backoff: z.enum(["exp", "fixed"]),
    base_ms: z.number().int().positive(),
    jitter: z.boolean(),
  })
  .strict();
export type RetryPolicy = z.infer<typeof RetryPolicySchema>;

/**
 * pin された tool dependency: 正確な `name@version` ref と、解決済みの
 * contract digest。これにより flow の identity は version label だけでなく
 * tool の *behavior* まで閉じます（[03 §5](03-ir.md#5-the-digest)）。
 */
export const RequireSchema = z
  .object({ ref: z.string().min(1), contract_digest: z.string().min(1) })
  .strict();
export type Require = z.infer<typeof RequireSchema>;

import { z } from "zod";

/**
 * tool 上で宣言される1つの input slot。tool の caller と body の間の contract です。
 * tool は input を名前と `schema` で読み取り、`secret: true` の slot は run boundary
 * （§7）を決して出ません。`schema` は slot の JSON-Schema-subset 型です。
 * スカラー **だけでなく** object/array も扱えるため、tool はたとえば object request body
 * を宣言できます。YAML surface は `type: string|number|boolean` という shorthand を受け付け、
 * canonicalization 中に `{ "type": … }` へ展開します
 * （[02 §3](02-authoring.md#3-the-same-flow-three-ways)）。
 */
export const InputDeclSchema = z
  .object({
    name: z.string().min(1),
    schema: JsonSchemaSchema,
    secret: z.boolean(),
  })
  .strict();

export type InputDecl = z.infer<typeof InputDeclSchema>;

/**
 * tool の interface contract。`inputs`/`output` は型付けされるため、配線は
 * author time にチェックされ、run time に検証されます。`capabilities` は tool が
 * 使用を許可された effect を列挙します（T2: permission による effects）。
 * Rider はそれらだけを注入し、それ以上は注入しません。`provenance.source_digest` は
 * tool body を作成したもの（例: 記録済み browser session）の content-addressed
 * fingerprint なので、tool は pin でき、監査できます。
 */
export const ToolContractSchema = z
  .object({
    schema_version: z.literal("1.0"),
    name: z.string().min(1),
    version: z.string().min(1), // semver
    kind: z.enum(["browser", "http", "shell", "transform", "code", "model", "composite"]),
    description: z.string().min(1),
    inputs: z.array(InputDeclSchema),
    output: JsonSchemaSchema, // 小さな JSON Schema（Draft 2020-12）のサブセット
    capabilities: z.array(z.enum(["net", "fs", "browser", "clock", "random", "env", "spawn", "secrets"])),
    provenance: z
      .object({ source_digest: z.string().optional(), pack: z.string().optional() })
      .strict(),
  })
  .strict();

export type ToolContract = z.infer<typeof ToolContractSchema>;

export const StepSchema = z
  .object({
    id: z.string().min(1), // flow 内で一意。編集をまたいで stable
    use: z.string().min(1), // "browser:search-price@1.2.0" | "http.post" | "flow:sub@2"
    with: z.record(z.string(), ExprSchema).optional(), // input bindings（expression の場合があります）
    needs: z.array(z.string()).optional(), // explicit deps。なければ refs から推論
    when: ExprSchema.optional(), // これが truthy に評価された場合のみ run
    retry: RetryPolicySchema.optional(),
    timeout_ms: z.number().int().positive().optional(),
    foreach: ExprSchema.optional(), // array に fan out（map）
    output_as: z.string().optional(), // downstream references 用の alias
  })
  .strict();

export type Step = z.infer<typeof StepSchema>;

${{ steps.lookup.output.price }}
${{ input.query }}
${{ env.REGION }}

export const FlowSpecSchema = z
  .object({
    schema_version: z.literal("1.0"),
    name: z.string().min(1),
    description: z.string().optional(),
    inputs: z.array(InputDeclSchema),
    output: ExprSchema.optional(),
    steps: z.array(StepSchema),
    requires: z.array(RequireSchema), // pinned tool ref + resolved contract digest
    digest: z.string().optional(), // canonical form の sha256（compiler が埋める）
  })
  .strict();

export type FlowSpec = z.infer<typeof FlowSpecSchema>;

export const RunSchema = z
  .object({
    id: z.string().min(1), // uuidv4
    flow_digest: z.string().min(1), // 実行された FlowSpec を正確に示す
    status: z.enum(["pending", "running", "succeeded", "failed", "canceled"]),
    started_at: z.string(), // ISO-8601
    finished_at: z.string().optional(),
    journal: z.array(JournalEntrySchema),
    output: z.unknown().optional(),
  })
  .strict();

export type Run = z.infer<typeof RunSchema>;

export const PackManifestSchema = z
  .object({
    schema_version: z.literal("1.0"),
    name: z.string().min(1), // "@acme/pricing"
    version: z.string().min(1), // semver
    tools: z.array(z.object({ ref: z.string(), contract_digest: z.string() }).strict()),
    flows: z.array(z.object({ name: z.string(), flow_digest: z.string() }).strict()),
    dependencies: z.array(z.string()), // 他の packs。pinned
    digest: z.string(), // canonical manifest の sha256
  })
  .strict();

export type PackManifest = z.infer<typeof PackManifestSchema>;