@api.global/typedsocket 6.3.0 → 7.1.0

package/readme.md

@@ -1,999 +1,465 @@
 # @api.global/typedsocket
 
-A TypeScript library for creating typed WebSocket connections with bi-directional communication support. Extends `@api.global/typedrequest` to bring type-safe request/response patterns to WebSocket connections.
+Typed request/response communication over WebSockets with one peer-scoped transport for JSON RPC and ordered `virtual-stream-v1` byte streams. TypedSocket 7 integrates TypedRequest 7 with SmartServe 5.1.1, enforces an exact package-major handshake, and binds every server operation to the physical peer and routing surface selected during upgrade.
 
 ## Issue Reporting and Security
 
 For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
 
-## Features
+## Install
 
-- 🔒 **Full Type Safety** - Leverages TypeScript for compile-time checking of all request/response payloads
-- 🔄 **Bi-directional Communication** - Both server and client can initiate requests
-- 🔌 **Auto-reconnect** - Client automatically reconnects on connection loss
-- 🏷️ **Policy-Gated Connection Tagging** - Default-deny client tags and protected server metadata
-- 🌐 **Browser Compatible** - Works in both Node.js and browser environments
-- 🚀 **SmartServe Integration** - Native support for SmartServe's WebSocket handling
-- **Ephemeral Binary Messages** - Bounded, acknowledged binary messages up to 4 MiB without JSON/base64 expansion
+```bash
+pnpm add @api.global/typedsocket @api.global/typedrequest @api.global/typedrequest-interfaces
+```
 
-## Install
+Server applications also need SmartServe:
 
 ```bash
-pnpm add @api.global/typedsocket
+pnpm add @push.rocks/smartserve
 ```
 
-## Usage
+TypedSocket 7 requires `@api.global/typedrequest` 7, `@api.global/typedrequest-interfaces` 7, and `@push.rocks/smartserve` 5.1.1 or newer within major 5. These package majors form one transport contract and must not be mixed with earlier router or stream APIs.
+
+## Version 7 transport model
 
-### Prerequisites
+Each physical WebSocket peer has one always-on TypedSocket transport:
 
-- TypeScript project setup
-- Basic understanding of async/await patterns
-- Familiarity with `@api.global/typedrequest` concepts
-- `@api.global/typedrequest` 5 and `@api.global/typedrequest-interfaces` 5
-- `@push.rocks/smartserve` 4.2.1 or newer within major 4 for server integrations
+- text frames carry bidirectional TypedRequest envelopes;
+- binary frames carry the same peer's `virtual-stream-v1` streams;
+- SmartServe fixes the peer's `routingSurface` and `transportOwner` during upgrade;
+- the client and server must complete the exact TypedSocket package-major handshake before application requests or streams are admitted;
+- client connection restoration runs after the handshake and before desired tags and the `connected` state are published.
 
-TypedSocket 6, SmartServe 4.2.1, and TypedRequest 5.2.1 share one `TypedRouter` contract. Do not
-mix older router contracts or bridge the mismatch with casts.
+There are no optional native-byte or native-message capability modes in version 7. The v6 `nativeBytes`, `native-byte-v1`, `native-message-v1`, binary-message channel, and capability-mode APIs are not part of the v7 public surface. There is also no `TypedSocket.fromSmartServe()` attachment shortcut: server composition must happen before SmartServe is constructed.
 
-### Define Your Request Interface
+## Define shared contracts
 
-First, define the typed request interface that both client and server will use:
+TypedSocket uses ordinary TypedRequest interfaces. VirtualStreams use the transport-neutral TypedRequest 7 types:
 
 ```typescript
-import * as typedrequestInterfaces from '@api.global/typedrequest-interfaces';
+import type {
+  ITypedRequest,
+  TVirtualStream,
+  implementsTR,
+} from '@api.global/typedrequest-interfaces';
 
-interface IGreetingRequest extends typedrequestInterfaces.implementsTR<
-  typedrequestInterfaces.ITypedRequest,
-  IGreetingRequest
-> {
+export interface IGreetRequest extends implementsTR<ITypedRequest, IGreetRequest> {
   method: 'greet';
+  request: { name: string };
+  response: { message: string };
+}
+
+export interface IUploadRequest extends implementsTR<ITypedRequest, IUploadRequest> {
+  method: 'upload';
   request: {
-    name: string;
+    stream: TVirtualStream<'send'>;
   };
   response: {
-    message: string;
+    storedBytes: number;
   };
 }
-```
-
-### Server Setup
 
-TypedSocket composes its private protocol handlers into the application router
-before that router is given to SmartServe:
-
-```typescript
-import { TypedSocket } from '@api.global/typedsocket';
-import * as typedrequest from '@api.global/typedrequest';
-import { SmartServe } from '@push.rocks/smartserve';
+export interface IDownloadRequest extends implementsTR<ITypedRequest, IDownloadRequest> {
+  method: 'download';
+  request: { objectId: string };
+  response: {
+    // Direction is local to the requester. The server handler sees 'send'.
+    stream: TVirtualStream<'receive'>;
+  };
+}
 
-// Create the router and add handlers
-const typedRouter = new typedrequest.TypedRouter();
+export interface IRestoreSessionRequest
+  extends implementsTR<ITypedRequest, IRestoreSessionRequest> {
+  method: 'restoreSession';
+  request: { token: string };
+  response: { restored: true };
+}
+```
 
-typedRouter.addTypedHandler<IGreetingRequest>(
-  new typedrequest.TypedHandler('greet', async (requestData) => {
-    return {
-      message: `Hello, ${requestData.name}! 👋`,
-    };
-  })
-);
+`TypedHandler` reverses stream directions at the handler boundary. An upload declared as requester-local `send` reaches the server handler as local `receive`; a download declared as requester-local `receive` is created by the handler as local `send`.
 
-const server = TypedSocket.createServer(typedRouter);
-const smartServe = new SmartServe({
-  port: 3000,
-  websocket: {
-    typedRouter,
-    transportOwner: server.webSocketTransportOwner,
-  },
-});
-server.attachSmartServe(smartServe);
-await smartServe.start();
-```
+## Server setup with SmartServe 5.1.1
 
-#### Integration with SmartServe
+Construction order is part of the transport contract:
 
-For SmartServe-based applications, compose the protocol router synchronously,
-attach the transport, and then start listening:
+1. Create and populate the application `TypedRouter`.
+2. Call `TypedSocket.createServer()`.
+3. Obtain the generated transport routing surface with `getServerRoutingSurface()`.
+4. Construct SmartServe with that routing surface and the exact `webSocketTransportOwner` object.
+5. Call `attachSmartServe()`.
+6. Start SmartServe.
 
 ```typescript
 import { TypedSocket } from '@api.global/typedsocket';
+import { TypedHandler, TypedRouter } from '@api.global/typedrequest';
 import { SmartServe } from '@push.rocks/smartserve';
-import * as typedrequest from '@api.global/typedrequest';
 
-const typedRouter = new typedrequest.TypedRouter();
+const applicationRouter = new TypedRouter();
 
-// Add handlers for client-to-server requests
-typedRouter.addTypedHandler<IGreetingRequest>(
-  new typedrequest.TypedHandler('greet', async (requestData) => {
-    return { message: `Hello, ${requestData.name}!` };
-  })
+applicationRouter.addTypedHandler(
+  new TypedHandler<IGreetRequest>('greet', async ({ name }) => ({
+    message: `Hello, ${name}!`,
+  })),
 );
 
-const typedSocket = TypedSocket.createServer(typedRouter);
+const typedSocket = TypedSocket.createServer(applicationRouter, {
+  onServerConnectionReady: (connection) => {
+    typedSocket.setServerTag(connection, 'application-client');
+    return undefined;
+  },
+});
 
-// Create SmartServe with the composed application router
 const smartServe = new SmartServe({
   port: 3000,
   websocket: {
-    typedRouter,
+    typedRouter: typedSocket.getServerRoutingSurface(applicationRouter),
     transportOwner: typedSocket.webSocketTransportOwner,
-    onConnectionOpen: (peer) => {
-      // Server metadata is protected from client overwrite/removal.
-      typedSocket.setServerTag(peer, 'client');
-    }
-  }
+  },
 });
 
 typedSocket.attachSmartServe(smartServe);
 await smartServe.start();
