@camstack/system 1.2.218 → 1.2.220

package/dist/kernel/transport/cap-action-census.d.ts

@@ -0,0 +1,218 @@
+/**
+ * cap-action-census — which cap METHOD moves the bytes, and how much of each
+ * one this parent forwarded without ever reading it.
+ *
+ * ## Why `socket-traffic.ts` keeps no method, and why this is a separate file
+ *
+ * Read `socket-traffic.ts` before changing anything here. It does not omit the
+ * method by oversight; three separate properties of that file forbid it, and
+ * this module exists because each can be answered somewhere else rather than
+ * relaxed:
+ *
+ * 1. **The channel does not know one.** `SocketChannel` sees a {@link
+ *    import('./local-transport.js').Frame} — `{ k, id, body }` — and `body` is
+ *    `unknown` by contract. The cap envelope lives one layer up, in
+ *    `child-cap-protocol.ts`. A counter inside the channel that reached into
+ *    `body.capName` would make the transport depend on the protocol it
+ *    carries. So the LABEL is supplied from above ({@link capActionLabel}) and
+ *    only the BYTES come from the wire.
+ *
+ * 2. **A `res` frame carries no method at all** — only its correlation `id`.
+ *    And the responses are the whole question: measured 2026-09-11, hub-main
+ *    wrote 144–262 MB/min to `hub/pipeline-analytics` on 1 966–2 411 responses
+ *    (a 73–108 kB mean) against 2 kB of requests. Charging those bytes to a
+ *    method is therefore not a counter at all, it is a CORRELATION: the label
+ *    is taken off the `req`, held against its id, and settled when the `res`
+ *    for that id is written. `socket-traffic.ts` is a two-addition hot path
+ *    with no state per message; this is state per in-flight request, and the
+ *    two do not belong in one file.
+ *
+ * 3. **Cardinality.** `recordSocketFrame` costs 2.37–2.41 ns and allocates
+ *    nothing, on a path that runs ~44 000 times a second. Its docblock's rule
+ *    — "an instrument that changes what it measures is not an instrument" — is
+ *    the binding constraint, and a naive per-method map breaks it twice: a Map
+ *    lookup and a counter object per method NAME, where the names arrive off
+ *    the wire and are therefore unbounded in principle.
+ *
+ * ## What was chosen for the cardinality, and why not a sample
+ *
+ * **Full per-method counters in memory, bounded per peer; top-N only at REPORT
+ * time.** The constraint that is real is the LINE's width (D446: Loki reads
+ * these prefixes), not the map's size — and those are different limits:
+ *
+ *  - *Measured shape.* The cap-usage graph already keeps `(caller, provider,
+ *    cap, method)` and, queried on this hub on 2026-09-11, holds **53 rows for
+ *    the whole cluster** — 14 of them for `pipeline-analytics`, whose top three
+ *    caps are 2 077 of its 2 141 calls/min. A peer uses a handful of methods,
+ *    not hundreds. ~39 peers × a few dozen labels is a few hundred counter
+ *    objects, each allocated ONCE and then only incremented. That is not an
+ *    explosion; it is smaller than the `childEventStats` map next to it.
+ *  - *The unbounded case is still refused*, because "measured today" is not a
+ *    guarantee: {@link MAX_CAP_ACTIONS_PER_PEER} caps the distinct labels per
+ *    peer and everything past it is charged to ONE
+ *    {@link CAP_ACTION_OVERFLOW_LABEL} bucket. The bytes are never dropped —
+ *    they stop being *named*, which is a different and visible failure.
+ *  - *A sampled window was rejected.* The flow this exists to name is few,
+ *    enormous responses: 1 966 responses carrying 144 MB. A 1-in-N sample of a
+ *    distribution whose top item fires ~30 times a minute answers "probably"
+ *    to a question that has an exact answer for the price of an integer add.
+ *    And a sample that misses a method would report it as zero bytes, which is
+ *    exactly the `null`-vs-`0` confusion D393 exists to forbid.
+ *  - *A byte THRESHOLD was rejected for the same reason in reverse*: a
+ *    threshold decides what to keep before it knows the window's shape, so the
+ *    method that only matters during an episode is the one it discards. Rank
+ *    at report time, when the totals are known.
+ *
+ * ## What a reader may conclude, and what it may not
+ *
+ * {@link CapActionWindow.labelledBytes} against `totalBytes` is the census's
+ * own coverage, and it is on the line. Bytes this parent moved that carry no
+ * cap envelope (`register`, `addon-call`, log and event frames) are charged to
+ * {@link CAP_ACTION_UNLABELLED} rather than omitted: an instrument that
+ * silently drops what it cannot classify reports a clean attribution of a
+ * fraction it never names. A window whose `labelledBytes` is a small part of
+ * `totalBytes` has NOT attributed the plane, and says so.
+ *
+ * ## Mutation, as in `socket-traffic.ts`
+ *
+ * Same deliberate exception, for the same measured reason: the counters are
+ * plain mutable numbers written only by {@link CapActionCensus.record} and
+ * friends, and read only through {@link CapActionCensus.read}, which COPIES.
+ * The copy is not a nicety — the reporting layer subtracts the previous
+ * reading, and a `read()` that handed back the live maps would advance the
+ * baseline together with the counters and report every window as empty.
+ */
+/**
+ * The channel's half of the census — see `socket-channel.ts` for the seam.
+ *
+ * The channel owns the BYTES and the request↔response correlation and NOTHING
+ * else: it sees `{ k, id, body }` with `body: unknown`, and a `res` frame
+ * carries no method at all. So the layer that understands the protocol supplies
+ * {@link CapActionChannelObserver.label}, and the channel calls it once per
+ * `req` frame, holds the answer against the frame's id, and settles it with
+ * {@link CapActionChannelObserver.record} when the matching `res` is written or
+ * read. A `null` label is still recorded — those bytes crossed, and a census
+ * that drops what it cannot name reports a clean attribution of a fraction it
+ * never mentions.
+ *
+ * Declared HERE rather than in the channel so `local-transport.ts` can name it
+ * on {@link import('./local-transport.js').LocalChannel} without importing the
+ * implementation that satisfies it.
+ */
+export interface CapActionChannelObserver {
+    /** `<cap>.<method>`, or `null` for a frame that carries no cap envelope. */
+    label(body: unknown): string | null;
+    /** One completed request/response pair, its on-the-wire bytes both ways. */
+    record(label: string | null, reqBytes: number, resBytes: number): void;
+}
+/** One action's cumulative cost on one peer's channel. Mutable by design. */
+export interface CapActionCounters {
+    /** Completed request/response pairs. */
+    calls: number;
+    /** On-the-wire bytes of the requests, prefix and payload included. */
+    reqBytes: number;
+    /** On-the-wire bytes of the answers. */
+    resBytes: number;
+    /** Of `calls`, how many this parent forwarded without reading (D448). */
+    raw: number;
+    /** Of `calls`, how many it materialised the args of. */
+    decoded: number;
+}
+/** An immutable reading of one action. */
+export interface CapActionSample {
+    readonly calls: number;
+    readonly reqBytes: number;
+    readonly resBytes: number;
+    readonly raw: number;
+    readonly decoded: number;
+}
+/** One complete reading: peer → action → counters. */
+export type CapActionReading = ReadonlyMap<string, ReadonlyMap<string, CapActionSample>>;
+/** A process that has never read the census. */
+export declare const EMPTY_CAP_ACTION_READING: CapActionReading;
+/**
+ * Bytes that crossed on a frame carrying no cap envelope.
+ *
+ * Named rather than omitted so the census's coverage is readable off its own
+ * output: `register`, `addon-call`, log frames and the event fan-out all land
+ * here. A census that reported only what it could name would look like a
+ * complete attribution of whatever share it happened to cover.
+ */
+export declare const CAP_ACTION_UNLABELLED = "(unlabelled)";
+/** Bytes of actions past {@link MAX_CAP_ACTIONS_PER_PEER} on one peer. */
+export declare const CAP_ACTION_OVERFLOW_LABEL = "(overflow)";
+/**
+ * Distinct named actions kept per peer before the overflow bucket takes over.
+ *
+ * Sixty-four against a measured worst case of 14 (`pipeline-analytics`, the
+ * heaviest peer on this hub, 2026-09-11) — four times the observed shape, so a
+ * peer has to change character before it overflows, and a bound that is never
+ * reached in practice still forbids the unbounded growth a wire-supplied key
+ * makes possible in principle.
+ */
+export declare const MAX_CAP_ACTIONS_PER_PEER = 64;
+/**
+ * `<cap>.<method>` for a cap envelope, `null` for anything else.
+ *
+ * Both directions are labelled by the same function: a child's `cap-call-out`
+ * and the parent's `cap-call` carry `capName` + `method` in the same two keys,
+ * so one predicate covers the whole plane. Anything else — a `register`, an
+ * `addon-call`, a log or an event — is deliberately unlabelled; see
+ * {@link CAP_ACTION_UNLABELLED} for where its bytes go.
+ *
+ * Cost: two property reads, two `typeof`s and one concatenation of two short
+ * strings, called once per `req` frame (not per frame). Against the
+ * `encodeFrame` it sits beside — 1 948–1 975 ns on a 0.33 kB body — it is
+ * noise, and unlike `recordSocketFrame` it is not on the `evt` path at all.
+ */
+export declare function capActionLabel(body: unknown): string | null;
+/** Which half of D448's census one call fell on. */
+export type CapActionForwardKind = 'raw' | 'decoded';
+/** The census as its writers see it. */
+export interface CapActionCensus {
+    /** One completed request/response pair on `peerId`, charged to `action`. */
+    record(peerId: string, action: string, reqBytes: number, resBytes: number): void;
+    /** How `action`'s most recent call was routed — see {@link CapActionForwardKind}. */
+    recordForward(peerId: string, action: string, kind: CapActionForwardKind): void;
+    /** Bytes on a frame that carried no cap envelope. */
+    recordUnlabelled(peerId: string, bytes: number): void;
+    /** Drop a peer's counters when its channel closes for good. */
+    forget(peerId: string): void;
+    /** A COPY of the counters — see the module docblock on why it must be one. */
+    read(): CapActionReading;
+}
+export declare function createCapActionCensus(): CapActionCensus;
+/** One (peer, action) pair over the window since the previous reading. */
+export interface CapActionDelta {
+    readonly peerId: string;
+    readonly action: string;
+    readonly calls: number;
+    readonly reqBytes: number;
+    readonly resBytes: number;
+    readonly raw: number;
+    readonly decoded: number;
+}
+/** The census over one heartbeat window. */
+export interface CapActionWindow {
+    /**
+     * Heaviest first by `reqBytes + resBytes`, at most the requested N.
+     *
+     * By BYTES and never by calls, for the reason D454 records: the flow this
+     * exists to name is few, enormous responses, and a ranking by count cannot
+     * see it by construction.
+     */
+    readonly top: readonly CapActionDelta[];
+    /** Bytes the census could put a cap method on, this window. */
+    readonly labelledBytes: number;
+    /** Every byte it saw, named or not. `labelled/total` is its own coverage. */
+    readonly totalBytes: number;
+}
+/**
+ * Subtract the previous reading from the current one.
+ *
+ * A peer whose runner RESPAWNED reconnects under the same id with counters
+ * that went backwards. Clamped at 0, exactly as `diffSocketPlane` clamps for
+ * the same reason: its traffic in that window is genuinely unknown, and a
+ * negative number on a rate reads as a broken meter.
+ */
+export declare function diffCapActionCensus(before: CapActionReading, current: CapActionReading, topN: number): CapActionWindow;

