@ripplo/testing 0.1.0 → 0.2.0

package/README.md

@@ -11,20 +11,24 @@ npm install @ripplo/testing
 ## Quick Start
 
 1. Run `npx ripplo` to authenticate and scaffold a `.ripplo/` directory in your project
-2. Define preconditions in `.ripplo/preconditions/`, then add `import "./preconditions/<file>.js";` to `.ripplo/index.ts`. Exports set up test data (users, workspaces, etc.)
-3. (Optional) Define observers in `.ripplo/observers/` for backend state assertions (`assert.backend(...)`), then add `import "./observers/<file>.js";` to `.ripplo/index.ts`
-4. Write tests in `.ripplo/tests/`, then add `import "./tests/<id>.js";` to `.ripplo/index.ts`. The CLI only loads what that file imports.
-5. Run `npx ripplo lint` to validate, `npx ripplo run` to execute
-6. Commit the generated `.ripplo/ripplo.lock` alongside your DSL changes (see Lockfile below)
+2. Define preconditions in `.ripplo/preconditions/index.ts` — export each handle and collect them into a `preconditions` registry
+3. (Optional) Define observers in `.ripplo/observers/index.ts` the same way
+4. Write tests in `.ripplo/tests/` — each file exports a `TestDefinition`; `.ripplo/tests/index.ts` composes them into a `tests` array
+5. Wire everything into `.ripplo/ripplo.ts` by passing the three registries to `createRipplo(config, { preconditions, observers, tests })`
+6. In your app server, call `createEngine(ripplo, { preconditions, observers })` to provide implementations — TypeScript enforces that every handle is implemented exactly once
+7. Run `npx ripplo lint` to validate, `npx ripplo run` to execute
+8. Commit the generated `.ripplo/ripplo.lock` alongside your DSL changes (see Lockfile below)
 
 Every test gets a clean slate via preconditions — no shared state, no ordering dependencies, fully parallelizable. Observers let tests verify backend side effects (async jobs, DB rows, webhooks) without polling or sleeps in test code.
 
 ## Architecture
 
-`@ripplo/testing` has two halves:
+`@ripplo/testing` has two halves that hand off through two "funnels":
 
-- **DSL** — the typed builder (`ripplo.test(...)`, `ripplo.precondition(...)`, `ripplo.observer(...)`, locators, actions, `assert.*`) that your `.ripplo/*.ts` files use. Pure TypeScript, compiles to a JSON lockfile.
-- **Engine** — the adapter (`@ripplo/testing/express`, `/fastify`, `/nextjs`) mounted into your app server. It hosts three routes under a single prefix (default `/ripplo`): `PUT /execute-preconditions`, `PUT /execute-observer`, `PUT /teardown-preconditions`. Every request is HMAC-signed; the adapter is gated behind `ENABLE_RIPPLO_TESTING` so it can't ship to production by accident.
+- **Definitions funnel into `createRipplo`.** The pure top-level factories `precondition(...)`, `observer(...)`, `test(...)` return plain handle/definition values. They have no side effects — no global builder. You gather them into registry objects and pass all three to `createRipplo(config, { preconditions, observers, tests })` in `.ripplo/ripplo.ts`. That call is the single point where the DSL graph is registered.
+- **Implementations funnel into `createEngine`.** In your app server, `createEngine(ripplo, { preconditions: {...}, observers: {...} })` wires every handle to its setup/teardown/run function. The impls object is exhaustiveness-checked at compile time: missing a key is a type error, adding an unknown key is a type error.
+
+The resulting `engine` is what adapters (`@ripplo/testing/express`, `/fastify`, `/nextjs`) mount under a path prefix (default `/ripplo`) — serving three routes: `PUT /execute-preconditions`, `PUT /execute-observer`, `PUT /teardown-preconditions`. Every request is HMAC-signed; the adapter is gated behind `ENABLE_RIPPLO_TESTING` so it can't ship to production by accident.
 
 Your precondition and observer implementations live in the server package where they have access to your DB/ORM. The DSL package never runs that code — it just orchestrates execution over signed HTTP.
 