-
-// Push notifications to tagged clients
-const clients = await typedSocket.findAllTargetConnectionsByTag('client');
-for (const client of clients) {
-  const request = typedSocket.createTypedRequest<IGreetingRequest>('greet', client);
-  await request.fire({ name: 'server' });
-}
 ```
 
-> **Note:** When using SmartServe, the WebSocket transport is managed by SmartServe. TypedSocket acts as a convenience layer for finding connections and sending server-initiated requests.
+Do not pass `applicationRouter` directly to `websocket.typedRouter`. `createServer()` creates a distinct routing surface that composes the private TypedSocket protocol before the application router. SmartServe must bind that returned surface and the exact transport-owner identity to the peer.
+
+`onServerConnectionReady(connection)` may synchronously assign protected tags or
+other connection-local state after the exact handshake response has been
+settled. It must return `undefined`; returning any other value, including a
+Promise or custom thenable, or throwing closes the connection before readiness
+is published.
+
+### Multiple isolated routing surfaces
 
-Multiple isolated application routers can share one transport without becoming
-reachable from each other:
+One TypedSocket can compose multiple application routers without making them reachable from one another. Resolve the corresponding generated surface during upgrade:
 
 ```typescript
+const publicRouter = new TypedRouter();
+const adminRouter = new TypedRouter();
 const typedSocket = TypedSocket.createServer([publicRouter, adminRouter]);
+
 const smartServe = new SmartServe({
   port: 3000,
   authorityValidation: 'strict',
   websocket: {
     resolveTypedRouter: (context) => {
-      if (context.url.hostname === 'example.com') return publicRouter;
-      if (context.url.hostname === 'admin.example.com') return adminRouter;
+      if (context.url.hostname === 'api.example.com') {
+        return typedSocket.getServerRoutingSurface(publicRouter);
+      }
+      if (context.url.hostname === 'admin.example.com') {
+        return typedSocket.getServerRoutingSurface(adminRouter);
+      }
       return undefined;
     },
     transportOwner: typedSocket.webSocketTransportOwner,
   },
 });
+
 typedSocket.attachSmartServe(smartServe);
 await smartServe.start();
 ```
 
-TypedSocket adds a private, one-way fallback router containing its protocol
-handlers to every application router. Duplicate protocol method names are
-rejected during composition and on later router mutations; `stop()` releases
-the owned fallback edges. `fromSmartServe()` remains available as a JSON-only
-attachment helper that delegates to `createServer()` and `attachSmartServe()`.
-
-Connection lookup via `findTargetConnection()`/`findAllTargetConnections()`
-spans every peer attached to this server's routing surfaces. Deprecated
-implicit single-peer targeting is narrower: multi-router servers throw
-`'TypedSocket multi-router servers require an explicit targetConnection'`
-before any lookup, and single-router servers only consider peers bound to that
-router's surface. Multi-surface servers should tag or filter peers by surface
-and pass an explicit target to `createTypedRequest()`.
-
-### Native Byte Streams
-
-TypedSocket 6 negotiates `native-byte-v1` on each physical WebSocket before
-restoring tags or publishing the client as connected. Native bytes require the
-SmartServe 4.2.1 raw-frame owner to be selected when SmartServe is constructed. The
-server construction order is strict:
-
-1. Create the application `TypedRouter` instances.
-2. Call `TypedSocket.createServer(routerOrRouters, options?)`.
-3. Construct `SmartServe` with the composed router and
-   `transportOwner: typedSocket.webSocketTransportOwner`.
-4. Call `typedSocket.attachSmartServe(smartServe)`.
-5. Start SmartServe.
-
-`fromSmartServe()` supports JSON-only attachment to an existing server. It cannot add a
-raw-frame owner to a SmartServe instance that has already selected transports,
-so native negotiation succeeds only for peers already bound to the exact
-`webSocketTransportOwner` object.
-
-Client and server options accept `nativeByteCapabilityMode`:
-
-- `optional` is the default. JSON RPC remains available if native negotiation is unavailable.
-- `required` fails client startup when negotiation does not return `native-byte-v1`. On servers it closes peers that do not negotiate the capability.
-- `disabled` advertises no native capability and keeps JSON RPC available.
-
-### Ephemeral Binary Message Channels
-
-TypedSocket separately negotiates `native-message-v1` with
-`__typedsocket_negotiateNativeMessages` after the existing primary capability
-negotiation. Client and server options accept an independent
-`nativeMessageCapabilityMode` (`disabled`, `optional`, or `required`). Optional
-clients tolerate servers that do not know the new private method. Disabled
-clients still call it and advertise an empty capability list when it exists.
-Required servers close peers that do not complete this negotiation within 10
-seconds.
-
-Message channels reuse the one `NativeByteManager`, SmartServe raw-frame owner,
-raw queue, control-first scheduler, exact outbound settlement identity, and
-aggregate connection/server accounting. They use a distinct `TSM1` codec and
-do not alter `native-byte-v1` frame encoding or byte-stream protocol semantics.
-
-The preferred server API is `createBinaryMessageChannel()`. It synchronously
-binds application authorization and returns a receive grant with an ordinary
-JSON descriptor. Applications explicitly carry that descriptor in their own
-typed DTO; TypedRequest and `VirtualStream` do not serialize it automatically.
+SmartServe rejects an upgrade when `resolveTypedRouter()` returns `undefined`. `typedRouter` and `resolveTypedRouter` are mutually exclusive, as are `transportOwner` and `resolveTransportOwner`.
 
-```typescript
-import {
-  TypedSocket,
-  type INativeMessageDescriptor,
-} from '@api.global/typedsocket';
-
-interface ICameraAuthorization {
-  principalId: string;
-  credentialRevision: string;
-  configRevision: string;
-  bindingRevision: string;
-}
+## Client setup
 
-declare const cameraAuthorization: ICameraAuthorization;
-declare function isCameraAuthorizationCurrent(
-  authorizationArg: ICameraAuthorization,
-  operationArg: 'open' | 'message' | 'close' | 'reject',
-): boolean | Promise<boolean>;
-
-const server = TypedSocket.createServer(typedRouter, {
-  nativeMessageCapabilityMode: 'required',
-  nativeMessageAuthorizationAdapter: {
-    bind: (authorizationArg, contextArg) => {
-      const authorization = authorizationArg as ICameraAuthorization;
-      return {
-        ...authorization,
-        revalidate: async (revalidationArg) =>
-          revalidationArg.connection.side === 'server'
-          && revalidationArg.connection.peer === contextArg.target
-          && await isCameraAuthorizationCurrent(
-            authorization,
-            revalidationArg.operation,
-          ),
-      };
-    },
-  },
-});
+The client router handles server-initiated requests. `createClient()` resolves only after the package-major handshake, optional connection restoration, and desired-tag reconciliation succeed.
 
-// Inside a server TypedHandler:
-const target = server.getServerConnectionForRequest(typedToolsArg);
-const grant = server.createBinaryMessageChannel({
-  direction: 'receive',
-  target,
-  authorization: cameraAuthorization,
-  maxMessageBytes: 4 * 1024 * 1024,
-});
-
-// Return grant.descriptor in an application-defined response DTO.
-const descriptor: INativeMessageDescriptor = grant.descriptor;
-
-void (async () => {
-  while (true) {
-    const message = await grant.receiver.receive();
-    if (message === undefined) break;
-    // Process one complete logical message.
-  }
-  await grant.receiver.closed;
-})().catch((errorArg) => grant.receiver.reject(errorArg));
-
-// On the descriptor recipient:
-const sender = await client.nativeBytes.messages.openSender(descriptor);
-await sender.send(jpegBytes);
-await sender.close();
-await sender.closed;
-```
+```typescript
+import { TypedHandler, TypedRouter } from '@api.global/typedrequest';
+import { TypedSocket } from '@api.global/typedsocket';
 
