Surface adapter: API — request/assert chains with capture

[queso]

Part of the multi-surface substrate plan (theaiteam-dev/the-ai-team-plugin#51, PRD 010; siblings: #6 CLI, #7 Conduit). This issue: API surface — REST/webhook services (conduit ingress, kanban-viewer API, print-farm backend, DevTrack).

Sketch

name: capture-and-retrieve-order
description: Creating an order returns an id that resolves on GET
surface: api
steps:
  - request: {post: /api/orders, json: {sku: "CC-BUCKET", qty: 1}}
    capture: {order_id: "$.id"}
  - request: {get: "/api/orders/{order_id}"}
expect:
  - status: 200
  - json: {path: "$.sku", equals: "CC-BUCKET"}
  - json: {path: "$.status", in: ["pending", "queued"]}

Proposed verbs / assertions

Steps	Assertions
request: {get/post/put/patch/delete: path, json/body, headers}	status: <code>
capture: {name: "$.jsonpath"} (from response → template vars)	json: {path, equals/in/matches}
wait: <ms> (async processing)	header: {name, contains}
auth via contract qa.account (token/header recipe)	latency_under: <ms> (e.g. ack-on-accept: webhook 200s within N ms while the run continues)

Design notes

• capture is the load-bearing addition — API flows are stateful chains (login → create → fetch). Captured vars template into later steps via {name}.
• Base URL from flowspec.config.yaml / contract; per-step absolute URLs allowed for cross-service checks.
• Retry semantics: status final by default; json assertions may retry within timeout for eventually-consistent endpoints (same retry model as web wait_for).
• Prior art acknowledged (Hurl, Step CI, Karate). The differentiator is NOT the request grammar — it's one grammar + the PreToolUse immutability hook + one graduation pipeline across all surfaces, so API promises (like ack timing) get the same agents-can't-loosen-the-spec guarantee feeding the PRD-010 auto-merge ladder.

Why

API behaviors are where agents most quietly weaken tests (bump a timeout, widen an enum, delete a latency assertion). Immutable API specs close that on the surface where it bites hardest.