@api.global/typedsocket 5.1.2 → 6.1.0

package/readme.md

@@ -11,18 +11,12 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 - 🔒 **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
-- 🏷️ **Connection Tagging** - Tag and filter connections for targeted messaging
+- 🏷️ **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
 
 ## Install
 
-```bash
-npm install @api.global/typedsocket
-```
-
-Or with pnpm:
-
 ```bash
 pnpm add @api.global/typedsocket
 ```
@@ -34,6 +28,11 @@ pnpm add @api.global/typedsocket
 - 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
+
+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.
 
 ### Define Your Request Interface
 
@@ -82,6 +81,7 @@ const smartServe = new SmartServe({
   port: 3000,
   websocket: {
     typedRouter,
+    transportOwner: server.webSocketTransportOwner,
   },
 });
 server.attachSmartServe(smartServe);
@@ -114,9 +114,10 @@ const smartServe = new SmartServe({
   port: 3000,
   websocket: {
     typedRouter,
+    transportOwner: typedSocket.webSocketTransportOwner,
     onConnectionOpen: (peer) => {
-      // Tag connections for later filtering
-      peer.tags.add('client');
+      // Server metadata is protected from client overwrite/removal.
+      typedSocket.setServerTag(peer, 'client');
     }
   }
 });
@@ -148,6 +149,7 @@ const smartServe = new SmartServe({
       if (context.url.hostname === 'admin.example.com') return adminRouter;
       return undefined;
     },
+    transportOwner: typedSocket.webSocketTransportOwner,
   },
 });
 typedSocket.attachSmartServe(smartServe);
@@ -157,14 +159,290 @@ 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
-compatibility shortcut that delegates to `createServer()` and
-`attachSmartServe()`.
+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.
+
+#### 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.
+
+```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>;
+  };
+}
+
+interface IUploadAuthorization {
+  uploadId: string;
+  principalId: string;
+  credentialRevision: string;
+  configRevision: string;
+  bindingRevision: string;
+}
+
+interface IDurableUpload {
+  writable: WritableStream<Uint8Array>;
+  commit(): Promise<void>;
+  abort(reasonArg: unknown): Promise<void>;
+}
+
+// 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 };
+}
+
+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,
+    });
+
+    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(() => {});
+      }
+    })();
+
+    return { stream };
+  },
+));
+
+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 smartServe = new SmartServe({
+  port: 3000,
+  websocket: {
+    typedRouter: serverRouter,
+    transportOwner: typedSocketServer.webSocketTransportOwner,
+  },
+});
+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();
+}
+```
 
-Connection lookup and implicit single-peer targeting span every peer on the
-attached SmartServe transport, regardless of the surface router that accepted
-the peer. Multi-surface servers should tag or filter peers by surface and pass
-an explicit target to `createTypedRequest()`.
+`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 |
+| Grants plus active streams per connection | `NATIVE_BYTE_MAX_STREAMS_PER_CONNECTION` | 32 |
+| 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 / streams | `NATIVE_BYTE_MAX_CONNECTIONS_PER_SERVER` / `NATIVE_BYTE_MAX_STREAMS_PER_SERVER` | 1,024 / 1,024 |
+| 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
 
@@ -184,6 +462,76 @@ const client = await TypedSocket.createClient(
 );
 ```
 
+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.
+
+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.
+
+```typescript
+import * as typedrequestInterfaces from '@api.global/typedrequest-interfaces';
+
+interface IRestoreSessionRequest extends typedrequestInterfaces.implementsTR<
+  typedrequestInterfaces.ITypedRequest,
+  IRestoreSessionRequest
+> {
+  method: 'restoreSession';
+  request: { token: string; connectionId: string };
+  response: { restored: true };
+}
+
+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,
+    });
+  },
+});
+```
+
+| Client limit | Exported constant | Package ceiling |
+|---|---|---:|
+| Complete text frame | `TYPEDSOCKET_MAX_TEXT_FRAME_BYTES` | 1 MiB |
+| Queued text frames / bytes | `TYPEDSOCKET_MAX_QUEUED_TEXT_FRAMES` / `TYPEDSOCKET_MAX_QUEUED_TEXT_BYTES` | 64 / 4 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` | 4 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.
@@ -237,23 +585,26 @@ console.log(response.message); // "Hello, World! 👋"
 
 #### Server to Client
 
-The server can also initiate requests to connected clients:
+The server can also initiate requests to connected clients. Always pass the
+target connection explicitly:
 
 ```typescript
-// When only one client is connected, it's automatically selected
-const request = server.createTypedRequest<IGreetingRequest>('greet');
-const response = await request.fire({
-  name: 'Client',
-});
-
-// For multiple clients, specify the target connection
 const connection = await server.findTargetConnection(async (conn) => {
   // Your filter logic here
   return true;
 });
 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
