@lovrozagar/oat 0.5.0 → 0.6.1

package/README.md

@@ -86,15 +86,15 @@ oat help          # same as oat --help
 oat --help
 ```
 
-Unknown commands and missing required flags exit `2`.
+Unknown commands, unknown flags, and missing required flags exit `2`.
 
 ## How a run works
 
 1. **Load** the OpenAPI document (URL or path). Internal `$ref`s are inlined. External `$ref`s are reported, never fetched.
 2. **Model** entities by inverting `x-invalidate` (or path heuristics) into a read surface per entity.
-3. **Authenticate** every configured principal (static headers and/or an auth flow). Credentials refresh themselves before they expire.
+3. **Authenticate** every configured principal (static headers and/or an auth flow). Credentials refresh on a countdown from `exp` (default 30s buffer) before every dispatch and each async poll.
 4. **Seed** a cohort of records per entity, in parent-before-child order, using each entity's create operation.
-5. **Test** the matrix, one entity at a time: foundations first, then composition, writes, isolation, declared effects. Checks inside an entity stay ordered. Entities may run in parallel (`concurrency`).
+5. **Test** the matrix, one entity at a time: foundations first, then composition, writes, isolation, declared effects. Entities run in series. Checks inside an entity stay ordered.
 6. **Teardown** everything the run created, unless `--keep-fixtures` / `keepFixtures: true`.
 
 The first principal is the writer. Isolation needs a second principal with different `roots`. A rank lattice needs two or more principals that share `roots` and differ in `rank`. Invite checks need `x-invite` plus a peer with `inviteAs`.
@@ -188,7 +188,6 @@ Same object. `${NAME}` is interpolated after load. There is no `defineConfig` wr
 	],
 	"seed": 42,
 	"cohortSize": 7,
-	"concurrency": 1,
 	"outDir": "./oat-out"
 }
 ```
@@ -254,24 +253,23 @@ oat help
 
 Requires `--config`. CLI flags override the same field in the config when both are set.
 
-| flag              | default                        | meaning                                                                                                                                      |
-| ----------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--config`        | required                       | module or JSON file, default export                                                                                                          |
-| `--base-url`      | `config.baseUrl`               | backend origin                                                                                                                               |
-| `--only`          | `config.only` or all entities  | comma-separated entity names as `oat plan` prints them (singularised)                                                                        |
-| `--seed`          | `config.seed` or `1`           | fixture generation seed (reproducible)                                                                                                       |
-| `--out`           | `config.outDir` or `./oat-out` | report directory                                                                                                                             |
-| `--concurrency`   | `config.concurrency` or `1`    | entities in parallel. Use `1` on nested graphs; higher values insert children while a parent page-walk is running and invent pagination bugs |
-| `--max-in-flight` | `config.maxInFlight` or `4`    | HTTP requests allowed at once                                                                                                                |
-| `--keep-fixtures` | `config.keepFixtures` or false | do not DELETE what the run created                                                                                                           |
-| `--quiet`         | false                          | no stderr progress; files under `--out` still update                                                                                         |
+| flag              | default                        | meaning                                                               |
+| ----------------- | ------------------------------ | --------------------------------------------------------------------- |
+| `--config`        | required                       | module or JSON file, default export                                   |
+| `--base-url`      | `config.baseUrl`               | backend origin                                                        |
+| `--only`          | `config.only` or all entities  | comma-separated entity names as `oat plan` prints them (singularised) |
+| `--seed`          | `config.seed` or `1`           | fixture generation seed (reproducible)                                |
+| `--out`           | `config.outDir` or `./oat-out` | report directory                                                      |
+| `--max-in-flight` | `config.maxInFlight` or `4`    | HTTP requests allowed at once                                         |
+| `--keep-fixtures` | `config.keepFixtures` or false | do not DELETE what the run created                                    |
+| `--quiet`         | false                          | no stderr progress; files under `--out` still update                  |
 
-**Exit codes:** `0` no defects, `1` at least one root-cause finding (`BACKEND_BUG`, `SPEC_BUG`, `SECURITY`, `AMBIGUITY`), `2` usage error (missing `--config`, no principals). `COVERAGE_GAP` and `BLOCKED` do not fail the process.
+**Exit codes:** `0` no defects, `1` at least one root-cause finding (`BACKEND_BUG`, `SPEC_BUG`, `SECURITY`, `AMBIGUITY`), `2` usage error (missing `--config`, no principals, unknown flag). `COVERAGE_GAP` and `BLOCKED` do not fail the process.
 
 Example:
 
 ```bash
