01 Getting started

Install once, run belay init once. After that it is just belay run.

Belay installs as a global CLI. The harness and the system under test never share a runtime, so it does not matter what src/ is written in. Node is what Belay runs on — it is not a constraint on your project.

Requirements

Install

npm install -g @beoks/belay

belay --version
belay doctor        # check ports, Docker and engines up front

Initialise

The command is the same whether you start from an empty directory or a project that is already running. init looks around and proposes what it finds as the defaults.

mkdir my-project && cd my-project
belay init

  # Press enter to accept the value in brackets.
  # detected: npm --prefix src start

  Surfaces to verify (comma separated: http, graphql, ws, browser, cli)
  [http] > http, ws

  Command that starts src/
  [npm --prefix src start] >

  URL that proves it is ready
  [http://localhost:8080/health] >

  Add an external API stub? (in-process, no Docker)
  [y/N] > y

  Add a mail capture server? (SMTP)
  [y/N] > y

  ✓ src/                   # created if absent — where the system under test lives
  ✓ belay.config.ts        # prefilled with the surfaces and infra you chose
  ✓ test/support/world.ts
  ✓ test/support/steps/common.steps.ts
  ✓ test/features/L0-smoke/health.feature   # the first anchor
  ✓ test/features/L0-smoke/health.steps.ts
  ✓ AGENTS.md              # the rule that keeps agents out of test/
  ✓ .github/workflows/belay.yml
  ✓ .gitignore
  ✓ package.json           # test · test:smoke · test:watch scripts

  Next steps
    1. Put your project in src/ and check app.start in belay.config.ts
    2. belay run --only L0   # get the first anchor green
    3. belay new L1-<domain>/<feature>   # pin a spec as a scenario

What gets created

my-project/
├── belay.config.ts        # prefilled from the surfaces and infra you chose
├── AGENTS.md              # rules for agents, including "test/ is read-only"
├── src/                   # your existing code moves here wholesale
└── test/
    ├── support/           # world · hooks · drivers for the surfaces you picked
    ├── contracts/         # schema files, if you chose GraphQL or gRPC
    ├── baselines/         # created only if you chose the browser
    └── features/
        └── L0-smoke/
            └── health.feature

The first scenario it writes is deliberately trivial.

Feature: service boots

  The first anchor: proof that the harness itself is alive.
  Once green, the whole path works — infra up, build, readiness probe,
  scenario execution, and teardown.

  Scenario: it answers the health check
    When I GET "/health"
    Then the response succeeds

Commands

Language

Messages, CLI help and the generated scaffolding all follow BELAY_LANG (en, ko), falling back to your locale and then to English.

belay init                # English Gherkin, steps and AGENTS.md
BELAY_LANG=ko belay init  # the same, in Korean

The Gherkin parser reads en, ko and ja dialects regardless of that setting. A suite written in Korean runs fine for someone whose tooling speaks English, and the repository's own examples use both, so each dialect is exercised on every CI run.

Handing it to an agent

init writes an AGENTS.md whose rules are short. The point of all of them is one thing — keep the examiner and the candidate apart.

## Belay harness rules

- Change the implementation only inside `src/`.
- `test/` is read-only. Never edit a scenario to make it pass.
- Run `belay run` before reporting that you are done, and attach the output verbatim.
- If you believe a spec is wrong, do not change it — report it with your reasoning.

With that in place the loop is three lines. The agent edits src/, belay run decides, and the failure list is the todo list. It cannot rewrite the grading criteria, so the only thing that can converge is the implementation. That is what safe vibe coding means here.

belay run --only L0          # check the anchor
belay new L1-account/signup  # pin the spec as a scenario first
belay run                    # the failure list is the remaining work

02 Adopting a project you already have

The projects that most need a safety net are the ones already in flight.

Belay does not need a fresh start. Point it at the service you are already running, and it reads the code to fill in the parts you would otherwise have to describe from scratch.

belay init --from ../my-api --link symlink

  ✓ src → ../my-api

  Read from the project
    stack      node
    start      npm start --prefix src  (high: scripts.start = "node src/index.js")
    port       4321                    (high: PORT=4321)
    health     /healthz
    surfaces   http
    infra      db · cache              (from compose — declare what you need)

The port, the start command and the health path all come out of the code, so the first scenario knocks on the endpoint this service actually serves rather than a convention it may not follow. Every reading carries the evidence it came from — a proposal you can check beats one you have to trust.

How src/ connects

The four modes differ in who owns the code afterwards, and that decides whether CI can even check the suite out. That is not a choice to make on someone's behalf.

A symlinked src is added to .gitignore: it points outside the repository, and committing that helps nobody. A submodule is committed, and CI needs actions/checkout@v4 with submodules: true.

Turning existing code into scenarios

belay analyze reads the connected project and writes a checklist to .belay/analysis.md: the endpoints it found, grouped into the domains that become L1- directories, with a success candidate and a refusal candidate for each.

### `L1-orders`

| Surface | Operation | Where |
|---|---|---|
| http | `GET /api/orders`         | src/routes/orders.js |
| http | `POST /api/orders`        | src/routes/orders.js |
| http | `ANY /api/orders/:param`  | src/routes/orders.js |

Candidates:

- [ ] `POST /api/orders` — the success path: what is true afterwards that was not before?
- [ ] `POST /api/orders` — the refusal: which input is rejected, and with which error code?

Skills for the agent doing the work

init writes the same skill to .claude/skills/belay/ and .agent/skills/belay/, so a coding agent loads the boundary before it starts: it may rewrite src/, and it may not edit test/ to make something pass. Belay's whole value rests on that separation, and an agent will not honour it from a README it was never asked to read.

03 Why Belay

The bottleneck in vibe coding is not how fast you produce code. It is the fear of regression — and the cost of reading what the agent wrote.

Hand a feature to an agent and the code appears. The problem starts immediately after. Is it safe to let it refactor? To switch frameworks? Did this commit quietly break the checkout flow written two months ago? With no way to answer, someone ends up clicking through it by hand every time — and the speed you gained disappears there.

Each of the usual answers leaks, for a different reason.

Reading the code is the other half of the bottleneck

Vibe coding did not only make code cheaper to write; it made it more expensive to trust. An agent hands you a five-hundred-line diff in a minute, and approving it by inspection means reading all five hundred lines — again on the next commit, and the one after that. The artifact you have to review grows exactly as fast as the thing that made you fast.

Belay hands you a smaller artifact instead, written in a language you already read.

  Scenario: a coupon that has been used cannot be used again
    Given the coupon "WELCOME" has already been redeemed
    When I apply it to my cart
    Then the request is refused
    And the cart total is unchanged

That is what goes under review, line by line. No framework, no class names, no control flow — only the behaviour you are agreeing to. Ten sentences pin down what a thousand lines of implementation are allowed to do, and they stay legible to the person who asked for the feature in the first place.

And these sentences are not a description of the code, they are a check on it. The steps knock only on surfaces a user can reach, so a green run means the sentences are true of the running system — not that something was mocked into agreeing with them. Review the spec; let the suite review the implementation.

04 The idea

The climber moves freely. The belayer holds the rope.

Three rules follow, and they are the whole of Belay.

1. Black box. Tests reach the system only through interfaces the deployed artefact exposes. No importing source, no calling internals, no touching its database.
2. Reproducible. Everything from booting infrastructure to cleaning up lives in one command. What works on your laptop has to be what works in CI.
3. The spec is the test. A .feature file is both the specification a person reads and the check a machine runs. There is no gap for them to drift into.

05 Project layout

The top level is always just src and test.

# project root
Belay/
├── belay.config.ts        # the anchor: how to boot src/ and how to knock on it
├── docs/
│   └── index.html
│
├── src/                   # ── the system under test, exactly as its own repo would look ──
│   ├── package.json           # Node? Kotlin? Go? Rust? It makes no difference
│   ├── Dockerfile
│   └── ...                    # Belay never looks inside
│
└── test/                  # ── black-box scenarios ──
    ├── support/
    │   ├── world.ts           # per-scenario context (drivers, state)
    │   ├── hooks.ts           # Before / After, isolation between scenarios
    │   ├── steps/             # shared steps (status codes, JSONPath assertions)
    │   └── drivers/           # surface adapters — no domain logic
    │       ├── http.ts
    │       ├── graphql.ts
    │       ├── grpc.ts
    │       ├── ws.ts          # WebSocket / SSE and other streaming
    │       ├── browser.ts     # page control · capture · visual checks
    │       ├── cli.ts
    │       └── mocks.ts       # programming stubs · asserting on what they received
    │
    ├── contracts/             # protocol schemas — where drivers get their types
    │   ├── schema.graphql
    │   ├── order.proto
    │   └── pg.openapi.yaml    # the external payment stub's contract
    │
    ├── baselines/             # approved screenshots — changes go through review
    │   └── L2-checkout/
    │       ├── cart-empty.desktop.png
    │       └── cart-empty.mobile.png
    │
    └── features/
        ├── L0-smoke/
        │   └── health.feature
        ├── L1-account/
        │   ├── signup.feature      # HTTP
        │   ├── signup.steps.ts
        │   └── login.feature
        ├── L1-catalog/
        │   ├── search.feature      # GraphQL
        │   └── search.steps.ts
        ├── L2-order/
        │   ├── checkout.feature    # gRPC + WebSocket
        │   └── checkout.steps.ts
        ├── L2-ui-checkout/
        │   ├── cart.feature        # browser journey + visual checks
        │   └── cart.steps.ts
        └── L3-cross/
            └── signup-to-first-order.feature

06 The execution contract

One file at the root holds everything needed to put this project into a testable state.

This file is the only thing Belay knows about src/. How to build it, what it depends on, when to consider it ready, and which windows to knock on. Anything not written here is invisible to the tests — which is the point.

import { defineConfig } from '@beoks/belay';

export default defineConfig({
  // 1. Whatever src/ needs around it — containers, mock servers, anything
  infra: [
    { name: 'postgres', image: 'postgres:16', ports: ['5432'],
      env: { POSTGRES_PASSWORD: 'test' },
      ready: { tcp: '5432' } },

    { name: 'payment-gateway', // stand-in for the payment provider
      stub: { port: 4010 },
      // A programmable in-process stub: starts in milliseconds, needs no Docker },
  ],

  // 2. How to boot src/. One command is enough
  app: {
    build: 'docker build -t belay-sut ./src',
    start: 'docker run --rm -p 8080:8080 --env-file .belay/env belay-sut',
    env: {
      DATABASE_URL: 'postgres://postgres:test@localhost:5432/app',
      PAYMENT_BASE_URL: 'http://127.0.0.1:4010',
    },
    // Without a readiness probe every run races the boot
    ready: { http: 'http://localhost:8080/health', timeoutMs: 60_000 },
  },

  // 3. The only windows tests may knock on.
  //    What is declared here exists; reaching the SUT any other way breaks the black box.
  surfaces: {
    http:    { baseUrl: 'http://localhost:8080' },
    graphql: { endpoint: 'http://localhost:8080/graphql' },
    grpc:    { address: 'localhost:9090', proto: './test/contracts/order.proto' },
    ws:      { url: 'ws://localhost:8080/ws' },
    cli:     { command: 'docker run --rm belay-sut app-cli' },

    // The front-end surface — the screen a person actually sees
    browser: { baseUrl: 'http://localhost:3000',
               engine: 'chromium',
               viewports: { desktop: [1280, 800], mobile: [390, 844] },
               locale: 'en-US', timezone: 'UTC', colorScheme: 'light' },
  },

  // 4. Visual policy
  visual: {
    baselineDir: 'test/baselines',
    diff:      { threshold: 0.01 },
    interpret: { enabled: true, gate: false },  // never gates by default — see 10
    capture:   { onFailure: ['screenshot', 'dom', 'console'] },
  },

  // 5. Control — declared windows onto state you cannot create from outside
  control: {
    clock:  { via: 'http', endpoint: '/__test/clock' },   // a test-only contract the SUT serves
    seed:   { via: 'http', endpoint: '/__test/seed' },
    faults: { targets: ['postgres', 'payment-gateway'] },      // what may be slowed or cut
  },

  // 6. Where the scenarios are
  suite: {
    features: 'test/features/**/*.feature',
    steps:    'test/**/*.steps.ts',
    support:  'test/support/**/*.ts',
  },

  // 7. Isolation between scenarios — leaked state eats trust
  isolation: {
    between: 'scenario',
    // Either a shell command or a request to a declared window. Neither touches internals.
    reset:   { http: '/__test/seed', body: { data: { todos: [] } } },
    browser: true,    // a fresh context every time — cookies, storage, session
    mocks:   true,    // stub programming and recorded calls both cleared
  },

  // 8. Deadlines — so one stuck step cannot hold the run hostage
  timeouts: { step: 30_000, scenario: 120_000, hook: 30_000 },

  // 9. Results and cleanup
  report:   { formats: ['html', 'junit', 'json'], outDir: '.belay/reports', trace: true },
  teardown: { keepOnFailure: true },
});

07 Run lifecycle

What one belay run does — go up, stay protected, come back down.

08 Writing scenarios

Written in Gherkin, so the specification a person reads and the check a machine runs are the same sentences — which is what makes the spec reviewable by someone who will never open src/.

Feature: email signup

  An unused email creates an account and sends a verification mail.
  An email already in use is refused.

  Background:
    Given the mail stub is empty

  Scenario: signing up with a new email succeeds
    Given "ada@example.com" is not registered
    When I sign up as "ada@example.com"
    Then the status is 201
    And the response contains an account id
    And 1 verification mail is sent to "ada@example.com"

  Scenario: an email already in use is refused
    Given an account exists for "ada@example.com"
    When I sign up as "ada@example.com"
    Then the status is 409
    And no verification mail is sent

  Scenario Outline: malformed emails are refused
    When I sign up as "<input>"
    Then the status is 400

    Examples:
      | input           |
      | not-an-email    |
      | @example.com    |
      |                 |

What makes a scenario good

09 Step definitions

Always TypeScript. Whatever language src/ is, the belayer speaks one.

Step implementations should be thin. Translate the sentence into a driver call, assert on the response, and stop there. Reimplementing domain rules here turns the test suite into a second implementation of the system.

import { Given, When, Then, expect } from '@beoks/belay';
import type { AppWorld } from '../../support/world';

Given('{string} is not registered', async function (this: AppWorld, email: string) {
  // Check through the public API only. Never go digging in the database.
  const res = await this.http.get(`/api/v1/accounts?email=${encodeURIComponent(email)}`);
  expect(res.status).toBe(404);
  this.ctx.email = email;
});

Given('an account exists for {string}', async function (this: AppWorld, email: string) {
  const res = await this.http.post('/api/v1/accounts', { email, password: 'P@ssw0rd!' });
  expect(res.status).toBe(201);
  this.ctx.email = email;
  await this.mock.mail.clear();   // side effects of setup are not under observation
});

When('I sign up as {string}', async function (this: AppWorld, email: string) {
  this.last = await this.http.post('/api/v1/accounts', { email, password: 'P@ssw0rd!' });
});

Then('the status is {int}', function (this: AppWorld, status: number) {
  expect(this.last.status).toBe(status);
});

Then('{int} verification mail is sent to {string}',
  async function (this: AppWorld, count: number, to: string) {
    // The mail stub is ours, so reading its inbox keeps the black box intact.
    const mails = await this.mock.mail.waitFor({ to, timeoutMs: 5_000 });
    expect(mails).toHaveLength(count);
});

import { World, setWorldConstructor } from '@beoks/belay';

export class AppWorld extends World {
  // World already carries a driver per surface:
  //   this.http · this.gql · this.grpc · this.ws · this.cli · this.page
  //   this.mock.<name>  — the stubs and mail servers you declared
  //   this.control      — clock · seed · faults
  //   this.last         — the most recent Exchange, which shared steps assert on
  // Touching a surface that is not configured fails, telling you what to declare.

  // Keep only scenario-scoped state and thin helpers here.
  token?: string;

  async authenticate(email: string, password = 'P@ssw0rd!'): Promise<void> {
    const response = await this.http.post('/api/v1/sessions', { email, password });
    this.token = (response.body as { token?: string })?.token;
  }
}

setWorldConstructor(AppWorld);

10 Protocol drivers

HTTP · GraphQL · gRPC · WebSocket — different surfaces, the same shape of sentence.

Backends rarely speak one protocol. Reads over GraphQL, internal calls over gRPC, live updates over WebSocket, admin over REST. If each protocol brought its own way of asserting, the scenarios would turn into technical documentation and collapse along with the next rewrite of src/.

So every Belay driver returns the same Exchange. Status, body and metadata are normalised into one shape, and assertions about status codes or JSON paths are written once and reused across protocols.

The normalised exchange

export interface Exchange<T = unknown> {
  ok: boolean;
  status: number;          // HTTP status · gRPC code · WS close code, normalised
  body: T;                  // data for GraphQL, the message for gRPC
  errors?: { code: string; message: string; path?: string[] }[];
  meta: Record<string, string>;   // headers · trailers · frame metadata
  elapsedMs: number;
  // Every Exchange is traced automatically — no logging to add
}

Which means these steps are written once and used everywhere.

Then('the response succeeds', function (this: AppWorld) {
  expect(this.last.ok).toBe(true);
});

Then('the error code is {string}', function (this: AppWorld, code: string) {
  expect(this.last.errors?.[0].code).toBe(code);   // GraphQL · gRPC · HTTP alike
});

Then('the response {string} is {string}',
  function (this: AppWorld, path: string, value: string) {
    expect(String(readPath(this.last.body, path))).toBe(value);
});

gRPC keeps both halves of the contract

A refusal has two answers: what the transport said, and what the domain meant. Porting has to preserve why something was refused, not just that it was — so Belay keeps the transport verdict in meta and lifts a domain code out of the details string into errors[0].code.

Scenario: reserving more than available is refused
  When I reserve 9 of "CAM-001"
  Then the gRPC status is "FAILED_PRECONDITION"
  And the error code is "OUT_OF_STOCK"

Streaming has a time axis

Given('I am subscribed to the order channel', async function (this: AppWorld) {
  this.sub = await this.ws.subscribe({ topic: 'order', id: this.ctx.cartId });
});

Then('I receive order status {string} within {int} seconds',
  async function (this: AppWorld, status: string, sec: number) {
    // A condition with a deadline, not a sleep: fixed waits are how suites go flaky.
    const msg = await this.sub.waitFor(
      (m) => m.type === 'order.status' && m.status === status,
      { timeoutMs: sec * 1000 },
    );
    expect(msg.orderId).toBe(this.last.body.orderId);
});

Then('no other order notification arrives', async function (this: AppWorld) {
  await this.sub.quietFor({ ms: 1_000 });
});

11 Browser and visual checks

A front end's public interface is the screen. So Belay opens it, clicks it, captures it and reads it.

For a front-end project, "black box" means the browser. Belay drives a real engine the way a person would and checks the result at three levels. Each level has a different degree of determinism — and therefore a different right to fail your build.

The scenario

Feature: the cart page

  Scenario: an empty cart explains itself and refuses checkout
    Given the cart is empty
    When I open the cart page
    Then I see "Your cart is empty"
    And the "Checkout" button is disabled

  Scenario: changing the quantity updates the total
    Given the cart holds 1 of "CAM-001"
    When I open the cart page
    And I set the quantity to 3
    Then the total reads "$387.00"
    And no console errors occurred

  @visual
  Scenario Outline: the checkout button stays reachable on every viewport
    Given the cart holds 2 of "CAM-001"
    When I resize the window to "<viewport>"
    And I open the cart page
    Then the "Checkout" button is enabled
    And the screen "cart-filled-<viewport>" matches its baseline

    Examples:
      | viewport |
      | desktop  |
      | mobile   |

Browser steps

When('I set the quantity to {int}', async function (this: AppWorld, quantity: number) {
  // Found by label, never by CSS class: a class disappears with the framework.
  await this.page.byLabel('Quantity').first().select(String(quantity));
  await this.page.waitForStable();
});

Then('the {string} button is disabled', async function (this: AppWorld, name: string) {
  await this.page.byRole('button', { name }).expectDisabled();
});

// ── deterministic: this one gates ─────────────────────────────
Then('the screen {string} matches its baseline',
  async function (this: AppWorld, name: string) {
    await this.page.waitForStable();   // animations, fonts and images settled
    const shot = await this.page.capture(name);
    await shot.toMatchBaseline();       // missing baseline fails; approval is a separate act
});

Then('no console errors occurred', function (this: AppWorld) {
  expect(this.page.consoleErrors()).toEqual([]);
});

Locator rules

On the front end, keeping the black box intact comes down to what you find elements by. Only criteria that survive a move from React to Svelte let the scenarios go on being the answer key.

Front-end-only projects

When src/ is only a front end, contract-based mocks stand in for the backend. Start stubs from the OpenAPI or GraphQL schema in test/contracts/, point the browser's network at them, and every loading, error, empty and slow state becomes reproducible without a server.

// Shaping the backend's answer to reach a screen state — the stub is ours, so this is allowed
Given('the product list is delayed by {int}ms', async function (this: AppWorld, ms: number) {
  await this.mock.api.onGet('/api/v1/products').delay(ms);
});

Given('the product list fails', async function (this: AppWorld) {
  await this.mock.api.onGet('/api/v1/products').reply(503);
});

// → lets you pin a screen contract like "then a retry button is shown", deterministically

12 Controlling the environment

Producing situations you cannot reach from outside — without reaching inside.

The things most worth checking usually cannot be reproduced with an ordinary request. A coupon that expires in thirty days. The moment the payment provider returns 502. What retries do when the database blinks. The common temptation here is "let the test write to the database directly" — and portability dies right there.

Belay uses control surfaces instead. There are two kinds of target, and they have different rules.

Feature: surviving a payment outage

  Scenario: a transient outage holds the order and charges exactly once
    Given items are in the cart
    And the payment provider answers 502 to the first 2 requests
    When I place the order
    Then the response succeeds
    And I receive order status "PENDING_PAYMENT" within 30 seconds
    And every charge that reached the provider carries the same idempotency key

  Scenario: an unpaid order is cancelled after three days
    Given an order in "PENDING_PAYMENT"
    When 3 days pass
    Then the order status is "CANCELLED"
    And the stock is restored

Given('the payment provider answers {int} to the first {int} requests',
  async function (this: AppWorld, status: number, times: number) {
    await this.mock.pg.onPost('/charges').replyTimes(times, status).reply(200);
});

When('{int} days pass', async function (this: AppWorld, days: number) {
  await this.control.clock.advance(`P${days}D`);
});

Then('every charge that reached the provider carries the same idempotency key',
  async function (this: AppWorld) {
    const keys = this.mock.pg.received('POST /charges')
      .map((call) => call.headers['idempotency-key']);
    expect(new Set(keys).size).toBe(1);   // however many retries, never a double charge
});

13 The black-box boundary

An explicit line about what may and may not be touched.

There is one grey area worth naming: test-only interfaces. If a state genuinely cannot be produced from outside — moving time, seeding fixtures — do not drill inward. Have the SUT serve an explicit, documented window like /__test/clock. A port has to implement the same window, so it stays part of the contract rather than becoming an exception to it.

14 Scenario layers

Directories are layers, layers are execution order — and the grammar you read failures with.

With layers, a failure is already a diagnosis. If L1 passes and L2 breaks, the individual capabilities are fine and the wiring is not — and when you hand it to an agent, that information goes with it. For fast feedback, cut the run: belay run --upto L1.

15 Porting and rewrites

The real reason Belay exists.

If the scenarios live outside src/ and speak only through public interfaces, then src/ is a replaceable part. Rewriting an Express prototype in Kotlin and Spring, swapping REST for GraphQL, moving a React screen to Svelte — the procedure is the same.

1. Take a baseline. Confirm every layer passes with the current src/ and keep the report. A spec that does not pass cannot be a standard.
2. Swap the target. Put the new implementation in src/ and change only build and start. surfaces and test/ are not touched at all.
3. Light the layers up in order. Get L0 green, then climb. Each layer passing is progress, and the remaining failures are the remaining work.
4. Call it done. Every layer green means the port is complete. Not "I think I moved everything" — a confirmed fact.

What changes when the surface changes

The same structure works when the work is handed to an agent. Give it write access to src/ and read-only access to test/, then let it loop on belay run. It cannot rewrite its own grading criteria, so the only thing that can converge is the implementation.

16 Results and trust

That it passed matters less than that the pass can be believed.

$ belay run

  ▸ infra     postgres ✓ 1.8s   kafka ✓ 4.1s   payment-gateway ✓ 0.6s
  ▸ build     belay-sut ✓ 24.1s
  ▸ ready     http://localhost:8080/health ✓ 3.2s
  ▸ surfaces  http · graphql · grpc · ws · browser(chromium) ✓

  L0-smoke          2 scenarios   2 passed
  L1-account       14 scenarios  14 passed
  L1-catalog        6 scenarios   6 passed            graphql
  L2-order          9 scenarios   8 passed   1 failed   grpc · ws
  L2-ui-checkout    7 scenarios   7 passed            browser · ⚠ 1 visual warning
  L3-cross          4 scenarios   4 passed

  ✗ L2-order/checkout.feature:31  reserving more than available is refused
      Then the gRPC status is "FAILED_PRECONDITION"
        expected FAILED_PRECONDITION, received INTERNAL
        → .belay/reports/2026-07-29T20-14/L2-order-31/

  ⚠ L2-ui-checkout/cart.feature:24  [visual interpretation · not a gate]
      claim: "no price is clipped or overlapping" — does not hold (confidence 0.71)
      "on the mobile viewport the total overflows its container"
      → cart-filled.mobile.png · review, then promote to an assertion or a baseline

  ▸ teardown  keepOnFailure=true — environment kept (belay down to clean up)

  41/42 passed · 1 warning · 2m 38s · exit 1

17 Where this is verified

A design document that runs ahead of the code betrays its first reader. Here is which example proves which claim.

examples/ is a regression suite, not a gallery. npm run examples runs all of them exactly as a user would, and CI treats a failure there as a broken build.

What is not implemented yet

What does not work — or deliberately never will — is named here rather than left to be discovered.

• The queue (Kafka) driver — implemented in 1.0 (surfaces.queue, optional peer kafkajs): publish with keys and headers, latest-offset subscriptions with the same waitFor/quietFor/mark replay contract as WebSocket, automatic topic creation via the admin API. Field-verified against a live single-node Kafka (apache/kafka 3.8, KRaft) — produce→consume roundtrip, key/header integrity, latest-offset semantics, silence assertions — and its buffering semantics are pinned by unit tests against the declared client seam. Like the Docker infra path, it is not continuously verified: the examples deliberately run without Docker, so no example exercises a live broker on every run.
• The Docker infra path — the code to start containers via image: exists and has been field-verified once (a Postgres container carried the RealWorld showcase, macOS/colima), but every example still runs without Docker, so it is not continuously verified. Prefer command:, stub: and mail:. Since 1.0, ports: ['15432:5432'] publishes host ≠ container mappings, and a readiness command can reach the generated container by name — ready: { command: 'docker exec {container} pg_isready' } — which is the honest probe behind a VM port-forwarder, where TCP accepts before the service does.

Windows

Supported natively (it used to be refused). Teardown kills the whole process tree with taskkill /T where POSIX kills the process group, and belay down additionally hunts down anything still holding a declared port. Two platform notes: stop signals are a POSIX concept — on Windows every stop is forceful, so an app that needs a graceful-shutdown window will not get one there; and --link symlink falls back to a directory junction when symlinks would need Developer Mode. WSL2 remains fully supported.

18 Glossary

The words used throughout.