@kirrosh/zond 0.21.0 → 0.23.0

package/src/cli/commands/api/annotate/overlay.ts

@@ -0,0 +1,206 @@
+/**
+ * ARV-187: read / merge / write `.api-resources.local.yaml`.
+ *
+ * The annotate command writes _only_ into the `patches:` block. That's
+ * the ARV-169 field-level overlay (see discover.ts:readResourcePatches)
+ * — strictly additive, doesn't touch the upstream `.api-resources.yaml`.
+ * The `extensions:` block (ARV-111, full-resource replacement) is left
+ * intact when we re-write the file, so users can mix annotate-generated
+ * patches with hand-written extensions.
+ *
+ * Idempotent re-annotation: when a patch field already exists in the
+ * overlay, we compare values. Equal → no-op (keep existing). Different
+ * → conflict (surface in diff, requires --yes to overwrite, or --keep
+ * to skip).
+ */
+
+import { join } from "node:path";
+import { writeFile } from "node:fs/promises";
+import type { ResourceYaml } from "../../discover.ts";
+
+export type ResourcePatch = Partial<ResourceYaml> & { resource: string };
+
+export interface LocalOverlayFile {
+  extensions?: ResourceYaml[];
+  patches?: ResourcePatch[];
+  /** Any other top-level keys the user added (preserved on rewrite). */
+  [key: string]: unknown;
+}
+
+const FILENAME = ".api-resources.local.yaml";
+
+export async function readLocalOverlay(apiDir: string): Promise<LocalOverlayFile> {
+  const file = Bun.file(join(apiDir, FILENAME));
+  if (!(await file.exists())) return {};
+  const parsed = Bun.YAML.parse(await file.text());
+  if (!parsed || typeof parsed !== "object") return {};
+  return parsed as LocalOverlayFile;
+}
+
+export async function writeLocalOverlay(apiDir: string, overlay: LocalOverlayFile): Promise<void> {
+  const path = join(apiDir, FILENAME);
+  const header = `# .api-resources.local.yaml — local overlay (ARV-111 / ARV-169 / ARV-187)
+#
+# extensions: full ResourceYaml entries that REPLACE the upstream entry
+#             (by resource name) or ADD a new one.
+# patches:    partial overlay — fields here are merged onto the matching
+#             upstream entry (idempotency / pagination / lifecycle /
+#             readback_diff / seed_body).
+#
+# This file is checked into git. Edit by hand or via \`zond api annotate\`.
+`;
+  // Bun.YAML doesn't have a stringify; use the yaml package.
+  const { stringify } = await import("yaml");
+  const body = stringify(overlay, { lineWidth: 0, defaultStringType: "PLAIN" });
+  await writeFile(path, header + "\n" + body, "utf-8");
+}
+
+export interface MergeConflict {
+  resource: string;
+  field: string;
+  existing: unknown;
+  proposed: unknown;
+}
+
+export interface MergeResult {
+  /** New patches array, with proposed merged over existing. */
+  patches: ResourcePatch[];
+  /** Per-resource per-field conflicts (existing value differs from proposed). */
+  conflicts: MergeConflict[];
+  /** Per-resource per-field accepted changes (new field, or overwrite when force=true). */
+  changes: MergeConflict[];
+}
+
+/**
+ * Merge proposed patches into existing patches.
+ *
+ * Conflict policy:
+ *   - Field absent in existing → added (counts as a `change`).
+ *   - Field present and structurally equal → kept (no-op).
+ *   - Field present and different → if force=true, overwritten and
+ *     counted as both `change` and `conflict`; else kept and counted
+ *     as `conflict` only.
+ *
+ * "Structural equality" uses JSON stringification with stable key order;
+ * good enough for yaml-roundtrip data which is plain JSON-shaped.
+ */
+export function mergePatches(
+  existing: ResourcePatch[],
+  proposed: ResourcePatch[],
+  opts: { force?: boolean } = {},
+): MergeResult {
+  const force = opts.force === true;
+  const byName = new Map<string, ResourcePatch>();
+  for (const p of existing) byName.set(p.resource, deepClone(p));
+  const conflicts: MergeConflict[] = [];
+  const changes: MergeConflict[] = [];
+
+  for (const proposedPatch of proposed) {
+    const name = proposedPatch.resource;
+    const current = byName.get(name) ?? { resource: name };
+    for (const [field, proposedVal] of Object.entries(proposedPatch)) {
+      if (field === "resource") continue;
+      const existingVal = (current as Record<string, unknown>)[field];
+      if (existingVal === undefined) {
+        (current as Record<string, unknown>)[field] = proposedVal;
+        changes.push({ resource: name, field, existing: undefined, proposed: proposedVal });
+        continue;
+      }
+      if (structurallyEqual(existingVal, proposedVal)) continue;
+      // Conflict.
+      conflicts.push({ resource: name, field, existing: existingVal, proposed: proposedVal });
+      if (force) {
+        (current as Record<string, unknown>)[field] = proposedVal;
+        changes.push({ resource: name, field, existing: existingVal, proposed: proposedVal });
+      }
+    }
+    byName.set(name, current);
+  }
+
+  return { patches: [...byName.values()], conflicts, changes };
+}
+
+function structurallyEqual(a: unknown, b: unknown): boolean {
+  return stableJson(a) === stableJson(b);
+}
+
+function stableJson(v: unknown): string {
+  if (v === null || typeof v !== "object") return JSON.stringify(v);
+  if (Array.isArray(v)) return "[" + v.map(stableJson).join(",") + "]";
+  const obj = v as Record<string, unknown>;
+  const keys = Object.keys(obj).sort();
+  return "{" + keys.map((k) => JSON.stringify(k) + ":" + stableJson(obj[k])).join(",") + "}";
+}
+
+function deepClone<T>(v: T): T {
+  return JSON.parse(JSON.stringify(v));
+}
+
+/**
+ * Render a unified, human-readable diff of the changes a merge produced.
+ * Returns "" when there are no changes.
+ *
+ * Format (kept simple so it works in plain stdout, no chalk dep):
+ *
+ *   resource: customers
+ *     + seed_body:
+ *         content_type: application/x-www-form-urlencoded
+ *         body:
+ *           description: 'zond probe customer'
+ *           email: 'probe@example.com'
+ *     ~ idempotency: (conflict — kept existing)
+ *         existing: { header: Idempotency-Key }
+ *         proposed: { header: X-Idempotency }
+ */
+export function renderChangesDiff(result: MergeResult): string {
+  const lines: string[] = [];
+  const byResource = new Map<string, { changes: MergeConflict[]; conflicts: MergeConflict[] }>();
+  for (const c of result.changes) {
+    if (!byResource.has(c.resource)) byResource.set(c.resource, { changes: [], conflicts: [] });
+    byResource.get(c.resource)!.changes.push(c);
+  }
+  for (const c of result.conflicts) {
+    if (!byResource.has(c.resource)) byResource.set(c.resource, { changes: [], conflicts: [] });
+    byResource.get(c.resource)!.conflicts.push(c);
+  }
+  for (const [resource, group] of byResource) {
+    lines.push(`resource: ${resource}`);
+    for (const ch of group.changes) {
+      const op = ch.existing === undefined ? "+" : "~";
+      lines.push(`  ${op} ${ch.field}:`);
+      lines.push(indent(yamlSnippet(ch.proposed), 6));
+    }
+    for (const cf of group.conflicts) {
+      // Skip if already rendered as a change (force=true case).
+      if (group.changes.some((c) => c.field === cf.field && c.existing !== undefined)) continue;
+      lines.push(`  ! ${cf.field}: (conflict — kept existing; pass --yes to overwrite)`);
+      lines.push(`      existing: ${oneLineYaml(cf.existing)}`);
+      lines.push(`      proposed: ${oneLineYaml(cf.proposed)}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+function yamlSnippet(v: unknown): string {
+  // Reuse yaml package for nested rendering.
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { stringify } = require("yaml") as { stringify: (v: unknown, opts?: unknown) => string };
+    return stringify(v, { lineWidth: 0 }).trimEnd();
+  } catch {
+    return JSON.stringify(v, null, 2);
+  }
+}
+
+function oneLineYaml(v: unknown): string {
+  try {
+    return JSON.stringify(v);
+  } catch {
+    return String(v);
+  }
+}
+
+function indent(text: string, n: number): string {
+  const pad = " ".repeat(n);
+  return text.split("\n").map((l) => pad + l).join("\n");
+}

package/src/cli/commands/api/annotate/pagination.ts

@@ -0,0 +1,60 @@
+/**
+ * ARV-187 / pagination: parser + expected shape.
+ */
+
+import { z } from "zod";
+import type { ResourcePatch } from "./overlay.ts";
+import type { ResourceSlice } from "./prompts.ts";
+
+const PaginationSchema = z.object({
+  type: z.enum(["cursor", "page", "offset", "token"]),
+  cursor_param: z.string().optional(),
+  cursor_field: z.string().optional(),
+  has_more_field: z.string().optional(),
+  limit_param: z.string().optional(),
+  default_limit: z.number().int().positive().optional(),
+  items_field: z.string().optional(),
+});
+
+const ResponseSchema = z.object({
+  resource: z.string(),
+  pagination: PaginationSchema.nullable(),
+  rationale: z.string().optional(),
+  confidence: z.enum(["low", "medium", "high"]).optional(),
+});
+
+export const EXPECTED_OUTPUT_SHAPE = {
+  resource: "string (echo input)",
+  pagination: {
+    type: "cursor | page | offset | token",
+    cursor_param: "string (optional — query param carrying cursor value)",
+    cursor_field: "string (optional — response field that becomes next cursor)",
+    has_more_field: "string (optional — boolean response field signalling more)",
+    limit_param: "string (optional)",
+    default_limit: "integer (optional)",
+    items_field: "string (optional — response field carrying array)",
+  },
+  rationale: "string (optional)",
+  confidence: "low | medium | high",
+  null_form: "if list endpoint doesn't paginate, return { resource, pagination: null }",
+};
+
+export function parsePaginationResponse(parsed: unknown, slice: ResourceSlice): { patch: ResourcePatch; audit: Record<string, unknown> } {
+  const validated = ResponseSchema.safeParse(parsed);
+  if (!validated.success) {
+    throw new Error(`pagination response failed schema for ${slice.resource}: ${validated.error.message}`);
+  }
+  const v = validated.data;
+  if (v.pagination == null) {
+    return {
+      patch: { resource: slice.resource },
+      audit: { resource: slice.resource, rationale: v.rationale, confidence: v.confidence, dropped: "endpoint does not paginate" },
+    };
+  }
+  return {
+    patch: { resource: slice.resource, pagination: v.pagination },
+    audit: { resource: slice.resource, rationale: v.rationale, confidence: v.confidence },
+  };
+}
+
+export function isApplicable(slice: ResourceSlice): boolean { return Boolean(slice.endpoints.list); }

package/src/cli/commands/api/annotate/prompts.ts

@@ -0,0 +1,183 @@
+/**
+ * ARV-187: shared prompt utilities — extract per-resource CRUD slices
+ * from a parsed OpenAPI document so each subcommand can build a tight,
+ * cheap prompt for the LLM.
+ *
+ * Per-resource slicing (vs. send-the-whole-spec) is the cost-control
+ * pattern AutoRestTest / KAT both use: keeps each call <4k tokens and
+ * lets us cache by `sha256(slice + prompt_version + model)`.
+ */
+
+import type { OpenAPIV3 } from "openapi-types";
+import type { ResourceYaml } from "../../discover.ts";
+
+export interface ResourceSlice {
+  resource: string;
+  basePath: string;
+  itemPath: string;
+  /** Concrete EndpointInfo-like dump per role with the *relevant* spec
+   *  bits inlined (summary, description, parameters, request schema,
+   *  example bodies, x-codeSamples). Designed to be JSON.stringify'd
+   *  straight into the prompt. */
+  endpoints: {
+    list?: EndpointDump;
+    create?: EndpointDump;
+    read?: EndpointDump;
+    update?: EndpointDump;
+    delete?: EndpointDump;
+  };
+}
+
+export interface EndpointDump {
+  method: string;
+  path: string;
+  operationId?: string;
+  summary?: string;
+  description?: string;
+  parameters?: Array<{
+    name: string;
+    in: string;
+    required?: boolean;
+    description?: string;
+    schema?: unknown;
+  }>;
+  requestBody?: {
+    contentType?: string;
+    description?: string;
+    schema?: unknown;
+    example?: unknown;
+  };
+  responses?: Record<string, { description?: string; schema?: unknown }>;
+  /** Stripe/Redocly convention — prose curl examples live here. */
+  xCodeSamples?: unknown;
+}
+
+/**
+ * Build per-resource CRUD slices from spec + the upstream resource map.
+ * We trust the resource map's endpoint pointers (already computed by
+ * the catalog builder) rather than re-doing path-grouping. Each slice
+ * carries the spec-fragments the LLM needs to reason about that
+ * resource — no more, no less.
+ */
+export function buildResourceSlices(
+  doc: OpenAPIV3.Document,
+  resources: ResourceYaml[],
+): ResourceSlice[] {
+  return resources.map((r) => {
+    const out: ResourceSlice = {
+      resource: r.resource,
+      basePath: r.basePath,
+      itemPath: r.itemPath,
+      endpoints: {},
+    };
+    for (const role of ["list", "create", "read", "update", "delete"] as const) {
+      const label = r.endpoints[role];
+      if (!label) continue;
+      const parsed = parseLabel(label);
+      if (!parsed) continue;
+      const dump = dumpEndpoint(doc, parsed.method, parsed.path);
+      if (dump) out.endpoints[role] = dump;
+    }
+    return out;
+  });
+}
+
+function parseLabel(label: string): { method: string; path: string } | null {
+  const parts = label.trim().split(/\s+/);
+  if (parts.length < 2) return null;
+  return { method: parts[0]!.toLowerCase(), path: parts[1]! };
+}
+
+function dumpEndpoint(doc: OpenAPIV3.Document, method: string, path: string): EndpointDump | null {
+  const pathItem = doc.paths?.[path] as OpenAPIV3.PathItemObject | undefined;
+  if (!pathItem) return null;
+  const op = (pathItem as Record<string, unknown>)[method] as OpenAPIV3.OperationObject | undefined;
+  if (!op) return null;
+
+  const parameters: EndpointDump["parameters"] = [];
+  for (const p of [...(pathItem.parameters ?? []), ...(op.parameters ?? [])]) {
+    if ("$ref" in p) continue;
+    parameters.push({
+      name: p.name,
+      in: p.in,
+      required: p.required,
+      description: truncate(p.description, 240),
+      schema: simplifySchema(p.schema as OpenAPIV3.SchemaObject | undefined),
+    });
+  }
+
+  let requestBody: EndpointDump["requestBody"];
+  if (op.requestBody && !("$ref" in op.requestBody)) {
+    const rb = op.requestBody as OpenAPIV3.RequestBodyObject;
+    const contentEntries = Object.entries(rb.content ?? {});
+    const [ct, media] = contentEntries[0] ?? [];
+    if (media) {
+      requestBody = {
+        contentType: ct,
+        description: truncate(rb.description, 240),
+        schema: simplifySchema(media.schema as OpenAPIV3.SchemaObject | undefined),
+        example: media.example,
+      };
+    }
+  }
+
+  const responses: EndpointDump["responses"] = {};
+  for (const [code, resp] of Object.entries(op.responses ?? {})) {
+    if (resp && !("$ref" in resp)) {
+      const r = resp as OpenAPIV3.ResponseObject;
+      const content = Object.values(r.content ?? {})[0];
+      responses[code] = {
+        description: truncate(r.description, 240),
+        schema: simplifySchema(content?.schema as OpenAPIV3.SchemaObject | undefined),
+      };
+    }
+  }
+
+  return {
+    method: method.toUpperCase(),
+    path,
+    operationId: op.operationId,
+    summary: truncate(op.summary, 240),
+    description: truncate(op.description, 600),
+    parameters: parameters.length > 0 ? parameters : undefined,
+    requestBody,
+    responses: Object.keys(responses).length > 0 ? responses : undefined,
+    xCodeSamples: (op as Record<string, unknown>)["x-codeSamples"],
+  };
+}
+
+/**
+ * Strip refs and nested noise from a schema dump. We don't need full
+ * fidelity — the LLM just needs to know the field names + types + any
+ * descriptions that hint at example values. Drops `additionalProperties`,
+ * collapses `oneOf/anyOf` to the first variant, truncates descriptions.
+ */
+function simplifySchema(s: OpenAPIV3.SchemaObject | undefined): unknown {
+  if (!s) return undefined;
+  if ((s as OpenAPIV3.ReferenceObject).$ref) return { $ref: (s as OpenAPIV3.ReferenceObject).$ref };
+  const out: Record<string, unknown> = {};
+  if (s.type) out.type = s.type;
+  if (s.format) out.format = s.format;
+  if (s.enum) out.enum = s.enum;
+  if (s.example !== undefined) out.example = s.example;
+  if (s.default !== undefined) out.default = s.default;
+  if (s.description) out.description = truncate(s.description, 240);
+  if (s.required) out.required = s.required;
+  if (s.properties) {
+    out.properties = Object.fromEntries(
+      Object.entries(s.properties).map(([k, v]) => [k, simplifySchema(v as OpenAPIV3.SchemaObject)]),
+    );
+  }
+  const asArr = s as OpenAPIV3.ArraySchemaObject;
+  if (asArr.items) out.items = simplifySchema(asArr.items as OpenAPIV3.SchemaObject);
+  const o = s as Record<string, unknown>;
+  if (Array.isArray(o.oneOf) && o.oneOf.length > 0) out.oneOf_first = simplifySchema(o.oneOf[0] as OpenAPIV3.SchemaObject);
+  if (Array.isArray(o.anyOf) && o.anyOf.length > 0) out.anyOf_first = simplifySchema(o.anyOf[0] as OpenAPIV3.SchemaObject);
+  return out;
+}
+
+function truncate(s: string | undefined, n: number): string | undefined {
+  if (!s) return undefined;
+  return s.length > n ? s.slice(0, n) + "…" : s;
+}
+

package/src/cli/commands/api/annotate/readback.ts

@@ -0,0 +1,58 @@
+/**
+ * ARV-187 / readback: parser + expected shape.
+ */
+
+import { z } from "zod";
+import type { ResourcePatch } from "./overlay.ts";
+import type { ResourceSlice } from "./prompts.ts";
+
+const ReadbackSchema = z.object({
+  ignore_fields: z.array(z.string()).default([]),
+  write_to_read_map: z.record(z.string(), z.string()).default({}),
+});
+
+const ResponseSchema = z.object({
+  resource: z.string(),
+  readback_diff: ReadbackSchema.nullable(),
+  rationale: z.string().optional(),
+  confidence: z.enum(["low", "medium", "high"]).optional(),
+});
+
+export const EXPECTED_OUTPUT_SHAPE = {
+  resource: "string (echo input)",
+  readback_diff: {
+    ignore_fields: "string[] (write-only fields cross_call_references should ignore)",
+    write_to_read_map: "{ <write_field>: <read_field> } (renames on the read shape)",
+  },
+  rationale: "string (optional)",
+  confidence: "low | medium | high",
+  null_form: "if read shape echoes write shape, return { resource, readback_diff: null }",
+};
+
+export function parseReadbackResponse(parsed: unknown, slice: ResourceSlice): { patch: ResourcePatch; audit: Record<string, unknown> } {
+  const validated = ResponseSchema.safeParse(parsed);
+  if (!validated.success) {
+    throw new Error(`readback response failed schema for ${slice.resource}: ${validated.error.message}`);
+  }
+  const v = validated.data;
+  if (v.readback_diff == null) {
+    return {
+      patch: { resource: slice.resource },
+      audit: { resource: slice.resource, rationale: v.rationale, confidence: v.confidence, dropped: "no drift expected" },
+    };
+  }
+  if ((v.readback_diff.ignore_fields?.length ?? 0) === 0 && Object.keys(v.readback_diff.write_to_read_map ?? {}).length === 0) {
+    return {
+      patch: { resource: slice.resource },
+      audit: { resource: slice.resource, rationale: v.rationale, confidence: v.confidence, dropped: "empty readback hints" },
+    };
+  }
+  return {
+    patch: { resource: slice.resource, readback_diff: v.readback_diff },
+    audit: { resource: slice.resource, rationale: v.rationale, confidence: v.confidence },
+  };
+}
+
+export function isApplicable(slice: ResourceSlice): boolean {
+  return Boolean(slice.endpoints.create && slice.endpoints.read);
+}

package/src/cli/commands/api/annotate/resources.ts

@@ -0,0 +1,91 @@
+/**
+ * ARV-187 / resources: parser + expected shape for orphan-clustering.
+ */
+
+import { z } from "zod";
+import type { ResourceYaml } from "../../discover.ts";
+
+const EndpointMapSchema = z.object({
+  list: z.string().optional(),
+  create: z.string().optional(),
+  read: z.string().optional(),
+  update: z.string().optional(),
+  delete: z.string().optional(),
+});
+
+const FkSchema = z.object({
+  var: z.string(),
+  param: z.string(),
+  in: z.enum(["path", "body"]),
+  ownerResource: z.string().nullable(),
+});
+
+const ExtensionSchema = z.object({
+  resource: z.string(),
+  basePath: z.string(),
+  itemPath: z.string(),
+  idParam: z.string(),
+  captureField: z.string().optional(),
+  hasFullCrud: z.boolean().optional(),
+  endpoints: EndpointMapSchema,
+  fkDependencies: z.array(FkSchema).default([]),
+  confidence: z.enum(["low", "medium", "high"]),
+  rationale: z.string().optional(),
+});
+
+const ResponseSchema = z.object({
+  extensions: z.array(ExtensionSchema).default([]),
+  rationale: z.string().optional(),
+});
+
+export const EXPECTED_OUTPUT_SHAPE = {
+  extensions: [{
+    resource: "slug",
+    basePath: "/v1/<collection>",
+    itemPath: "/v1/<collection>/{<id_param>}",
+    idParam: "string",
+    captureField: "string (optional, default 'id')",
+    hasFullCrud: "boolean (optional)",
+    endpoints: { list: "GET /...", create: "POST /...", read: "GET /...", update: "PATCH /...", delete: "DELETE /..." },
+    fkDependencies: "FkRef[] (usually [])",
+    confidence: "low | medium | high (only 'high' is accepted by zond)",
+    rationale: "string (optional)",
+  }],
+  rationale: "string (optional)",
+};
+
+export interface ResourcesParseResult {
+  extensions: ResourceYaml[];
+  audit: {
+    proposed: number;
+    droppedLowConfidence: number;
+    rationale?: string;
+  };
+}
+
+export function parseResourcesResponse(parsed: unknown): ResourcesParseResult {
+  const validated = ResponseSchema.safeParse(parsed);
+  if (!validated.success) {
+    throw new Error(`resources response failed schema: ${validated.error.message}`);
+  }
+  const v = validated.data;
+  let dropped = 0;
+  const extensions: ResourceYaml[] = [];
+  for (const ext of v.extensions) {
+    if (ext.confidence !== "high") { dropped++; continue; }
+    extensions.push({
+      resource: ext.resource,
+      basePath: ext.basePath,
+      itemPath: ext.itemPath,
+      idParam: ext.idParam,
+      captureField: ext.captureField,
+      hasFullCrud: ext.hasFullCrud,
+      endpoints: ext.endpoints,
+      fkDependencies: ext.fkDependencies,
+    });
+  }
+  return {
+    extensions,
+    audit: { proposed: v.extensions.length, droppedLowConfidence: dropped, rationale: v.rationale },
+  };
+}

package/src/cli/commands/api/annotate/seed-bodies.ts

@@ -0,0 +1,61 @@
+/**
+ * ARV-187 / seed-bodies: parser + schema-shape. zond does NOT
+ * formulate prompts — that's the agent's job. zond exposes the spec
+ * slice and the expected response shape; the agent decides how to ask
+ * its LLM.
+ */
+
+import { z } from "zod";
+import type { ResourcePatch } from "./overlay.ts";
+import type { ResourceSlice } from "./prompts.ts";
+
+const SeedBodySchema = z.object({
+  content_type: z.string().optional(),
+  body: z.record(z.string(), z.unknown()),
+});
+
+const ResponseSchema = z.object({
+  resource: z.string(),
+  seed_body: SeedBodySchema.nullable(),
+  rationale: z.string().optional(),
+  confidence: z.enum(["low", "medium", "high"]).optional(),
+});
+
+export const EXPECTED_OUTPUT_SHAPE = {
+  resource: "string (echo input)",
+  seed_body: {
+    content_type: "string (optional; defaults to spec's requestBodyContentType)",
+    body: "object (minimal-required field-set the create endpoint accepts)",
+  },
+  rationale: "string (optional, one sentence)",
+  confidence: "low | medium | high",
+  null_form: "if endpoint cannot be seeded statically, return { resource, seed_body: null, rationale }",
+};
+
+export function parseSeedBodyResponse(parsedYaml: unknown, slice: ResourceSlice): { patch: ResourcePatch; audit: Record<string, unknown> } {
+  const validated = ResponseSchema.safeParse(parsedYaml);
+  if (!validated.success) {
+    throw new Error(`seed_body response failed schema for ${slice.resource}: ${validated.error.message}`);
+  }
+  const v = validated.data;
+  if (v.seed_body == null) {
+    return {
+      patch: { resource: slice.resource },
+      audit: { resource: slice.resource, rationale: v.rationale, confidence: v.confidence, dropped: "agent judged endpoint not seedable" },
+    };
+  }
+  return {
+    patch: {
+      resource: slice.resource,
+      seed_body: {
+        content_type: v.seed_body.content_type ?? slice.endpoints.create?.requestBody?.contentType,
+        body: v.seed_body.body,
+      },
+    },
+    audit: { resource: slice.resource, rationale: v.rationale, confidence: v.confidence },
+  };
+}
+
+export function isApplicable(slice: ResourceSlice): boolean {
+  return Boolean(slice.endpoints.create);
+}