@shivaedev/test-story 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.7.0 - 2026-10-18
+
+### Added
+
+- `fakeHttpService` serves a scoped loopback API for story kits, with named path-param routes, an auth guard, JSON pages, one-shot replies, request holds and an ordered request log. Bind `narrate(story.tell)` to tell requests and controls in the story.
+
+### Changed
+
+- Point application story authors to the shared `story-testing` skill and align README guidance with observable results, explicit assertions and database isolation.
+
+## 0.6.0 - 2026-10-18
+
+### Added
+
+- Let the OTLP receiver's status callback return `undefined` to withhold response headers, or set `answer: null` to send headers without completing the body.
+
 ## 0.5.0 - 2026-10-17
 
 ### Added

package/README.md

@@ -41,6 +41,8 @@ The first line is the assertion's own message. The box under it tells a reader w
 
 ## Using it
 
+Before writing or reviewing application stories, follow the [story-testing skill](https://github.com/ShivaeDev/platform/blob/main/packages/skills/skills/story-testing/SKILL.md), shipped by `@shivaedev/skills`. It owns the rules for observable evidence, boundary-driven setup, verbs and readouts, assertions, jobs, framework gaps, faked preconditions, database isolation and focused runs. The examples below explain this package's API; framework fixtures exercise this package's responsibilities, rather than prescribe application scenarios.
+
 ### How to think about it
 
 An application has an **engine**: the real thing a test drives, such as a bakery simulation, a game store or a service with its database. A **story** is one test's run of a fresh engine. It starts from **traits**, sentences of setup in domain words that each change the engine, and goes on through **verbs**, the entry points a user or caller reaches, such as `baker.kneads(2)` or `oven.bakesEverything()`. The engine may also run on its own, one **step** at a time, until something the test waits for holds. Every trait tells a line, and verbs and steps tell what they do, so the story is both the plan the test gave and the trace of what happened, in order.
@@ -220,6 +222,44 @@ expect(receiver.requests.some(({ body }) => body.includes(Buffer.from("planted-s
 
 `exportWork` is the kit's verb that runs application work and flushes its exporter. The receiver accepts OTLP/HTTP JSON and protobuf. `spans` flattens all exports into decoded trace and span IDs, parent span IDs, names, numeric OTLP kinds and status codes, attributes, events and links. Attributes retain OTLP key/value objects, including lossless decimal strings for integers; each span also has `resourceAttributes`. `requests` retains every request's unmodified `body` Buffer, parsed `headers`, original `rawHeaders` pairs and `path`. Search all body bytes when checking that a secret was not exported. Optional `path`, `status` (a number or attempt callback) and `answer` configure collector responses for failure stories.
 
+For timeout stories, return `undefined` from the `status` callback to accept an export without sending response headers. Set `answer: null` to send headers without completing the response body.
+
+#### Faking an outbound HTTP API
+
+Use `fakeHttpService` from `@shivaedev/test-story/fakeHttpService.ts` in a kit's scoped `create` hook. Like the OTLP receiver, it listens on an allocated loopback port and closes with the scope. Routes have names for controls, a method (default `GET`), and a path whose `:segments` become decoded `request.params`. A reply receives the request and returns a JSON `body`, optional `status` (default 200), and optional response `headers`.
+
+```ts
+import { fakeHttpService } from "@shivaedev/test-story/fakeHttpService.ts";
+
+const api = yield* fakeHttpService({
+  guard: ({ headers }) => headers.authorization === "Bearer story-key",
+  routes: {
+    user: { path: "/users/:id", reply: ({ params }) => ({ body: { id: params.id } }) },
+    items: { path: "/items", pages: [["paper", "ink"], ["pens"]] },
+  },
+});
+```
+
+Point the application's real HTTP client at `api.url`, or use the kit's `outbound` map to route its external hostname there. A service-wide `guard` returns a boolean; a missing or wrong credential gets 401 before holds or scripted replies are consumed. Omit the guard for a public fake. Unmatched paths and methods get 404.
+
+In `verbs`, bind `api.narrate(story.tell)` to tell received requests, replies, rejections and hold controls through the story. An optional `tell` callback can also be supplied at acquisition. The service keeps request headers and bytes in its log; narration of normal requests includes only method, path and status.
+
+```ts
+api.narrate(story.tell);
+yield* api.failOnce("user", { status: 502, body: { error: "try again" } });
+const paused = yield* api.hold("user");
+const pending = yield* Effect.forkChild(application.loadUser("alice"));
+yield* paused.waiting;
+yield* paused.release;
+const user = yield* Fiber.join(pending);
+```
+
+`application.loadUser` is the application's real client call. `failOnce` affects the next authorized matching request to that named route, then the route answers normally. `hold` pauses that route until `release`; `waiting` completes when a request reaches the hold, so a story needs no polling to know when to release it. Other routes still answer. Effects that wait for HTTP should use a live-clock kit.
+
+A `pages` route accepts a one-based `?page=` query and returns `{ items, next }`, with `next: null` on the last page. No query means page 1; a page past the end returns an empty list; a non-positive or non-integer page gets 400. `api.requests` reads a snapshot of the request log, including rejected and held requests, with `method`, `path` (including query), raw `body` Buffer, `headers`, `params` and `query`.
+
+The [fake HTTP stories](https://github.com/ShivaeDev/platform/blob/main/packages/test-story/src/server/outboundApi.spec.ts) use Node fetch to check params, credentials, pages, one-shot failure, hold/release ordering, request logs, narration and listener cleanup.
+
 ### 2. Once per feature: traits and verbs
 
 A trait is a line and a change, tagged with a stage:
@@ -328,6 +368,14 @@ After the engine has been created, a failing story test adds the story to its fi
 
 The package wraps between words or JSON fields toward 120 columns and prints the story's own lines whole. An indivisible word, field or rerun command component can exceed that width. A passing test adds nothing. A typed failure with no message, such as an `after` hook's `NoBowls`, prints by its tag.
 
+### Library package kits
+
+A library package has an engine too: its own services or Layer under test. Keep its kit in `src/test-support/`, acquire the real services in `create` with their dependencies supplied by the kit's `layer`, and use real PostgreSQL wherever the package touches it. Traits seed that engine in domain words; verbs call the package's public API. The same division applies as for an application: the kit owns setup and wiring, and a spec names traits, calls verbs and checks results. Following the [root test guidance](https://github.com/ShivaeDev/platform/blob/main/AGENTS.md), reserve plain Vitest tests for pure functions with no engine behind them.
+
+The [`backfill` kit](https://github.com/ShivaeDev/platform/blob/main/packages/effect-test-sql/src/test-support/migrationStory.ts) in `effect-test-sql` is a library example. Its `create` returns the package's `migrationSteps(migrations)` API, its worker Layer provides PostgreSQL, and `around: withIsolatedDatabase` isolates each story. The `oldSchema` and `existingContacts` traits put contacts with email addresses into the old schema; the `backfill` verb calls `steps.migrateToLatest`. Its [story](https://github.com/ShivaeDev/platform/blob/main/packages/effect-test-sql/src/server/migrationStory.spec.ts) proves that those existing addresses survive the migration into a new table. It runs only when `PLATFORM_EFFECT_TEST_SQL_TEST_DATABASE_URL` is configured; a skipped story proves nothing.
+
+A fake belongs only at a true external boundary, wired in `create`; keep the package's own engine real. The [resume kit](https://github.com/ShivaeDev/platform/blob/main/packages/effect-contract/src/test-support/resumeStory.ts), for example, creates synthetic browser and native event sources while running the package's real `resumeSignal` API. Its [stories](https://github.com/ShivaeDev/platform/blob/main/packages/effect-contract/src/resume.dom.test.ts) exercise refresh on those events and listener cleanup. Those synthetic sources prove the package's response to events, not a physical browser or native application's event delivery.
+
 ### Whole-stack application kits
 
 Keep one kit in the application’s `test-support/`. `effect-test` owns Vitest registration, worker Layer acquisition, the per-test Scope, cancellation and clock selection. `test-story` owns engine creation, staged traits, verbs and narration. The application owns database lifecycle, migrations, isolation, seeds, actual server/client wiring and screen interactions.
@@ -336,29 +384,9 @@ Set `runIf: hasPostgres` in the kit definition to gate all its stories once, whe
 
 The [order feature kit](https://github.com/ShivaeDev/platform/tree/main/packages/effect-react/src/test-support/order-example) runs the existing feature’s services, repository, contracts, JSON serialization and authentication middleware over a loopback HTTP listener. Its [stories](https://github.com/ShivaeDev/platform/blob/main/packages/effect-react/src/orderStory.dom.spec.tsx) test visible commits through a separate PostgreSQL pool, rollback of a rejected write without publication, cross-owner rejection, a native React action refreshing a list, and an editor retaining rejected input before a corrected save.
 
-```ts
-import { app, realPostgres } from "./test-support/application.ts";
-import { aliceHasOrder } from "./test-support/traits.ts";
-
-app.it("a save commits and a rejected write leaves storage intact", [realPostgres(), aliceHasOrder("paper")], function* ({ saveOrder, rejectOrder, storedOrderIs, changesAre }) {
-  yield* saveOrder("paper", "Office chairs", 8);
-  yield* storedOrderIs("paper", "Office chairs", 8);
-  yield* rejectOrder("paper", -1);
-  yield* storedOrderIs("paper", "Office chairs", 8);
-  yield* changesAre(1);
-});
-```
-
-The application’s worker Layer leases a uniquely named disposable database, opens native PgClient pools and runs `migratePostgres`. Multiple kits in the worker share the database; the last lease drops it after the pools close. The PostgreSQL trait checks that infrastructure and the declared policy; it does not start a database. The application validates its local disposable destination before database creation or reset and skips database stories without `PLATFORM_EFFECT_SQL_TEST_DATABASE_URL`. Tests sharing that database run serially; parallelism belongs between workers or inside one story.
-
-| Application mode | Reset policy | Transaction policy | Coverage |
-| --- | --- | --- | --- |
-| HTTP | Truncate application tables and restart identities before and after the story; retain the migration ledger. | Commands perform real commits. | RPC serialization/transport, independent persistence reads, React refresh and forms. |
-| Local | Reset the baseline before and after the story. | Wrap creation, seeds and body in an outer Platform `transact`, then force rollback after success with a private sentinel. | Local repositories and services, transactional seeds and nested writes. |
+For full-app stories, use `around: withIsolatedDatabase` from `@shivaedev/effect-test-sql/withIsolatedDatabase.ts` with a PostgreSQL test layer prepared from the application's migrations. Each story gets a database cloned from that template, and HTTP and worker pools commit into the same clone. The clone is dropped after scoped hosts and pools close. The starter's [application kit](https://github.com/ShivaeDev/platform/blob/main/examples/starter/src/test-support/application.ts) uses this isolation path.
 
-The kit’s `around` implements that policy. HTTP requests run in separate fibers, so an outer test transaction cannot isolate their writes. Local rollback starts with Platform `transact`; putting it inside a native outer transaction violates transaction ownership. Catch only the wrapper’s private rollback sentinel, let other failures escape, and check independent storage before cleanup truncation so cleanup cannot hide an accidental commit.
-
-Application-authored seed builders reuse application schemas, validate overrides, insert actual rows and return generated values. Traits retain aliases such as `"paper"` so specs avoid generated IDs. There is no shared factory or automatic relationship seeding.
+For repository-level tests on a migrated template, `withTestTransaction` from `@shivaedev/effect-test-sql/withTestTransaction.ts` provides rollback isolation when all work uses its transaction connection. See the [database test helpers](https://github.com/ShivaeDev/platform/blob/main/packages/effect-test-sql/README.md) for template preparation and both wrappers.
 
 React screen traits acquire roots in Scope and use a fresh native atom registry for each screen. Cleanup unmounts roots before disposing registries and servers. Screen verbs dispatch DOM events and use bounded observations of rendered output. Select a live clock once on an HTTP/DOM kit; keep TestClock for deterministic local stories. `runUntil` is for engines with a meaningful step hook, not HTTP or DOM polling. Creation forms can use the same pattern with the existing `useCreate` path.
 
@@ -405,22 +433,7 @@ const cookieApp = storyKit({
 });
 ```
 
-`startHost`, `postgres` and `authVerbs` are application plumbing. The starter's [cookie application kit](https://github.com/ShivaeDev/platform/blob/main/examples/starter/src/test-support/cookieApp.ts) shows the full setup. Its Better Auth client signs up and signs in, and its verbs read `/api/auth/get-session` and post to `/api/auth/sign-out` through the DOM fetch. They do not copy cookies into request headers or use bearer tokens.
-
-```ts
-cookieApp.it("sign-up and sign-in keep their cookie sessions against the PostgreSQL host", [], function* ({ signUp, signIn, signOut, sessionIs }) {
-  yield* signUp();
-  yield* sessionIs("alice@starter.test");
-  yield* signOut();
-  yield* sessionIs(null);
-  yield* signIn();
-  yield* sessionIs("alice@starter.test");
-  yield* signOut();
-  yield* sessionIs(null);
-});
-```
-
-This story proves Better Auth cookie sessions across real loopback HTTP requests from happy-dom with an in-process PostgreSQL host. It also reads sessions through Better Auth's client and checks the fetch response's status, headers and JSON body.
+`startHost`, `postgres` and `authVerbs` are application plumbing. Actions in `authVerbs` perform requests, and readouts return response data for assertions in the spec. A sign-in story drives its real sign-in flow; feature stories start from a faked signed-in precondition as described in the shared skill.
 
 #### Social sign-in through an outbound provider
 
@@ -440,20 +453,23 @@ const socialApp = storyKit({
       await engine.screen.click();
       await domNavigate();
     }),
-    signedInPageIs: (email: string) => Effect.promise(async () => {
-      expect(document.querySelector("h1")?.textContent).toBe(`Signed in as ${email}`);
-      expect(await (await engine.fetch("/api/auth/get-session")).json()).toMatchObject({ user: { email } });
-    }),
+    signedInPage: () => Effect.promise(async () => ({
+      heading: document.querySelector("h1")?.textContent,
+      session: await (await engine.fetch("/api/auth/get-session")).json(),
+    })),
   }),
 });
 
-socialApp.it("a social sign-in returns with a cookie session", [], function* ({ signInWithGitHub, signedInPageIs }) {
+socialApp.it("a social sign-in returns with a cookie session", [], function* ({ signInWithGitHub, signedInPage }) {
   yield* signInWithGitHub();
-  yield* signedInPageIs("alice@social.test");
+  expect(yield* signedInPage()).toMatchObject({
+    heading: "Signed in as alice@social.test",
+    session: { user: { email: "alice@social.test" } },
+  });
 });
 ```
 
-`socialDefinition` starts the host and renders the screen with a Better Auth client whose `customFetchImpl` is `domFetch(baseUrl)`. The [story](https://github.com/ShivaeDev/platform/blob/main/examples/starter/src/server/socialSessions.dom.spec.ts) also checks the authorize, token and user requests at the fake, persisted PostgreSQL rows, and an HttpOnly session cookie read through a later document request. It does not copy cookies into request headers.
+`socialDefinition` starts the host and renders the screen with a Better Auth client whose `customFetchImpl` is `domFetch(baseUrl)`. The authorize, token and user requests at the fake and a later session response provide evidence across the provider and application boundaries. It does not copy cookies into request headers.
 
 `domFetch` uses the current window and its cookie jar; it does not isolate multiple users. Run stories using that window serially, and let the application's cleanup end its sessions, restore the page location and close its host. Cookies follow hostnames, not listener ports, so a different loopback port alone does not isolate accounts.
 
@@ -468,6 +484,8 @@ Import each module with the prefix `@shivaedev/test-story/`; there is no root en
 | `domNavigate.ts` | `domNavigate(url?)` |
 | `genreTags.ts` | `genreTags(...kitNames)`, `GenreTag` |
 | `domEnvironment.config.ts` | Default Vitest environment preserving Node host globals and happy-dom document transport |
+| `fakeHttpService.ts` | `fakeHttpService(options)`, `FakeHttpRoute`, `FakeHttpRequest`, `FakeHttpReply`, `FakeHttpHold`, `FakeHttpServiceOptions` |
+| `otlpReceiver.ts` | `otlpReceiver(options?)`, `OtlpSpan`, `OtlpExport`, `OtlpReceiverOptions` |
 
 ### Install and limits
 

package/dist/server/fakeHttpService.d.ts

@@ -0,0 +1,42 @@
+import { type IncomingHttpHeaders } from "node:http";
+import { Effect } from "effect";
+export interface FakeHttpRequest {
+    readonly body: Buffer;
+    readonly headers: IncomingHttpHeaders;
+    readonly method: string;
+    readonly params: Readonly<Record<string, string>>;
+    readonly path: string;
+    readonly query: URLSearchParams;
+}
+export interface FakeHttpReply {
+    readonly body?: unknown;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly status?: number;
+}
+export type FakeHttpRoute = {
+    readonly method?: string;
+    readonly path: string;
+} & ({
+    readonly reply: (request: FakeHttpRequest) => FakeHttpReply;
+    readonly pages?: never;
+} | {
+    readonly pages: readonly (readonly unknown[])[];
+    readonly reply?: never;
+});
+export interface FakeHttpServiceOptions {
+    readonly guard?: (request: FakeHttpRequest) => boolean;
+    readonly routes: Readonly<Record<string, FakeHttpRoute>>;
+    readonly tell?: (line: string) => void;
+}
+export interface FakeHttpHold {
+    readonly release: Effect.Effect<void>;
+    readonly waiting: Effect.Effect<void>;
+}
+export declare const fakeHttpService: (options: FakeHttpServiceOptions) => Effect.Effect<{
+    failOnce: (route: string, reply: FakeHttpReply) => Effect.Effect<void, never, never>;
+    hold: (route: string) => Effect.Effect<FakeHttpHold, never, never>;
+    narrate: (sink: (line: string) => void) => void;
+    readonly requests: readonly FakeHttpRequest[];
+    url: string;
+}, import("effect/Cause").UnknownError, import("effect/Scope").Scope>;
+//# sourceMappingURL=fakeHttpService.d.ts.map

package/dist/server/fakeHttpService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fakeHttpService.d.ts","sourceRoot":"","sources":["../../src/server/fakeHttpService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACnE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAKhC,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;CAChC;AAED,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,aAAa,GAAG;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB,GAAG,CACD;IAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,aAAa,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,GACvF;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,CAC7E,CAAC;AAEF,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC;IACvD,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;IACzD,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;CACtC;AAED,eAAO,MAAM,eAAe;sBAgBR,MAAM,SAAS,aAAa;kBAChC,MAAM;oBACJ,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI;uBAGtB,SAAS,eAAe,EAAE;;qEAK1C,CAAC"}

package/dist/server/fakeHttpService.js

@@ -0,0 +1,33 @@
+import { createServer } from "node:http";
+import { Effect } from "effect";
+import { fakeHttpControls } from "#internal/fakeHttpControls.ts";
+import { fakeHttpReceive } from "#internal/fakeHttpReceive.ts";
+import { loopbackServer } from "#internal/loopback.ts";
+export const fakeHttpService = Effect.fnUntraced(function* (options) {
+    const requests = [];
+    let narrate = options.tell;
+    function tell(line) {
+        narrate?.(line);
+    }
+    const controls = fakeHttpControls(tell);
+    const server = createServer((request, response) => fakeHttpReceive(request, response, options, requests, controls, tell));
+    const url = yield* loopbackServer(server);
+    yield* Effect.addFinalizer(() => Effect.sync(controls.close));
+    function checkRoute(route) {
+        if (!Object.hasOwn(options.routes, route)) {
+            throw new Error(`Unknown fake HTTP route "${route}".\nhelp: Use a name from fakeHttpService's routes when scripting a reply or hold.`);
+        }
+    }
+    return {
+        failOnce: (route, reply) => Effect.sync(() => checkRoute(route)).pipe(Effect.andThen(controls.failOnce(route, reply))),
+        hold: (route) => Effect.sync(() => checkRoute(route)).pipe(Effect.andThen(controls.hold(route))),
+        narrate: (sink) => {
+            narrate = sink;
+        },
+        get requests() {
+            return requests.slice();
+        },
+        url,
+    };
+});
+//# sourceMappingURL=fakeHttpService.js.map

package/dist/server/fakeHttpService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fakeHttpService.js","sourceRoot":"","sources":["../../src/server/fakeHttpService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAA4B,MAAM,WAAW,CAAC;AACnE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAoCvD,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,OAA+B;IAC1F,MAAM,QAAQ,GAAsB,EAAE,CAAC;IACvC,IAAI,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAC3B,SAAS,IAAI,CAAC,IAAY;QACzB,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC;IACD,MAAM,QAAQ,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,YAAY,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,EAAE,CAAC,eAAe,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;IAC1H,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;IAC1C,KAAK,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9D,SAAS,UAAU,CAAC,KAAa;QAChC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC;YAC3C,MAAM,IAAI,KAAK,CAAC,4BAA4B,KAAK,oFAAoF,CAAC,CAAC;QACxI,CAAC;IACF,CAAC;IACD,OAAO;QACN,QAAQ,EAAE,CAAC,KAAa,EAAE,KAAoB,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;QAC7I,IAAI,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QACxG,OAAO,EAAE,CAAC,IAA4B,EAAE,EAAE;YACzC,OAAO,GAAG,IAAI,CAAC;QAChB,CAAC;QACD,IAAI,QAAQ;YACX,OAAO,QAAQ,CAAC,KAAK,EAAE,CAAC;QACzB,CAAC;QACD,GAAG;KACH,CAAC;AACH,CAAC,CAAC,CAAC"}

package/dist/server/internal/fakeHttpControls.d.ts

@@ -0,0 +1,10 @@
+import { Effect } from "effect";
+import type { FakeHttpHold, FakeHttpReply } from "#fakeHttpService.ts";
+export declare function fakeHttpControls(tell: (line: string) => void): {
+    close: () => void;
+    failOnce: (route: string, reply: FakeHttpReply) => Effect.Effect<void, never, never>;
+    hold: (route: string) => Effect.Effect<FakeHttpHold>;
+    pause: (route: string) => Promise<void>;
+    takeFailure: (route: string) => FakeHttpReply | undefined;
+};
+//# sourceMappingURL=fakeHttpControls.d.ts.map

package/dist/server/internal/fakeHttpControls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fakeHttpControls.d.ts","sourceRoot":"","sources":["../../../src/server/internal/fakeHttpControls.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEvE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI;IAI3D,KAAK;IAKL,QAAQ,UAAU,MAAM,SAAS,aAAa;IAO9C,IAAI,UAAU,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC;IA0BlD,KAAK,UAAgB,MAAM;IAG3B,WAAW,UAAU,MAAM;EAE5B"}

package/dist/server/internal/fakeHttpControls.js

@@ -0,0 +1,48 @@
+import { Deferred, Effect } from "effect";
+export function fakeHttpControls(tell) {
+    const failures = new Map();
+    const holds = new Map();
+    return {
+        close: () => {
+            for (const hold of holds.values()) {
+                hold.release();
+            }
+        },
+        failOnce: (route, reply) => Effect.sync(() => {
+            const queue = failures.get(route) ?? [];
+            queue.push(reply);
+            failures.set(route, queue);
+            tell(`fake HTTP ${route} will answer once with ${reply.status ?? 200}`);
+        }),
+        hold: (route) => Effect.sync(() => {
+            if (holds.has(route)) {
+                throw new Error(`Fake HTTP route "${route}" is already held.\nhelp: Release its current hold before holding the route again.`);
+            }
+            const waiting = Deferred.makeUnsafe();
+            const released = Promise.withResolvers();
+            const hold = {
+                enter: () => {
+                    tell(`fake HTTP ${route} has a waiting request`);
+                    Deferred.doneUnsafe(waiting, Effect.void);
+                    return released.promise;
+                },
+                release: () => {
+                    if (holds.get(route) !== hold) {
+                        return;
+                    }
+                    holds.delete(route);
+                    released.resolve();
+                    tell(`fake HTTP ${route} released`);
+                },
+            };
+            holds.set(route, hold);
+            tell(`fake HTTP ${route} held`);
+            return { release: Effect.sync(hold.release), waiting: Deferred.await(waiting) };
+        }),
+        pause: async (route) => {
+            await holds.get(route)?.enter();
+        },
+        takeFailure: (route) => failures.get(route)?.shift(),
+    };
+}
+//# sourceMappingURL=fakeHttpControls.js.map

package/dist/server/internal/fakeHttpControls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fakeHttpControls.js","sourceRoot":"","sources":["../../../src/server/internal/fakeHttpControls.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAG1C,MAAM,UAAU,gBAAgB,CAAC,IAA4B;IAC5D,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA2B,CAAC;IACpD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAiF,CAAC;IACvG,OAAO;QACN,KAAK,EAAE,GAAG,EAAE;YACX,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;gBACnC,IAAI,CAAC,OAAO,EAAE,CAAC;YAChB,CAAC;QACF,CAAC;QACD,QAAQ,EAAE,CAAC,KAAa,EAAE,KAAoB,EAAE,EAAE,CACjD,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE;YAChB,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;YACxC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAClB,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YAC3B,IAAI,CAAC,aAAa,KAAK,0BAA0B,KAAK,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC,CAAC;QACzE,CAAC,CAAC;QACH,IAAI,EAAE,CAAC,KAAa,EAA+B,EAAE,CACpD,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE;YAChB,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBACtB,MAAM,IAAI,KAAK,CAAC,oBAAoB,KAAK,oFAAoF,CAAC,CAAC;YAChI,CAAC;YACD,MAAM,OAAO,GAAG,QAAQ,CAAC,UAAU,EAAQ,CAAC;YAC5C,MAAM,QAAQ,GAAG,OAAO,CAAC,aAAa,EAAQ,CAAC;YAC/C,MAAM,IAAI,GAAG;gBACZ,KAAK,EAAE,GAAG,EAAE;oBACX,IAAI,CAAC,aAAa,KAAK,wBAAwB,CAAC,CAAC;oBACjD,QAAQ,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;oBAC1C,OAAO,QAAQ,CAAC,OAAO,CAAC;gBACzB,CAAC;gBACD,OAAO,EAAE,GAAG,EAAE;oBACb,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC;wBAC/B,OAAO;oBACR,CAAC;oBACD,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;oBACpB,QAAQ,CAAC,OAAO,EAAE,CAAC;oBACnB,IAAI,CAAC,aAAa,KAAK,WAAW,CAAC,CAAC;gBACrC,CAAC;aACD,CAAC;YACF,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YACvB,IAAI,CAAC,aAAa,KAAK,OAAO,CAAC,CAAC;YAChC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QACjF,CAAC,CAAC;QACH,KAAK,EAAE,KAAK,EAAE,KAAa,EAAE,EAAE;YAC9B,MAAM,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC;QACjC,CAAC;QACD,WAAW,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE;KAC5D,CAAC;AACH,CAAC"}

package/dist/server/internal/fakeHttpReceive.d.ts

@@ -0,0 +1,5 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { FakeHttpRequest, FakeHttpServiceOptions } from "#fakeHttpService.ts";
+import type { fakeHttpControls } from "#internal/fakeHttpControls.ts";
+export declare function fakeHttpReceive(incoming: IncomingMessage, response: ServerResponse, options: FakeHttpServiceOptions, requests: FakeHttpRequest[], controls: ReturnType<typeof fakeHttpControls>, tell: (line: string) => void): Promise<void>;
+//# sourceMappingURL=fakeHttpReceive.d.ts.map

package/dist/server/internal/fakeHttpReceive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fakeHttpReceive.d.ts","sourceRoot":"","sources":["../../../src/server/internal/fakeHttpReceive.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,KAAK,EAAiB,eAAe,EAAiB,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AACjH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAmDtE,wBAAsB,eAAe,CACpC,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,sBAAsB,EAC/B,QAAQ,EAAE,eAAe,EAAE,EAC3B,QAAQ,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,EAC7C,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,iBAoD5B"}

package/dist/server/internal/fakeHttpReceive.js

@@ -0,0 +1,102 @@
+function match(route, method, pathname) {
+    if ((route.method ?? "GET").toUpperCase() !== method) {
+        return;
+    }
+    const pattern = route.path.split("/");
+    const segments = pathname.split("/");
+    if (pattern.length !== segments.length) {
+        return;
+    }
+    const params = {};
+    for (const [index, part] of pattern.entries()) {
+        const segment = segments[index] ?? "";
+        if (part.startsWith(":")) {
+            params[part.slice(1)] = segment;
+        }
+        else if (part !== segment) {
+            return;
+        }
+    }
+    return params;
+}
+function decodeParams(params) {
+    try {
+        for (const [name, value] of Object.entries(params)) {
+            params[name] = decodeURIComponent(value);
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function pageReply(route, request) {
+    if (route.reply) {
+        return route.reply(request);
+    }
+    const page = Number(request.query.get("page") ?? "1");
+    if (!Number.isInteger(page) || page < 1) {
+        return { body: { error: "page must be a positive integer" }, status: 400 };
+    }
+    return { body: { items: route.pages[page - 1] ?? [], next: page < route.pages.length ? page + 1 : null } };
+}
+function send(response, reply) {
+    const body = reply.body === undefined ? undefined : JSON.stringify(reply.body);
+    response.writeHead(reply.status ?? 200, { "content-type": "application/json", ...reply.headers });
+    response.end(body);
+}
+export async function fakeHttpReceive(incoming, response, options, requests, controls, tell) {
+    try {
+        const path = incoming.url ?? "/";
+        const url = new URL(path, "http://127.0.0.1");
+        const method = incoming.method ?? "GET";
+        const found = Object.entries(options.routes).flatMap(([name, route]) => {
+            const params = match(route, method, url.pathname);
+            return params ? [{ name, params, route }] : [];
+        })[0];
+        const chunks = [];
+        for await (const chunk of incoming) {
+            chunks.push(Buffer.from(chunk));
+        }
+        const params = found?.params ?? {};
+        const request = {
+            body: Buffer.concat(chunks),
+            headers: incoming.headers,
+            method,
+            params,
+            path,
+            query: url.searchParams,
+        };
+        requests.push(request);
+        tell(`fake HTTP received ${method} ${path}`);
+        if (!decodeParams(params)) {
+            tell(`fake HTTP rejected ${method} ${path} with 400`);
+            send(response, { status: 400 });
+            return;
+        }
+        if (options.guard && !options.guard(request)) {
+            tell(`fake HTTP rejected ${method} ${path} with 401`);
+            send(response, { status: 401 });
+            return;
+        }
+        if (!found) {
+            tell(`fake HTTP answered ${method} ${path} with 404`);
+            send(response, { status: 404 });
+            return;
+        }
+        await controls.pause(found.name);
+        const reply = controls.takeFailure(found.name) ?? pageReply(found.route, request);
+        tell(`fake HTTP answered ${method} ${path} with ${reply.status ?? 200}`);
+        send(response, reply);
+    }
+    catch (error) {
+        tell(`fake HTTP could not answer: ${String(error)}`);
+        if (response.headersSent) {
+            response.end();
+        }
+        else {
+            send(response, { status: 500 });
+        }
+    }
+}
+//# sourceMappingURL=fakeHttpReceive.js.map

package/dist/server/internal/fakeHttpReceive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fakeHttpReceive.js","sourceRoot":"","sources":["../../../src/server/internal/fakeHttpReceive.ts"],"names":[],"mappings":"AAIA,SAAS,KAAK,CAAC,KAAoB,EAAE,MAAc,EAAE,QAAgB;IACpE,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC,WAAW,EAAE,KAAK,MAAM,EAAE,CAAC;QACtD,OAAO;IACR,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACtC,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,OAAO,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,EAAE,CAAC;QACxC,OAAO;IACR,CAAC;IACD,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;QAC/C,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QACtC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;QACjC,CAAC;aAAM,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;YAC7B,OAAO;QACR,CAAC;IACF,CAAC;IACD,OAAO,MAAM,CAAC;AACf,CAAC;AAED,SAAS,YAAY,CAAC,MAA8B;IACnD,IAAI,CAAC;QACJ,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YACpD,MAAM,CAAC,IAAI,CAAC,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;QAC1C,CAAC;QACD,OAAO,IAAI,CAAC;IACb,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,KAAK,CAAC;IACd,CAAC;AACF,CAAC;AAED,SAAS,SAAS,CAAC,KAAoB,EAAE,OAAwB;IAChE,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QACjB,OAAO,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC;IACtD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;QACzC,OAAO,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,iCAAiC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;IAC5E,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;AAC5G,CAAC;AAED,SAAS,IAAI,CAAC,QAAwB,EAAE,KAAoB;IAC3D,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/E,QAAQ,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,IAAI,GAAG,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IAClG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACpB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CACpC,QAAyB,EACzB,QAAwB,EACxB,OAA+B,EAC/B,QAA2B,EAC3B,QAA6C,EAC7C,IAA4B;IAE5B,IAAI,CAAC;QACJ,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,IAAI,GAAG,CAAC;QACjC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC;QAC9C,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,IAAI,KAAK,CAAC;QACxC,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE;YACtE,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC;YAClD,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAChD,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACN,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;YACpC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QACjC,CAAC;QACD,MAAM,MAAM,GAAG,KAAK,EAAE,MAAM,IAAI,EAAE,CAAC;QACnC,MAAM,OAAO,GAAoB;YAChC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;YAC3B,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,MAAM;YACN,MAAM;YACN,IAAI;YACJ,KAAK,EAAE,GAAG,CAAC,YAAY;SACvB,CAAC;QACF,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvB,IAAI,CAAC,sBAAsB,MAAM,IAAI,IAAI,EAAE,CAAC,CAAC;QAC7C,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,IAAI,CAAC,sBAAsB,MAAM,IAAI,IAAI,WAAW,CAAC,CAAC;YACtD,IAAI,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;YAChC,OAAO;QACR,CAAC;QACD,IAAI,OAAO,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9C,IAAI,CAAC,sBAAsB,MAAM,IAAI,IAAI,WAAW,CAAC,CAAC;YACtD,IAAI,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;YAChC,OAAO;QACR,CAAC;QACD,IAAI,CAAC,KAAK,EAAE,CAAC;YACZ,IAAI,CAAC,sBAAsB,MAAM,IAAI,IAAI,WAAW,CAAC,CAAC;YACtD,IAAI,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;YAChC,OAAO;QACR,CAAC;QACD,MAAM,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACjC,MAAM,KAAK,GAAG,QAAQ,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAClF,IAAI,CAAC,sBAAsB,MAAM,IAAI,IAAI,SAAS,KAAK,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC,CAAC;QACzE,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IACvB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,IAAI,CAAC,+BAA+B,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACrD,IAAI,QAAQ,CAAC,WAAW,EAAE,CAAC;YAC1B,QAAQ,CAAC,GAAG,EAAE,CAAC;QAChB,CAAC;aAAM,CAAC;YACP,IAAI,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;QACjC,CAAC;IACF,CAAC;AACF,CAAC"}

package/dist/server/internal/loopback.d.ts

@@ -0,0 +1,4 @@
+import type { Server } from "node:http";
+import { Effect } from "effect";
+export declare const loopbackServer: (server: Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>) => Effect.Effect<string, import("effect/Cause").UnknownError, import("effect/Scope").Scope>;
+//# sourceMappingURL=loopback.d.ts.map

package/dist/server/internal/loopback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopback.d.ts","sourceRoot":"","sources":["../../../src/server/internal/loopback.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,eAAO,MAAM,cAAc,2LA0BzB,CAAC"}

package/dist/server/internal/loopback.js

@@ -0,0 +1,19 @@
+import { Effect } from "effect";
+export const loopbackServer = Effect.fnUntraced(function* (server) {
+    yield* Effect.acquireRelease(Effect.tryPromise(() => new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            server.off("error", reject);
+            resolve();
+        });
+    })), () => Effect.promise(() => new Promise((resolve, reject) => {
+        server.close((error) => (error ? reject(error) : resolve()));
+        server.closeAllConnections();
+    })));
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+        return yield* Effect.die("Missing loopback HTTP server address.\nhelp: The scoped HTTP server must be listening before reading its URL.");
+    }
+    return `http://127.0.0.1:${address.port}`;
+});
+//# sourceMappingURL=loopback.js.map

package/dist/server/internal/loopback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopback.js","sourceRoot":"","sources":["../../../src/server/internal/loopback.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,MAAc;IACxE,KAAK,CAAC,CAAC,MAAM,CAAC,cAAc,CAC3B,MAAM,CAAC,UAAU,CAChB,GAAG,EAAE,CACJ,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC7B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE;YAClC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAC5B,OAAO,EAAE,CAAC;QACX,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CACH,EACD,GAAG,EAAE,CACJ,MAAM,CAAC,OAAO,CACb,GAAG,EAAE,CACJ,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAC7D,MAAM,CAAC,mBAAmB,EAAE,CAAC;IAC9B,CAAC,CAAC,CACH,CACF,CAAC;IACF,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;IACjC,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QACrD,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,+GAA+G,CAAC,CAAC;IAC3I,CAAC;IACD,OAAO,oBAAoB,OAAO,CAAC,IAAI,EAAE,CAAC;AAC3C,CAAC,CAAC,CAAC"}

package/dist/server/otlpReceiver.d.ts

@@ -9,9 +9,9 @@ export interface OtlpExport {
     readonly rawHeaders: readonly string[];
 }
 export interface OtlpReceiverOptions {
-    readonly answer?: string;
+    readonly answer?: string | null;
     readonly path?: string;
-    readonly status?: number | ((attempt: number) => number);
+    readonly status?: number | ((attempt: number) => number | undefined);
 }
 export declare const otlpReceiver: (options?: OtlpReceiverOptions | undefined) => Effect.Effect<{
     readonly requests: readonly OtlpExport[];

package/dist/server/otlpReceiver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"otlpReceiver.d.ts","sourceRoot":"","sources":["../../src/server/otlpReceiver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,mBAAmB,EAA6C,MAAM,WAAW,CAAC;AAC9G,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAEvD,MAAM,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAC9D,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AACD,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;CACzD;AA0BD,eAAO,MAAM,YAAY;uBAqBa,SAAS,UAAU,EAAE;oBAAkB,SAAS,QAAQ,EAAE;kBAAgB,MAAM;qEAMpH,CAAC"}
+{"version":3,"file":"otlpReceiver.d.ts","sourceRoot":"","sources":["../../src/server/otlpReceiver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,mBAAmB,EAA6C,MAAM,WAAW,CAAC;AAC9G,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAEvD,MAAM,MAAM,QAAQ,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAC9D,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AACD,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC,CAAC;CACrE;AAmCD,eAAO,MAAM,YAAY;uBAKa,SAAS,UAAU,EAAE;oBAAkB,SAAS,QAAQ,EAAE;kBAAgB,MAAM;qEAMpH,CAAC"}

package/dist/server/otlpReceiver.js

@@ -1,5 +1,6 @@
 import { createServer } from "node:http";
 import { Effect } from "effect";
+import { loopbackServer } from "#internal/loopback.ts";
 import { otlpReadout } from "#internal/otlpReadout.ts";
 async function receive(request, response, requests, spans, options) {
     try {
@@ -19,7 +20,17 @@ async function receive(request, response, requests, spans, options) {
             return;
         }
         spans.push(...otlpReadout(body, contentType));
-        response.writeHead(typeof options.status === "function" ? options.status(requests.length) : (options.status ?? 200)).end(options.answer ?? "{}");
+        const status = typeof options.status === "function" ? options.status(requests.length) : (options.status ?? 200);
+        if (status === undefined) {
+            return;
+        }
+        response.writeHead(status);
+        if (options.answer === null) {
+            response.flushHeaders();
+        }
+        else {
+            response.end(options.answer ?? "{}");
+        }
     }
     catch {
         response.writeHead(400).end();
@@ -29,21 +40,11 @@ export const otlpReceiver = Effect.fnUntraced(function* (options = {}) {
     const requests = [];
     const spans = [];
     const server = createServer((request, response) => receive(request, response, requests, spans, options));
-    yield* Effect.acquireRelease(Effect.tryPromise(() => new Promise((resolve, reject) => {
-        server.once("error", reject);
-        server.listen(0, "127.0.0.1", () => {
-            server.off("error", reject);
-            resolve();
-        });
-    })), () => Effect.promise(() => new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())))));
-    const address = server.address();
-    if (address === null || typeof address === "string") {
-        return yield* Effect.die("Missing OTLP receiver address");
-    }
+    const url = yield* loopbackServer(server);
     const receiver = {
         requests,
         spans,
-        url: `http://127.0.0.1:${address.port}`,
+        url,
     };
     return receiver;
 });

package/dist/server/otlpReceiver.js.map

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

package/docs/roadmap.md

@@ -1,9 +1,6 @@
 # Roadmap
 
-This file owns the story kit's implementation, next work and open questions. The
-[framework roadmap](https://github.com/ShivaeDev/platform/blob/main/docs/framework/roadmap.md)
-owns composed application features and host-level validation. Those roadmaps link
-to each other rather than repeating a completion checklist.
+This file owns the story kit's implementation, next work and open questions. The [framework roadmap](https://github.com/ShivaeDev/platform/blob/main/docs/framework/roadmap.md) owns composed application features and host-level validation. Those roadmaps link to each other rather than repeating a completion checklist.
 
 ## Built
 
@@ -13,10 +10,15 @@ to each other rather than repeating a completion checklist.
 - [x] `story.runUntil(condition)`: steps the engine until the condition holds, stops on what `run.failed` reports, and stops after a step budget with a diagnosis, keeping every hook's typed failure in its error channel.
 - [x] A failed test prints a short guide, its story, where it stopped with the spec line there, and the engine's state, inline or in a file under `node_modules/.cache/test-story/`, broken at 120 columns.
 - [x] `domEnvironment` keeps Node fetch classes for an in-process host and happy-dom fetch for the client; `domFetch(baseUrl)` connects the window to that host, with a starter story proving Better Auth sign-up, sign-in, session reads and sign-out on PostgreSQL through cookies.
+- [x] `domNavigate` loads a routed document into happy-dom, updates its location and returns a response whose body remains readable. [Document transport stories](../src/server/documentTransport.dom.spec.ts) assert the rendered heading, location and response body.
+- [x] `outbound` routes exact hostnames to fake HTTP servers while preserving request paths, queries, methods, headers and bodies, and restores Node routing after successful and failed stories. [Outbound stories](../src/server/outbound.spec.ts) assert routing and restoration; [document transport stories](../src/server/documentTransport.dom.spec.ts) cover redirects, cookies and XMLHttpRequest; [DOM refusal tests](../src/server/domOutbound.spec.ts) assert that unrouted external fetches, document requests and redirects fail the story even when application code catches the error.
+- [x] In-process host creation separates request traces from the story span: requests without trace headers get distinct root traces, supplied trace headers continue their trace, request work stays under the request span, and traits and steps stay under the story span. [Host tracing stories](../src/server/hostTracing.spec.ts) assert span parents, trace IDs and completed request spans.
+- [x] Creation, traits and stage `after` hooks can return Effects directly, with services from the kit's Layer and resources released in the story's Scope, covered by [Effect hook stories](../src/server/effectHooks.spec.ts).
+- [x] Kit hooks and steps support a live clock and a per-story TestClock override. [Live-time stories](../src/server/liveTime.spec.ts) cover polling real workers with `withLive` without advancing virtual token expiry.
 
 ## Next
 
-- [ ] Move a first application's hand-written story DSL onto the kit and let what it needs decide the next hook.
+- [ ] Move the Work Fleet engine's hand-written story DSL onto the kit and let what it needs decide the next hook.
 
 ## Open questions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/test-story",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Tests that read like stories over the real engine: a story kit per engine with its own it, traits per feature, and a failure that prints the story, where it stopped and the engine's state",
   "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/test-story#readme",
   "bugs": {
@@ -47,8 +47,8 @@
   },
   "devDependencies": {
     "@effect/vitest": "4.0.4",
-    "@shivaedev/quality": "0.22.0",
-    "@types/node": "24.19.1",
+    "@shivaedev/quality": "0.24.0",
+    "@types/node": "24.19.2",
     "@typescript/native": "npm:typescript@7.0.2",
     "effect": "4.0.4",
     "happy-dom": "20.14.6",

package/src/server/fakeHttpService.ts

@@ -0,0 +1,67 @@
+import { createServer, type IncomingHttpHeaders } from "node:http";
+import { Effect } from "effect";
+import { fakeHttpControls } from "#internal/fakeHttpControls.ts";
+import { fakeHttpReceive } from "#internal/fakeHttpReceive.ts";
+import { loopbackServer } from "#internal/loopback.ts";
+
+export interface FakeHttpRequest {
+	readonly body: Buffer;
+	readonly headers: IncomingHttpHeaders;
+	readonly method: string;
+	readonly params: Readonly<Record<string, string>>;
+	readonly path: string;
+	readonly query: URLSearchParams;
+}
+
+export interface FakeHttpReply {
+	readonly body?: unknown;
+	readonly headers?: Readonly<Record<string, string>>;
+	readonly status?: number;
+}
+
+export type FakeHttpRoute = {
+	readonly method?: string;
+	readonly path: string;
+} & (
+	| { readonly reply: (request: FakeHttpRequest) => FakeHttpReply; readonly pages?: never }
+	| { readonly pages: readonly (readonly unknown[])[]; readonly reply?: never }
+);
+
+export interface FakeHttpServiceOptions {
+	readonly guard?: (request: FakeHttpRequest) => boolean;
+	readonly routes: Readonly<Record<string, FakeHttpRoute>>;
+	readonly tell?: (line: string) => void;
+}
+
+export interface FakeHttpHold {
+	readonly release: Effect.Effect<void>;
+	readonly waiting: Effect.Effect<void>;
+}
+
+export const fakeHttpService = Effect.fnUntraced(function* (options: FakeHttpServiceOptions) {
+	const requests: FakeHttpRequest[] = [];
+	let narrate = options.tell;
+	function tell(line: string) {
+		narrate?.(line);
+	}
+	const controls = fakeHttpControls(tell);
+	const server = createServer((request, response) => fakeHttpReceive(request, response, options, requests, controls, tell));
+	const url = yield* loopbackServer(server);
+	yield* Effect.addFinalizer(() => Effect.sync(controls.close));
+	function checkRoute(route: string) {
+		if (!Object.hasOwn(options.routes, route)) {
+			throw new Error(`Unknown fake HTTP route "${route}".\nhelp: Use a name from fakeHttpService's routes when scripting a reply or hold.`);
+		}
+	}
+	return {
+		failOnce: (route: string, reply: FakeHttpReply) => Effect.sync(() => checkRoute(route)).pipe(Effect.andThen(controls.failOnce(route, reply))),
+		hold: (route: string) => Effect.sync(() => checkRoute(route)).pipe(Effect.andThen(controls.hold(route))),
+		narrate: (sink: (line: string) => void) => {
+			narrate = sink;
+		},
+		get requests(): readonly FakeHttpRequest[] {
+			return requests.slice();
+		},
+		url,
+	};
+});

package/src/server/internal/fakeHttpControls.ts

@@ -0,0 +1,51 @@
+import { Deferred, Effect } from "effect";
+import type { FakeHttpHold, FakeHttpReply } from "#fakeHttpService.ts";
+
+export function fakeHttpControls(tell: (line: string) => void) {
+	const failures = new Map<string, FakeHttpReply[]>();
+	const holds = new Map<string, { readonly enter: () => Promise<void>; readonly release: () => void }>();
+	return {
+		close: () => {
+			for (const hold of holds.values()) {
+				hold.release();
+			}
+		},
+		failOnce: (route: string, reply: FakeHttpReply) =>
+			Effect.sync(() => {
+				const queue = failures.get(route) ?? [];
+				queue.push(reply);
+				failures.set(route, queue);
+				tell(`fake HTTP ${route} will answer once with ${reply.status ?? 200}`);
+			}),
+		hold: (route: string): Effect.Effect<FakeHttpHold> =>
+			Effect.sync(() => {
+				if (holds.has(route)) {
+					throw new Error(`Fake HTTP route "${route}" is already held.\nhelp: Release its current hold before holding the route again.`);
+				}
+				const waiting = Deferred.makeUnsafe<void>();
+				const released = Promise.withResolvers<void>();
+				const hold = {
+					enter: () => {
+						tell(`fake HTTP ${route} has a waiting request`);
+						Deferred.doneUnsafe(waiting, Effect.void);
+						return released.promise;
+					},
+					release: () => {
+						if (holds.get(route) !== hold) {
+							return;
+						}
+						holds.delete(route);
+						released.resolve();
+						tell(`fake HTTP ${route} released`);
+					},
+				};
+				holds.set(route, hold);
+				tell(`fake HTTP ${route} held`);
+				return { release: Effect.sync(hold.release), waiting: Deferred.await(waiting) };
+			}),
+		pause: async (route: string) => {
+			await holds.get(route)?.enter();
+		},
+		takeFailure: (route: string) => failures.get(route)?.shift(),
+	};
+}

package/src/server/internal/fakeHttpReceive.ts

@@ -0,0 +1,112 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { FakeHttpReply, FakeHttpRequest, FakeHttpRoute, FakeHttpServiceOptions } from "#fakeHttpService.ts";
+import type { fakeHttpControls } from "#internal/fakeHttpControls.ts";
+
+function match(route: FakeHttpRoute, method: string, pathname: string) {
+	if ((route.method ?? "GET").toUpperCase() !== method) {
+		return;
+	}
+	const pattern = route.path.split("/");
+	const segments = pathname.split("/");
+	if (pattern.length !== segments.length) {
+		return;
+	}
+	const params: Record<string, string> = {};
+	for (const [index, part] of pattern.entries()) {
+		const segment = segments[index] ?? "";
+		if (part.startsWith(":")) {
+			params[part.slice(1)] = segment;
+		} else if (part !== segment) {
+			return;
+		}
+	}
+	return params;
+}
+
+function decodeParams(params: Record<string, string>) {
+	try {
+		for (const [name, value] of Object.entries(params)) {
+			params[name] = decodeURIComponent(value);
+		}
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function pageReply(route: FakeHttpRoute, request: FakeHttpRequest): FakeHttpReply {
+	if (route.reply) {
+		return route.reply(request);
+	}
+	const page = Number(request.query.get("page") ?? "1");
+	if (!Number.isInteger(page) || page < 1) {
+		return { body: { error: "page must be a positive integer" }, status: 400 };
+	}
+	return { body: { items: route.pages[page - 1] ?? [], next: page < route.pages.length ? page + 1 : null } };
+}
+
+function send(response: ServerResponse, reply: FakeHttpReply) {
+	const body = reply.body === undefined ? undefined : JSON.stringify(reply.body);
+	response.writeHead(reply.status ?? 200, { "content-type": "application/json", ...reply.headers });
+	response.end(body);
+}
+
+export async function fakeHttpReceive(
+	incoming: IncomingMessage,
+	response: ServerResponse,
+	options: FakeHttpServiceOptions,
+	requests: FakeHttpRequest[],
+	controls: ReturnType<typeof fakeHttpControls>,
+	tell: (line: string) => void,
+) {
+	try {
+		const path = incoming.url ?? "/";
+		const url = new URL(path, "http://127.0.0.1");
+		const method = incoming.method ?? "GET";
+		const found = Object.entries(options.routes).flatMap(([name, route]) => {
+			const params = match(route, method, url.pathname);
+			return params ? [{ name, params, route }] : [];
+		})[0];
+		const chunks: Buffer[] = [];
+		for await (const chunk of incoming) {
+			chunks.push(Buffer.from(chunk));
+		}
+		const params = found?.params ?? {};
+		const request: FakeHttpRequest = {
+			body: Buffer.concat(chunks),
+			headers: incoming.headers,
+			method,
+			params,
+			path,
+			query: url.searchParams,
+		};
+		requests.push(request);
+		tell(`fake HTTP received ${method} ${path}`);
+		if (!decodeParams(params)) {
+			tell(`fake HTTP rejected ${method} ${path} with 400`);
+			send(response, { status: 400 });
+			return;
+		}
+		if (options.guard && !options.guard(request)) {
+			tell(`fake HTTP rejected ${method} ${path} with 401`);
+			send(response, { status: 401 });
+			return;
+		}
+		if (!found) {
+			tell(`fake HTTP answered ${method} ${path} with 404`);
+			send(response, { status: 404 });
+			return;
+		}
+		await controls.pause(found.name);
+		const reply = controls.takeFailure(found.name) ?? pageReply(found.route, request);
+		tell(`fake HTTP answered ${method} ${path} with ${reply.status ?? 200}`);
+		send(response, reply);
+	} catch (error) {
+		tell(`fake HTTP could not answer: ${String(error)}`);
+		if (response.headersSent) {
+			response.end();
+		} else {
+			send(response, { status: 500 });
+		}
+	}
+}

package/src/server/internal/loopback.ts

@@ -0,0 +1,30 @@
+import type { Server } from "node:http";
+import { Effect } from "effect";
+
+export const loopbackServer = Effect.fnUntraced(function* (server: Server) {
+	yield* Effect.acquireRelease(
+		Effect.tryPromise(
+			() =>
+				new Promise<void>((resolve, reject) => {
+					server.once("error", reject);
+					server.listen(0, "127.0.0.1", () => {
+						server.off("error", reject);
+						resolve();
+					});
+				}),
+		),
+		() =>
+			Effect.promise(
+				() =>
+					new Promise<void>((resolve, reject) => {
+						server.close((error) => (error ? reject(error) : resolve()));
+						server.closeAllConnections();
+					}),
+			),
+	);
+	const address = server.address();
+	if (address === null || typeof address === "string") {
+		return yield* Effect.die("Missing loopback HTTP server address.\nhelp: The scoped HTTP server must be listening before reading its URL.");
+	}
+	return `http://127.0.0.1:${address.port}`;
+});

package/src/server/otlpReceiver.ts

@@ -1,5 +1,6 @@
 import { createServer, type IncomingHttpHeaders, type IncomingMessage, type ServerResponse } from "node:http";
 import { Effect } from "effect";
+import { loopbackServer } from "#internal/loopback.ts";
 import { otlpReadout } from "#internal/otlpReadout.ts";
 
 export type OtlpSpan = ReturnType<typeof otlpReadout>[number];
@@ -10,9 +11,9 @@ export interface OtlpExport {
 	readonly rawHeaders: readonly string[];
 }
 export interface OtlpReceiverOptions {
-	readonly answer?: string;
+	readonly answer?: string | null;
 	readonly path?: string;
-	readonly status?: number | ((attempt: number) => number);
+	readonly status?: number | ((attempt: number) => number | undefined);
 }
 
 async function receive(request: IncomingMessage, response: ServerResponse, requests: OtlpExport[], spans: OtlpSpan[], options: OtlpReceiverOptions) {
@@ -33,7 +34,16 @@ async function receive(request: IncomingMessage, response: ServerResponse, reque
 			return;
 		}
 		spans.push(...otlpReadout(body, contentType));
-		response.writeHead(typeof options.status === "function" ? options.status(requests.length) : (options.status ?? 200)).end(options.answer ?? "{}");
+		const status = typeof options.status === "function" ? options.status(requests.length) : (options.status ?? 200);
+		if (status === undefined) {
+			return;
+		}
+		response.writeHead(status);
+		if (options.answer === null) {
+			response.flushHeaders();
+		} else {
+			response.end(options.answer ?? "{}");
+		}
 	} catch {
 		response.writeHead(400).end();
 	}
@@ -43,27 +53,11 @@ export const otlpReceiver = Effect.fnUntraced(function* (options: OtlpReceiverOp
 	const requests: OtlpExport[] = [];
 	const spans: OtlpSpan[] = [];
 	const server = createServer((request, response) => receive(request, response, requests, spans, options));
-	yield* Effect.acquireRelease(
-		Effect.tryPromise(
-			() =>
-				new Promise<void>((resolve, reject) => {
-					server.once("error", reject);
-					server.listen(0, "127.0.0.1", () => {
-						server.off("error", reject);
-						resolve();
-					});
-				}),
-		),
-		() => Effect.promise(() => new Promise<void>((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())))),
-	);
-	const address = server.address();
-	if (address === null || typeof address === "string") {
-		return yield* Effect.die("Missing OTLP receiver address");
-	}
+	const url = yield* loopbackServer(server);
 	const receiver: { readonly requests: readonly OtlpExport[]; readonly spans: readonly OtlpSpan[]; readonly url: string } = {
 		requests,
 		spans,
-		url: `http://127.0.0.1:${address.port}`,
+		url,
 	};
 	return receiver;
 });