@@ -281,59 +632,171 @@ const responsePromise = request.fire(
 const response = await responsePromise;
 ```
 
+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.
+
 ### Connection Tagging
 
-Tag connections for organized, targeted communication:
+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.
 
 ```typescript
-// Client side: add a tag
-interface IUserTag extends typedrequestInterfaces.ITag {
-  name: 'userRole';
-  payload: 'admin' | 'user' | 'guest';
+interface IProgressTag extends typedrequestInterfaces.ITag {
+  name: 'progressSubscription';
+  payload: { channel: 'scan-progress' };
 }
 
-await client.setTag<IUserTag>('userRole', 'admin');
+declare const authenticatedAuthorities: ReadonlySet<string>;
+
+const server = TypedSocket.createServer(typedRouter, {
+  clientTagPolicy: {
+    rules: [{
+      name: 'progressSubscription',
+      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'
+          );
+      },
+    }],
+  },
+});
+
+await client.setTag<IProgressTag>(
+  'progressSubscription',
+  { channel: 'scan-progress' },
+);
 
-// On reconnect, stored tags are restored before statusSubject emits
-// "connected". A failed restoration keeps the client unready and is retried
-// through the normal reconnect policy.
+// On reconnect, desired tags are reconciled before statusSubject emits
+// "connected". Acknowledgements are scoped to one physical generation.
 
-// Removed tags are not restored after reconnect, even if this rejects because
-// the server is unavailable while the removal request is attempted.
-await client.removeTag('userRole');
+// 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
-// Server side: find connections by tag
-const adminConnections = await server.findAllTargetConnectionsByTag<IUserTag>(
-  'userRole',
-  'admin'
+const progressConnections = await server.findAllTargetConnectionsByTag<IProgressTag>(
+  'progressSubscription',
+  { channel: 'scan-progress' }
 );
 
-// Send to all admins
-for (const conn of adminConnections) {
+for (const conn of progressConnections) {
   const request = server.createTypedRequest<IGreetingRequest>('greet', conn);
-  await request.fire({ name: 'admin' });
+  await request.fire({ name: 'subscriber' });
 }
+```
+
+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.
+
+Authentication, roles, service registration, and other authoritative metadata must be assigned by
+the server after application-level verification:
+
+```typescript
+const connection = server.getServerConnectionForRequest(typedToolsArg);
+server.setServerTag(connection, 'authenticatedUser', { userId });
 
-// Find a single connection
-const firstAdmin = await server.findTargetConnectionByTag<IUserTag>('userRole', 'admin');
+// Clients cannot set, overwrite, or remove this name. Removal remains server-owned.
+server.removeServerTag(connection, 'authenticatedUser');
 ```
 
+Do not mutate `peer.tags` or TypedSocket's prefixed `peer.data` entries directly. The protected
+server methods reconcile ownership with in-flight client proposals.
+
+Fixed limits cannot be raised by policy (each is exported by name from the
+package root):
+
+- 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`).
+
+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.
+
+#### TypedServer Integration Contract
+
+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.
+
 ### Event Handling
 
-Subscribe to connection status events:
+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`.
 
-server.statusSubject.subscribe((status) => {
-  console.log('Server connection event:', status);
+```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:
@@ -355,9 +818,9 @@ await smartServe.stop();
 
 | Method | Description |
 |--------|-------------|
-| `createClient(router, serverUrl, options?)` | Creates a WebSocket client that connects to the specified server URL. Options include `autoReconnect`, `maxRetries`, `initialBackoffMs`, `maxBackoffMs`, and `abortSignal`. |
-| `createServer(routerOrRouters)` | Synchronously composes TypedSocket protocol handling into one or more isolated application routers. |
-| `fromSmartServe(smartServe, routerOrRouters)` | Compatibility shortcut that creates and attaches a server-side TypedSocket. |
+| `createClient(router, serverUrl, options?)` | Creates a WebSocket client. Options include reconnect controls, `abortSignal`, `nativeByteCapabilityMode`, lowering-only `limits`, and `restoreConnection`. |
+| `createServer(routerOrRouters, options?)` | Synchronously composes protocol handling. Options include `nativeByteCapabilityMode`, `nativeByteAuthorizationAdapter`, and 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
@@ -366,25 +829,42 @@ await smartServe.stop();
 |----------|-------------|
 | `side` | Whether this instance is a `'server'` or `'client'`. |
 | `typedrouter` | The TypedRouter instance handling requests. |
-| `statusSubject` | RxJS Subject for connection status events. |
+| `nativeBytes` | Advanced native-byte grant, sender, capability, and statistics API for transport integrations. |
+| `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, 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. |
 | `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. |
-| `setTag(name, payload)` | Sets a tag on the client connection (client-side only). |
-| `removeTag(name)` | Immediately removes a tag from local reconnect state, then removes it from the server connection; rejects if the server removal fails. |
+| `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. |
+
 ## License and Legal Information
 
-This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](./license) file.
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license.md](./license.md) file.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 
@@ -396,7 +876,7 @@ Use of these trademarks must comply with Task Venture Capital GmbH's Trademark G
 
 ### Company Information
 
-Task Venture Capital GmbH
+Task Venture Capital GmbH<br>
 Registered at District Court Bremen HRB 35230 HB, Germany
 
 For any legal inquiries or further information, please contact us via email at hello@task.vc.