@lenso/workers-runtime 0.1.0

package/README.md

@@ -0,0 +1,76 @@
+# Lenso Workers Runtime
+
+This package owns event resources, generation admission and reset, and the
+JavaScript timer domain used by the `lenso-workers-driver` Rust crate. It does
+not resolve Plugins, grant network authority, authenticate, or authorize requests.
+The new package is under qualification; no registry release is claimed.
+
+Use `lenso-workers-build --manifest Cargo.toml --package my-host --out-dir pkg`
+to build a consumer Host with its locked dependency graph. It requires Rust
+1.94.0, `wasm32-unknown-unknown`, and wasm-bindgen CLI 0.2.127. `CARGO` and
+`WASM_BINDGEN` may select executable paths. No sibling repository layout is
+required. The generated module imports `@lenso/workers-runtime/clock`; the Host
+must give its runner `clearTimers` from that same module. Use one runner per
+generated module/timer domain. Multiple independent Wasm modules require separate
+timer domains and are not supported by the shared default clock export.
+
+```js
+import { createEventScope, createEventRunner } from '@lenso/workers-runtime';
+import { clearTimers } from '@lenso/workers-runtime/clock';
+const runner = createEventRunner({
+  instantiate: () => initSync({ module }), resetState: __wbg_reset_state, clearTimers,
+});
+// Inside this request's owner context, never at module scope:
+const scope = createEventScope(scope => ({
+  batch: input => scope.run(() => database.batch(prepare(input)), JSON.stringify),
+}));
+const result = await runner.run(() => invoke(input, scope), { scope, signal: request.signal });
+```
+
+An adapter uses `scope.operation(() => ({ promise, abort }))` for abortable work,
+`scope.run(start, project)` for unabortable work, and `scope.trackNative(promise)`
+for native reads/cancellation spawned by that operation. Native adapters must
+bound this work; `trackNative` is not an application admission API. Projection
+functions must be JavaScript-only and must not capture Wasm callbacks. The scope
+admits at most 128 simultaneous operations by default, rejects new operations on
+close, fences stale promise delivery synchronously, and drains native cleanup
+including work registered by a late completion. Cleanup has one total 250 ms
+budget by default. An uncertain result remains uncertain on repeated settlement;
+no retry, rollback, or exactly-once mutation guarantee is implied.
+
+`runner.run` accepts a serialized JSON terminal receipt. `runner.open` accepts
+an operation resolving `{ value, closed }`: `value` contains response/session
+metadata, while `closed` resolves to `{ shutdown: 'clean' }` only after the body
+and App have shut down. It returns `{ value, generation, invoke, cancel, closed }`.
+The Host must observe `closed`; failure after headers is a failed stream, not a
+replacement HTTP success. Route every subsequent Wasm entry through
+`session.invoke(() => ...)`. Do not call old Wasm destructors after abandonment.
+`cancel()` signals the event scope; it does not fabricate a terminal receipt.
+A cancellation must settle within `cancellationLimitMs` (default 1 s), after
+which the generation is abandoned.
+
+Headers keep the original event startup deadline (default 1 s). After opening,
+the session has `sessionLimitMs` (default 5 min). Generation retirement waits for
+all admitted sessions. A trap or deadline abandons the entire generation,
+synchronously fences all admitted scopes, and rejects their owners; native
+cleanup runs only in each owner's continuation. These are shared-instance failure
+semantics, not independent per-session isolation. WebSocket hibernation is not
+provided by this event runtime.
+
+The buffered HTTP compatibility bridge is exported from `./http`. New Host
+integrations should create one immutable `createEventScope` for all D1, Fetch and
+cancellation bindings. `createCancellationScope` preserves legacy mutable Host
+composition only; it is not the preferred API.
+
+Run `npm test` for focused resource, HTTP, and session boundary checks. Actual
+Workers deployment and each Plugin's own conformance remain separate evidence.
+
+`createStreamingHttpHandler` consumes an `openHttp` adapter returning
+`{ value: { status, headers, read }, closed }`. Each `read()` yields one
+`Uint8Array` or `null`; the adapter must finish App shutdown for `closed` before
+clean EOF. Reads begin only on consumer demand, copy the current Wasm memory
+view, and enforce per-chunk and total byte limits. Disconnect cancels the lease;
+a failed generation errors an outstanding body read. The real Rust/Wasm duplex fixture is qualified on the deployed Workers target;
+receipts are in `experiments/workers-g2/evidence/duplex.json`. Supply Web's
+`createWebSocketTransport()` through `upgradeWebSocket` for authorized status-101
+responses. Web owns that transport and its Capability, not Runtime.

