@camstack/system 1.2.217 → 1.2.219

package/dist/kernel/array-buffer-census.d.ts

@@ -0,0 +1,122 @@
+/** One power-of-two bucket of the live set: every buffer with `byteLength <= upToBytes`
+ *  and above the previous bucket. */
+export interface ArrayBufferSizeBucket {
+    readonly upToBytes: number;
+    readonly count: number;
+    readonly bytes: number;
+}
+/** One exact byteLength and how much of the live set it accounts for. */
+export interface ArrayBufferExactSize {
+    readonly byteLength: number;
+    readonly count: number;
+    readonly bytes: number;
+}
+export interface ArrayBufferCensusReport {
+    /** Live `ArrayBuffer` objects reachable after the census's own GC. */
+    readonly count: number;
+    /** Their total `byteLength`. */
+    readonly bytes: number;
+    /** Buffers whose backing store is gone (`byteLength === 0`, detached). */
+    readonly detached: number;
+    /** Largest buckets first, by bytes. */
+    readonly buckets: readonly ArrayBufferSizeBucket[];
+    /** Largest exact sizes first, by bytes. */
+    readonly topSizes: readonly ArrayBufferExactSize[];
+}
+/** Take a census. Injectable so the heartbeat's gating is testable without an inspector. */
+export type ArrayBufferCensus = () => Promise<ArrayBufferCensusReport>;
+/**
+ * Take the census once `arrayBuffers` has been at or above this for
+ * {@link ARRAY_BUFFER_CENSUS_SUSTAIN_MS}.
+ *
+ * 512 MB. The two 2026-09-10 episodes crossed it 25 and 8 minutes in; the
+ * routine reading in six hours of 2-second samples around them was 18–100 MB
+ * with single-sample spikes to 479 MB, and the process's floor after every
+ * compaction is 12–18 MB. A dead-buffer sawtooth between major GCs (measured
+ * up to 3.65 GB on 2026-08-08 when the heap had 4 GB of headroom) cannot reach
+ * it while GC runs every few seconds — and if one did, the census would SAY
+ * so: it reports the live total after its own GC next to the raw reading.
+ */
+export declare const ARRAY_BUFFER_CENSUS_THRESHOLD_MB = 512;
+/**
+ * How long the reading must stay above the threshold before a census is taken.
+ *
+ * 60 s = 30 probes at the 2 s cadence. A burst that a scavenge or the next
+ * major GC returns never pays a forced GC; an episode climbing at the slowest
+ * rate measured (20 MB/min) is still 20 MB higher by the time it is measured,
+ * which is nothing against the threshold.
+ */
+export declare const ARRAY_BUFFER_CENSUS_SUSTAIN_MS = 60000;
+/**
+ * Minimum spacing between two censuses.
+ *
+ * 30 minutes: the second episode ran 76 minutes, so it would have produced
+ * three readings — enough to see the shape change (or not) as it grew — at a
+ * cost the router already pays six times an hour for the reclaim pass.
+ */
+export declare const ARRAY_BUFFER_CENSUS_COOLDOWN_MS: number;
+/**
+ * A drop of at least this share of the threshold between two consecutive
+ * probes, from a reading that had been SUSTAINED above the threshold, is a
+ * RELEASE — the boundary both episodes crossed with no line, and the one line
+ * that lets the release be correlated with whatever else the process logged
+ * that second. Sustained, not merely above: a one-probe spike that the next
+ * scavenge sweeps (a 1.3 GB burst in 11 s was measured on 2026-08-29) is not
+ * an episode ending, and a WARN for every one of those would bury the line
+ * this exists to produce.
+ */
+export declare const ARRAY_BUFFER_RELEASE_MIN_DROP_RATIO = 0.5;
+export interface ArrayBufferCensusGateOptions {
+    readonly thresholdMb?: number;
+    readonly sustainMs?: number;
+    readonly cooldownMs?: number;
+}
+/** What one probe reading means to the gate. */
+export type ArrayBufferCensusVerdict = {
+    readonly kind: 'hold';
+}
+/** Take a census now. `reason` is printed on the resulting line. */
+ | {
+    readonly kind: 'take';
+    readonly reason: string;
+}
+/** The live set was released between this probe and the previous one. */
+ | {
+    readonly kind: 'released';
+    readonly fromMb: number;
+    readonly toMb: number;
+};
+export interface ArrayBufferCensusGate {
+    /** Judge one reading. A `take` verdict starts the cooldown. */
+    readonly observe: (arrayBuffersMb: number, at: number) => ArrayBufferCensusVerdict;
+}
+/**
+ * The pure decision: threshold, sustain, cooldown, release — testable without
+ * allocating a gigabyte or forcing a GC.
+ */
+export declare function createArrayBufferCensusGate(options?: ArrayBufferCensusGateOptions): ArrayBufferCensusGate;
+/** The inspector answers `unknown`; the report is trusted only once it has this shape. */
+export declare function isArrayBufferCensusReport(value: unknown): value is ArrayBufferCensusReport;
+/**
+ * The real census: an in-process inspector session, opened for the call and
+ * closed after it, so no session is left listening between censuses.
+ *
+ * Every remote object it creates is released before the session closes; a
+ * failure anywhere still disconnects. The session is in-process — nothing
+ * listens on a port, nothing outside this process can reach it.
+ */
+export declare function createInspectorArrayBufferCensus(): ArrayBufferCensus;
+/** What a census line needs beyond the report. */
+export interface ArrayBufferCensusContext {
+    /** `process.memoryUsage().arrayBuffers` at the probe that triggered it. */
+    readonly rawMb: number;
+    readonly tookMs: number;
+    /** The gate's `take` reason. */
+    readonly reason: string;
+}
+/**
+ * The census line. `live` is what survived the census's own GC; `raw` is the
+ * reading that triggered it — when they disagree by a lot, the growth was dead
+ * buffers awaiting a sweep, not a retention, and the line says which.
+ */
+export declare function formatArrayBufferCensus(label: string, report: ArrayBufferCensusReport, context: ArrayBufferCensusContext): string;