package/dist/kernel/transport/cap-child-index.d.ts

@@ -0,0 +1,49 @@
+import { ChildCapDescriptor } from './child-cap-protocol.js';
+/**
+ * One connected child as the index reads it: its id and the cap manifest it
+ * registered. A structural subset of `LocalChildRegistry`'s own child entry,
+ * so the index can be built from `children.values()` directly and unit-tested
+ * without a socket.
+ */
+export interface CapIndexEntry {
+    readonly childId: string;
+    readonly caps: readonly ChildCapDescriptor[];
+}
+/**
+ * The two questions `resolveChildId` asks, answered in O(1).
+ *
+ * Deliberately NOT "resolve a child": the operator's `setActiveSingleton`
+ * preference is read at CALL time from the capability registry and can change
+ * without any child connecting or leaving, so the index must not be allowed to
+ * hold an answer that depends on it. It holds only what the `children` map
+ * says, which is the same thing that invalidates it.
+ */
+export interface CapChildIndex {
+    /** The FIRST child owning the exact `(capName, deviceId)` pair, or null. */
+    deviceOwner(capName: string, deviceId: number): string | null;
+    /**
+     * Every child owning a deviceId-LESS descriptor for `capName`, in children
+     * insertion order (so `[0]` is the first-registered), each named once.
+     */
+    singletonCandidates(capName: string): readonly string[];
+}
+/**
+ * Build the `(cap, device?) → child` index from the connected children.
+ *
+ * A PURE function of what it is handed — it captures nothing, subscribes to
+ * nothing and cannot be updated in place. That is the whole safety argument
+ * (D3, D457): the only way to change what it says is to build a new one from
+ * the `children` map, so an index can never name a child that map has already
+ * dropped. An incremental index — add on register, remove on close — would be
+ * a second registry that can disagree with the first, and a stale one routes
+ * to a dead runner, which is strictly worse than a slow scan.
+ *
+ * Cost: O(children × descriptors), paid once per mutation of the children map
+ * (a register, a re-register, a disconnect) rather than once per cap call.
+ *
+ * The two tiers stay separate, exactly as the scan had them: a device lookup
+ * is never answered from a deviceId-less descriptor. `resolveChildId` owns
+ * the fallback from tier 1 to tier 2, and folding it in here would make it
+ * unreachable.
+ */
+export declare function buildCapChildIndex(entries: Iterable<CapIndexEntry>): CapChildIndex;

