@spine-event-engine/auth 2.0.0-snapshot.25 → 2.0.0-snapshot.28

package/README.md

@@ -24,15 +24,25 @@ is native-only and treats auth as an optional peer.
 
 ## First success: create and resolve a local session
 
-`OpaqueSessions` is a bounded, process-local store for local development or a
-single process. This creates a credential, resolves it, and closes the store.
+Omitting a store selects process-local memory for development. Configure a seal
+secret and explicit session policy before issuing credentials. A
+`PersistentOpaqueSessionStore` can instead share the same atomic sessions across
+processes; its asynchronous factory prepares selected structures by default.
 
 ```ts
 import { OpaqueSessions } from "@spine-event-engine/auth";
-
-const sessions = new OpaqueSessions({ ttlMilliseconds: 60 * 60 * 1_000, maxSessions: 100 });
+import { Time } from "@spine-event-engine/core/time";
+
+const password = process.env.SESSION_SEAL_PASSWORD;
+if (!password) throw new Error("Configure SESSION_SEAL_PASSWORD");
+const sessions = await OpaqueSessions.create({
+  scope: "local-browser",
+  password,
+  clock: { now: Time.currentTimeMillis },
+  ttlMilliseconds: 60 * 60 * 1_000,
+});
 try {
-  const created = await sessions.create({ id: "local-user" });
+  const created = await sessions.issue({ id: "local-user" });
   if (created.kind !== "created") throw new Error(`Session creation failed: ${created.reason}`);
   const resolved = await sessions.resolve(created.credential);
   if (resolved === undefined) throw new Error("New local session was not resolvable");
@@ -42,6 +52,67 @@ try {
 }
 ```
 
+## Share opaque sessions through PostgreSQL
+
+Install `@spine-event-engine/storage-postgres` alongside the auth package. Give
+the session family a dedicated storage group. The database and schema must
+already exist.
+
+```ts
+import { OpaqueSessions, PersistentOpaqueSessionStore } from "@spine-event-engine/auth";
+import { Time } from "@spine-event-engine/core/time";
+import { StorageGroup } from "@spine-event-engine/storage";
+import { PostgresStorageFactory } from "@spine-event-engine/storage-postgres";
+
+const url = process.env.DATABASE_URL;
+const password = process.env.SESSION_SEAL_PASSWORD;
+if (!url || !password) throw new Error("Configure database and session credentials");
+const factory = await PostgresStorageFactory.newBuilder().setOptions({ url }).build();
+let store: PersistentOpaqueSessionStore | undefined;
+try {
+  store = await PersistentOpaqueSessionStore.create({
+    storageFactory: factory,
+    group: new StorageGroup("auth_sessions"),
+  });
+  const sessions = await OpaqueSessions.create({
+    store,
+    scope: "orders-browser",
+    password,
+    clock: { now: Time.currentTimeMillis },
+    ttlMilliseconds: 60 * 60 * 1_000,
+  });
+  try {
+    const issued = await sessions.issue({ id: "user-42" });
+    if (issued.kind !== "created") throw new Error(`Session issue failed: ${issued.reason}`);
+    // Send issued.credential through the application's credential transport.
+  } finally {
+    await sessions.close();
+  }
+} finally {
+  try {
+    await store?.close();
+  } finally {
+    await factory.close();
+  }
+}
+```
+
+The strategy leaves an injected store open; close the strategy, store, and
+factory in that order. Use the same group and seal policy in each process.
+
+## Signed bearer sessions
+
+`SignedSessions` issues and verifies ES256 bearer tokens with an application
+P-256 key pair. Without a revocation source, logout reports expiry-only.
+`PersistentTokenRevocations.create` supplies shared scoped revocation through
+the selected storage factory and group; pass the resulting store as the
+strategy's `revocation`. The store prepares its indexed record family by
+default. Its explicit `purgeExpired` method removes records only after their
+full inclusive acceptance deadline, including configured clock skew. The
+application closes the strategy, store, and factory separately. See the
+[signed session reference](REFERENCE.md) for exact retention and maintenance
+behavior.
+
 For a real gateway, construct `UnaryGateway` with exactly one admission mode:
 `sessions`, or deliberate `publicAccess: true`. It requires a finite request
 limit, policy, trusted-context resolver, clock, and forwarder. Every approved