package/dist/kernel/custom-action-registry.d.ts

@@ -1,4 +1,4 @@
-import { CustomActionCaller, CustomActionSpec, CustomActionsSpec } from '@camstack/types';
+import { ChildCustomActionCatalogs, CustomActionCaller, CustomActionSpec, CustomActionsSpec } from '@camstack/types';
 type Handler = (action: string, input: unknown, caller?: CustomActionCaller) => Promise<unknown>;
 export interface CustomActionEntry {
     readonly spec: CustomActionSpec;
@@ -19,5 +19,14 @@ export declare class CustomActionRegistry {
     resolve(addonId: string, action: string): CustomActionEntry | null;
     listActions(addonId: string): readonly string[];
     listAddons(): readonly string[];
+    /**
+     * Every registered catalog with its schemas stripped, keyed by addon id —
+     * what a runner puts in its register frame so the hub learns the catalogs
+     * from the process that owns them (D444). `hostedAddonIds` are the addons
+     * this runner hosts: each is present in the result, with an EMPTY catalog
+     * when it registered none, so the parent can say "declares no actions" per
+     * addon instead of guessing from an absent key.
+     */
+    describeAll(hostedAddonIds: readonly string[]): ChildCustomActionCatalogs;
 }
 export {};

package/dist/kernel/heap-watch.d.ts

@@ -1,6 +1,9 @@
 import { EventPlaneReader } from './event-plane-report.js';
-import { SocketPlaneReader } from './socket-plane-report.js';
+import { SocketPlaneCounters, SocketPlaneReader } from './socket-plane-report.js';
+import { MeshPeerQueue, MeshQueueReader } from './moleculer/mesh-queue-report.js';
+import { OutboundQueueGateOptions, OutboundQueueReading } from './outbound-queue-watch.js';
 import { HeapSpaceReader } from './heap-spaces.js';
+import { ArrayBufferCensus, ArrayBufferCensusGateOptions } from './array-buffer-census.js';
 /**
  * What hub-main calls itself in a `[mem]` line.
  *
@@ -606,7 +609,42 @@ export interface HeapWatchProbes {
      * from the parent's side. Only hub-main and an agent's main pass one.
      */
     readonly socketPlane?: SocketPlaneReader;
+    /**
+     * The write queue of every Moleculer TCP socket to a peer node. No default:
+     * only a process with a broker on a real transporter has one. Those sockets
+     * are UNREF'D by Moleculer, so a sum over `_getActiveHandles()` never listed
+     * them — the hole in the 2026-09-10 exclusion of "every socket queue"
+     * (D446). Read on every probe, judged with the UDS queues below.
+     */
+    readonly meshQueue?: MeshQueueReader;
+    /**
+     * Thresholds for the outbound-queue gate. The gate itself is created
+     * whenever {@link socketPlane} or {@link meshQueue} is given; this only
+     * tunes it (tests, or a process with a different notion of "held").
+     */
+    readonly outboundQueue?: OutboundQueueGateOptions;
+    /**
+     * The ArrayBuffer census that ARMS ITSELF. No default: it costs a forced
+     * full GC when it fires, and only hub-main has an episode on record (two
+     * silent linear climbs to 1.3 GB and 5 GB on 2026-09-10, each released in
+     * one instant with no line, the second two hours before the OOM). A runner
+     * that legitimately holds gigabytes of ArrayBuffers (`hub/stream-broker`,
+     * ~900 MB of RTP pre-roll rings) would fire it forever. See
+     * `array-buffer-census.ts` for the gate, the cost and what it is NOT.
+     */
+    readonly arrayBufferCensus?: ArrayBufferCensusProbe;
+}
+/** How the census is wired: the census itself plus the gate's thresholds. */
+export interface ArrayBufferCensusProbe extends ArrayBufferCensusGateOptions {
+    readonly census: ArrayBufferCensus;
 }
