@camstack/system 1.2.219 → 1.2.221

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;