Zap Recipe Schema Reference: Fields, Types, Defaults

import type { ZapSpec, ZapStep, ZapStepKind, ZapInput, PublicZapSpec } from "@wzrdtech/core";

// Full recipe spec — parsed and validated from Zap.md frontmatter
type ZapSpec = { ... }

// A single pipeline step
type ZapStep = { ... }

// Union of all 11 supported step kinds
type ZapStepKind =
  | "image.gen" | "image.edit"
  | "video.gen" | "video.extend" | "video.edit" | "video.upscale"
  | "audio.tts" | "audio.music" | "audio.sfx"
  | "keyframes" | "stitch";

// A validated input declaration
type ZapInput = { ... }

// ZapSpec with an added `title` field (titleized from the slug)
type PublicZapSpec = ZapSpec & { title: string };

// Parse a Zap.md string into a validated ZapSpec.
// Throws on YAML syntax errors, schema violations,
// undeclared input variables, or duplicate step IDs.
parseZapMarkdown(markdown: string): ZapSpec

// Extract and return the raw YAML content from inside
// the --- fences of a Zap.md string.
// Throws if no frontmatter block is found.
extractFrontmatter(markdown: string): string

// Assert that all {VARIABLE} references in prompt paths
// correspond to declared inputs. Called inside parseZapMarkdown().
validateVariables(spec: ZapSpec): void

// Assert that no two steps share the same id.
// Called inside parseZapMarkdown().
validateDuplicateStepIds(spec: ZapSpec): void

// Assert that all inputs marked required: true are
// present in the run's inputs payload.
validateRequiredInputs(zap: ZapSpec, inputs: Record<string, unknown>): void

// Derive a PublicZapSpec by titleizing the slug
// (e.g. "launch-trailer" → { ..., title: "Launch Trailer" }).
publicZapSpec(spec: ZapSpec): PublicZapSpec

// Expand repeat steps and compute the estimated run cost.
// extendCount controls how many video.extend iterations to plan.
planZapRun(zap: ZapSpec, extendCount: number): ZapPlan

// Throw if the plan's estimateUsd exceeds the recipe's budget.cap_usd.
assertWithinBudget(plan: ZapPlan): void

// Return the estimated USD cost for a single step
// based on the model rate table in planner.ts.
quoteStep(step: ZapStep): number

// Flatten video.extend steps into numbered PlannedZapStep instances.
// Non-extend steps are passed through unchanged.
expandRepeatSteps(zap: ZapSpec, extendCount: number): PlannedZapStep[]

type PlannedZapStep = ZapStep & {
  originalId: string;   // the id from the recipe before expansion
  repeatIndex?: number; // 1-based index for expanded repeat steps
};

type ZapPlan = {
  budgetCapUsd: number;
  estimateUsd: number;
  extendCount: number;
  steps: PlannedZapStep[];
  zap: string;
};

---
zap: launch-trailer
version: 1
description: A short creator video.
budget:
  estimate_usd: 0
  cap_usd: 5
defaults:
  provider: mock
inputs:
  PROMPT:
    type: textarea
    required: true
steps:
  - id: initial_frame
    kind: image.gen
    provider: mock
    model: mock-image
    prompt: prompts/initial-frame.md
  - id: initial_gen
    kind: video.gen
    provider: mock
    model: mock-video
    inputs: [initial_frame]
    duration_s: 15
    prompt: prompts/initial-gen.md
  - id: stitch
    kind: stitch
    inputs: [initial_gen]
output: Zap.mp4
---