+/**
+ * Every outbound queue the heartbeat can reach, as the gate wants them: the
+ * UDS children (only those whose channel keeps a reading — an unmeasured
+ * peer is not a zero) and the mesh writer sockets, each prefixed with its
+ * plane.
+ */
+export declare function outboundQueueReadings(uds: SocketPlaneCounters | undefined, mesh: readonly MeshPeerQueue[] | undefined): readonly OutboundQueueReading[];
 /**
  * Start the heartbeat. Returns a stop function.
  *

package/dist/kernel/moleculer/mesh-queue-report.d.ts

@@ -0,0 +1,51 @@
+/**
+ * mesh-queue-report — the write queue of every Moleculer TCP socket this
+ * process holds to a peer node, on the `[mem]` line (D446).
+ *
+ * ## Why a separate reader
+ *
+ * The UDS plane is measured on the channel (`SocketChannel.queuedBytes`). The
+ * mesh plane is Moleculer's: `TcpTransporter.writer` is a `TcpWriter` whose
+ * `sockets` map holds one `net.Socket` per peer node, opened lazily on the
+ * first send and — this is the point — `unref()`'d at connect
+ * (`transporters/tcp/tcp-writer.js`). An unref'd handle is not in
+ * `process._getActiveHandles()`, so the 2026-09-10 census that summed
+ * `writableLength` over that list and excluded "every socket queue" could not
+ * have seen a backlog to an agent, however large.
+ *
+ * ## What is read, and how carefully
+ *
+ * `broker.transit.tx.writer.sockets` — an internal path, walked with type
+ * guards and never a cast. Every step that is not the expected shape yields
+ * `undefined` for the WHOLE reading: a test broker (`Fake` transporter), a
+ * broker that does not exist yet, a Moleculer whose internals moved. `undefined`
+ * is "this process has no mesh writer to report", never "the mesh is quiet".
+ * A socket entry without numeric `writableLength`/`bytesWritten` is skipped
+ * on its own.
+ */
+/** One peer node's outbound socket, as the writer holds it. */
+export interface MeshPeerQueue {
+    readonly nodeId: string;
+    /** Bytes handed to the socket that the kernel has not taken yet. */
+    readonly queuedBytes: number;
+    /** Lifetime bytes written on this socket — so a stalled queue can be read
+     *  against the peer's normal rate. */
+    readonly bytesWritten: number;
+}
+/** `undefined` = no mesh writer to report (no broker, `Fake` transporter). */
+export type MeshQueueReader = () => readonly MeshPeerQueue[] | undefined;
+/**
+ * Build a reader over a lazily-resolved broker. Wrapped: a broker mid-teardown
+ * may throw, and a diagnostic that can crash the process it watches is worse
+ * than none.
+ */
+export declare function createMeshQueueReader(getBroker: () => unknown): MeshQueueReader;
+/** At most this many nodes named. A cluster has a handful. */
+export declare const MESH_QUEUE_TOP_N = 3;
+/**
+ * The suffix appended to a `[mem]` line — leading space included, empty when
+ * this process has no mesh writer. `meshQueued` is printed always, at zero
+ * included: a quiet mesh is a reading. `meshQueuedTop` names only nodes with
+ * a queue, largest first — a ranked list of zeros is noise.
+ */
+export declare function formatMeshQueue(peers: readonly MeshPeerQueue[] | undefined): string;