-oat run --config oat.config.ts --only store,product --concurrency 1 --out oat-out/prod
+oat run --config oat.config.ts --only store,product --out oat-out/prod
 ```
 
 `--only store,product` matches the **entity names** from `oat plan`, not path segments. `/v1/stores` is usually the entity `store`. If a name is unknown, that entity is simply not tested (the others still run).
@@ -431,7 +429,6 @@ export default defineConfig({
 	roots: { org_id: "org_shared" }, // path params oat cannot create; also declarable via x-root
 	seed: 42, // fixture generation; a failing run with the same seed is identical
 	cohortSize: 12, // records created per entity (default 7)
-	concurrency: 1, // entities in parallel
 	maxInFlight: 4, // HTTP in flight
 	only: ["store", "product"], // restrict entities
 	keepFixtures: false,
@@ -450,7 +447,6 @@ export default defineConfig({
 | `roots`         | no       | `{}`        | Shared path params (merged with each principal's `roots`)          |
 | `seed`          | no       | `1`         | Integer. Same seed → same fixture bodies                           |
 | `cohortSize`    | no       | `7`         | Sliced from the 7 built-in variants. Larger repeats the pattern    |
-| `concurrency`   | no       | `1`         | Entity-level only. Checks inside one entity stay ordered           |
 | `maxInFlight`   | no       | `4`         | Across the whole run                                               |
 | `only`          | no       | all         | Entity names from `oat plan`                                       |
 | `keepFixtures`  | no       | `false`     | Skip DELETE at the end                                             |
@@ -458,7 +454,7 @@ export default defineConfig({
 
 `spec` may be a path relative to `baseUrl` (`/v1/openapi/spec`) or an absolute URL or a file.
 
-CLI `--base-url`, `--only`, `--seed`, `--out`, `--concurrency`, `--max-in-flight`, `--keep-fixtures` override these when passed.
+CLI `--base-url`, `--only`, `--seed`, `--out`, `--max-in-flight`, `--keep-fixtures` override these when passed.
 
 ### Spec loading
 
@@ -540,16 +536,33 @@ principals: [
 
 ```ts
 auth: {
-  steps: [ /* at least one */ ],
+  steps: [ /* register / verify — first acquire only */ ],
   credentialFrom: "$.access_token", // JSON path in the last (or saved) response
   expiresInFrom: "$.expires_in",    // lifetime in seconds
   header: "authorization",          // default
   template: "Bearer {credential}",  // default
   assumeTtlMs: 3600000,             // used only if neither expiresInFrom nor JWT exp is present
+  refreshBufferMs: 30_000,          // optional; default 30s. Proactive when expiresAt - now <= this
+  refresh: {                        // signup flows must set this — re-running steps is not a refresh
+    steps: [
+      {
+        operationId: "auth.refreshToken",
+        body: { refresh_token: "{refreshToken}" },
+        saveAs: {
+          credential: "$.access_token",
+          refreshToken: "$.refresh_token",
+        },
+      },
+    ],
+  },
 }
 ```
 
-Expiry is `expiresInFrom` (seconds) → JWT `exp` claim → `assumeTtlMs`. Refresh happens before dispatch, at roughly three quarters of the assumed window (`assumeTtlMs` default 300000 ms when used as the window), never by retrying a 401.
+Expiry is `expiresInFrom` (seconds) → JWT `exp` claim → `assumeTtlMs`. `assumeTtlMs` is only the fallback lifetime when nothing else revealed expiry — it is not used for the refresh threshold when `expiresAt` is known.
+
+Refresh is countdown-based (`expiresAt - refreshBufferMs`, default 30s) before every dispatch and before each async poll. Signup flows declare `auth.refresh` (refresh-token operation). Re-running `steps` is only the fallback when `refresh` is omitted (API-key / token-exchange principals). A register-like first hop without `refresh` fails closed (`AUTH_REFRESH_REQUIRED`) rather than signing up again.
+
+One 401 → force refresh + single retry with live headers. A second 401 is evidence. 5xx / 429 are never a refresh trigger. `expiresAt === null` (static-header principal) never proactive-refreshes.
 
 Each step is one of:
 
@@ -561,7 +574,7 @@ Each step is one of:
   body: { key: "${API_KEY}" },
   headers: { "x-extra": "1" },
   query: { realm: "test" },
-  saveAs: { token: "$.access_token" },
+  saveAs: { credential: "$.access_token", refreshToken: "$.refresh_token" },
   saveClaimsFrom: { token: "$.access_token", bind: { orgId: "orgs.0.oid" } },
   bind: { address: "user@example.test" }, // literals, with {name} interpolation
   expect: [200],                            // default: any 2xx
@@ -585,7 +598,7 @@ Each step is one of:
 { outOfBand: { address: "{address}", kind: "email-verify", as: "verifyToken" } }
 ```
 
