@api.global/typedsocket 6.2.0 → 7.0.0

package/dist_ts/interfaces.virtualstream.d.ts

@@ -0,0 +1,131 @@
+import type * as plugins from './plugins.js';
+import type { VIRTUAL_STREAM_FRAME_TYPES, VIRTUAL_STREAM_PROTOCOL } from './constants.virtualstream.js';
+export type TVirtualStreamDirection = plugins.typedrequestInterfaces.TVirtualStreamDirection;
+export type TVirtualStreamAuthorityOperation = 'open' | 'chunk' | 'accept' | 'reject';
+export type TVirtualStreamConnectionBinding = {
+    readonly side: 'client';
+    readonly generation: number;
+    readonly webSocket: WebSocket;
+} | {
+    readonly side: 'server';
+    readonly peer: plugins.IWebSocketPeer;
+};
+export interface IVirtualStreamDescriptorTransport {
+    readonly [key: string]: plugins.typedrequestInterfaces.TVirtualStreamTransportDescriptorPayload;
+    readonly capability: string;
+    readonly expiresAt: number;
+}
+export interface ITypedSocketVirtualStreamDescriptor<TDirection extends TVirtualStreamDirection = TVirtualStreamDirection> extends plugins.typedrequestInterfaces.IVirtualStreamDescriptor<TDirection> {
+    readonly protocol: typeof VIRTUAL_STREAM_PROTOCOL;
+    readonly transport: IVirtualStreamDescriptorTransport;
+}
+export interface IVirtualStreamAuthorizationContext {
+    readonly target: plugins.IWebSocketPeer;
+    readonly creatorDirection: TVirtualStreamDirection;
+    readonly contentType?: string;
+    readonly integrity?: plugins.typedrequestInterfaces.IVirtualStreamIntegrity;
+}
+export interface IVirtualStreamRevalidationContext {
+    readonly operation: TVirtualStreamAuthorityOperation;
+    readonly descriptor: ITypedSocketVirtualStreamDescriptor;
+    readonly connection: TVirtualStreamConnectionBinding;
+    readonly abortSignal: AbortSignal;
+    readonly deadline: number;
+}
+export type TVirtualStreamRevalidate = (contextArg: Readonly<IVirtualStreamRevalidationContext>) => boolean | Promise<boolean>;
+export interface IVirtualStreamAuthorizationBinding {
+    readonly revalidate: TVirtualStreamRevalidate;
+}
+export interface IVirtualStreamAuthorizationAdapter {
+    bind(authorizationArg: unknown, contextArg: Readonly<IVirtualStreamAuthorizationContext>): IVirtualStreamAuthorizationBinding;
+}
+export interface ICreateVirtualStreamOptions<TDirection extends TVirtualStreamDirection = TVirtualStreamDirection> {
+    readonly target: {
+        readonly peer: plugins.IWebSocketPeer;
+    } | plugins.IWebSocketPeer;
+    readonly creatorDirection: TDirection;
+    readonly contentType?: string;
+    readonly integrity?: plugins.typedrequestInterfaces.IVirtualStreamIntegrity;
+    readonly authorization: unknown;
+}
+export interface IVirtualStreamCreateRegistrationOptions<TDirection extends TVirtualStreamDirection = TVirtualStreamDirection> {
+    readonly creatorDirection: TDirection;
+    readonly contentType?: string;
+    readonly integrity?: plugins.typedrequestInterfaces.IVirtualStreamIntegrity;
+    readonly revalidate?: TVirtualStreamRevalidate;
+}
+export interface IVirtualStreamServerCreateRegistrationOptions<TDirection extends TVirtualStreamDirection = TVirtualStreamDirection> {
+    readonly creatorDirection: TDirection;
+    readonly contentType?: string;
+    readonly integrity?: plugins.typedrequestInterfaces.IVirtualStreamIntegrity;
+    readonly revalidate: TVirtualStreamRevalidate;
+}
+export interface IVirtualStreamStats {
+    readonly connection: 'none' | 'client' | 'server';
+    readonly handshakeReady: boolean;
+    readonly registeredCapabilities: number;
+    readonly activeStreams: number;
+    readonly queuedChunks: number;
+    readonly queuedBytes: number;
+    readonly rawQueueFrames: number;
+    readonly rawQueueBytes: number;
+    readonly arrivalStamps: number;
+    readonly arrivalStampBytes: number;
+    readonly outboundFrames: number;
+    readonly retainedRevalidations: number;
+    readonly tombstones: number;
+    readonly serverConnections: number;
+    readonly serverStreams: number;
+    readonly serverRetainedRevalidations: number;
+    readonly serverRetainedBytes: number;
+}
+export interface IVirtualStreamRuntime {
+    now(): number;
+    randomBytes(lengthArg: number): Uint8Array;
+    setTimer(callbackArg: () => void, delayMsArg: number): unknown;
+    clearTimer(timerArg: unknown): void;
+    scheduleMacrotask(callbackArg: () => void): unknown;
+}
+export type TVirtualStreamOpenFrame = {
+    readonly type: typeof VIRTUAL_STREAM_FRAME_TYPES.OPEN;
+    readonly streamId: string;
+    readonly capability: string;
+    readonly descriptorDigest: string;
+};
+export type TVirtualStreamOpenAckFrame = {
+    readonly type: typeof VIRTUAL_STREAM_FRAME_TYPES.OPEN_ACK;
+    readonly streamId: string;
+};
+export type TVirtualStreamChunkFrame = {
+    readonly type: typeof VIRTUAL_STREAM_FRAME_TYPES.CHUNK;
+    readonly streamId: string;
+    readonly sequence: number;
+    readonly totalLength: number;
+    readonly fragmentOffset: number;
+    readonly payload: Uint8Array;
+};
+export type TVirtualStreamChunkAckFrame = {
+    readonly type: typeof VIRTUAL_STREAM_FRAME_TYPES.CHUNK_ACK;
+    readonly streamId: string;
+    readonly sequence: number;
+};
+export type TVirtualStreamFinFrame = {
+    readonly type: typeof VIRTUAL_STREAM_FRAME_TYPES.FIN;
+    readonly streamId: string;
+    readonly chunkCount: number;
+    readonly byteLength: number;
+};
+export type TVirtualStreamAcceptFrame = {
+    readonly type: typeof VIRTUAL_STREAM_FRAME_TYPES.ACCEPT;
+    readonly streamId: string;
+    readonly chunkCount: number;
+    readonly byteLength: number;
+    readonly integrityVerified: boolean;
+};
+export type TVirtualStreamResetFrame = {
+    readonly type: typeof VIRTUAL_STREAM_FRAME_TYPES.RESET;
+    readonly streamId: string;
+    readonly code: number;
+    readonly reason: string;
+};
+export type TVirtualStreamFrame = TVirtualStreamOpenFrame | TVirtualStreamOpenAckFrame | TVirtualStreamChunkFrame | TVirtualStreamChunkAckFrame | TVirtualStreamFinFrame | TVirtualStreamAcceptFrame | TVirtualStreamResetFrame;

