@lovrozagar/oat 0.1.0

package/labs/README.md

@@ -0,0 +1,130 @@
+# labs — real backends, always D1
+
+Each world is a Hono API this repo owns. **Storage is Cloudflare D1**, never
+local SQLite. Local `serve.ts` talks to D1 over HTTP. After oat is green
+locally, `deploy.mjs` puts the same app on a Worker bound to that D1 and oat
+runs again against `https://`.
+
+```
+node labs/provision.mjs tiny          # create oat-labs-tiny, apply schema
+LAB=tiny LAB_PORT=8790 node --experimental-strip-types labs/serve.ts
+LAB_URL=http://127.0.0.1:8790 node --experimental-sqlite dist/cli.js run --config labs/oat.config.ts
+node labs/deploy.mjs tiny             # Worker + D1 binding
+LAB_URL=https://oat-labs-tiny.<subdomain>.workers.dev ...
+```
+
+Wipe leftover rows (schema stays) before a clean re-run:
+
+```
+node --experimental-strip-types labs/wipe.mjs huge
+```
+
+A live `oat run` writes `progress.log` and `progress.json` under `--out`
+(entity, check, last request, age). If those stop moving, the run is stuck.
+`--quiet` keeps the files and drops stderr.
+
+Or the loop:
+
+```
+bash labs/iterate.sh                  # tiny + probe cases on D1
+bash labs/iterate.sh new              # planted worlds not in the original eight
+bash labs/iterate.sh shop campus
+bash labs/probe-cases.sh
+```
+
+| world | entities | what it is for |
+| --- | --- | --- |
+| `tiny` | 1 | one collection, invite, ranks, soft-delete |
+| `shop` | 5 | store → product → review, plus order / customer. Cross-entity `x-invalidate` |
+| `campus` | 10 | nested campus / building / room / booking / course |
+| `platform` | 20 | a workspace SaaS. Many parents, many derived counts |
+| `huge` / `vast` | 200 / 2000 | schema-only unless `LAB_SCALE=1`. Do not oat-run on D1 by default. |
+
+Credentials: repo-root `.env` (`CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_API_TOKEN`).
+Provision writes `CLOUDFLARE_D1_<WORLD>=<uuid>` into `.env` and `labs/.d1.json`
+(gitignored).
+
+## Correct vs planted bugs
+
+`bash labs/probe-cases.sh` — each case is its own D1.
+
+| world | planted | oat must report |
+| --- | --- | --- |
+| `ok-pair` / `ok-classic` | none | nothing |
+| `ok-jobs` | none (async start + artifact effect) | nothing |
+| `bug-stale` | child write does not bump `product_count` | `invalidation.declared-route-changes` |
+| `bug-nofilter` | filter parses, then is dropped | `filter.equality-selects-exactly-one` |
+| `bug-leak` | item GET is global by id | `tenant.item-not-readable-cross-tenant` |
+| `bug-overclaim` | `x-query.filterable` lists `ghost` | `spec.declared-filterable-is-filterable` |
+| `bug-pagefilter` | page first, then filter the page | `query.filter-selects-from-whole-set` |
+| `bug-cursor` | `nextCursor` advertised, ignored | `pagination.cursor-agrees-with-page` |
+| `bug-lostupdate` | PATCH writes the whole row | `concurrency.no-lost-update` |
+| `bug-invite` | accept does not grant | `auth.invite-grants-then-revokes` |
+| `bug-tombstone` | soft-deleted row stays in the default list | `softdelete.absent-from-default-list` |
+| `bug-rank` | viewer can read a record member cannot | `auth.rank-is-monotonic` |
+| `bug-filterleak` | a filter drops the tenant predicate | `tenant.filter-does-not-bypass-scope` |
+| `bug-hasmore` | `hasMore` is always false | `pagination.has-more-is-accurate` |
+| `bug-maxlimit` | documented `maxLimit` is not capped | `pagination.limit-respects-documented-max` |
+| `bug-search` | `q` is accepted and ignored | `search.q-narrows-result` |
+| `bug-select` | sparse fieldset is ignored | `select.projection-honoured` |
+| `bug-sort` | `order` is accepted and ignored | `sort.order-is-applied` |
+| `bug-idem` | `Idempotency-Key` is ignored | `idempotency.replay-does-not-duplicate` |
+| `bug-immutable` | `x-immutable` fields accept writes | `patch.immutable-field-rejected` |
+| `bug-enum` | enum is not enforced | `validation.enum-enforced` |
+| `bug-maxlen` | maxLength is not enforced | `validation.max-length-enforced` |
+| `bug-required` | required fields are not enforced | `validation.required-enforced` |
+| `bug-revoke` | revoke leaves the grant in place | `auth.invite-grants-then-revokes` |
+| `bug-offset` | page/offset is ignored | `pagination.page-walk-covers-set` |
+| `bug-oracle` | 403 vs 404 reveals existence | `tenant.denial-does-not-reveal-existence` |
+| `bug-like` | LIKE `%` is treated as a wildcard | `filter.like-metacharacters-escaped` |
+| `bug-async` | job start stays `pending` forever | `async.reaches-terminal-state` |
+| `bug-effect` | `x-effects` create does not insert | `effects.declared-effect-occurs` |
+| `bug-oversort` | `x-query.sortable` lists `ghost` | `spec.declared-sortable-is-sortable` |
+| `bug-overselect` | `x-query.selectable` lists `ghost` | `spec.declared-selectable-is-selectable` |
+| `bug-receipt` | job start receipt omits `id` | `async.receipt-identifies-the-job` |
+| `bug-count` | envelope `count` is always 0 | `count.consistent-with-returned-page` |
+| `bug-widen` | PATCH also writes `kind` | `patch.minimality` |
+| `bug-unknown` | unknown filter field is ignored | `filter.unknown-field-rejected` |
+| `bug-neq` | `neq` is a no-op | `filter.negation-partitions-the-set` |
+| `bug-and` | `and()` compiles as OR | `filter.and-composes-as-intersection` |
+| `bug-or` | `or()` compiles as AND | `filter.or-composes-as-union` |
+| `bug-numeric` | numeric `gt` compares as text | `filter.numeric-comparison-is-numeric` |
+| `bug-limit` | `limit` does not bound the page | `pagination.limit-bounds-page-size` |
+| `bug-dropfield` | create drops submitted `note` | `create.persists-submitted-fields` |
+| `bug-status` | create returns 200 not 201 | `create.status-matches-document` |
+| `bug-del404` | DELETE of a missing id is 204 | `delete.absent-record-returns-404` |
+| `bug-ctype` | `text/plain` accepted on JSON create | `validation.content-type-enforced` |
+| `bug-500` | malformed filter returns 500 | `error.malformed-filter-not-5xx` |
+| `bug-errschema` | error body omits `error_key` | `schema.error-response-matches-document` |
+
+Invites live in D1 (`invites` table). An in-memory map would die on Worker isolate hops.
+
+Schema is generated, not mocked. `labs/worlds/catalog.ts` is the source;
+`labs/kit/schema.ts` turns it into `CREATE TABLE` statements that
+`provision.mjs` runs on a real D1. To read the SQL:
+
+```
+node --experimental-strip-types labs/dump-schema.mjs   # writes labs/schema/<world>.sql
+```
+
+OpenAPI is generated the same way (`kit/spec.ts`) and served at
+`/v1/openapi/spec`. There is no local SQLite path.
+
+## Configs and the fixture demo
+
+These also live here — there is no top-level `examples/`.
+
+| file | what it is |
+| --- | --- |
+| `oat.config.ts` | principals for a labs world (D1) |
+| `local.config.ts` | point oat at `oat serve` (the fixture) |
+| `minimal.config.ts` | smallest useful config, static API key |
+| `anyrow.config.ts` | multi-step login against a stranger API |
+| `annotated-openapi.yaml` | every `x-*` tag in one document |
+| `demo.mjs` | one-process fixture demo (`npm run demo`) |
+
+```
+node dist/cli.js serve --defects STALE_LIST,PATCH_REPLACES
+node --experimental-strip-types dist/cli.js run --config labs/local.config.ts --base-url http://127.0.0.1:PORT
+node dist/cli.js doctor --spec labs/annotated-openapi.yaml
+```

