ignotum 0.0.14 → 0.0.16

package/src/dev-runtime/database.ts

@@ -50,8 +50,8 @@ import {
   SchemaDefinitionTypeId,
   type ValueDescriptor,
 } from "@ignotum/contracts/schema";
-import { SchemaSnapshot } from "@ignotum/contracts/deployment";
-import { encodeCanonical } from "@ignotum/deployment";
+import { SchemaSnapshot } from "@ignotum/contracts/version";
+import { encodeCanonical } from "@ignotum/versions";
 import type { FileValue } from "@ignotum/contracts/schema/file";
 
 import { DevelopmentDatabase } from "./migrations.js";

package/src/dev-runtime/functions.ts

@@ -68,7 +68,7 @@ export type RuntimeHandlerContext = (LocalMutationContext | LocalQueryContext) &
 export type RuntimeFunctionDefinition = InternalRuntimeFunctionDefinition<RuntimeHandlerContext>;
 
 const loadDevelopmentEnvironment = Effect.fn("DevelopmentEnvironment.load")(function* (
-  server: ViteDevServer,
+  server: Pick<ViteDevServer, "ssrLoadModule">,
   appDirectory: string,
 ) {
   const fileSystem = yield* FileSystem.FileSystem;
@@ -100,7 +100,7 @@ export class DevelopmentEnvironment extends Context.Service<
     readonly snapshot: Effect.Effect<LoadedEnvironment, unknown>;
   }
 >()("ignotum/dev-runtime/functions/DevelopmentEnvironment") {
-  static layer(server: ViteDevServer, appDirectory: string) {
+  static layer(server: Pick<ViteDevServer, "ssrLoadModule">, appDirectory: string) {
     return Layer.effect(
       DevelopmentEnvironment,
       Effect.gen(function* () {
@@ -151,7 +151,7 @@ export class FunctionRegistry extends Context.Service<
     ) => Effect.Effect<ResolvedFunction, FunctionResolutionError>;
   }
 >()("ignotum/dev-runtime/functions/FunctionRegistry") {
-  static layer(server: ViteDevServer, appDirectory: string) {
+  static layer(server: Pick<ViteDevServer, "ssrLoadModule">, appDirectory: string) {
     return Layer.effect(
       FunctionRegistry,
       Effect.gen(function* () {

package/src/dev-runtime/managed-functions.ts

@@ -0,0 +1,255 @@
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { Crypto, Effect, Encoding, FileSystem, Path, Predicate, Schema } from "effect";
+import type { ViteDevServer } from "vite";
+import { parseSync } from "oxc-parser";
+import { prepareManagedExecution, type ManagedExecution } from "@ignotum/runtime/quickjs";
+import { apiFunctionParts } from "@ignotum/contracts/runtime/sync";
+import { getFunctionEnvironment } from "@ignotum/contracts/runtime/schema";
+import * as serverNamespace from "../server/index.js";
+import * as internalServerNamespace from "../internal/server.js";
+import * as apiNamespace from "../internal/api.js";
+import { validateManagedReleaseGraph } from "@ignotum/versions/managed-release";
+import { descriptorCodec } from "@ignotum/runtime/schema";
+import { SchemaSnapshotField } from "@ignotum/contracts/version";
+import { attachValueDescriptor, defineEnv, emptyEnv } from "@ignotum/contracts/schema";
+import type { ManagedServerBuildResult } from "../cli/build/managed-server.js";
+import type { buildManagedReleaseGraph } from "../cli/managed-release.js";
+
+type DevelopmentModule = Awaited<ReturnType<ViteDevServer["ssrLoadModule"]>>;
+const literal = Schema.encodeSync(Schema.fromJsonString(Schema.String));
+
+export class ManagedFunctionLoadFailed extends Schema.TaggedError<ManagedFunctionLoadFailed>()(
+  "ManagedFunctionLoadFailed",
+  { cause: Schema.Defect() },
+) {}
+
+export interface ManagedFunctionBuild extends Pick<
+  ManagedServerBuildResult,
+  "server" | "artifacts" | "bytes"
+> {
+  readonly environment?: {
+    readonly declaration: Pick<ManagedServerBuildResult["environment"]["declaration"], "fields">;
+  };
+}
+
+export interface ManagedFunctionLoader {
+  readonly reload: (build: ManagedFunctionBuild) => Effect.Effect<void, ManagedFunctionLoadFailed>;
+  readonly invalidate: (cause: unknown) => void;
+  readonly ssrLoadModule: (filename: string) => Promise<DevelopmentModule>;
+}
+
+export interface ManagedFunctionSelection {
+  readonly guest: Effect.Success<ReturnType<typeof buildManagedReleaseGraph>>;
+  readonly release: ManagedExecution["release"];
+  readonly requirements: ManagedExecution["requirements"];
+}
+
+/** Verify the deployed graph contract, then run app code with the local executor's SDK bindings. */
+export const createManagedFunctionLoader = Effect.fn("ManagedFunctions.createLoader")(function* (
+  appDirectory: string,
+  selection: ManagedFunctionSelection,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const crypto = yield* Crypto.Crypto;
+  const path = yield* Path.Path;
+  const directory = yield* fs.makeTempDirectoryScoped({ prefix: "ignotum-managed-functions-" });
+  const modules = new Map<string, Promise<DevelopmentModule>>();
+  let current = new Map<string, ReadonlyArray<{ readonly name: string; readonly url: string }>>();
+  let environment: Promise<DevelopmentModule> = Promise.resolve({ default: emptyEnv });
+  let failure: unknown;
+  const load = (url: string): Promise<DevelopmentModule> => {
+    let loaded = modules.get(url);
+    if (loaded === undefined) {
+      loaded = import(/* @vite-ignore */ url);
+      modules.set(url, loaded);
+    }
+    return loaded;
+  };
+  const namespaces = new Map<string, DevelopmentModule>([
+    ["ignotum/server", serverNamespace],
+    ["ignotum/internal/server", internalServerNamespace],
+    ["ignotum/internal/api", apiNamespace],
+  ]);
+  const guest = yield* validateManagedReleaseGraph(
+    selection.guest.manifestBytes,
+    [...selection.guest.files].map(([path, bytes]) => ({ path, bytes })),
+  );
+  const bridges = new Map<string, string>();
+  for (const [specifier, namespace] of namespaces) {
+    const entry = guest.manifest.modules.find(
+      (module) => module.path === guest.manifest.entries[specifier],
+    );
+    if (entry === undefined || entry.exports.some((name) => !Object.hasOwn(namespace, name))) {
+      throw new Error(`The local SDK cannot supply managed entry ${specifier}.`);
+    }
+    const filename = path.join(directory, `${encodeURIComponent(specifier)}.mjs`);
+    const key = Symbol.for(filename);
+    // A facade captures the existing SDK namespace so schemas and codecs retain their owner.
+    // The handoff exists only while this closed, generated facade is initialized.
+    yield* Effect.acquireUseRelease(
+      Effect.sync(() => {
+        Reflect.set(globalThis, key, namespace);
+      }),
+      () =>
+        Effect.gen(function* () {
+          const source =
+            `const namespace = globalThis[Symbol.for(${literal(filename)})];\n` +
+            entry.exports
+              .map(
+                (name, index) =>
+                  `const binding${index} = namespace[${literal(name)}]; export { binding${index} as ${name} };`,
+              )
+              .join("\n");
+          yield* fs.writeFileString(filename, source);
+          const url = pathToFileURL(filename).href;
+          yield* Effect.tryPromise({
+            try: () => load(url),
+            catch: (cause) => ManagedFunctionLoadFailed.make({ cause }),
+          });
+          bridges.set(specifier, url);
+        }),
+      () =>
+        Effect.sync(() => {
+          Reflect.deleteProperty(globalThis, key);
+        }),
+    );
+  }
+  const reload = Effect.fn("ManagedFunctions.reload")(
+    function* (build: ManagedFunctionBuild) {
+      const prepared = yield* prepareManagedExecution(
+        {
+          graph: build.server.graph,
+          artifacts: build.artifacts,
+          bytes: build.bytes,
+          entry: build.server.schema.entry,
+          release: selection.release,
+          requirements: selection.requirements,
+          guest: {
+            manifestBytes: selection.guest.manifestBytes,
+            files: [...selection.guest.files].map(([path, bytes]) => ({ path, bytes })),
+          },
+        },
+        "schema",
+      ).pipe(Effect.provideService(Crypto.Crypto, crypto));
+      const urls = new Map(
+        prepared.modules
+          .filter((module) => module.owner === "App")
+          .map((module) => [
+            module.id,
+            pathToFileURL(path.join(directory, `${encodeURIComponent(module.id)}.mjs`)).href,
+          ]),
+      );
+      for (const module of prepared.modules.filter((module) => module.owner === "App")) {
+        const source = prepared.load(module.id);
+        const parsed = parseSync(`${module.id}.mjs`, source, { sourceType: "module" });
+        if (parsed.module.dynamicImports.length > 0)
+          throw new Error("Managed local modules cannot use dynamic imports.");
+        if (parsed.errors.length > 0)
+          throw new Error(`Could not parse managed module ${module.id}.`);
+        const replacements: Array<{ start: number; end: number; value: string }> = [];
+        for (const statement of parsed.program.body) {
+          if (
+            statement.type !== "ImportDeclaration" &&
+            statement.type !== "ExportNamedDeclaration" &&
+            statement.type !== "ExportAllDeclaration"
+          )
+            continue;
+          if (statement.source === null) continue;
+          const targetId = prepared.normalize(module.id, statement.source.value);
+          const target = bridges.get(statement.source.value) ?? urls.get(targetId);
+          if (target === undefined) throw new Error("Missing verified managed module target.");
+          replacements.push({
+            start: statement.source.start,
+            end: statement.source.end,
+            value: literal(target),
+          });
+        }
+        let rewritten = source;
+        for (const replacement of replacements.sort((a, b) => b.start - a.start)) {
+          rewritten =
+            rewritten.slice(0, replacement.start) +
+            replacement.value +
+            rewritten.slice(replacement.end);
+        }
+        if (module.sourceMap !== undefined) {
+          rewritten = rewritten.replace(/^\/\/# sourceMappingURL=.*$/gm, "");
+          rewritten += `\n//# sourceMappingURL=data:application/json;base64,${Encoding.encodeBase64(module.sourceMap.bytes)}\n`;
+        }
+        yield* fs.writeFileString(fileURLToPath(urls.get(module.id)!), rewritten);
+      }
+      const next = new Map<string, Array<{ name: string; url: string }>>();
+      next.set(path.resolve(appDirectory, "server/schema.ts"), [
+        { name: "default", url: urls.get(build.server.schema.entry.module)! },
+      ]);
+      for (const fn of build.server.functions) {
+        const { moduleName, functionName } = apiFunctionParts(fn.address);
+        const filename = path.resolve(appDirectory, "server", `${moduleName}.ts`);
+        const entries = next.get(filename) ?? [];
+        entries.push({ name: functionName, url: urls.get(fn.entry.module)! });
+        next.set(filename, entries);
+      }
+      const first = build.server.functions[0];
+      const fields = yield* Schema.decodeEffect(Schema.Array(SchemaSnapshotField))(
+        build.environment?.declaration.fields ?? [],
+      );
+      const declaredEnvironment =
+        fields.length === 0
+          ? emptyEnv
+          : defineEnv(() =>
+              Object.fromEntries(
+                fields.map((field) => [
+                  field.name,
+                  attachValueDescriptor(
+                    Schema.make<Schema.Codec<unknown>>(descriptorCodec(field.value).ast),
+                    field.value,
+                  ),
+                ]),
+              ),
+            );
+
+      environment =
+        first === undefined
+          ? Promise.resolve({ default: declaredEnvironment })
+          : load(urls.get(first.entry.module)!).then((loaded) => {
+              const candidate = loaded[first.entry.exportName];
+              return {
+                default: Predicate.isObject(candidate)
+                  ? getFunctionEnvironment(candidate)
+                  : undefined,
+              };
+            });
+      yield* Effect.tryPromise({
+        try: () => environment,
+        catch: (cause) => ManagedFunctionLoadFailed.make({ cause }),
+      });
+      current = next;
+      failure = undefined;
+    },
+    Effect.tapCause((cause) =>
+      Effect.sync(() => {
+        failure = cause;
+      }),
+    ),
+    Effect.mapError((cause) => ManagedFunctionLoadFailed.make({ cause })),
+  );
+  const loader: ManagedFunctionLoader = {
+    reload,
+    invalidate: (cause: unknown): void => {
+      failure = cause ?? new Error("Managed server compilation failed.");
+    },
+    ssrLoadModule: async (filename: string): Promise<DevelopmentModule> => {
+      if (failure !== undefined) throw failure;
+      const normalized = path.resolve(filename);
+      if (normalized === path.resolve(appDirectory, "server/env.ts")) return environment;
+      const entries = current.get(normalized);
+      if (entries === undefined)
+        throw new Error(`Module is outside the managed server graph: ${filename}`);
+      return Object.fromEntries(
+        await Promise.all(
+          entries.map(async (entry) => [entry.name, (await load(entry.url)).default]),
+        ),
+      );
+    },
+  };
+  return loader;
+});

package/src/dev-runtime/managed-sync.ts

@@ -0,0 +1,263 @@
+import { canonicalInvocationInput } from "@ignotum/contracts/runtime/hosted";
+import { ManagedClientMessage, ManagedServerMessage } from "@ignotum/contracts/managed-sync";
+import {
+  sameExecutionSelection,
+  ExecutionSelection,
+  type RecoveryIdentity,
+  type RecoverySessionId,
+} from "@ignotum/contracts/platform";
+import { idViewKey, type SessionState } from "@ignotum/contracts/id";
+import type { ViteDevServer } from "vite";
+import { Clock, Deferred, Effect, PubSub, Schema, Semaphore } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+import * as Socket from "effect/unstable/socket/Socket";
+import { LocalApplicationFiles } from "./files.js";
+import { MutationReplay, QueryInvalidation, createLocalSession } from "./sync.js";
+
+export interface ManagedSyncOptions {
+  readonly selection: () => ExecutionSelection;
+  readonly loadModule?: ViteDevServer["ssrLoadModule"];
+  readonly isServerDependency?: (file: string) => boolean;
+  readonly beforeReload?: (file: string, event: "add" | "change" | "unlink") => Promise<void>;
+}
+
+/** Native managed protocol framing, selection fencing, and durable invocation ownership. */
+export const runManagedSession = Effect.fn("ManagedLocalSync.runSession")(function* (
+  socket: Socket.Socket,
+  options: ManagedSyncOptions,
+  identity: SessionState,
+  refreshIdentity?: Effect.Effect<SessionState>,
+) {
+  const sql = yield* SqlClient.SqlClient;
+  const files = yield* LocalApplicationFiles;
+  const preparations = new Set<import("@ignotum/contracts/runtime/hosted").InvocationId>();
+  const shutdown = yield* Deferred.make<void>();
+  const replays = yield* MutationReplay;
+  const invalidation = yield* QueryInvalidation;
+  const write = yield* socket.writer;
+  const writes = yield* Semaphore.make(1);
+  const messages = yield* Semaphore.make(1);
+  let selection: ExecutionSelection | undefined;
+  let session: Effect.Success<ReturnType<typeof createLocalSession>> | undefined;
+  let clientSessionId: RecoverySessionId | undefined;
+  let expired = false;
+  const send = (message: ManagedServerMessage) =>
+    writes.withPermits(1)(
+      Schema.encodeEffect(Schema.fromJsonString(ManagedServerMessage))(message).pipe(
+        Effect.orDie,
+        Effect.flatMap(write),
+      ),
+    );
+  const error = (
+    code:
+      | "InvalidMessage"
+      | "SessionExpired"
+      | "InvocationIdConflict"
+      | "Unavailable"
+      | "InvalidArguments",
+    message: string,
+    id?: string,
+  ) =>
+    send(
+      id === undefined ? { type: "Error", code, message } : { type: "Error", code, message, id },
+    );
+  const close = Effect.gen(function* () {
+    expired = true;
+    yield* write(new Socket.CloseEvent(1000, "Local managed session ended")).pipe(
+      Effect.ensuring(Deferred.succeed(shutdown, undefined)),
+    );
+  });
+  const checkSelection = Effect.fn("ManagedLocalSync.checkSelection")(function* () {
+    if (expired) return false;
+    if (selection === undefined || sameExecutionSelection(selection, options.selection()))
+      return true;
+    expired = true;
+    yield* send({ type: "UpgradeRequired", selection: options.selection() });
+    yield* close;
+    return false;
+  });
+  const checkIdentity = Effect.fn("ManagedLocalSync.checkIdentity")(function* () {
+    if (expired) return false;
+    const current = refreshIdentity === undefined ? identity : yield* refreshIdentity;
+    if (
+      current.sessionEpoch === identity.sessionEpoch &&
+      idViewKey(current) === idViewKey(identity) &&
+      current.validUntil > (yield* Clock.currentTimeMillis)
+    )
+      return true;
+    expired = true;
+    yield* error("SessionExpired", "The local ID session changed or expired.");
+    yield* close;
+    return false;
+  });
+  const events = yield* invalidation.subscribe;
+  yield* PubSub.take(events).pipe(
+    Effect.andThen(checkSelection()),
+    Effect.flatMap((current) => (current ? checkIdentity() : Effect.succeed(false))),
+    Effect.forever,
+    Effect.forkScoped,
+  );
+  const ownerRows = (invocationId: string) =>
+    sql<{
+      input: string;
+      prepared: number;
+      clientSessionId: string;
+      sessionEpoch: string;
+      selection: string;
+    }>`SELECT input, prepared, clientSessionId, sessionEpoch, selection FROM managed_invocation_owners WHERE id = ${invocationId}`;
+  const owns = (
+    row: { clientSessionId: string; sessionEpoch: string; selection: string },
+    original: ExecutionSelection,
+  ) =>
+    row.clientSessionId === clientSessionId &&
+    row.sessionEpoch === identity.sessionEpoch &&
+    sameExecutionSelection(
+      Schema.decodeSync(Schema.fromJsonString(ExecutionSelection))(row.selection),
+      original,
+    );
+  const outcome = Effect.fn("ManagedLocalSync.outcome")(function* (
+    id: string,
+    recovery: RecoveryIdentity,
+  ) {
+    if (
+      selection === undefined ||
+      recovery.originalSelection.appId !== selection.appId ||
+      recovery.originalSelection.dataHistoryId !== selection.dataHistoryId
+    ) {
+      yield* error(
+        "Unavailable",
+        "This recovery record belongs to another application data history.",
+        id,
+      );
+      return;
+    }
+    const rows = yield* ownerRows(recovery.invocationId).pipe(Effect.orDie);
+    if (rows[0] === undefined || !owns(rows[0], recovery.originalSelection)) {
+      yield* error("SessionExpired", "This session does not own the mutation recovery record.", id);
+      return;
+    }
+    const result = yield* replays.lookup(recovery.invocationId).pipe(Effect.orDie);
+    yield* send({
+      type: "MutationOutcome",
+      id,
+      identity: recovery,
+      outcome: result === undefined ? { type: "Uncertain" } : { type: "Settled", result },
+    });
+  });
+  const deliver = Effect.fn("ManagedLocalSync.deliver")(function* (message: ManagedServerMessage) {
+    if (!(yield* checkSelection()) || !(yield* checkIdentity())) return;
+    yield* send(message);
+  });
+  yield* Effect.addFinalizer(() =>
+    Effect.forEach(preparations, (id) => files.releasePreparation(id)),
+  );
+  yield* socket
+    .runString((text) =>
+      messages.withPermits(1)(
+        Effect.gen(function* () {
+          const message = yield* Schema.decodeEffect(Schema.fromJsonString(ManagedClientMessage))(
+            text,
+          ).pipe(
+            Effect.catch(() =>
+              error("InvalidMessage", "The frame is not valid managed sync JSON."),
+            ),
+          );
+          if (message === undefined) return;
+          if (message.type === "Connect") {
+            if (selection !== undefined)
+              return yield* error("InvalidMessage", "Connect has already been accepted.");
+            const current = options.selection();
+            if (
+              message.protocolVersion !== 1 ||
+              !sameExecutionSelection(message.selection, current)
+            ) {
+              yield* send({ type: "UpgradeRequired", selection: current });
+              return;
+            }
+            if (!(yield* checkIdentity())) return;
+            selection = current;
+            clientSessionId = message.clientSessionId;
+            session = yield* createLocalSession(current, identity, deliver);
+            yield* send({
+              type: "Handshake",
+              protocolVersion: 1,
+              selection,
+              session: identity,
+              serverTime: yield* Clock.currentTimeMillis,
+            });
+            return;
+          }
+          if (selection === undefined || session === undefined)
+            return yield* error("InvalidMessage", "Connect must be accepted first.");
+          if (expired || !(yield* checkSelection())) return;
+          if (!(yield* checkIdentity())) return;
+          if (message.type === "RecoverMutation")
+            return yield* outcome(message.id, message.identity);
+          if (message.type === "Invoke" || message.type === "Prepare") {
+            const input = canonicalInvocationInput(
+              selection.versionId,
+              "Mutation",
+              message.function,
+              message.args,
+              identity.sessionEpoch,
+            );
+            const rows = yield* ownerRows(message.invocationId).pipe(Effect.orDie);
+            if (rows[0] !== undefined && (!owns(rows[0], selection) || rows[0].input !== input))
+              return yield* error(
+                "InvocationIdConflict",
+                "This invocation belongs to another input, selection or session.",
+                message.invocationId,
+              );
+            if (
+              rows[0] === undefined &&
+              (yield* replays.lookup(message.invocationId).pipe(Effect.orDie)) !== undefined
+            )
+              return yield* error(
+                "InvocationIdConflict",
+                "This invocation already exists outside this managed session.",
+                message.invocationId,
+              );
+            const encodedSelection = yield* Schema.encodeEffect(
+              Schema.fromJsonString(ExecutionSelection),
+            )(selection).pipe(Effect.orDie);
+            const inserted =
+              yield* sql`INSERT OR IGNORE INTO managed_invocation_owners (id, input, prepared, clientSessionId, sessionEpoch, selection) VALUES (${message.invocationId}, ${input}, ${message.type === "Prepare" ? 1 : 0}, ${clientSessionId!}, ${identity.sessionEpoch}, ${encodedSelection}) RETURNING id`.pipe(
+                Effect.orDie,
+              );
+            const admitted = yield* ownerRows(message.invocationId).pipe(Effect.orDie);
+            if (
+              admitted[0] === undefined ||
+              admitted[0].input !== input ||
+              !owns(admitted[0], selection)
+            )
+              return yield* error(
+                "InvocationIdConflict",
+                "This invocation belongs to another session.",
+                message.invocationId,
+              );
+            if (inserted.length === 0) {
+              if (admitted[0].prepared === 0)
+                return yield* outcome(message.invocationId, {
+                  invocationId: message.invocationId,
+                  originalSelection: selection,
+                });
+              if (message.type === "Invoke") {
+                const claimed =
+                  yield* sql`UPDATE managed_invocation_owners SET prepared = 0 WHERE id = ${message.invocationId} AND prepared = 1 RETURNING id`.pipe(
+                    Effect.orDie,
+                  );
+                if (claimed.length === 0)
+                  return yield* outcome(message.invocationId, {
+                    invocationId: message.invocationId,
+                    originalSelection: selection,
+                  });
+              }
+            }
+            preparations.add(message.invocationId);
+          }
+          yield* session.handle(message);
+        }),
+      ),
+    )
+    .pipe(Effect.raceFirst(Deferred.await(shutdown)));
+}, Effect.scoped);

package/src/dev-runtime/managed-websocket.ts

@@ -0,0 +1,71 @@
+// @effect-diagnostics-next-line nodeBuiltinImport:off Vite supplies Node HTTP upgrade requests.
+import type { IncomingMessage } from "node:http";
+// @effect-diagnostics-next-line nodeBuiltinImport:off Vite supplies the raw Node upgrade socket.
+import type { Duplex } from "node:stream";
+import { NodeSocket } from "@effect/platform-node";
+import { Cause, Context, Effect, FiberSet, Function, Layer } from "effect";
+import * as Socket from "effect/unstable/socket/Socket";
+
+/** Owns upgraded sessions without sending an HTTP response when a session ends. */
+const makeManagedWebSocketUpgradeHandler = Effect.fn("ManagedWebSocket.makeUpgradeHandler")(
+  function* <E, R>(
+    server: NodeSocket.NodeWS.WebSocketServer,
+    handle: (socket: Socket.Socket, request: IncomingMessage) => Effect.Effect<void, E, R>,
+  ) {
+    const run = yield* FiberSet.makeRuntime<R>();
+    return (request: IncomingMessage, raw: Duplex, head: Buffer): void => {
+      const session = Effect.gen(function* () {
+        const socket = yield* Socket.fromWebSocket(
+          Effect.acquireRelease(
+            Effect.callback<globalThis.WebSocket>((resume) => {
+              server.handleUpgrade(request, raw, head, (webSocket) => {
+                // SAFETY: Effect's NodeSocket layer uses this same NodeWS/DOM bridge. Socket.fromWebSocket consumes compatible events, send and close methods.
+                // eslint-disable-next-line anti-slop/no-chained-type-assertions
+                resume(Effect.succeed(webSocket as unknown as globalThis.WebSocket));
+              });
+            }),
+            (webSocket) => Effect.sync(() => webSocket.close()),
+          ),
+          { closeCodeIsError: Function.constFalse },
+        );
+        yield* handle(socket, request);
+      }).pipe(
+        Effect.scoped,
+        Effect.catchCause((cause) =>
+          Cause.hasInterruptsOnly(cause)
+            ? Effect.void
+            : Effect.logError("A managed local WebSocket session failed.").pipe(
+                Effect.annotateLogs({ cause }),
+              ),
+        ),
+      );
+      const fiber = run(session);
+      const onClose = () => fiber.interruptUnsafe();
+      raw.on("error", Function.constVoid);
+      raw.once("close", onClose);
+      fiber.addObserver(() => {
+        raw.off("error", Function.constVoid);
+        raw.off("close", onClose);
+      });
+    };
+  },
+);
+
+export class ManagedWebSocket extends Context.Service<
+  ManagedWebSocket,
+  {
+    readonly upgrade: (request: IncomingMessage, socket: Duplex, head: Buffer) => void;
+  }
+>()("ignotum/dev-runtime/managed-websocket/ManagedWebSocket") {
+  static layer<E, R>(
+    server: NodeSocket.NodeWS.WebSocketServer,
+    handle: (socket: Socket.Socket, request: IncomingMessage) => Effect.Effect<void, E, R>,
+  ) {
+    return Layer.effect(
+      ManagedWebSocket,
+      makeManagedWebSocketUpgradeHandler(server, handle).pipe(
+        Effect.map((upgrade) => ManagedWebSocket.of({ upgrade })),
+      ),
+    );
+  }
+}

package/src/dev-runtime/migrations.ts

@@ -101,6 +101,17 @@ export const developmentMigrationLoader = Migrator.fromRecord({
   "0002_application_indexes": addDevelopmentIndexes,
   "0003_application_files": addApplicationFiles,
   "0004_schema_state": addSchemaState,
+  "0005_managed_invocation_owners": Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    yield* sql`CREATE TABLE managed_invocation_owners (
+      id TEXT PRIMARY KEY NOT NULL,
+      input TEXT NOT NULL,
+      prepared INTEGER NOT NULL DEFAULT 0 CHECK (prepared IN (0, 1)),
+      clientSessionId TEXT NOT NULL,
+      sessionEpoch TEXT NOT NULL,
+      selection TEXT NOT NULL CHECK (json_valid(selection))
+    ) STRICT`;
+  }),
 });
 
 interface DevelopmentDatabaseService {