ignotum 0.0.13 → 0.0.15

package/src/dev-runtime/sync.ts

@@ -1,7 +1,13 @@
+import {
+  managedSyncPath,
+  type ManagedClientMessage,
+  type ManagedServerMessage,
+} from "@ignotum/contracts/managed-sync";
+import { runManagedSession, type ManagedSyncOptions } from "./managed-sync.js";
+import { ManagedWebSocket } from "./managed-websocket.js";
 import { LocalQueryCache } from "./query-cache.js";
 import {
   SessionRequest,
-  idViewKey,
   sessionPath,
   sessionRequestsPath,
   type SessionState,
@@ -13,31 +19,19 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { NodeHttpServer, NodeServices, NodeSocket } from "@effect/platform-node";
 import { SqliteClient } from "@effect/sql-sqlite-node";
 import {
-  AppId,
   AppStateRevision,
-  DeploymentGeneration,
-  DeploymentId,
   InvocationId,
   RuntimeMutationResult,
   canonicalInvocationInput,
   canonicalQueryKey,
 } from "@ignotum/contracts/runtime/hosted";
-import {
-  ClientMessageJson,
-  ServerMessageJson,
-  type ClientMessage,
-  type FunctionAddress,
-  type Operation,
-  type ErrorCode,
-  type ServerMessage,
-  type SubscriptionId,
-} from "@ignotum/contracts/runtime/sync";
+import { SubscriptionId, type FunctionAddress } from "@ignotum/contracts/runtime/sync";
+import type { ExecutionSelection } from "@ignotum/contracts/platform";
 import {
   Effect,
   Clock,
   Context,
   FileSystem,
-  Function,
   FiberSet,
   HashMap,
   Layer,
@@ -70,7 +64,7 @@ import {
 } from "@ignotum/runtime/sync";
 
 import { generate } from "../cli/codegen.js";
-import { isIgnotumPath, syncPath } from "../internal/http-paths.js";
+import { isIgnotumPath } from "../internal/http-paths.js";
 import { LocalDatabase } from "./database.js";
 import { IdGenerator } from "@ignotum/shared/id";
 import { DevelopmentDatabase } from "./migrations.js";
@@ -85,16 +79,11 @@ import { LocalApplicationFiles, localApplicationFilesLayer } from "./files.js";
 interface QuerySubscription {
   readonly args: Schema.Json;
   readonly function: FunctionAddress;
+  readonly grantId: SubscriptionId;
   readonly queryKey: ReturnType<typeof canonicalQueryKey>;
   refreshGeneration: number;
 }
 
-export const localSyncIdentity = {
-  appId: AppId.make("app_000000000000000000000001"),
-  deploymentId: DeploymentId.make("dep_000000000000000000000001"),
-  generation: DeploymentGeneration.make(0),
-} as const;
-
 export { QueryInvalidation };
 
 const reloadEnvironmentAndInvalidate = <Error, Requirements>(
@@ -134,9 +123,12 @@ class InvocationIdConflict extends Schema.TaggedError<InvocationIdConflict>()(
 
 const MutationReplayRow = Schema.Struct({ input: Schema.String, result: Schema.String });
 
-class MutationReplay extends Context.Service<
+export class MutationReplay extends Context.Service<
   MutationReplay,
   {
+    readonly lookup: (
+      id: InvocationId,
+    ) => Effect.Effect<RuntimeMutationResult | undefined, SqlError.SqlError>;
     readonly execute: (
       id: InvocationId,
       input: string,
@@ -161,6 +153,16 @@ class MutationReplay extends Context.Service<
       });
 
       return MutationReplay.of({
+        lookup: Effect.fn("MutationReplay.lookup")(function* (id) {
+          const replay = yield* findReplay({ id }).pipe(
+            Effect.catchTags({ SchemaError: Effect.die }),
+          );
+          return Option.isNone(replay)
+            ? undefined
+            : yield* Schema.decodeEffect(Schema.fromJsonString(RuntimeMutationResult))(
+                replay.value.result,
+              ).pipe(Effect.orDie);
+        }),
         execute: Effect.fn("MutationReplay.execute")(
           function* (
             id,
@@ -198,63 +200,57 @@ class MutationReplay extends Context.Service<
 
 export const mutationReplayLayer = MutationReplay.layer;
 
-const operationForSubscription = (subscriptionId: SubscriptionId): Operation => ({
-  type: "Subscription",
-  id: subscriptionId,
-});
-
-const syncError = (code: ErrorCode, message: string, operation?: Operation): ServerMessage => {
-  if (operation === undefined) {
-    return { type: "Error", code, message };
+export type LocalSessionMessage = Extract<
+  ManagedClientMessage,
+  {
+    readonly type: "Subscribe" | "Unsubscribe" | "Prepare" | "Invoke";
   }
-  return { type: "Error", code, message, operation };
-};
+>;
+type LocalErrorCode = Extract<ManagedServerMessage, { readonly type: "Error" }>["code"];
+const syncError = (code: LocalErrorCode, message: string, id: string): ManagedServerMessage => ({
+  type: "Error",
+  code,
+  message,
+  id,
+});
 
-export const runSession = Effect.fn("SyncServer.runSession")(function* (
-  socket: Socket.Socket,
-  initialIdentity?: SessionState,
-  refreshIdentity?: Effect.Effect<SessionState>,
+/** Executes admitted session commands directly; the transport owns framing and selection checks. */
+export const createLocalSession = Effect.fn("LocalSession.create")(function* (
+  selection: ExecutionSelection,
+  identity: SessionState,
+  send: (message: ManagedServerMessage) => Effect.Effect<void, Socket.SocketError>,
 ) {
-  let identity = initialIdentity ?? {
-    sessionEpoch: "dev:anonymous",
-    user: null,
-    viewRevision: 0,
-    validUntil: Number.MAX_SAFE_INTEGER,
-  };
   const runtime = yield* FunctionRuntime;
+  const ids = yield* IdGenerator;
   const invalidation = yield* QueryInvalidation;
   const mutationReplay = yield* MutationReplay;
   const queryCache = yield* LocalQueryCache;
   const files = yield* LocalApplicationFiles;
   const subscriptions = yield* Ref.make(HashMap.empty<SubscriptionId, QuerySubscription>());
   const dependencyIndex = makeDependencyIndex<SubscriptionId>();
+  yield* Effect.addFinalizer(() =>
+    Ref.get(subscriptions).pipe(
+      Effect.flatMap((active) =>
+        Effect.forEach(HashMap.values(active), (subscription) =>
+          files.releaseGrants(subscription.grantId),
+        ),
+      ),
+      Effect.asVoid,
+    ),
+  );
   const invocationFibers = yield* FiberSet.make();
-  const messageSemaphore = yield* Semaphore.make(1);
-  const writeSemaphore = yield* Semaphore.make(1);
-  const write = yield* socket.writer;
-
-  const send = Effect.fn("SyncServer.send")(function* (message: ServerMessage) {
-    const bound =
-      message.type === "Result" || message.type === "Preparation" || message.type === "Error"
-        ? { ...message, sessionEpoch: identity.sessionEpoch }
-        : message;
-    yield* writeSemaphore.withPermits(1)(
-      Schema.encodeEffect(ServerMessageJson)(bound).pipe(Effect.flatMap(write)),
-    );
-  });
 
   const sendResolutionError = (
-    operation: Operation,
+    operation: string,
     error:
       | { readonly _tag: "UnknownFunction"; readonly message: string }
       | { readonly _tag: "WrongFunctionKind"; readonly message: string }
       | { readonly _tag: "InvalidArguments"; readonly message: string }
       | { readonly _tag: "FunctionUnavailable"; readonly message: string },
-    deliver: (
-      message: ServerMessage,
-    ) => Effect.Effect<void, Schema.SchemaError | Socket.SocketError> = send,
+    deliver: (message: ManagedServerMessage) => Effect.Effect<void, Socket.SocketError> = send,
   ) => {
-    const code: ErrorCode = error._tag;
+    const code: LocalErrorCode =
+      error._tag === "InvalidArguments" ? "InvalidArguments" : "Unavailable";
     return deliver(syncError(code, error.message, operation));
   };
 
@@ -268,7 +264,7 @@ export const runSession = Effect.fn("SyncServer.runSession")(function* (
   const sendIfActive = Effect.fn("SyncServer.sendIfActive")(function* (
     subscriptionId: SubscriptionId,
     subscription: QuerySubscription,
-    message: ServerMessage,
+    message: ManagedServerMessage,
   ) {
     if (yield* isActive(subscriptionId, subscription)) {
       yield* send(message);
@@ -281,8 +277,9 @@ export const runSession = Effect.fn("SyncServer.runSession")(function* (
     refreshGeneration: number,
     previouslyPrepared?: PreparedFunction,
   ) {
-    const operation = operationForSubscription(subscriptionId);
-    const deliver = (message: ServerMessage) => sendIfActive(subscriptionId, subscription, message);
+    const operation = subscriptionId;
+    const deliver = (message: ManagedServerMessage) =>
+      sendIfActive(subscriptionId, subscription, message);
     let prepared = previouslyPrepared;
 
     while (yield* isActive(subscriptionId, subscription)) {
@@ -317,17 +314,12 @@ export const runSession = Effect.fn("SyncServer.runSession")(function* (
       }
       dependencyIndex.record(subscriptionId, result.dependencies);
       if ((yield* invalidation.latestRevision) > result.observedRevision) continue;
-      const granted = yield* files.grants(subscriptionId, result.files ?? []);
+      const granted = yield* files.grants(subscription.grantId, result.files ?? []);
       const snapshot = {
-        type: "Snapshot",
+        type: "QuerySnapshot",
         id: subscriptionId,
-        result: result.result,
-        revision: result.observedRevision,
-        identity: {
-          sessionEpoch: identity.sessionEpoch,
-          viewRevision: identity.viewRevision,
-          dependsOnId: result.dependencies.some((dependency) => dependency.type === "Id"),
-        },
+        selection,
+        result,
       } as const;
       yield* deliver(granted.length === 0 ? snapshot : { ...snapshot, files: granted });
       return;
@@ -352,19 +344,6 @@ export const runSession = Effect.fn("SyncServer.runSession")(function* (
   };
 
   const refreshAll = Effect.fn("SyncServer.refreshAll")(function* () {
-    if (refreshIdentity !== undefined) {
-      const next = yield* refreshIdentity;
-      const changed =
-        idViewKey(identity) !== idViewKey(next) || identity.validUntil !== next.validUntil;
-      identity = next;
-      if (changed)
-        yield* send({
-          type: "Session",
-          event: "Updated",
-          session: identity,
-          serverTime: yield* Clock.currentTimeMillis,
-        });
-    }
     const current = yield* Ref.get(subscriptions);
     yield* Effect.forEach(HashMap.toEntries(current), ([subscriptionId, subscription]) =>
       scheduleQuery(subscriptionId, subscription),
@@ -391,9 +370,9 @@ export const runSession = Effect.fn("SyncServer.runSession")(function* (
   );
 
   const handleSubscribe = Effect.fn("SyncServer.handleSubscribe")(function* (
-    message: Extract<ClientMessage, { readonly type: "Subscribe" }>,
+    message: Extract<LocalSessionMessage, { readonly type: "Subscribe" }>,
   ) {
-    const operation = operationForSubscription(message.id);
+    const operation = message.id;
     if (encodedFileOccurrencesOf(message.args).length > 0) {
       yield* send(
         syncError("InvalidArguments", "Queries cannot take files as arguments.", operation),
@@ -404,7 +383,7 @@ export const runSession = Effect.fn("SyncServer.runSession")(function* (
 
     if (HashMap.has(current, message.id)) {
       yield* send(
-        syncError("DuplicateOperationId", `Subscription ${message.id} already exists.`, operation),
+        syncError("InvalidMessage", `Subscription ${message.id} already exists.`, operation),
       );
       return;
     }
@@ -425,7 +404,8 @@ export const runSession = Effect.fn("SyncServer.runSession")(function* (
     const subscription = {
       args: message.args,
       function: message.function,
-      queryKey: canonicalQueryKey(localSyncIdentity.deploymentId, message.function, message.args),
+      grantId: yield* ids.generate(SubscriptionId),
+      queryKey: canonicalQueryKey(selection.versionId, message.function, message.args),
       refreshGeneration: 0,
     };
     yield* Ref.update(subscriptions, HashMap.set(message.id, subscription));
@@ -433,10 +413,10 @@ export const runSession = Effect.fn("SyncServer.runSession")(function* (
   });
 
   const handleInvoke = Effect.fn("SyncServer.handleInvoke")(function* (
-    message: Extract<ClientMessage, { readonly type: "Invoke" }>,
+    message: Extract<LocalSessionMessage, { readonly type: "Invoke" }>,
   ) {
-    const operation: Operation = { type: "Invocation", id: message.id };
-    const admitted = yield* files.admit(message.id, message.function, message.args).pipe(
+    const operation = message.invocationId;
+    const admitted = yield* files.admit(message.invocationId, message.function, message.args).pipe(
       Effect.as(true),
       Effect.catchCause((cause) =>
         send(
@@ -449,7 +429,7 @@ export const runSession = Effect.fn("SyncServer.runSession")(function* (
       ),
     );
     if (!admitted) {
-      yield* files.releasePreparation(message.id);
+      yield* files.releasePreparation(message.invocationId);
       return;
     }
     const prepared = yield* runtime
@@ -464,12 +444,12 @@ export const runSession = Effect.fn("SyncServer.runSession")(function* (
       );
 
     if (prepared === undefined) {
-      yield* files.releasePreparation(message.id);
+      yield* files.releasePreparation(message.invocationId);
       return;
     }
 
     const input = canonicalInvocationInput(
-      localSyncIdentity.deploymentId,
+      selection.versionId,
       "Mutation",
       message.function,
       message.args,
@@ -477,7 +457,7 @@ export const runSession = Effect.fn("SyncServer.runSession")(function* (
     );
     yield* mutationReplay
       .execute(
-        message.id,
+        message.invocationId,
         input,
         prepared.execute.pipe(
           Effect.flatMap((result) =>
@@ -487,39 +467,42 @@ export const runSession = Effect.fn("SyncServer.runSession")(function* (
       )
       .pipe(
         Effect.flatMap((result) => {
-          if (!("committedRevision" in result)) {
-            return send({ type: "Result", id: message.id, result: result.result });
-          }
           const response = send({
-            type: "Result",
-            id: message.id,
-            result: result.result,
-            committedRevision: result.committedRevision,
+            type: "MutationOutcome",
+            id: message.invocationId,
+            identity: { invocationId: message.invocationId, originalSelection: selection },
+            outcome: { type: "Settled", result },
           });
-          return response.pipe(
-            Effect.ensuring(
-              invalidation.publish({
-                type: "Dependencies",
-                invalidations: result.invalidations,
-                committedRevision: result.committedRevision,
-              }),
-            ),
-          );
+          return "committedRevision" in result
+            ? response.pipe(
+                Effect.ensuring(
+                  invalidation.publish({
+                    type: "Dependencies",
+                    invalidations: result.invalidations,
+                    committedRevision: result.committedRevision,
+                  }),
+                ),
+              )
+            : response;
         }),
         Effect.catchTags({
           InvocationIdConflict: () =>
             send(
               syncError(
                 "InvocationIdConflict",
-                `Invocation ${message.id} was already used with different inputs.`,
+                `Invocation ${message.invocationId} was already used with different inputs.`,
                 operation,
               ),
             ),
         }),
-        Effect.ensuring(files.releasePreparation(message.id)),
+        Effect.ensuring(files.releasePreparation(message.invocationId)),
         Effect.catchCause((cause) =>
           Effect.logError("A mutation invocation fiber failed.").pipe(
-            Effect.annotateLogs({ cause, function: message.function, requestId: message.id }),
+            Effect.annotateLogs({
+              cause,
+              function: message.function,
+              requestId: message.invocationId,
+            }),
           ),
         ),
         FiberSet.run(invocationFibers),
@@ -528,12 +511,12 @@ export const runSession = Effect.fn("SyncServer.runSession")(function* (
   });
 
   const handlePrepare = Effect.fn("SyncServer.handlePrepare")(function* (
-    message: Extract<ClientMessage, { readonly type: "Prepare" }>,
+    message: Extract<LocalSessionMessage, { readonly type: "Prepare" }>,
   ) {
-    const operation: Operation = { type: "Invocation", id: message.id };
-    yield* files.prepare(message.id, message.function, message.args, message.files).pipe(
+    const operation = message.invocationId;
+    yield* files.prepare(message.invocationId, message.function, message.args, message.files).pipe(
       Effect.flatMap((uploads) =>
-        send({ type: "Preparation", id: message.id, kind: message.kind, uploads }),
+        send({ type: "Preparation", invocationId: message.invocationId, uploads }),
       ),
       Effect.catchCause((cause) =>
         send(
@@ -547,26 +530,19 @@ export const runSession = Effect.fn("SyncServer.runSession")(function* (
     );
   });
 
-  const handleMessage = Effect.fn("SyncServer.handleMessage")(function* (text: string) {
-    const message = yield* Schema.decodeEffect(ClientMessageJson)(text).pipe(
-      Effect.catch(() =>
-        send(syncError("InvalidMessage", "The WebSocket frame is not valid Ignotum JSON.")),
-      ),
-    );
-
-    if (message === undefined) {
-      return;
-    }
-
+  const handle = Effect.fn("LocalSession.handle")(function* (message: LocalSessionMessage) {
     switch (message.type) {
       case "Subscribe":
         yield* handleSubscribe(message);
         return;
-      case "Unsubscribe":
+      case "Unsubscribe": {
+        const current = yield* Ref.get(subscriptions);
+        const subscription = Option.getOrUndefined(HashMap.get(current, message.id));
         dependencyIndex.remove(message.id);
         yield* Ref.update(subscriptions, HashMap.remove(message.id));
-        yield* files.releaseGrants(message.id);
+        if (subscription !== undefined) yield* files.releaseGrants(subscription.grantId);
         return;
+      }
       case "Prepare":
         yield* handlePrepare(message);
         return;
@@ -575,31 +551,11 @@ export const runSession = Effect.fn("SyncServer.runSession")(function* (
         return;
     }
   });
-
-  yield* socket
-    .runString((text) => messageSemaphore.withPermits(1)(handleMessage(text)), {
-      onOpen: send({
-        type: "Handshake",
-        ...localSyncIdentity,
-        session: identity,
-        serverTime: yield* Clock.currentTimeMillis,
-      }).pipe(Effect.orDie),
-    })
-    .pipe(
-      Effect.ensuring(
-        Ref.get(subscriptions).pipe(
-          Effect.flatMap((active) =>
-            Effect.forEach(HashMap.keys(active), (subscriptionId) =>
-              files.releaseGrants(subscriptionId),
-            ),
-          ),
-          Effect.asVoid,
-        ),
-      ),
-    );
+  return { handle };
 });
 
 interface SyncHandlersService {
+  readonly invalidate: Effect.Effect<void>;
   readonly http: (request: IncomingMessage, response: ServerResponse) => void;
   readonly upgrade: NodeJS.EventEmitter extends infer _EventEmitter
     ? (request: IncomingMessage, socket: import("node:stream").Duplex, head: Buffer) => void
@@ -611,7 +567,17 @@ class SyncHandlers extends Context.Service<SyncHandlers, SyncHandlersService>()(
   "ignotum/dev-runtime/sync/SyncHandlers",
 ) {}
 
-const makeHandlersLayer = (server: ViteDevServer, appDirectory: string, databasePath: string) => {
+type LocalDevSyncOptions = ManagedSyncOptions & {
+  readonly loadModule: ViteDevServer["ssrLoadModule"];
+};
+
+const makeHandlersLayer = (
+  appDirectory: string,
+  databasePath: string,
+  managed: LocalDevSyncOptions,
+) => {
+  const transportPath = managedSyncPath;
+  const loader = { ssrLoadModule: managed.loadModule };
   const sqliteLayer = SqliteClient.layer({ filename: databasePath });
   const persistenceLayer = Layer.merge(LocalDatabase.layer, mutationReplayLayer).pipe(
     Layer.provideMerge(DevelopmentDatabase.layer),
@@ -621,14 +587,14 @@ const makeHandlersLayer = (server: ViteDevServer, appDirectory: string, database
     Layer.provide(persistenceLayer),
     Layer.provide(IdGenerator.layer),
   );
-  const environmentLayer = DevelopmentEnvironment.layer(server, appDirectory).pipe(
+  const environmentLayer = DevelopmentEnvironment.layer(loader, appDirectory).pipe(
     Layer.provide(NodeServices.layer),
     Layer.orDie,
   );
   const devFunctionRuntimeLayer = functionRuntimeLayer.pipe(
     Layer.provide(
       Layer.merge(
-        FunctionRegistry.layer(server, appDirectory).pipe(
+        FunctionRegistry.layer(loader, appDirectory).pipe(
           Layer.provide(Layer.merge(NodeServices.layer, environmentLayer)),
         ),
         executorLayer,
@@ -640,6 +606,8 @@ const makeHandlersLayer = (server: ViteDevServer, appDirectory: string, database
     environmentLayer,
     queryInvalidationLayer,
     persistenceLayer,
+    sqliteLayer,
+    IdGenerator.layer,
     NodeServices.layer,
     LocalId.layer(appDirectory).pipe(Layer.provide(NodeServices.layer)),
     localApplicationFilesLayer(appDirectory).pipe(
@@ -778,31 +746,32 @@ const makeHandlersLayer = (server: ViteDevServer, appDirectory: string, database
             : HttpServerResponse.uint8Array(granted.value.bytes, { headers });
         }
         return yield* HttpServerResponse.json(
-          pathname === syncPath
-            ? { code: "UpgradeRequired", message: `Connect to ${syncPath} with WebSocket.` }
+          pathname === transportPath
+            ? { code: "UpgradeRequired", message: `Connect to ${transportPath} with WebSocket.` }
             : { code: "NotFound", message: "Unknown Ignotum API route." },
-          { status: pathname === syncPath ? 426 : 404 },
-        );
-      });
-      const socketApp = Effect.gen(function* () {
-        const request = yield* HttpServerRequest.HttpServerRequest;
-        const url = new URL(request.url, `http://${request.headers.host ?? "ignotum.local"}`);
-        if (request.headers.origin !== url.origin) return HttpServerResponse.empty({ status: 403 });
-        const refresh = localId.session(
-          url.searchParams.get("username"),
-          url.searchParams.get("epoch") ?? "dev:anonymous",
+          { status: pathname === transportPath ? 426 : 404 },
         );
-        const identity = yield* refresh;
-        const socket = yield* request.upgrade;
-        yield* runSession(socket, identity, refresh);
-        return HttpServerResponse.empty();
       });
       const http = yield* NodeHttpServer.makeHandler(httpApp, { scope });
-      const upgrade = yield* NodeHttpServer.makeUpgradeHandler(
-        Effect.succeed(webSocketServer),
-        socketApp,
-        { scope },
-      );
+      const upgrade = yield* Layer.build(
+        ManagedWebSocket.layer(
+          webSocketServer,
+          Effect.fn("ManagedSyncServer.session")(function* (
+            socket: Socket.Socket,
+            request: IncomingMessage,
+          ) {
+            const url = new URL(
+              request.url ?? "/",
+              `http://${request.headers.host ?? "ignotum.local"}`,
+            );
+            const refresh = localId.session(
+              url.searchParams.get("username"),
+              url.searchParams.get("epoch") ?? "dev:anonymous",
+            );
+            yield* runManagedSession(socket, managed, yield* refresh, refresh);
+          }),
+        ),
+      ).pipe(Effect.map((context) => Context.get(context, ManagedWebSocket).upgrade));
       const serverDirectory = path.join(appDirectory, "server");
       const environmentPath = path.join(appDirectory, ".env.ignotum");
       const reloadUnsafe = Effect.fn("SyncServer.reload")(function* (
@@ -813,10 +782,19 @@ const makeHandlersLayer = (server: ViteDevServer, appDirectory: string, database
         const relative = path.relative(serverDirectory, file);
         const isServerTypeScript =
           !relative.startsWith("..") && !path.isAbsolute(relative) && file.endsWith(".ts");
-        if (!isEnvironmentValues && !isServerTypeScript) {
+        if (
+          !isEnvironmentValues &&
+          !isServerTypeScript &&
+          managed.isServerDependency?.(file) !== true
+        ) {
           return;
         }
 
+        if (managed.beforeReload !== undefined)
+          yield* Effect.tryPromise(() => managed.beforeReload!(file, event)).pipe(
+            Effect.onError(() => invalidation.publish({ type: "All" })),
+          );
+
         if (isServerTypeScript && event !== "change") {
           yield* generate(appDirectory).pipe(
             Effect.provideService(FileSystem.FileSystem, fileSystem),
@@ -843,7 +821,12 @@ const makeHandlersLayer = (server: ViteDevServer, appDirectory: string, database
             ),
           );
 
-      return SyncHandlers.of({ http, reload, upgrade });
+      return SyncHandlers.of({
+        http,
+        reload,
+        upgrade,
+        invalidate: invalidation.publish({ type: "All" }),
+      });
     }),
   ).pipe(Layer.provide(dependencies));
 };
@@ -870,60 +853,77 @@ const rejectUpgrade = (socket: import("node:stream").Duplex): void => {
 
 export const syncPluginInternals = { isAppOrigin, reloadEnvironmentAndInvalidate };
 
-export const ignotumSyncPlugin: {
-  (databasePath: string): (appDirectory: string) => Plugin;
-  (appDirectory: string, databasePath: string): Plugin;
-} = Function.dual(2, (appDirectory: string, databasePath: string): Plugin => ({
-  name: "ignotum:sync",
-  configureServer: (server) => {
-    if (server.httpServer === null) {
-      throw new Error("Ignotum sync requires Vite's Node HTTP server.");
-    }
+const createSyncPlugin = (
+  appDirectory: string,
+  databasePath: string,
+  managed: LocalDevSyncOptions,
+): Plugin & { api: { invalidate: () => Promise<void>; dispose: () => Promise<void> } } => {
+  const api = {
+    invalidate: (): Promise<void> => Promise.resolve(),
+    dispose: (): Promise<void> => Promise.resolve(),
+  };
+  return {
+    api,
+    name: "ignotum:sync",
+    configureServer: (server) => {
+      if (server.httpServer === null) {
+        throw new Error("Ignotum sync requires Vite's Node HTTP server.");
+      }
 
-    const runtime = ManagedRuntime.make(makeHandlersLayer(server, appDirectory, databasePath));
-    const httpServer = server.httpServer;
-    return runtime.runPromise(SyncHandlers).then(
-      (handlers) => {
-        const onUpgrade = (
-          request: IncomingMessage,
-          socket: import("node:stream").Duplex,
-          head: Buffer,
-        ) => {
-          if (new URL(request.url ?? "/", "http://ignotum.local").pathname !== syncPath) return;
-          if (!isAppOrigin(request.headers.host, request.headers.origin)) {
-            rejectUpgrade(socket);
-            return;
-          }
-          handlers.upgrade(request, socket, head);
-        };
-        const onAdd = (file: string) => runtime.runFork(handlers.reload(file, "add"));
-        const onChange = (file: string) => runtime.runFork(handlers.reload(file, "change"));
-        const onUnlink = (file: string) => runtime.runFork(handlers.reload(file, "unlink"));
-        const cleanup = () => {
-          httpServer.off("upgrade", onUpgrade);
-          server.watcher.off("add", onAdd);
-          server.watcher.off("change", onChange);
-          server.watcher.off("unlink", onUnlink);
+      const runtime = ManagedRuntime.make(makeHandlersLayer(appDirectory, databasePath, managed));
+      api.dispose = () => runtime.dispose();
+      const httpServer = server.httpServer;
+      return runtime.runPromise(SyncHandlers).then(
+        (handlers) => {
+          api.invalidate = () => runtime.runPromise(handlers.invalidate);
+          const onUpgrade = (
+            request: IncomingMessage,
+            socket: import("node:stream").Duplex,
+            head: Buffer,
+          ) => {
+            if (new URL(request.url ?? "/", "http://ignotum.local").pathname !== managedSyncPath)
+              return;
+            if (!isAppOrigin(request.headers.host, request.headers.origin)) {
+              rejectUpgrade(socket);
+              return;
+            }
+            handlers.upgrade(request, socket, head);
+          };
+          const onAdd = (file: string) => runtime.runFork(handlers.reload(file, "add"));
+          const onChange = (file: string) => runtime.runFork(handlers.reload(file, "change"));
+          const onUnlink = (file: string) => runtime.runFork(handlers.reload(file, "unlink"));
+          const cleanup = () => {
+            httpServer.off("upgrade", onUpgrade);
+            server.watcher.off("add", onAdd);
+            server.watcher.off("change", onChange);
+            server.watcher.off("unlink", onUnlink);
+            void runtime.dispose();
+          };
+
+          httpServer.on("upgrade", onUpgrade);
+          httpServer.once("close", cleanup);
+          server.watcher.on("add", onAdd);
+          server.watcher.on("change", onChange);
+          server.watcher.on("unlink", onUnlink);
+          server.middlewares.use((request, response, next) => {
+            if (!isApiPath(request)) {
+              next();
+              return;
+            }
+            handlers.http(request, response);
+          });
+        },
+        (error) => {
           void runtime.dispose();
-        };
-
-        httpServer.on("upgrade", onUpgrade);
-        httpServer.once("close", cleanup);
-        server.watcher.on("add", onAdd);
-        server.watcher.on("change", onChange);
-        server.watcher.on("unlink", onUnlink);
-        server.middlewares.use((request, response, next) => {
-          if (!isApiPath(request)) {
-            next();
-            return;
-          }
-          handlers.http(request, response);
-        });
-      },
-      (error) => {
-        void runtime.dispose();
-        throw error;
-      },
-    );
-  },
-}));
+          throw error;
+        },
+      );
+    },
+  };
+};
+
+export const ignotumManagedSyncPlugin = (
+  appDirectory: string,
+  databasePath: string,
+  options: LocalDevSyncOptions,
+) => createSyncPlugin(appDirectory, databasePath, options);