@camstack/system 1.2.218 → 1.2.220

package/dist/kernel/transport/socket-channel.d.ts

@@ -1,5 +1,6 @@
 import { Socket } from 'node:net';
-import { LocalChannel, RequestHandler, EventHandler } from './local-transport.js';
+import { CapActionChannelObserver } from './cap-action-census.js';
+import { EventHandler, LocalChannel, RequestHandler } from './local-transport.js';
 import { SocketTrafficSample } from './socket-traffic.js';
 /**
  * Default bound on one UDS request, when the caller names none.
@@ -16,6 +17,8 @@ export declare const DEFAULT_UDS_REQUEST_TIMEOUT_MS = 60000;
 export interface SocketRequestOptions {
     /** Bound in ms; `0` or negative disables the timer entirely. */
     readonly timeoutMs?: number;
+    /** Opaque bytes carried beside the body — see `LocalRequestOptions.payload`. */
+    readonly payload?: Uint8Array;
 }
 export declare class SocketChannel implements LocalChannel {
     private readonly socket;
@@ -32,6 +35,8 @@ export declare class SocketChannel implements LocalChannel {
     private readonly txCounters;
     /** Frames read from the peer, cumulative, split by kind. */
     private readonly rxCounters;
+    /** See {@link CapActionChannelObserver}. Absent = no per-action census. */
+    private actionObserver;
     constructor(socket: Socket);
     /**
      * Send a request and wait for the peer's response.
@@ -46,6 +51,20 @@ export declare class SocketChannel implements LocalChannel {
      */
     request(body: unknown, opts?: SocketRequestOptions): Promise<unknown>;
     emit(body: unknown): void;
+    /**
+     * Wire the per-action census. Only one observer is active at a time; an
+     * unwired channel records nothing at all (never zeros).
+     */
+    observeActions(observer: CapActionChannelObserver): void;
+    /**
+     * The label for one envelope, or `undefined` when there is nothing to
+     * record. Wrapped: a broken labeller must never fail the call it watches —
+     * the same discipline `LocalChildRegistry.recordCapUsage` applies, and for
+     * the same reason.
+     */
+    private labelSafely;
+    /** Settle one request/response pair on the census. Never throws. */
+    private recordAction;
     /** Replace the request handler. Only one handler is active at a time. */
     onRequest(handler: RequestHandler): void;
     /** Replace the event handler. Only one handler is active at a time. */
@@ -61,6 +80,26 @@ export declare class SocketChannel implements LocalChannel {
      * 22 500 writes/s") and not a total since boot.
      */
     readTraffic(): SocketTrafficSample;
+    /**
+     * Bytes handed to the socket that the kernel has not taken yet — the
+     * `Writable` buffer plus the write in flight. Read LIVE, never cached: this
+     * is the number that says whether the peer is draining what we write, and
+     * it is read on every heartbeat probe (D446). An unref'd socket keeps it
+     * exactly like a ref'd one, which is why it is read here and not summed
+     * over `_getActiveHandles()`.
+     */
+    queuedBytes(): number;
+    /**
+     * Write one frame. With a payload the head and the tail are two `write`
+     * calls under `cork()` — the kernel sees one `writev`, and the payload bytes
+     * are never copied into the head. A forwarded payload is a view into the
+     * frame it arrived on, and that frame's buffer is never mutated, so handing
+     * the view to the socket is safe.
+     *
+     * Returns the on-the-wire bytes it charged — the same number the per-kind
+     * counter got, so the per-action census can never disagree with the per-peer
+     * one. `0` when the channel is closed and nothing was written.
+     */
     private send;
     private onData;
     /**