package/labs/annotated-openapi.yaml

@@ -0,0 +1,311 @@
+# A complete, valid OpenAPI 3.1 document showing every tag oat reads, in place.
+#
+# This file is not illustrative — the conformance suite loads it and asserts that oat resolves
+# what the comments claim, so it cannot drift away from the implementation. Run it yourself:
+#
+#     oat plan --spec labs/annotated-openapi.yaml --base-url https://api.example.com
+#
+# Every `x-` tag below is OPTIONAL. Each one either tells oat something it cannot otherwise know,
+# or replaces a guess that oat would report as a coverage gap. Nothing here is oat-specific
+# vocabulary you are locked into: they are plain OpenAPI extensions, and any other tool ignores
+# them.
+
+openapi: 3.1.0
+info:
+  title: Widgets API
+  version: "1.0"
+
+paths:
+  /v1/workspaces/{workspace_id}/widgets:
+    get:
+      operationId: widget.list
+      summary: List widgets
+
+      # ── x-entity ─────────────────────────────────────────────────────────────
+      # Which resource this operation reads, and which property identifies it.
+      # Without this oat guesses the entity from the path and the identity from the
+      # response schema — usually right, and reported as a guess when it has to.
+      x-entity:
+        name: widget
+        action: list
+        identity: id
+
+      # ── x-tenant ─────────────────────────────────────────────────────────────
+      # Names the parameter that scopes this route to a tenant. This is what turns a
+      # cross-tenant read from an AMBIGUITY ("oat inferred a boundary") into a SECURITY
+      # finding ("the document states a boundary and it was crossed").
+      x-tenant: workspace_id
+
+      # ── x-query ──────────────────────────────────────────────────────────────
+      # The one oat cannot work around. `filter` is declared below as `type: string`,
+      # which says nothing about WHICH fields it accepts — so without this tag oat
+      # assumes every scalar property is filterable and warns that it is guessing.
+      x-query:
+        grammar: postgrest          # postgrest | colon | equality — how filter values are written
+        filterable: [id, workspace_id, name, status, priority, created_at]
+        sortable: [name, priority, created_at]
+        searchable: [name, description]   # the fields `q` actually searches
+        selectable: [id, name, status, priority, created_at]
+        maxLimit: 100
+        defaultOrder: created_at.desc
+        # Load-bearing: without a total order, keyset pagination is unsound and page
+        # walks silently drop or duplicate rows. Declaring it lets oat assert it;
+        # omitting it makes oat probe for the instability instead.
+        stableTiebreak: id
+
+      parameters:
+        - { name: workspace_id, in: path, required: true, schema: { type: string } }
+        # The description is not decoration: oat infers the filter grammar from the
+        # syntax demonstrated here when `x-query.grammar` is absent.
+        - name: filter
+          in: query
+          schema: { type: string }
+          description: "PostgREST-style filter: field.op.value, and(...), or(...). e.g. status.eq.active"
+        - name: order
+          in: query
+          schema: { type: string }
+          description: "Sort: field[.asc|.desc], comma-separated. e.g. created_at.desc"
+        - name: select
+          in: query
+          schema: { type: string }
+          description: Comma-separated sparse fieldset
+        - name: q
+          in: query
+          schema: { type: string }
+          description: Free-text search
+        # `limit` carries a maximum and a default, which is how oat tells a page size
+        # from a total when a name is ambiguous (`count` is both, in the wild).
+        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } }
+        - { name: page, in: query, schema: { type: integer, minimum: 1 } }
+        - { name: cursor, in: query, schema: { type: string } }
+
+      responses:
+        "200":
+          description: A page of widgets
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  widgets: { type: array, items: { $ref: "#/components/schemas/Widget" } }
+                  count: { type: integer }
+                  hasMore: { type: boolean }
+                  nextCursor: { type: [string, "null"] }
+                required: [widgets, count, hasMore]
+
+    post:
+      operationId: widget.create
+      summary: Create a widget
+      x-entity: { name: widget, action: create, identity: id }
+      x-tenant: workspace_id
+
+      # ── x-invalidate ─────────────────────────────────────────────────────────
+      # Which read routes this write changes. oat inverts these into the entity's
+      # read surface — it is how the entity graph is built — AND verifies them: a
+      # route named here that returns a byte-identical body after the write is either
+      # a stale projection or a wrong declaration.
+      x-invalidate:
+        - "GET /v1/workspaces/{workspace_id}/widgets"
+        - "GET /v1/workspaces/{workspace_id}/summary"
+
+      # ── x-generated ──────────────────────────────────────────────────────────
+      # Server-owned fields. Excluded from PATCH-minimality comparisons, because a
+      # value the server maintains may legitimately change between two reads.
+      x-generated: [id, workspace_id, created_at, updated_at]
+
+      parameters:
+        - { name: workspace_id, in: path, required: true, schema: { type: string } }
+        # A declared idempotency header is a promise oat will test by replaying the
+        # request: the replay must return the original record, not create a second.
+        - { name: Idempotency-Key, in: header, required: false, schema: { type: string } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: false
+              properties:
+                name: { type: string, maxLength: 128 }
+                description: { type: string, maxLength: 512 }
+                status: { type: string, enum: [draft, active, archived] }
+                priority: { type: integer, minimum: 0, maximum: 10 }
+              required: [name]
+      responses:
+        "201":
+          description: Created
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Widget" }
+
+  /v1/workspaces/{workspace_id}/widgets/{widget_id}:
+    get:
+      operationId: widget.read
+      x-entity: { name: widget, action: read, identity: id }
+      x-tenant: workspace_id
+      parameters:
+        - { name: workspace_id, in: path, required: true, schema: { type: string } }
+        - { name: widget_id, in: path, required: true, schema: { type: string } }
+      responses:
+        "200":
+          description: A widget
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Widget" }
+
+    patch:
+      operationId: widget.update
+      x-entity: { name: widget, action: update, identity: id }
+      x-tenant: workspace_id
+      x-invalidate: ["GET /v1/workspaces/{workspace_id}/widgets"]
+
+      # ── x-immutable ──────────────────────────────────────────────────────────
+      # Fields a client must never be able to write. oat PATCHes each one and expects
+      # a rejection; a backend that accepts a write to the tenant key here is how a
+      # record silently moves between tenants.
+      x-immutable: [id, workspace_id, created_at]
+      x-generated: [updated_at]
+
+      parameters:
+        - { name: workspace_id, in: path, required: true, schema: { type: string } }
+        - { name: widget_id, in: path, required: true, schema: { type: string } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: false
+              properties:
+                name: { type: string, maxLength: 128 }
+                description: { type: string, maxLength: 512 }
+                status: { type: string, enum: [draft, active, archived] }
+                priority: { type: integer, minimum: 0, maximum: 10 }
+      responses:
+        "200":
+          description: Updated
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Widget" }
+
+    delete:
+      operationId: widget.delete
+      x-entity: { name: widget, action: delete, identity: id }
+      x-tenant: workspace_id
+      x-invalidate: ["GET /v1/workspaces/{workspace_id}/widgets"]
+
+      # ── x-soft-delete ────────────────────────────────────────────────────────
+      # Names the tombstone column. oat then asserts a deleted record disappears from
+      # the default listing rather than expecting a hard 404 that will never come.
+      x-soft-delete: deleted_at
+
+      # ── x-destructive ────────────────────────────────────────────────────────
+      # Advisory: oat will not run this against data it did not create.
+      x-destructive: true
+
+      parameters:
+        - { name: workspace_id, in: path, required: true, schema: { type: string } }
+        - { name: widget_id, in: path, required: true, schema: { type: string } }
+      responses:
+        "204": { description: Deleted }
+
+  # The route `widget.create` declares it invalidates. It exposes a count derived from
+  # another entity, which is exactly the case `x-invalidate` exists to make testable:
+  # oat snapshots this route, creates a widget, and re-reads it. A byte-identical body
+  # means the derived value is stale or the declaration is wrong.
+  /v1/workspaces/{workspace_id}/summary:
+    get:
+      operationId: workspace.summary
+      summary: Workspace totals
+      # Declared as a read of `workspace`, so oat models it as that entity's read
+      # surface rather than inferring a third entity with no way to verify it.
+      x-entity: { name: workspace, action: read, identity: workspace_id }
+      x-tenant: workspace_id
+      parameters:
+        - { name: workspace_id, in: path, required: true, schema: { type: string } }
+      responses:
+        "200":
+          description: Totals for the workspace
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  workspace_id: { type: string }
+                  widget_count: { type: integer }
+                required: [workspace_id, widget_count]
+
+  /v1/workspaces/{workspace_id}/exports:
+    post:
+      operationId: export.start
+      summary: Start an export
+
+      # ── x-async ──────────────────────────────────────────────────────────────
+      # The request returns a receipt, not a result. Without this oat asserts against
+      # the receipt and reports the missing data as a bug; with it, oat follows the
+      # job to a terminal state and asserts on the outcome.
+      x-async:
+        poll: export.read              # operationId that reports progress
+        idFrom: $.export_id            # where the receipt carries the job id
+        until: $.status in [complete, failed]
+        successWhen: $.status == complete
+        timeoutMs: 30000
+        pollIntervalMs: 500
+
+      # ── x-effects ────────────────────────────────────────────────────────────
+      # What this operation changes elsewhere. `x-invalidate` says a route's response
+      # changes; `x-effects` says how, which is what makes it assertable.
+      x-effects:
+        - entity: widget
+          change: none                 # exporting must not mutate what it exports
+
+      x-tenant: workspace_id
+      parameters:
+        - { name: workspace_id, in: path, required: true, schema: { type: string } }
+      responses:
+        "202":
+          description: Accepted
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  export_id: { type: string }
+                  status: { type: string, enum: [pending, running, complete, failed] }
+                required: [export_id, status]
+
+  /v1/workspaces/{workspace_id}/exports/{export_id}:
+    get:
+      operationId: export.read
+      x-entity: { name: export, action: read, identity: export_id }
+      x-tenant: workspace_id
+      parameters:
+        - { name: workspace_id, in: path, required: true, schema: { type: string } }
+        - { name: export_id, in: path, required: true, schema: { type: string } }
+      responses:
+        "200":
+          description: Export status
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  export_id: { type: string }
+                  status: { type: string, enum: [pending, running, complete, failed] }
+                required: [export_id, status]
+
+components:
+  schemas:
+    Widget:
+      type: object
+      properties:
+        id: { type: string }
+        workspace_id: { type: string }
+        name: { type: string }
+        description: { type: [string, "null"] }
+        status: { type: string, enum: [draft, active, archived] }
+        priority: { type: integer }
+        created_at: { type: string, format: date-time }
+        updated_at: { type: string, format: date-time }
+        deleted_at: { type: [string, "null"] }
+      required: [id, workspace_id, name, status, priority, created_at, updated_at]

package/labs/anyrow.config.ts

@@ -0,0 +1,107 @@
+/**
+ * A config against a live API that needs a multi-step login.
+ *
+ * This file is the entire coupling surface between oat and one specific backend: which route
+ * issues a credential, how a verification token that never travels over HTTP is collected, which
+ * header carries it, and which path parameters the credential itself identifies. Delete it and
+ * oat still runs against any other OpenAPI document.
+ *
+ *   ANYROW_TESTER_KEY=... oat run --config labs/anyrow.config.ts
+ *
+ * Written as `from "../dist/index.js"` only because this file lives inside the repository —
+ * in your own project it is `from "@lovrozagar/oat"`.
+ */
+
+import { defineConfig, type AuthFlow, type OutOfBandRequest } from "../dist/index.js"
+
+const API = process.env.ANYROW_API ?? "https://api.anyrow.ai"
+const TESTER_KEY = process.env.ANYROW_TESTER_KEY ?? ""
+const PASSWORD = "OatSpec123!x"
+
+/** A distinct address per principal per run, so tenants never collide between runs. */
+function freshEmail(label: string): string {
+	return `oat-${label}-${Date.now()}-${Math.floor(Math.random() * 10_000)}@anyrow-spec.test`
+}
+
+/**
+ * Register, collect the emailed verification token, verify, keep the credential.
+ *
+ * Registration provisions an organisation and a project, so each principal arrives owning its
+ * own tenant — which is what makes the isolation checks meaningful without a single fixture
+ * identifier being configured by hand.
+ */
+function signUp(label: string): AuthFlow {
+	const email = freshEmail(label)
+	return {
+		credentialFrom: "$.access_token",
+		expiresInFrom: "$.access_token_expires_in",
+		steps: [
+			/* Raw paths rather than operationIds: this API's published document contains no auth
+			 * operations at all, so there is nothing in the spec to reference. `oat doctor`
+			 * reports that as a gap — a document describing a protected API should describe how
+			 * to authenticate to it. */
+			{
+				/* Binding the address is what lets teardown cascade the account away afterwards. */
+				bind: { address: email },
+				body: { email, name: `Oat ${label}`, password: PASSWORD },
+				method: "POST",
+				path: "/v1/auth/register/email",
+			},
+			{ outOfBand: { address: email, as: "verifyToken", kind: "email-verify" } },
+			{
+				body: { token: "{verifyToken}" },
+				method: "POST",
+				path: "/v1/auth/email/verify",
+				saveAs: { credential: "$.access_token" },
+				/* The credential names the org and project registration just provisioned. */
+				saveClaimsFrom: {
+					bind: { orgId: "orgs.0.oid", projectId: "orgs.0.pids.0" },
+					token: "$.access_token",
+				},
+			},
+		],
+	}
+}
+
+/**
+ * Reads a token this deployment stashes for test traffic. Every backend does this differently —
+ * a mail catcher, a KV tap, a webhook sink — which is exactly why oat cannot do it for you.
+ * Returning null asks oat to retry: such stores are usually eventually consistent.
+ */
+async function resolveOutOfBand({ address, kind }: OutOfBandRequest): Promise<string | null> {
+	const url = new URL(`${API}/v1/test/last-token`)
+	url.searchParams.set("email", address)
+	url.searchParams.set("type", kind)
+	const response = await fetch(url, { headers: { "x-ia-tester-key": TESTER_KEY } })
+	if (!response.ok) return null
+	const body = (await response.json()) as { token?: unknown }
+	return typeof body.token === "string" ? body.token : null
+}
+
+/** Cascade-deletes a principal this run provisioned, and everything it created with it. */
+async function teardownPrincipal(address: string): Promise<void> {
+	const url = new URL(`${API}/v1/test/cleanup-user`)
+	url.searchParams.set("email", address)
+	await fetch(url, { headers: { "x-ia-tester-key": TESTER_KEY }, method: "DELETE" })
+}
+
+export default defineConfig({
+	baseUrl: API,
+	/* Sent on every request. Opaque to oat — it never inspects these. */
+	globalHeaders: { "x-ia-tester-key": TESTER_KEY },
+	hooks: { resolveOutOfBand, teardownPrincipal },
+	principals: [
+		{
+			auth: signUp("alpha"),
+			id: "alpha",
+			rootsFromFlow: { organization_id: "orgId", project_id: "projectId" },
+		},
+		{
+			auth: signUp("beta"),
+			id: "beta",
+			rootsFromFlow: { organization_id: "orgId", project_id: "projectId" },
+		},
+	],
+	seed: 42,
+	spec: `${API}/v1/openapi/spec`,
+})

package/labs/demo.mjs

@@ -0,0 +1,124 @@
+/**
+ * Self-contained demo — no credentials, no external service, nothing to configure.
+ *
+ * Boots the reference backend with a handful of deliberate defects, points oat at it, and writes
+ * a full report. This is the fastest way to see what oat actually produces before wiring it to
+ * anything of your own.
+ *
+ *   node labs/demo.mjs                  # a few defects, see the report
+ *   node labs/demo.mjs --clean          # a correct backend — should find nothing
+ *   node labs/demo.mjs --defects A,B    # pick your own, names are in DEFECTS below
+ *   node --experimental-sqlite labs/demo.mjs --backend sqlite
+ *
+ * The backend is a test fixture that ships with the repo, not part of the published package —
+ * oat itself never talks to a database, only to HTTP.
+ */
+
+import { mkdir, writeFile } from "node:fs/promises"
+import { dirname, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import { DEFECTS } from "../dist/reference/defects.js"
+import { createMemoryServer, createPostgresServer, createSqliteServer } from "../dist/reference/http.js"
+import { renderConsole, renderJson, renderMarkdown, renderRepros } from "../dist/report/render.js"
+import { run } from "../dist/runtime/run.js"
+
+const here = dirname(fileURLToPath(import.meta.url))
+const outDir = resolve(here, "../oat-out")
+
+function flag(name) {
+	const index = process.argv.indexOf(`--${name}`)
+	if (index === -1) return undefined
+	const next = process.argv[index + 1]
+	return next !== undefined && !next.startsWith("--") ? next : true
+}
+
+/* A deliberately mixed bag: one of each severity, so the report shows how findings are ranked
+ * rather than a wall of one kind. */
+const DEFAULT_DEFECTS = [
+	"STALE_LIST",
+	"PATCH_REPLACES",
+	"TENANT_LEAK_VIA_FILTER",
+	"CREATED_201_AS_200",
+	"SELECT_IGNORED",
+]
+
+const defects =
+	flag("clean") === true
+		? []
+		: typeof flag("defects") === "string"
+			? flag("defects").split(",")
+			: DEFAULT_DEFECTS
+
+for (const name of defects) {
+	if (!Object.hasOwn(DEFECTS, name)) {
+		console.error(`unknown defect "${name}". Available:\n  ${Object.keys(DEFECTS).join("\n  ")}`)
+		process.exit(2)
+	}
+}
+
+const backend = flag("backend") ?? "memory"
+const createServer =
+	backend === "memory"
+		? createMemoryServer
+		: backend === "sqlite"
+			? createSqliteServer
+			: createPostgresServer
+
+const server = await createServer({ defects })
+
+/* Two principals in different tenants — the second is what makes the isolation checks possible. */
+const principals = [
+	{
+		auth: {
+			credentialFrom: "$.access_token",
+			steps: [{ body: { key: "key_alpha" }, operationId: "auth.token" }],
+		},
+		id: "alpha",
+		roots: { project_id: "proj_alpha" },
+	},
+	{
+		auth: {
+			credentialFrom: "$.access_token",
+			steps: [{ body: { key: "key_beta" }, operationId: "auth.token" }],
+		},
+		id: "beta",
+		roots: { project_id: "proj_beta" },
+	},
+]
+
+console.log(`\n  backend  ${backend}`)
+console.log(`  defects  ${defects.length > 0 ? defects.join(", ") : "none — correct backend"}`)
+
+const startedAt = new Date()
+const began = performance.now()
+const result = await run({
+	baseUrl: server.url,
+	principals,
+	seed: 42,
+	spec: `${server.url}/v1/openapi/spec`,
+})
+const durationMs = performance.now() - began
+
+const input = {
+	baseUrl: server.url,
+	checksRun: result.checksRun,
+	client: result.client,
+	durationMs,
+	entitiesTested: result.entitiesTested,
+	findings: result.findings,
+	model: result.model,
+	startedAt,
+}
+
+await mkdir(resolve(outDir, "repro"), { recursive: true })
+await writeFile(resolve(outDir, "oat-report.md"), renderMarkdown(input))
+await writeFile(resolve(outDir, "oat-report.json"), renderJson(input))
+for (const script of renderRepros(result.findings, server.url)) {
+	await writeFile(resolve(outDir, "repro", script.filename), script.content, { mode: 0o755 })
+}
+
+process.stdout.write(renderConsole(input))
+console.log(`  report   ${resolve(outDir, "oat-report.md")}`)
+console.log(`  repro    ${resolve(outDir, "repro")}/\n`)
+
+await server.close()