@forgeax/engine-host 0.1.27

package/dist/backend.mjs

@@ -0,0 +1,797 @@
+import { Context } from '@forgeax/engine-plugin';
+import { bootstrapCatalogLoader, projectPluginEntries } from '@forgeax/engine-plugin/loader';
+
+// src/backend.ts
+
+// src/protocol.ts
+var HOST_ASSEMBLY_SCHEMA_VERSION = 1;
+var HostAssemblyError = class extends Error {
+  code;
+  expected;
+  hint;
+  detail;
+  constructor(code, expected, hint, detail) {
+    super(`${code}: ${expected}`);
+    this.name = "HostAssemblyError";
+    this.code = code;
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = detail;
+  }
+};
+function assertHostModuleCatalogIdentity(module, record) {
+  if (record.version !== void 0 && record.version !== module.version) {
+    throw new HostAssemblyError(
+      "host-assembly-module-version-mismatch",
+      `module ${module.name} to load catalog version ${module.version}`,
+      "Regenerate the static Catalog from the same backend package revision.",
+      { name: module.name, actual: record.version, expected: module.version }
+    );
+  }
+  if (record.digest !== void 0 && module.digest !== void 0 && record.digest !== module.digest) {
+    throw new HostAssemblyError(
+      "host-assembly-module-version-mismatch",
+      `module ${module.name} to load catalog digest ${module.digest ?? "none"}`,
+      "Regenerate the static Catalog from the same backend package bytes.",
+      { name: module.name, actual: record.digest, expected: module.digest ?? "none" }
+    );
+  }
+  const versionMatches = record.version !== void 0 && record.version === module.version;
+  const digestMatches = module.digest !== void 0 && record.digest !== void 0 && record.digest === module.digest;
+  const staticWithoutIdentity = module.version === "static" && module.digest === void 0 && record.version === void 0 && record.digest === void 0;
+  if (!versionMatches && !digestMatches && !staticWithoutIdentity) {
+    throw new HostAssemblyError(
+      "host-assembly-module-version-mismatch",
+      `module ${module.name} to have a matching catalog code identity for ${module.version}`,
+      "Add the generated module version or digest to the static Catalog.",
+      {
+        name: module.name,
+        actual: record.version ?? record.digest ?? "unknown",
+        expected: module.version
+      }
+    );
+  }
+}
+function canonicalHostJson(value) {
+  if (value === void 0) return "undefined";
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalHostJson).join(",")}]`;
+  return `{${Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => `${JSON.stringify(key)}:${canonicalHostJson(item)}`).join(",")}}`;
+}
+function hostRevision(value) {
+  let hash = 2166136261;
+  for (const char of canonicalHostJson(value)) {
+    hash ^= char.codePointAt(0) ?? 0;
+    hash = Math.imul(hash, 16777619);
+  }
+  return `fnv1a:${(hash >>> 0).toString(16).padStart(8, "0")}`;
+}
+function cloneEntry(entry) {
+  const config = entry.group ? entry.config?.map(cloneEntry) : entry.config;
+  return {
+    id: entry.id,
+    name: entry.name,
+    ...config === void 0 ? {} : { config },
+    ...entry.group === void 0 ? {} : { group: entry.group },
+    ...entry.disabled === void 0 ? {} : { disabled: entry.disabled },
+    ...entry.inject === void 0 ? {} : { inject: entry.inject },
+    ...entry.realm === void 0 ? {} : { realm: entry.realm }
+  };
+}
+function projectPairs(pairs) {
+  const entries = [];
+  const modules = [];
+  const projections = [];
+  for (const pair of pairs) {
+    if (pair.backend !== void 0 && pair.frontend !== void 0 && pair.backend.module.version !== pair.frontend.module.version) {
+      throw new HostAssemblyError(
+        "host-assembly-module-version-mismatch",
+        `paired module ${pair.id} to use one code version on both hosts`,
+        "Resolve backend and frontend package entries from the same locked package revision.",
+        {
+          name: pair.id,
+          actual: pair.backend.module.version,
+          expected: pair.frontend.module.version
+        }
+      );
+    }
+    if (pair.frontend === void 0) continue;
+    entries.push(pair.frontend.entry);
+    modules.push(pair.frontend.module);
+    projections.push({
+      id: pair.id,
+      entryId: pair.frontend.entry.id,
+      module: pair.frontend.module
+    });
+  }
+  return { entries, modules, projections };
+}
+function assemblyPairsFromInput(input) {
+  if (input.pairs !== void 0) {
+    const projected = projectPairs(input.pairs);
+    return {
+      entries: input.entries ?? projected.entries,
+      modules: input.modules ?? projected.modules,
+      pairs: projected.projections
+    };
+  }
+  const entries = input.entries ?? [];
+  const modules = [...input.modules ?? []];
+  for (const [index, entry] of entries.entries()) {
+    if (modules[index] !== void 0 || modules.some((module) => module.name === entry.name))
+      continue;
+    modules.push({
+      name: entry.name,
+      realm: entry.realm ?? "engine",
+      version: "unknown"
+    });
+  }
+  return {
+    entries,
+    modules,
+    pairs: entries.map((entry, index) => ({
+      id: entry.id,
+      entryId: entry.id,
+      module: modules[index]?.name === entry.name ? modules[index] : modules.find((module) => module.name === entry.name) ?? {
+        name: entry.name,
+        realm: entry.realm ?? "engine",
+        version: "unknown"
+      }
+    }))
+  };
+}
+function createHostAssembly(input) {
+  const projected = assemblyPairsFromInput(input);
+  const entries = projected.entries.map(cloneEntry);
+  const modules = projected.modules.map((module) => ({ ...module }));
+  const pairs = projected.pairs.map((pair) => ({ ...pair, module: { ...pair.module } }));
+  const identity = {
+    schemaVersion: HOST_ASSEMBLY_SCHEMA_VERSION,
+    entries,
+    modules,
+    pairs,
+    ...input.config === void 0 ? {} : { config: input.config }
+  };
+  return {
+    ...identity,
+    revision: hostRevision(identity)
+  };
+}
+function validateEntry(entry, path) {
+  if (entry === null || typeof entry !== "object") return `${path} must be an Entry object`;
+  if (typeof entry.id !== "string" || entry.id.length === 0) return `${path}.id must be non-empty`;
+  if (typeof entry.name !== "string" || entry.name.length === 0)
+    return `${path}.name must be non-empty`;
+  if (entry.group === true) {
+    if (!Array.isArray(entry.config)) return `${path}.config must be an Entry array for a Group`;
+    for (const [index, child] of entry.config.entries()) {
+      const reason = validateEntry(child, `${path}.config[${index}]`);
+      if (reason !== void 0) return reason;
+    }
+  }
+  return void 0;
+}
+function validateHostAssembly(assembly) {
+  if (assembly === null || typeof assembly !== "object") {
+    return {
+      ok: false,
+      error: new HostAssemblyError(
+        "host-assembly-invalid",
+        "assembly to be an object",
+        "Regenerate the frontend assembly from the active backend authority.",
+        { reason: "assembly is not an object" }
+      )
+    };
+  }
+  if (assembly.schemaVersion !== HOST_ASSEMBLY_SCHEMA_VERSION) {
+    return {
+      ok: false,
+      error: new HostAssemblyError(
+        "host-assembly-invalid",
+        `assembly schema ${HOST_ASSEMBLY_SCHEMA_VERSION}`,
+        "Regenerate the frontend assembly with the matching Engine host package.",
+        { reason: `unsupported schema ${String(assembly.schemaVersion)}` }
+      )
+    };
+  }
+  if (!Array.isArray(assembly.entries) || !Array.isArray(assembly.modules)) {
+    return {
+      ok: false,
+      error: new HostAssemblyError(
+        "host-assembly-invalid",
+        "assembly entries and modules to be arrays",
+        "Regenerate the frontend assembly from the active backend authority.",
+        { reason: "entries or modules is not an array" }
+      )
+    };
+  }
+  if (!Array.isArray(assembly.pairs)) {
+    return {
+      ok: false,
+      error: new HostAssemblyError(
+        "host-assembly-invalid",
+        "assembly pairs to be an array",
+        "Regenerate the assembly from the backend host using the matching host package.",
+        { reason: "pairs is not an array" }
+      )
+    };
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const [index, entry] of assembly.entries.entries()) {
+    const reason = validateEntry(entry, `entries[${index}]`);
+    if (reason !== void 0) {
+      return {
+        ok: false,
+        error: new HostAssemblyError(
+          "host-assembly-invalid",
+          "all assembly entries to be valid native EntryOptions",
+          "Repair the backend Entry projection before publishing it to a browser.",
+          { reason }
+        )
+      };
+    }
+    if (seen.has(entry.id)) {
+      return {
+        ok: false,
+        error: new HostAssemblyError(
+          "host-assembly-invalid",
+          "assembly Entry ids to be unique",
+          "Give repeated plugin instances independent stable ids.",
+          { reason: `duplicate Entry id ${entry.id}` }
+        )
+      };
+    }
+    seen.add(entry.id);
+  }
+  const seenModules = /* @__PURE__ */ new Map();
+  for (const [index, module] of assembly.modules.entries()) {
+    if (module === null || typeof module !== "object" || typeof module.name !== "string" || typeof module.realm !== "string" || typeof module.version !== "string" || module.name.length === 0 || module.version.length === 0 || module.url !== void 0 && typeof module.url !== "string" || module.digest !== void 0 && (typeof module.digest !== "string" || module.digest.length === 0)) {
+      return {
+        ok: false,
+        error: new HostAssemblyError(
+          "host-assembly-invalid",
+          "module names and versions to be non-empty",
+          "Regenerate the module projection from the resolved package metadata.",
+          { reason: `invalid module at index ${index}` }
+        )
+      };
+    }
+    const previousModule = seenModules.get(module.name);
+    if (previousModule !== void 0 && (previousModule.realm !== module.realm || previousModule.version !== module.version || previousModule.url !== module.url || previousModule.digest !== module.digest)) {
+      return {
+        ok: false,
+        error: new HostAssemblyError(
+          "host-assembly-invalid",
+          "assembly module identity to be consistent for repeated Entries",
+          "Reuse one resolved module identity when a package has multiple Entry instances.",
+          { reason: `module ${module.name} has conflicting identities` }
+        )
+      };
+    }
+    seenModules.set(module.name, module);
+  }
+  const seenPairIds = /* @__PURE__ */ new Set();
+  for (const [index, pair] of assembly.pairs.entries()) {
+    const pairModule = pair?.module;
+    if (pair === null || typeof pair !== "object" || typeof pair.id !== "string" || pair.id.length === 0 || typeof pair.entryId !== "string" || pair.entryId.length === 0 || pairModule === null || pairModule === void 0 || typeof pairModule !== "object" || typeof pairModule.name !== "string" || typeof pairModule.realm !== "string" || typeof pairModule.version !== "string" || pairModule.name.length === 0 || pairModule.version.length === 0 || pairModule.url !== void 0 && typeof pairModule.url !== "string" || pairModule.digest !== void 0 && (typeof pairModule.digest !== "string" || pairModule.digest.length === 0)) {
+      return {
+        ok: false,
+        error: new HostAssemblyError(
+          "host-assembly-invalid",
+          "assembly pair identities and modules to be valid",
+          "Regenerate paired frontend entries from the backend package manifest.",
+          { reason: `invalid pair at index ${index}` }
+        )
+      };
+    }
+    if (seenPairIds.has(pair.id)) {
+      return {
+        ok: false,
+        error: new HostAssemblyError(
+          "host-assembly-invalid",
+          "assembly pair ids to be unique",
+          "Give each paired package instance an independent stable id.",
+          { reason: `duplicate pair ${pair.id}` }
+        )
+      };
+    }
+    seenPairIds.add(pair.id);
+    if (!assembly.entries.some((entry) => entry.id === pair.entryId)) {
+      return {
+        ok: false,
+        error: new HostAssemblyError(
+          "host-assembly-invalid",
+          `pair ${pair.id} to reference an assembly Entry`,
+          "Keep paired identity and frontend Entry projection under one backend authority.",
+          { reason: `missing frontend Entry ${pair.entryId}` }
+        )
+      };
+    }
+    const module = assembly.modules.find(
+      (candidate) => candidate.name === pairModule.name && candidate.realm === pairModule.realm && candidate.version === pairModule.version && candidate.url === pairModule.url && candidate.digest === pairModule.digest
+    );
+    if (module === void 0) {
+      return {
+        ok: false,
+        error: new HostAssemblyError(
+          "host-assembly-invalid",
+          `pair ${pair.id} to reference a resolved frontend module`,
+          "Keep module/code identity in the backend-derived assembly projection.",
+          { reason: `missing frontend module ${pairModule.name}` }
+        )
+      };
+    }
+  }
+  const expected = hostRevision({
+    schemaVersion: assembly.schemaVersion,
+    entries: assembly.entries,
+    modules: assembly.modules,
+    pairs: assembly.pairs,
+    ...assembly.config === void 0 ? {} : { config: assembly.config }
+  });
+  if (expected !== assembly.revision) {
+    return {
+      ok: false,
+      error: new HostAssemblyError(
+        "host-assembly-revision-mismatch",
+        "assembly revision to match its entries and modules",
+        "Discard the stale response and request the current backend assembly again.",
+        { actual: assembly.revision, expected }
+      )
+    };
+  }
+  return { ok: true, value: assembly };
+}
+function modulesFromCatalog(catalog, realm, version = "static") {
+  return [...catalog.entries()].filter(([, record]) => record.realm === realm).map(([name, record]) => ({
+    name,
+    realm,
+    version: record.version ?? version,
+    ...record.digest === void 0 ? {} : { digest: record.digest }
+  }));
+}
+
+// src/transport.ts
+var HOST_ASSEMBLY_SERVICE = "host/assembly.get";
+var HOST_ACTIVATION_REPORT_SERVICE = "host/assembly.report";
+var HOST_ASSEMBLY_CHANGED_TOPIC = "host/assembly.changed";
+function createHostTransport() {
+  const services = /* @__PURE__ */ new Map();
+  const generations = /* @__PURE__ */ new Map();
+  const clients = /* @__PURE__ */ new Set();
+  let closed = false;
+  const closeClient = (state, reason) => {
+    if (!state.connected) return;
+    state.connected = false;
+    for (const controller of state.pending) controller.abort();
+    state.pending.clear();
+    for (const callbacks of state.subscriptions.values()) callbacks.clear();
+    state.subscriptions.clear();
+    clients.delete(state);
+    const error = new HostAssemblyError(
+      "host-transport-failure",
+      "the host connection to remain available",
+      "Reconnect the frontend host before issuing another request.",
+      { service: "host/socket", reason: String(reason ?? "host connection closed") }
+    );
+    for (const listener of state.disconnectListeners) listener(error);
+    state.disconnectListeners.clear();
+  };
+  const server = {
+    get connectedClients() {
+      return clients.size;
+    },
+    register(service, handler) {
+      if (closed) throw new Error("host transport is closed");
+      const previous = services.get(service);
+      const generation = (generations.get(service) ?? 0) + 1;
+      generations.set(service, generation);
+      for (const controller of previous?.pending ?? []) controller.abort();
+      const identity = Symbol(service);
+      services.set(service, {
+        identity,
+        generation,
+        handler,
+        pending: /* @__PURE__ */ new Set()
+      });
+      return () => {
+        const current = services.get(service);
+        if (current?.identity !== identity) return;
+        for (const controller of current.pending) controller.abort();
+        generations.set(service, current.generation + 1);
+        services.delete(service);
+      };
+    },
+    invalidate(service) {
+      const current = services.get(service);
+      if (current === void 0) return;
+      for (const controller of current.pending) controller.abort();
+      generations.set(service, current.generation + 1);
+      services.delete(service);
+    },
+    snapshot(service) {
+      const current = services.get(service);
+      return current === void 0 ? void 0 : { service, generation: current.generation };
+    },
+    publish(topic, payload) {
+      for (const state of clients) {
+        for (const listener of state.subscriptions.get(topic) ?? []) listener(payload);
+      }
+    },
+    connect() {
+      if (closed) throw new Error("host transport is closed");
+      const state = {
+        connected: true,
+        subscriptions: /* @__PURE__ */ new Map(),
+        pending: /* @__PURE__ */ new Set(),
+        disconnectListeners: /* @__PURE__ */ new Set()
+      };
+      clients.add(state);
+      const client = {
+        get connected() {
+          return state.connected;
+        },
+        get generation() {
+          let current = 0;
+          for (const service of services.values()) current = Math.max(current, service.generation);
+          return current;
+        },
+        async request(service, payload, options = {}) {
+          if (!state.connected) {
+            throw new HostAssemblyError(
+              "host-assembly-service-unavailable",
+              `service ${service} to be available on the current connection`,
+              "Reconnect the frontend host before issuing another request.",
+              { service }
+            );
+          }
+          if (options.signal?.aborted) {
+            throw new HostAssemblyError(
+              "host-assembly-request-aborted",
+              `request ${service} to start with a live AbortSignal`,
+              "Start a fresh request with a live AbortSignal.",
+              { service }
+            );
+          }
+          const record = services.get(service);
+          if (record === void 0) {
+            const invalidatedGeneration = generations.get(service);
+            if (options.generation !== void 0 && invalidatedGeneration !== void 0 && options.generation < invalidatedGeneration) {
+              throw new HostAssemblyError(
+                "host-assembly-stale-request",
+                `request generation ${options.generation} to match the invalidated service ${service}`,
+                "Refresh the client capability after the backend service is enabled again.",
+                { service, generation: options.generation }
+              );
+            }
+            throw new HostAssemblyError(
+              "host-assembly-service-unavailable",
+              `service ${service} to be registered`,
+              "Wait for the backend plugin to activate before using this capability.",
+              { service }
+            );
+          }
+          const generation = options.generation ?? record.generation;
+          if (generation !== record.generation) {
+            throw new HostAssemblyError(
+              "host-assembly-stale-request",
+              `request generation ${generation} to match service ${service}`,
+              "Refresh the client capability and retry only when the owning business contract permits it.",
+              { service, generation }
+            );
+          }
+          const controller = new AbortController();
+          const abortFromCaller = () => controller.abort();
+          options.signal?.addEventListener("abort", abortFromCaller, { once: true });
+          record.pending.add(controller);
+          state.pending.add(controller);
+          let removeAbortRequest;
+          try {
+            if (controller.signal.aborted) {
+              throw new HostAssemblyError(
+                "host-assembly-request-aborted",
+                `request ${service} not to be aborted before execution`,
+                "Start a fresh request with a live AbortSignal.",
+                { service }
+              );
+            }
+            let abortReject;
+            const aborted = new Promise((_, reject) => {
+              abortReject = reject;
+            });
+            const abortRequest = () => {
+              abortReject?.(
+                new HostAssemblyError(
+                  "host-assembly-request-aborted",
+                  `request ${service} to finish before its service is closed or invalidated`,
+                  "Treat the capability as withdrawn and refresh the service before retrying.",
+                  { service }
+                )
+              );
+            };
+            controller.signal.addEventListener("abort", abortRequest, { once: true });
+            removeAbortRequest = () => controller.signal.removeEventListener("abort", abortRequest);
+            const result = await Promise.race([
+              Promise.resolve(
+                record.handler({
+                  service,
+                  payload,
+                  generation,
+                  signal: controller.signal
+                })
+              ),
+              aborted
+            ]);
+            if (controller.signal.aborted) {
+              throw new HostAssemblyError(
+                "host-assembly-request-aborted",
+                `request ${service} to finish before its service is invalidated`,
+                "Treat the capability as withdrawn and refresh the service before retrying.",
+                { service }
+              );
+            }
+            return result;
+          } finally {
+            removeAbortRequest?.();
+            record.pending.delete(controller);
+            state.pending.delete(controller);
+            options.signal?.removeEventListener("abort", abortFromCaller);
+          }
+        },
+        subscribe(topic, listener) {
+          if (!state.connected) return () => {
+          };
+          const callbacks = state.subscriptions.get(topic) ?? /* @__PURE__ */ new Set();
+          callbacks.add(listener);
+          state.subscriptions.set(topic, callbacks);
+          return () => {
+            callbacks.delete(listener);
+            if (callbacks.size === 0) state.subscriptions.delete(topic);
+          };
+        },
+        onDisconnect(listener) {
+          if (!state.connected) {
+            listener(
+              new HostAssemblyError(
+                "host-transport-failure",
+                "the host connection to remain available",
+                "Reconnect the frontend host before issuing another request.",
+                { service: "host/socket", reason: "host connection is already closed" }
+              )
+            );
+            return () => {
+            };
+          }
+          state.disconnectListeners.add(listener);
+          return () => state.disconnectListeners.delete(listener);
+        },
+        close(reason) {
+          closeClient(state, reason);
+        }
+      };
+      return client;
+    },
+    close(reason) {
+      if (closed) return;
+      closed = true;
+      for (const service of services.values())
+        for (const controller of service.pending) controller.abort();
+      services.clear();
+      for (const client of [...clients]) closeClient(client, reason);
+      generations.clear();
+    }
+  };
+  return server;
+}
+
+// src/backend.ts
+function effectiveAssemblyInput(current, input) {
+  const preservePairs = input.pairs === void 0 && input.entries === void 0 && input.modules === void 0;
+  const entriesById = new Map(current.entries.map((entry) => [entry.id, entry]));
+  const modulesByName = new Map(current.modules.map((module) => [module.name, module]));
+  const pairs = current.pairs.flatMap((pair) => {
+    const entry = entriesById.get(pair.entryId);
+    const module = modulesByName.get(pair.module.name);
+    return entry === void 0 || module === void 0 ? [] : [{ id: pair.id, frontend: { entry, module } }];
+  });
+  return {
+    entries: input.entries ?? current.entries,
+    modules: input.modules ?? current.modules,
+    ...input.pairs !== void 0 ? { pairs: input.pairs } : preservePairs ? { pairs } : {},
+    ...input.config === void 0 ? current.config === void 0 ? {} : { config: current.config } : { config: input.config },
+    ...input.backendEntries === void 0 ? {} : { backendEntries: input.backendEntries }
+  };
+}
+function authorityOf(initial) {
+  let current = initial;
+  let generation = 1;
+  const listeners = /* @__PURE__ */ new Set();
+  const authority = {
+    get current() {
+      return current;
+    },
+    get generation() {
+      return generation;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    }
+  };
+  return {
+    authority,
+    publish(input) {
+      const next = createHostAssembly(input);
+      const checked = validateHostAssembly(next);
+      if (!checked.ok) throw checked.error;
+      current = checked.value;
+      generation += 1;
+      for (const listener of listeners) listener(current);
+      return current;
+    }
+  };
+}
+function hostFoundationPlugin(assembly, transport) {
+  return {
+    name: "forgeax:backend-host-foundation",
+    provide: ["hostAssembly", "hostTransport"],
+    apply(ctx) {
+      ctx.provide("hostAssembly", assembly);
+      ctx.provide("hostTransport", transport);
+    }
+  };
+}
+function assertBackendCatalogIdentity(catalog, modules) {
+  if (catalog === void 0) return;
+  for (const module of modules) {
+    const record = catalog.get(module.name);
+    if (record !== void 0) assertHostModuleCatalogIdentity(module, record);
+  }
+}
+async function createBackendHost(options = {}) {
+  const context = options.context ?? new Context();
+  const ownedContext = options.context === void 0;
+  const realm = options.realm ?? "engine";
+  const catalog = options.catalog;
+  const pairedBackendEntries = options.pairs?.flatMap((pair) => pair.backend === void 0 ? [] : [pair.backend.entry]) ?? [];
+  const entries = options.entries ?? options.assembly?.entries ?? options.pairs?.flatMap((pair) => pair.frontend === void 0 ? [] : [pair.frontend.entry]) ?? [];
+  const modules = options.modules ?? options.assembly?.modules ?? (options.pairs === void 0 ? catalog === void 0 ? [] : modulesFromCatalog(catalog, realm) : options.pairs.flatMap(
+    (pair) => pair.frontend === void 0 ? [] : [pair.frontend.module]
+  ));
+  const initialAssembly = options.assembly ?? createHostAssembly({
+    entries,
+    modules,
+    ...options.pairs === void 0 ? {} : { pairs: options.pairs },
+    ...options.config === void 0 ? {} : { config: options.config }
+  });
+  const checkedInitial = validateHostAssembly(initialAssembly);
+  if (!checkedInitial.ok) {
+    if (ownedContext) await context.fiber.dispose();
+    throw checkedInitial.error;
+  }
+  const backendModules = options.pairs === void 0 ? modules : options.pairs.flatMap((pair) => pair.backend === void 0 ? [] : [pair.backend.module]);
+  assertBackendCatalogIdentity(catalog, backendModules);
+  const authority = authorityOf(checkedInitial.value);
+  const assembly = authority.authority;
+  const bootstrapRevision = checkedInitial.value.revision;
+  const transport = options.transport ?? createHostTransport();
+  let foundationFiber;
+  let loaderFiber;
+  let loader;
+  let backendEntries = options.pairs === void 0 ? options.entries ?? options.assembly?.entries ?? [] : pairedBackendEntries;
+  const startupFibers = [];
+  let unregisterAssemblyService;
+  let unregisterActivationService;
+  let unsubscribeAssembly;
+  try {
+    foundationFiber = await context.plugin(hostFoundationPlugin(assembly, transport));
+    for (const plugin of options.startupPlugins ?? [])
+      startupFibers.push(await context.plugin(plugin));
+    if (catalog !== void 0) {
+      const bootstrapped = await bootstrapCatalogLoader(context, catalog, realm, {
+        catalogDigest: checkedInitial.value.revision,
+        supportedRealms: [realm]
+      });
+      if (!bootstrapped.ok) throw bootstrapped.error;
+      loaderFiber = bootstrapped.value.fiber;
+      loader = bootstrapped.value.loader;
+      if (backendEntries.length > 0) {
+        await loader.root.update(projectPluginEntries(backendEntries, realm, realm));
+        await loader.await();
+      }
+    }
+    unregisterAssemblyService = transport.register(HOST_ASSEMBLY_SERVICE, () => assembly.current);
+    unregisterActivationService = transport.register(
+      HOST_ACTIVATION_REPORT_SERVICE,
+      async ({ payload }) => {
+        const report = payload;
+        if (report.revision !== assembly.current.revision && report.revision !== bootstrapRevision) {
+          throw new HostAssemblyError(
+            "host-assembly-revision-mismatch",
+            `activation report revision ${report.revision} to match ${assembly.current.revision}`,
+            "Discard the stale frontend report and fetch the current backend assembly.",
+            { actual: report.revision, expected: assembly.current.revision }
+          );
+        }
+        await options.onActivationReport?.(report);
+        return { accepted: true };
+      }
+    );
+    unsubscribeAssembly = assembly.subscribe((next) => {
+      transport.publish(HOST_ASSEMBLY_CHANGED_TOPIC, next);
+    });
+  } catch (error) {
+    unregisterActivationService?.();
+    unregisterAssemblyService?.();
+    unsubscribeAssembly?.();
+    await loaderFiber?.dispose();
+    for (const fiber of startupFibers.reverse()) await fiber.dispose();
+    await foundationFiber?.dispose();
+    if (ownedContext) await context.fiber.dispose();
+    throw error;
+  }
+  let disposed = false;
+  const host = {
+    context,
+    ...loader === void 0 ? {} : { loader },
+    assembly,
+    transport,
+    ownedContext,
+    async update(nextInput) {
+      if (disposed) {
+        throw new HostAssemblyError(
+          "host-assembly-service-unavailable",
+          "backend host to remain active while updating Entries",
+          "Create a new host instance before updating the disposed host.",
+          { service: "host-assembly" }
+        );
+      }
+      const input = Array.isArray(nextInput) ? {
+        entries: nextInput,
+        backendEntries: nextInput
+      } : nextInput;
+      const effectiveInput = effectiveAssemblyInput(assembly.current, input);
+      const candidate = createHostAssembly(effectiveInput);
+      const checkedCandidate = validateHostAssembly(candidate);
+      if (!checkedCandidate.ok) throw checkedCandidate.error;
+      const candidateBackendModules = input.pairs === void 0 ? checkedCandidate.value.modules : input.pairs.flatMap(
+        (pair) => pair.backend === void 0 ? [] : [pair.backend.module]
+      );
+      assertBackendCatalogIdentity(catalog, candidateBackendModules);
+      const nextBackendEntries = input.backendEntries ?? (input.pairs === void 0 ? input.entries ?? backendEntries : input.pairs.flatMap(
+        (pair) => pair.backend === void 0 ? [] : [pair.backend.entry]
+      ));
+      if (loader === void 0 && nextBackendEntries.length > 0) {
+        throw new HostAssemblyError(
+          "host-assembly-service-unavailable",
+          "a CatalogLoader to be installed before updating Entries",
+          "Provide a backend Catalog when the host owns plugin Entry activation.",
+          { service: "loader" }
+        );
+      }
+      if (loader !== void 0) {
+        await loader.root.update(projectPluginEntries(nextBackendEntries, realm, realm));
+        await loader.await();
+      }
+      backendEntries = nextBackendEntries;
+      return authority.publish(effectiveInput);
+    },
+    async dispose() {
+      if (disposed) return;
+      disposed = true;
+      unsubscribeAssembly?.();
+      unregisterActivationService?.();
+      unregisterAssemblyService?.();
+      transport.close();
+      await loaderFiber?.dispose();
+      for (const fiber of startupFibers.reverse()) await fiber.dispose();
+      await foundationFiber?.dispose();
+      if (ownedContext) await context.fiber.dispose();
+    }
+  };
+  return host;
+}
+
+export { HostAssemblyError, createBackendHost };
+//# sourceMappingURL=backend.mjs.map
+//# sourceMappingURL=backend.mjs.map