@camstack/system 1.2.390 → 1.2.392

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

@@ -1,225 +1,225 @@
 /**
- * event-plane-report — the fan-out counters this cluster has always kept and
- * never read, on the line it already emits.
- *
- * ## Why this exists
- *
- * hub-main's memory is a RATE, not a set. Measured 2026-08-29 over the first 25
- * minutes of telemetry this process has ever produced: every forced compaction
- * drops `arrayBuffers` to **12–29 MB** — ten passes out of ten — so a reading of
- * 726 MB is 707 MB of dead Buffers not yet swept, not a retained set. The real
- * quantity is the slope: **181–330 MB/min steady, with one burst of ≥1.3 GB in
- * ≤11 s**.
- *
- * And it is sockets, not media. `/proc/<pid>/io` over the same windows: ~21 800
- * reads/s and ~22 500 writes/s at a **0.33 KB mean**, with regular-file reads at
- * 0.73 MB/min. A 64 KB proxy chunk or a 200 KB JPEG cannot hide inside a 0.33 KB
- * mean, so the cost is per MESSAGE on a fan-out plane nobody has ever counted —
- * an IDLE addon still reads 82 messages/s of it, across ~38 runners.
- *
- * The strongest single number available is that **78–82% of hub-main's outbound
- * bytes correlate with `hub/pipeline-analytics`, in both windows** — but `rchar`
- * on that runner also counts page-cache reads and it owns a vector store, so the
- * correlation is not an attribution. `fanoutTop` turns it into one.
- *
- * ## Both planes always filter
- *
- * The cross-node plane ran a `shadow` burn-in (`CAMSTACK_MOLECULER_EVENT_FANOUT`)
- * with no end condition, and the UDS plane carried the same three-mode switch
- * (`CAMSTACK_UDS_EVENT_FANOUT`). Both switches were removed on 2026-10-06: a
- * suppressed count now always means "this many WERE dropped", and the line no
- * longer prints a regime because there is only one.
- *
- * ## The fail-open nobody can see
- *
- * A child that never declares its pattern set (`eventPatterns === null`,
- * `local-child-registry.ts:170`) makes the per-child gate fail OPEN, and per
- * `setNodeEventInterest` ANY undeclared child makes the whole node's inbound
- * cross-node gate fail open too. **One legacy runner silently disables the
- * filtering on both planes**, and nothing reported it. `childrenUndeclared` is
- * printed even at zero for the same reason `largeObjectSpace=0MB` is: absence
- * must never be ambiguous.
- *
- * ## Deltas, never totals
- *
- * Both registries count cumulatively for the life of the process. A cumulative
- * number on a heartbeat answers "how much since boot", which nobody asked; the
- * question is "which peer receives the 22 500 writes/s", and that is a rate. So
- * the meter is read ONCE PER LINE and reports the window since the previous read
- * — the same discipline the loop-delay histogram already follows, for the same
- * reason.
- *
- * ## The unit trap (D467)
- *
- * `fanoutSent` / `fanoutSuppressed` are **(event × child) pairs**, not events:
- * `broadcastEventToChildren` increments them inside the per-child loop, so on a
- * 39-child node ONE emit produces up to 38 increments. A 2026-09-12 reading of
- * `fanoutSuppressed=433461` was read as "433k events a minute, 97% discarded";
- * the real production was **~11 700 events/min**. The line proves it itself —
- * every pure-consumer child's `sent + suppressed` converges on 11 730, because
- * that sum IS the distinct broadcast count, and the two rows that fall short
- * (`pipeline-orchestrator`, `pipeline-analytics`) fall short by exactly what
- * they originated. `fanoutEvents` is the production rate, counted once per emit
- * outside that loop, and it is printed so the pair counters can never be read as
- * one again.
- *
- * `fanoutCats` names PRODUCERS (`fanoutTop` names subscribers) and
- * `fanoutOrphans` counts what was serialised and walked across every child with
- * zero subscribers. A suppressed pair was measured at **255 ns** — 1.84 ms/s of
- * event loop at this rate — so the filter is not the cost; the emit is.
- */
+* event-plane-report — the fan-out counters this cluster has always kept and
+* never read, on the line it already emits.
+*
+* ## Why this exists
+*
+* hub-main's memory is a RATE, not a set. Measured 2026-08-29 over the first 25
+* minutes of telemetry this process has ever produced: every forced compaction
+* drops `arrayBuffers` to **12–29 MB** — ten passes out of ten — so a reading of
+* 726 MB is 707 MB of dead Buffers not yet swept, not a retained set. The real
+* quantity is the slope: **181–330 MB/min steady, with one burst of ≥1.3 GB in
+* ≤11 s**.
+*
+* And it is sockets, not media. `/proc/<pid>/io` over the same windows: ~21 800
+* reads/s and ~22 500 writes/s at a **0.33 KB mean**, with regular-file reads at
+* 0.73 MB/min. A 64 KB proxy chunk or a 200 KB JPEG cannot hide inside a 0.33 KB
+* mean, so the cost is per MESSAGE on a fan-out plane nobody has ever counted —
+* an IDLE addon still reads 82 messages/s of it, across ~38 runners.
+*
+* The strongest single number available is that **78–82% of hub-main's outbound
+* bytes correlate with `hub/pipeline-analytics`, in both windows** — but `rchar`
+* on that runner also counts page-cache reads and it owns a vector store, so the
+* correlation is not an attribution. `fanoutTop` turns it into one.
+*
+* ## Both planes always filter
+*
+* The cross-node plane ran a `shadow` burn-in (`CAMSTACK_MOLECULER_EVENT_FANOUT`)
+* with no end condition, and the UDS plane carried the same three-mode switch
+* (`CAMSTACK_UDS_EVENT_FANOUT`). Both switches were removed on 2026-10-06: a
+* suppressed count now always means "this many WERE dropped", and the line no
+* longer prints a regime because there is only one.
+*
+* ## The fail-open nobody can see
+*
+* A child that never declares its pattern set (`eventPatterns === null`,
+* `local-child-registry.ts:170`) makes the per-child gate fail OPEN, and per
+* `setNodeEventInterest` ANY undeclared child makes the whole node's inbound
+* cross-node gate fail open too. **One legacy runner silently disables the
+* filtering on both planes**, and nothing reported it. `childrenUndeclared` is
+* printed even at zero for the same reason `largeObjectSpace=0MB` is: absence
+* must never be ambiguous.
+*
+* ## Deltas, never totals
+*
+* Both registries count cumulatively for the life of the process. A cumulative
+* number on a heartbeat answers "how much since boot", which nobody asked; the
+* question is "which peer receives the 22 500 writes/s", and that is a rate. So
+* the meter is read ONCE PER LINE and reports the window since the previous read
+* — the same discipline the loop-delay histogram already follows, for the same
+* reason.
+*
+* ## The unit trap (D467)
+*
+* `fanoutSent` / `fanoutSuppressed` are **(event × child) pairs**, not events:
+* `broadcastEventToChildren` increments them inside the per-child loop, so on a
+* 39-child node ONE emit produces up to 38 increments. A 2026-09-12 reading of
+* `fanoutSuppressed=433461` was read as "433k events a minute, 97% discarded";
+* the real production was **~11 700 events/min**. The line proves it itself —
+* every pure-consumer child's `sent + suppressed` converges on 11 730, because
+* that sum IS the distinct broadcast count, and the two rows that fall short
+* (`pipeline-orchestrator`, `pipeline-analytics`) fall short by exactly what
+* they originated. `fanoutEvents` is the production rate, counted once per emit
+* outside that loop, and it is printed so the pair counters can never be read as
+* one again.
+*
+* `fanoutCats` names PRODUCERS (`fanoutTop` names subscribers) and
+* `fanoutOrphans` counts what was serialised and walked across every child with
+* zero subscribers. A suppressed pair was measured at **255 ns** — 1.84 ms/s of
+* event loop at this rate — so the filter is not the cost; the emit is.
+*/
 /** One child's fan-out counters, as the registry keeps them (cumulative). */
 export interface ChildFanoutSample {
-    readonly childId: string;
-    readonly sent: number;
-    readonly suppressed: number;
+	readonly childId: string;
+	readonly sent: number;
+	readonly suppressed: number;
 }
 /** One child's fan-out over the window since the previous read. */
 export interface ChildFanoutDelta {
-    readonly childId: string;
-    readonly sent: number;
-    readonly suppressed: number;
+	readonly childId: string;
+	readonly sent: number;
+	readonly suppressed: number;
 }
 /** What `LocalChildRegistry` exposes, structurally — the kernel's heartbeat
- *  must not depend on the transport layer's class. */
+*  must not depend on the transport layer's class. */
 export interface ChildFanoutRegistryChild {
-    readonly childId: string;
+	readonly childId: string;
 }
 export interface ChildFanoutRegistryStats {
-    readonly sent: number;
-    readonly suppressed: number;
+	readonly sent: number;
+	readonly suppressed: number;
 }
 /**
- * D467 — one PRODUCED category, cumulative, as the registry keeps it.
- *
- * `broadcasts` is EMITS, not deliveries; `wanted` is the number of child
- * subscriptions that matched, summed over those emits.
- */
+* D467 — one PRODUCED category, cumulative, as the registry keeps it.
+*
+* `broadcasts` is EMITS, not deliveries; `wanted` is the number of child
+* subscriptions that matched, summed over those emits.
+*/
 export interface CategoryFanoutSample {
-    readonly category: string;
-    readonly broadcasts: number;
-    readonly wanted: number;
+	readonly category: string;
+	readonly broadcasts: number;
+	readonly wanted: number;
 }
 export interface ChildFanoutRegistry {
-    readonly listChildren: () => readonly ChildFanoutRegistryChild[];
-    readonly getChildEventStats: (childId: string) => ChildFanoutRegistryStats | null;
-    readonly undeclaredChildCount: () => number;
-    readonly categoryFanout: () => readonly CategoryFanoutSample[];
-    readonly categoryCensusOverflow: () => number;
+	readonly listChildren: () => readonly ChildFanoutRegistryChild[];
+	readonly getChildEventStats: (childId: string) => ChildFanoutRegistryStats | null;
+	readonly undeclaredChildCount: () => number;
+	readonly categoryFanout: () => readonly CategoryFanoutSample[];
+	readonly categoryCensusOverflow: () => number;
 }
 /** What `getMoleculerEventStats` returns, structurally. */
 export interface CrossNodeEventStats {
-    readonly delivered: number;
-    readonly suppressed: number;
+	readonly delivered: number;
+	readonly suppressed: number;
 }
 /** One cumulative reading of both planes. */
 export interface EventPlaneCounters {
-    readonly children: readonly ChildFanoutSample[];
-    readonly childrenConnected: number;
-    readonly childrenUndeclared: number;
-    readonly crossNodeDelivered: number;
-    readonly crossNodeSuppressed: number;
-    readonly categories: readonly CategoryFanoutSample[];
-    readonly categoryOverflow: number;
+	readonly children: readonly ChildFanoutSample[];
+	readonly childrenConnected: number;
+	readonly childrenUndeclared: number;
+	readonly crossNodeDelivered: number;
+	readonly crossNodeSuppressed: number;
+	readonly categories: readonly CategoryFanoutSample[];
+	readonly categoryOverflow: number;
 }
 /** `undefined` = this process has no event plane to report (every forked
- *  runner, and hub-main before the registry exists). */
+*  runner, and hub-main before the registry exists). */
 export type EventPlaneReader = () => EventPlaneCounters | undefined;
 /** Where a reader gets each part. Every one is late-bound, because the
- *  heartbeat starts before any of them exist. */
+*  heartbeat starts before any of them exist. */
 export interface EventPlaneSources {
-    readonly registry: () => ChildFanoutRegistry | null;
-    readonly crossNodeStats: () => CrossNodeEventStats | null;
+	readonly registry: () => ChildFanoutRegistry | null;
+	readonly crossNodeStats: () => CrossNodeEventStats | null;
 }
 /**
- * Build a reader over the two registries.
- *
- * Returns `undefined` until the child registry exists — the heartbeat starts as
- * the FIRST statement of `bootstrap()` (a process that dies early still leaves
- * samples) and `LocalChildRegistry` is built hundreds of lines later inside
- * `MoleculerService.onModuleInit`. Printing zeros in that window would report a
- * silent plane where there is no plane at all.
- *
- * Wrapped: a registry mid-teardown may throw, and a diagnostic that can crash
- * the process it watches is worse than none.
- */
+* Build a reader over the two registries.
+*
+* Returns `undefined` until the child registry exists — the heartbeat starts as
+* the FIRST statement of `bootstrap()` (a process that dies early still leaves
+* samples) and `LocalChildRegistry` is built hundreds of lines later inside
+* `MoleculerService.onModuleInit`. Printing zeros in that window would report a
+* silent plane where there is no plane at all.
+*
+* Wrapped: a registry mid-teardown may throw, and a diagnostic that can crash
+* the process it watches is worse than none.
+*/
 export declare function createEventPlaneReader(sources: EventPlaneSources): EventPlaneReader;
 /**
- * How many children get named on the line.
- *
- * Five, because the question is which peer DOMINATES and the measured
- * distribution is not flat: one peer accounted for 78–82% of outbound bytes and
- * the runner-up for ~6%. Five names the dominant peer, its challenger and enough
- * of the tail to see the shape change; naming all ~38 would put a kilobyte-long
- * line in the hub's shared log every minute, which is how a log stops being read.
- */
+* How many children get named on the line.
+*
+* Five, because the question is which peer DOMINATES and the measured
+* distribution is not flat: one peer accounted for 78–82% of outbound bytes and
+* the runner-up for ~6%. Five names the dominant peer, its challenger and enough
+* of the tail to see the shape change; naming all ~38 would put a kilobyte-long
+* line in the hub's shared log every minute, which is how a log stops being read.
+*/
 export declare const EVENT_PLANE_TOP_N = 5;
 /** Both planes over one heartbeat window. */
 export interface EventPlaneWindow {
-    readonly childrenConnected: number;
-    readonly childrenUndeclared: number;
-    readonly fanoutSent: number;
-    readonly fanoutSuppressed: number;
-    readonly crossNodeDelivered: number;
-    readonly crossNodeSuppressed: number;
-    /** Largest `sent` first, at most {@link EVENT_PLANE_TOP_N} entries. */
-    readonly top: readonly ChildFanoutDelta[];
-    /** Events PRODUCED in the window — emits, summed over categories. */
-    readonly categoryBroadcasts: number;
-    /** Produced events no child subscribed to. Pure waste. */
-    readonly orphanBroadcasts: number;
-    /** Largest `broadcasts` first, at most {@link EVENT_PLANE_TOP_N} entries. */
-    readonly topCategories: readonly CategoryFanoutDelta[];
-    /** The orphans alone, largest first, at most {@link EVENT_PLANE_TOP_N}. */
-    readonly topOrphans: readonly CategoryFanoutDelta[];
-    /** Broadcasts the census could not attribute because it was full. */
-    readonly categoryOverflow: number;
+	readonly childrenConnected: number;
+	readonly childrenUndeclared: number;
+	readonly fanoutSent: number;
+	readonly fanoutSuppressed: number;
+	readonly crossNodeDelivered: number;
+	readonly crossNodeSuppressed: number;
+	/** Largest `sent` first, at most {@link EVENT_PLANE_TOP_N} entries. */
+	readonly top: readonly ChildFanoutDelta[];
+	/** Events PRODUCED in the window — emits, summed over categories. */
+	readonly categoryBroadcasts: number;
+	/** Produced events no child subscribed to. Pure waste. */
+	readonly orphanBroadcasts: number;
+	/** Largest `broadcasts` first, at most {@link EVENT_PLANE_TOP_N} entries. */
+	readonly topCategories: readonly CategoryFanoutDelta[];
+	/** The orphans alone, largest first, at most {@link EVENT_PLANE_TOP_N}. */
+	readonly topOrphans: readonly CategoryFanoutDelta[];
+	/** Broadcasts the census could not attribute because it was full. */
+	readonly categoryOverflow: number;
 }
 /** One category's production over the window since the previous read. */
 export interface CategoryFanoutDelta {
-    readonly category: string;
-    readonly broadcasts: number;
-    readonly wanted: number;
+	readonly category: string;
+	readonly broadcasts: number;
+	readonly wanted: number;
 }
 /** Previous cumulative reading, kept between lines. */
 export interface EventPlaneBaseline {
-    readonly children: ReadonlyMap<string, ChildFanoutSample>;
-    readonly categories: ReadonlyMap<string, CategoryFanoutSample>;
-    readonly crossNodeDelivered: number;
-    readonly crossNodeSuppressed: number;
-    readonly categoryOverflow: number;
+	readonly children: ReadonlyMap<string, ChildFanoutSample>;
+	readonly categories: ReadonlyMap<string, CategoryFanoutSample>;
+	readonly crossNodeDelivered: number;
+	readonly crossNodeSuppressed: number;
+	readonly categoryOverflow: number;
 }
 /** A process that has never read a plane. */
 export declare const EMPTY_EVENT_PLANE_BASELINE: EventPlaneBaseline;
 /**
- * Subtract the previous cumulative reading from the current one.
- *
- * A child that RESTARTED has counters that went backwards — the registry keys by
- * childId and a respawned runner reconnects under the same id with a fresh
- * entry. Clamping at 0 reports the restart as a quiet window rather than as a
- * negative rate: the window's traffic is genuinely unknown, and a negative
- * number on a rate reads as a broken meter.
- */
+* Subtract the previous cumulative reading from the current one.
+*
+* A child that RESTARTED has counters that went backwards — the registry keys by
+* childId and a respawned runner reconnects under the same id with a fresh
+* entry. Clamping at 0 reports the restart as a quiet window rather than as a
+* negative rate: the window's traffic is genuinely unknown, and a negative
+* number on a rate reads as a broken meter.
+*/
 export declare function diffEventPlane(baseline: EventPlaneBaseline, current: EventPlaneCounters, topN?: number): EventPlaneWindow;
 /** Reads the delta since the PREVIOUS read. Same contract as the loop meter. */
 export interface EventPlaneMeter {
-    readonly read: () => EventPlaneWindow | undefined;
+	readonly read: () => EventPlaneWindow | undefined;
 }
 export declare function createEventPlaneMeter(reader: EventPlaneReader, topN?: number): EventPlaneMeter;
 /**
- * The suffix appended to a `[mem]` line — leading space included, empty when
- * this process has no event plane.
- *
- * Only two processes in the cluster have one (hub-main, and an agent's main), so
- * these fields never appear on the ~38 runner lines that share the same log
- * stream. On the two that do, every field is printed on every line INCLUDING at
- * zero: the modes because a suppressed count without its regime is unreadable,
- * `childrenUndeclared` because one undeclared child silently disables both
- * gates, and the deltas because "the plane went quiet for a minute" is a
- * reading, not a blank.
- *
- * `fanoutTop` 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: `childId:sent/suppressed`, largest first.
- */
+* The suffix appended to a `[mem]` line — leading space included, empty when
+* this process has no event plane.
+*
+* Only two processes in the cluster have one (hub-main, and an agent's main), so
+* these fields never appear on the ~38 runner lines that share the same log
+* stream. On the two that do, every field is printed on every line INCLUDING at
+* zero: the modes because a suppressed count without its regime is unreadable,
+* `childrenUndeclared` because one undeclared child silently disables both
+* gates, and the deltas because "the plane went quiet for a minute" is a
+* reading, not a blank.
+*
+* `fanoutTop` 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: `childId:sent/suppressed`, largest first.
+*/
 export declare function formatEventPlane(window: EventPlaneWindow | undefined): string;

package/dist/kernel/fs-utils.d.ts

@@ -1,88 +1,88 @@
 /**
- * Ensure a directory exists (recursive).
- * Single source of truth — replaces scattered mkdirSync calls.
- */
+* Ensure a directory exists (recursive).
+* Single source of truth — replaces scattered mkdirSync calls.
+*/
 export declare function ensureDir(dirPath: string): void;
 /**
- * Copy a directory recursively — ASYNC so it never blocks the event loop.
- *
- * The hub installs addons into `/data/addons`, which on Unraid is a slow
- * shfs/FUSE mount. The former synchronous `fs.copyFileSync`-per-file loop
- * blocked the Node event loop for the whole copy of a large bundle (e.g.
- * `addon-pipeline`), which froze the hub's HTTP listener mid-`camstack deploy`
- * (accept backlog piling up, existing connections stuck in CLOSE_WAIT). Using
- * `fs.promises.cp` keeps the I/O off the event loop. (Node ≥18 stable.)
- */
+* Copy a directory recursively — ASYNC so it never blocks the event loop.
+*
+* The hub installs addons into `/data/addons`, which on Unraid is a slow
+* shfs/FUSE mount. The former synchronous `fs.copyFileSync`-per-file loop
+* blocked the Node event loop for the whole copy of a large bundle (e.g.
+* `addon-pipeline`), which froze the hub's HTTP listener mid-`camstack deploy`
+* (accept backlog piling up, existing connections stuck in CLOSE_WAIT). Using
+* `fs.promises.cp` keeps the I/O off the event loop. (Node ≥18 stable.)
+*/
 export declare function copyDirRecursive(src: string, dest: string): Promise<void>;
 /**
- * Runtime deps a stripped addon package.json must KEEP so the installer still
- * `npm install`s them into the addon dir.
- *
- * Empty by design: every native an addon can import is now HOST-EXTERNAL
- * (node-av, sharp, node-pty — resolved from the framework closure via the
- * resolver hook, see host-externals.ts), and every pure-JS lib (ssh2, werift,
- * @simplewebauthn, mqtt, aws-sdk, …) is inlined by the self-contained vite
- * bundle. So a self-contained dist requires NOTHING from a local node_modules —
- * `addons/` stays node_modules-free, which is what lets the backup tar the whole
- * folder with no exclusion list (see ADR-0027). An addon that genuinely needs an
- * un-bundleable runtime dep declares it explicitly in
- * `camstack.runtimeDependencies`.
- *
- * (Historically this mirrored the build preset's COMMON_NATIVE_DEPS and
- * per-addon-installed node-av/sharp/onnxruntime-node/ssh2/werift/systeminformation
- * — 74k files / 1.34 GB of redundant node_modules on the live hub. That redundancy
- * is removed: the natives come from the framework, the pure-JS from the bundle.)
- */
+* Runtime deps a stripped addon package.json must KEEP so the installer still
+* `npm install`s them into the addon dir.
+*
+* Empty by design: every native an addon can import is now HOST-EXTERNAL
+* (node-av, sharp, node-pty — resolved from the framework closure via the
+* resolver hook, see host-externals.ts), and every pure-JS lib (ssh2, werift,
+* @simplewebauthn, mqtt, aws-sdk, …) is inlined by the self-contained vite
+* bundle. So a self-contained dist requires NOTHING from a local node_modules —
+* `addons/` stays node_modules-free, which is what lets the backup tar the whole
+* folder with no exclusion list (see ADR-0027). An addon that genuinely needs an
+* un-bundleable runtime dep declares it explicitly in
+* `camstack.runtimeDependencies`.
+*
+* (Historically this mirrored the build preset's COMMON_NATIVE_DEPS and
+* per-addon-installed node-av/sharp/onnxruntime-node/ssh2/werift/systeminformation
+* — 74k files / 1.34 GB of redundant node_modules on the live hub. That redundancy
+* is removed: the natives come from the framework, the pure-JS from the bundle.)
+*/
 export declare const RUNTIME_NATIVE_KEEP: readonly string[];
 /**
- * Strip every dependency an addon's self-contained dist has already bundled,
- * keeping ONLY what must resolve from node_modules at runtime:
- *
- *   keep = RUNTIME_NATIVE_KEEP ∪ camstack.runtimeDependencies (minus @camstack/*)
- *
- * Addon dists are fully bundled (vite `externals: 'self-contained'`), yet the
- * blanket `npm install` of the manifest's dependencies re-installed the whole
- * tree the dist already contains — 98% of the deployed addons dir was
- * redundant node_modules (74k files / 1.34 GB on the live hub; it stalled the
- * backup walk and bloated every deploy). Kept PEER deps are folded into
- * `dependencies` so `--omit=peer` installs can't drop them (pipeline's
- * patched `werift`).
- *
- * Returns a new object (immutable).
- */
+* Strip every dependency an addon's self-contained dist has already bundled,
+* keeping ONLY what must resolve from node_modules at runtime:
+*
+*   keep = RUNTIME_NATIVE_KEEP ∪ camstack.runtimeDependencies (minus @camstack/*)
+*
+* Addon dists are fully bundled (vite `externals: 'self-contained'`), yet the
+* blanket `npm install` of the manifest's dependencies re-installed the whole
+* tree the dist already contains — 98% of the deployed addons dir was
+* redundant node_modules (74k files / 1.34 GB on the live hub; it stalled the
+* backup walk and bloated every deploy). Kept PEER deps are folded into
+* `dependencies` so `--omit=peer` installs can't drop them (pipeline's
+* patched `werift`).
+*
+* Returns a new object (immutable).
+*/
 export declare function stripBundledDeps(pkg: Record<string, unknown>): Record<string, unknown>;
 /**
- * Strip @camstack/* dependencies and devDependencies from a package.json object.
- * Used when installing addons into the addons directory — @camstack packages
- * are provided by the host runtime, not installed per-addon.
- *
- * Returns a new object (immutable).
- */
+* Strip @camstack/* dependencies and devDependencies from a package.json object.
+* Used when installing addons into the addons directory — @camstack packages
+* are provided by the host runtime, not installed per-addon.
+*
+* Returns a new object (immutable).
+*/
 export declare function stripCamstackDeps(pkg: Record<string, unknown>): Record<string, unknown>;
 /**
- * Copy extra file directories declared in package.json "files" field.
- * Copies directories (not individual files) from source to destination.
- * Skips "dist" (already handled) and glob patterns.
- */
+* Copy extra file directories declared in package.json "files" field.
+* Copies directories (not individual files) from source to destination.
+* Skips "dist" (already handled) and glob patterns.
+*/
 export declare function copyExtraFileDirs(pkgJson: Record<string, unknown>, sourceDir: string, destDir: string): Promise<void>;
 /**
- * Check if any file in src/ is newer than dist/.
- * Returns true if rebuild is needed.
- */
+* Check if any file in src/ is newer than dist/.
+* Returns true if rebuild is needed.
+*/
 export declare function isSourceNewer(packageDir: string): boolean;
 /**
- * Ensure a library dependency (not an addon) has a dist/ directory.
- * Does NOT rebuild — in dev mode, `npm run build` should be run separately.
- * Only checks that dist/ exists and has an index file.
- */
+* Ensure a library dependency (not an addon) has a dist/ directory.
+* Does NOT rebuild — in dev mode, `npm run build` should be run separately.
+* Only checks that dist/ exists and has an index file.
+*/
 export declare function ensureLibraryBuilt(packageName: string, packagesDir: string): void;
 /**
- * Install a single npm package into a target directory (package.json + dist/).
- * No validation on camstack.addons -- works for any @camstack/* package.
- *
- * ASYNC: uses `execFile`/`fs.promises` throughout so a package install on a
- * live node never blocks the event loop (the `npm pack` + tar extract + copy to
- * the slow shfs/FUSE `/data` would otherwise freeze the HTTP listener). See
- * `copyDirRecursive` for the wedge this prevents.
- */
+* Install a single npm package into a target directory (package.json + dist/).
+* No validation on camstack.addons -- works for any @camstack/* package.
+*
+* ASYNC: uses `execFile`/`fs.promises` throughout so a package install on a
+* live node never blocks the event loop (the `npm pack` + tar extract + copy to
+* the slow shfs/FUSE `/data` would otherwise freeze the HTTP listener). See
+* `copyDirRecursive` for the wedge this prevents.
+*/
 export declare function installPackageFromNpm(packageName: string, targetDir: string): Promise<void>;