effect-browser 0.2.0-beta.9 → 0.3.0-beta.11

package/src/internal/page/context.ts

@@ -0,0 +1,314 @@
+/**
+ * What a page's parts share: the browser state they act on, the page's own lane, pointer and
+ * clock, and how they call the browser and report its failures. The assembly in `page.ts` builds
+ * one context per page.
+ */
+import {
+  Clock,
+  Context,
+  Duration,
+  Effect,
+  Fiber,
+  MutableRef,
+  Option,
+  Schema,
+  type Scope,
+} from "effect";
+import type { CDPSession, Page as PlaywrightPage } from "playwright-core";
+
+import type { CaptureSource } from "../../Browser.ts";
+import { BrowserError, Closed, Failed, type Reason, Timeout } from "../../BrowserError.ts";
+import type { BrowserEvent } from "../../BrowserEvent.ts";
+import type { InputGuard, Point } from "../../Page.ts";
+import type { Gate } from "../input/gate.ts";
+import { Current } from "../input/replies.ts";
+import type * as BrowserClock from "../pictures/clock.ts";
+import * as Lane from "./lane.ts";
+import type { Openings } from "./openings.ts";
+import * as Url from "./url.ts";
+
+/** Why a page is gone. */
+export type ClosedCause = Closed["cause"];
+
+/** What every page of a browser shares, from its options. */
+export interface Settings {
+  readonly actionTimeout: Duration.Duration;
+  readonly policyTimeout: Duration.Duration;
+  readonly navigationTimeout: Duration.Duration;
+  /** How long screencast frames stay in `recentFrames`, measured back from the newest. */
+  readonly frameHistory: Duration.Duration;
+  readonly guard: InputGuard | undefined;
+}
+
+export interface MakeOptions {
+  /** The page's CDP target id, which is also its main frame's id. */
+  readonly id: string;
+  /** The id of the browser's session, which its frames carry. */
+  readonly session: string;
+  /** This tracking connection, distinct from the provider session and capture socket. */
+  readonly connection: string;
+  /** The page's address when the browser began tracking it. */
+  readonly url: string;
+  readonly playwright: PlaywrightPage;
+  readonly cdp: CDPSession;
+  /** A call's reply, or a failure as for a closed page once the browser is lost first. */
+  readonly untilLost: <A>(reply: Promise<A>) => Promise<A>;
+  readonly settings: Settings;
+  readonly clock: Clock.Clock;
+  /** Browser-wide input authority; direct internal page fixtures need not provide one. */
+  readonly inputGate?: Gate | undefined;
+  /** The browser's epoch mapping: its first capture measures it, and later ones renew it. */
+  readonly mapping: BrowserClock.Mapping;
+  readonly publish: (event: BrowserEvent) => number;
+  /** This page's retained events, oldest first. */
+  readonly recentEvents: Effect.Effect<ReadonlyArray<BrowserEvent>>;
+  /** Registration of the actual popups this page's current input opened. */
+  readonly openings: Openings;
+  /** Succeeds once the page's own session holds focus emulation, which keeps it painting behind. */
+  readonly focused: Effect.Effect<void, BrowserError>;
+  /** Succeeds once the page's own session has the Page domain on, so it sees every later commit. */
+  readonly paging: (operation: string) => Effect.Effect<void, BrowserError>;
+  /** Why the page is gone, once it is: its browser's loss, else its own close or crash. */
+  readonly closedBy: () => ClosedCause;
+  /** Where the page's screencast runs, if not on its own session. */
+  readonly capture?: CaptureSource | undefined;
+}
+
+const messageOf = (cause: unknown): string =>
+  cause instanceof Error ? cause.message : typeof cause === "string" ? cause : "unknown error";
+
+const closedPattern =
+  /has been closed|Target closed|Session closed|browser has disconnected|Target page, context or browser/i;
+
+/**
+ * Map a Playwright or protocol failure to a reason, `Closed` with `closed` as its cause for a page
+ * or browser that is gone. A call that gives Playwright a timeout passes the same bound, so its
+ * `Timeout` reports it; without one, Playwright's own message stays.
+ */
+export const reasonOf = (
+  cause: unknown,
+  timeoutMillis?: number,
+  closed: ClosedCause = "connection",
+): Reason => {
+  const message = messageOf(cause);
+
+  if (closedPattern.test(message)) return new Closed({ cause: closed });
+  if (cause instanceof Error && cause.name === "TimeoutError" && timeoutMillis !== undefined)
+    return new Timeout({ millis: timeoutMillis });
+  const line = message.split("\n")[0] ?? message;
+
+  return new Failed({ detail: Url.redactWithin(line.replace(/^[\w.]+: /, "")) });
+};
+
+/**
+ * One Playwright or protocol call, failing undispatched. A closed page says why it is gone as the
+ * browser knows then: the library's own calls fail with the browser's loss, and Playwright fails
+ * its calls on a dropped connection after reporting the context closed.
+ */
+export const call = <A>(
+  operation: string,
+  run: () => Promise<A>,
+  closedBy: () => ClosedCause,
+  timeoutMillis?: number,
+) =>
+  Effect.tryPromise({
+    try: run,
+    catch: (cause) => undispatched(operation, reasonOf(cause, timeoutMillis, closedBy())),
+  });
+
+export const contextGone = (error: BrowserError) =>
+  error.reason._tag === "Failed" &&
+  /Cannot find context|Execution context was destroyed|__effectBrowser|Inspected target navigated/i.test(
+    error.reason.detail,
+  );
+
+/**
+ * What a page operation spent on the page's own protocol session: its calls, the bytes of their
+ * parameters and results, and how long at least one of them awaited its reply. An operation inside
+ * another counts toward both.
+ */
+interface Cost {
+  readonly enclosing: Cost | undefined;
+  calls: number;
+  bytesOut: number;
+  bytesIn: number;
+  waitedMillis: number;
+  awaiting: number;
+  awaitingSince: number;
+}
+
+/** The cost of the page operation the current fiber runs, if any. */
+const CurrentCost = Context.Reference<Cost | undefined>(
+  "effect-browser/internal/page/CurrentCost",
+  {
+    defaultValue: () => undefined,
+  },
+);
+
+/** Track the promise returned to the action, after tracing wraps it, so input counts once. */
+const track = <A>(reply: Promise<A>) => Fiber.getCurrent()?.getRef(Current)?.track(reply) ?? reply;
+
+// A message's size on the wire, give or take its envelope.
+const sizeOf = (value: unknown) =>
+  value === undefined ? 0 : Buffer.byteLength(JSON.stringify(value));
+
+/** A failure of `operation` before any of its input reached the browser. */
+export const undispatched = (operation: string, reason: Reason) =>
+  new BrowserError({ operation, reason, dispatched: false });
+
+export const failWith = (operation: string, reason: Reason) =>
+  Effect.fail(undispatched(operation, reason));
+
+export const decodeWith =
+  <A>(operation: string, schema: Schema.Codec<A, unknown>) =>
+  (value: unknown) =>
+    Schema.decodeUnknownEffect(schema)(value).pipe(
+      Effect.mapError((error) => undispatched(operation, new Failed({ detail: error.message }))),
+    );
+
+export const make = (options: MakeOptions, scope: Scope.Scope) => {
+  const { id, clock } = options;
+  const now = () => Number(clock.monotonicTimeNanosUnsafe()) / 1e6;
+  // Deadlines and pacing guard the page's lane, so page operations run on the owner's clock; a
+  // caller's clock, such as a TestClock, cannot stall or stretch them.
+  const owned = Effect.provideService(Clock.Clock, clock);
+
+  // This page's spans name it and report what the operation cost on the protocol. Fine-grained
+  // ones carry a level below the default Info, so an application keeps only the coarse ones by
+  // raising `Tracer.MinimumTraceLevel`.
+  const span =
+    (name: string, attributes: Record<string, unknown> = {}, level?: "Debug" | "Trace") =>
+    <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+      Effect.gen(function* () {
+        const cost: Cost = {
+          enclosing: yield* CurrentCost,
+          calls: 0,
+          bytesOut: 0,
+          bytesIn: 0,
+          waitedMillis: 0,
+          awaiting: 0,
+          awaitingSince: 0,
+        };
+
+        return yield* effect.pipe(
+          Effect.provideService(CurrentCost, cost),
+          Effect.ensuring(
+            Effect.suspend(() =>
+              Effect.annotateCurrentSpan({
+                calls: cost.calls,
+                bytesOut: cost.bytesOut,
+                bytesIn: cost.bytesIn,
+                waitedMillis: Math.round(cost.waitedMillis * 10) / 10,
+              }),
+            ),
+          ),
+        );
+      }).pipe(
+        Effect.withSpan(
+          name,
+          { attributes: { page: id, ...attributes }, ...(level === undefined ? {} : { level }) },
+          { captureStackTrace: false },
+        ),
+      );
+
+  // Every call on the page's own protocol session, counted into the operation that sends it and
+  // the operations around that one. It is looked up when the call is sent, so input pipelined
+  // from inside an operation counts toward it too.
+  const send: CDPSession["send"] = (method, params) => {
+    const cost = Fiber.getCurrent()?.getRef(CurrentCost);
+    const sentAt = now();
+    const bytesOut = sizeOf(params);
+
+    for (let each = cost; each !== undefined; each = each.enclosing) {
+      each.calls++;
+      each.bytesOut += bytesOut;
+      if (each.awaiting++ === 0) each.awaitingSince = sentAt;
+    }
+    const reply = options.untilLost(options.cdp.send(method, params));
+
+    if (cost === undefined) return track(reply);
+
+    const settle = (bytesIn: number) => {
+      const at = now();
+
+      for (let each: Cost | undefined = cost; each !== undefined; each = each.enclosing) {
+        each.bytesIn += bytesIn;
+        if (--each.awaiting === 0) each.waitedMillis += at - each.awaitingSince;
+      }
+    };
+
+    return track(
+      reply.then(
+        (result) => {
+          settle(sizeOf(result));
+
+          return result;
+        },
+        (cause: unknown) => {
+          settle(0);
+
+          return Promise.reject(cause);
+        },
+      ),
+    );
+  };
+
+  // Every protocol or Playwright call. Errors are undispatched here; `perform` marks them
+  // dispatched once input has gone out.
+  const native = <A>(operation: string, run: () => Promise<A>, timeoutMillis?: number) =>
+    call(operation, () => track(run()), options.closedBy, timeoutMillis);
+
+  /** Fail with `Timeout` once `duration` has passed, the action timeout unless another is given. */
+  const within =
+    (operation: string, duration: Duration.Input = options.settings.actionTimeout) =>
+    <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+      Effect.timeoutOrElse(effect, {
+        duration,
+        orElse: () => failWith(operation, new Timeout({ millis: Duration.toMillis(duration) })),
+      });
+
+  // The latest submitted input or page change. A read that must follow it waits for the action in
+  // flight, so only paint from after its latest input is current. An action ends after its input
+  // was handled, so if that input changed the page, newer paint follows; a lost final paint is
+  // bounded by recency instead. Paint from before the current document began, when the page's own
+  // session saw the main frame commit it, shows a page the tab has left, so no read reuses it,
+  // whatever it asks.
+  const activity = { inputAt: 0, documentAt: Number.NEGATIVE_INFINITY };
+
+  const noteInput = () => {
+    activity.inputAt = Math.max(activity.inputAt, now());
+  };
+
+  const lane = Lane.make({
+    now,
+    actionTimeout: options.settings.actionTimeout,
+    documentAt: () => activity.documentAt,
+    gone: (operation) => undispatched(operation, new Closed({ cause: options.closedBy() })),
+    scope,
+    inputGate: options.inputGate,
+  });
+
+  // Where this page's latest move left its pointer, which is where its next plain glide starts and
+  // where a held button is released. Its lane orders the page's input, and Chromium keeps a
+  // pointer per page too.
+  const pointer = MutableRef.make(Option.none<Point>());
+
+  // Named, so that the declarations of what holds it need not spell out Playwright's protocol types.
+  const protocol: Pick<CDPSession, "send"> = { send };
+
+  return {
+    ...options,
+    lane,
+    pointer,
+    now,
+    owned,
+    span,
+    protocol,
+    native,
+    within,
+    activity,
+    noteInput,
+  };
+};
+
+export type PageContext = ReturnType<typeof make>;