@@ -54,14 +125,52 @@ Events can refer to the exact Command that caused them. Those metadata fields
 are supplied by the caller; they are not proof of identity. Queries and
 subscription Topics receive the context supplied by the gateway resolver.
 
+## Pass verified reader information to the application node
+
+The gateway also forwards the admitted principal and the `authorityFacts`
+returned by `ContextResolver.resolve()`. These facts may contain JSON values,
+including role arrays, booleans, and nested objects. They are detached from the
+session and resolver result before forwarding. The framework does not copy the
+request credential into them or fetch fresh information from an identity provider.
+Your resolver decides which facts to supply on each request.
+
+For a browser gateway, supply the issuer through
+`BrowserServerOptions.forwardingProof`. When assembling a native gateway,
+configure `NativeSubscriptionCreator(transport, { issuer, maxBytes })`; a custom
+unary forwarder must produce the same operation-bound proof. See
+[Verified reader forwarding](REFERENCE.md#verified-reader-forwarding) for the forwarding adapters.
+
+In either setup, configure `ServerOptions.services.readerAdmission.forwarded`
+on the receiving application node. The issuer produces a proof for the service,
+method, request bytes, and reader facts. The verifier checks that proof and the
+forwarding peer. Both are replaceable application adapters. A header name, actor
+ID, or loopback connection does not establish a verified reader.
+
+Authenticated forwarding requires an issuer. Deliberate `publicAccess: true`
+forwards no principal or authority facts; the gateway's public admission marker
+does not become a user identity. See the [server reference](https://github.com/SpineEventEngine/spine-ts/blob/master/packages/server/REFERENCE.md#native-reader-admission)
+for direct native authentication and managed forwarding configuration.
+
 ## Browser and OIDC extensions
 
-The package does not provide HTTP routes, browser pages, users, permissions,
-TLS, or a production session database. An application can compose
-`OidcFlow` with Google, GitHub, or another verified provider, but it must own
-the start, callback, exchange, identity mapping, and session issuance routes.
+`OidcFlow` is a component flow: the application provides its start, callback,
+exchange, identity mapping, and session issuance routes. It does not supply
+browser pages, users, permissions, TLS, or a production session database. An application can compose `OidcFlow` with
+Google, GitHub, or another verified provider.
 Keep provider access, refresh, and ID tokens server-side.
 
+`OidcFlow.start()` is asynchronous: await it before redirecting the browser.
+The default transaction and application-grant store is process-local. To share
+one login flow across processes, create `PersistentOidcFlowStore` with a
+`StorageFactory`, `StorageGroup`, and stable `flowId`, then pass it in
+`OidcFlowOptions.store`. The factory prepares both record families by default;
+`createMissingStructures: false` skips preparation. Close the flow, then its
+injected store and factory when the application shuts down. Call
+`purgeExpired(cutoff)` explicitly for expired records; no timer runs it.
+
+The application must send the authorization URL returned by `OidcFlow.start()`
+to the browser and supply the actual callback parameters.
+
 For browser-facing hosting, install the server browser entry point and use
 `BrowserServer` and `DurableSubscriptionBindings` from
 `@spine-event-engine/server/browser`. That boundary requires exact origins,
@@ -70,8 +179,16 @@ durable authenticated bindings when applicable.
 
 ## Limits and next steps
 
-`OpaqueSessions` is not shared or durable. Signed-session revocation and OIDC
-identity provisioning are application responsibilities. A gateway protects
+The [Fieldnotes application](https://github.com/SpineEventEngine/spine-ts/blob/master/examples/fieldnotes/README.md)
+connects a Next.js map interface to a single-tenant Bounded Context. Its two launch
+options demonstrate direct Google OIDC and Google sign-in through Firebase Auth.
+Both use persistent opaque application sessions stored through the PostgreSQL
+storage factory. The application guide follows sign-in through authenticated
+Commands, private queries and subscriptions, and logout.
+
+Memory-selected `OpaqueSessions` is process-local; select durable shared storage
+for sessions that must survive process restart. Signed-session revocation and
+OIDC identity provisioning are application responsibilities. A gateway protects
 only traffic that operators route through it; do not expose a backend route
 around that boundary.
 

package/REFERENCE.md

@@ -7,7 +7,7 @@ Start with the [authentication overview](README.md) when choosing a gateway shap
 
 The package supplies provider-neutral gateway building blocks. An application places its gateway in front of a Spine TS or Spine JVM backend, then supplies the listener, credential extraction, identity provider, session storage, authorization rules, actor/tenant resolution, and forwarding implementation. The framework does not enforce a particular proxy, route topology, identity provider, tenant policy, or deployment configuration.
 
-`TransportFacts.from()` exposes only allowlisted request facts. Credentials are passed only to `Authenticator` or `SessionResolver`; they are not included in `IncomingRequest`. `IncomingRequest` is a discriminated union for command, query, subscription creation, activation, and cancellation. Command facts can include a decoded message when a `TypeRegistryLookup` knows its packed type; unknown and malformed `Any` values remain type-URL-only facts.
+`TransportFacts.from()` exposes only allowlisted request facts. Credentials are passed only to `Authenticator` or `SessionResolver`; they are not included in `IncomingRequest`. `IncomingRequest` is a discriminated union for command, entity query, application query, subscription creation, activation, and cancellation. Command facts can include a decoded message when a `TypeRegistryLookup` knows its packed type; unknown and malformed `Any` values remain type-URL-only facts.
 
 `AuthorizationPolicy.authorize()` is evaluated separately for each incoming request. `ContextResolver.resolve()` returns the trusted actor, optional tenant, timestamp, zone, and language. The caller-provided `ActorContext` must match that resolved actor and tenant, otherwise `UnaryGateway` rejects the request as `context-stale`. Backends may rely on these identity checks only when the deployment routes traffic through an application-selected gateway.
 
@@ -40,7 +40,7 @@ a failed remote cleanup remains retryable.
 
 ## Unary requests
 
-`UnaryGateway` accepts `CommandService.Post`, `QueryService.Read`, and
+`UnaryGateway` accepts `CommandService.Post`, `QueryService.Read`, `QueryService.Execute`, and
 `AuthenticationService.ResolveContext`. Construct both `UnaryGateway` and
 `SubscriptionGateway` with exactly one admission mode: a `SessionResolver`, or
 `publicAccess: true`. Public access creates no login session and no synthetic
@@ -50,18 +50,167 @@ Gateway, its authorization policy admits the public principal, and its
 also require finite request limits, an authorization function,
 `ContextResolver`, clock, and the corresponding forwarding collaborator.
 
-For Post and Read, it bounds and decodes bytes, admits the request through the selected mode, authorizes the decoded request, resolves trusted context, checks requested actor/tenant, and forwards exactly once. In authenticated mode, admission resolves the supplied session. In public mode, it uses the framework-owned public principal and no session. The forwarder receives only service, method, bytes, and optional cancellation signal. It does not receive credentials or extra transport facts. It returns `forwarded`, `resolved`, or a rejection reason: `request-too-large`, `unknown-operation`, `malformed-request`, `unauthenticated`, `forbidden`, or `context-stale`. Mapping a rejection to HTTP or gRPC status is the native transport adapter's job.
+For Post, Read, and Execute, it bounds and decodes bytes, admits the request through the selected mode, authorizes the decoded request, resolves trusted context, checks requested actor/tenant, and forwards exactly once. In authenticated mode, admission resolves the supplied session. In public mode, it uses the public admission marker and no session. The forwarder receives service, method, bytes, detached `reader` facts, and an optional cancellation signal. It does not receive credentials or extra transport facts. It returns `forwarded`, `resolved`, or a rejection reason: `request-too-large`, `unknown-operation`, `malformed-request`, `unauthenticated`, `forbidden`, or `context-stale`. Mapping a rejection to HTTP or gRPC status is the native transport adapter's job.
 
 ResolveContext returns informational trusted actor and tenant facts in both modes. In authenticated mode, it validates the current session and also returns its expiry. In public mode, it resolves context for the framework-owned public principal and omits `expiresAt` because no session exists. It neither authorizes a business request nor creates a reusable credential. Later requests are independently admitted and authorized.
 
+### Verified reader forwarding
+
+`reader.principal` contains the admitted application principal's ID and string
+attributes. `reader.authorityFacts` comes from `AuthorizedRequestContext.authorityFacts`
+and accepts finite JSON values, including nested objects and arrays. The gateway
+copies these values for the invocation. Public admission omits both fields even
+if a context resolver supplies facts for the public admission marker.
+The existing `ContextResolver` remains the replacement point for obtaining
+application-specific authority information; there is no provider polling or
+promise that its information remains current after resolution.
+
+`NativeSubscriptionCreator(transport, { issuer, maxBytes })` uses the configured
+issuer to forward that reader with each native operation. `BrowserServerOptions.forwardingProof`
+configures the same issuer in browser composition. Its `issue(bytes)` method
+returns a transport-safe proof. The application node's corresponding
+`services.readerAdmission.forwarded.verify(bytes, proof, peer)` verifies the
+forwarding peer and the assertion. The signed bytes bind the service, method,
+canonical request, and reader facts; an Activate proof cannot authorize Cancel.
+Internal metadata received from a caller is not accepted without that verifier.
+
+An authenticated native forwarding call without an issuer fails rather than
+discarding its reader identity. Configure both issuer and verifier for authenticated
+browser forwarding. These are TS forwarding ports; merely sending
+their metadata to a JVM backend does not add verified-reader support there.
+Custom forwarding implementations must establish the equivalent trust at their
+receiving boundary. Credentials and provider tokens are not forwarding fields.
+
 ## Sessions and sign-in
 
-`OpaqueSessions` implements a bounded, process-local `SessionResolver` with random cookie credentials. Defaults are an eight-hour lifetime, 10,000 retained sessions, and three identifier attempts. It lazily removes expired entries and is terminal after `close()`. It suits local development and the supported single-Gateway shape; choose an application session strategy that meets that gateway's restart and revocation requirements.
+`OpaqueSessions.create` requires an application scope, iron-session password
+configuration, trusted clock, and positive lifetime. `issue` seals a random
+stable reference and generation before atomic absent insertion. `resolve`
+checks the current stored generation and exact deadline without renewal.
+The authenticated application deadline is authoritative: any grace period in
+iron-session's seal validation cannot extend it. Rotation seals before
+compare-and-set. An old unexpired seal can revoke the current generation, but
+an expired seal cannot resolve or revoke.
+
+Omitting the store selects process-local memory. `PersistentOpaqueSessionStore.create`
+accepts a common storage factory and group; it prepares the indexed session
+family before returning by default. `createMissingStructures: false` opens a
+non-preparing handle for already prepared structures. The strategy leaves an
+injected store open, so the application closes the strategy, store, and factory
+separately. Explicit `purgeExpired(cutoff, signal)` traverses finite indexed
+pages with conditional removal in the persistent store; process-local memory
+scans its own records. If a row changes during conditional removal, the pass
+finishes that expiry group and returns its removed count. The changed row and
+other eligible rows in later groups can remain for another explicit purge.
+Storage errors and cancellation reject, possibly after partial removal. No
+timer calls maintenance automatically.
+
+For cancellation after a confirmed insertion or replacement, the strategy
+attempts conditional compensation and returns no credential. A storage error
+that does not confirm whether a commit occurred cannot safely authorize removal:
+another session may already occupy the same stable reference. The operation
+fails without returning a credential, but a committed row may require later
+explicit maintenance. This is a best-effort cleanup guarantee.
+
+`SignedSessions` issues and verifies ES256 application bearer tokens using jose.
+Without a `SignedTokenRevocation` source, logout is expiry-only. For shared
+revocation, create `PersistentTokenRevocations` with a storage factory, group,
+issuer, and audience, then inject it as `revocation`. Its asynchronous factory
+prepares the indexed record family by default; `createMissingStructures: false`
+opens a non-preparing handle with no physical schema checks or DDL at creation
+or during later operations. If structures are missing, ordinary storage
+operations fail. Close the strategy, revocation store, and shared
+factory separately. The strategy passes the full inclusive acceptance deadline,
+including clock skew, to the store. Reads ignore records after that deadline
+even before maintenance. Explicit `purgeExpired(cutoff, signal)` removes only
+records strictly before a cutoff no later than the store's trusted clock. It
+uses scoped indexed pages and conditional deletion; a concurrent change can
+leave eligible rows for a later invocation. No automatic cleanup runs.
 
-`SignedSessions` provides signed application session tokens. Local signature validation can delay revocation; shared revocation requires an explicit `SignedTokenRevocation` implementation. `OpaqueSessionCookies` supplies strict cookie parsing and serialization helpers. Neither strategy provisions users nor grants permissions.
+`SessionResolver.resolve(credential, lifetime?)` accepts an optional operation
+signal. Omitting it performs one validation without a retained monitor. With
+one, standard opaque and signed strategies register by stable authenticated
+identity before the authoritative storage or revocation read and return
+`ResolvedSession.invalidated`. Local logout, the captured resolved deadline,
+or strategy close aborts that signal. The supplied operation ending releases
+the listener and expiry timer. Opaque rotation does not extend an existing
+operation's captured deadline; signed token verification skew and durable
+revocation retention do not extend it either. The Gateway links invalidation
+to its backend cancellation and suppresses late updates. Logout errors remain
+visible even when local forwarding has stopped. Another process receives no
+local abort signal and must validate against shared durable state separately.
+`OpaqueSessionCookies` binds its CSRF value to the complete sealed credential,
+parses Cookie fields with cookie 2.0.1 after duplicate checks, and emits separate
+secure `__Host-` session and CSRF `Set-Cookie` fields. Pass the actual issued
+deadline to `issue`; `persistent: true` gives both cookies that deadline while
+the default keeps them as browser-session cookies. `sameSite` accepts `lax`,
+`strict`, or `none`; the session cookie remains `HttpOnly` and the CSRF cookie
+remains readable by the browser.
+
+```ts
+import { OpaqueSessionCookies, type OpaqueSessions } from "@spine-event-engine/auth";
+
+declare const sessions: OpaqueSessions;
+const cookies = new OpaqueSessionCookies({
+  csrfSecret: crypto.getRandomValues(new Uint8Array(32)),
+  origins: ["https://app.example"],
+  sameSite: "strict",
+  persistent: true,
+});
+const issued = await sessions.issue({ id: "example-user" });
+if (issued.kind === "created") {
+  const setCookieFields = cookies.issue(issued.credential.value, issued.session.expiresAt);
+  // Append each field separately to the HTTP response.
+  void setCookieFields;
+}
+```
+
+After rotation, call `issue` again with the new sealed value and its deadline;
+`clear()` emits matching host-only removal fields. `read` distinguishes missing
+credentials from terminal rejection so browser hosting does not fall back to a
+different reader after invalid input.
+Neither strategy provisions users nor grants permissions.
 
 `OidcFlow` is a bounded authorization-code and PKCE transaction manager. It works with `createGoogleProvider`, `createGitHubProvider`, or a discovered or configured OIDC provider. Applications expose start/callback/exchange endpoints, perform HTTP routing, map verified external identity through `IdentityMapping`, and issue an application session through `ApplicationSessionIssuer`. Provider access, refresh, and ID tokens remain sensitive server-side material; do not return them to browser application code.
 
+`OidcFlow.start()` awaits transaction persistence before returning an
+authorization URL. Callback binding and expiry are validated before the
+transaction is atomically consumed; provider exchange and identity mapping
+follow consumption. Browser PKCE proof and grant expiry are validated before
+the grant is consumed; application session issuance follows consumption. A
+trusted clock check after each confirmed consumption stops the next external
+step if the record reached expiry while storage was pending. A
+failed external step does not restore a consumed record. Independent flow
+instances select the same one-use records through their configured store.
+The optional second `AbortSignal` on start, callback, and exchange carries host
+request cancellation. Ordinary abort rejects with that reason; a distinct
+session issuer failure rejects the pending exchange or, after an abort or
+timeout has returned, is reported by `close()`. Close waits for admitted work
+and the original provider, mapping, and issuer promises to settle. A consumed
+transaction or grant is never restored after cancellation.
+
+The default `OidcFlow` store is process-local. `PersistentOidcFlowStore.create()`
+selects two record families from the supplied `StorageFactory` and `StorageGroup`;
+`flowId` qualifies state, grants, and indexed expiry queries. Preparation of
+both families completes by default. `createMissingStructures: false` returns
+non-preparing handles that do not probe for structures later. `OidcFlow.close()`
+drains admitted work and closes only its default memory store. Close an injected
+store and its factory separately. `purgeExpired(cutoff)` is explicit and uses a
+flow-scoped exact expiry index in persistent storage. A concurrent row change
+can leave eligible records for a later invocation. Cancellation or storage
+failure rejects with partial progress possible. A known confirmed late insert
+is conditionally removed after close; if another writer has replaced that
+record, the replacement remains. An ambiguous thrown storage result cannot be
+rolled back safely and may need later explicit maintenance.
+
+`discoverOidcProvider()` uses the exact selected discovery URL, including an
+application supplied path and query, and rejects a returned issuer mismatch.
+The selected URL does not replace token or JWKS destinations. Authorization
+URLs use S256 and replace reserved protocol parameters while retaining other
+provider query values. Token exchange uses the configured client authentication
+and exact callback URI; the provider returns an identity only after bounded
+response parsing and JOSE ID-token verification.
+
 ## Subscription and native adapters
 
 `SubscriptionGateway` and `InMemorySubscriptionBindings` compose subscription creation, activation, cancellation, and relaying at the gateway boundary. The Gateway accepts a logical `SubscriptionCoordinator`; native `SubscriptionCreator` instances remain a per-node implementation seam. This is an intentional replacement of the former public native-creator input, with no compatibility adapter because Spine TS has no deployed users. In-memory bindings are local to one process and have finite operation limits; they do not provide cross-machine propagation. `createNativeGatewayServices`, `NativeSubscriptionCreator`, and `SubscriptionUpdateRelay` adapt these public contracts to the native service layer. They do not make a deployment secure by themselves: applications choose how their listener accepts only gateway-routed traffic.
@@ -69,10 +218,14 @@ ResolveContext returns informational trusted actor and tenant facts in both mode
 `BackendSubscriptionEnvelope` is opaque to the Gateway. A custom `SubscriptionCreator` or `DynamicUnaryClient` must validate each forwarded update's subscription ID and Topic against the actual Subscription accepted by its backend. The built-in native creator performs this validation; a custom envelope does not imply the backend reused the requested child ID.
 
 `DurableSubscriptionBindings` from `@spine-event-engine/server/browser` retains one approved
-`GatewayAuthenticatedSubscription` per public Subscription. The retained Topic
-includes the trusted Actor and Tenant, so Activate and Cancel compare that pair
-with the newly resolved request context. It is single-Gateway persistence, not
-cross-process quota, reservation, lease, fence, or fingerprint coordination.
+`GatewayAuthenticatedSubscription` per public Subscription. The record includes
+the stable principal ID, while its Topic retains the trusted Actor and Tenant.
+Activate and Cancel check all three against the newly admitted request before
+affecting a stream or record. The same principal may reconnect with changed
+attributes or authority facts; those facts are not persisted as its identity.
+Explicit anonymous admission is distinct from a missing legacy binding. A
+missing binding cannot be claimed by the next caller. This remains single-Gateway
+persistence, not cross-process quota, reservation, lease, or fingerprint coordination.
 
 Public subscription creation has two stages. `Subscribe` stores a process-local
 definition and returns its ID; `Activate` must arrive within the shared
@@ -100,9 +253,10 @@ Read the [browser client and gateway guide](../../docs/BROWSER_CLIENT_AUTH_EXTEN
 
 `DynamicUnaryForwarder` accepts complete current application-node snapshots. It serializes reconciliation, retains only the latest pending snapshot during churn, starts clients in bounded batches, disposes departed clients, and round-robins commands and queries across the resulting set. A dispatched unary request is never retried. Empty membership reports backend unavailability until a later snapshot restores clients.
 
-Dynamic subscriptions use the same reconciliation owner. Durable bindings retain
-the logical subscription definition and trusted Actor/Tenant facts only; native streams are
-ephemeral per-node work. Nodes may be added, removed, or re-added without
+Dynamic subscriptions use the same reconciliation process. Durable bindings retain
+the logical subscription definition, trusted Actor/Tenant facts, and stable reader
+identity; native streams and changing authority facts are per-process data.
+Nodes may be added, removed, or re-added without
 changing a durable definition. Notifications are best effort, may duplicate,
 and browser clients reconnect and re-query authoritative state after loss.
 

package/dist/gateway/dynamic-unary-forwarder.d.ts

@@ -52,13 +52,67 @@ export declare class DynamicUnaryForwarder implements UnaryForwarder {
      * @param options Configures discovery clients and resource bounds.
      */
     constructor(options: DynamicUnaryOptions);
+    /**
+     * Records the native child definition and its admitted logical reader.
+     *
+     * @param definition The serialized logical subscription definition.
+     * @param node Selected managed application node.
+     * @returns The child subscription definition.
+     */
+    private childDefinition;
     /**
      * Builds membership operations for one connected gateway client.
      *
      * @param client The connected gateway client.
      * @returns The member's forwarding and subscription operations.
      */
-    private static memberClient;
+    private memberClient;
+    /**
+     * Removes one native child and then retires its reader associations.
+     *
+     * @param client Connected member client that created this child.
+     * @param child Backend-issued child envelope.
+     * @param signal Cancellation signal for native disposal.
+     * @returns Completion after native disposal and reader cleanup.
+     */
+    private disposeChild;
+    /**
+     * Starts a native child and tracks an assigned ID for its admitted reader.
+     *
+     * @param client Native subscription client.
+     * @param definition The serialized subscription definition.
+     * @param signal The cancellation signal for this operation.
+     * @returns The managed-child subscription.
+     */
+    private subscribeChild;
+    /**
+     * Finds detached reader facts for one retained logical or native child definition.
+     *
+     * @param bytes The serialized message bytes.
+     * @returns The persisted reader binding field.
+     */
+    private readerField;
+    /**
+     * Records a backend-assigned child ID to its admitted logical reader.
+     *
+     * @param association Native child attempt that produced the backend ID.
+     * @param produced Backend update produced for a subscription.
+     */
+    private rememberProducedChild;
+    /**
+     * Records one child ID with its attempt and current logical reader.
+     *
+     * @param association Native child attempt that introduced the ID.
+     * @param childId Initial or backend-issued child ID.
+     * @param reader Current verified reader facts, if supplied.
+     */
+    private associateChildId;
+    /**
+     * Removes only IDs still associated with this retired child attempt.
+     *
+     * @param association Native child attempt after successful disposal.
+     */
+    private retireChild;
     /**
      * Checks a response-only successful child activation acknowledgement.
      *
@@ -117,8 +171,7 @@ export declare class DynamicUnaryForwarder implements UnaryForwarder {
      * @param wire Supplies the public subscription wire.
      * @param updates Receives relayed subscription updates.
      * @param signal Cancels update relay.
-     * @returns Completion after cancellation; rejects on unexpected child failure, possibly
-     * including bounded cleanup failure.
+     * @returns Completion after cancellation; rejects on unexpected child or bounded cleanup failure.
      */
     activateDefinition(wire: PublicSubscriptionWire, updates: SubscriptionUpdateSink, signal: AbortSignal): Promise<void>;
     /**
@@ -129,6 +182,12 @@ export declare class DynamicUnaryForwarder implements UnaryForwarder {
      * @returns Completion of child cleanup.
      */
     cancelDefinition(wire: PublicSubscriptionWire, signal: AbortSignal): Promise<void>;
+    /**
+     * Updates current reader facts for a retained definition and its native children.
+     *
+     * @param wire The admitted definition with current verified reader facts.
+     */
+    private rememberReader;
     /**
      * Resolves when the supplied signal aborts.
      *

package/dist/gateway/dynamic-unary-forwarder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dynamic-unary-forwarder.d.ts","sourceRoot":"","sources":["../../src/gateway/dynamic-unary-forwarder.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAMjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAEV,sBAAsB,EACtB,mBAAmB,EACnB,sBAAsB,EAEvB,MAAM,2BAA2B,CAAC;AAEnC;;;;GAIG;AACH,MAAM,WAAW,kBAAmB,SAAQ,cAAc,EAAE,mBAAmB;IAG7E;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAGlC;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAE7F;;OAEG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAEtC;;OAEG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAE1C;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;CAC7B;AAED;;;GAGG;AACH,qBAAa,qBAAsB,YAAW,cAAc;;IAQ1D;;;;OAIG;gBACS,OAAO,EAAE,mBAAmB;IAkCxC;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;IA4B3B;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;IAK9B;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB;IASnC;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3D;;;;;OAKG;IACH,OAAO,CAAC,OAAO,EAAE,UAAU,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC;IAM/E;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB;;;;;;;OAOG;IACH,mBAAmB,CACjB,OAAO,EAAE,sBAAsB,EAC/B,MAAM,EAAE,WAAW,EACnB,uBAAuB,CAAC,EAAE,MAAM,GAC/B,OAAO,CAAC,IAAI,CAAC;IAWhB;;;;;;OAMG;IACG,mBAAmB,CACvB,OAAO,EAAE,sBAAsB,EAC/B,uBAAuB,CAAC,EAAE,MAAM,GAC/B,OAAO,CAAC,IAAI,CAAC;IAWhB;;;;;;;;OAQG;IACH,kBAAkB,CAChB,IAAI,EAAE,sBAAsB,EAC5B,OAAO,EAAE,sBAAsB,EAC/B,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,IAAI,CAAC;IAIhB;;;;;;OAMG;IACH,gBAAgB,CAAC,IAAI,EAAE,sBAAsB,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlF;;;;;OAKG;IACH,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvD;;;;;OAKG;IACH,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS;IAI3D;;;;;;OAMG;IACH,MAAM,CAAC,eAAe,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,eAAe,GAAG,UAAU;CAiB7E"}
+{"version":3,"file":"dynamic-unary-forwarder.d.ts","sourceRoot":"","sources":["../../src/gateway/dynamic-unary-forwarder.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAMjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAM1C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAEV,sBAAsB,EACtB,mBAAmB,EACnB,sBAAsB,EAEvB,MAAM,2BAA2B,CAAC;AAEnC;;;;GAIG;AACH,MAAM,WAAW,kBAAmB,SAAQ,cAAc,EAAE,mBAAmB;IAG7E;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAGlC;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAE7F;;OAEG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAEtC;;OAEG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAE1C;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;CAC7B;AAWD;;;GAGG;AACH,qBAAa,qBAAsB,YAAW,cAAc;;IAkB1D;;;;OAIG;gBACS,OAAO,EAAE,mBAAmB;IAgCxC;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAavB;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IA2BpB;;;;;;;OAOG;YACW,YAAY;IAiB1B;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IAsBtB;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAWnB;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;IAY7B;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IAaxB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAWnB;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;IAK9B;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB;IASnC;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3D;;;;;OAKG;IACH,OAAO,CAAC,OAAO,EAAE,UAAU,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC;IAM/E;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQtB;;;;;;;OAOG;IACH,mBAAmB,CACjB,OAAO,EAAE,sBAAsB,EAC/B,MAAM,EAAE,WAAW,EACnB,uBAAuB,CAAC,EAAE,MAAM,GAC/B,OAAO,CAAC,IAAI,CAAC;IAYhB;;;;;;OAMG;IACG,mBAAmB,CACvB,OAAO,EAAE,sBAAsB,EAC/B,uBAAuB,CAAC,EAAE,MAAM,GAC/B,OAAO,CAAC,IAAI,CAAC;IAYhB;;;;;;;OAOG;IACH,kBAAkB,CAChB,IAAI,EAAE,sBAAsB,EAC5B,OAAO,EAAE,sBAAsB,EAC/B,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,IAAI,CAAC;IAKhB;;;;;;OAMG;IACH,gBAAgB,CAAC,IAAI,EAAE,sBAAsB,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAclF;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAStB;;;;;OAKG;IACH,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvD;;;;;OAKG;IACH,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS;IAI3D;;;;;;OAMG;IACH,MAAM,CAAC,eAAe,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,eAAe,GAAG,UAAU;CAsB7E"}