-`INativeMessageReceiver` deliberately exposes only `receive()`, `closed`, and
-`reject()`. It has no `ReadableStream`. A complete message occupies one
-application slot, and `MESSAGE_ACK` is queued only when `receive()` dequeues it.
-`send()` snapshots its `Uint8Array` at admission and remains pending until the
-exact logical sequence is acknowledged. Sends serialize without fragment
-interleaving; `close()` queues after admitted sends and waits for `CLOSE_ACK`.
-Empty messages are valid.
-
-The receive grant also exposes `opened`, `revoke(reason?)`, and `dispose()`.
-`opened` settles when the peer successfully opens the channel. Use `revoke()`
-to reject an advertised grant, and use `dispose()` to release a descriptor that
-was never published or opened.
-
-Descriptors are single-use, expire after 10 seconds, and are bound to one exact
-physical peer or client generation. They are recreated after reconnect. The
-protocol has no durability claim, content hash, FIN, reconnect resume, or
-automatic business idempotency. `RESET` normally closes only its channel;
-malformed binary framing closes the physical connection because the routing
-identity cannot be trusted.
-
-| Message-channel limit | Exported constant | Value |
-|---|---|---:|
-| Complete raw frame | `NATIVE_MESSAGE_MAX_FRAME_BYTES` | 32 KiB |
-| Fragment payload | `NATIVE_MESSAGE_MAX_FRAGMENT_PAYLOAD_BYTES` | 32,720 bytes |
-| Logical message package ceiling/default | `NATIVE_MESSAGE_MAX_LOGICAL_MESSAGE_BYTES` / `NATIVE_MESSAGE_DEFAULT_MAX_LOGICAL_MESSAGE_BYTES` | 4 MiB |
-| Pending messages / bytes per channel | `NATIVE_MESSAGE_MAX_PENDING_MESSAGES_PER_CHANNEL` / `NATIVE_MESSAGE_MAX_PENDING_BYTES_PER_CHANNEL` | 8 / 8 MiB |
-| Message channels per connection | `NATIVE_MESSAGE_MAX_CHANNELS_PER_CONNECTION` | 32, also subject to the shared 32 stream+channel slots |
-| Closed-channel tombstones | `NATIVE_MESSAGE_MAX_TOMBSTONES_PER_CONNECTION` / `NATIVE_MESSAGE_TOMBSTONE_RETENTION_MS` | 64 / 60 seconds |
-| Negotiation and OPEN deadlines | `NATIVE_MESSAGE_NEGOTIATION_TIMEOUT_MS` / `NATIVE_MESSAGE_OPEN_TIMEOUT_MS` | 10 seconds |
-| Fragment, acknowledgement, receive, close, and frame progress | `NATIVE_MESSAGE_PROGRESS_TIMEOUT_MS` | 30 seconds |
-
-Pending outbound messages, inbound reassembly/completed slots, native-byte
-stream queues, the raw queue, and server-retained frame/authentication state are
-charged to shared bounded connection and server budgets. Message authorization
-reuses the native transport's principal, three authority revisions, callback
-deadline, and per-peer/principal/server retained-revalidation caps. Revalidation
-callbacks receive operation and authority metadata but never message payloads or
-capability secrets. `nativeBytes.messages.getCapability()` and `getStats()`
-likewise expose only bounded counters and status.
-
-#### Preferred VirtualStream Facade
-
-For bounded byte payloads, application code uses
-`TypedSocket.createVirtualStream()` and passes the returned
-`VirtualStream<Uint8Array>` facade in its typed DTO. TypedRequest transfers the
-opaque transport descriptor automatically. The receiving application drains
-and durably commits the stream before confirmation; the sender sees only the
-reversed `send` facade and its durable completion receipt.
+const clientRouter = new TypedRouter();
 
-```typescript
-import * as typedrequest from '@api.global/typedrequest';
-import * as typedrequestInterfaces from '@api.global/typedrequest-interfaces';
-import { SmartServe } from '@push.rocks/smartserve';
-import { createSha256Hasher } from '@push.rocks/smarthash/web';
-import {
-  TypedSocket,
-  type TNativeByteAuthorityOperation,
-} from '@api.global/typedsocket';
-
-interface IUploadRequest extends typedrequestInterfaces.implementsTR<
-  typedrequestInterfaces.ITypedRequest,
-  IUploadRequest
-> {
-  method: 'uploadBytes';
-  request: {
-    uploadId: string;
-    byteLength: number;
-    sha256: string;
-    contentType: string;
-  };
-  response: {
-    stream: typedrequestInterfaces.INativeByteVirtualStream<Uint8Array>;
-  };
-}
+clientRouter.addTypedHandler(
+  new TypedHandler<IGreetRequest>('greet', async ({ name }) => ({
+    message: `Hello from the client, ${name}!`,
+  })),
+);
 
-interface IUploadAuthorization {
-  uploadId: string;
-  principalId: string;
-  credentialRevision: string;
-  configRevision: string;
-  bindingRevision: string;
-}
+const client = await TypedSocket.createClient(
+  clientRouter,
+  'https://api.example.com',
+  {
+    autoReconnect: true,
+    maxRetries: 20,
+    initialBackoffMs: 1_000,
+    maxBackoffMs: 30_000,
+  },
+);
 
-interface IDurableUpload {
-  writable: WritableStream<Uint8Array>;
-  commit(): Promise<void>;
-  abort(reasonArg: unknown): Promise<void>;
-}
+const response = await client
+  .createTypedRequest<IGreetRequest>('greet')
+  .fire({ name: 'Ada' });
+```
 
-// These hooks belong to the application and its durable storage layer.
-declare function bindUploadAuthorization(uploadIdArg: string): IUploadAuthorization;
-declare function revalidateUpload(
-  authorizationArg: IUploadAuthorization,
-  manifestArg: typedrequestInterfaces.INativeByteStreamManifest,
-  operationArg: TNativeByteAuthorityOperation,
-): Promise<boolean>;
-declare function openDurableUpload(uploadIdArg: string): Promise<IDurableUpload>;
-
-function parseUploadAuthorization(valueArg: unknown): IUploadAuthorization {
-  if (typeof valueArg !== 'object' || valueArg === null) {
-    throw new Error('Upload authorization is invalid');
-  }
-  const uploadId = Reflect.get(valueArg, 'uploadId');
-  const principalId = Reflect.get(valueArg, 'principalId');
-  const credentialRevision = Reflect.get(valueArg, 'credentialRevision');
-  const configRevision = Reflect.get(valueArg, 'configRevision');
-  const bindingRevision = Reflect.get(valueArg, 'bindingRevision');
-  if (
-    typeof uploadId !== 'string'
-    || typeof principalId !== 'string'
-    || typeof credentialRevision !== 'string'
-    || typeof configRevision !== 'string'
-    || typeof bindingRevision !== 'string'
-  ) {
-    throw new Error('Upload authorization is invalid');
-  }
-  return { uploadId, principalId, credentialRevision, configRevision, bindingRevision };
-}
+Use `TypedSocket.useWindowLocationOriginUrl()` for same-origin browser connections. Remote connections must use `https:` or `wss:`. Plain `http:` and `ws:` are restricted to loopback hosts. URLs containing credentials or fragments are rejected, and lifecycle logs redact paths and query strings.
 