package/dist/kernel/outbound-queue-watch.d.ts

@@ -0,0 +1,94 @@
+/**
+ * outbound-queue-watch — an outbound socket queue that HOLDS is named, and its
+ * release is timestamped (D446).
+ *
+ * ## The blind spot this closes
+ *
+ * On 2026-09-10 hub-main's `arrayBuffers` climbed twice at a constant rate
+ * (20 MB/min to 1 264 MB; 63 MB/min for 77 min to 4 968 MB), LIVE across a
+ * forced compaction, with ~4 % of JS heap alongside, and each time released in
+ * one instant with no line from any owner. The investigation excluded "every
+ * socket write queue" by summing `writableLength` over
+ * `process._getActiveHandles()` — 84 MB, all of it the phone's WebSocket.
+ *
+ * `_getActiveHandles()` lists only handles that keep the loop alive. An
+ * UNREF'D socket is not one of them, and Moleculer's `TcpWriter.connect`
+ * unrefs every socket it opens to a peer node (`transporters/tcp/tcp-writer.js`,
+ * `socket.unref()`). So the one outbound plane that writes to another MACHINE
+ * — where a reader that stops draining is the ordinary failure — was never in
+ * the sum. The UDS children were in it, but only as a total, at one instant,
+ * by hand.
+ *
+ * ## What this is
+ *
+ * A pure gate over per-peer queue depths the heartbeat reads on every probe:
+ * the UDS children's `socket.writableLength` (`SocketChannel.queuedBytes`) and
+ * the mesh writer sockets' (`mesh-queue-report.ts`). It says three things and
+ * nothing else:
+ *
+ *  - a peer whose queue has been at or above {@link OUTBOUND_QUEUE_THRESHOLD_BYTES}
+ *    for {@link OUTBOUND_QUEUE_SUSTAIN_MS} is NAMED, with its current and peak
+ *    depth and how long it has held — at most once per
+ *    {@link OUTBOUND_QUEUE_COOLDOWN_MS};
+ *  - a named peer whose queue then falls under half the threshold, or that
+ *    vanishes from the readings (its socket died — which is how a queue is
+ *    dropped in one instant), is reported as RELEASED with its peak and the
+ *    hold, so the release the episodes never logged has a line and a peer;
+ *  - a burst that drains inside the sustain window says nothing. Backpressure
+ *    measures LIVENESS, not identity (D444): a peer momentarily behind is
+ *    coming back.
+ *
+ * ## What it is NOT
+ *
+ * Not a bound. It terminates nothing: a UDS child whose channel is destroyed
+ * loses every in-flight call, and a mesh socket Moleculer reconnects on its
+ * own terms. The WS guard (`ws-slow-consumer-guard.ts`) bounds the one plane
+ * whose client is expendable. Here the line is the deliverable; what to do
+ * about a peer that holds is decided with the peer named, not before.
+ */
+/** 64 MiB. Below this a queue is a burst on a busy peer (the orchestrator's
+ *  channel moves ~1.5 MB/s of audio responses); above it, and held, it is
+ *  retention with a name. */
+export declare const OUTBOUND_QUEUE_THRESHOLD_BYTES: number;
+/** Matches the ArrayBuffer census sustain: a minute above the bound. */
+export declare const OUTBOUND_QUEUE_SUSTAIN_MS = 60000;
+/** A held queue is re-named every ten minutes, not every probe. */
+export declare const OUTBOUND_QUEUE_COOLDOWN_MS: number;
+/** One outbound channel's queue depth at one probe. `peerId` carries its
+ *  plane as a prefix (`uds:<childId>`, `mesh:<nodeId>`). */
+export interface OutboundQueueReading {
+    readonly peerId: string;
+    readonly bytes: number;
+}
+export type OutboundQueueVerdict = {
+    readonly kind: 'sustained';
+    readonly peerId: string;
+    readonly bytes: number;
+    readonly peakBytes: number;
+    readonly heldForMs: number;
+} | {
+    readonly kind: 'released';
+    readonly peerId: string;
+    readonly peakBytes: number;
+    readonly toBytes: number;
+    readonly heldForMs: number;
+    /** The peer left the readings altogether — its socket is gone. */
+    readonly gone: boolean;
+};
+export interface OutboundQueueGateOptions {
+    readonly thresholdBytes?: number;
+    readonly sustainMs?: number;
+    readonly cooldownMs?: number;
+}
+export interface OutboundQueueGate {
+    /** Judge one probe's readings. Every peer is judged on its own. */
+    readonly observe: (readings: readonly OutboundQueueReading[], at: number) => readonly OutboundQueueVerdict[];
+}
+/**
+ * The pure decision — threshold, sustain, cooldown, release, gone — testable
+ * without a socket.
+ */
+export declare function createOutboundQueueGate(options?: OutboundQueueGateOptions): OutboundQueueGate;
+/** The line for one verdict. Both carry the peer, the bytes and the hold;
+ *  the sustained one also says why the older census could not see it. */
+export declare function formatOutboundQueueVerdict(label: string, verdict: OutboundQueueVerdict): string;