@@ -38,20 +42,35 @@ The Ripplo server reads the lockfile on every GitHub push webhook. If the lockfi
 - `ripplo compile --check` — exit non-zero if the lockfile is missing or stale. Use in pre-commit hooks or CI.
 - `ripplo doctor` — surfaces stale lockfiles and a missing pre-commit hook.
 
+## Project Layout
+
+```
+.ripplo/
+  ripplo.ts              # createRipplo(config, { preconditions, observers, tests })
+  index.ts               # re-exports the default ripplo instance + registries
+  preconditions/index.ts # export each handle + a `preconditions` registry
+  observers/index.ts     # export each handle + an `observers` registry
+  tests/
+    index.ts             # compose all tests into a `tests` array
+    <test-id>.ts         # each file exports a TestDefinition
+
+<your-server>/src/test/
+  engine.ts              # createEngine(ripplo, { preconditions, observers }) — impls live here
+```
+
 ## DSL API
 
-### Test Builder
+### Test
 
 ```typescript
-import ripplo from "../ripplo.js";
-import { dataWorkspace } from "../preconditions/index.js";
-import { invitePendingForEmail } from "../observers/index.js";
+import { test } from "@ripplo/testing";
 import { click, fill } from "@ripplo/testing/actions";
 import { assert } from "@ripplo/testing/assert";
 import { role } from "@ripplo/testing/locators";
+import { dataWorkspace } from "../preconditions/index.js";
+import { invitePendingForEmail } from "../observers/index.js";
 
-ripplo
-  .test("invite-a-teammate")
+export const inviteATeammate = test("invite-a-teammate")
   .name("Invite a teammate")
   .requires({ workspace: dataWorkspace })
   .expectedOutcome("Invite appears in the pending list and an invite record is created")
@@ -70,9 +89,52 @@ ripplo
   ]);
 ```
 
-**Chain:** `.test(id)` → `.name(display)` → `.requires(preconditions)` → `.expectedOutcome(text)` → `.startsAt(urlFn)` → `.steps(stepsFn)`
+**Chain:** `test(id)` → `.name(display)` → `.requires(preconditions)` → `.expectedOutcome(text)` → `.startsAt(urlFn)` → `.steps(stepsFn)`
+
+Use `.notImplemented()` in place of `.startsAt() + .steps()` to stub a test during planning.
+
+### Preconditions
+
+```typescript
+import { precondition } from "@ripplo/testing";
+
+export const authLoggedIn = precondition("auth:logged-in")
+  .description("Authenticated test user with a valid session")
+  .contract<{ userId: string }>();
+
+export const dataProject = precondition("data:project")
+  .description("A project exists and the user is an admin member")
+  .requires({ auth: authLoggedIn })
+  .contract<{ orgId: string; projectId: string }>();
+
+export const preconditions = { authLoggedIn, dataProject };
+```
+
+**Chain:** `precondition(name)` → `.description(text)` → `.requires(deps)` → `.contract<TData>()`
 
-Use `.notImplemented()` instead of `.startsAt()` + `.steps()` to stub a test during planning.
+The generic on `.contract<T>()` describes the shape of the data the precondition setup must return. Each field must be a `string` (run-scoped test values).
+
+### Observers
+
+```typescript
+import { observer } from "@ripplo/testing";
+
+export const orgNameIs = observer("org:name-is")
+  .description("Org with the given id has the given name in the DB")
+  .input<{ orgId: string; expectedName: string }>()
+  .budget("fast") // optional; "fast" is default
+  .contract();
+
+export const observers = { orgNameIs };
+```
+
+**Chain:** `observer(name)` → `.description(text)` → `.input<TInput>()` → `.budget(tier)` (optional) → `.contract()`
+
+**Budget tiers** (framework-defined, not numeric):
+
+- `"fast"` — ~5s with 100→1000ms backoff. Default. Synchronous DB reads.
+- `"slow"` — ~30s with 250→2000ms backoff. Queue drains, replication settling.
+- `"async"` — ~120s with 500→5000ms backoff. Webhooks, queue workers, LLM calls.
 
 ### Locators
 
