@camstack/system 1.2.219 → 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/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-registry.d.ts

@@ -1,5 +1,6 @@
 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';
@@ -19,6 +20,14 @@ 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):
@@ -225,6 +234,14 @@ export declare class LocalChildRegistry {
     /** 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}. */
@@ -237,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.
@@ -277,6 +300,19 @@ export declare class LocalChildRegistry {
     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.
@@ -366,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,3 +1,4 @@
+import { CapActionChannelObserver } from './cap-action-census.js';
 import { SocketTrafficSample } from './socket-traffic.js';
 /**
  * Wire frame exchanged over a local channel.
@@ -91,6 +92,14 @@ export interface LocalChannel {
      * 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 {

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

@@ -1,4 +1,5 @@
 import { Socket } from 'node:net';
+import { CapActionChannelObserver } from './cap-action-census.js';
 import { EventHandler, LocalChannel, RequestHandler } from './local-transport.js';
 import { SocketTrafficSample } from './socket-traffic.js';
 /**
@@ -34,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.
@@ -48,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. */
@@ -78,6 +95,10 @@ export declare class SocketChannel implements LocalChannel {
      * 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;