package/build.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { mkdirSync } from "node:fs";
+
+// Paths come from the consumer, never a sibling repository's checkout layout.
+export function build({
+  manifest,
+  packageName,
+  outDir,
+  cargo = process.env.CARGO || "cargo",
+  cargoConfig,
+  bindgen = process.env.WASM_BINDGEN || "wasm-bindgen",
+  features = [],
+}) {
+  if (!manifest || !packageName || !outDir)
+    throw new Error("manifest, package, and out-dir are required");
+  const version = spawnSync(bindgen, ["--version"], { encoding: "utf8" });
+  if (
+    version.status !== 0 ||
+    version.stdout.trim() !== "wasm-bindgen 0.2.127"
+  ) {
+    throw new Error(
+      "Install wasm-bindgen-cli 0.2.127, matching the Workers Driver lock",
+    );
+  }
+  const command = [
+    "+1.94.0",
+    "rustc",
+    "--locked",
+    ...(cargoConfig ? ["--config", resolve(cargoConfig)] : []),
+    "--manifest-path",
+    resolve(manifest),
+    "--target",
+    "wasm32-unknown-unknown",
+    "-p",
+    packageName,
+    "--release",
+    "--no-default-features",
+    "--message-format=json",
+    ...(features.length ? ["--features", features.join(",")] : []),
+    "--",
+    "-C",
+    "link-arg=--export=__wasm_call_ctors",
+  ];
+  const result = spawnSync(cargo, command, {
+    encoding: "utf8",
+    maxBuffer: 32 * 1024 * 1024,
+    stdio: ["inherit", "pipe", "inherit"],
+  });
+  const messages = (result.stdout || "")
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+  for (const message of messages) {
+    if (message.reason === "compiler-message")
+      process.stderr.write(message.message.rendered || message.message.message);
+  }
+  if (result.status !== 0)
+    throw result.error || new Error(`Cargo failed (${result.status})`);
+  const artifacts = messages
+    .filter(
+      (message) =>
+        message.reason === "compiler-artifact" &&
+        message.target.name === packageName.replaceAll("-", "_"),
+    )
+    .flatMap((message) => message.filenames)
+    .filter((name) => name.endsWith(".wasm"));
+  if (artifacts.length !== 1)
+    throw new Error("Expected exactly one Wasm host artifact");
+  mkdirSync(resolve(outDir), { recursive: true });
+  const generated = spawnSync(
+    bindgen,
+    [
+      artifacts[0],
+      "--target",
+      "web",
+      "--experimental-reset-state-function",
+      "--out-dir",
+      resolve(outDir),
+    ],
+    { stdio: "inherit" },
+  );
+  if (generated.status !== 0)
+    throw generated.error || new Error("wasm-bindgen failed");
+  return artifacts[0];
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(resolve(process.argv[1])).href
+) {
+  try {
+    const options = {},
+      names = {
+        "--manifest": "manifest",
+        "--package": "packageName",
+        "--out-dir": "outDir",
+        "--features": "features",
+        "--config": "cargoConfig",
+      };
+    for (let index = 2; index < process.argv.length; index += 2) {
+      const key = names[process.argv[index]],
+        value = process.argv[index + 1];
+      if (!key || !value || value.startsWith("--"))
+        throw new Error(
+          "Usage: lenso-workers-build --manifest Cargo.toml --package host --out-dir pkg [--features a,b]",
+        );
+      if (key in options)
+        throw new Error(`Duplicate option ${process.argv[index]}`);
+      options[key] = key === "features" ? value.split(",") : value;
+    }
+    build(options);
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}

package/clock.mjs

@@ -0,0 +1,31 @@
+// One generated wasm-bindgen module owns this timer domain. Its runner must use
+// this same clearTimers export before resetting that module's state.
+const timers = new Map();
+let nextId = 0;
+export function clock(operation, callback, value) {
+  if (operation === 0) return performance.now();
+  if (operation === 1) {
+    do {
+      nextId = nextId === 0x7fffffff ? 1 : nextId + 1;
+    } while (timers.has(nextId));
+    const id = nextId;
+    timers.set(
+      id,
+      setTimeout(() => {
+        timers.delete(id);
+        callback();
+      }, value),
+    );
+    return id;
+  }
+  if (operation === 2) {
+    clearTimeout(timers.get(value));
+    timers.delete(value);
+    return 0;
+  }
+  throw new Error("Unknown clock operation");
+}
+export function clearTimers() {
+  for (const timer of timers.values()) clearTimeout(timer);
+  timers.clear();
+}

package/http.mjs

@@ -0,0 +1,366 @@
+// Event-owned transport adaptation; routing and authorization stay in Web Ingress.
+import { createEventScope } from "./scope.mjs";
+// Compatibility name; all cancellation and native I/O now share one scope.
+export function createCancellationScope(extra = {}) {
+  // Legacy Hosts used mutable finalizer composition. New Hosts use createEventScope.
+  return { ...createEventScope(extra) };
+}
+export function attachCancellation(scope, callback) {
+  scope.attach(callback);
+}
+export function detachCancellation(scope) {
+  scope.detach();
+}
+export function cancellation(scope, callback) {
+  if (callback === null) scope.detach();
+  else scope.attach(callback);
+}
+
+function transportFailure(status, error) {
+  return Response.json(
+    { error },
+    {
+      status,
+      headers: {
+        "cache-control": "no-store",
+        "x-content-type-options": "nosniff",
+      },
+    },
+  );
+}
+
+function responseBytes(result, limit) {
+  const fail = (message) => {
+    const error = new Error(message);
+    error.status = 502;
+    throw error;
+  };
+  if (Object.hasOwn(result, "body_base64")) {
+    if (Object.hasOwn(result, "body") || typeof result.body_base64 !== "string")
+      fail("invalid_response_body");
+    const encoded = result.body_base64;
+    // Bound allocation before decoding. Require canonical padded standard Base64.
+    if (encoded.length > 4 * Math.ceil(limit / 3))
+      fail("response_body_too_large");
+    const padding = encoded.endsWith("==") ? 2 : encoded.endsWith("=") ? 1 : 0;
+    if (
+      encoded.length % 4 !== 0 ||
+      /[^A-Za-z0-9+/]/.test(encoded.slice(0, encoded.length - padding))
+    ) {
+      fail("invalid_response_body");
+    }
+    if ((encoded.length / 4) * 3 - padding > limit)
+      fail("response_body_too_large");
+    const decoded = atob(encoded);
+    if (btoa(decoded) !== encoded) fail("invalid_response_body");
+    const bytes = new Uint8Array(decoded.length);
+    for (let index = 0; index < decoded.length; index++)
+      bytes[index] = decoded.charCodeAt(index);
+    return bytes;
+  }
+  if (!Array.isArray(result.body)) fail("invalid_response_body");
+  if (result.body.length > limit) fail("response_body_too_large");
+  if (
+    result.body.some(
+      (byte) => !Number.isInteger(byte) || byte < 0 || byte > 255,
+    )
+  )
+    fail("invalid_response_body");
+  return Uint8Array.from(result.body);
+}
+
+async function readBody(request, limit, timeoutMs) {
+  const length = request.headers.get("content-length");
+  if (length !== null && /^\d+$/.test(length) && Number(length) > limit) {
+    const error = new Error("payload_too_large");
+    error.status = 413;
+    throw error;
+  }
+  if (request.signal.aborted)
+    throw new DOMException("Request aborted", "AbortError");
+  if (!request.body) return new Uint8Array();
+  const reader = request.body.getReader();
+  let timer;
+  let abort;
+  const interrupted = new Promise((_, reject) => {
+    abort = () => reject(new DOMException("Request aborted", "AbortError"));
+    request.signal.addEventListener("abort", abort, { once: true });
+    timer = setTimeout(() => {
+      const error = new Error("request_body_timeout");
+      error.status = 408;
+      reject(error);
+    }, timeoutMs);
+  });
+  const chunks = [];
+  let lengthRead = 0;
+  let complete = false;
+  try {
+    while (true) {
+      const { value, done } = await Promise.race([reader.read(), interrupted]);
+      if (done) {
+        complete = true;
+        break;
+      }
+      if (value.byteLength > limit - lengthRead) {
+        const error = new Error("payload_too_large");
+        error.status = 413;
+        throw error;
+      }
+      lengthRead += value.byteLength;
+      chunks.push(value);
+    }
+    const bytes = new Uint8Array(lengthRead);
+    let offset = 0;
+    for (const chunk of chunks) {
+      bytes.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+    return bytes;
+  } finally {
+    clearTimeout(timer);
+    request.signal.removeEventListener("abort", abort);
+    if (!complete) await reader.cancel().catch(() => {});
+    reader.releaseLock();
+  }
+}
+
+export function createHttpHandler({
+  run,
+  handleHttp,
+  maxRequestBodyBytes = 1048576,
+  maxResponseBodyBytes = 1048576,
+  maxRequestHeadBytes = 16384,
+  bodyReadTimeoutMs = 30000,
+  createScope = () => createCancellationScope(),
+  onReceipt = () => {},
+}) {
+  return async function handleRequest(request) {
+    let scope;
+    try {
+      scope = createScope(request);
+      // URL.search loses a trailing empty '?'. Slice the original platform URL.
+      const url = new URL(request.url);
+      const uri = request.url.slice(url.origin.length).split("#", 1)[0] || "/";
+      const headers = [...request.headers];
+      const encoder = new TextEncoder();
+      let headBytes = encoder.encode(request.method + " " + uri).byteLength;
+      for (const [name, value] of headers)
+        headBytes += encoder.encode(name + ": " + value).byteLength + 2;
+      if (headBytes > maxRequestHeadBytes)
+        return transportFailure(431, "request_header_fields_too_large");
+      const body = await readBody(
+        request,
+        maxRequestBodyBytes,
+        bodyReadTimeoutMs,
+      );
+      const input = JSON.stringify({
+        method: request.method,
+        uri,
+        headers,
+        body: [...body],
+      });
+      const result = await run(() => handleHttp(input, scope), {
+        scope,
+        signal: request.signal,
+      });
+      if (result.shutdown !== "clean")
+        throw new Error("HTTP App shutdown was not clean");
+      const responseBody = responseBytes(result, maxResponseBodyBytes);
+      const responseHeaders = new Headers();
+      for (const [name, value] of result.headers)
+        responseHeaders.append(name, value);
+      const bodyForbidden =
+        request.method === "HEAD" ||
+        [101, 204, 205, 304].includes(result.status);
+      const response = new Response(bodyForbidden ? null : responseBody, {
+        status: result.status,
+        headers: responseHeaders,
+      });
+      onReceipt(result, response);
+      return response;
+    } catch (error) {
+      if (error.name === "AbortError")
+        return transportFailure(503, "request_cancelled");
+      return transportFailure(
+        error.status ?? 503,
+        error.status ? error.message : "host_unavailable",
+      );
+    } finally {
+      // Early head/length rejection must release an unread incoming body too.
+      if (request.body && !request.bodyUsed && !request.body.locked) {
+        await request.body.cancel().catch(() => {});
+      }
+      // Runner also finalizes admitted events; this covers body-read/admission errors.
+      try {
+        scope?.abort();
+        const settled = await scope?.settled?.();
+        // A bounded storage adapter can report uncertainty without retrying writes.
+        if (settled === false)
+          return transportFailure(503, "storage_cleanup_unconfirmed");
+      } catch {
+        return transportFailure(503, "storage_cleanup_unconfirmed");
+      }
+    }
+  };
+}
+
+/**
+ * Pull-based response transport. openHttp returns { value: { status, headers,
+ * read }, closed }; read resolves one Uint8Array or null. closed resolves only
+ * after the Plugin stream terminal and App shutdown. No Wasm callback survives
+ * its runner lease. The Host owns request parsing; Ingress still owns routing.
+ */
+export function createStreamingHttpHandler({
+  open,
+  openHttp,
+  maxRequestBodyBytes = 1048576,
+  maxRequestHeadBytes = 16384,
+  maxResponseChunkBytes = 65536,
+  maxResponseBodyBytes = 64 * 1024 * 1024,
+  bodyReadTimeoutMs = 30000,
+  createScope = () => createEventScope(),
+  upgradeWebSocket,
+}) {
+  for (const limit of [
+    maxRequestBodyBytes,
+    maxRequestHeadBytes,
+    maxResponseChunkBytes,
+    maxResponseBodyBytes,
+    bodyReadTimeoutMs,
+  ]) {
+    if (!Number.isSafeInteger(limit) || limit < 1)
+      throw new TypeError("invalid transport limit");
+  }
+  return async (request) => {
+    let scope,
+      session,
+      transferred = false;
+    try {
+      scope = createScope(request);
+      const url = new URL(request.url);
+      const uri = request.url.slice(url.origin.length).split("#", 1)[0] || "/";
+      const headers = [...request.headers],
+        encoder = new TextEncoder();
+      const headBytes =
+        encoder.encode(request.method + " " + uri).byteLength +
+        headers.reduce(
+          (bytes, [name, value]) =>
+            bytes + encoder.encode(name + ": " + value).byteLength + 2,
+          0,
+        );
+      if (headBytes > maxRequestHeadBytes)
+        return transportFailure(431, "request_header_fields_too_large");
+      const body = await readBody(
+        request,
+        maxRequestBodyBytes,
+        bodyReadTimeoutMs,
+      );
+      session = await open(
+        () =>
+          openHttp(
+            JSON.stringify({
+              method: request.method,
+              uri,
+              headers,
+              body: [...body],
+            }),
+            scope,
+          ),
+        { scope, signal: request.signal },
+      );
+      const head = session.value;
+      if (head?.status === 101 && upgradeWebSocket) {
+        const response = upgradeWebSocket(request, session, scope);
+        transferred = true;
+        return response;
+      }
+      if (
+        !Number.isInteger(head?.status) ||
+        head.status < 200 ||
+        head.status > 599 ||
+        typeof head.read !== "function"
+      )
+        throw new Error("invalid_stream_response");
+      const responseHeaders = new Headers();
+      for (const [name, value] of head.headers)
+        responseHeaders.append(name, value);
+      const forbidden =
+        request.method === "HEAD" || [204, 205, 304].includes(head.status);
+      let received = 0,
+        ended = false;
+      const stream = forbidden
+        ? null
+        : new ReadableStream(
+            {
+              start(controller) {
+                session.closed.catch(() => {
+                  if (!ended) {
+                    ended = true;
+                    controller.error(new Error("response_stream_failed"));
+                  }
+                });
+              },
+              async pull(controller) {
+                if (ended) return;
+                try {
+                  const chunk = await session.invoke(() => head.read());
+                  if (chunk === null) {
+                    await session.closed;
+                    ended = true;
+                    controller.close();
+                    return;
+                  }
+                  if (
+                    !(chunk instanceof Uint8Array) ||
+                    chunk.byteLength > maxResponseChunkBytes ||
+                    chunk.byteLength > maxResponseBodyBytes - received
+                  )
+                    throw new Error("invalid_stream_chunk");
+                  // A copy releases the Wasm memory view before a later receive grows memory.
+                  received += chunk.byteLength;
+                  controller.enqueue(chunk.slice());
+                } catch {
+                  ended = true;
+                  session.cancel();
+                  controller.error(new Error("response_stream_failed"));
+                }
+              },
+              async cancel() {
+                ended = true;
+                session.cancel();
+                await session.closed.catch(() => {});
+              },
+            },
+            { highWaterMark: 0 },
+          );
+      const response = new Response(stream, {
+        status: head.status,
+        headers: responseHeaders,
+      });
+      if (forbidden) {
+        session.cancel();
+        await session.closed;
+      }
+      transferred = true;
+      return response;
+    } catch (error) {
+      session?.cancel();
+      return transportFailure(
+        error.status ?? 503,
+        error.status ? error.message : "host_unavailable",
+      );
+    } finally {
+      if (request.body && !request.bodyUsed && !request.body.locked)
+        await request.body.cancel().catch(() => {});
+      if (!transferred) {
+        try {
+          scope?.abort();
+          if ((await scope?.settled?.()) === false)
+            return transportFailure(503, "storage_cleanup_unconfirmed");
+        } catch {
+          return transportFailure(503, "storage_cleanup_unconfirmed");
+        }
+      }
+    }
+  };
+}

package/index.mjs

@@ -0,0 +1,3 @@
+export { createEventScope } from "./scope.mjs";
+export { createEventRunner } from "./runner.mjs";
+export { createHttpHandler, createStreamingHttpHandler } from "./http.mjs";

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@lenso/workers-runtime",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Event-owned resource and generation boundaries for Lenso Workers hosts",
+  "exports": {
+    ".": "./index.mjs",
+    "./http": "./http.mjs",
+    "./runner": "./runner.mjs",
+    "./clock": "./clock.mjs",
+    "./build": "./build.mjs"
+  },
+  "files": [
+    "*.mjs",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "lenso-workers-build": "./build.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LioRael/lenso-runtime-rust.git",
+    "directory": "packages/workers-runtime"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/runner.mjs

@@ -0,0 +1,283 @@
+// Product-neutral extraction of the qualified G1 generation boundary.
+// Every run owns its continuation, cancellation scope and finalizer.
+export function createEventRunner({
+  instantiate,
+  resetState,
+  clearTimers,
+  eventLimitMs = 1000,
+  maxConcurrent = 32,
+  retirementAdmissionLimit = 64,
+  sessionLimitMs = 300_000,
+  cancellationLimitMs = 1000,
+}) {
+  for (const [name, value] of Object.entries({
+    eventLimitMs,
+    sessionLimitMs,
+    cancellationLimitMs,
+  })) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > 0x7fffffff) {
+      throw new RangeError(`${name} must be a positive 32-bit timer duration`);
+    }
+  }
+  if (
+    !Number.isInteger(maxConcurrent) ||
+    maxConcurrent < 1 ||
+    maxConcurrent > 32
+  ) {
+    throw new RangeError("maxConcurrent must be an integer from 1 to 32");
+  }
+  if (
+    !Number.isInteger(retirementAdmissionLimit) ||
+    retirementAdmissionLimit < 1 ||
+    retirementAdmissionLimit > 96
+  ) {
+    throw new RangeError(
+      "retirementAdmissionLimit must be an integer from 1 to 96",
+    );
+  }
+  let exports = instantiate();
+  exports.__wasm_call_ctors();
+  let generation = 1;
+  let unavailable = false;
+  const pending = new Set();
+
+  // Bound retained allocation even if a dependency retains request App state.
+  // Retire at the next idle boundary after the configured admission count; 96 is the hard ceiling.
+  let admittedCount = 0;
+  let queued = 0;
+  function resetInstance() {
+    unavailable = true;
+    clearTimers();
+    const previousMemory = exports.memory;
+    resetState();
+    exports = instantiate();
+    if (exports.memory === previousMemory)
+      throw new Error("Wasm memory was reused");
+    exports.__wasm_call_ctors();
+    admittedCount = 0;
+    unavailable = false;
+  }
+  function rotate() {
+    generation++;
+    resetInstance();
+  }
+  // Failure is distinct from clean retirement: reject every admitted event, then
+  // rebuild. Owner-context finalizers dispose I/O after rejection.
+  function abandon(cause) {
+    const abandoned = generation;
+    const failure = new Error(
+      `Wasm generation ${abandoned} abandoned: ${cause}`,
+    );
+    failure.code = "instance_abandoned";
+    failure.generation = abandoned;
+    unavailable = true;
+    for (const event of pending) {
+      clearTimeout(event.timer);
+      event.invalidate();
+      event.reject(failure);
+    }
+    pending.clear();
+    try {
+      rotate();
+    } catch {
+      /* Admission remains closed on reset failure. */
+    }
+  }
+
+  function execute(operation, { scope, signal } = {}, opened) {
+    if (signal?.aborted)
+      return Promise.reject(new DOMException("Request aborted", "AbortError"));
+    if (unavailable)
+      return Promise.reject(new Error("Wasm instance unavailable"));
+    if (admittedCount >= 96) {
+      if (!pending.size) {
+        try {
+          rotate();
+        } catch (error) {
+          return Promise.reject(error);
+        }
+      } else {
+        if (queued >= 32)
+          return Promise.reject(new Error("Rotation queue capacity exceeded"));
+        queued++;
+        // Each waiter owns its timer. A shared cross-request Promise can be
+        // canceled by workerd when its creating request has no local I/O left.
+        return (async () => {
+          try {
+            const deadline = Date.now() + eventLimitMs;
+            while (admittedCount >= 96 && pending.size) {
+              if (signal?.aborted)
+                throw new DOMException("Request aborted", "AbortError");
+              if (unavailable) throw new Error("Wasm instance unavailable");
+              if (Date.now() >= deadline)
+                throw new Error("Rotation admission deadline exceeded");
+              await new Promise((resolve) => setTimeout(resolve, 1));
+            }
+            return await execute(operation, { scope, signal }, opened);
+          } finally {
+            queued--;
+          }
+        })();
+      }
+    }
+    if (pending.size >= maxConcurrent)
+      return Promise.reject(new Error("Event capacity exceeded"));
+    const admitted = generation;
+    admittedCount++;
+    let event;
+    const result = new Promise((resolve, reject) => {
+      const onAbort = () => {
+        scope?.abort();
+        if (event && !event.cancelling) {
+          event.cancelling = true;
+          clearTimeout(event.timer);
+          event.timer = setTimeout(
+            () => abandon("cancellation deadline exceeded"),
+            cancellationLimitMs,
+          );
+        }
+      };
+      event = {
+        reject,
+        invalidate() {
+          scope?.invalidate?.();
+        },
+        dispose() {
+          scope?.abort();
+          signal?.removeEventListener("abort", onAbort);
+        },
+        timer: setTimeout(
+          () => abandon("event deadline exceeded"),
+          eventLimitMs,
+        ),
+      };
+      signal?.addEventListener("abort", onAbort, { once: true });
+      if (signal?.aborted) onAbort();
+      pending.add(event);
+      let pendingOperation;
+      try {
+        pendingOperation = operation();
+      } catch (error) {
+        abandon(String(error));
+        return;
+      }
+      Promise.resolve(pendingOperation).then(
+        (value) => {
+          if (!pending.has(event) || admitted !== generation) return;
+          if (opened) {
+            // Headers may leave the Host now; the generation remains admitted until
+            // the session's clean terminal receipt or a bounded failure.
+            if (
+              !value ||
+              !value.closed ||
+              typeof value.closed.then !== "function"
+            ) {
+              reject(
+                new TypeError("open operation must return { value, closed }"),
+              );
+              return;
+            }
+            clearTimeout(event.timer);
+            event.timer = setTimeout(
+              () =>
+                abandon(
+                  event.cancelling
+                    ? "cancellation deadline exceeded"
+                    : "session deadline exceeded",
+                ),
+              event.cancelling ? cancellationLimitMs : sessionLimitMs,
+            );
+            opened({
+              value: value.value,
+              generation: admitted,
+              invoke(call) {
+                if (
+                  !pending.has(event) ||
+                  admitted !== generation ||
+                  scope?.closed
+                ) {
+                  throw new Error("session_closed");
+                }
+                return call();
+              },
+              cancel() {
+                if (pending.has(event) && admitted === generation) onAbort();
+              },
+            });
+            Promise.resolve(value.closed).then(
+              (receipt) => {
+                if (!pending.has(event) || admitted !== generation) return;
+                clearTimeout(event.timer);
+                if (receipt?.shutdown !== "clean")
+                  abandon("session_shutdown_unconfirmed");
+                else resolve(receipt);
+              },
+              (error) => {
+                if (admitted === generation) abandon(String(error));
+              },
+            );
+          } else {
+            clearTimeout(event.timer);
+            try {
+              resolve({
+                ...JSON.parse(value),
+                generation: admitted,
+                wasm_memory_bytes: exports.memory.buffer.byteLength,
+              });
+            } catch (error) {
+              reject(error);
+            }
+          }
+        },
+        (error) => {
+          if (admitted === generation) abandon(String(error));
+        },
+      );
+    });
+    // Register cleanup in the owning fetch context. Another event may reject this
+    // promise, but it must never directly abort this request's native I/O objects.
+    return result.finally(async () => {
+      try {
+        clearTimeout(event?.timer);
+        event?.dispose();
+        if ((await scope?.settled?.()) === false)
+          throw new Error("Storage completion unavailable");
+      } catch {
+        const error = new Error("storage_cleanup_unconfirmed");
+        error.status = 503;
+        throw error;
+      } finally {
+        // Even a normal result can leave unconfirmed native work. Fence every
+        // continuation before this event leaves the generation's pending set.
+        event?.invalidate();
+        pending.delete(event);
+        if (
+          !unavailable &&
+          !pending.size &&
+          admittedCount >= retirementAdmissionLimit
+        )
+          rotate();
+      }
+    });
+  }
+  function run(operation, options) {
+    return execute(operation, options);
+  }
+  function open(operation, options) {
+    let publish, fail;
+    const ready = new Promise((resolve, reject) => {
+      publish = resolve;
+      fail = reject;
+    });
+    let session;
+    const closed = execute(operation, options, (value) => {
+      session = value;
+      publish({ ...session, closed });
+    });
+    // Always own rejection even if a transport fails before consuming headers.
+    // The returned closed Promise remains rejected for the owner to observe.
+    closed.catch(fail);
+    return ready;
+  }
+  return { run, open, generation: () => generation };
+}

package/scope.mjs

@@ -0,0 +1,170 @@
+/**
+ * One request's native resources and detachable Wasm continuations.
+ * Invalidation is synchronous JS-only fencing; abort/settled run in the owner.
+ * Native adapters may track cleanup spawned by a late completion, but cannot
+ * admit another application operation after this scope closes.
+ */
+export function createEventScope(
+  bindings = {},
+  { cleanupTimeoutMs = 250, maxOperations = 128 } = {},
+) {
+  if (!Number.isFinite(cleanupTimeoutMs) || cleanupTimeoutMs <= 0) {
+    throw new RangeError("cleanupTimeoutMs must be positive and finite");
+  }
+  if (!Number.isSafeInteger(maxOperations) || maxOperations < 1) {
+    throw new RangeError("maxOperations must be a positive integer");
+  }
+  let closed = false,
+    invalidated = false,
+    callback,
+    cancelled = false;
+  const pending = new Set(),
+    gates = new Set(),
+    aborters = new Set();
+  let settlement;
+  const closedError = () => new Error("event_scope_closed");
+
+  function trackNative(value) {
+    const promise = Promise.resolve(value);
+    pending.add(promise);
+    // Both handlers own rejection immediately and never call Wasm.
+    promise.then(
+      () => pending.delete(promise),
+      () => pending.delete(promise),
+    );
+    return promise;
+  }
+
+  function operation(start, project = (value) => value) {
+    if (closed) return { promise: Promise.reject(closedError()), abort() {} };
+    if (aborters.size >= maxOperations) {
+      return {
+        promise: Promise.reject(new Error("event_operation_capacity")),
+        abort() {},
+      };
+    }
+    let resource;
+    try {
+      resource = start();
+    } catch (error) {
+      return { promise: Promise.reject(error), abort() {} };
+    }
+    if (!resource || !("promise" in resource))
+      throw new TypeError("operation requires a promise");
+    let aborted = false;
+    const abort = () => {
+      if (aborted) return;
+      aborted = true;
+      // Cancellation errors must be observed by bounded cleanup too.
+      try {
+        const result = resource.abort?.();
+        if (result !== undefined) trackNative(result);
+      } catch {
+        cleanupFailed = true;
+      }
+    };
+    aborters.add(abort);
+    const gate = {};
+    const promise = new Promise((resolve, reject) => {
+      gate.resolve = resolve;
+      gate.reject = reject;
+    });
+    gates.add(gate);
+    const finish = (error, value) => {
+      aborters.delete(abort);
+      gates.delete(gate);
+      const { resolve, reject } = gate;
+      gate.resolve = gate.reject = undefined;
+      if (invalidated) return;
+      if (error) reject?.(value);
+      else {
+        try {
+          resolve?.(project(value));
+        } catch (failure) {
+          reject?.(failure);
+        }
+      }
+    };
+    trackNative(resource.promise).then(
+      (value) => finish(false, value),
+      (error) => finish(true, error),
+    );
+    return { promise, abort };
+  }
+
+  let cleanupFailed = false;
+  const scope = {
+    get closed() {
+      return closed;
+    },
+    get invalidated() {
+      return invalidated;
+    },
+    trackNative,
+    operation,
+    run(start, project) {
+      return operation(() => ({ promise: start() }), project).promise;
+    },
+    attach(next) {
+      if (invalidated) return;
+      callback = next;
+      if (cancelled) callback?.();
+    },
+    detach() {
+      callback = undefined;
+    },
+    invalidate() {
+      closed = invalidated = true;
+      callback = undefined;
+      for (const gate of gates) gate.resolve = gate.reject = undefined;
+      gates.clear();
+    },
+    abort() {
+      closed = cancelled = true;
+      const cancel = callback;
+      callback = undefined;
+      try {
+        cancel?.();
+      } catch {
+        cleanupFailed = true;
+      }
+      for (const abort of [...aborters]) abort();
+    },
+    settled() {
+      if (settlement) return settlement;
+      // No admission once cleanup begins, even on an early HTTP rejection.
+      closed = true;
+      settlement = (async () => {
+        let timer;
+        const timeout = new Promise((resolve) => {
+          timer = setTimeout(() => resolve(false), cleanupTimeoutMs);
+        });
+        const drain = async () => {
+          // A completed read can start reader cancellation. A single snapshot
+          // is insufficient: drain every newly registered native operation.
+          while (pending.size) await Promise.allSettled([...pending]);
+          return !cleanupFailed;
+        };
+        try {
+          const clean = await Promise.race([drain(), timeout]);
+          if (!clean) scope.invalidate();
+          return clean;
+        } finally {
+          clearTimeout(timer);
+        }
+      })();
+      return settlement;
+    },
+  };
+  const values = typeof bindings === "function" ? bindings(scope) : bindings;
+  if (!values || typeof values !== "object")
+    throw new TypeError("event bindings must be an object");
+  for (const name of Object.keys(values)) {
+    if (name in scope || name === "bindings")
+      throw new TypeError(`reserved event binding: ${name}`);
+  }
+  scope.bindings = Object.freeze({ ...values });
+  // The direct projection preserves the existing wasm-bindgen Host ABI.
+  Object.assign(scope, scope.bindings);
+  return Object.freeze(scope);
+}