-Later steps interpolate `{name}` from the flow scope. `saveAs` paths are `$.foo.bar` / `$.orgs.0.id` (dot + numeric index only; no JSON Pointer, no filters). `saveClaimsFrom` reads a JWT's _claims_ (signature is not verified — oat is reading its own credential). `rootsFromFlow` maps path parameter names to those bound keys.
+Later steps interpolate `{name}` from the flow scope. `saveAs` paths are `$.foo.bar` / `$.orgs.0.id` (dot + numeric index only; no JSON Pointer, no filters). Bind `saveAs.refreshToken` from `$.refresh_token` so `{refreshToken}` interpolates in `auth.refresh`. `saveClaimsFrom` reads a JWT's _claims_ (signature is not verified — oat is reading its own credential). `rootsFromFlow` maps path parameter names to those bound keys.
 
 `bind` on a step runs **before** the request. `saveAs` / `saveClaimsFrom` run **after**. `credentialFrom` is read from the last HTTP response unless a step already saved `credential`.
 
@@ -598,6 +611,16 @@ function signUp(email: string): AuthFlow {
 	return {
 		credentialFrom: "$.access_token",
 		expiresInFrom: "$.access_token_expires_in",
+		refresh: {
+			steps: [
+				{
+					body: { refresh_token: "{refreshToken}" },
+					method: "POST",
+					path: "/v1/auth/refresh",
+					saveAs: { credential: "$.access_token", refreshToken: "$.refresh_token" },
+				},
+			],
+		},
 		steps: [
 			{
 				bind: { address: email },
@@ -610,6 +633,7 @@ function signUp(email: string): AuthFlow {
 				body: { token: "{verifyToken}" },
 				method: "POST",
 				path: "/v1/auth/email/verify",
+				saveAs: { credential: "$.access_token", refreshToken: "$.refresh_token" },
 				saveClaimsFrom: {
 					token: "$.access_token",
 					bind: { orgId: "orgs.0.oid", projectId: "orgs.0.pids.0" },
@@ -783,7 +807,7 @@ Numbers use the ladder `1, 2, 5, 10, 20, 50, 100` so **lexical order ≠ numeric
 
 Empty schemas (`{}`, `true`, `additionalProperties: {}`) and cyclic `$ref`s after inlining stop the walk — they become a scalar or `{}`, never another object descent. A `RangeError` during generation is a `COVERAGE_GAP` on that entity naming the operationId and JSON pointer (`fixture generation overflow on table.create (/)`), not `blocked by unknown`.
 
-String fields honour `format` and `pattern`: `email` → `oat-{variant}-{index}@example.test`, `uri` / `url` → `https://example.test/...`, `uuid` → a fixed-shape UUID, `pattern` → a string that matches (or the field is omitted / the entity is a gap). `"Quarterly Report N"` is only used when the document does not constrain the string.
+String fields honour `format`, `pattern`, and `minLength` together: `email` → `oat-{variant}-{index}@example.test`, `uri` / `url` → `https://example.test/...`, `uuid` → a fixed-shape UUID, `pattern` → a string that matches (or the field is omitted / the entity is a gap). A generated string is padded to `minLength` (repeat the last character) without breaking `pattern`. `"Quarterly Report N"` is only used when the document does not constrain the string. `minLength` greater than `maxLength` omits an optional field and records `missingRequired` on a required one.
 
 An operation with `x-invite` is not `entity.create`. oat does not POST a generated invitee. The invite check sends `granteeField` = the peer's `inviteAs`. Missing `inviteAs` is a coverage gap naming the tag.
 
@@ -870,7 +894,7 @@ Collection shape is derived from the success JSON schema, not from hardcoded wra
 | page       | `page`, `pageNumber`, `page_number`, `offset`               |
 | limit      | `limit`, `perPage`, `per_page`, `pageSize`, `page_size`     |
 
-Success schema is the first JSON media type on responses `200`, `201`, `202`, `2XX`, or `default`. Request schema is taken from `requestBody` preferring `multipart/form-data`, then `application/x-www-form-urlencoded`, then JSON. A raw `text/event-stream` body is not treated as a JSON schema defect.
+Success schema is the first JSON media type on responses `200`, `201`, `202`, `2XX`, or `default`. Request schema is taken from `requestBody` preferring `multipart/form-data`, then `application/x-www-form-urlencoded`, then JSON. A success response that lists `text/event-stream` is a stream: oat consumes it to the end and does not treat the raw body as a JSON schema defect. Media type is the stream tag — there is no `x-stream`.
 
 ## OpenAPI meta tags
 
@@ -949,6 +973,8 @@ An invite operation is **not** the entity's fixture create, even when it is `POS
 
 Timeline asserted: cannot read → invite → still cannot → accept → can → revoke → cannot.
 
+Accept and revoke send the documented JSON request body when the operation declares one, filled from the invite token / grant id (and other known scope values). A path-only accept (`POST /invites/{token}` with no body) stays path-only — oat does not invent a body.
+
 **Fallback:** the check does not run.
 
 ### `x-query`
@@ -983,11 +1009,17 @@ x-async:
   pollIntervalMs: 2000
 ```
 
-The HTTP response is a receipt. oat polls until `until` matches, then treats that payload as the result. `poll` may be an operationId or `"GET /path/{id}"`. Defaults: `timeoutMs: 120000`, `pollIntervalMs: 2000`.
+`x-async` means **POST is a receipt, then poll**. It is not how you mark a stream. A stream is a success response that lists `text/event-stream`.
+
+When the start response is JSON, oat polls `poll` until `until` matches, then treats that payload as the result. `poll` may be an operationId or `"GET /path/{id}"`. Defaults: `timeoutMs: 120000`, `pollIntervalMs: 2000`.
+
+When the start response is `text/event-stream`, oat parses `event:` / `data:` frames. `data` is JSON when it starts with `{` / `[`. `idFrom` is resolved against **each event's JSON `data`**, first hit wins — `$.batch_id` on `event: batch` data `{ "batch_id": "…" }` works. A frame named `complete` / `error`, or one whose `data` matches `until`, is the terminal record; `successWhen` is applied to it and oat does **not** GET the poll route. Poll only if the stream ended without a terminal frame **and** `idFrom` resolved.
+
+A spec may leave both `x-async` and `text/event-stream` on the same operation. The stream is still the result; `x-async` only supplies `idFrom` / `until` / the poll fallback.
 
 `until` / `successWhen` use the same `field.op.value` predicates as filters (`eq`, `in`, …).
 
-**Fallback:** treated as synchronous; async checks are `COVERAGE_GAP`.
+**Fallback:** treated as synchronous; async checks are `COVERAGE_GAP`. A 2xx stream without `x-async` is consumed and recorded; async checks do not run.
 
 ### `x-effects`
 
@@ -1211,8 +1243,8 @@ Order is fixed (foundations first) so cascade suppression has a cause to point a
 | `softdelete.absent-from-default-list`      | a soft-deleted row is gone from the default list                                     | `x-soft-delete`                                                      | `list.read-after-write`                 |
 | `invalidation.declared-route-changes`      | after a write, the other entity's listed route actually changes                      | `x-invalidate` naming another entity                                 | list, persist                           |
 | `effects.declared-effect-occurs`           | `x-effects` cardinality delta is observed on the named list                          | `x-effects`                                                          | `list.read-after-write`                 |
-| `async.reaches-terminal-state`             | polling `x-async` reaches `until` before `timeoutMs`                                 | `x-async`                                                            | —                                       |
-| `async.receipt-identifies-the-job`         | `idFrom` on the receipt resolves to a pollable job                                   | `x-async` + `idFrom`                                                 | —                                       |
+| `async.reaches-terminal-state`             | `x-async` reaches `until` (poll, or a terminal SSE frame) before `timeoutMs`         | `x-async`                                                            | —                                       |
+| `async.receipt-identifies-the-job`         | `idFrom` on the receipt (JSON object or SSE event JSON) resolves to a pollable job   | `x-async` + `idFrom`                                                 | —                                       |
 | `patch.minimality`                         | PATCH `{ name }` does not clear other writable fields                                | update + item route                                                  | —                                       |
 | `idempotency.replay-does-not-duplicate`    | same Idempotency-Key + same body does not create a second row                        | create + documented Idempotency-Key header                           | list, persist                           |
 | `delete.absent-record-returns-404`         | DELETE of a missing id is 404, not 200                                               | delete                                                               | —                                       |
@@ -1471,7 +1503,6 @@ const result = await run({
 	baseUrl: config.baseUrl,
 	principals: config.principals,
 	seed: 1,
-	concurrency: 1,
 	maxInFlight: 4,
 	onProgress: (snap) => {
 		// snap.phase, snap.entity, snap.check, snap.message, …
@@ -1494,7 +1525,7 @@ const { doc: resolved, externalRefs } = dereference(doc)
 const model = buildModel(resolved)
 ```
 
-Types exported: `OatConfig`, `Principal`, `AuthFlow`, `AuthStep`, `Hooks`, `Uploads`, `UploadRequest`, `UploadFile`, `RunOptions`, `RunResult`, `Finding`, `Verdict`, `Actor`, `SpecModel`, `EntityModel`, `OperationModel`, `OpenApiDocument`, matrix types.
+Types exported: `OatConfig`, `Principal`, `AuthFlow`, `AuthRefresh`, `AuthStep`, `Hooks`, `Uploads`, `UploadRequest`, `UploadFile`, `RunOptions`, `RunResult`, `Finding`, `Verdict`, `Actor`, `SpecModel`, `EntityModel`, `OperationModel`, `OpenApiDocument`, `AuthRefreshRequiredError`, matrix types.
 
 ## CI
 
@@ -1508,7 +1539,7 @@ Against **your** API:
 # GitHub Actions sketch
 - run: npm i -D @lovrozagar/oat
 - run: oat doctor --spec "$SPEC_URL"
-- run: oat run --config oat.config.ts --concurrency 1
+- run: oat run --config oat.config.ts
   env:
     API_TOKEN: ${{ secrets.API_TOKEN }}
     API_TOKEN_B: ${{ secrets.API_TOKEN_B }}
@@ -1516,8 +1547,6 @@ Against **your** API:
 
 Gate on exit code 1 (defects). Read `oat-out/oat-report.json` if you need to classify verdicts.
 
-Nested APIs: keep `--concurrency 1`. Higher values create children while a parent page-walk is in flight and produce false `pagination.page-walk-covers-set` findings.
-
 Wipe leftover rows on a shared database between runs if a previous `--keep-fixtures` or a crashed teardown left data. Leftover rows make numeric/filter checks look like type bugs (`1, 10, 2` from old TEXT-sorted leftovers mixed with a fresh numeric cohort).
 
 ## Reference defects (`oat serve --defects`)
@@ -1599,7 +1628,7 @@ oat run --config labs/local.config.ts --base-url <url>
 These are deliberate. An agent should not invent a flag for them.
 
 - **No request timeout.** `fetch` waits until the server answers. Watch `idle_ms`.
-- **No retry on 5xx / 429 / 401.** A 401 mid-run is evidence, not a refresh trigger. Refresh is expiry-based only.
+- **No retry on 5xx / 429.** One 401 → force refresh + single retry. A second 401 is evidence.
 - **No OpenAPI `security`.** Put credentials in `principals`. Cookie auth is a `headers: { cookie: "…" }` (or a flow that sets that header).
 - **No `servers[]`.** Always set `baseUrl`.
 - **No OCR.** Multipart and file parts are sent as dummy / pool / `resolveUpload` bytes. oat checks HTTP status and JSON responses, not whether a PDF is a real invoice.
@@ -1609,7 +1638,6 @@ These are deliberate. An agent should not invent a flag for them.
 - **Rate-limit pacing only covers requests oat itself sends.** It cannot see traffic from anything else hitting the backend at the same time, so a shared budget can still trip even when oat's own share was within the declared rate.
 - **Equality filter grammar** cannot express `neq` / `gt` / `like` / `and` / `or`. Those checks did-not-apply, they do not fail.
 - **`or()` is postgrest-only.**
-- **Concurrency > 1 on nested graphs invents pagination bugs.** Use `1`.
 - **Leftover rows on a shared DB** poison numeric and filter checks. Wipe between runs.
 - **`--only` uses plan names** (`store`, not `stores` or `/v1/stores`).
 - **Default cohort is 7.** `pagination.limit-respects-documented-max` needs `cohortSize > maxLimit`.

package/bin/oat.js

@@ -1,2 +1,4 @@
 #!/usr/bin/env node
-import "../dist/cli.js"
+import { start } from "../dist/cli.js"
+
+start()

package/dist/cli.js

@@ -2,6 +2,7 @@
 import { createWriteStream, writeFileSync } from "node:fs";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
 import { interpolate, loadConfig } from "./config/load.js";
 import { report } from "./report/console.js";
 import { renderMatrixGraph, renderMatrixHtml } from "./report/matrix.js";
@@ -10,7 +11,28 @@ import { createStderrProgress, formatProgressJsonl, formatProgressLine, formatPr
 import { renderTeardown } from "./runtime/teardown.js";
 import { buildModel } from "./spec/graph.js";
 import { dereference, loadSpec } from "./spec/load.js";
-function parseArgs(argv) {
+export const KNOWN_FLAGS = new Set([
+    "help",
+    "config",
+    "spec",
+    "base-url",
+    "only",
+    "profile",
+    "seed",
+    "out",
+    "keep-fixtures",
+    "max-in-flight",
+    "quiet",
+    "untagged",
+    "backend",
+    "dialect",
+    "fuzz",
+    "precision",
+    "max-defects",
+    "json",
+    "parser",
+]);
+export function parseArgs(argv) {
     const [command = "help", ...rest] = argv;
     const flags = {};
     for (let i = 0; i < rest.length; i++) {
@@ -29,7 +51,14 @@ function parseArgs(argv) {
     }
     return { command, flags };
 }
-const USAGE = `oat — OpenAPI Tester
+export function unknownFlag(flags) {
+    for (const key of Object.keys(flags)) {
+        if (!KNOWN_FLAGS.has(key))
+            return key;
+    }
+    return undefined;
+}
+export const USAGE = `oat — OpenAPI Tester
 
   oat run     --config <file>              test a live backend and write a report
   oat plan    --spec <url|file>            derive and print the test model (offline)
@@ -46,7 +75,6 @@ Flags
   --seed       integer seed for fixture generation (default 1)
   --out        output directory for the report (default ./oat-out)
   --keep-fixtures  leave created records in place instead of tearing them down
-  --concurrency    entities tested in parallel (default 1)
   --max-in-flight  requests allowed in flight at once (default 4)
   --quiet          no live progress on stderr (progress.log still written)
   --untagged       serve (or test) a document with every x-* tag stripped
@@ -139,7 +167,6 @@ async function commandRun(flags) {
             ...(config.profiles === undefined ? {} : { profiles: config.profiles }),
             ...(config.rateLimits === undefined ? {} : { rateLimits: config.rateLimits }),
             keepFixtures: flags["keep-fixtures"] === true || config.keepFixtures === true,
-            concurrency: Number.parseInt(str(flags, "concurrency") ?? "", 10) || config.concurrency || 1,
             maxInFlight: Number.parseInt(str(flags, "max-in-flight") ?? "", 10) || config.maxInFlight || 4,
             seed: seedFlag === undefined ? (config.seed ?? 1) : Number.parseInt(seedFlag, 10),
             onProgress,
@@ -195,8 +222,13 @@ async function commandRun(flags) {
      * not failures, and a CI gate should react to defects only. */
     return result.findings.filter((f) => f.verdict !== "COVERAGE_GAP" && f.verdict !== "BLOCKED").length > 0 ? 1 : 0;
 }
-async function main() {
+export async function main() {
     const { command, flags } = parseArgs(process.argv.slice(2));
+    const unknown = unknownFlag(flags);
+    if (unknown !== undefined) {
+        process.stderr.write(`oat: unknown flag "--${unknown}"\n\n${USAGE}`);
+        return 2;
+    }
     if (command === "help" || flags.help === true) {
         process.stdout.write(USAGE);
         return 0;
@@ -403,10 +435,17 @@ async function main() {
             return 2;
     }
 }
-main().then((code) => {
-    process.exitCode = code;
-}, (error) => {
-    process.stderr.write(`oat: ${error instanceof Error ? error.message : String(error)}\n`);
-    process.exitCode = 1;
-});
+export function start() {
+    main().then((code) => {
+        process.exitCode = code;
+    }, (error) => {
+        process.stderr.write(`oat: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+    });
+}
+/* `node dist/cli.js …` is the test/CI entry. `bin/oat.js` calls start() itself because
+ * argv[1] is the bin wrapper, not this module. */
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+    start();
+}
 //# sourceMappingURL=cli.js.map

package/dist/config/define-config.d.ts

@@ -56,8 +56,13 @@ export interface OutOfBandStep {
     };
 }
 export type AuthStep = OperationStep | RequestStep | OutOfBandStep;
+/** How to renew a credential without re-running the acquire chain. */
+export interface AuthRefresh {
+    /** Run against the existing scope so `{refreshToken}` interpolates. */
+    steps: [AuthStep, ...AuthStep[]];
+}
 export interface AuthFlow {
-    /** Run in order; values flow forward through the scope. */
+    /** Run in order; values flow forward through the scope. First acquire only. */
     steps: [AuthStep, ...AuthStep[]];
     /** Where the credential is in the final response, e.g. `$.access_token`. */
     credentialFrom: string;
@@ -69,6 +74,17 @@ export interface AuthFlow {
     template?: string;
     /** Used only when neither the response nor the credential reveals an expiry. */
     assumeTtlMs?: number;
+    /**
+     * Proactive refresh fires when `expiresAt - now <= refreshBufferMs`.
+     * Defaults to 30_000. Ignored when `expiresAt` is null (static-header principal).
+     */
+    refreshBufferMs?: number;
+    /**
+     * Renew via these steps (typically `auth.refreshToken` + `{refreshToken}`).
+     * Signup flows must set this — re-running `steps` would register again.
+     * Omitted: re-run `steps` (API-key / token-exchange). Register-like first hops fail closed.
+     */
+    refresh?: AuthRefresh;
 }
 export interface Principal {
     id: string;
@@ -213,8 +229,6 @@ export interface OatConfig {
     seed?: number;
     /** Instances seeded per entity. Larger cohorts discriminate more, and cost more. */
     cohortSize?: number;
-    /** Entities tested in parallel. Checks within one entity always stay ordered. */
-    concurrency?: number;
     /** Requests allowed in flight at once. Past a server's comfort this makes runs slower. */
     maxInFlight?: number;
     /** Restrict the run to these entity names. */

package/dist/config/define-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define-config.d.ts","sourceRoot":"","sources":["../../src/config/define-config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"define-config.d.ts","sourceRoot":"","sources":["../../src/config/define-config.ts"],"names":[],"mappings":"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"}

package/dist/config/define-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"define-config.js","sourceRoot":"","sources":["../../src/config/define-config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA6PH;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,MAAiB;IAC7C,OAAO,MAAM,CAAA;AACd,CAAC"}
+{"version":3,"file":"define-config.js","sourceRoot":"","sources":["../../src/config/define-config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA4QH;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,MAAiB;IAC7C,OAAO,MAAM,CAAA;AACd,CAAC"}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { defineConfig } from "./config/define-config.ts";
-export type { AuthFlow, AuthStep, Hooks, OatConfig, OperationStep, OutOfBandRequest, OutOfBandStep, Principal, ProfileSpec, RateLimitSpec, RequestStep, UploadFile, UploadRequest, UploadResolution, Uploads, } from "./config/define-config.ts";
+export type { AuthFlow, AuthRefresh, AuthStep, Hooks, OatConfig, OperationStep, OutOfBandRequest, OutOfBandStep, Principal, ProfileSpec, RateLimitSpec, RequestStep, UploadFile, UploadRequest, UploadResolution, Uploads, } from "./config/define-config.ts";
 export { loadConfig } from "./config/load.ts";
 export { deriveCollectionShape, deriveIdentity } from "./spec/collection.ts";
 export type { CollectionShape } from "./spec/collection.ts";
@@ -7,6 +7,7 @@ export { buildModel } from "./spec/graph.ts";
 export type { EntityModel, OperationModel, SpecModel } from "./spec/graph.ts";
 export { dereference, loadSpec, normalisePath, parseRouteRef } from "./spec/load.ts";
 export type { OpenApiDocument } from "./spec/types.ts";
+export { AuthRefreshRequiredError } from "./runtime/auth.ts";
 export { run } from "./runtime/run.ts";
 export type { RunOptions, RunResult } from "./runtime/run.ts";
 export type { Actor } from "./runtime/checks.ts";

package/dist/index.js

@@ -3,6 +3,7 @@ export { loadConfig } from "./config/load.js";
 export { deriveCollectionShape, deriveIdentity } from "./spec/collection.js";
 export { buildModel } from "./spec/graph.js";
 export { dereference, loadSpec, normalisePath, parseRouteRef } from "./spec/load.js";
+export { AuthRefreshRequiredError } from "./runtime/auth.js";
 export { run } from "./runtime/run.js";
 export { buildMatrixGraph, matrixViewFromReport, renderMatrixGraph, renderMatrixHtml } from "./report/matrix.js";
 export { coverageByCheck, renderConsole, renderJson, renderMarkdown, renderRepros } from "./report/render.js";

package/dist/runtime/async.d.ts

@@ -1,13 +1,13 @@
 /**
  * Async operation support.
  *
- * For an operation declared with `x-async`, the HTTP response is a receipt, not an outcome. oat
- * drives the poll route to a terminal state and treats that payload as the real result — without
- * this, an extraction or batch API is testable only as "returned 202", which for such an API is
- * most of the surface.
+ * `x-async` means the HTTP response is a receipt, then oat polls. A `text/event-stream` body is
+ * the result itself — parse events, do not `JSON.parse` the raw string. Poll only when the
+ * stream ends without a terminal frame and `idFrom` resolved.
  */
 import type { AsyncSpec } from "../spec/extensions.ts";
 import type { Client, Exchange } from "./client.ts";
+import { type SseEvent } from "./sse.ts";
 export interface AsyncOutcome {
     /** Terminal state reached, or null on timeout. */
     terminal: Record<string, unknown> | null;
@@ -23,6 +23,21 @@ export interface AsyncOutcome {
  * language as the filter grammar rather than inventing a second one.
  */
 export declare function matchesPredicate(record: Record<string, unknown>, expression: string): boolean;
+export declare function readPath(body: unknown, path: string): unknown;
+/**
+ * Resolve `idFrom` against a JSON receipt, or against each SSE event's JSON `data` (first hit).
+ */
+export declare function resolveAsyncId(receipt: unknown, idFrom: string): unknown;
+export interface StreamAsyncView {
+    id: unknown;
+    /** Event data that carried `idFrom`, for binding the poll path. */
+    idRecord: Record<string, unknown> | null;
+    /** `complete` / `error` frame, or a frame whose `data` matches `until`. */
+    terminal: Record<string, unknown> | null;
+    events: SseEvent[];
+}
+/** Read job id and terminal state from SSE frames. `null` when the body is not a stream. */
+export declare function inspectStreamAsync(receipt: unknown, spec: AsyncSpec): StreamAsyncView | null;
 /**
  * Polls until `until` matches, the timeout expires, or the poll route stops responding.
  *
@@ -30,5 +45,5 @@ export declare function matchesPredicate(record: Record<string, unknown>, expres
  * behave the same way, and the interval is fixed rather than exponential — the point is to
  * observe when the state changes, not to be gentle with an API oat is already hammering.
  */
-export declare function driveAsync(client: Client, spec: AsyncSpec, receipt: unknown, scope: Record<string, string>, headers: Record<string, string>): Promise<AsyncOutcome>;
+export declare function driveAsync(client: Client, spec: AsyncSpec, receipt: unknown, scope: Record<string, string>, headers: () => Record<string, string>, refreshIfStale?: (force?: boolean) => Promise<void>): Promise<AsyncOutcome>;
 //# sourceMappingURL=async.d.ts.map

package/dist/runtime/async.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"async.d.ts","sourceRoot":"","sources":["../../src/runtime/async.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAGnD,MAAM,WAAW,YAAY;IAC5B,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IACxC,SAAS,EAAE,QAAQ,EAAE,CAAA;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,OAAO,CAAA;IACjB,2FAA2F;IAC3F,SAAS,EAAE,OAAO,CAAA;CAClB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CA0B7F;AAcD;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC/B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,OAAO,CAAC,YAAY,CAAC,CAsEvB"}
+{"version":3,"file":"async.d.ts","sourceRoot":"","sources":["../../src/runtime/async.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACnD,OAAO,EAAE,KAAK,QAAQ,EAAa,MAAM,UAAU,CAAA;AAGnD,MAAM,WAAW,YAAY;IAC5B,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IACxC,SAAS,EAAE,QAAQ,EAAE,CAAA;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,OAAO,CAAA;IACjB,2FAA2F;IAC3F,SAAS,EAAE,OAAO,CAAA;CAClB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CA0B7F;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAU7D;AAOD;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAYxE;AAED,MAAM,WAAW,eAAe;IAC/B,EAAE,EAAE,OAAO,CAAA;IACX,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IACxC,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IACxC,MAAM,EAAE,QAAQ,EAAE,CAAA;CAClB;AAED,4FAA4F;AAC5F,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,GAAG,eAAe,GAAG,IAAI,CAsB5F;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC/B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC7B,OAAO,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACrC,cAAc,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GACjD,OAAO,CAAC,YAAY,CAAC,CA4EvB"}