@xyo-network/dapp-kit-port 2.1.4 → 2.3.0

package/README.md

@@ -21,3 +21,52 @@ compatible Node implementations. It verifies the expected dApp, plan, protocol
 version, and grant lifetime before publishing an `ApplicationPortClient`.
 Transport loss rejects pending unary and streaming work; reconnecting creates a
 new attachment and resumes only through the existing cursor protocol.
+
+A host's `closeAdmission()` synchronously detaches inbound delivery and aborts
+accepted requests. `drain()` closes admission if necessary and waits for unary
+work, pending stream opening/reads, and source cancellation. `close()` combines
+both; every caller joins the same retained promise. Cleanup failures reject
+that promise after the remaining resources receive their cleanup attempts.
+Late-acquired and invalid stream sources remain owned. A dApp session work
+binding can delegate `close` to `host.closeAdmission()` and `drain` to
+`host.drain()` so its Actor/Provider dependencies remain alive during drainage.
+These are cooperative lifecycle guarantees, not external-effect rollback.
+
+`createDappEngineApplicationPortHost()` adds exact engine/system-reference
+admission to the same protocol host. It validates attachment identity before
+endpoint acquisition and captures explicitly classified read/write operations.
+Each unary start and stream open/resume rechecks readiness and incarnation;
+writes require their own writable capability, while public reads need no write
+capability. A declared read cannot bypass a matching write capability.
+
+The helper binds work directly to the selected engine session, so replacement
+and stop drain it before Actor/Provider teardown. Its required async `disconnect`
+callback must settle pending clients and reject future transport work. Drain
+awaits both transport release and accepted host work. Endpoint activation occurs
+only after ownership is registered, and startup failure awaits cleanup. The
+returned host exposes lifecycle only; it exposes no providers or locators.
+This API does not replace domain authorization/consent or qualify browser
+crash recovery. Existing browser-host durable-write admission remains separate.
+
+### Selected operation recovery admission
+
+An engine-aware host can additionally receive `recovery` with an immutable
+operation profile, an opaque bound-authority scope ID and a synchronous
+`readSnapshot(requirement, binding)` callback. The adapter captures the profile
+and callback at attachment and freezes the exact engine/plan/network binding
+passed to observation. The selected profile must cover every bound operation
+exactly and agree with its read/write classification.
+
+Each write first passes current engine identity and operation authorization,
+then the core recovery validator, then another authorization check in case the
+observer stopped or revoked the system reentrantly. Public reads never invoke
+the private snapshot callback. A missing guarantee, stale binding, unavailable,
+corrupt, pending or uncertain state fails closed with a stable recovery code;
+private callback exceptions are not exposed through domain error mapping.
+
+The snapshot observes a readiness result already maintained by the selected
+recovery owner. It does not run I/O, sign, broadcast or acquire a second journal.
+Reported guarantees require separate adapter qualification. Kit-journal mode
+retains the existing receipt executor and crash-durable requirement. Omitting
+this optional profile preserves existing host composition and does not enable
+browser writes.

package/dist/browser/applicationPortHost.d.ts

@@ -5,6 +5,8 @@ export interface CreateApplicationPortHostOptions extends ApplicationPortPeerOpt
 }
 export interface ApplicationPortHost {
     close(): Promise<void>;
+    closeAdmission(): void;
+    drain(): Promise<void>;
 }
 export declare function createApplicationPortHost(options: CreateApplicationPortHostOptions): ApplicationPortHost;
 //# sourceMappingURL=applicationPortHost.d.ts.map

