@camstack/system 1.2.218 → 1.2.219

package/dist/kernel/transport/local-child-registry.d.ts

@@ -1,8 +1,24 @@
 import { IReadinessRegistryRecord, SystemEvent } from '@camstack/types';
 import { CapUsageCallRecord } from '../moleculer/cap-usage-registry.js';
+import { CapRoutingHints } from './cap-routing-hints.js';
 import { AddonCallInput, CapCallInput, ChildLogMessage, RegisteredChild } from './child-cap-protocol.js';
 import { LocalTransportServer } from './local-transport.js';
 import { SocketTrafficSample } from './socket-traffic.js';
+/**
+ * How many child `cap-call-out`s this parent forwarded WITHOUT reading their
+ * args (`raw`) against how many it decoded (`decoded`: an inline-args frame,
+ * a target that cannot take a payload, or a call that left the sibling path
+ * for `onUnownedCall`). Cumulative; the heartbeat reports the window.
+ *
+ * It exists because raw-forward makes the parent blind to the bytes on
+ * purpose, and the one thing it must not be blind to is how often that
+ * happens. A plane that says "raw=0" under load is a plane where the
+ * negotiation failed, and nothing else would show it.
+ */
+export interface ForwardCensus {
+    readonly raw: number;
+    readonly decoded: number;
+}
 /**
  * Fan-out mode for parent→child event delivery, from the
  * `CAMSTACK_UDS_EVENT_FANOUT` env (read once at registry construction):
@@ -104,6 +120,13 @@ export interface LocalChildRegistryOptions {
      * which is the one thing the caller took the trouble to say it did not want.
      * It goes to `onUnownedCall`, which resolves the named provider.
      *
+     * The third argument is the call's ROUTING HINTS (`{ nodeId?, addonId? }`,
+     * `cap-routing-hints.ts`) — the two top-level string fields the parent ever
+     * read out of the args — not the args themselves. Under raw-forward the
+     * parent does not decode the args at all; the sender lifts the hints, and
+     * for a legacy frame the parent lifts them itself. Both modes reach this
+     * predicate with the same shape.
+     *
      * The array-method bypass above and this one are the same defect seen twice.
      * `broker.getBrokerConfig({id:'ha_001', addonId:'provider-homeassistant'})`
      * from the Home Assistant export was answered by `provider-homematic` — which
@@ -117,7 +140,7 @@ export interface LocalChildRegistryOptions {
      * wiring side injects it, sharing the predicate with the handler that then
      * performs the routing — a rule implemented twice is a rule that drifts.
      */
-    readonly isAddonPinnedCall?: (capName: string, method: string, args: unknown) => boolean;
+    readonly isAddonPinnedCall?: (capName: string, method: string, hints: CapRoutingHints) => boolean;
     /**
      * Per-cap-method bound for UDS cap calls, in ms — read from the cap
      * definition's declared `timeoutMs`. The SAME resolver the remote plane uses
@@ -199,6 +222,9 @@ export declare class LocalChildRegistry {
     /** See {@link LocalChildRegistryOptions.isAggregatedCollectionMethod}. */
     private readonly isAggregatedCollectionMethod?;
     private readonly isAddonPinnedCall?;
+    /** See {@link ForwardCensus}. Mutable counters on the hot path, by design. */
+    private forwardedRaw;
+    private forwardedDecoded;
     /** See {@link LocalChildRegistryOptions.capTimeoutMs}. */
     private readonly capTimeoutMs?;
     /** See {@link LocalChildRegistryOptions.capUsageObserver}. */
