@camstack/system 1.2.216 → 1.2.218

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,7 @@
 import { EventPlaneReader } from './event-plane-report.js';
 import { SocketPlaneReader } from './socket-plane-report.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,6 +607,20 @@ export interface HeapWatchProbes {
      * from the parent's side. Only hub-main and an agent's main pass one.
      */
     readonly socketPlane?: SocketPlaneReader;
+    /**
+     * 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;
 }
 /**
  * Start the heartbeat. Returns a stop function.

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

@@ -1,4 +1,4 @@
-import { CustomActionCaller, IReadinessRegistryRecord, LogLevel, LogTags, SystemEvent } from '@camstack/types';
+import { ChildCustomActionCatalogs, CustomActionCaller, IReadinessRegistryRecord, LogLevel, LogTags, SystemEvent } from '@camstack/types';
 /**
  * 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 +35,18 @@ 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;
 }
 /**
  * Child → parent, fire-and-forget: the child's category-pattern subscription
@@ -248,6 +260,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/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,6 +56,15 @@ 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;
     /** Handler for parent→child events. Registered via `onEvent`. */
@@ -138,7 +147,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