@forgeax/engine-host 0.1.27 → 0.1.29

package/README.md

@@ -30,3 +30,12 @@ capability: requests fail, `connected` becomes false, and the frontend status
 becomes `failed` with a transport error. Consumer plugins own their domain
 resources through Cordis effects; the host owns only its transport and Loader
 lifetime.
+
+Embedding owners can observe accepted frontend reports with
+`backend.subscribeActivationReports(listener)`; the returned disposer removes
+only that listener and preserves `onActivationReport`. A staged consumer may
+call `backend.update(input, { bootstrap: true })` to replace the one bootstrap
+revision admitted alongside the current assembly. Later updates retain that
+bootstrap revision for reconnects; arbitrary stale revisions still fail. The
+owner must serialize assembly updates and keep backend Entries in the input
+when changing the frontend projection.

package/dist/__tests__/startup.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=startup.test.d.ts.map

package/dist/__tests__/startup.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"startup.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/startup.test.ts"],"names":[],"mappings":""}

package/dist/backend.d.ts

@@ -31,7 +31,13 @@ export interface BackendHost {
     readonly transport: HostTransportServer;
     readonly ownedContext: boolean;
     /** Reconcile backend Entries and publish the matching frontend assembly atomically. */
-    update(input: HostAssemblyInput | readonly GamePluginEntry[]): Promise<HostAssembly>;
+    update(input: HostAssemblyInput | readonly GamePluginEntry[], 
+    /** Replace the one admitted bootstrap revision for staged frontend reconnects. */
+    options?: {
+        readonly bootstrap?: boolean;
+    }): Promise<HostAssembly>;
+    /** Observe accepted reports without replacing the owning host's callback. */
+    subscribeActivationReports(listener: (report: HostActivationReport) => void | Promise<void>): () => void;
     dispose(): Promise<void>;
 }
 /**

package/dist/backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAc,KAAK,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAC1E,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,4BAA4B,EACjC,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,WAAW,EAEjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAGL,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EAGpB,MAAM,eAAe,CAAC;AACvB,OAAO,EAKL,KAAK,mBAAmB,EACzB,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,SAAS,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,YAAY,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACnE;AAED,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,gEAAgE;IAChE,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IAC9C,iFAAiF;IACjF,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAC3C,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACnD,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,mBAAmB,CAAC;IACzC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtF;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,wBAAwB,CAAC;IAC5C,QAAQ,CAAC,SAAS,EAAE,mBAAmB,CAAC;IACxC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,uFAAuF;IACvF,MAAM,CAAC,KAAK,EAAE,iBAAiB,GAAG,SAAS,eAAe,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACrF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAwFD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,WAAW,CAAC,CAqL9F;AAED,YAAY,EAAE,4BAA4B,EAAE,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,CAAC"}
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAc,KAAK,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAC1E,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,4BAA4B,EACjC,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,WAAW,EAEjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAGL,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EAGpB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAKL,KAAK,mBAAmB,EACzB,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,SAAS,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,YAAY,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACnE;AAED,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,gEAAgE;IAChE,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IAC9C,iFAAiF;IACjF,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAC3C,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACnD,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,mBAAmB,CAAC;IACzC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtF;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,wBAAwB,CAAC;IAC5C,QAAQ,CAAC,SAAS,EAAE,mBAAmB,CAAC;IACxC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,uFAAuF;IACvF,MAAM,CACJ,KAAK,EAAE,iBAAiB,GAAG,SAAS,eAAe,EAAE;IACrD,kFAAkF;IAClF,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GACzC,OAAO,CAAC,YAAY,CAAC,CAAC;IACzB,6EAA6E;IAC7E,0BAA0B,CACxB,QAAQ,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAC/D,MAAM,IAAI,CAAC;IACd,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAwFD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,WAAW,CAAC,CAqM9F;AAED,YAAY,EAAE,4BAA4B,EAAE,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/backend.mjs

@@ -350,6 +350,30 @@ function modulesFromCatalog(catalog, realm, version = "static") {
     ...record.digest === void 0 ? {} : { digest: record.digest }
   }));
 }
+async function createHostStartup(options = {}) {
+  const context = options.context ?? new Context();
+  const ownedContext = options.context === void 0;
+  const fibers = [];
+  let disposed = false;
+  try {
+    for (const plugin of options.startupPlugins ?? []) fibers.push(await context.plugin(plugin));
+  } catch (error) {
+    for (const fiber of fibers.reverse()) await fiber.dispose();
+    if (ownedContext) await context.fiber.dispose();
+    throw error;
+  }
+  return {
+    context,
+    ownedContext,
+    fibers,
+    async dispose() {
+      if (disposed) return;
+      disposed = true;
+      for (const fiber of [...fibers].reverse()) await fiber.dispose();
+      if (ownedContext) await context.fiber.dispose();
+    }
+  };
+}
 
 // src/transport.ts
 var HOST_ASSEMBLY_SERVICE = "host/assembly.get";
@@ -650,7 +674,6 @@ function assertBackendCatalogIdentity(catalog, modules) {
 }
 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]) ?? [];
@@ -666,27 +689,31 @@ async function createBackendHost(options = {}) {
   });
   const checkedInitial = validateHostAssembly(initialAssembly);
   if (!checkedInitial.ok) {
-    if (ownedContext) await context.fiber.dispose();
+    if (options.context === void 0) 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;
+  let bootstrapRevision = checkedInitial.value.revision;
+  const activationListeners = /* @__PURE__ */ new Set();
   const transport = options.transport ?? createHostTransport();
