@crvouga/atlas 0.3.0 → 0.5.0

package/README.md

@@ -1,33 +1,89 @@
 # Atlas
 
-**Executable statecharts.** Write down how a product behaves as statecharts in open formats, then
-let Atlas lint them, plan paths that cover every transition, run those paths against the real
-product through any driver (a browser, a phone, a plain function), and write a manifest of what
-happened, with screenshots, video clips, captions, business events and standard test reports.
-
+**Specs of any kind, reported as layered evidence.** Atlas lays the results of every suite that
+checks your specs (Gherkin, Quint, DMN, Alloy, OpenSLO, unit and end-to-end tests, linters,
+statecharts) over the specs themselves, across machines, branches, environments and storage
+backends, and tells you in one command whether the product still does what it was specified to do.
+
+- **Any spec, any runner.** Anything that ends in "this check passed or failed" publishes a *layer*:
+  from a JUnit or CTRF file, a ten-line script, or code. No runner and no notation is privileged.
+- **Layered, never partitioned.** A report is computed from layers, not stored as "the run". Partial
+  runs on separate nodes, branches and devices are how a report is built, and they compose without
+  coordinating: the same layers give the same report in any order, split any way.
+- **Open evidence.** A result carries whatever your framework produces: screenshots, videos, traces, logs, DOM
+  snapshots, timelines, retries, annotations, your own structured data. Any media type, nothing registered, and
+  new kinds never break older readers ([extending](docs/extending.md)). Specs stay opinionated (statecharts,
+  Gherkin, Quint, DMN, Alloy, OpenSLO); evidence stays open.
+- **Open standards, stable schemas.** JUnit XML and CTRF in, JSON Schema 2020-12 contracts, a
+  versioned layer format with a golden fixture, and an `ObjectStore` interface any bucket fits.
+- **One server, live.** A project runs one `atlas serve`: a Bun API that serves the viewer from the same host.
+  Every laptop and CI job sends results to it as they finish (`atlas report publish`, or `atlas report stream` while
+  a suite runs), it keeps them on its own disk (or in S3, R2, MinIO), and every viewer sees the combined report
+  update live, receiving only what changed ([the server](docs/server.md), [deploying](docs/deploying.md)).
+- **Fast and fail-closed.** Publishing is two small writes. A thousand layers of a hundred checks
+  combine in about a second. An unreadable layer, a downed backend or a check still running is never
+  counted as a pass.
+- **Executable statecharts too.** Atlas can also run a product's flows as statecharts against the
+  real app, and publishes those runs as layers like any other ([below](#executable-statecharts)).
+
+```
+ any suite   ──▶ layer ─┐                              atlas report status   exit 1 unless it passes
+ any node    ──▶ layer ─┼─▶ backends ─▶ combine ─▶     the visualizer        browse it beside the specs
+ any branch  ──▶ layer ─┘   (directories, buckets, …)   combineBackends()     your own code
 ```
-specs/                     atlas lint      the charts are pure, reachable, free of silent dead ends,
-  app.scxml          ──▶                   and every journey replays
-  child.machine.yaml       atlas plan      curated journeys + shortest paths covering every transition
-  journeys.yaml            atlas run       each path against the product, through a driver
-                                  │
-                                  ▼
-                           atlas-runs/<run>/manifest.json, junit.xml, ctrf.json, chart.mmd, media/
-```
-
-The spec is the source of truth for the product's behaviour, not for the test code: a state says
-what a person sees, an event says what happens in business language ("Adds a todo", "Sync fails"),
-and the implementation says how a driver makes each event happen and recognises each state.
 
 > [!IMPORTANT]
 > **Dogfooding phase:** Atlas is developed by using it in real projects. Those projects install the
-> published packages from npm and report bugs and missing features as GitHub issues; they do not
+> published package from npm and report bugs and missing features as GitHub issues; they do not
 > change this repository. If you are integrating Atlas, or are an agent working in a project that
-> uses it, read [using Atlas from another project](docs/dogfooding.md) and
-> [reporting issues](docs/reporting-issues.md). Releases are automatic: see
-> [releasing](docs/releasing.md).
+> uses it, read **[integrating Atlas](docs/integrating.md)**, then
+> [using Atlas from another project](docs/dogfooding.md) and [reporting issues](docs/reporting-issues.md).
+> Releases are automatic: see [releasing](https://github.com/crvouga/atlas/blob/main/docs/releasing.md).
+
+## For AI agents
+
+Atlas is built to be integrated and operated by agents, with nothing to click and nothing to guess.
 
-Atlas also owns specification and test-evidence visualization: Gherkin, Quint, DMN, Alloy, OpenSLO and supporting documents appear in **Specs and evidence**, alongside commit-scoped checks, recordings and performance measurements. See [Atlas reports](packages/reports/README.md).
+- **`atlas init`** detects a project's test runners, specs and CI and prints a plan (`--format json`) of the exact commands to
+  run each suite and send its results; `--write` creates the CI workflow and an `AGENTS.md` section. Running it twice
+  changes nothing.
+- **Every command prints JSON on request** (`--format json`), every document has a published JSON Schema, exit codes mean the
+  same everywhere (`0` worked, `1` the answer is no, `2` the command was wrong), and every operation is safe to repeat.
+- **The server describes itself:** `GET /api/openapi.json` (OpenAPI 3.1) and `GET /llms.txt` (a guide for an agent given only
+  the address) need no token; errors are RFC 9457 problem documents that say what to do.
+- **Documentation is generated from the code beside it:** `llms.txt` / `llms-full.txt` (also in the package), the TypeScript
+  reference in [`docs/reference/`](docs/reference/server.md), the CLI and HTTP references, and the settings tables; tests fail when
+  any of it drifts.
+
+Start with **[Atlas for AI agents](docs/agents.md)**.
+
+## Integrate in five minutes
+
+```sh
+bun add -d @crvouga/atlas            # or npm install -D / pnpm add -D; runs on Bun and Node 22.18+
+
+# 1. Each suite publishes a layer of what it ran: a JUnit or CTRF file, an Atlas run, or a checks file.
+bunx atlas report publish --store atlas-reports --producer web-e2e --junit out.xml --specs ./specs --environment desktop-web
+
+# 2. Any number of nodes, branches and machines do the same into their own stores. Copying stores
+#    together is the aggregate: layers are immutable and named by their content.
+bunx atlas report merge --store node-1 --store node-2 --into all
+
+# 3. The gate: exit 1 on a failed check, a check still running, an unreadable layer, a backend that
+#    is down, or an environment with no results.
+bunx atlas report status --store all --specs ./specs --require-environments desktop-web,ios
+```
+
+| Read | When |
+| --- | --- |
+| **[Integrating Atlas](docs/integrating.md)** | Start here. Step by step, with the command and expected output for each step, a CI workflow for sharded nodes, and troubleshooting. |
+| **[The Atlas server](docs/server.md)** | The living application: configuration, tokens, the upload and streaming protocol, the full API, what it refuses, performance. |
+| **[Running Atlas for a project](docs/deploying.md)** | Production: the server (Docker, Kubernetes, auth), sending results from CI and laptops, an S3 bucket and its policies, filters, operating it. |
+| [The report contract](docs/report-contract.md) | The exact rules: the layer document, how layers compose, guarantees, backends, versioning, failure behaviour. |
+| **[Evidence: attachments, timelines and everything else](docs/extending.md)** | What a result can carry, the rules that keep the format compatible forever, and how to attach anything from any framework. |
+| [Report backends and live snapshots](docs/report-backends.md) | Connecting directories, HTTP files and APIs, streaming, and writing another transport. |
+| [`@crvouga/atlas/reports`](packages/reports/README.md) | The programmatic API: `publishChecks`, `combineBackends`, `reportStatus`, `directoryStore`, `reportsHost`. |
+| [`@crvouga/atlas/schema`](packages/schema/README.md) | The JSON Schemas and Zod schemas of every document. |
 
 ## One package
 
@@ -40,616 +96,134 @@ bun add -d @crvouga/atlas
 
 | Import | What it is |
 | --- | --- |
-| [`@crvouga/atlas`](packages/core) | Spec loading (SCXML and XState), composition, lint, planning, the runner, multi-client runs (`combineDrivers`), `httpDriver` and `functionDriver`, reports, CloudEvents, privacy, config and the `atlas` CLI. `@crvouga/atlas/spec` is a browser-safe subset; `@crvouga/atlas/signals` holds the driver-neutral signals. |
+| [`@crvouga/atlas/reports/<module>`](packages/reports) | Evidence for any spec: publish layers (`publish-checks`, `ingest`, `reporter` to stream them), store them (`s3-store`, `directory-store`, `http-store` for a server, any `object-store`), combine and gate them (`compose`, `report-status`), copy them (`copy-store`). |
+| [`@crvouga/atlas/server`](packages/server) | The Atlas server as a `fetch` handler (`createAtlasServer`), served over HTTP on Bun and Node (`listen`). |
+| [`@crvouga/atlas/schema`](packages/schema) | The contract: Zod schemas and JSON Schemas for layers, check files, report status, specs, journeys, manifests, timelines and the runs index. |
+| [`@crvouga/atlas`](packages/core) | Spec loading (SCXML and XState), composition, lint, planning, the runner, multi-client runs (`combineDrivers`), `httpDriver` and `functionDriver`, CloudEvents, privacy, config and the `atlas` CLI. `@crvouga/atlas/spec` is a browser-safe subset; `@crvouga/atlas/signals` holds the driver-neutral signals. |
 | [`@crvouga/atlas/playwright`](packages/playwright) | Playwright driver: signal-based screen recognisers, paced taps and typing with a touch overlay, device-resolution screenshots and H.264 clips. |
 | [`@crvouga/atlas/bun`](packages/bun) | Bun WebView driver: Bun's built-in headless browser (the system WebKit on macOS, Chrome elsewhere), nothing to download. |
 | [`@crvouga/atlas/webdriver`](packages/webdriver) | W3C WebDriver driver with no dependencies: Safari, Chrome, Firefox and Edge, and native iOS and Android apps through Appium. |
 | [`@crvouga/atlas/detox`](packages/detox) | Detox driver for iOS and Android apps, inside a Detox test run. |
 | [`@crvouga/atlas/vitest`](packages/vitest) | Run a config as a test suite in Vitest, `bun test` or any Jest-style runner, one test per planned path. |
-| [`@crvouga/atlas/schema`](packages/schema) | The contract: Zod schemas and JSON Schemas for specs, journeys, manifests, timelines and the runs index. |
-| [`@crvouga/atlas/reports/<module>`](packages/reports) | Publish, store, retain and serve test evidence, and combine it across backends, branches and commits. |
-| [`atlas-visualizer`](packages/visualizer) (command) | Browse charts and runs: every state with its screenshots, every transition with its clip. |
-
-## Open standards
-
-Atlas invents as little as it can. Everything it reads or writes is a format other tools already
-understand.
-
-| Standard | Used for |
-| --- | --- |
-| [W3C SCXML](https://www.w3.org/TR/scxml/) | Charts (`*.scxml`), with business metadata in an `atlas` XML namespace |
-| [XState v5](https://stately.ai/docs/machines) machine config | Charts (`*.machine.json`, `*.machine.yaml`): the JSON shape Stately Studio imports and exports |
-| [JSON Schema 2020-12](https://json-schema.org/draft/2020-12) | The manifest, journeys, state nodes, timelines and runs index (`packages/schema/schemas`) |
-| [JUnit XML](https://github.com/testmoapp/junitxml) | `junit.xml`: one test case per path, for any CI system |
-| [CTRF](https://ctrf.io) | `ctrf.json`: Common Test Report Format |
-| [WebVTT](https://www.w3.org/TR/webvtt1/) | Captions for every clip: each tap, keystroke, system call and screen change |
-| [CloudEvents 1.0](https://cloudevents.io) | Business events the product emits (HTTP structured, binary and batch modes) |
-| [W3C WebDriver](https://www.w3.org/TR/webdriver2/) | Driving browsers and, through Appium, native iOS and Android apps |
-| [WAI-ARIA](https://www.w3.org/TR/wai-aria/) roles and accessible names | Signals that recognise screens the same way on every driver |
-| MP4 / H.264 | Clips of each transition, encoded with FFmpeg |
-| PNG / WebP | Screenshots at device resolution, with WebP thumbnails |
-| [Mermaid](https://mermaid.js.org/syntax/stateDiagram.html) `stateDiagram-v2` | `chart.mmd`, and `atlas export --format mermaid` |
-
-## Quick start: the todo example
-
-[`examples/todo`](examples/todo) is a dependency-free web app (static HTML and vanilla JavaScript
-served by a small Node server) specified as two charts:
-
-- `specs/todo-app.scxml`, the root chart in SCXML: a welcome screen, a "Setting up" state that
-  invokes the child chart, and a `<parallel>` "Working on the list" state whose "Sync" and "List"
-  regions change independently.
-- `specs/getting-started.machine.yaml`, the child chart in XState YAML. Its two final states hand
-  back to the parent through `meta.doneEvent`.
-- `specs/journeys.yaml`, four curated journeys.
-- `specs/getting-started.feature` and `specs/working-the-list.feature`, the same stories in Gherkin.
-- `specs/todo.qnt`, the list, its sync, and its actions as a Quint model.
-
-The visualizer lists the features under Gherkin and the model under Quint.
-
-It has every kind of event: user events (taps and typing), a **system** event ("Sync fails", which
-the test triggers through a real HTTP endpoint on the example server), a **time** event ("Retry
-timer elapses", which jumps Playwright's clock 30 seconds) and **hand-off** events from the child
-chart. The server reports business events as CloudEvents to an Atlas `cloudEventsHttpSource`, so
-the states' `meta.events` are checked on every run.
-
-This repository runs on [Bun](https://bun.sh). Video clips and WebP thumbnails need FFmpeg on the
-`PATH`. From the repository root:
-
-```sh
-bun install
-bunx playwright install chromium
-
-bun run example:lint   # pure, reachable, no undocumented dead ends, journeys replay, everything implemented
-bun run example:plan   # 4 journeys + 1 generated path cover all 14 transitions
-bun run example:fast   # run every path quickly
-bun run example:run    # statechart showcase, then the Gherkin features and the Quint model
-bun test examples      # the same spec against an in-memory model, as a test suite
-
-bun run example:clients      # clients/: one chart across a phone, a desktop and the sync server at once
-bun run example:clients:bun  # the same, with the desktop in Bun's WebKit and the phone in Playwright's Chromium
-```
-
-To run every chart of the example and browse the results, run these in separate terminals; the
-visualizer updates when a run finishes.
-
-```sh
-bun run atlas:run   # example:clients, then example:run: every chart of the example, in showcase mode
-bun run atlas:viz   # the example's specs, chart runs, Gherkin features, and Quint model
-```
-
-Each config writes its own run and the visualizer shows one run at a time: the latest is the
-single-browser run, and the run across clients is the one before it in the run picker.
-
-A showcase run ends with:
-
-```
-States 14/14 passed, 0 failed, 0 not reached
-Transitions 14/14 passed, 0 failed, 0 not reached
-Manifest: examples/todo/atlas-runs/<run-id>/manifest.json
-```
-
-`example:run` then runs the Gherkin features in a browser and the Quint model. `atlas:viz` shows those results on the scenario and trace rows.
+| [`atlas-visualizer`](packages/visualizer) (command) | Browse specs, charts and layered reports: every spec with its result per environment, every state with its screenshots, every transition with its clip. |
 
-`bun test examples` runs [`model.test.ts`](examples/todo/model.test.ts): the same charts and journeys
-against `TodoModel`, a plain class, through `functionDriver` and `describeAtlas`. Only the driver
-and the implementation differ, which is the point: the spec belongs to the product, not to one
-test tool.
+Two commands install with it: `atlas` (`report`, `lint`, `plan`, `run`, `merge`, `export`) and
+`atlas-visualizer`.
 
-## Writing specs
+## Reports for any spec
 
-### Files
+Atlas separates *what the product should do* (the specs) from *evidence of what it did* (layers).
+Evidence is published by whatever checks the spec, and read back as one report.
 
-Atlas loads every chart and journeys file directly inside the specs directory:
+**A layer** is one focused recording: the checks one producer ran, on one environment, from one
+commit and branch, at one time. It is immutable and addressed by its content. Publish one from:
 
-- `*.scxml`, `*.machine.json`, `*.machine.yaml` (or `.yml`): one chart each;
-- `journeys.yaml` (or `.yml`, `.json`): the curated journeys.
-
-The **root** chart is the one no other chart invokes. A chart's id is the SCXML `name` attribute or
-the XState `id`.
-
-### The pure subset
-
-Atlas walks charts without running any code, so it executes only the parts of a statechart that
-are pure structure:
-
-- states, nesting (`initial`), `parallel` regions and `final` states;
-- event transitions, written as a target (`Opens: Open` or `{ target: '#Open' }`);
-- `invoke` that names another chart (`src`, `id`, `onDone`), composed statically;
-- `meta`.
-
-Guards, actions, `entry`/`exit`, `context`, `after` (delays), `always`, `output` and `onError` are
-lint errors. A condition becomes a state or an event instead: "Payment declined" is an event the
-system sends, not a guard on "Pays"; "30 seconds pass" is a time event, not an `after`.
-
-State names are global across the composed product (transitions target `#<name>`), so they must be
-unique across charts, and they cannot contain dots. Names are business language and may contain
-spaces.
-
-### `meta`
-
-| Field | Meaning |
+| You have | Publish with |
 | --- | --- |
-| `description` | What is true in this state. Required on every state by default (`requiredMeta` changes that). |
-| `snapshot` | What a person sees, in words. |
-| `events` | Business events that happen on entering the state, checked against what event sources observed. |
-| `checks` | Things to verify on screen, quoted from the spec; the implementation's `checks()` returns their results. |
-| `confidence` | `confirmed` or `assumed`. |
-| `source` | Where the behaviour is documented. |
-| `deadEnd` | Why a state with no way out is meant to be one. Without it, a dead end is a lint error. |
-| `doneEvent` | On a child chart's final state: the event its parent receives from that final. |
-| `childMachine`, `childFinalEvents` | Legacy composition on the parent state. Prefer `invoke`. |
-
-### SCXML conventions
-
-SCXML ids are XML IDs and event attributes are token lists, so business names travel in an
-`atlas:name` attribute next to a token id. Metadata lives in the `atlas` namespace, as SCXML allows:
-
-```xml
-<scxml xmlns="http://www.w3.org/2005/07/scxml" xmlns:atlas="https://github.com/crvouga/atlas/ns/1"
-       version="1.0" datamodel="null" name="Todo app" initial="welcome">
-  <state id="welcome" atlas:name="Welcome">
-    <atlas:meta>
-      <atlas:description>The first screen a person sees.</atlas:description>
-      <atlas:event>App opened</atlas:event>
-    </atlas:meta>
-    <transition event="starts-setup" atlas:name="Starts setup" target="setting-up"/>
-  </state>
-  <state id="setting-up" atlas:name="Setting up">
-    <atlas:meta><atlas:description>The child chart runs here.</atlas:description></atlas:meta>
-    <invoke id="getting-started" src="getting-started.machine.yaml" atlas:name="Getting started"/>
-    <transition event="done.invoke.getting-started" target="working"/>
-  </state>
-  ...
-</scxml>
-```
-
-`<atlas:event>`, `<atlas:check>` and `<atlas:source>` repeat to form lists; `<atlas:dead-end>` is
-`meta.deadEnd`; a final state's `atlas:done-event` attribute is `meta.doneEvent`. `atlas export
---format scxml` writes any chart (or the composed product) back out in this form, and reading it
-again gives the same chart.
-
-### Composition
-
-A parent state runs a child chart with any of:
-
-1. XState `invoke: { src: 'Child', id: 'child', onDone: '#Next' }`, or SCXML `<invoke id="child">`
-   plus a `done.invoke.child` transition;
-2. `meta.doneEvent` on the child's final states, each naming the event the parent receives, which
-   the parent handles in its `on` (a final whose event the parent does not handle goes to
-   `onDone`);
-3. legacy `meta.childMachine: 'Child'` and `meta.childFinalEvents: { <final>: <event> }` on the
-   parent state.
-
-Atlas inlines each child into the state that invokes it. The child's final states stay as states
-(so they keep their screenshots and checks) but take the parent's transition for their hand-off
-event. When a path reaches one, the hand-off happens by itself: journeys never list hand-off
-events, and the planner inserts them. Give each hand-off event an implementation of kind
-`hand-off` (usually a no-op); events without an implementation count as blocked.
-
-### Journeys
-
-```yaml
-journeys:
-  Keeps working through a sync outage:
-    description: Adds todos while the sync is down, and the retry catches up.
-    events: [Starts setup, Skips naming the list, Adds a todo, Sync fails, Adds a todo, Retry timer elapses]
-    endsIn: [Some todos open, Synced]
-```
-
-The linter replays each journey through the composed chart and checks it ends in every `endsIn`
-state. Each journey runs as its own path; generated paths only cover what journeys leave out.
-
-## Implementing a spec
-
-An implementation tells a driver how to make each event happen and how to recognise each state.
-Events are keyed by their exact name in the spec.
+| JUnit XML from Cucumber, Jest, Vitest, Bun, pytest, `go test`, Playwright, … | `atlas report publish --junit out.xml` |
+| [CTRF](https://ctrf.io) JSON | `atlas report publish --ctrf ctrf.json` |
+| An Atlas statechart run | `atlas report publish --manifest atlas-runs/<run>/manifest.json` |
+| A script, a model checker, an SLO evaluation, a linter | `atlas report publish --checks checks.json`, or `publishChecks(store, …)` |
+
+**Layers compose by one rule.** A *slot* is `(producer, kind, spec, check id, environment,
+parameters)`. Each slot shows the newest completed result of any layer that filled it. Branch, commit,
+backend and run are provenance and never split a slot. So desktop web, mobile web, iOS and Android
+results of one check sit side by side; a layer that re-ran one scenario leaves every other scenario as
+the last layer that ran it; and a fix on any branch replaces the failure it fixes.
+
+**The report does not depend on how layers arrived.** Order of reading, number of backends, how
+the layers were split across nodes, and duplicates are all invisible. This is tested over random
+partial runs, and it is why you can shard a suite across ten machines, re-run one failing check
+locally, and publish a device lab's layers from elsewhere, with nothing to coordinate.
+
+**Backends** hold layers. A backend is any implementation of the seven-method `ObjectStore`
+interface. Atlas ships an S3 store (AWS S3, R2, MinIO and anything that speaks its protocol, with no SDK)
+and a directory store with atomic writes, and `verifyObjectStore` proves an adapter before you trust it. Several backends are one report, and one
+that is down is named and skipped.
+
+**The gate** is `atlas report status`. It exits 0 only if some check completed, none failed, none is
+still running, every layer and backend could be read, and every `--require-environments` environment
+has results. `--format json` is a [stable schema](packages/schema/schemas/report-status.schema.json). Exit code 1
+means the report does not pass; 2 means the command itself was wrong (a missing store directory, a bad
+flag).
+
+**The server** is `atlas serve`: one process that serves the viewer, takes in results and streams the report to
+every viewer. Point `ATLAS_STORE` at it and every developer's laptop and every CI job sends results with the same
+commands that write to a folder; everyone then looks at one report, live. Results are kept in its data folder
+unless you choose a bucket. `atlas dev` runs the same server with the viewer's dev server in front, so
+development is one host too. See [the server](docs/server.md) and
+[running Atlas for a project](docs/deploying.md).
 
-```ts
-import { defineConfig } from '@crvouga/atlas';
-import { playwrightDriver, role, screen, text } from '@crvouga/atlas/playwright';
-
-export default defineConfig({
-  specs: './specs',
-  driver: () => playwrightDriver({ clock: true }),
-  targets: ['http://127.0.0.1:4317'],
-  implementation: {
-    async setup({ page }) {
-      await page.goto('http://127.0.0.1:4317');
-    },
-    events: {
-      'Adds a todo': {
-        kind: 'user',
-        how: 'Types a todo and taps "Add".',
-        async run({ page, user }) {
-          await user.type(page.getByLabel('New todo'), 'Water the plants', 'New todo');
-          await user.tap(page.getByRole('button', { name: 'Add' }), 'Add');
-        }
-      },
-      'Retry timer elapses': {
-        kind: 'time',
-        how: 'Jumps the page clock 30 seconds.',
-        run: ({ page }) => page.clock.fastForward(30_000)
-      }
-    },
-    states: {
-      'No todos': screen({ all: [text('Nothing to do yet')] }),
-      Offline: screen({ all: [text('Offline')], none: [text('All changes synced')] })
-    }
-  }
-});
-```
-
-**Events** (`EventImplementation<C>`): `kind` is `user`, `system`, `time` or `hand-off`; `how` is a
-plain-language note shown in reports; `run(ctx, tools)` makes it happen; `prepare(ctx, tools)`
-creates test data before the path starts; `blocked: '<reason>'` marks an event that cannot run yet,
-so paths stop before it and report why.
-
-**States** (`StateImplementation<C>`): `recognize(ctx)` returns whether the state is showing and the
-signals it looked at. Optional: `checks(ctx)` (results for `meta.checks`; a failed check fails the
-state), `lookIn(ctx)` (where to look when the change happens off screen, such as reloading or
-opening another tab), `settle(ctx)` (within-state actions after the screenshot, such as
-dismissing a toast), `transient` (shown too briefly to wait for) and `sameAs` (a state the UI cannot
-tell apart from this one).
-
-**Setup**: `setup(ctx, { path, tools })` puts the product in the path's start configuration;
-`canStart(active)` returns `true` or the reason a start configuration cannot be set up yet. It is
-optional when seeds cover every start.
-
-**Seeds** (`seeds: Record<string, Seed<C>>`): see [Seeds and parallel runs](#seeds-and-parallel-runs).
-
-**Correlation**: `correlate(ctx)` returns ids (a user id, a trace id) that tell this attempt's
-business events from those of attempts running beside it.
-
-Only leaf states need recognisers. `atlas lint --require-implementations` lists every event and
-leaf state in scope that has no implementation.
-
-## Seeds and parallel runs
-
-A chart of a whole product is deep: a member reaches a results screen after signing up,
-onboarding, paying and booking. Walking every path from the initial state repeats that prefix
-in every path, so a run gets slower the more of the product it covers. Seeds remove the prefix.
-
-A seed puts the system directly in one configuration of the chart, usually through an API or the
-database: create a member who has paid, sign them in, open the screen.
+```sh
+atlas serve                                          # the project's server, at :8080 (ATLAS_TOKEN says who may upload)
 
-```ts
-implementation: {
-  seeds: {
-    'Paid member': {
-      at: 'Paid',                               // a state name, or a full state value
-      how: 'Creates a paid member through the admin API and signs in.',
-      async run({ page, api }) {
-        const member = await api.createMember({ plan: 'paid' });
-        await page.goto(`/sign-in?token=${member.token}`);
-      }
-    }
-  },
-  events: { /* … */ },
-  states: { /* … */ }
-}
+export ATLAS_STORE=https://atlas.example.com ATLAS_TOKEN=…   # on every laptop and CI job
+atlas report publish --producer unit --junit out.xml --specs ./specs     # when a suite is done
+my-suite --json | atlas report stream --producer e2e --environment ios  # or as its checks finish
+atlas report status --branch main --ignore-modified  # the gate, answered by the server
 ```
 
-With seeds, the plan changes in three ways:
-
-- **Journeys are cut at seeded configurations.** A journey is replayed from the initial state, and
-  wherever it passes through a configuration a seed produces, it is cut. Each stretch becomes a path
-  that starts from that seed. A stretch that several journeys share becomes one path. The manifest's
-  `journeys` lists the paths each journey is made of. A journey passes when all of them pass, fails
-  when one fails, and is `not-reached` while any is blocked.
-- **Generated paths start from the nearest seed.** A breadth-first search from every start point at
-  once finds, for each uncovered transition, the shortest way to take it from any seed (or from
-  `setup`'s start). Ties go to the seed declared first.
-- **Redundant paths are dropped.** A generated path that is a prefix of another path from the same
-  start is not planned.
-
-The plan is deterministic. The same chart, journeys and seeds give the same paths, ids and keys
-(`key` hashes the start and the events) on every machine, so results can be composed:
-
-- **Workers.** `--workers n` (or `workers` in the config) runs n path attempts at once. Each attempt
-  gets its own driver context. The longest paths go first, timed by earlier runs.
-  - The driver's `concurrency` caps the worker count. Playwright and Bun contexts and HTTP clients
-    run side by side. A WebDriver session or a Detox device runs one at a time unless you raise it.
-  - The manifest is a pure fold of the path outcomes in plan order, so the same outcomes give the
-    same report whatever order they finished in.
-- **Shards.** `--shard i/n` runs one part of the plan, split by the plan alone, so every machine
-  agrees on the split. `atlas merge <run-dir>...` composes the shards into one run, with their media
-  copied in.
-- **Reruns.** `--rerun-failed` keeps the passed paths of the newest run, matched by key, and runs
-  the rest. The result is still one complete run.
-- **Areas.** `--seed <name>` (repeatable) runs only the paths that start from that seed (`start`
-  for paths `setup` starts). `--state <name>` scopes the run to one state of the chart. With these you can
-  run one area of the product on its own, then merge it into a full run.
-
-Seeds are what make the composition sound: a seed must leave the system exactly as the steps that
-lead there would. Atlas checks this both ways and reports it:
-- A seeded path must first recognise its start state.
-- The manifest's `seeds` lists, for each seed, the passed paths that reached the same states through
-  real steps (`verifiedBy`).
-
-A seed nobody reaches through the steps is a claim that has not been checked yet. In the
-visualizer, seeded states carry a "Seeded" tag.
-
-Business events and parallel runs: a shared source, such as a log file, sees every attempt's events.
-`EventSource.mark()` returns a position that `collect(mark)` reads from, so attempts don't consume
-each other's marks.
-- With `correlate(ctx)`, only events and log lines that mention one of the attempt's ids count.
-- Without it, a run on several workers reports business events as "no signal" rather than guessing.
-
-## Drivers
-
-| Driver | Package | Plays | Speed | Clips |
-| --- | --- | --- | --- | --- |
-| `functionDriver(create)` | `@crvouga/atlas` | A domain model, a CLI, anything reachable from code | Microseconds | No |
-| `httpDriver(baseUrl)` | `@crvouga/atlas` | An API client with a cookie jar: a partner system, an operator API, a back office job | Milliseconds | No |
-| `bunWebViewDriver()` | `@crvouga/atlas/bun` | A web app in Bun's built-in browser (WebKit on macOS, Chrome elsewhere) | A view in milliseconds, screenshots in about 10 ms | From screenshots |
-| `playwrightDriver()` | `@crvouga/atlas/playwright` | A web app (or React Native on the web) in Chromium, with a fake clock | About a second per context | Screencast with a touch overlay |
-| `webdriverDriver()` | `@crvouga/atlas/webdriver` | Safari, Chrome, Firefox, Edge; native iOS and Android apps through Appium | Depends on the server | From screenshots, or Appium's recorder |
-| `detoxDriver()` | `@crvouga/atlas/detox` | A React Native app, inside a Detox test run | Depends on the device | Detox artifacts |
-
-The Bun, Playwright, WebDriver and Detox contexts all provide a `SignalContext` (`goto`,
-`isVisible`, `user.tap`, `user.type`), and they resolve the same signals (`testId`, `role`, `label`,
-`text`, `css` from `@crvouga/atlas/signals`), each against its own UI tree: the DOM, or the
-accessibility tree of a native app, where a test ID is the accessibility identifier (React
-Native's `testID`). An implementation written
-against `SignalContext` with `screen` from `@crvouga/atlas/signals` runs on any of them unchanged.
-
-`bunWebViewDriver` needs the Bun runtime: run `bun --bun atlas run`. The `atlas` binary runs on
-Node (through tsx) or Bun, and Playwright works under Bun too, so one run can mix Bun's WebKit and
-Playwright's Chromium.
-
-## Several clients in one run
-
-Product flows cross devices: a member books on an iOS app, an operator approves in a web
-dashboard, a partner confirms over an API. `combineDrivers` runs several drivers as the named
-clients of one run, and `combineImplementations` merges what each client does and shows:
+**The viewer** shows each spec (Gherkin, Quint, DMN, Alloy, OpenSLO, and the rest by file type) with
+its combined result per environment and the layer behind it. See
+[integrating Atlas](docs/integrating.md#6-browse-it).
 
 ```ts
-import { combineDrivers, combineImplementations, defineConfig, httpDriver, type HttpClient } from '@crvouga/atlas';
-import { role, screen, text, type SignalContext } from '@crvouga/atlas/signals';
-import { playwrightDriver } from '@crvouga/atlas/playwright';
-import { accessibilityId, webdriverDriver } from '@crvouga/atlas/webdriver';
-
-type Clients = { member: SignalContext; operator: SignalContext; partner: HttpClient };
-
-export default defineConfig<Clients>({
-  specs: './specs',
-  driver: combineDrivers<Clients>(
-    {
-      member: webdriverDriver({
-        url: 'http://127.0.0.1:4723', // Appium
-        capabilities: { platformName: 'iOS', 'appium:automationName': 'XCUITest', 'appium:app': './build/App.app' }
-      }),
-      operator: playwrightDriver({ baseUrl: 'http://127.0.0.1:3000', device: { viewport: { width: 1280, height: 800 } } }),
-      partner: httpDriver('http://127.0.0.1:4000')
-    },
-    { screens: 'all' }
-  ),
-  implementation: combineImplementations<Clients>(
-    {
-      member: {
-        events: { 'Requests a visit': { kind: 'user', how: 'Taps "Request".', run: (m) => m.user.tap(role('button', 'Request'), 'Request') } },
-        states: { 'Visit confirmed': screen({ all: [text('Confirmed')] }) }
-      },
-      operator: {
-        setup: (o) => o.goto('/queue'),
-        events: { 'Operator approves': { kind: 'user', how: 'Approves it in the queue.', run: (o) => o.user.tap(role('button', 'Approve'), 'Approve') } },
-        states: { 'Waiting for approval': screen({ all: [role('row', 'New request')] }) }
-      },
-      partner: {
-        events: { 'Partner confirms': { kind: 'system', how: 'POSTs the confirmation webhook.', run: (p) => p.post('/webhooks/confirm', { ok: true }).then(() => undefined) } }
-      }
-    },
-    { setup: async ({ partner }) => void (await partner.post('/test/reset')) }
-  )
-});
-```
+import { combineBackends } from '@crvouga/atlas/reports/compose';
+import { directoryStore } from '@crvouga/atlas/reports/directory-store';
+import { reportStatus } from '@crvouga/atlas/reports/report-status';
 
-- Each client's part is written against that client's own context, so every driver's helpers
-  work unchanged; `shared` (the second argument) holds setup and events that need several clients
-  at once. `shared.setup` runs first, then each client's setup in order.
-- `onClient(name, impl)` lifts a single event or state implementation to a client.
-- An event's client is recorded for its clip; a state's client is the screen it is recognised and
-  photographed on. With `screens: 'all'`, every other client's screen is captured at the same
-  moment (`screenshot.also`).
-- Timeline entries, clips, states and transitions carry `client` in the manifest;
-  `run.environment.clients` names the driver each client ran on; a failed attempt keeps one trace
-  per client.
-- If one client cannot open (no simulator booted), the others are closed and the attempt fails
-  naming that client.
-
-[`examples/todo/clients`](examples/todo/clients) runs a chart (`specs/clients/shared-list.scxml`)
-across a phone, a desktop and the sync server; pick each device's driver with `ATLAS_PHONE` and
-`ATLAS_DESKTOP` (`playwright`, `bun` or `webdriver`).
-
-## Writing a driver
-
-A driver owns the thing under test for one path attempt: a browser context, a device, a model or
-an API client. Only `open` and `close` are required.
-
-```ts
-type Focus = { client?: string };
-
-type Driver<C> = {
-  name: string;
-  open(input: { path: PlannedPath; attempt: number; mode: RunMode; directory: string; timeline: Timeline }): Promise<C>;
-  close(ctx: C, input: { failed: boolean; traceFile: string }): Promise<{ trace?: string; traces?: Record<string, string> } | void>;
-  screenshot?(ctx: C, file: string, focus?: Focus): Promise<Image | null>;
-  record?(ctx: C, workDirectory: string, focus?: Focus): Promise<{ stop(output: string): Promise<Clip | null> }>;
-  text?(ctx: C, focus?: Focus): Promise<string>;
-  hold?(ctx: C, ms: number, focus?: Focus): Promise<void>;
-  pacing?: { before: number; after: number };
-  clients?: Record<string, string>;
-  concurrency?: number;
-  dispose?(): Promise<void>;
-};
+const report = await combineBackends([
+  { id: 'ci', store: directoryStore('all') },
+  { id: 'lab', label: 'Device lab', store: deviceLabStore() }
+]);
+const status = reportStatus(report, { requireEnvironments: ['ios'] });
+if (!status.ok) throw new Error(status.reasons.join('\n'));
 ```
 
-`focus` says which client a multi-client run is looking at; single-client drivers ignore it.
-A driver without a native screen recorder can encode clips from screenshots with
-`recordFrames(capture, workDirectory)`.
-
-- `open` returns a fresh context for each attempt; `close` may return the path of a trace file
-  (Playwright writes one for failed attempts).
-- `screenshot` and `record` produce media; `record` is used only in showcase mode, one clip per
-  transition.
-- `text` returns the visible text, for the privacy scan.
-- `concurrency` is how many contexts can be open at once (1 when omitted). Workers never exceed
-  it, so a driver of one device stays sequential while browser contexts run side by side.
-- `timeline.add({ kind, label, ... })` logs taps, typing, system calls and time jumps; they become
-  each clip's captions.
+## Open standards
 
-For anything you can reach from Node (a domain model, an API client, a CLI), `functionDriver(create)`
-is a complete driver:
+Atlas invents as little as it can. Everything it reads or writes is a format other tools already
+understand, or a JSON Schema it publishes.
 
-```ts
-import { functionDriver } from '@crvouga/atlas';
+| Standard | Used for |
+| --- | --- |
+| [JUnit XML](https://github.com/testmoapp/junitxml) | Read: any test runner's results become a layer. Written: `junit.xml`, one test case per statechart path. |
+| [CTRF](https://ctrf.io) | Read: any CTRF report becomes a layer. Written: `ctrf.json` for each statechart run. |
+| [JSON Schema 2020-12](https://json-schema.org/draft/2020-12) | The contract: layers, check files, report status, run manifests, journeys, state nodes, timelines and the runs index (`@crvouga/atlas/schemas/*.schema.json`) |
+| [Gherkin](https://cucumber.io/docs/gherkin/), [Quint](https://quint-lang.org), [DMN](https://www.omg.org/spec/DMN), [Alloy](https://alloytools.org), [OpenSLO](https://openslo.com) | Spec kinds the viewer lays results over, each in its own tab. Any other file is a spec of its own type. |
+| [W3C SCXML](https://www.w3.org/TR/scxml/) | Statecharts (`*.scxml`), with business metadata in an `atlas` XML namespace |
+| [XState v5](https://stately.ai/docs/machines) machine config | Statecharts (`*.machine.json`, `*.machine.yaml`): the JSON shape Stately Studio imports and exports |
+| [WebVTT](https://www.w3.org/TR/webvtt1/) | Captions for every clip: each tap, keystroke, system call and screen change |
+| [CloudEvents 1.0](https://cloudevents.io) | Business events the product emits (HTTP structured, binary and batch modes) |
+| [W3C WebDriver](https://www.w3.org/TR/webdriver2/) | Driving browsers and, through Appium, native iOS and Android apps |
+| [WAI-ARIA](https://www.w3.org/TR/wai-aria/) roles and accessible names | Signals that recognise screens the same way on every driver |
+| MP4 / H.264 | Clips of each transition, encoded with FFmpeg |
+| PNG / WebP | Screenshots at device resolution, with WebP thumbnails |
+| [Mermaid](https://mermaid.js.org/syntax/stateDiagram.html) `stateDiagram-v2` | `chart.mmd`, and `atlas export --format mermaid` |
 
-const driver = functionDriver(() => new TodoModel());
-```
+## Executable statecharts
 
-## CLI
+Atlas can also run a product's flows as statecharts against the real app. Write down how the product
+behaves as statecharts in open formats (W3C SCXML, XState v5 machine config), then let Atlas lint
+them, plan paths that cover every transition, run those paths through any driver (a browser, a
+phone, a plain function), and write a manifest of what happened, with screenshots, video clips,
+captions, business events and standard test reports.
 
 ```
-atlas lint   [--config atlas.config.ts | --specs <dir>] [--require-implementations]
-atlas plan   [--config atlas.config.ts] [--state <name>]
-atlas run    [--config atlas.config.ts] [--mode fast|showcase] [--workers n] [--state <name>]
-             [--seed <name>]... [--paths id,id] [--shard i/n] [--rerun-failed | --reuse <run-dir>]
-             [--no-retry] [--output <dir>]
-atlas merge  [--config atlas.config.ts] [--output <dir>] <run-dir> <run-dir>...
-atlas export --specs <dir> --format scxml|mermaid|markdown|json [--out <file>]
+specs/                     atlas lint      the charts are pure, reachable, free of silent dead ends,
+  app.scxml          ──▶                   and every journey replays
+  child.machine.yaml       atlas plan      curated journeys + shortest paths covering every transition
+  journeys.yaml            atlas run       each path against the product, through a driver
+                                  │
+                                  ▼
+                           atlas-runs/<run>/manifest.json, junit.xml, ctrf.json, chart.mmd, media/
 ```
 
-- `lint` with `--specs` checks charts and journeys alone; with a config it also lists missing
-  implementations, and `--require-implementations` makes them errors.
-- `plan` prints the seeds and each path with:
-  - its seed and step count;
-  - what blocks it;
-  - the paths each journey is made of;
-  - the total and longest path length, and how many transitions stay uncovered.
-- `run` exits non-zero when a path fails or the privacy scan finds something. `--paths` runs only
-  the given path ids; `--no-retry` skips the retry of failed paths.
-- `--workers`, `--shard`, `--seed`, `--state`, `--rerun-failed` and `--reuse` are described in
-  [Seeds and parallel runs](#seeds-and-parallel-runs).
-- `merge` composes runs of the same plan (shards, or a rerun and its earlier run) into one run.
-- `export` writes the composed product (every child inlined) as SCXML, Mermaid, Markdown or
-  XState JSON. The Markdown is a readable map for the people who own the product: one section per
-  area (each parallel region apart), every state with its description and what the user sees (a
-  `snapshot` written as an identifier is left out), a table of every event that can happen there
-  and where it leads, then the named journeys.
-
-The config file is TypeScript (loaded with `tsx`) and defaults to `atlas.config.ts` in the current
-directory. Relative paths in it resolve against the config file's directory.
-
-## Config reference
-
-`defineConfig<C>(config)` returns the config unchanged, typed for the driver's context `C`.
-
-| Field | Meaning |
-| --- | --- |
-| `specs` | The specs directory. |
-| `driver` | A `Driver<C>`, or a function returning one (called once per run). |
-| `implementation` | `{ events, states, seeds?, setup?, canStart?, correlate? }`. |
-| `chart` | Run one chart of the product; the root chart when omitted. |
-| `start`, `startLabel` | Where generated paths start (an XState state value) and how to describe it; the initial state when omitted. |
-| `entryEvents` | When running one chart or one state: the only events that enter it from outside. |
-| `state` | Run one state of a chart and what is inside it, with the transitions into and out of it: one area of a chart that models the whole product. |
-| `workers` | Path attempts that run at once, capped by the driver's `concurrency`; one per CPU when omitted. |
-| `beforeRun` | Runs once before any path: prepare what every seed relies on (reference data, configuration). |
-| `output` | Where runs are written; `atlas-runs` beside the config. |
-| `eventSources` | `() => EventSource[]`: where business events come from. |
-| `eventMatchers` | How each business event name is recognised: `{ type }`, `{ pattern }` or a function. |
-| `privacy` | Extra `deny` patterns, `allowEmails` and `allowHosts`. |
-| `targets` | URLs the run reaches, checked against `privacy.allowHosts` before anything runs. |
-| `environment` | Recorded in the manifest. |
-| `stepTimeoutMs` | How long to wait for a state to show up (default 45 000). |
-| `requiredMeta` | `meta` fields every state needs (default `['description']`). |
-
-The programmatic API mirrors the CLI: `prepare(config)` loads, lints and plans; `runConfig(config,
-options)` runs; `loadSpecDirectory`, `lintBundle`, `chartScope`, `planChart` and `runPaths` are the
-steps underneath.
-
-## How a run works
-
-1. **Plan.** Curated journeys come first.
-   - When running one chart of a larger product, each journey is cut to its stretch inside the
-     chart, starting at an entry transition.
-   - With seeds, journeys are also cut wherever they pass through a seeded configuration.
-   - Then, for each transition still uncovered, the plan adds the shortest path that takes it from
-     the nearest seed or start. The search is breadth-first, so loops stay bounded.
-   - Paths stop before blocked events. A blocked path whose runnable part other paths already cover
-     is reported but not run.
-2. **Run each path.** Paths run on a pool of workers, longest first. Each gets a fresh driver
-   context, then every event's `prepare`, then its seed's `run` (or `setup`). The start state must
-   be recognised. Then for each step: run the event, wait for the target state, run its checks,
-   collect business events, screenshot, `settle`.
-3. **Retry.** A failed path runs once more. Passing the second time makes it `flaky`.
-4. **Write.** The manifest and reports are rewritten each time a path finishes, from every outcome
-   so far in plan order, so a crash keeps what ran. `outcomes.json` keeps the raw outcomes, for
-   `atlas merge` and `--rerun-failed`.
-
-Every path, state and transition ends as `passed`, `failed`, `flaky` or `not-reached`. Reaching a
-state also reaches its ancestors. A failure records the recogniser's signals and which known states
-the screen looked like instead.
-
-### Run modes
-
-| Mode | Pacing | Media |
-| --- | --- | --- |
-| `fast` | None | Screenshots of every state (when the driver takes them) |
-| `showcase` | Holds before and after each step; taps glide and type at human speed | Screenshots, plus an H.264 clip of every transition with a poster and WebVTT captions |
-
-## Manifest and reports
-
-Each run writes `<output>/<timestamp>-<mode>/`:
-
-| File | Contents |
-| --- | --- |
-| `manifest.json` | The run (commit, branch, environment, mode, spec version, scope), every chart, the composed map (nodes and edges), every state and transition with status, media, timeline and reasons, every path with its attempts, coverage and privacy results. Schema: `packages/schema/schemas/manifest.schema.json`. |
-| `junit.xml` | One test case per path: failures, skips (with the blocking reason) and flaky passes. |
-| `ctrf.json` | The same as CTRF. |
-| `chart.mmd` | The composed chart as a Mermaid state diagram. |
-| `outcomes.json` | Each path's raw outcome by path key, which the manifest is folded from: for merging shards and reusing passed paths. |
-| `media/paths/<path>/NN.png`, `.webp` | Screenshots of each state a path reached; `failed-NN.png` where it failed. |
-| `media/clips/<path>/NN.mp4`, `.poster.webp`, `.vtt` | Showcase clips of each transition, with captions. |
-| `media/traces/<path>.zip` | Driver traces of failed attempts (Playwright traces with the Playwright driver). |
-
-## Business events
-
-States list the business events that happen on entering them in `meta.events`. An `EventSource`
-says what actually happened. `mark()` returns a position before each event, and `collect(mark)`
-returns what arrived after it, once the state is recognised:
-
-- `cloudEventsHttpSource()` starts an HTTP endpoint that accepts CloudEvents in structured, binary
-  or batch mode. Point the product's event bus, webhook relay or collector at its `url`.
-- `logFileSource(file)` collects lines appended to a log, for products whose only event stream is a
-  log; match them with `{ pattern }`.
-- Any object with `name`, `mark` and `collect` works, such as an in-memory bus in a unit test.
-
-With no matcher, a business event is observed when a CloudEvent's `type` equals its name. Events
-with neither a matcher nor a CloudEvents source are reported as "no signal", never as missing.
-
-## Privacy
-
-Runs produce media and manifests that get shared, so Atlas refuses to leak real data:
-
-- Before running, every `targets` URL must be on `allowHosts` (loopback only by default).
-- After every step, the driver's visible text is scanned, and the manifest is scanned before it is
-  written. By default it flags email addresses outside `example.com`/`.org`/`.net` and the `.test`,
-  `.example`, `.invalid`, `.localhost` and `.local` domains, anything shaped like a US Social Security
-  number, and card numbers other than the well-known test cards. Findings describe the match without
-  repeating it.
-- Any finding fails the run. Add `deny` patterns and `allowEmails` in `privacy`.
-
-## Visualizer
-
-The [`atlas-visualizer`](packages/visualizer) command renders the charts from the specs directory and
-overlays runs from the runs directory: screenshots on states, clips on transitions, statuses and
-history. See its README for how to point it at a project.
-
-Its open index lists every place, journey and spec beside one plate. Connect multiple local
-directories, HTTP report stores and streaming
-APIs using [report backends](docs/report-backends.md). The runner publishes reached screens
-and completed steps while paths are still running.
+Each run publishes as a layer (`atlas report publish --manifest <run>/manifest.json`), so it combines
+with every other suite's evidence. Shards, seeds, several clients in one run, drivers (Playwright,
+Bun WebView, WebDriver and Appium, Detox, plain functions), business events and the privacy scan are
+in **[Executable statecharts](docs/statecharts.md)**, which starts with a runnable example,
+[`examples/todo`](https://github.com/crvouga/atlas/tree/main/examples/todo).
 
 ## License