@@ -155,6 +217,7 @@ assert.not.focused(role("textbox", "Search")); // No focus
 assert.count(testId("row"), 5); // Element count
 assert.attribute(role("link", "Docs"), "href", "/docs"); // Attribute value
 assert.value(role("textbox", "Email"), "test@x.com"); // Input value
+assert.backend(observerHandle, { ... });                // Backend state (see Observers)
 ```
 
 All text/URL assertions use **exact matching only** (`equals` operator). No `contains`, `startsWith`, or regex.
@@ -178,125 +241,141 @@ click(role("button", "Save")).as("save the form");
 assert.visible(role("status", "Saved")).as("verify save confirmation");
 ```
 
-## Precondition System
-
-Preconditions declare test data requirements with typed contracts:
-
-```typescript
-import ripplo from "./ripplo.js";
-
-export const authLoggedIn = ripplo
-  .precondition("auth:logged-in")
-  .description("Authenticated test user with a valid session")
-  .contract<{ userId: string }>();
-
-export const dataProject = ripplo
-  .precondition("data:project")
-  .description("A project exists and the user is an admin member")
-  .requires({ auth: authLoggedIn })
-  .contract<{ orgId: string; projectId: string }>();
-```
-
-**Chain:** `.precondition(name)` → `.description(text)` → `.requires(deps)` → `.contract<T>()`
-
-Use `.notImplemented()` instead of `.contract<T>()` for stubs.
-
-### Data Flow
+## Data Flow
 
 Precondition data flows into tests via destructuring:
 
 ```typescript
-ripplo
-  .test("delete-project")
+test("delete-project")
+  .name("Delete project")
   .requires({ project: dataProject })
+  .expectedOutcome("project no longer exists")
   .startsAt(({ project }) => `/projects/${project.projectId}/settings`)
   .steps(({ project }) => [
-    navigate(`/projects/${project.projectId}/settings`).as("go to settings"),
     // project.projectId, project.orgId available here
+    navigate(`/projects/${project.projectId}/settings`).as("go to settings"),
+    // ...
   ]);
 ```
 
 **Always destructure and use precondition data.** Never hardcode values that come from preconditions — if a precondition implementation changes, the test should not break.
 
-### Precondition Implementation
+## Wiring it together
+
+### `.ripplo/ripplo.ts` — the definitions funnel
 
 ```typescript
-ripplo.implementPrecondition(authLoggedIn, {
-  setup: async (ctx, deps) => {
-    const email = ctx.uniqueEmail();
-    // Create user, set cookies via ctx.setCookie()
-    return { userId: ctx.fixed("user-123") };
-  },
-  teardown: async (ctx) => {
-    // Clean up using ctx.data
+import { createRipplo } from "@ripplo/testing";
+import { preconditions } from "./preconditions/index.js";
+import { observers } from "./observers/index.js";
+import { tests } from "./tests/index.js";
+
+const ripplo = createRipplo(
+  {
+    appUrl: process.env.APP_URL ?? "https://localhost:3001",
+    engineUrl: `${process.env.APP_URL ?? "https://localhost:3001"}/ripplo`,
+    projectId: "<your-project-id>",
+    webhookSecret: process.env.RIPPLO_WEBHOOK_SECRET ?? "",
   },
-});
-```
+  { preconditions, observers, tests },
+);
 