-  let foundationFiber;
+  let startup;
   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));
+    startup = await createHostStartup({
+      context,
+      startupPlugins: [
+        hostFoundationPlugin(assembly, transport),
+        ...options.startupPlugins ?? []
+      ]
+    });
     if (catalog !== void 0) {
       const bootstrapped = await bootstrapCatalogLoader(context, catalog, realm, {
         catalogDigest: checkedInitial.value.revision,
@@ -714,6 +741,7 @@ async function createBackendHost(options = {}) {
           );
         }
         await options.onActivationReport?.(report);
+        for (const listener of activationListeners) await listener(report);
         return { accepted: true };
       }
     );
@@ -725,9 +753,7 @@ async function createBackendHost(options = {}) {
     unregisterAssemblyService?.();
     unsubscribeAssembly?.();
     await loaderFiber?.dispose();
-    for (const fiber of startupFibers.reverse()) await fiber.dispose();
-    await foundationFiber?.dispose();
-    if (ownedContext) await context.fiber.dispose();
+    await startup?.dispose();
     throw error;
   }
   let disposed = false;
@@ -736,8 +762,22 @@ async function createBackendHost(options = {}) {
     ...loader === void 0 ? {} : { loader },
     assembly,
     transport,
-    ownedContext,
-    async update(nextInput) {
+    ownedContext: options.context === void 0,
+    subscribeActivationReports(listener) {
+      if (disposed) {
+        throw new HostAssemblyError(
+          "host-assembly-service-unavailable",
+          "the backend host to remain active while observing activation reports",
+          "Subscribe on an active host instance.",
+          { service: HOST_ACTIVATION_REPORT_SERVICE }
+        );
+      }
+      activationListeners.add(listener);
+      return () => {
+        activationListeners.delete(listener);
+      };
+    },
+    async update(nextInput, updateOptions) {
       if (disposed) {
         throw new HostAssemblyError(
           "host-assembly-service-unavailable",
@@ -774,19 +814,19 @@ async function createBackendHost(options = {}) {
         await loader.await();
       }
       backendEntries = nextBackendEntries;
+      if (updateOptions?.bootstrap === true) bootstrapRevision = checkedCandidate.value.revision;
       return authority.publish(effectiveInput);
     },
     async dispose() {
       if (disposed) return;
       disposed = true;
+      activationListeners.clear();
       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();
+      await startup?.dispose();
     }
   };
   return host;