@@ -242,6 +268,15 @@ export declare class LocalChildRegistry {
      * pair for the whole process and has no per-socket breakdown.
      */
     getChildSocketTraffic(childId: string): SocketTrafficSample | null;
+    /**
+     * Bytes this process has written to a child that the child has not yet
+     * taken, live, or `null` when the channel keeps no such reading. Read on
+     * every heartbeat probe (D446) — a child that stops draining is the shape
+     * of an outbound-queue episode, and the number lives on the channel.
+     */
+    getChildQueuedBytes(childId: string): number | null;
+    /** Cumulative {@link ForwardCensus} of this parent's `cap-call-out` routing. */
+    readForwardCensus(): ForwardCensus;
     /**
      * The regime the counters above were produced under, read once from
      * `CAMSTACK_UDS_EVENT_FANOUT` at construction.

package/dist/kernel/transport/local-transport.d.ts

@@ -1,14 +1,24 @@
 import { SocketTrafficSample } from './socket-traffic.js';
-/** Wire frame exchanged over a local channel. */
+/**
+ * Wire frame exchanged over a local channel.
+ *
+ * `pl` is an OPAQUE payload the channel carries beside the envelope and never
+ * interprets: the bytes a `req` handler receives as its second argument, or
+ * the bytes a {@link PayloadReply} put on a `res`. On the wire it is the
+ * frame's last msgpack key (`frame-codec.ts` `encodeFrameHead`), which is
+ * what lets a router forward it as a view without decoding it.
+ */
 export type Frame = {
     readonly k: 'req';
     readonly id: number;
     readonly body: unknown;
+    readonly pl?: Uint8Array;
 } | {
     readonly k: 'res';
     readonly id: number;
     readonly ok: true;
     readonly body: unknown;
+    readonly pl?: Uint8Array;
 } | {
     readonly k: 'res';
     readonly id: number;
@@ -18,8 +28,27 @@ export type Frame = {
     readonly k: 'evt';
     readonly body: unknown;
 };
-export type RequestHandler = (body: unknown) => Promise<unknown>;
+/**
+ * A request handler receives the envelope body and, when the request carried
+ * one, its opaque payload. It may answer with a plain value or with a
+ * {@link PayloadReply}; a plain value travels inline exactly as before.
+ */
+export type RequestHandler = (body: unknown, payload?: Uint8Array) => Promise<unknown>;
 export type EventHandler = (body: unknown) => void;
+/**
+ * An answer that carries an opaque payload beside its body.
+ *
+ * A CLASS rather than a shape so the channel can tell it from a provider's
+ * ordinary `{ body, payload }` return value by identity, never by duck-typing:
+ * a cap method is free to return an object with those two keys and it must
+ * travel inline like any other. `request()` resolves with one of these only
+ * when the peer's `res` frame carried a payload.
+ */
+export declare class PayloadReply {
+    readonly body: unknown;
+    readonly payload: Uint8Array;
+    constructor(body: unknown, payload: Uint8Array);
+}
 /** Per-request options a {@link LocalChannel} implementation may honour. */
 export interface LocalRequestOptions {
     /**
@@ -29,6 +58,13 @@ export interface LocalRequestOptions {
      * not cut short.
      */
     readonly timeoutMs?: number;
+    /**
+     * Opaque bytes to carry beside `body`. The peer's request handler receives
+     * them as its second argument; the channel never reads them. An
+     * implementation without a wire (in-process, test doubles) may hand them
+     * through as-is.
+     */
+    readonly payload?: Uint8Array;
 }
 /** A bidirectional request/response + one-way event channel over one socket. */
 export interface LocalChannel {
@@ -48,6 +84,13 @@ export interface LocalChannel {
      * finds it absent reports the peer as unmeasured rather than as silent.
      */
     readTraffic?(): SocketTrafficSample;
+    /**
+     * Bytes written to the peer that it has not yet taken, read live. OPTIONAL
+     * for the same reason as {@link readTraffic}: only a real socket has a
+     * write queue. A reader that finds it absent reports the peer's queue as
+     * unmeasured — never as zero (D393).
+     */
+    queuedBytes?(): number;
 }
 /** Parent side: listens and hands a channel per accepted child connection. */
 export interface LocalTransportServer {

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

@@ -1,5 +1,5 @@
 import { Socket } from 'node:net';
-import { LocalChannel, RequestHandler, EventHandler } from './local-transport.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 +16,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;
@@ -61,6 +63,22 @@ 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.
+     */
     private send;
     private onData;
     /**