package/src/internal/page/identity.ts

@@ -0,0 +1,35 @@
+/** Connection identity uses the supplied Crypto service, or the host's Web Crypto on Node/Bun. */
+import { Crypto, Effect, Option, PlatformError } from "effect";
+
+import { Failed } from "../../BrowserError.ts";
+import { undispatched } from "./context.ts";
+
+// The core owns this tiny platform adapter to keep Chromium/CDP usable without another package
+// or a new required service. Browser construction captures it once; there is no global counter.
+const native = () =>
+  Crypto.make({
+    randomBytes: (size) => globalThis.crypto.getRandomValues(new Uint8Array(size)),
+    digest: (algorithm, data) =>
+      Effect.tryPromise({
+        try: () => globalThis.crypto.subtle.digest(algorithm, new Uint8Array(data)),
+        catch: (cause) =>
+          PlatformError.systemError({
+            module: "Crypto",
+            method: "digest",
+            _tag: "Unknown",
+            description: "Could not compute digest",
+            cause,
+          }),
+      }).pipe(Effect.map((bytes) => new Uint8Array(bytes))),
+  });
+
+export const make = Effect.gen(function* () {
+  const supplied = yield* Effect.serviceOption(Crypto.Crypto);
+  const crypto = Option.getOrElse(supplied, native);
+
+  return yield* crypto.randomUUIDv4.pipe(
+    Effect.mapError(() =>
+      undispatched("make", new Failed({ detail: "Could not name connection" })),
+    ),
+  );
+});