package/dist/browser/applicationPortHost.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"applicationPortHost.d.ts","sourceRoot":"","sources":["../../src/applicationPortHost.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,wBAAwB,EACxB,wBAAwB,EACxB,0BAA0B,EAI3B,MAAM,2BAA2B,CAAA;AAWlC,MAAM,WAAW,gCAAiC,SAAQ,0BAA0B;IAClF,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,wBAAwB,CAAA;IAC/D,QAAQ,CAAC,UAAU,EAAE,SAAS,wBAAwB,EAAE,CAAA;CACzD;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAmbD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,gCAAgC,GAAG,mBAAmB,CAExG"}
+{"version":3,"file":"applicationPortHost.d.ts","sourceRoot":"","sources":["../../src/applicationPortHost.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,wBAAwB,EACxB,wBAAwB,EACxB,0BAA0B,EAI3B,MAAM,2BAA2B,CAAA;AAWlC,MAAM,WAAW,gCAAiC,SAAQ,0BAA0B;IAClF,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,wBAAwB,CAAA;IAC/D,QAAQ,CAAC,UAAU,EAAE,SAAS,wBAAwB,EAAE,CAAA;CACzD;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,cAAc,IAAI,IAAI,CAAA;IACtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AA+eD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,gCAAgC,GAAG,mBAAmB,CAExG"}

package/dist/browser/engineApplicationPortHost.d.ts

@@ -0,0 +1,20 @@
+import type { DappEngineSession, DappEngineSystemReference } from '@xyo-network/dapp-kit';
+import type { ApplicationPortHost, CreateApplicationPortHostOptions } from './applicationPortHost.ts';
+import type { ApplicationPortOperation } from './applicationPortModel.ts';
+import type { DappEngineOperationRecoveryOptions } from './engineOperationRecovery.ts';
+export type { DappEngineOperationRecoveryOptions } from './engineOperationRecovery.ts';
+export { DappEnginePortAdmissionError } from './enginePortAdmissionError.ts';
+export interface DappEngineApplicationPortOperation {
+    readonly access: 'read' | 'write';
+    readonly operation: ApplicationPortOperation;
+}
+export interface CreateDappEngineApplicationPortHostOptions extends Omit<CreateApplicationPortHostOptions, 'operations'> {
+    readonly disconnect: () => Promise<void>;
+    readonly engine: DappEngineSession;
+    readonly operations: readonly DappEngineApplicationPortOperation[];
+    readonly recovery?: DappEngineOperationRecoveryOptions;
+    readonly reference: DappEngineSystemReference;
+}
+/** Engine admission around the existing application-port protocol and work owner. */
+export declare function createDappEngineApplicationPortHost(options: CreateDappEngineApplicationPortHostOptions): Promise<ApplicationPortHost>;
+//# sourceMappingURL=engineApplicationPortHost.d.ts.map

package/dist/browser/engineApplicationPortHost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engineApplicationPortHost.d.ts","sourceRoot":"","sources":["../../src/engineApplicationPortHost.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EAAE,yBAAyB,EAC7C,MAAM,uBAAuB,CAAA;AAK9B,OAAO,KAAK,EAAE,mBAAmB,EAAE,gCAAgC,EAAE,MAAM,0BAA0B,CAAA;AAErG,OAAO,KAAK,EAAkC,wBAAwB,EAAE,MAAM,2BAA2B,CAAA;AAEzG,OAAO,KAAK,EAAE,kCAAkC,EAAE,MAAM,8BAA8B,CAAA;AAItF,YAAY,EAAE,kCAAkC,EAAE,MAAM,8BAA8B,CAAA;AACtF,OAAO,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAA;AAE5E,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAA;IACjC,QAAQ,CAAC,SAAS,EAAE,wBAAwB,CAAA;CAC7C;AAED,MAAM,WAAW,0CAA2C,SAAQ,IAAI,CAAC,gCAAgC,EAAE,YAAY,CAAC;IACtH,QAAQ,CAAC,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACxC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;IAClC,QAAQ,CAAC,UAAU,EAAE,SAAS,kCAAkC,EAAE,CAAA;IAClE,QAAQ,CAAC,QAAQ,CAAC,EAAE,kCAAkC,CAAA;IACtD,QAAQ,CAAC,SAAS,EAAE,yBAAyB,CAAA;CAC9C;AA4GD,qFAAqF;AACrF,wBAAsB,mCAAmC,CAAC,OAAO,EAAE,0CAA0C,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAuD3I"}

package/dist/browser/engineOperationRecovery.d.ts

@@ -0,0 +1,10 @@
+import type { DappEngineSystemReference, DappEngineSystemStatus, DappOperationRecoveryBinding, DappOperationRecoveryProfile, DappOperationRecoveryRequirement, DappOperationRecoverySnapshot } from '@xyo-network/dapp-kit';
+import type { DappEngineApplicationPortOperation } from './engineApplicationPortHost.ts';
+export interface DappEngineOperationRecoveryOptions {
+    readonly authorityScopeId: string;
+    readonly profile: DappOperationRecoveryProfile;
+    readonly readSnapshot: (requirement: Readonly<DappOperationRecoveryRequirement>, binding: Readonly<DappOperationRecoveryBinding>) => DappOperationRecoverySnapshot;
+}
+/** Capture a boot-selected profile; observation does not acquire or execute recovery work. */
+export declare function bindEngineOperationRecovery(options: DappEngineOperationRecoveryOptions | undefined, operations: readonly DappEngineApplicationPortOperation[], reference: DappEngineSystemReference, target: DappEngineSystemStatus): ((portId: string, operationId: string) => void) | undefined;
+//# sourceMappingURL=engineOperationRecovery.d.ts.map

package/dist/browser/engineOperationRecovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engineOperationRecovery.d.ts","sourceRoot":"","sources":["../../src/engineOperationRecovery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,yBAAyB,EAAE,sBAAsB,EAAE,4BAA4B,EAAE,4BAA4B,EAAE,gCAAgC,EAAE,6BAA6B,EAC/K,MAAM,uBAAuB,CAAA;AAK9B,OAAO,KAAK,EAAE,kCAAkC,EAAE,MAAM,gCAAgC,CAAA;AAGxF,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,OAAO,EAAE,4BAA4B,CAAA;IAC9C,QAAQ,CAAC,YAAY,EAAE,CAAC,WAAW,EAAE,QAAQ,CAAC,gCAAgC,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,4BAA4B,CAAC,KAAK,6BAA6B,CAAA;CACnK;AAID,8FAA8F;AAC9F,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,kCAAkC,GAAG,SAAS,EACvD,UAAU,EAAE,SAAS,kCAAkC,EAAE,EACzD,SAAS,EAAE,yBAAyB,EACpC,MAAM,EAAE,sBAAsB,GAC7B,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAgD7D"}

package/dist/browser/enginePortAdmissionError.d.ts

@@ -0,0 +1,5 @@
+export declare class DappEnginePortAdmissionError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+//# sourceMappingURL=enginePortAdmissionError.d.ts.map

package/dist/browser/enginePortAdmissionError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enginePortAdmissionError.d.ts","sourceRoot":"","sources":["../../src/enginePortAdmissionError.ts"],"names":[],"mappings":"AAAA,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;gBAET,IAAI,EAAE,MAAM;CAKzB"}

package/dist/browser/index.d.ts

@@ -2,5 +2,6 @@ export * from './applicationPortClient.ts';
 export * from './applicationPortHost.ts';
 export * from './applicationPortModel.ts';
 export * from './applicationPortWire.ts';
+export * from './engineApplicationPortHost.ts';
 export * from './webSocketApplicationPortClient.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/browser/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAA;AAC1C,cAAc,0BAA0B,CAAA;AACxC,cAAc,2BAA2B,CAAA;AACzC,cAAc,0BAA0B,CAAA;AACxC,cAAc,qCAAqC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAA;AAC1C,cAAc,0BAA0B,CAAA;AACxC,cAAc,2BAA2B,CAAA;AACzC,cAAc,0BAA0B,CAAA;AACxC,cAAc,gCAAgC,CAAA;AAC9C,cAAc,qCAAqC,CAAA"}

package/dist/browser/index.mjs

@@ -467,11 +467,11 @@ import {
   validatePortFrame as validatePortFrame2
 } from "@xyo-network/dapp-kit";
 function registeredOperations(options) {
-  const operations = /* @__PURE__ */ new Map();
+  const operations2 = /* @__PURE__ */ new Map();
   for (const operation of options.operations) {
-    const key = applicationPortOperationKey(operation.portId, operation.operationId);
+    const key2 = applicationPortOperationKey(operation.portId, operation.operationId);
     const grant = applicationPortOperationGrant(options.grant, operation.portId, operation.operationId);
-    if (operations.has(key)) {
+    if (operations2.has(key2)) {
       throw new ApplicationPortProxyError(
         ApplicationPortProxyErrorCode.duplicateRequest,
         `Application-port operation is registered more than once: ${operation.portId}.${operation.operationId}`
@@ -483,15 +483,18 @@ function registeredOperations(options) {
         `Registered operation conflicts with attachment grant: ${operation.portId}.${operation.operationId}`
       );
     }
-    operations.set(key, operation);
+    operations2.set(key2, operation);
   }
-  return operations;
+  return operations2;
 }
 var ApplicationPortHostInstance = class {
+  cleanupErrors = [];
+  closePromise;
   isClosed = false;
   listener;
   operations;
   options;
+  ownedRequests = /* @__PURE__ */ new Set();
   requests = /* @__PURE__ */ new Map();
   constructor(options) {
     this.options = { ...options, grant: PortAttachmentGrantZod2.parse(options.grant) };
@@ -500,19 +503,42 @@ var ApplicationPortHostInstance = class {
     options.endpoint.addMessageListener(this.listener);
     options.endpoint.start?.();
   }
-  async close() {
-    if (this.isClosed) return;
+  close() {
+    return this.drain();
+  }
+  closeAdmission() {
+    if (this.closePromise !== void 0) return;
+    const completion = Promise.withResolvers();
+    this.closePromise = completion.promise;
+    void this.closePromise.catch(() => {
+    });
     this.isClosed = true;
-    this.options.endpoint.removeMessageListener(this.listener);
-    const completions = [];
-    for (const state of this.requests.values()) {
+    try {
+      this.options.endpoint.removeMessageListener(this.listener);
+    } catch (cause) {
+      this.cleanupErrors.push(cause);
+    }
+    for (const state of this.ownedRequests) {
       state.isCancelled = true;
       state.controller.abort(ApplicationPortProxyErrorCode.detached);
-      if (state.kind === "unary" && state.completion !== void 0) completions.push(state.completion);
-      if (state.kind === "stream") this.collectStreamClosePromises(state, completions);
     }
-    await Promise.allSettled(completions);
-    this.requests.clear();
+    void Promise.resolve().then(async () => {
+      const outcomes = await Promise.allSettled([...this.ownedRequests].map(async (state) => {
+        if (state.kind === "unary") await state.completion;
+        else await this.cleanupStream(state, ApplicationPortProxyErrorCode.detached);
+      }));
+      for (const outcome of outcomes) {
+        if (outcome.status === "rejected") this.cleanupErrors.push(outcome.reason);
+      }
+      this.requests.clear();
+      if (this.cleanupErrors.length > 0) {
+        throw new AggregateError([...this.cleanupErrors], "Application-port host cleanup failed");
+      }
+    }).then(completion.resolve, completion.reject);
+  }
+  drain() {
+    this.closeAdmission();
+    return this.closePromise;
   }
   cancelAcknowledgement(frame) {
     return parseApplicationPortFrame({
@@ -534,21 +560,35 @@ var ApplicationPortHostInstance = class {
       await state.completion;
       return;
     }
-    await state.openPromise;
-    if (state.pumpPromise !== void 0) await state.pumpPromise;
-    await state.source?.cancel?.(frame.reasonCode);
+    await this.cleanupStream(state, frame.reasonCode);
     if (!this.isClosed && !state.isTerminal) {
       state.isTerminal = true;
-      this.post(this.cancelAcknowledgement(frame));
+      if (state.cleanupFailed) this.postError(frame, ApplicationPortProxyErrorCode.hostFailure);
+      else this.post(this.cancelAcknowledgement(frame));
     }
     this.requests.delete(frame.requestId);
   }
-  collectStreamClosePromises(state, completions) {
-    if (state.openPromise !== void 0) completions.push(state.openPromise);
-    if (state.pumpPromise !== void 0) completions.push(state.pumpPromise);
-    if (state.source?.cancel !== void 0) {
-      completions.push(state.source.cancel(ApplicationPortProxyErrorCode.detached));
-    }
+  cleanupStream(state, reasonCode) {
+    if (state.cleanupPromise !== void 0) return state.cleanupPromise;
+    const completion = Promise.withResolvers();
+    state.cleanupPromise = completion.promise;
+    void Promise.resolve().then(async () => {
+      for (const work of [() => state.openPromise, () => state.pumpPromise, () => state.source?.cancel?.(reasonCode)]) {
+        try {
+          await work();
+        } catch (cause) {
+          state.cleanupFailed = true;
+          this.cleanupErrors.push(cause);
+        }
+      }
+    }).catch((cause) => {
+      state.cleanupFailed = true;
+      this.cleanupErrors.push(cause);
+    }).finally(() => {
+      this.ownedRequests.delete(state);
+      completion.resolve();
+    });
+    return state.cleanupPromise;
   }
   dispatchStart(frame) {
     const operation = this.operations.get(applicationPortOperationKey(frame.portId, frame.operationId));
@@ -594,7 +634,10 @@ var ApplicationPortHostInstance = class {
       ...frame.frameKind === "stream-resume" ? { resumeCursor: frame.resumeCursor } : {}
     };
     this.requests.set(frame.requestId, state);
-    state.openPromise = this.runStreamOpen(state, frame, operation);
+    this.ownedRequests.add(state);
+    const completion = Promise.withResolvers();
+    state.openPromise = completion.promise;
+    void this.runStreamOpen(state, frame, operation).then(completion.resolve, completion.reject);
   }
   post(frame) {
     if (!this.isClosed) this.options.endpoint.send(frame);
@@ -604,8 +647,10 @@ var ApplicationPortHostInstance = class {
   }
   async pump(state) {
     if (state.pumpPromise !== void 0 || state.source === void 0 || state.isTerminal || state.isCancelled) return;
-    const pumping = this.pumpOnce(state);
+    const completion = Promise.withResolvers();
+    const pumping = completion.promise;
     state.pumpPromise = pumping;
+    void this.pumpOnce(state).then(completion.resolve, completion.reject);
     await pumping;
     if (state.pumpPromise === pumping) state.pumpPromise = void 0;
   }
@@ -677,8 +722,8 @@ var ApplicationPortHostInstance = class {
   async runStreamOpen(state, frame, operation) {
     try {
       const source = await this.startStreamSource(state, frame, operation);
-      this.verifyStreamSource(source, frame, state.grant);
       state.source = source;
+      this.verifyStreamSource(source, frame, state.grant);
       state.lastSequence = source.nextSequence - 1;
       state.resumeCursor = source.resumeCursor;
       if (state.isCancelled || this.isClosed) return;
@@ -697,6 +742,7 @@ var ApplicationPortHostInstance = class {
         state.isTerminal = true;
         this.post(applicationPortErrorFrame(this.options.grant, frame, this.mapError(frame, error)));
         this.requests.delete(frame.requestId);
+        void this.cleanupStream(state, ApplicationPortProxyErrorCode.hostFailure);
       }
     }
   }
@@ -728,6 +774,7 @@ var ApplicationPortHostInstance = class {
         this.post(this.cancelAcknowledgement(frame));
       }
       this.requests.delete(frame.requestId);
+      this.ownedRequests.delete(state);
     }
   }
   async sendNext(state) {
@@ -745,6 +792,7 @@ var ApplicationPortHostInstance = class {
         ...read.resumeCursor === void 0 ? {} : { resumeCursor: read.resumeCursor }
       }));
       this.requests.delete(state.frame.requestId);
+      this.ownedRequests.delete(state);
       return false;
     }
     if (source.resumable && read.value.resumeCursor === void 0) {
@@ -797,7 +845,10 @@ var ApplicationPortHostInstance = class {
       kind: "unary"
     };
     this.requests.set(frame.requestId, state);
-    state.completion = this.runUnary(state, frame, operation);
+    this.ownedRequests.add(state);
+    const completion = Promise.withResolvers();
+    state.completion = completion.promise;
+    void this.runUnary(state, frame, operation).then(completion.resolve, completion.reject);
   }
   terminateStreamWithError(state, cause, code) {
     const source = state.source;
@@ -813,6 +864,9 @@ var ApplicationPortHostInstance = class {
       error
     }));
     this.requests.delete(state.frame.requestId);
+    state.isCancelled = true;
+    state.controller.abort(ApplicationPortProxyErrorCode.hostFailure);
+    void this.cleanupStream(state, ApplicationPortProxyErrorCode.hostFailure);
   }
   verifyStreamSource(source, frame, grant) {
     const resumeMismatch = frame.frameKind === "stream-resume" && (source.streamId !== frame.streamId || source.nextSequence !== frame.lastAcceptedSequence + 1);
@@ -923,6 +977,233 @@ function serializeApplicationPortWireMessage(message, maximumFrameBytes) {
   return source;
 }
 
+// src/engineApplicationPortHost.ts
+import {
+  DappEngineSystemReferenceZod,
+  PortAttachmentGrantZod as PortAttachmentGrantZod4,
+  validateDappEngineSystemReference
+} from "@xyo-network/dapp-kit";
+
+// src/engineOperationRecovery.ts
+import {
+  DappOperationRecoveryBindingZod,
+  DappOperationRecoveryProfileZod,
+  validateDappOperationRecoveryAdmission
+} from "@xyo-network/dapp-kit";
+
+// src/enginePortAdmissionError.ts
+var DappEnginePortAdmissionError = class extends Error {
+  code;
+  constructor(code) {
+    super(code);
+    this.name = "DappEnginePortAdmissionError";
+    this.code = code;
+  }
+};
+
+// src/engineOperationRecovery.ts
+var key = (portId, operationId) => JSON.stringify([portId, operationId]);
+function bindEngineOperationRecovery(options, operations2, reference, target2) {
+  if (options === void 0) return void 0;
+  const parsed = DappOperationRecoveryProfileZod.safeParse(options.profile);
+  if (!parsed.success || typeof options.readSnapshot !== "function") throw new DappEnginePortAdmissionError("recovery.profile-invalid");
+  const profile = parsed.data;
+  if (profile.operations.length !== operations2.length) throw new DappEnginePortAdmissionError("recovery.profile-mismatch");
+  const requirements = /* @__PURE__ */ new Map();
+  for (const requirement of profile.operations) {
+    if (requirement.recovery.kind !== "read-only") Object.freeze(requirement.recovery.requiredGuarantees);
+    Object.freeze(requirement.recovery);
+    requirements.set(key(requirement.portId, requirement.operationId), Object.freeze(requirement));
+  }
+  for (const binding2 of operations2) {
+    const requirement = requirements.get(key(binding2.operation.portId, binding2.operation.operationId));
+    if (requirement === void 0 || requirement.recovery.kind === "read-only" !== (binding2.access === "read")) {
+      throw new DappEnginePortAdmissionError("recovery.profile-mismatch");
+    }
+  }
+  const parsedBinding = DappOperationRecoveryBindingZod.safeParse({
+    reference,
+    dappId: target2.status.dappId,
+    hostSessionId: target2.status.hostSessionId,
+    planId: target2.status.planId,
+    network: target2.declaration.network,
+    authorityScopeId: options.authorityScopeId
+  });
+  if (!parsedBinding.success) throw new DappEnginePortAdmissionError("recovery.binding-invalid");
+  Object.freeze(parsedBinding.data.reference);
+  Object.freeze(parsedBinding.data.network);
+  const binding = Object.freeze(parsedBinding.data);
+  const readSnapshot = options.readSnapshot.bind(options);
+  return (portId, operationId) => {
+    const requirement = requirements.get(key(portId, operationId));
+    if (requirement.recovery.kind === "read-only") return;
+    let snapshot;
+    try {
+      snapshot = readSnapshot(requirement, binding);
+    } catch {
+      throw new DappEnginePortAdmissionError("recovery.unavailable");
+    }
+    let admission;
+    try {
+      admission = validateDappOperationRecoveryAdmission(requirement, binding, snapshot);
+    } catch {
+      throw new DappEnginePortAdmissionError("recovery.snapshot-invalid");
+    }
+    if (!admission.success) throw new DappEnginePortAdmissionError(admission.issue.code);
+  };
+}
+
+// src/engineApplicationPortHost.ts
+function deferredEndpoint(source) {
+  let listener;
+  let attached = false;
+  let closed = false;
+  const endpoint = {
+    addMessageListener: (value) => {
+      listener = value;
+    },
+    removeMessageListener: (value) => {
+      closed = true;
+      if (attached) source.removeMessageListener(value);
+      listener = void 0;
+    },
+    send: (message) => source.send(message)
+  };
+  return {
+    endpoint,
+    activate: () => {
+      if (closed || listener === void 0) throw new DappEnginePortAdmissionError("engine.system-unavailable");
+      attached = true;
+      source.addMessageListener(listener);
+      if (!closed) source.start?.();
+    }
+  };
+}
+function target(readStatus, reference, grant) {
+  const result = validateDappEngineSystemReference(readStatus(), reference);
+  if (!result.success) throw new DappEnginePortAdmissionError(result.issue.code);
+  const status = result.value.status;
+  if (grant.dappId !== status.dappId || grant.hostSessionId !== status.hostSessionId || grant.planId !== status.planId || grant.systemInstanceId !== status.systemInstanceId) {
+    throw new DappEnginePortAdmissionError("engine.attachment-mismatch");
+  }
+  return result.value;
+}
+function operations(bindings, grant, readTarget, admitRecovery) {
+  const keys = /* @__PURE__ */ new Set();
+  return bindings.map(({ access, operation }) => {
+    const {
+      portId,
+      operationId,
+      streaming
+    } = operation;
+    const key2 = applicationPortOperationKey(portId, operationId);
+    const allowed = grant.operations.find((value) => value.portId === portId && value.operationId === operationId);
+    if (access !== "read" && access !== "write" || keys.has(key2) || allowed?.streaming !== streaming) {
+      throw new DappEnginePortAdmissionError("engine.operation-binding-invalid");
+    }
+    keys.add(key2);
+    const authorize = () => {
+      const capability = readTarget().status.writeCapabilities.find((value) => value.portId === portId && value.operationId === operationId);
+      if (access === "read" && capability !== void 0) throw new DappEnginePortAdmissionError("engine.operation-access-invalid");
+      if (access === "write" && capability?.writable !== true) throw new DappEnginePortAdmissionError("engine.operation-not-writable");
+    };
+    const admit = () => {
+      authorize();
+      if (access !== "write" || admitRecovery === void 0) {
+        return;
+      }
+      admitRecovery(portId, operationId);
+      authorize();
+    };
+    if (operation.streaming) {
+      const open = operation.open.bind(operation);
+      const resume = operation.resume?.bind(operation);
+      return Object.freeze({
+        portId,
+        operationId,
+        streaming: true,
+        open: (context) => {
+          admit();
+          return open(context);
+        },
+        ...resume === void 0 ? {} : {
+          resume: (context) => {
+            admit();
+            return resume(context);
+          }
+        }
+      });
+    }
+    const handle = operation.handle.bind(operation);
+    return Object.freeze({
+      portId,
+      operationId,
+      streaming: false,
+      handle: (context) => {
+        admit();
+        return handle(context);
+      }
+    });
+  });
+}
+async function createDappEngineApplicationPortHost(options) {
+  const reference = DappEngineSystemReferenceZod.parse(options.reference);
+  const grant = PortAttachmentGrantZod4.parse(options.grant);
+  const readStatus = options.engine.status.bind(options.engine);
+  const readTarget = () => target(readStatus, reference, grant);
+  const selected = readTarget();
+  const admitRecovery = bindEngineOperationRecovery(options.recovery, options.operations, reference, selected);
+  const boundOperations = operations(options.operations, grant, readTarget, admitRecovery);
+  const deferred = deferredEndpoint(options.endpoint);
+  const mapDomainError = options.mapError.bind(options);
+  const disconnect = options.disconnect.bind(options);
+  const binding = options.engine.bindSystemWork(reference, () => {
+    const host = createApplicationPortHost({
+      authenticatedPrincipalId: options.authenticatedPrincipalId,
+      endpoint: deferred.endpoint,
+      grant,
+      now: options.now,
+      onProtocolError: options.onProtocolError,
+      operations: boundOperations,
+      mapError: (error) => error instanceof DappEnginePortAdmissionError ? { code: error.code, retriable: false } : mapDomainError(error)
+    });
+    let disconnected;
+    return {
+      close: () => {
+        host.closeAdmission();
+        disconnected = (async () => {
+          await disconnect();
+        })();
+        void disconnected.catch(() => {
+        });
+      },
+      drain: async () => {
+        const outcomes = await Promise.allSettled([host.drain(), disconnected]);
+        const errors = outcomes.filter((outcome) => outcome.status === "rejected").map((outcome) => outcome.reason);
+        if (errors.length > 0) throw new AggregateError(errors, "Engine application-port drainage failed");
+      }
+    };
+  });
+  try {
+    deferred.activate();
+    readTarget();
+  } catch (cause) {
+    try {
+      await binding.close();
+    } catch (cleanup) {
+      throw new AggregateError([cause, cleanup], "Engine application-port setup and cleanup failed", { cause: cleanup });
+    }
+    throw cause;
+  }
+  return Object.freeze({
+    close: () => binding.close(),
+    closeAdmission: () => {
+      void binding.close();
+    },
+    drain: () => binding.close()
+  });
+}
+
 // src/webSocketApplicationPortClient.ts
 import { PortFrameZod as PortFrameZod3 } from "@xyo-network/dapp-kit";
 var WebSocketApplicationPortClientErrorCode = {
@@ -1165,6 +1446,7 @@ export {
   ApplicationPortWireError,
   ApplicationPortWireErrorCode,
   ApplicationPortWireMessageZod,
+  DappEnginePortAdmissionError,
   WebSocketApplicationPortClientError,
   WebSocketApplicationPortClientErrorCode,
   applicationPortErrorFrame,
@@ -1174,6 +1456,7 @@ export {
   connectWebSocketApplicationPort,
   createApplicationPortClient,
   createApplicationPortHost,
+  createDappEngineApplicationPortHost,
   isApplicationPortFrame,
   parseApplicationPortFrame,
   parseApplicationPortWireText,