-const serverRouter = new typedrequest.TypedRouter();
-let typedSocketServer!: TypedSocket;
-
-serverRouter.addTypedHandler(new typedrequest.TypedHandler<IUploadRequest>(
-  'uploadBytes',
-  async (requestArg, metaArg) => {
-    const authorization = bindUploadAuthorization(requestArg.uploadId);
-    const connection = typedSocketServer.getServerConnectionForRequest(metaArg);
-    const stream = typedSocketServer.createVirtualStream({
-      protocol: 'native-byte-v1',
-      direction: 'receive',
-      target: connection,
-      byteLength: requestArg.byteLength,
-      sha256: requestArg.sha256,
-      contentType: requestArg.contentType,
-      authorization,
-    });
+### Restoring authenticated connection state
 
-    void (async () => {
-      let durableUpload: IDurableUpload | undefined;
-      try {
-        durableUpload = await openDurableUpload(authorization.uploadId);
-        await stream.writeToWebstream(durableUpload.writable);
-        await durableUpload.commit();
-        await stream.confirmDurable();
-      } catch (errorArg) {
-        await durableUpload?.abort(errorArg).catch(() => {});
-        await stream.reject(errorArg).catch(() => {});
-      }
-    })();
+`restoreConnection` runs after the version handshake and before tags or readiness. Its request factory is deadline-bound and becomes invalid when the callback finishes:
 
-    return { stream };
-  },
-));
+```typescript
+declare const serverUrl: string;
+declare const currentSessionToken: string;
 
-typedSocketServer = TypedSocket.createServer(serverRouter, {
-  nativeByteCapabilityMode: 'required',
-  nativeByteAuthorizationAdapter: {
-    bind: (authorizationArg, contextArg) => {
-      const authorization = parseUploadAuthorization(authorizationArg);
-      return {
-        principalId: authorization.principalId,
-        credentialRevision: authorization.credentialRevision,
-        configRevision: authorization.configRevision,
-        bindingRevision: authorization.bindingRevision,
-        revalidate: async (revalidationArg) =>
-          revalidationArg.connection.side === 'server'
-          && revalidationArg.connection.peer === contextArg.target
-          && await revalidateUpload(
-            authorization,
-            contextArg.manifest,
-            revalidationArg.operation,
-          ),
-      };
-    },
+const client = await TypedSocket.createClient(clientRouter, serverUrl, {
+  restoreConnection: async ({ createTypedRequest, abortSignal }) => {
+    if (abortSignal.aborted) return;
+    await createTypedRequest<IRestoreSessionRequest>('restoreSession').fire(
+      { token: currentSessionToken },
+    );
   },
 });
+```
 