package/dist/kernel/transport/cap-routing-hints.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The routing facts a parent reads OUT OF a cap call's args.
+ *
+ * `LocalChildRegistry` routes a child's `cap-call-out` on two things it used
+ * to read straight out of `args`: an inline `nodeId` (the historical per-call
+ * node pin — `extractNodeId`) and an `addonId` selector on a collection cap
+ * (`addonPinOf`). Under raw-forward the parent never decodes `args`, so the
+ * SENDER lifts those two fields into the envelope, and the parent routes on
+ * the lifted copy in both modes — one code path, whichever way the args
+ * travelled.
+ *
+ * Only top-level string fields are lifted, which is exactly what the two
+ * readers ever looked at. Nothing else about the args is visible to the
+ * parent under raw-forward, and that is the point.
+ */
+export interface CapRoutingHints {
+    readonly nodeId?: string;
+    readonly addonId?: string;
+}
+/** Lift {@link CapRoutingHints} from a call's args. Never throws. */
+export declare function liftRoutingHints(args: unknown): CapRoutingHints;

package/dist/kernel/transport/child-cap-protocol.d.ts

@@ -1,4 +1,5 @@
 import { ChildCustomActionCatalogs, CustomActionCaller, IReadinessRegistryRecord, LogLevel, LogTags, SystemEvent } from '@camstack/types';