-**SetupContext provides:**
+export default ripplo;
+```
 
-- `ctx.runId` — unique UUID for this test run
-- `ctx.fixed(value)` — static test value
-- `ctx.uniqueId(prefix)` — generate unique ID (e.g., `ripplo-test-abc123`)
-- `ctx.uniqueEmail()` — generate unique email
-- `ctx.setCookie(name, value, options?)` — inject auth cookies
+### App server — the implementations funnel
 
-## Observer System
+```typescript
+// <your-server>/src/test/engine.ts
+import { createEngine } from "@ripplo/testing";
+import ripplo from "../../../../.ripplo/index.js";
+import { prisma } from "../lib/prisma.js";
+
+export const engine = createEngine(ripplo, {
+  preconditions: {
+    authLoggedIn: {
+      setup: async (ctx) => {
+        // create user, set cookies via ctx.setCookie()
+        return { userId: ctx.uniqueId("user") };
+      },
+      teardown: async (ctx) => {
+        // clean up using ctx.data.userId
+      },
+    },
+    dataProject: {
+      setup: async (ctx, { auth }) => {
+        // use auth.userId to create a project
+        return {
+          orgId: ctx.fixed("..."),
+          projectId: ctx.fixed("..."),
+        };
+      },
+      teardown: async () => {},
+    },
+  },
+  observers: {
+    orgNameIs: async (ctx, { orgId, expectedName }) => {
+      const org = await prisma.organization.findUnique({
+        select: { name: true },
+        where: { id: orgId },
+      });
+      if (org == null) return ctx.retry(`organization "${orgId}" not found yet`);
+      if (org.name !== expectedName) {
+        return ctx.retry(`name is "${org.name}", expected "${expectedName}"`);
+      }
+      return ctx.pass();
+    },
+  },
+});
+```
 
-Observers are backend state assertions evaluated mid-test. Use them when the UI is optimistic, the effect is async (jobs, webhooks, pubsub), or a load-bearing write needs independent verification. An observer is a named yes/no question about backend state — if a test needs to _read_ state for later reuse, that's a precondition, not an observer.
+**Exhaustiveness:** the `preconditions` and `observers` keys in this object must exactly match the registries you passed to `createRipplo`. Missing a key is a TypeScript error; adding an unknown key is a TypeScript error.
 
-### Declaration (`.ripplo/observers/*.ts`)
+**Stubbing an impl:** use the `notImplemented` sentinel to keep planning-mode placeholders while the surrounding code still compiles.
 
 ```typescript
-import type { ObserverHandle } from "@ripplo/testing";
-import ripplo from "../ripplo.js";
+import { createEngine, notImplemented } from "@ripplo/testing";
 
-export const orgNameIs: ObserverHandle<{ orgId: string; expectedName: string }> = ripplo
-  .observer("org:name-is")
-  .description("Org with the given id has the given name in the DB")
-  .input<{ orgId: string; expectedName: string }>()
-  .budget("fast") // optional; "fast" is default
-  .contract();
+createEngine(ripplo, {
+  preconditions: {
+    authLoggedIn: { setup, teardown },
+    dataProject: notImplemented("awaiting prisma seed helper"),
+  },
+  observers: { orgNameIs: notImplemented() },
+});
 ```
 
-**Chain:** `.observer(name)` → `.description(text)` → `.input<T>()` → `.budget(tier)` (optional) → `.contract()`
+The engine returns a "not implemented" failure outcome at runtime for any stub, and `ripplo lint` can be configured to block CI on unimplemented entries.
 
-**Budget tiers** (framework-defined, not numeric):
+### SetupContext
 
-- `"fast"` — ~3s with 100→1000ms backoff. Default. Synchronous DB reads.
-- `"slow"` — ~30s with 250→2000ms backoff. Queue drains, replication settling.
-- `"async"` — ~120s with 500→5000ms backoff. Webhooks, queue workers, LLM calls.
+`ctx` passed to each precondition `setup` provides:
 
-### Implementation (server side)
+- `ctx.runId` — unique 12-char id for this test run
+- `ctx.fixed(value)` — static test value
+- `ctx.uniqueId(prefix)` — generate unique ID (e.g., `ripplo-test-<prefix>-<runId>`)
+- `ctx.uniqueEmail()` — generate unique email (`ripplo-test-<runId>@test.ripplo.ai`)
+- `ctx.setCookie(name, value, options?)` — inject auth cookies; forwarded as `Set-Cookie` to the test browser
 
-```typescript
-ripplo.implementObserver(orgNameIs, async (ctx, { orgId, expectedName }) => {
-  const org = await prisma.organization.findUnique({
-    select: { name: true },
-    where: { id: orgId },
-  });
-  if (org == null) return ctx.retry(`organization "${orgId}" not found yet`);
-  if (org.name !== expectedName)
-    return ctx.retry(`name is "${org.name}", expected "${expectedName}"`);
-  return ctx.pass();
-});
-```
+### ObserverContext
 
-**ObserverContext provides:**
+`ctx` passed to each observer impl provides:
 
-- `ctx.pass()` → assertion satisfied, stop polling.
-- `ctx.retry(reason)` → transient; runtime keeps polling until budget expires. `reason` surfaces in failure detail.
-- `ctx.fail(reason)` → invariant violated; stop immediately.
+- `ctx.pass()` → assertion satisfied; stop polling.
+- `ctx.retry(reason)` → **default**. Use for anything that might succeed on a later poll: row not found yet, status not transitioned, queue not drained, side effect still in flight. Runtime polls until the budget expires; the last `reason` surfaces in the failure detail.
+- `ctx.fail(reason)` → **narrow**. Only when further polling cannot help — an invariant has been violated (wrong shape, contradictory value, forbidden state). Stops immediately. If you're tempted to use `fail` for "not found" or "not yet X", it should be `retry`.
 - Any thrown exception is treated as `fail` with the error message.
 
-### Usage in tests
+## Observer Usage in Tests
 
 ```typescript
 import { orgNameIs } from "../observers/index.js";
 
-ripplo
-  .test("update-org-name")
+test("update-org-name")
+  .name("Update org name")
   .requires({ project: dataProject })
+  .expectedOutcome("org name persisted")
+  .startsAt(({ project }) => `/projects/${project.projectId}/settings`)
   .steps(({ project }) => [
     fill(role("textbox", "Organization name"), "New Name").as("fill new name"),
     click(role("button", "Save")).as("click save"),
@@ -319,10 +398,10 @@ For steps that genuinely don't touch server state (cancel dialogs, toggle a disp
 click(role("button", "Cancel"), { uiOnly: true }).as("close dialog");
 ```
 
-For entire presentation-only flows, pass the flag to `ripplo.test`:
+For entire presentation-only flows, pass the flag to `test`:
 
 ```typescript
-ripplo.test("filter-sort-user-flows", { uiOnly: true }).name("Filter & sort");
+test("filter-sort-user-flows", { uiOnly: true }).name("Filter & sort");
 ```
 
 Treat `uiOnly` as a narrow escape hatch — default to writing an observer.
@@ -348,34 +427,40 @@ ripplo flake-detect <id> --runs=10  # Run N times in parallel to detect flakines
 
 ## Server Setup
 
-Your application server must expose the engine endpoint under a single path prefix (the value you pass to `createRipplo({ engineUrl })`). Pick the adapter that matches your framework — each handles webhook signature verification, cookie forwarding, and request parsing for you. Every adapter takes a required `enabled: boolean` flag — bind it to an env var (e.g. `process.env.ENABLE_RIPPLO_TESTING === "true"`) so the endpoints never ship to production. When `enabled` is false the adapter mounts a no-op handler.
+Pick the adapter that matches your framework — each handles webhook signature verification, cookie forwarding, and request parsing for you. Every adapter takes a required `enabled: boolean` flag — bind it to an env var (e.g. `process.env.ENABLE_RIPPLO_TESTING === "true"`) so the endpoints never ship to production. When `enabled` is false the adapter mounts a no-op handler.
+
+All adapters take the `engine` produced by `createEngine(ripplo, impls)` — not the bare `ripplo` instance.
 
 ### Express
 
 ```ts
 import express from "express";
 import { createExpressHandler } from "@ripplo/testing/express";
-import ripplo from "<path to .ripplo/ripplo>"; // import the existing instance — never call createRipplo() outside .ripplo/ripplo.ts
+import { engine } from "./test/engine.js";
 
 const app = express();
 app.use(
   "/ripplo",
-  createExpressHandler({ enabled: process.env.ENABLE_RIPPLO_TESTING === "true", ripplo }),
+  createExpressHandler({
+    enabled: process.env.ENABLE_RIPPLO_TESTING === "true",
+    engine,
+  }),
 );
 ```
 
-Mounts both `PUT /execute-preconditions` and `PUT /teardown-preconditions` under the prefix you choose.
-
 ### Fastify
 
 ```ts
 import Fastify from "fastify";
 import { registerFastifyHandler } from "@ripplo/testing/fastify";
-import ripplo from "<path to .ripplo/ripplo>"; // import the existing instance — never call createRipplo() outside .ripplo/ripplo.ts
+import { engine } from "./test/engine.js";
 
 const app = Fastify();
 await app.register(
-  registerFastifyHandler({ enabled: process.env.ENABLE_RIPPLO_TESTING === "true", ripplo }),
+  registerFastifyHandler({
+    enabled: process.env.ENABLE_RIPPLO_TESTING === "true",
+    engine,
+  }),
   { prefix: "/ripplo" },
 );
 ```
@@ -387,34 +472,28 @@ The Next.js adapter exports a single catch-all handler. Create one dynamic route
 ```ts
 // app/ripplo/[action]/route.ts
 import { createNextHandler } from "@ripplo/testing/nextjs";
-import ripplo from "@/.ripplo/ripplo";
+import { engine } from "@/server/test/engine";
 
 export const PUT = createNextHandler({
   enabled: process.env.ENABLE_RIPPLO_TESTING === "true",
-  ripplo,
+  engine,
 });
 ```
 
-The handler dispatches on the last URL segment (`execute-preconditions` or `teardown-preconditions`) and returns 404 for anything else. It depends only on the Web `Request` / `Response` types, so it runs on both the Node and Edge runtimes — no `next` import required.
+The handler dispatches on the last URL segment (`execute-preconditions`, `execute-observer`, `teardown-preconditions`) and returns 404 for anything else. It depends only on the Web `Request` / `Response` types, so it runs on both the Node and Edge runtimes — no `next` import required.
 
 ### Custom integration (raw engine)
 
-If your framework isn't covered above (Hono, Koa, Bun, Deno, Cloudflare Workers, etc.), use the raw engine directly. The adapters are thin wrappers over the same API.
+If your framework isn't covered above (Hono, Koa, Bun, Deno, Cloudflare Workers, etc.), use the engine directly. The adapters are thin wrappers over the same API.
 
 ```ts
-import {
-  buildSetCookieHeader,
-  createEngine,
-  serializeCookie,
-  verifyWebhookSignature,
-} from "@ripplo/testing";
-import ripplo from "<path to .ripplo/ripplo>"; // import the existing instance — never call createRipplo() outside .ripplo/ripplo.ts
+import { buildSetCookieHeader, serializeCookie, verifyWebhookSignature } from "@ripplo/testing";
+import { engine } from "./test/engine.js";
 
-const engine = createEngine(ripplo);
-const webhookSecret = ripplo.getConfig().webhookSecret;
+const webhookSecret = engine.getConfig().webhookSecret;
 
 // PUT /ripplo/execute-preconditions
-async function executeBatch(req: Request): Promise<Response> {
+async function executePreconditions(req: Request): Promise<Response> {
   const body = await req.text();
   const verified = verifyWebhookSignature(
     body,
@@ -431,7 +510,7 @@ async function executeBatch(req: Request): Promise<Response> {
 
   const { preconditions } = JSON.parse(body);
   const appUrl = `${req.headers.get("x-forwarded-proto") ?? "http"}://${req.headers.get("host")}`;
-  const result = await engine.executeBatch(preconditions, { appUrl });
+  const result = await engine.executePreconditions(preconditions, { appUrl });
 
   const headers = new Headers({ "content-type": "application/json" });
   result.cookies.forEach((c) => {
@@ -440,69 +519,17 @@ async function executeBatch(req: Request): Promise<Response> {
   return new Response(JSON.stringify(result), { headers });
 }
 
-// PUT /ripplo/teardown
-async function teardown(req: Request): Promise<Response> {
-  // ... same verify pattern, then:
-  // await engine.teardown(parsed.preconditions, parsed.data);
-}
+// PUT /ripplo/teardown-preconditions — same verify pattern, then engine.teardown(...)
+// PUT /ripplo/execute-observer      — same verify pattern, then engine.executeObserver(...)
 ```
 
 **You're responsible for:**
 
 - **Webhook verification.** Always call `verifyWebhookSignature` before invoking the engine.
-- **Routing.** Dispatch the two endpoints (`execute-preconditions`, `teardown-preconditions`) however your framework handles routes.
+- **Routing.** Dispatch the three endpoints (`execute-preconditions`, `execute-observer`, `teardown-preconditions`) however your framework handles routes.
 - **Cookie forwarding.** `result.cookies` contains the cookies preconditions set during setup — they must reach the test browser as `Set-Cookie` headers, or login/session preconditions will silently fail.
 - **Body parsing.** Use the raw text body for signature verification, then `JSON.parse` for the engine call.
 
-### Config
-
-After mounting, point Ripplo at the prefix:
-
-```ts
-// .ripplo/ripplo.ts
-import { createRipplo } from "@ripplo/testing";
-
-export default createRipplo({
-  appUrl: process.env.APP_URL,
-  engineUrl: `${process.env.APP_URL}/ripplo`,
-  projectId: "...",
-  webhookSecret: process.env.RIPPLO_WEBHOOK_SECRET,
-});
-```
-
-## Precondition API Contract
-
-The app server exposes two endpoints for test data management:
-
-### Execute (`PUT {engineBaseUrl}/execute`)
-
-```json
-// Request
-{ "precondition": "data:project" }
-
-// Response
-{ "success": true, "data": { "projectId": "cuid-abc", "orgId": "org-xyz" } }
-```
-
-Returns data that flows into test variables. Set-Cookie headers are captured automatically.
-
-### Teardown (`PUT {engineBaseUrl}/teardown`)
-
-```json
-// Request
-{ "preconditions": ["auth:logged-in", "data:project"] }
-
-// Response
-{ "success": true }
-```
-
-### Parallel Safety
-
-- Generate unique names/emails per run using `crypto.randomUUID()` suffixes
-- Return created entity IDs in the `data` response
-- Teardown only deletes that run's data (use session cookies to identify user)
-- Never hardcode entity names or use bulk deletion
-
 ### Webhook Signing
 
 All requests are signed using Standard Webhooks (HMAC-SHA256). Headers: `webhook-id`, `webhook-timestamp`, `webhook-signature`. Verify before executing.
@@ -510,3 +537,10 @@ All requests are signed using Standard Webhooks (HMAC-SHA256). Headers: `webhook
 ### Environment Guard
 
 Wrap all precondition routes behind `ENABLE_RIPPLO_TESTING=true`. Never expose in production.
+
+### Parallel Safety
+
+- Use `ctx.uniqueId(prefix)` / `ctx.uniqueEmail()` in precondition setup so names/emails don't collide across parallel runs
+- Return created entity IDs in the data contract so teardown can scope deletion precisely
+- Teardown only deletes that run's data (use the `runId` captured at setup)
+- Never hardcode entity names or use bulk deletion

package/dist/assert.d.ts

@@ -1,4 +1,4 @@
-import { O as ObserverHandle, a as ObserverInput, b as ObserverBudgetTier } from './types-oYS_Yv4G.js';
+import { O as ObserverHandle, a as ObserverInput, b as ObserverBudgetTier } from './types-yIhY8cwG.js';
 import { U as UnlabeledStep } from './step-De52hTLd.js';
 import { CheckLocator, AnyLocator } from './locators.js';
 import 'zod';

package/dist/assert.js

@@ -1,13 +1,13 @@
 import {
   toSpecLocator
 } from "./chunk-2VUWFRR5.js";
-import {
-  createStep
-} from "./chunk-MGATMMCZ.js";
 import {
   readObserverBudget,
   readObserverName
-} from "./chunk-3IL457A7.js";
+} from "./chunk-P4ZI7G5M.js";
+import {
+  createStep
+} from "./chunk-MGATMMCZ.js";
 import "./chunk-DCJBLS2U.js";
 
 // src/steps/assert.ts