Protocol Flow

1. specdown launches the adapter process
2. specdown sends exec or assert messages in document order, each with an integer id
3. The adapter responds to each message, echoing the id
4. When the spec run finishes, specdown closes stdin and waits for the process to exit

Sessions are scoped per-document. Each adapter session is started on first use and closed after all cases in that document complete. With --jobs N, each document gets its own independent sessions.

A single adapter process handles multiple requests during one spec run. The adapter can maintain process-local state across requests. Use this to cache data: for example, when a check table has many rows that all query the same endpoint, fetch once on the first row and reuse the cached response for subsequent rows.

Exec Request

For executable blocks:

{
  "type": "exec",
  "id": 1,
  "source": "create-board"
}

Variables in source are already substituted by the engine. The adapter executes the source and returns the result.

Exec Response

An exec response must contain exactly one of "output" or "error" keys. Key presence determines success or failure — not the value.

{"id": 1, "output": "board-1"}
{"id": 1, "output": ""}
{"id": 1, "error": "command not found"}

The engine handles variable capture: if the block has -> $var, the engine extracts the output value. For string output, lines are split and mapped to capture names in order. For structured (non-string) output, the value is stored as-is and accessible via dot-path syntax (${result.field}).

Assert Request

For check table rows and check calls:

{
  "type": "assert",
  "id": 2,
  "check": "board-exists",
  "checkParams": {"user": "alan"},
  "columns": ["board", "exists"],
  "cells": ["board-1", "yes"]
}

Variables in cells are already substituted. Cell escape sequences are already resolved.

Assert Response

{"id": 2, "type": "passed"}
{"id": 2, "type": "failed", "message": "expected 3, got 4"}
{"id": 2, "type": "failed", "message": "mismatch", "expected": "foo", "actual": "bar", "label": "row description"}

Registration

Adapters declare their capabilities in specdown.json. specdown routes each case to the adapter that declared the matching block or check. Capabilities are declared in config, not negotiated at runtime.

{
  "adapters": [{
    "name": "myapp",
    "command": ["python3", "./tools/adapter.py"],
    "blocks": ["run:myapp"],
    "checks": ["user-exists"]
  }]
}

Adapter Behavior

• A non-zero exit indicates an adapter crash or infrastructure failure, not a case failure
• Only protocol messages are written to stdout; stderr is for diagnostic output
• Built-in adapters follow the same protocol contract (see below)

Built-in Shell Adapter

The shell adapter is one of two built-in adapters (the other is the jq check). It handles run:shell blocks without any adapter configuration.

Writing an Adapter

Any executable works — Python, Node, Ruby, Go, Rust, shell scripts. The minimal pattern is: read NDJSON from stdin, handle exec and assert messages, and write the response to stdout.

#!/usr/bin/env python3
import json, sys

def handle_exec(source):
    try:
        output = execute(source)
        return {"output": output}
    except Exception as e:
        return {"error": str(e)}

def handle_assert(check, params, columns, cells):
    try:
        run_check(check, params, columns, cells)
        return {"type": "passed"}
    except Exception as e:
        return {"type": "failed", "message": str(e)}

for line in sys.stdin:
    req = json.loads(line)
    if req["type"] == "exec":
        result = handle_exec(req["source"])
        print(json.dumps({"id": req["id"], **result}))
    elif req["type"] == "assert":
        result = handle_assert(
            req["check"], req.get("checkParams", {}),
            req.get("columns", []), req.get("cells", []))
        print(json.dumps({"id": req["id"], **result}))

#!/bin/sh
while IFS= read -r line; do
  type=$(echo "$line" | grep -o '"type":"[^"]*"' | head -1 | cut -d'"' -f4)
  id=$(echo "$line" | grep -o '"id":[0-9]*' | head -1 | cut -d: -f2)
  case "$type" in
    exec)
      echo "{\"id\":${id},\"output\":\"ok\"}"
      ;;
    assert)
      echo "{\"id\":${id},\"type\":\"passed\"}"
      ;;
  esac
done

{
  "id": 1,
  "type": "failed",
  "message": "content mismatch",
  "expected": "alpha\nbeta",
  "actual": "alpha\ngamma",
  "label": "list: empty middle splits"
}

Timeouts

Every adapter request is subject to a time limit. The timeout is determined by (in priority order):

1. Per-document timeout in frontmatter (milliseconds)
2. defaultTimeoutMsec in specdown.json (default: 30000)

If the adapter does not respond within the timeout:

• Exec requests: the engine synthesizes an error response with the message timeout after Nms
• Assert requests: the engine synthesizes a failed response with the message timeout after Nms

The adapter process is not killed — only the pending request is abandoned.

Response Size Limit

Adapter responses are limited to 1 MB per line. If a single response line exceeds this limit, the engine treats it as a read error.

Error Handling