+import { CapRoutingHints } from './cap-routing-hints.js';
 /**
  * Routing descriptor a child sends so the parent can route cap calls to it.
  * The provider implementation never crosses the wire — only these keys do.
@@ -47,6 +48,22 @@ export interface RegisterMessage {
      * and from a legacy child; absent means "not described yet", never "none".
      */
     readonly customActions?: ChildCustomActionCatalogs;
+    /**
+     * The child can RECEIVE a `cap-call` whose args ride as an opaque payload
+     * beside the envelope (raw-forward), and answer with one. Declared, never
+     * assumed: a parent forwards a payload only to a child that said so, and
+     * decodes it for one that did not. Absent = legacy child = inline args.
+     */
+    readonly rawForward?: true;
+}
+/**
+ * Parent → child answer to `register`. `rawForward` says the parent accepts
+ * a `cap-call-out` whose args ride as a payload — a child packs its args
+ * only after seeing it. Absent = legacy parent = inline args.
+ */
+export interface RegisterAck {
+    readonly ok: true;
+    readonly rawForward?: true;
 }
 /**
  * Child → parent, fire-and-forget: the child's category-pattern subscription
@@ -59,12 +76,21 @@ export interface EventSubUpdateMessage {
     readonly kind: 'event-sub';
     readonly patterns: readonly string[];
 }
-/** Child → parent outbound cap invocation — the child asks the parent to route a cap call it does not own. */
+/**
+ * Child → parent outbound cap invocation — the child asks the parent to route
+ * a cap call it does not own.
+ *
+ * Under raw-forward `args` is ABSENT from the envelope: the packed args ride
+ * as the frame's opaque payload and `hints` carries the two fields the parent
+ * routes on. A legacy child sends `args` inline and no `hints`; the parent
+ * lifts the hints itself. See `cap-routing-hints.ts`.
+ */
 export interface CapCallOutMessage {
     readonly kind: 'cap-call-out';
     readonly capName: string;
     readonly method: string;
-    readonly args: unknown;
+    readonly args?: unknown;
+    readonly hints?: CapRoutingHints;
     readonly deviceId?: number;
     /**
      * Optional per-call node pin (out-of-band; NOT part of the validated method

package/dist/kernel/transport/frame-codec.d.ts

@@ -1,5 +1,54 @@
 /** Encode a value as a length-prefixed (4-byte big-endian) MsgPack frame. */
 export declare function encodeFrame(value: unknown): Buffer;
+/**
+ * The key under which an opaque payload rides on a frame — see
+ * {@link encodeFrameHead}. Short on purpose: it is written once per frame by
+ * hand, and it is the one msgpack key on this plane a decoder must never
+ * interpret.
+ */
+export declare const PAYLOAD_KEY = "pl";
+/**
+ * Encode the HEAD of a frame that carries an opaque payload: the length
+ * prefix, the msgpack envelope with one extra key ({@link PAYLOAD_KEY}), and
+ * the `bin 32` header for the payload — everything but the payload bytes
+ * themselves, which the caller writes straight after it.
+ *
+ * ## Why the payload is the frame's TAIL and not a field
+ *
+ * hub-main routes every sibling↔sibling call. Until this existed it decoded
+ * the whole request (args included), built a new message, and re-encoded it
+ * — walking a 13.5 KB PCM chunk or a 2 000-row settings answer twice on the
+ * one thread that serves every tRPC request, and allocating an `Encoder`
+ * buffer that doubles from 2 KiB up to the body's size on every write
+ * (D441: ~27 % of hub-main's busy time in msgpack decode, ~6 % in encode,
+ * and the churn that fed a 29.5 % GC share).
+ *
+ * With the payload appended as the LAST key of the map, the receiver's
+ * ordinary msgpack decode yields it as a zero-copy VIEW of the frame
+ * (`@msgpack/msgpack` decodes `bin` as `subarray`), the router reads only the
+ * envelope, and forwarding is: encode a ~60-byte head, write it, write the
+ * view. The wire stays plain msgpack — a peer that never heard of payloads
+ * decodes `{ …frame, pl: <bytes> }` and can be told, at register, not to be
+ * sent one.
+ *
+ * ## The one hand-written msgpack in this repository
+ *
+ * `@msgpack/msgpack` has no "encode a map, then append a key" API, so the
+ * envelope is encoded normally and its `fixmap` count byte is bumped by one
+ * before the key and the `bin 32` header are appended. That patch is only
+ * valid for a `fixmap` (≤ 15 keys); a `Frame` has at most four, and anything
+ * else is refused rather than silently corrupted.
+ */
+export declare function encodeFrameHead(frame: Record<string, unknown>, payload: Uint8Array): Buffer;
+/**
+ * Serialise a value into the bytes a payload carries. The SAME options as the
+ * envelope codec, so `undefined` properties are omitted rather than turned
+ * into `null` — a `z.void()` cap output must read back as `undefined` on the
+ * far side exactly as it did when it travelled inline.
+ */
+export declare function packPayload(value: unknown): Uint8Array;
+/** Inverse of {@link packPayload}. A `bin` inside decodes as a view of `bytes`. */
+export declare function unpackPayload(bytes: Uint8Array): unknown;
 /**
  * Reassembles length-prefixed MsgPack frames from a byte stream.
  *

package/dist/kernel/transport/index.d.ts

@@ -2,6 +2,8 @@ export type { Frame, RequestHandler, EventHandler, LocalChannel, LocalTransportS
 export { encodeFrame, FrameDecoder } from './frame-codec.js';
 export type { SocketDirectionCounters, SocketDirectionSample, SocketMessageKind, SocketTrafficSample, } from './socket-traffic.js';
 export { createSocketDirectionCounters, EMPTY_SOCKET_DIRECTION, recordSocketFrame, sampleSocketDirection, socketDirectionBytes, socketDirectionMessages, } from './socket-traffic.js';
+export type { CapActionCensus, CapActionChannelObserver, CapActionDelta, CapActionReading, CapActionSample, CapActionWindow, } from './cap-action-census.js';
+export { CAP_ACTION_OVERFLOW_LABEL, CAP_ACTION_UNLABELLED, capActionLabel, createCapActionCensus, diffCapActionCensus, EMPTY_CAP_ACTION_READING, MAX_CAP_ACTIONS_PER_PEER, } from './cap-action-census.js';
 export { localEndpointPath } from './local-endpoint-path.js';
 export { SocketChannel } from './socket-channel.js';
 export { UdsLocalTransportServer, UdsLocalTransportClient } from './uds-local-transport.js';

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

@@ -67,6 +67,13 @@ export declare class LocalChildClient {
     private latestCustomActions;
     /** Events and logs queued while the channel is not yet open. */
     private readonly pendingEmits;
+    /**
+     * Whether the parent acknowledged raw-forward at `register`. Until it has,
+     * `callOut` sends args inline exactly as every child always did — a legacy
+     * parent would decode a payload-borne call to `args: undefined` and run the
+     * provider on nothing, silently. Re-read on every re-register.
+     */
+    private parentRawForward;
     /** Handler for parent→child events. Registered via `onEvent`. */
     private eventHandler;
     /**

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

@@ -1,8 +1,33 @@
 import { IReadinessRegistryRecord, SystemEvent } from '@camstack/types';
 import { CapUsageCallRecord } from '../moleculer/cap-usage-registry.js';
+import { CapActionReading } from './cap-action-census.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;
+}
+/**
+ * Peer id the action census charges frames that arrived before `register`.
+ *
+ * One frame per connection, and it is named rather than dropped: a census is
+ * only worth its coverage, and coverage you cannot see is coverage you cannot
+ * check.
+ */
+export declare const PRE_REGISTER_PEER_ID = "(pre-register)";
 /**
  * Fan-out mode for parent→child event delivery, from the
  * `CAMSTACK_UDS_EVENT_FANOUT` env (read once at registry construction):
@@ -104,6 +129,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 +149,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 +231,17 @@ 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;
+    /**
+     * The per-ACTION byte census (D456). `ForwardCensus` above is the same
+     * question asked of the whole plane; this one asks it per `<cap>.<method>`,
+     * beside the bytes that method actually moved. Both are kept: `socketFwd=`
+     * says whether the negotiation is working at all, and a `raw=0` on ONE
+     * method with `raw>0` on its neighbours is a different fault.
+     */
+    private readonly actionCensus;
     /** See {@link LocalChildRegistryOptions.capTimeoutMs}. */
     private readonly capTimeoutMs?;
     /** See {@link LocalChildRegistryOptions.capUsageObserver}. */
@@ -211,6 +254,12 @@ export declare class LocalChildRegistry {
     private readonly childEventStats;
     /** Last pattern-set string logged per child, to dedup the INFO line. */
     private readonly loggedPatternSet;
+    /**
+     * Derived `(cap, device?) → child` index over {@link children}, or `null`
+     * when it must be rebuilt. See {@link capIndex} for why it is a cache and
+     * never a registry (D3, D457).
+     */
+    private capChildIndex;
     /**
      * Accepts either a plain positional `server` argument (backward-compatible)
      * or a full `LocalChildRegistryOptions` object.
@@ -242,6 +291,28 @@ 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;
+    /**
+     * Cumulative per-action byte census: peer → `<cap>.<method>` → bytes, calls
+     * and the raw/decoded split. A COPY (`cap-action-census.ts` explains why it
+     * must be one); the heartbeat subtracts the previous reading.
+     *
+     * This is the instrument D454 closed by asking for. `socketTopBytes=` names
+     * the peer that moves the bytes and `txkB=` says they are responses; neither
+     * can say WHICH method originates them, and after raw-forward the bytes that
+     * cross are no longer the proxy for what hub-main pays — 85.7 % of sibling
+     * calls cross unread. What costs is what hub-main LOOKS at, and that is the
+     * `decoded` half of an entry, next to the bytes it carried.
+     */
+    readActionCensus(): CapActionReading;
     /**
      * The regime the counters above were produced under, read once from
      * `CAMSTACK_UDS_EVENT_FANOUT` at construction.
@@ -331,10 +402,33 @@ export declare class LocalChildRegistry {
      * is not the registry.
      */
     private recordCapUsage;
-    /** First child whose cap manifest contains a descriptor matching `predicate`. */
-    private findChildId;
-    /** Every child whose cap manifest contains a descriptor matching `predicate`. */
-    private findAllChildIds;
+    /**
+     * The cap index over the CURRENT children, rebuilt on first use after any
+     * mutation of {@link children}.
+     *
+     * This replaced a linear walk of every child's cap manifest per
+     * `cap-call-out`, measured at **7.1 % of hub-main's busy main thread**
+     * across 39 children (D456). Why it did not exist before is the whole
+     * design: what it indexes moves — a runner is replaced on every update, a
+     * crash respawns one, a child re-registers with a replacement manifest after
+     * init — and an index that names a dead child routes work into a socket
+     * nobody is reading, which is strictly worse than a slow scan.
+     *
+     * So it is not maintained; it is DISCARDED. `buildCapChildIndex` is a pure
+     * function of `children.values()`, the only two writers of that map
+     * ({@link invalidateCapIndex}'s call sites) drop the index in the same
+     * statement, and nothing else can construct one. There is no add-on-register
+     * / remove-on-close path that could disagree with the map — i.e. no shadow
+     * registry (D3): the map remains the single authority and this holds no fact
+     * it does not.
+     *
+     * The operator's active-singleton preference is deliberately NOT indexed —
+     * it changes without any child connecting or leaving, so `resolveChildId`
+     * reads it live and the index only supplies the candidate list.
+     */
+    private capIndex;
+    /** Drop the derived index. MUST follow every write to {@link children}. */
+    private invalidateCapIndex;
     /**
      * Does the named child currently provide `(capName, deviceId?)`?
      *

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

@@ -1,14 +1,25 @@
+import { CapActionChannelObserver } from './cap-action-census.js';
 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 +29,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 +59,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 +85,21 @@ 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;
+    /**
+     * Wire the per-action byte census (`cap-action-census.ts`). OPTIONAL for the
+     * same reason as {@link readTraffic}: only a real socket has bytes to
+     * charge. A registry whose channel does not implement it keeps no per-action
+     * numbers for that peer, and the report omits the field rather than printing
+     * a zero (D393).
+     */
+    observeActions?(observer: CapActionChannelObserver): void;
 }
 /** Parent side: listens and hands a channel per accepted child connection. */
 export interface LocalTransportServer {