package/dist/kernel/socket-plane-report.d.ts

@@ -1,24 +1,52 @@
 import { SocketDirectionSample, SocketTrafficSample } from './transport/socket-traffic.js';
-/** One peer's cumulative traffic, as the channel keeps it. */
+/** One peer's cumulative traffic, as the channel keeps it, plus its outbound
+ *  queue depth at the instant of the read. */
 export interface SocketPeerSample {
     readonly peerId: string;
     readonly tx: SocketDirectionSample;
     readonly rx: SocketDirectionSample;
+    /**
+     * Bytes written to this peer that it has not yet taken — `writableLength`
+     * on the channel, read live (D446). `null` when the channel keeps no such
+     * reading: a measurement that failed is null, never 0 (D393), and the
+     * window counts it as unmeasured rather than as empty.
+     */
+    readonly queuedBytes: number | null;
 }
 /** What `LocalChildRegistry` exposes, structurally — the kernel's heartbeat
  *  must not depend on the transport layer's class. */
 export interface SocketPlaneRegistryChild {
     readonly childId: string;
 }
+/**
+ * How many child→sibling cap calls the parent forwarded without reading
+ * their args (`raw`) against how many it decoded — see
+ * `transport/local-child-registry.ts` `ForwardCensus`. Cumulative on the
+ * registry; a delta on the window.
+ */
+export interface SocketForwardCensus {
+    readonly raw: number;
+    readonly decoded: number;
+}
 export interface SocketPlaneRegistry {
     readonly listChildren: () => readonly SocketPlaneRegistryChild[];
     readonly getChildSocketTraffic: (childId: string) => SocketTrafficSample | null;
+    /** Live outbound queue depth to one child, or `null` when unmeasured. */
+    readonly getChildQueuedBytes: (childId: string) => number | null;
+    /**
+     * The raw-forward census, when the registry keeps one. OPTIONAL: a registry
+     * that predates raw-forward has no such number, and the line must then omit
+     * the field rather than print a zero that reads as "nothing was forwarded".
+     */
+    readonly readForwardCensus?: () => SocketForwardCensus;
 }
 /** One cumulative reading of every measured peer. */
 export interface SocketPlaneCounters {
     readonly peers: readonly SocketPeerSample[];
     /** Connected children, INCLUDING any whose channel keeps no counters. */
     readonly peersConnected: number;
+    /** Cumulative forward census, absent when the registry keeps none. */
+    readonly forward?: SocketForwardCensus;
 }
 /** `undefined` = this process has no local socket plane to report (every forked
  *  runner, and hub-main before the registry exists). */