package/dist_ts/interfaces.virtualstream.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW50ZXJmYWNlcy52aXJ0dWFsc3RyZWFtLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvaW50ZXJmYWNlcy52aXJ0dWFsc3RyZWFtLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiIifQ==

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@api.global/typedsocket",
-  "version": "6.2.0",
+  "version": "7.0.0",
   "private": false,
   "description": "A library for creating typed WebSocket connections, supporting bi-directional communication with type safety.",
   "main": "dist_ts/index.js",
@@ -19,14 +19,14 @@
     "@git.zone/tsbuild": "^4.4.2",
     "@git.zone/tsbundle": "^2.11.3",
     "@git.zone/tsrun": "^2.0.6",
-    "@git.zone/tstest": "^3.6.7",
+    "@git.zone/tstest": "^4.0.0",
     "@push.rocks/smartenv": "^6.1.0",
-    "@push.rocks/smartserve": "^4.2.1",
-    "@types/node": "26.1.1"
+    "@push.rocks/smartserve": "^5.1.1",
+    "@types/node": "26.1.2"
   },
   "dependencies": {
-    "@api.global/typedrequest": "^5.2.1",
-    "@api.global/typedrequest-interfaces": "^5.1.1",
+    "@api.global/typedrequest": "^7.0.1",
+    "@api.global/typedrequest-interfaces": "^7.0.0",
     "@push.rocks/smartdelay": "^3.1.0",
     "@push.rocks/smarthash": "^3.3.0",
     "@push.rocks/smartjson": "^6.0.1",
@@ -36,7 +36,7 @@
     "@push.rocks/smarturl": "^3.1.0"
   },
   "peerDependencies": {
-    "@push.rocks/smartserve": ">=4.2.1 <5"
+    "@push.rocks/smartserve": ">=5.1.1 <6"
   },
   "browserslist": [
     "last 1 chrome versions"

package/readme.hints.md

@@ -1,62 +1,23 @@
 # TypedSocket Hints
 
-## TypedSocket 6 Integration
-
-TypedSocket 6 requires SmartServe 4.2.1 and TypedRequest 5.2.1. Compose the
-TypedSocket server before constructing SmartServe so `webSocketTransportOwner`
-is selected for the physical peer at upgrade time.
-
-### Authority Rules
-
-1. **Peer identity**: Incoming server handlers call
-   `getServerConnectionForRequest(typedTools)` to obtain the exact typed transport
-   connection without assertions. Tag validators receive opaque `connectionId`
-   and `routingSurfaceId` identities instead of mutable peer/router objects.
-
-2. **Tags**: Client tags are default-deny exact rules. Authentication, roles,
-   registration, and reserved names are assigned only with `setServerTag()`.
-
-3. **Bytes**: Generic legacy VirtualStreams are always denied. Exact native-byte
-   facades require fixed manifests, principal/revision authority, and durable
-   confirmation.
-
-4. **Lifecycle**: Client text work, native frames, callbacks, pending requests,
-   tag mutations, and server request interests have fixed resource ceilings and
-   generation fencing. SmartServe settlements authorize only the exact frame
-   object returned by `pullBinaryFrame()`.
-
-5. **Restoration**: `restoreConnection(context)` runs after capability
-   negotiation and before desired tags or `connected`. Use
-   `context.createTypedRequest()` for authenticated restoration RPCs; it inherits
-   the restoration deadline and abort signal and becomes invalid afterward.
-
-### Diagnostics and Close Codes
-
-`diagnosticsSubject` (and `onDiagnostic` on a standalone `NativeByteManager`)
-publishes structured invariant-close, peer-rejection, reconnect, tag-denial,
-and implicit-targeting events. Emission must never disturb transport paths:
-every sink call is try/catch-wrapped.
-
-The WebSocket JS `close()` API only permits codes 1000 and 3000-4999. All
-client-initiated invariant closes therefore go through
-`toClientWebSocketCloseCode()` (1009 -> 4009). Calling `close(1008)` on a real
-client WebSocket throws `InvalidAccessError` — under Node/undici that escapes
-`onmessage` as an uncaught exception and kills the process, and inside
-`NativeByteManager`'s try/catch it silently left the socket open. Server-side
-`peer.close()` keeps protocol codes; diagnostics always report the semantic
-protocol code.
-
-### Source Layout
-
-Files are named after their main class: `classes.typedsocket.ts`,
-`classes.typedsockettagpolicymanager.ts`, `classes.clienttagreconciler.ts`
-(client desired/acknowledged tag state machine behind a transport adapter),
-`classes.nativebytemanager.ts`, `classes.nativebyteerror.ts`, plus
-`helpers.*`, `interfaces.*`, `constants.*`, and `plugins.ts`.
-
-### Release Artifact
-
-Only compiled `dist_ts` JavaScript/declarations, package metadata, documentation,
-and the license are published. `pnpm run verify:package` performs the deterministic
-two-pack entry, hash, metadata, and smoke-import gate (exact artifact count is
-asserted in `verify.package.ts` — update it when adding source files).
+## TypedSocket 7 integration findings
+
+1. `TypedSocket.createServer()` creates a transport routing surface for each application router. SmartServe 5.1.1 must receive `typedSocket.getServerRoutingSurface(applicationRouter)` and the exact `typedSocket.webSocketTransportOwner`; passing the application router directly does not establish the v7 peer authority boundary.
+
+2. Construction order is fixed: application routers, `createServer()`, SmartServe construction, `attachSmartServe()`, then `smartServe.start()`. Version 7 intentionally has no `fromSmartServe()` path because routing-surface and transport-owner identities are selected during upgrade.
+
+3. Every peer uses one always-on TypedRequest 7 `IVirtualStreamTransport` with protocol `virtual-stream-v1`. There are no native-byte/native-message capability modes or JSON-only fallback. The exact TypedSocket package major must handshake before application RPC or binary stream traffic is authorized.
+
+4. Server-initiated TypedRequests require an explicit `ISmartServeConnectionWrapper`. Resolve it from handler tools with `getServerConnectionForRequest()` or from the live target lookup APIs. There is no implicit single-peer targeting.
+
+5. Server-created streams go through `TypedSocket.createVirtualStream()`, which requires an exact target and a synchronous `virtualStreamAuthorizationAdapter.bind()` result containing `revalidate()`. Client-created streams use `virtualStreams.createRegistration()` plus TypedRequest's `VirtualStream.fromRegistration()` on the current handshake-ready generation.
+
+6. Stream direction in shared DTOs is requester-local and TypedHandler reverses it at the handler boundary. Receivers drain until `undefined` and then call `accept()`; senders call `close()`. Direct receive and `ReadableStream` consumption are mutually exclusive.
+
+7. Client tags remain default-deny and exact-rule based. Authentication and roles belong in protected server tags. Connection restoration runs after the major handshake and before desired tags and `connected` readiness.
+
+8. `stop()` releases TypedSocket-owned guards, resolvers, pending requests, streams, and router composition. Server stop does not stop SmartServe. Diagnostics use `text` and `virtualStream` scopes and never expose caller-controlled unbounded values.
+
+## Release artifact
+
+The package publishes compiled `dist_ts` JavaScript and declarations, package metadata, `readme.md`, `readme.hints.md`, and `license.md`. Keep examples aligned with root exports from `ts/index.ts`; v6 native modules are no longer published.