package/src/internal/page/lane.ts

@@ -0,0 +1,311 @@
+/**
+ * A page's admission: the one lane every operation on the page takes its turn in, so a page waits
+ * only for itself. A write, an action that sends input or navigates, holds the lane alone, in the
+ * order writes asked; reads share it, after the write in flight and every write asked before them,
+ * so a read describes the page an action left, never one an action is still changing. Each write
+ * starts a new epoch as it asks. A turn not given in time fails `Busy`, never `Timeout`, and a
+ * caller under `FailFast` gets it at once.
+ *
+ * Reads keep their work. An identical read asked in the same epoch and document joins the one in
+ * flight, which runs in the page's scope under the action timeout whoever gives up; one that ends
+ * after all its callers gave up serves the next to ask the same, within an action timeout. A write
+ * stops the reads nobody awaits, since no caller after it could use them.
+ *
+ * Effect's `Semaphore` is not fair to a writer that needs every permit, so the rule is this
+ * module's own: one state, changed by `step` alone, which the model test drives.
+ */
+import { Context, Deferred, Duration, Effect, Exit, type Fiber, type Scope } from "effect";
+
+import { BrowserError, Busy } from "../../BrowserError.ts";
+import type { Gate } from "../input/gate.ts";
+
+export type Kind = "read" | "write";
+
+export interface Ticket {
+  readonly id: number;
+  readonly kind: Kind;
+}
+
+/** Who holds the lane: no one, reads together, or one write. */
+export type Turn =
+  | { readonly _tag: "Free" }
+  | { readonly _tag: "Reading"; readonly count: number }
+  | { readonly _tag: "Writing" };
+
+export interface State {
+  readonly turn: Turn;
+  /** The tickets waiting, in the order they asked. */
+  readonly queue: ReadonlyArray<Ticket>;
+  /** The writes asked so far: two reads in one epoch follow the same writes. */
+  readonly epoch: number;
+}
+
+export type Input =
+  | { readonly _tag: "Ask"; readonly ticket: Ticket }
+  /** The ticket gave up waiting, or ended its turn. */
+  | { readonly _tag: "Leave"; readonly ticket: Ticket };
+
+export const initial: State = { turn: { _tag: "Free" }, queue: [], epoch: 0 };
+
+const holders = (turn: Turn) =>
+  turn._tag === "Reading" ? turn.count : turn._tag === "Writing" ? 1 : 0;
+
+/** Whether a ticket of `kind` asking now would hold the lane at once. */
+export const admitsNow = ({ turn, queue }: State, kind: Kind) =>
+  queue.length === 0 && (kind === "read" ? turn._tag !== "Writing" : turn._tag === "Free");
+
+/**
+ * The operations ahead of a waiting ticket: those holding the lane and those asked before it, or
+ * all that are queued for a ticket not in the queue.
+ */
+export const ahead = ({ turn, queue }: State, id?: number) => {
+  const at = queue.findIndex((ticket) => ticket.id === id);
+
+  return holders(turn) + (at === -1 ? queue.length : at);
+};
+
+/**
+ * The lane after `input`, and the tickets it lets in. Tickets go in from the head of the queue
+ * only: a write once the lane is free, reads while no write holds it, so reads asked before a
+ * write go before it, and reads asked after it wait for it.
+ */
+export const step = (
+  state: State,
+  input: Input,
+): { readonly state: State; readonly admitted: ReadonlyArray<Ticket> } => {
+  let { turn, queue, epoch } = state;
+
+  if (input._tag === "Ask") {
+    queue = [...queue, input.ticket];
+    if (input.ticket.kind === "write") epoch += 1;
+  } else {
+    const at = queue.findIndex((ticket) => ticket.id === input.ticket.id);
+
+    if (at !== -1) queue = queue.toSpliced(at, 1);
+    else
+      turn =
+        turn._tag === "Reading" && turn.count > 1
+          ? { _tag: "Reading", count: turn.count - 1 }
+          : { _tag: "Free" };
+  }
+
+  const admitted: Array<Ticket> = [];
+
+  for (const ticket of queue) {
+    if (ticket.kind === "write" ? turn._tag !== "Free" : turn._tag === "Writing") break;
+    admitted.push(ticket);
+    turn =
+      ticket.kind === "write" ? { _tag: "Writing" } : { _tag: "Reading", count: holders(turn) + 1 };
+  }
+
+  return { state: { turn, queue: queue.slice(admitted.length), epoch }, admitted };
+};
+
+/** Whether operations on a busy page fail `Busy` at once rather than wait their turn. */
+export const FailFast = Context.Reference<boolean>("effect-browser/internal/page/FailFast", {
+  defaultValue: () => false,
+});
+
+/** The id a caller gives the actions it asks for, which each records as its `correlation`. */
+export const Correlation = Context.Reference<string | undefined>(
+  "effect-browser/internal/page/Correlation",
+  { defaultValue: () => undefined },
+);
+
+/** A shared read in flight: its epoch, its result once it ends, and how many callers await it. */
+interface Flight<A> {
+  readonly epoch: number;
+  readonly result: Deferred.Deferred<A, BrowserError>;
+  waiting: number;
+  fiber: Fiber.Fiber<A, BrowserError> | undefined;
+}
+
+export const make = (options: {
+  readonly now: () => number;
+  readonly actionTimeout: Duration.Duration;
+  /** When the page's current document began: a read is shared only within one. */
+  readonly documentAt: () => number;
+  /** The failure of a read still awaited as the page closes. */
+  readonly gone: (operation: string) => BrowserError;
+  /** The page's scope, which shared reads run in. */
+  readonly scope: Scope.Scope;
+  readonly inputGate?: Gate | undefined;
+}) => {
+  const { now, actionTimeout } = options;
+  let state = initial;
+  let tickets = 0;
+  const admissions = new Map<number, Deferred.Deferred<void>>();
+  // Each shared read's sweep, which a write runs as it asks.
+  const sweeps: Array<() => void> = [];
+
+  const apply = (input: Input) => {
+    const next = step(state, input);
+
+    state = next.state;
+    if (input._tag === "Leave") admissions.delete(input.ticket.id);
+    for (const ticket of next.admitted) {
+      const admitted = admissions.get(ticket.id);
+
+      admissions.delete(ticket.id);
+      if (admitted !== undefined) Deferred.doneUnsafe(admitted, Exit.void);
+    }
+    if (input._tag === "Ask" && input.ticket.kind === "write") for (const sweep of sweeps) sweep();
+  };
+
+  const busy = (operation: string, askedAt: number, id?: number) =>
+    new BrowserError({
+      operation,
+      reason: new Busy({ waitedMillis: Math.round(now() - askedAt), ahead: ahead(state, id) }),
+      dispatched: false,
+    });
+
+  /**
+   * Run `effect` in a turn of `kind`, waiting at most `wait` for it, or failing `Busy`. The turn
+   * ends with `effect`, however it ends.
+   */
+  const turn =
+    (kind: Kind, operation: string, wait: Duration.Duration) =>
+    <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E | BrowserError, R> =>
+      Effect.uninterruptibleMask((restore) =>
+        Effect.gen(function* () {
+          const ticket: Ticket = { id: ++tickets, kind };
+          const askedAt = now();
+
+          if (kind === "write" && options.inputGate !== undefined)
+            yield* options.inputGate.check(operation);
+
+          if ((yield* FailFast) && !admitsNow(state, kind)) return yield* busy(operation, askedAt);
+          const admitted = Deferred.makeUnsafe<void>();
+
+          admissions.set(ticket.id, admitted);
+          apply({ _tag: "Ask", ticket });
+
+          const waiting = Deferred.await(admitted).pipe(
+            Effect.timeoutOrElse({
+              duration: wait,
+              orElse: () =>
+                Deferred.isDoneUnsafe(admitted)
+                  ? Effect.void
+                  : Effect.fail(busy(operation, askedAt, ticket.id)),
+            }),
+          );
+
+          const given = yield* Effect.exit(
+            restore(
+              kind === "write" && options.inputGate !== undefined
+                ? Effect.raceFirst(waiting, options.inputGate.refused(operation))
+                : waiting,
+            ),
+          );
+
+          if (Exit.isFailure(given)) {
+            apply({ _tag: "Leave", ticket });
+
+            return yield* Effect.failCause(given.cause);
+          }
+
+          return yield* restore(effect).pipe(
+            Effect.ensuring(Effect.sync(() => apply({ _tag: "Leave", ticket }))),
+          );
+        }),
+      );
+
+  /**
+   * A read whose identical calls share their work: `work` runs once per epoch and document while
+   * calls await it, and with `keep` its result serves the next call after all of them gave up,
+   * within an action timeout of its end. Pictures, whose callers say how old they may be, only
+   * join.
+   */
+  const shared = <A>(operation: string, keep: boolean) => {
+    const flights = new Map<string, Flight<A>>();
+    const kept = new Map<string, { readonly value: A; readonly until: number }>();
+
+    sweeps.push(() => {
+      kept.clear();
+      for (const flight of flights.values())
+        if (flight.waiting === 0) flight.fiber?.interruptUnsafe();
+    });
+
+    // A read in flight, its first caller waiting. However its fiber ends, even before it began,
+    // as when the page closes, its callers hear.
+    const start = (id: string, work: Effect.Effect<A, BrowserError>) =>
+      Effect.gen(function* () {
+        const flight: Flight<A> = {
+          epoch: state.epoch,
+          result: Deferred.makeUnsafe(),
+          waiting: 1,
+          fiber: undefined,
+        };
+
+        flights.set(id, flight);
+        flight.fiber = yield* turn(
+          "read",
+          operation,
+          actionTimeout,
+        )(work).pipe(
+          // The caller chose whether to wait; the work it started serves others too.
+          Effect.provideService(FailFast, false),
+          Effect.forkIn(options.scope),
+        );
+        flight.fiber.addObserver((exit) => {
+          flights.delete(id);
+          if (keep && Exit.isSuccess(exit) && flight.waiting === 0 && flight.epoch === state.epoch)
+            kept.set(id, { value: exit.value, until: now() + Duration.toMillis(actionTimeout) });
+          Deferred.doneUnsafe(
+            flight.result,
+            Exit.hasInterrupts(exit) ? Effect.fail(options.gone(operation)) : exit,
+          );
+        });
+
+        return flight;
+      });
+
+    const join = (id: string, work: Effect.Effect<A, BrowserError>) =>
+      Effect.acquireUseRelease(
+        Effect.suspend(() => {
+          const flying = flights.get(id);
+
+          if (flying === undefined) return start(id, work);
+          flying.waiting += 1;
+
+          return Effect.as(Effect.annotateCurrentSpan("shared", "joined"), flying);
+        }),
+        (flight) => Deferred.await(flight.result),
+        (flight) =>
+          Effect.sync(() => {
+            flight.waiting -= 1;
+            if (flight.waiting === 0 && flight.epoch < state.epoch) flight.fiber?.interruptUnsafe();
+          }),
+      );
+
+    return (key: string, work: Effect.Effect<A, BrowserError>): Effect.Effect<A, BrowserError> =>
+      Effect.gen(function* () {
+        const id = `${state.epoch} ${options.documentAt()} ${key}`;
+        const at = now();
+
+        for (const [old, { until }] of kept) if (until < at) kept.delete(old);
+        const hit = kept.get(id);
+
+        if (hit !== undefined) {
+          kept.delete(id);
+          yield* Effect.annotateCurrentSpan("shared", "kept");
+
+          return hit.value;
+        }
+        if ((yield* FailFast) && !admitsNow(state, "read")) return yield* busy(operation, at);
+
+        return yield* join(id, work);
+      });
+  };
+
+  return {
+    /** A turn alone, for an action: `wait` bounds the wait for it. */
+    write: (operation: string, wait: Duration.Duration) => turn("write", operation, wait),
+    /** A turn beside other reads, waited for within the action timeout. */
+    read: (operation: string, wait: Duration.Duration = actionTimeout) =>
+      turn("read", operation, wait),
+    shared,
+  };
+};
+
+export type Lane = ReturnType<typeof make>;