@@ -57,6 +85,23 @@ export interface SocketPeerDelta {
     readonly tx: SocketDirectionSample;
     readonly rx: SocketDirectionSample;
 }
+/** One peer holding an outbound queue at the instant of the read. */
+export interface SocketPeerQueue {
+    readonly peerId: string;
+    readonly bytes: number;
+}
+/**
+ * The outbound queues at the instant of the read — NOT a delta: a queue is a
+ * level, and the level is the reading (D446).
+ */
+export interface SocketQueueReading {
+    /** Summed over every peer with a reading. */
+    readonly totalBytes: number;
+    /** Peers whose channel keeps no queue reading. Never folded into the total. */
+    readonly unmeasured: number;
+    /** Peers holding a queue, largest first, at most {@link SOCKET_QUEUE_TOP_N}. */
+    readonly top: readonly SocketPeerQueue[];
+}
 /** The whole plane over one heartbeat window. */
 export interface SocketPlaneWindow {
     readonly peersConnected: number;
@@ -67,10 +112,31 @@ export interface SocketPlaneWindow {
     readonly rx: SocketDirectionSample;
     /** Busiest first (tx+rx messages), at most {@link SOCKET_PLANE_TOP_N}. */
     readonly top: readonly SocketPeerDelta[];
+    /**
+     * Heaviest first (tx+rx BYTES), at most {@link SOCKET_PLANE_TOP_N}.
+     *
+     * A separate ranking rather than a replacement, because the two questions
+     * have different answers and both are live: `top` names the peer paying for
+     * round trips (`audio-codec` at 8 379 calls/min of small frames), `topBytes`
+     * names the peer paying for copies and GC. A peer that moves FEW, HUGE
+     * frames is absent from `top` by construction — measured 2026-09-11, the
+     * five peers named by messages left 116 MB/min of hub-main's outbound bytes
+     * with no name on them (D454).
+     */
+    readonly topBytes: readonly SocketPeerDelta[];
+    readonly queued: SocketQueueReading;
+    /** Forwards in this window, absent when the registry keeps no census. */
+    readonly forward?: SocketForwardCensus;
 }
+/** How many queue-holding peers get named. Three: a queue is an exception,
+ *  and the line already carries five names for traffic. */
+export declare const SOCKET_QUEUE_TOP_N = 3;
+/** The queue reading over the current counters — a level, so no baseline. */
+export declare function readSocketQueues(current: SocketPlaneCounters): SocketQueueReading;
 /** Previous cumulative reading, kept between lines. */
 export interface SocketPlaneBaseline {
     readonly peers: ReadonlyMap<string, SocketPeerSample>;
+    readonly forward?: SocketForwardCensus;
 }
 /** A process that has never read the plane. */
 export declare const EMPTY_SOCKET_PLANE_BASELINE: SocketPlaneBaseline;
@@ -92,8 +158,13 @@ export declare function createSocketPlaneMeter(reader: SocketPlaneReader, topN?:
  * is the only way to see an unmeasured channel, and the per-kind splits because
  * "the plane went quiet for a minute" is a reading.
  *
- * `socketTop` is the one conditional field — a ranked list of nothing is noise —
- * and it is a single comma-separated value so the field COUNT does not change
- * from line to line.
+ * `socketTop` is a conditional field — a ranked list of nothing is noise — and
+ * it is a single comma-separated value so the field COUNT does not change from
+ * line to line.
+ *
+ * `socketTopBytes` is the other one, and its PRESENCE is the reading: it is
+ * printed only when ranking by bytes names a peer that ranking by messages
+ * does not. A line without it says the two rankings agree; a line with it says
+ * a peer is moving few, heavy frames and names it (D454).
  */
 export declare function formatSocketPlane(window: SocketPlaneWindow | undefined): string;

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 { CustomActionCaller, IReadinessRegistryRecord, LogLevel, LogTags, SystemEvent } from '@camstack/types';
+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.
@@ -35,6 +36,34 @@ export interface RegisterMessage {
      * `EventSubUpdateMessage` for post-boot updates.
      */
     readonly eventPatterns?: readonly string[];
+    /**
+     * Custom-action catalogs of the addons this child hosts, keyed by addon id,
+     * with the Zod schemas stripped — see `CustomActionDescriptor`. Carried IN
+     * the register frame for the same reason as `eventPatterns`: the parent
+     * learns it race-free, at the post-init re-register, FROM THE PROCESS THAT
+     * OWNS THE ADDON. It is never learned by evaluating the addon's bundle in the
+     * parent (D444: ten 9 MB evaluations in hub-main, none of which produced a
+     * catalog, and every one pinned the evicted graph's module-scope state).
+     * OPTIONAL: absent from the pre-init register (the catalogs do not exist yet)
+     * 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
@@ -47,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
@@ -248,6 +286,8 @@ export interface RegisteredChild {
      * one. See docs/decisions/adr-0188-an-unregister-carries-proof-of-ownership.md.
      */
     readonly incarnation: number;
+    /** See {@link RegisterMessage.customActions}. Absent = not described yet. */
+    readonly customActions?: ChildCustomActionCatalogs;
 }
 /** Arguments to route a cap method call (the `cap-call` message minus its discriminant). */
 export type CapCallInput = Omit<CapCallMessage, 'kind'>;

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/local-child-client.d.ts

@@ -1,4 +1,4 @@
-import { IReadinessRegistryRecord, SystemEvent } from '@camstack/types';
+import { ChildCustomActionCatalogs, IReadinessRegistryRecord, SystemEvent } from '@camstack/types';
 import { AddonCallInput, CapCallInput, ChildCapDescriptor, ChildLogMessage } from './child-cap-protocol.js';
 export interface LocalChildClientOptions {
     /** Parent node id — selects the UDS endpoint this child connects to. */
@@ -56,8 +56,24 @@ export declare class LocalChildClient {
      * subscriptions do), the register carries the real union — even if empty.
      */
     private hasDeclaredEventPatterns;
+    /**
+     * The custom-action catalogs of every hosted addon, once the runner's init
+     * loop has produced them (`updateCaps(caps, catalogs)` at post-init). `null`
+     * until then, and OMITTED from the register frame while null: the parent
+     * reads absence as "not described yet", and a pre-init register must never
+     * look like "this child declares no actions". Kept on the client so every
+     * later re-register (native-cap change, reconnect) re-carries it unchanged.
+     */
+    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;
     /**
@@ -138,7 +154,14 @@ export declare class LocalChildClient {
      * it (device-restore can race ahead of the UDS connect). After `start()`,
      * the set is sent immediately.
      */
-    updateCaps(caps: readonly ChildCapDescriptor[]): Promise<void>;
+    updateCaps(caps: readonly ChildCapDescriptor[], customActions?: ChildCustomActionCatalogs): Promise<void>;
+    /**
+     * The register frame: caps, plus everything a re-register must atomically
+     * re-carry so no separate re-sync can be missed — the subscription union
+     * (omitted if nothing ever declared, which keeps the fail-open shape) and the
+     * custom-action catalogs (omitted until the init loop produced them).
+     */
+    private registerFrame;
     /**
      * Fire-and-forget: send a system event to the parent for forwarding to the
      * hub event bus. Safe to call before `start()` — events are buffered and