-const smartServe = new SmartServe({
-  port: 3000,
-  websocket: {
-    typedRouter: serverRouter,
-    transportOwner: typedSocketServer.webSocketTransportOwner,
-  },
+A `TypedSocketHandshakeError` is terminal for that client startup. A package-major mismatch, malformed handshake envelope, handshake timeout, or binary frame before handshake completion closes the connection instead of falling back to a reduced transport.
+
+## Explicit server targets
+
+Client requests target their server implicitly because the client owns one current physical connection. Server-initiated requests always require an explicit `ISmartServeConnectionWrapper`:
+
+```typescript
+const target = await typedSocket.findTargetConnectionByTag('account', {
+  accountId: 'account-123',
 });
-typedSocketServer.attachSmartServe(smartServe);
-await smartServe.start();
 
-const client = await TypedSocket.createClient(
-  new typedrequest.TypedRouter(),
-  'http://127.0.0.1:3000',
-  { nativeByteCapabilityMode: 'required', autoReconnect: false },
-);
-try {
-  const payload = new TextEncoder().encode('authorized payload');
-  const sha256 = `sha256:${createSha256Hasher().update(payload).digest()}`;
-  const response = await client.createTypedRequest<IUploadRequest>('uploadBytes').fire({
-    uploadId: 'upload-1',
-    byteLength: payload.byteLength,
-    sha256,
-    contentType: 'text/plain',
-  });
-  await response.stream.readFromWebstream(new ReadableStream<Uint8Array>({
-    start: (controllerArg) => {
-      controllerArg.enqueue(payload);
-      controllerArg.close();
-    },
-  }));
-  const receipt = await response.stream.completion;
-  if (receipt.sha256 !== sha256 || !receipt.durable) {
-    throw new Error('Upload receipt did not match the authorized manifest');
-  }
-} finally {
-  await client.stop();
-  await typedSocketServer.stop();
-  await smartServe.stop();
+if (target) {
+  const response = await typedSocket
+    .createTypedRequest<IGreetRequest>('greet', target, {
+      timeoutMs: 15_000,
+    })
+    .fire({ name: 'server push' });
 }
 ```
 
-`nativeByteAuthorizationAdapter.bind()` is synchronous so descriptor publication
-cannot race authority capture. Its `revalidate()` callback may be asynchronous;
-OPEN, DATA, FIN, and durable confirmation are followed by an exact
-peer/generation ownership check. Rejection attempts one final best-effort
-revalidation before local cleanup and RESET.
-
-#### Advanced Transport API
-
-`nativeBytes.createReceiveGrant()`, `nativeBytes.openSender()`, and opaque native
-descriptors are protocol-integration APIs. Normal application DTOs should carry
-the `VirtualStream` facade shown above, not a descriptor. Transport integrations
-that cannot use the facade must still provide a non-negative safe-integer
-`byteLength`, exact `sha256:<64 lowercase hex>`, and a normalized media-type
-`contentType` of at most 255 UTF-8 bytes (`NATIVE_BYTE_MAX_CONTENT_TYPE_BYTES`).
-They must also provide all three
-nonempty authority revisions and mandatory `revalidate(context)`.
-
-The application must drain the stream, commit it durably, and only then call
-`confirmDurable()`. The transport can enforce validated FIN, complete drain, and
-explicit confirmation, but the application owns the storage durability claim.
-`FIN_ACK` is not emitted before confirmation. The sender's `close()` and
-`completion` remain pending until then.
-Accepted nonempty DATA calls are copied and admitted against the authorized
-length and queue limits before asynchronous execution, so caller mutation,
-large backing buffers, and non-awaited calls cannot escape transport accounting.
-
-Native byte transport deliberately provides no business idempotency, reconnect
-resume, HTTP fallback, or legacy-byte fallback. A disconnect or generation
-change fails all affected grants and streams. Capabilities and stream IDs are
-one-use on one exact physical peer.
-
-#### Legacy VirtualStream Removal
-
-TypedSocket 6 unconditionally rejects generic `##VirtualStream##` descriptors and
-control requests. There is no client option, server option, fallback, or migration
-opt-in. Byte DTOs must use the exact native facade returned by
-`TypedSocket.createVirtualStream()`.
-
-#### Native Limits
-
-| Limit | Exported constant | Value |
-|---|---|---:|
-| Complete binary message | `NATIVE_BYTE_MAX_FRAME_BYTES` | 32 KiB |
-| DATA payload per message | `NATIVE_BYTE_MAX_DATA_PAYLOAD_BYTES` | 32,720 bytes |
-| Maximum stream length | `NATIVE_BYTE_MAX_STREAM_BYTES` | 140,531,329,925,120 bytes (127.8125 TiB) |
-| Default receive window | `NATIVE_BYTE_DEFAULT_INITIAL_WINDOW_BYTES` | 256 KiB |
-| Maximum receive window / queued payload per stream | `NATIVE_BYTE_MAX_WINDOW_BYTES` / `NATIVE_BYTE_MAX_QUEUED_PAYLOAD_BYTES_PER_STREAM` | 1 MiB |
-| Queued payload per connection | `NATIVE_BYTE_MAX_QUEUED_PAYLOAD_BYTES_PER_CONNECTION` | 8 MiB |
-| Queued receive chunks per stream | `NATIVE_BYTE_MAX_RECEIVE_QUEUE_CHUNKS` | 4,096 |
-| Native-byte grants/streams plus native-message grants/channels per connection | `NATIVE_BYTE_MAX_STREAMS_PER_CONNECTION` | 32 shared slots |
-| Pending admitted DATA operations per connection | `NATIVE_BYTE_MAX_PENDING_DATA_OPERATIONS_PER_CONNECTION` | 64 |
-| Raw inbound queue | `NATIVE_BYTE_MAX_RAW_QUEUE_FRAMES` / `NATIVE_BYTE_MAX_RAW_QUEUE_BYTES` | 64 frames / 2 MiB |
-| Grant and OPEN timeout | `NATIVE_BYTE_GRANT_OPEN_TIMEOUT_MS` | 10 seconds |
-| Progress, ACK, frame settlement, FIN_ACK, durable confirmation | `NATIVE_BYTE_PROGRESS_TIMEOUT_MS` | 30 seconds |
-| Closed-stream tombstones | `NATIVE_BYTE_MAX_TOMBSTONES` / `NATIVE_BYTE_TOMBSTONE_RETENTION_MS` | 64, oldest-first, 60 seconds |
-| Principal and each authority revision | `NATIVE_BYTE_MAX_PRINCIPAL_ID_BYTES` / `NATIVE_BYTE_MAX_AUTHORITY_REVISION_BYTES` | 256 UTF-8 bytes |
-| Retained revalidation callbacks | `NATIVE_BYTE_MAX_REVALIDATIONS_PER_PEER` / `_PER_PRINCIPAL` / `_PER_SERVER` | 4 per peer / 16 per principal / 128 per server |
-| Server connections / native-byte and native-message endpoints | `NATIVE_BYTE_MAX_CONNECTIONS_PER_SERVER` / `NATIVE_BYTE_MAX_STREAMS_PER_SERVER` | 1,024 / 1,024 shared slots |
-| Server retained bytes / receive reservations | `NATIVE_BYTE_MAX_RETAINED_BYTES_PER_SERVER` | 64 MiB / 64 MiB |
-
-SmartServe owner sends prioritize control frames over DATA and pull one binary
-frame per requested turn. Browser clients likewise send one binary frame per
-macrotask, allowing direct JSON text traffic to run before the next binary turn.
-Server frame accounting remains retained after stream or connection cleanup
-until SmartServe settles the exact frame object returned by `pullBinaryFrame()`;
-late, cloned, or duplicate callbacks cannot settle newer work. Tombstone
-admission evicts oldest entries first and closes the connection if the fixed
-retained-byte budget still cannot hold the required replay fence.
-`getStats()` exposes connection/negotiation status, counts, and byte totals;
-descriptors, capability tokens, digests, and payloads are not included.
-
-### Client Setup
-
-Connect to the WebSocket server from a client:
+Inside a server handler, bind follow-up work to the request's exact trusted peer:
 
 ```typescript
-import { TypedSocket } from '@api.global/typedsocket';
-import * as typedrequest from '@api.global/typedrequest';
-
-// Create a router for handling server-initiated requests (if needed)
-const clientRouter = new typedrequest.TypedRouter();
-
-// Connect to the server
-const client = await TypedSocket.createClient(
-  clientRouter,
-  'http://localhost:3000'
+applicationRouter.addTypedHandler(
+  new TypedHandler<IGreetRequest>('greet', async ({ name }, tools) => {
+    const target = typedSocket.getServerConnectionForRequest(tools);
+    typedSocket.setServerTag(target, 'authenticated', { subject: 'user-123' });
+    return { message: `Hello, ${name}!` };
+  }),
 );
 ```
 
-Remote connections must use `https:` or `wss:`. Plain `http:` and `ws:` are
-accepted only for loopback hosts. Credentials and URL fragments are rejected;
-connection logs include only the protocol and authority, never paths or queries.
+`findTargetConnection()`, `findAllTargetConnections()`, and their tag variants return only live peers attached to this TypedSocket's generated routing surfaces. There is no implicit single-peer server fallback in v7.
 
-Client options can lower, but never raise, package ceilings for text-frame bytes,
-queued text frames/bytes, concurrent handlers, retained callbacks, pending
-requests, outbound WebSocket buffering, request timeouts, and connection
-restoration timeouts. `restoreConnection(context)` runs after capability
-negotiation and before desired tags are reconciled or `connected` is published.
-Its `context.createTypedRequest<T>(method)` uses the new physical connection and
-inherits the restoration abort signal and remaining deadline. The factory is
-invalidated when restoration succeeds, fails, times out, or is aborted, so it
-must not be retained for later application traffic.
+## VirtualStreams
+
+TypedSocket 7 supplies TypedRequest 7's `IVirtualStreamTransport` for each handshake-ready physical peer. TypedRequest serializes only the JSON-compatible descriptor in the parent envelope; ordered `Uint8Array` chunks travel as bounded binary frames on that exact peer.
+
+All stream facades expose `protocol`, `direction`, `streamId`, optional `contentType` and `integrity`, `opened`, `completion`, `closed`, and `abort()`. Senders add `send()`, `writable`, and `close()`. Receivers add `receive()`, `readable`, `accept()`, and `reject()`.
+
+`receive()` returns one complete logical chunk at a time and `undefined` at graceful EOF. The receiver must call `accept()` after draining EOF. `completion` resolves with the shared acceptance receipt; abnormal termination rejects it. Direct `receive()` and `readable` consumption are mutually exclusive.
+
+### Client-created streams with manager registrations
+
+Application-level client streams use the advanced manager registration API, then bind the registration to TypedRequest's public facade:
 
 ```typescript
-import * as typedrequestInterfaces from '@api.global/typedrequest-interfaces';
+import { VirtualStream } from '@api.global/typedrequest';
 
-interface IRestoreSessionRequest extends typedrequestInterfaces.implementsTR<
-  typedrequestInterfaces.ITypedRequest,
-  IRestoreSessionRequest
-> {
-  method: 'restoreSession';
-  request: { token: string; connectionId: string };
-  response: { restored: true };
+const transport = client.virtualStreams.getClientTransport();
+if (!transport) {
+  throw new Error('TypedSocket client transport is not connected');
 }
 
-const client = await TypedSocket.createClient(clientRouter, serverUrl, {
-  autoReconnect: true,
-  restoreConnection: async ({
-    connectionId,
-    abortSignal,
-    deadline,
-    createTypedRequest,
-  }) => {
-    if (abortSignal.aborted || Date.now() >= deadline) {
-      throw new Error('Connection restoration expired');
-    }
-    await createTypedRequest<IRestoreSessionRequest>('restoreSession').fire({
-      token: sessionToken,
-      connectionId,
-    });
-  },
+const registration = client.virtualStreams.createRegistration({
+  creatorDirection: 'send',
+  contentType: 'application/octet-stream',
 });
-```
 
-| Client limit | Exported constant | Package ceiling |
-|---|---|---:|
-| Complete text frame | `TYPEDSOCKET_MAX_TEXT_FRAME_BYTES` | 16 MiB |
-| Queued text frames / bytes | `TYPEDSOCKET_MAX_QUEUED_TEXT_FRAMES` / `TYPEDSOCKET_MAX_QUEUED_TEXT_BYTES` | 64 / 32 MiB |
-| Concurrent handlers / retained callbacks | `TYPEDSOCKET_MAX_CONCURRENT_CLIENT_HANDLERS` / `TYPEDSOCKET_MAX_RETAINED_CLIENT_CALLBACKS` | 16 / 64 |
-| Pending client requests | `TYPEDSOCKET_MAX_PENDING_CLIENT_REQUESTS` | 1,024 |
-| Outbound WebSocket buffered bytes | `TYPEDSOCKET_MAX_OUTBOUND_BUFFERED_BYTES` | 32 MiB |
-| Method name / correlation ID | `TYPEDSOCKET_MAX_METHOD_NAME_BYTES` / `TYPEDSOCKET_MAX_CORRELATION_ID_BYTES` | 256 UTF-8 bytes each |
-| Request timeout | `TYPEDSOCKET_MAX_REQUEST_TIMEOUT_MS` | 5 minutes |
-| Connection restoration timeout | `TYPEDSOCKET_MAX_CONNECTION_RESTORE_TIMEOUT_MS` | 10 seconds |
-| Reconnect attempts | `TYPEDSOCKET_MAX_RECONNECT_RETRIES` | 100 |
-| Initial / maximum reconnect backoff | `TYPEDSOCKET_MAX_RECONNECT_BACKOFF_MS` | 60 seconds |
-
-`maxRetries` is a non-negative safe integer no greater than 100.
-`initialBackoffMs` and `maxBackoffMs` are positive safe integers no greater
-than 60,000, and the initial value cannot exceed the maximum.
-
-Every ceiling in this document is exported as a named constant from the package
-root, so consumers can compare against the canonical value instead of
-hardcoding numbers. The limits philosophy is uniform and deliberate:
-configuration may lower a ceiling, but nothing may raise one — there is no
-unsafe override option. When a legitimate use case outgrows a ceiling, the
-constant is raised in a reviewed package release, not by per-deployment
-configuration.
-
-#### Abortable Startup
-
-Pass an `AbortSignal` when startup or reconnect attempts must be cancellable. Aborting stops the in-flight WebSocket and prevents queued reconnect attempts from continuing.
+const stream = VirtualStream.fromRegistration({
+  transport,
+  registration,
+});
 
-```typescript
-const abortController = new AbortController();
+const request = client.createTypedRequest<IUploadRequest>('upload');
+const responsePromise = request.fire({ stream });
 
-const clientPromise = TypedSocket.createClient(
-  clientRouter,
-  'http://localhost:3000',
-  {
-    abortSignal: abortController.signal,
-    initialBackoffMs: 1000,
-    maxRetries: 10,
-  }
-);
+await stream.opened;
+await stream.send(new Uint8Array([1, 2, 3]));
+await stream.close();
 
-// Later, if the connection attempt should no longer continue:
-abortController.abort();
-
-try {
-  const client = await clientPromise;
-} catch (error) {
-  // Startup was aborted before a stable connection was established.
-}
+const response = await responsePromise;
 ```
 
-#### Using Window Location (Browser)
+Client registrations do not take a peer target: the manager binds them to the current handshake-ready client generation. Registration is synchronous and silent. Its descriptor capability expires if it is not consumed, and TypedRequest owns disposal after the facade is created. Do not hand-build descriptors or reuse them across connections.
 
-In browser environments, you can automatically use the current page's origin:
+The matching server handler receives a requester-local `send` stream as local `receive`:
 
 ```typescript
-const client = await TypedSocket.createClient(
-  clientRouter,
-  TypedSocket.useWindowLocationOriginUrl()
+applicationRouter.addTypedHandler(
+  new TypedHandler<IUploadRequest>('upload', async ({ stream }) => {
+    let storedBytes = 0;
+    while (true) {
+      const chunk = await stream.receive();
+      if (chunk === undefined) break;
+      storedBytes += chunk.byteLength;
+    }
+    await stream.accept();
+    return { storedBytes };
+  }),
 );
 ```
 
-### Sending Requests
+### Server-created streams and the authorization facade
 
-#### Client to Server
+Server application code should create streams through `TypedSocket.createVirtualStream()`. This facade requires an exact attached target and a configured `virtualStreamAuthorizationAdapter`; it synchronously binds application authorization before publishing a descriptor.
 
 ```typescript
-const request = client.createTypedRequest<IGreetingRequest>('greet');
-const response = await request.fire({
-  name: 'World',
-});
-
-console.log(response.message); // "Hello, World! 👋"
-```
+interface IStreamAuthorization {
+  subject: string;
+  objectId: string;
+  revision: string;
+}
 
-#### Server to Client
+declare function isStreamAuthorityCurrent(
+  authority: IStreamAuthorization,
+  operation: 'open' | 'chunk' | 'accept' | 'reject',
+): Promise<boolean>;
 
-The server can also initiate requests to connected clients. Always pass the
-target connection explicitly:
+const typedSocket = TypedSocket.createServer(applicationRouter, {
+  virtualStreamAuthorizationAdapter: {
+    bind: (authorization, context) => {
+      const authority = authorization as IStreamAuthorization;
+      if (!authority.subject || !authority.objectId || !authority.revision) {
+        throw new Error('Invalid stream authorization');
+      }
+      const target = context.target;
 
-```typescript
-const connection = await server.findTargetConnection(async (conn) => {
-  // Your filter logic here
-  return true;
+      return {
+        revalidate: async ({ operation, connection, abortSignal }) => {
+          if (
+            abortSignal.aborted
+            || connection.side !== 'server'
+            || connection.peer !== target
+          ) return false;
+          return await isStreamAuthorityCurrent(authority, operation);
+        },
+      };
+    },
+  },
 });
-const targetedRequest = server.createTypedRequest<IGreetingRequest>('greet', connection);
-const response = await targetedRequest.fire({ name: 'Client' });
 ```
 
-> **Deprecated:** omitting the target on a server-side `createTypedRequest()`
-> auto-selects the connection only while exactly one client is attached, and
-> throws as soon as a second client connects. It also silently disables
-> native-byte transport for that request, because no peer was known when the
-> request object was created. Each implicit resolution emits an
-> `implicitTargetingUsed` diagnostic (once per request object); the implicit
-> path will be removed in the next major version.
-
-#### Request Deadlines and Cancellation
-
-TypedSocket forwards both configured request cancellation and per-`fire()` deadlines to its client
-and SmartServe server transports. The first timeout or abort to occur cancels the transport work and
-cleans the pending request state.
+`bind()` must return synchronously and must provide `revalidate(context)`. Revalidation runs with the exact connection binding, operation (`open`, `chunk`, `accept`, or `reject`), deadline, and abort signal. Return literal `true` only while the application authority remains current.
 
 ```typescript
-const requestAbort = new AbortController();
-const request = client.createTypedRequest<IGreetingRequest>(
-  'greet',
-  undefined,
-  {
-    timeoutMs: 10_000,
-    abortSignal: requestAbort.signal,
-  }
-);
+declare function loadBoundedObjectChunks(
+  objectId: string,
+): AsyncIterable<Uint8Array>;
+
+applicationRouter.addTypedHandler(
+  new TypedHandler<IDownloadRequest>('download', async ({ objectId }, tools) => {
+    const target = typedSocket.getServerConnectionForRequest(tools);
+    const stream = typedSocket.createVirtualStream({
+      target,
+      creatorDirection: 'send',
+      contentType: 'application/octet-stream',
+      authorization: {
+        subject: 'user-123',
+        objectId,
+        revision: 'revision-7',
+      } satisfies IStreamAuthorization,
+    });
 
-const responsePromise = request.fire(
-  { name: 'World' },
-  { timeoutMs: 3_000 }
-);
+    const production = (async () => {
+      await stream.opened;
+      for await (const chunk of loadBoundedObjectChunks(objectId)) {
+        await stream.send(chunk);
+      }
+      await stream.close();
+    })();
+    void production.catch((error) => stream.abort(error).catch(() => undefined));
 
-// A lifecycle owner can independently cancel before either timeout:
-// requestAbort.abort();
-const response = await responsePromise;
+    return { stream };
+  }),
+);
 ```
 
-Server-initiated requests retain at most 64 pending requests per peer and 1,024
-per TypedSocket server (`TYPEDSOCKET_MAX_PENDING_SERVER_REQUESTS_PER_PEER`,
-`TYPEDSOCKET_MAX_PENDING_SERVER_REQUESTS`). Asynchronous `addInterest()`
-registration retains at most 8 operations per peer and 64 per server
-(`TYPEDSOCKET_MAX_RETAINED_SERVER_INTERESTS_PER_PEER`,
-`TYPEDSOCKET_MAX_RETAINED_SERVER_INTERESTS`). Cancellation removes the pending
-request immediately, while a non-settling registration remains charged until
-its underlying promise actually settles.
+Finite streams may include `{ algorithm: 'sha256', byteLength, digest }` integrity metadata. Open-ended streams omit integrity. Capabilities are opaque, single-use, peer-scoped, generation-scoped, and short-lived.
 
-### Connection Tagging
+## Connection tags
 
-Client tag mutation is disabled by default. A server must opt in each exact name, choose whether
-an accepted proposal remains client-owned or becomes server-owned, and validate both payload shape
-and connection authorization inside the private protocol boundary.
+Client tag mutation is default-deny. Declare exact rules on the server:
 
 ```typescript
-interface IProgressTag extends typedrequestInterfaces.ITag {
-  name: 'progressSubscription';
-  payload: { channel: 'scan-progress' };
-}
-
-declare const authenticatedAuthorities: ReadonlySet<string>;
-
-const server = TypedSocket.createServer(typedRouter, {
+const typedSocket = TypedSocket.createServer(applicationRouter, {
   clientTagPolicy: {
+    authorizationTimeoutMs: 2_000,
     rules: [{
-      name: 'progressSubscription',
+      name: 'workspace',
       owner: 'client',
-      validateAndAuthorize: ({ operation, payload, authority, abortSignal }) => {
-        // Both IDs are opaque exact-object identities. The callback receives no
-        // mutable peer.tags, peer.data, peer, or router object access.
-        const authorityKey = `${authority.connectionId}:${authority.routingSurfaceId}`;
-        if (abortSignal.aborted || !authenticatedAuthorities.has(authorityKey)) return false;
-        return operation === 'remove'
-          || (
-            typeof payload === 'object'
-            && payload !== null
-            && Reflect.get(payload, 'channel') === 'scan-progress'
-          );
+      validateAndAuthorize: ({ payload, operation, abortSignal }) => {
+        if (abortSignal.aborted) return false;
+        if (operation === 'remove') return true;
+        return typeof payload === 'object'
+          && payload !== null
+          && typeof Reflect.get(payload, 'workspaceId') === 'string';
       },
     }],
   },
 });
-
-await client.setTag<IProgressTag>(
-  'progressSubscription',
-  { channel: 'scan-progress' },
-);
-
-// On reconnect, desired tags are reconciled before statusSubject emits
-// "connected". Acknowledgements are scoped to one physical generation.
-
-// A policy denial discards only that FIFO intent and recomputes desired state
-// from any later pending intent or the stable baseline established by earlier
-// settlements. Transport failure retains the canonical desired removal tombstone;
-// accepted removal, including successful reconnect replay, clears it.
-await client.removeTag('progressSubscription');
 ```
 
 ```typescript
-const progressConnections = await server.findAllTargetConnectionsByTag<IProgressTag>(
-  'progressSubscription',
-  { channel: 'scan-progress' }
-);
-
-for (const conn of progressConnections) {
-  const request = server.createTypedRequest<IGreetingRequest>('greet', conn);
-  await request.fire({ name: 'subscriber' });
-}
+await client.setTag('workspace', { workspaceId: 'workspace-123' });
+await client.removeTag('workspace');
 ```
 
-Connection wrappers deliberately expose the underlying transport peer as
-`connection.peer` — this is the supported escape hatch for admission-time
-metadata in selection predicates, for example reading
-`connection.peer.context.headers` or server-owned `connection.peer.context.state`
-inside `findAllTargetConnections()`. Reading through `peer` is fine; mutating
-`peer.tags` or TypedSocket's prefixed `peer.data` entries is not — ownership of
-those is reconciled by the protected server tag methods.
+Use `setServerTag()` and `removeServerTag()` for authentication, roles, registration state, and other server-owned metadata. A server-owned name remains protected from client overwrite after removal. Desired client tags are reconciled after reconnect only after `restoreConnection` succeeds.
 
-Authentication, roles, service registration, and other authoritative metadata must be assigned by
-the server after application-level verification:
+Do not use a universal `allClients` broadcast tag. Assign a dedicated application tag and target only clients that implement the corresponding server-initiated method.
 
-```typescript
-const connection = server.getServerConnectionForRequest(typedToolsArg);
-server.setServerTag(connection, 'authenticatedUser', { userId });
-
-// Clients cannot set, overwrite, or remove this name. Removal remains server-owned.
-server.removeServerTag(connection, 'authenticatedUser');
-```
+## Lifecycle, limits, and diagnostics
 
-Do not mutate `peer.tags` or TypedSocket's prefixed `peer.data` entries directly. The protected
-server methods reconcile ownership with in-flight client proposals.
+- `statusSubject` publishes `new`, `connecting`, `connected`, `disconnected`, and `reconnecting` transitions.
+- `diagnosticsSubject` publishes bounded structured events for invariant closes, peer rejection, reconnect scheduling or exhaustion, and tag denial. Subscribers own unsubscription; the subject does not complete.
+- `stop()` disables client reconnect, rejects pending work, closes streams, and releases router registrations. Server `stop()` detaches TypedSocket state and composition but does not stop SmartServe.
+- Request `timeoutMs` and `abortSignal` are supported on both sides. Server requests are cancelled on target disconnect or server stop.
+- Client `limits` may lower package ceilings but cannot raise them. Untrusted network deployments should lower text-frame and queue ceilings to match the application protocol.
+- The stream transport bounds connections, active streams, logical chunk size, queued chunks and bytes, raw frames, outbound frames, revalidations, arrival accounting, tombstones, capability lifetime, progress time, and cleanup time.
+- Invalid framing, overflow, integrity failure, authority revocation, handshake failure, and timeout fail closed. Physical-peer identity and raw-frame settlement identity are never inferred from caller-controlled payloads.
 
-Fixed limits cannot be raised by policy (each is exported by name from the
-package root):
+Selected stream defaults are 32 KiB physical frames, 4 MiB logical chunks, 32 active streams per connection, a 10-second handshake and capability deadline, a 30-second progress deadline, and a 5-second revalidation deadline. Root exports provide the principal package ceilings and timeout constants.
 
-- Tag name: 128 UTF-8 bytes (`TYPEDSOCKET_MAX_TAG_NAME_BYTES`).
-- SmartJSON payload envelope: 4,096 bytes (`TYPEDSOCKET_MAX_TAG_PAYLOAD_BYTES`).
-- Client-originated retained tags: 16 per peer (`TYPEDSOCKET_MAX_CLIENT_TAGS_PER_PEER`).
-- Client-originated cumulative name and payload storage: 16,384 bytes per peer (`TYPEDSOCKET_MAX_CLIENT_TAG_RETAINED_BYTES_PER_PEER`).
-- Client-side retained mutation work: 8 per exact name and 64 per client (`TYPEDSOCKET_MAX_RETAINED_CLIENT_TAG_MUTATIONS_PER_NAME`, `TYPEDSOCKET_MAX_RETAINED_CLIENT_TAG_MUTATIONS`).
-- Retained mutation/authorization work: 8 per peer, 32 per exact rule, and 256 per TypedSocket server (`TYPEDSOCKET_MAX_RETAINED_TAG_MUTATIONS_PER_PEER`, `_PER_RULE`, `_PER_SERVER`).
-- Protected server tag state: 64 names and 65,536 cumulative name/payload bytes per peer (`TYPEDSOCKET_MAX_SERVER_TAG_NAMES_PER_PEER`, `TYPEDSOCKET_MAX_SERVER_TAG_RETAINED_BYTES_PER_PEER`).
-- Authorization callback deadline: at most 5 seconds; policy may only lower it (`TYPEDSOCKET_MAX_TAG_AUTHORIZATION_TIMEOUT_MS`).
+## Public API summary
 
-Same-name mutations execute FIFO. Timed-out callbacks receive an aborted signal and remain charged
-against authorization budgets until they actually settle. Disconnect and server stop abort active
-callbacks and prevent late commits.
+### `TypedSocket`
 
-#### TypedServer Integration Contract
+| API | Side | Purpose |
+| --- | --- | --- |
+| `TypedSocket.createClient(router, url, options?)` | client | Connects, handshakes, restores connection state, and reconciles tags. |
+| `TypedSocket.createServer(routerOrRouters, options?)` | server | Composes private protocol and application routers before SmartServe construction. |
+| `getServerRoutingSurface(applicationRouter?)` | server | Returns the exact generated router SmartServe must bind during upgrade. |
+| `attachSmartServe(smartServe)` | server | Attaches lifecycle, authority guards, and peer-scoped stream resolvers. |
+| `createTypedRequest(method, target?, options?)` | both | Creates a TypedRequest; server calls require an explicit target. |
+| `createVirtualStream(options)` | server | Creates an exact authorized stream facade for one attached peer. |
+| `getServerConnectionForRequest(tools)` | server | Resolves the exact trusted physical peer for an incoming request. |
+| `setTag()` / `removeTag()` | client | Mutates an explicitly allowed client-owned tag. |
+| `setServerTag()` / `removeServerTag()` | server | Maintains protected server-owned peer metadata. |
+| `findTargetConnection*()` / `findAllTargetConnections*()` | server | Finds live attached targets by predicate or tag. |
+| `getStatus()` | both | Returns the current connection status. |
+| `stop()` | both | Releases all TypedSocket-owned lifecycle state. |
 
-TypedServer 9 passes `clientTagPolicy` through, exposes
-`webSocketTransportOwner`, resolves handler-local peers through
-`getServerConnectionForRequest(typedTools)`, and assigns infrastructure tags
-through `setServerTag()`. Authentication, roles, frontend registration, and
-service-worker registration are server-owned application state; v6 provides no
-legacy tag migration mode.
+### `virtualStreams`
 
-### Event Handling
+`VirtualStreamManager` is the peer-scoped transport manager. Client applications may use `getClientTransport()` and `createRegistration()` for explicit creator registrations. `getStats()` exposes bounded transport accounting. Server registration is not exposed on the manager; server applications must use the authorization-enforcing `TypedSocket.createVirtualStream()` facade.
 
-Client instances publish connection status events:
-
-```typescript
-client.statusSubject.subscribe((status) => {
-  console.log('Connection status:', status);
-});
-```
-
-### Diagnostics
-
-Both sides publish structured diagnostics on `diagnosticsSubject` — the *why*
-channel next to `statusSubject` (state transitions) and `nativeBytes.getStats()`
-(counters). Events carry package-defined static strings, bounded identifiers
-(tag names, method names), and bounded codes only; payloads, URLs beyond
-protocol//host, and free-form error messages never appear. Client-received
-denial codes are validated against `TYPEDSOCKET_TAG_DENIAL_CODES` before they
-reach the channel; anything unknown collapses to `MALFORMED_TAG_RESPONSE`.
-
-```typescript
-import type { TTypedSocketDiagnosticEvent } from '@api.global/typedsocket';
-
-client.diagnosticsSubject.subscribe((event: TTypedSocketDiagnosticEvent) => {
-  switch (event.kind) {
-    case 'connectionClosed':      // an invariant close: scope, closeCode, reason
-    case 'peerRejected':          // server-only: peer rejected before state existed
-    case 'reconnectScheduled':    // attempt, maxRetries, delayMs, endpoint
-    case 'reconnectExhausted':    // at most once per exhausted sequence
-    case 'tagMutationDenied':     // operation, tag name, denial code, side
-    case 'implicitTargetingUsed': // server-only: deprecated implicit targeting fired
-      console.log(event);
-  }
-});
-```
-
-`diagnosticsSubject` never completes, mirroring `statusSubject`; subscribers
-own their unsubscription. A `NativeByteManager` used standalone accepts the
-same sink via the `onDiagnostic` option, typed to the narrower
-`TNativeByteDiagnosticEvent` subset.
-
-Close codes in `connectionClosed` events are always the semantic protocol
-codes (1002, 1003, 1008, 1009, 1011, 1013). On the wire, client-initiated invariant
-closes mirror them into the application range the WebSocket `close()` API
-permits — 1009 becomes 4009 (`toClientWebSocketCloseCode()`); server-initiated
-closes keep the protocol codes.
-
-### Cleanup
-
-Properly close connections when done:
-
-```typescript
-// Client
-await client.stop();
-
-// Server integration
-await typedSocket.stop();
-await smartServe.stop();
-```
+## Migration from version 6
 
-## API Reference
-
-### TypedSocket
-
-#### Static Methods
-
-| Method | Description |
-|--------|-------------|
-| `createClient(router, serverUrl, options?)` | Creates a WebSocket client. Options include reconnect controls, `abortSignal`, independent `nativeByteCapabilityMode` and `nativeMessageCapabilityMode`, lowering-only `limits`, and `restoreConnection`. |
-| `createServer(routerOrRouters, options?)` | Synchronously composes protocol handling. Options include independent native byte/message capability modes and authorization adapters, plus the default-deny `clientTagPolicy`. |
-| `fromSmartServe(smartServe, routerOrRouters, options?)` | Creates and attaches a JSON-only server-side TypedSocket to an existing SmartServe instance. |
-| `useWindowLocationOriginUrl()` | Returns the current window location origin (browser only). |
-
-#### Instance Properties
-
-| Property | Description |
-|----------|-------------|
-| `side` | Whether this instance is a `'server'` or `'client'`. |
-| `typedrouter` | The TypedRouter instance handling requests. |
-| `nativeBytes` | Native transport API. Existing stream methods stay on this object; ephemeral message channels are under `nativeBytes.messages`. |
-| `webSocketTransportOwner` | Stable SmartServe 4 raw-frame owner selected during SmartServe construction. |
-| `statusSubject` | RxJS Subject for client connection status events. Server instances do not publish lifecycle transitions here. |
-| `diagnosticsSubject` | RxJS Subject of structured `TTypedSocketDiagnosticEvent` values: invariant closes (including `scope: 'nativeMessage'`), peer rejections, reconnect scheduling/exhaustion, tag denials, and deprecated implicit targeting. Never completes. |
-
-#### Instance Methods
-
-| Method | Description |
-|--------|-------------|
-| `attachSmartServe(smartServe)` | Attaches one SmartServe transport to a composed server-side TypedSocket before listening. |
-| `createVirtualStream(options)` | Creates the preferred exact, authorized native-byte receive facade for one server peer. TypedRequest transfers its descriptor automatically. |
-| `createBinaryMessageChannel(options)` | Creates an authorized ephemeral binary-message receive grant and ordinary descriptor for one exact server peer. |
-| `createTypedRequest(method, targetConnection?, options?)` | Creates a typed request. Options include the transport `timeoutMs` and `abortSignal`; per-call `fire()` deadlines are also forwarded to the transport. |
-| `getServerConnectionForRequest(typedTools)` | Resolves the exact transport connection for an incoming server handler without assertions. |
-| `getStatus()` | Returns the client connection lifecycle status. Server instances remain in the initial `new` state. |
-| `setTag(name, payload)` | Requests one exact policy-authorized tag and records reconnect state only after an ordered server acknowledgement. |
-| `removeTag(name)` | Requests removal of a client-owned tag. Policy denial discards that FIFO intent and recomputes from any later pending intent or the stable settled baseline. Transport failure retains the canonical desired removal tombstone; accepted removal, including successful reconnect replay, clears it. |
-| `setServerTag(connection, name, payload?)` | Assigns protected server-owned metadata after application verification. |
-| `removeServerTag(connection, name)` | Removes server-owned metadata while keeping the name protected from client mutation for that peer. |
-| `findAllTargetConnections(filterFn)` | Finds all connections matching the filter (server-side only). |
-| `findTargetConnection(filterFn)` | Finds the first connection matching the filter (server-side only). |
-| `findAllTargetConnectionsByTag(key, payload?)` | Finds all connections with the specified tag. |
-| `findTargetConnectionByTag(key, payload?)` | Finds the first connection with the specified tag. |
-| `stop()` | On clients, closes the WebSocket and rejects pending requests. On servers, cancels pending requests, cleans their interests, unsubscribes from SmartServe, and releases protocol-router composition without stopping SmartServe itself. |
-
-#### Advanced Native Methods
-
-| Method | Description |
-|--------|-------------|
-| `nativeBytes.createReceiveGrant(options)` | Creates an explicit exact-manifest receive grant for a protocol integration. |
-| `nativeBytes.openSender(descriptor, options?)` | Opens an explicit sender for an opaque descriptor on the exact target connection. |
-| `nativeBytes.getCapability(target?)` | Reports negotiated native-byte capability without exposing tokens or descriptors. |
-| `nativeBytes.getStats(target?)` | Reports bounded connection, stream, queue, and tombstone counts. |
-| `nativeBytes.messages.createReceiveGrant(options)` | Advanced explicit receive-grant API for one ephemeral message channel. The grant exposes `opened`, `revoke(reason?)`, and `dispose()` in addition to its descriptor and receiver. |
-| `nativeBytes.messages.openSender(descriptor, options?)` | Opens the descriptor on the exact physical client generation or required server peer target. |
-| `nativeBytes.messages.getCapability(target?)` | Reports separately negotiated `native-message-v1` status. |
-| `nativeBytes.messages.getStats(target?)` | Reports bounded channel, pending message, reassembly, queue, and aggregate accounting. |
+- Replace TypedRequest 5 and SmartServe 4 with TypedRequest 7 and SmartServe 5.1.1.
+- Remove `nativeByteCapabilityMode`, `nativeMessageCapabilityMode`, `nativeBytes`, message-channel APIs, and native-specific authorization adapters.
+- Replace native stream DTOs with `TVirtualStream<'send' | 'receive'>` from `@api.global/typedrequest-interfaces`.
+- Replace `fromSmartServe()` with the required `createServer()` → SmartServe construction → `attachSmartServe()` order.
+- Pass `getServerRoutingSurface(applicationRouter)` to SmartServe, not the application router itself.
+- Always pass an explicit server target to `createTypedRequest()`.
+- Configure `virtualStreamAuthorizationAdapter` and use `createVirtualStream()` for server-created streams.
+- Treat a package-major handshake failure as terminal; there is no JSON-only or capability-disabled fallback.
 
 ## License and Legal Information