@camstack/system 1.2.390 → 1.2.391

package/dist/logging/log-manager.d.ts

@@ -1,141 +1,141 @@
-import { LogEntry, LogFilter, LogLevel } from './log-ring-buffer.js';
-import { LoggingGate } from './logging-gate.js';
-import { PartitionedLogBufferOptions } from './partitioned-log-buffer.js';
-import { IScopedLogger } from './scoped-logger.js';
+import { type LogEntry, type LogFilter, type LogLevel } from "./log-ring-buffer.js";
+import type { LoggingGate } from "./logging-gate.js";
+import { type PartitionedLogBufferOptions } from "./partitioned-log-buffer.js";
+import { type IScopedLogger } from "./scoped-logger.js";
 export interface ILogDestination {
-    initialize(): Promise<void>;
-    shutdown(): Promise<void>;
-    write(entry: LogEntry): void;
-    query?(filter: LogFilter): Promise<readonly LogEntry[]>;
+	initialize(): Promise<void>;
+	shutdown(): Promise<void>;
+	write(entry: LogEntry): void;
+	query?(filter: LogFilter): Promise<readonly LogEntry[]>;
 }
 /**
- * The reserved destination id of the in-memory buffer. Not an addon: the
- * buffer must exist before any addon loads (boot lines) and it backs
- * `logs.query`/`subscribe`, so it lives in the kernel — but it answers to the
- * SAME orchestrator toggle as every other destination.
- */
+* The reserved destination id of the in-memory buffer. Not an addon: the
+* buffer must exist before any addon loads (boot lines) and it backs
+* `logs.query`/`subscribe`, so it lives in the kernel — but it answers to the
+* SAME orchestrator toggle as every other destination.
+*/
 export declare const LOG_BUFFER_DESTINATION_ID = "log-buffer";
 /**
- * The addon that OWNS stdout. Every other shipped destination writes somewhere
- * else (winston is file-only, loki is remote), so this is the single id whose
- * arrival means "the real console is up now".
- *
- * It exists because the console destination is a core builtin that boots after
- * the whole runner plan: a measured hub boot produced no stdout for ~40 s and
- * then flushed the backlog newest-first. {@link LogManager.attachBootstrapConsole}
- * covers that window, and this constant is how the handover is recognised.
- */
+* The addon that OWNS stdout. Every other shipped destination writes somewhere
+* else (winston is file-only, loki is remote), so this is the single id whose
+* arrival means "the real console is up now".
+*
+* It exists because the console destination is a core builtin that boots after
+* the whole runner plan: a measured hub boot produced no stdout for ~40 s and
+* then flushed the backlog newest-first. {@link LogManager.attachBootstrapConsole}
+* covers that window, and this constant is how the handover is recognised.
+*/
 export declare const STDOUT_DESTINATION_ADDON_ID = "console-logging";
 export declare class LogManager {
-    private readonly ringBuffer;
-    /**
-     * Destinations, each tagged with the addon that provides it (when known) so
-     * the fan-out can honour the operator's per-destination toggle.
-     */
-    private readonly destinations;
-    /**
-     * "Is this destination enabled?", injected by the wiring side (which owns
-     * the capability registry). Absent ⇒ everything is enabled.
-     *
-     * WHY: the orchestrator's Enable/Disable toggle only added the addon to
-     * `disabledProviders` and NOTHING consulted it for `log-destination` — so
-     * console and winston could not be turned off at all and the badge in the UI
-     * lied, while Loki appeared to work only because it carried a SECOND,
-     * private `enabled` setting of its own (audit 2026-07-30).
-     */
-    private isDestinationEnabled?;
-    private readonly subscribers;
-    private deviceNameLookup;
-    /**
-     * The bootstrap stdout sink, while one is attached. Detached — and its
-     * replay suppressed — when {@link STDOUT_DESTINATION_ADDON_ID} registers.
-     */
-    private bootstrapConsole;
-    /**
-     * The node-wide level floor, mirrored from the logging settings document.
-     *
-     * Consulted on EVERY emitted line, so it is a boolean field read and nothing
-     * else while nothing is configured — see {@link LoggingGate}. It gates the
-     * DESTINATIONS only: the ring buffer keeps the line either way, because a
-     * floor that also blinded the log viewer would make raising the level to
-     * quieten a disk cost the operator the one window they read incidents from.
-     */
-    private gate;
-    /**
-     * `perAddonCapacity` bounds EACH addon's bucket, not the total — a chatty addon
-     * evicts only its own lines, so quiet addons keep their sparse history.
-     *
-     * `options.maxTotalEntries` ceilings the total across all buckets, because the
-     * per-bucket bound scales with addon count, and `options.maxBuckets` ceilings the
-     * bucket count itself. When the total is exceeded, entries at or below
-     * `options.pruneLevel` (default `debug`) are discarded first — a live addon's
-     * `warn`/`error` are never evicted to satisfy it — and only if that cannot reach
-     * the target are whole least-recently-written buckets dropped. Both bounds are ON
-     * by default; pass an explicit `null` to opt out. See {@link PartitionedLogBuffer}.
-     */
-    constructor(perAddonCapacity?: number, options?: PartitionedLogBufferOptions);
-    /** Entries currently retained across every bucket. */
-    bufferSize(): number;
-    /**
-     * Register a callback that resolves `deviceId → deviceName`. Called
-     * for every emitted entry that carries `tags.deviceId` but no
-     * explicit `tags.deviceName` — the LogManager injects the resolved
-     * name directly into the entry's tags BEFORE ring-buffer / destination
-     * write, so every destination (local console, file, remote forwarder,
-     * addon-bundled copies of core) sees the enriched shape regardless of
-     * which module instance the destination was built from.
-     */
-    setDeviceNameLookup(lookup: ((deviceId: number) => string | null) | null): void;
-    createLogger(scope?: string): IScopedLogger;
-    private enrichDeviceName;
-    /** Subscribe to live logs matching a filter. Returns an unsubscribe function. */
-    subscribe(filter: Partial<LogFilter>, callback: (entry: LogEntry) => void): () => void;
-    private matchesFilter;
-    /**
-     * Register a log destination.
-     *
-     * @param opts.replay  If true (default), replay every entry currently in
-     *                     the ring buffer to the new destination before live
-     *                     traffic starts. Lets a destination added mid-boot
-     *                     still receive boot-time log entries.
-     */
-    /** Apply new in-memory buffer limits at runtime (see PartitionedLogBuffer). */
-    reconfigureBuffer(options: {
-        readonly perAddonCapacity?: number;
-        readonly maxTotalEntries?: number | null;
-        readonly pruneLevel?: LogLevel;
-    }): void;
-    /**
-     * Swap the node-wide level gate. Production uses the process singleton;
-     * a spec passes its own so two suites cannot arm each other's floor.
-     */
-    setLoggingGate(gate: LoggingGate): void;
-    /** Set the per-destination enablement check (see {@link isDestinationEnabled}). */
-    setDestinationEnabledCheck(check: ((addonId: string) => boolean) | null): void;
-    /**
-     * Attach a minimal console sink that carries the boot log until the real
-     * `console-logging` builtin registers — see {@link STDOUT_DESTINATION_ADDON_ID}.
-     *
-     * Registered WITHOUT an `addonId` on purpose: the per-destination toggle
-     * could otherwise hide the one window an operator cannot read any other way
-     * (a hub that dies before pass 3 would emit nothing at all). It is detached
-     * the moment the stdout owner arrives, so stdout never carries two copies.
-     *
-     * Idempotent: a second call while one is attached is a no-op.
-     */
-    attachBootstrapConsole(dest: ILogDestination): void;
-    addDestination(dest: ILogDestination, opts?: {
-        replay?: boolean;
-        addonId?: string;
-    }): void;
-    removeDestination(dest: ILogDestination): void;
-    query(filter: LogFilter): LogEntry[];
-    /**
-     * Drop ring-buffer entries matching `filter`. Returns the count
-     * removed. Backs the UI's "Clear logs" admin action so an operator
-     * can wipe the historical window for a scope (per-device, per-addon,
-     * agent-level) without restarting the server. External destinations
-     * (file, forwarder) are NOT touched — only the in-memory ring.
-     */
-    clear(filter?: LogFilter): number;
+	private readonly ringBuffer;
+	/**
+	* Destinations, each tagged with the addon that provides it (when known) so
+	* the fan-out can honour the operator's per-destination toggle.
+	*/
+	private readonly destinations;
+	/**
+	* "Is this destination enabled?", injected by the wiring side (which owns
+	* the capability registry). Absent ⇒ everything is enabled.
+	*
+	* WHY: the orchestrator's Enable/Disable toggle only added the addon to
+	* `disabledProviders` and NOTHING consulted it for `log-destination` — so
+	* console and winston could not be turned off at all and the badge in the UI
+	* lied, while Loki appeared to work only because it carried a SECOND,
+	* private `enabled` setting of its own (audit 2026-07-30).
+	*/
+	private isDestinationEnabled?;
+	private readonly subscribers;
+	private deviceNameLookup;
+	/**
+	* The bootstrap stdout sink, while one is attached. Detached — and its
+	* replay suppressed — when {@link STDOUT_DESTINATION_ADDON_ID} registers.
+	*/
+	private bootstrapConsole;
+	/**
+	* The node-wide level floor, mirrored from the logging settings document.
+	*
+	* Consulted on EVERY emitted line, so it is a boolean field read and nothing
+	* else while nothing is configured — see {@link LoggingGate}. It gates the
+	* DESTINATIONS only: the ring buffer keeps the line either way, because a
+	* floor that also blinded the log viewer would make raising the level to
+	* quieten a disk cost the operator the one window they read incidents from.
+	*/
+	private gate;
+	/**
+	* `perAddonCapacity` bounds EACH addon's bucket, not the total — a chatty addon
+	* evicts only its own lines, so quiet addons keep their sparse history.
+	*
+	* `options.maxTotalEntries` ceilings the total across all buckets, because the
+	* per-bucket bound scales with addon count, and `options.maxBuckets` ceilings the
+	* bucket count itself. When the total is exceeded, entries at or below
+	* `options.pruneLevel` (default `debug`) are discarded first — a live addon's
+	* `warn`/`error` are never evicted to satisfy it — and only if that cannot reach
+	* the target are whole least-recently-written buckets dropped. Both bounds are ON
+	* by default; pass an explicit `null` to opt out. See {@link PartitionedLogBuffer}.
+	*/
+	constructor(perAddonCapacity?: number, options?: PartitionedLogBufferOptions);
+	/** Entries currently retained across every bucket. */
+	bufferSize(): number;
+	/**
+	* Register a callback that resolves `deviceId → deviceName`. Called
+	* for every emitted entry that carries `tags.deviceId` but no
+	* explicit `tags.deviceName` — the LogManager injects the resolved
+	* name directly into the entry's tags BEFORE ring-buffer / destination
+	* write, so every destination (local console, file, remote forwarder,
+	* addon-bundled copies of core) sees the enriched shape regardless of
+	* which module instance the destination was built from.
+	*/
+	setDeviceNameLookup(lookup: ((deviceId: number) => string | null) | null): void;
+	createLogger(scope?: string): IScopedLogger;
+	private enrichDeviceName;
+	/** Subscribe to live logs matching a filter. Returns an unsubscribe function. */
+	subscribe(filter: Partial<LogFilter>, callback: (entry: LogEntry) => void): () => void;
+	private matchesFilter;
+	/**
+	* Register a log destination.
+	*
+	* @param opts.replay  If true (default), replay every entry currently in
+	*                     the ring buffer to the new destination before live
+	*                     traffic starts. Lets a destination added mid-boot
+	*                     still receive boot-time log entries.
+	*/
+	/** Apply new in-memory buffer limits at runtime (see PartitionedLogBuffer). */
+	reconfigureBuffer(options: {
+		readonly perAddonCapacity?: number;
+		readonly maxTotalEntries?: number | null;
+		readonly pruneLevel?: LogLevel;
+	}): void;
+	/**
+	* Swap the node-wide level gate. Production uses the process singleton;
+	* a spec passes its own so two suites cannot arm each other's floor.
+	*/
+	setLoggingGate(gate: LoggingGate): void;
+	/** Set the per-destination enablement check (see {@link isDestinationEnabled}). */
+	setDestinationEnabledCheck(check: ((addonId: string) => boolean) | null): void;
+	/**
+	* Attach a minimal console sink that carries the boot log until the real
+	* `console-logging` builtin registers — see {@link STDOUT_DESTINATION_ADDON_ID}.
+	*
+	* Registered WITHOUT an `addonId` on purpose: the per-destination toggle
+	* could otherwise hide the one window an operator cannot read any other way
+	* (a hub that dies before pass 3 would emit nothing at all). It is detached
+	* the moment the stdout owner arrives, so stdout never carries two copies.
+	*
+	* Idempotent: a second call while one is attached is a no-op.
+	*/
+	attachBootstrapConsole(dest: ILogDestination): void;
+	addDestination(dest: ILogDestination, opts?: {
+		replay?: boolean;
+		addonId?: string;
+	}): void;
+	removeDestination(dest: ILogDestination): void;
+	query(filter: LogFilter): LogEntry[];
+	/**
+	* Drop ring-buffer entries matching `filter`. Returns the count
+	* removed. Backs the UI's "Clear logs" admin action so an operator
+	* can wipe the historical window for a scope (per-device, per-addon,
+	* agent-level) without restarting the server. External destinations
+	* (file, forwarder) are NOT touched — only the in-memory ring.
+	*/
+	clear(filter?: LogFilter): number;
 }

package/dist/logging/log-redactor.d.ts

@@ -1,4 +1,25 @@
-import { LogEntry } from '@camstack/types';
+/**
+* The central log redactor (D787 §8). Every line passes through it before any
+* destination, ring buffer or subscriber sees it — in hub-main's `LogManager`,
+* in a forked runner's UDS logger (which alone knows the values that runner
+* resolved), and on an agent before a child's line is forwarded to the hub.
+*
+* Three nets, cheapest first:
+*  1. KNOWN VALUES — every secret this process resolved through `ctx.secrets`
+*     is replaced wherever it appears (`‹secret:<ref hash>›`). The only net
+*     that catches a value inside a library's error message.
+*  2. URL CREDENTIALS — `user:pass@` and credential query params in any URL
+*     inside a string (`maskUrlCredentials`), and the value after a
+*     credential-looking CLI flag (`--token X`, `--auth-key=X`).
+*  3. KEY NAMES — a `meta` value under a credential-named key, at any depth.
+*
+* Key names are a LOG heuristic only: whether a field is STORED in the
+* keychain is decided by its schema type, never by its name.
+*
+* Hot path: a line with no meta, no `://`, no `--` and no registered values
+* costs a few `includes` checks.
+*/
+import { type LogEntry } from "@camstack/types";
 /** True when a meta key names a credential. */
 export declare function isCredentialKeyName(key: string): boolean;
 /** Redact one free-form string. */

package/dist/logging/log-ring-buffer.d.ts

@@ -1,62 +1,62 @@
-import { LogLevel, LogEntry, LogFilter, LogTags } from '@camstack/types';
+import type { LogLevel, LogEntry, LogFilter, LogTags } from "@camstack/types";
 export type { LogLevel, LogEntry, LogFilter };
 /**
- * Per-tag filter matcher with semantic-aware comparisons:
- *
- *   `addonId`  — matches the entry's bare addon id (strips any `@<workerId>`
- *                qualifier added by the cap-router for remote providers).
- *                So a UI filter for `audio-classifier` matches both the
- *                addon's own log lines and bridge management lines whose
- *                addonId is logged as `audio-classifier@dev-agent-0/audio-classifier`.
- *
- *   `agentId`  — matches when ANY of these hold:
- *                  * the entry was emitted by that agent (`agentId` exact)
- *                  * the entry's `nodeId` IS that agent (single-node case)
- *                  * the entry's `nodeId` starts with `<agent>/` (worker
- *                    inside that agent — e.g. `dev-agent-0/audio-classifier`)
- *                Captures all the log emission paths for an addon hosted
- *                on the agent regardless of who actually emitted the line.
- *
- *   any other key — exact match (legacy semantics).
- *
- * Returns `true` when ALL filter keys match (AND), `false` otherwise.
- * `undefined` filter values are skipped.
- */
+* Per-tag filter matcher with semantic-aware comparisons:
+*
+*   `addonId`  — matches the entry's bare addon id (strips any `@<workerId>`
+*                qualifier added by the cap-router for remote providers).
+*                So a UI filter for `audio-classifier` matches both the
+*                addon's own log lines and bridge management lines whose
+*                addonId is logged as `audio-classifier@dev-agent-0/audio-classifier`.
+*
+*   `agentId`  — matches when ANY of these hold:
+*                  * the entry was emitted by that agent (`agentId` exact)
+*                  * the entry's `nodeId` IS that agent (single-node case)
+*                  * the entry's `nodeId` starts with `<agent>/` (worker
+*                    inside that agent — e.g. `dev-agent-0/audio-classifier`)
+*                Captures all the log emission paths for an addon hosted
+*                on the agent regardless of who actually emitted the line.
+*
+*   any other key — exact match (legacy semantics).
+*
+* Returns `true` when ALL filter keys match (AND), `false` otherwise.
+* `undefined` filter values are skipped.
+*/
 export declare function matchesLogTags(entryTags: LogTags | undefined, filterTags: Partial<LogTags>): boolean;
 export declare class LogRingBuffer {
-    private readonly capacity;
-    private readonly buffer;
-    private head;
-    private count;
-    constructor(capacity?: number);
-    push(entry: LogEntry): void;
-    getAll(): LogEntry[];
-    query(filter: LogFilter): LogEntry[];
-    /**
-     * Drop entries that match `filter`. Returns the number of entries
-     * removed. Triggered by the UI's "Clear logs" button so the operator
-     * can wipe the historical buffer for a specific scope (per-device,
-     * per-addon, per-agent) — without it, closing and reopening the
-     * panel re-populates the cleared rows from the server's ring buffer.
-     *
-     * Filter semantics mirror `query` (same level / since / until / tags
-     * handling) — whatever you'd see listed by `query(filter)` is what
-     * gets removed.
-     */
-    clear(filter?: LogFilter): number;
-    /** Entries currently retained. */
-    size(): number;
-    /**
-     * Drop up to `max` entries, OLDEST first, whose level is at or below
-     * `threshold`. Returns how many were removed.
-     *
-     * This is what lets a total-memory cap be enforced without losing the entries
-     * that matter: sweeping `debug` reclaims almost all of the space (debug is the
-     * overwhelming majority of any busy buffer) while `warn` and `error` are never
-     * touched. Losing the one error line that explains an incident, in order to keep
-     * a thousand debug lines about frame timings, would be the wrong trade.
-     *
-     * Oldest-first because recent context is what an operator is looking at.
-     */
-    pruneOldestAtOrBelow(threshold: LogLevel, max: number): number;
+	private readonly capacity;
+	private readonly buffer;
+	private head;
+	private count;
+	constructor(capacity?: number);
+	push(entry: LogEntry): void;
+	getAll(): LogEntry[];
+	query(filter: LogFilter): LogEntry[];
+	/**
+	* Drop entries that match `filter`. Returns the number of entries
+	* removed. Triggered by the UI's "Clear logs" button so the operator
+	* can wipe the historical buffer for a specific scope (per-device,
+	* per-addon, per-agent) — without it, closing and reopening the
+	* panel re-populates the cleared rows from the server's ring buffer.
+	*
+	* Filter semantics mirror `query` (same level / since / until / tags
+	* handling) — whatever you'd see listed by `query(filter)` is what
+	* gets removed.
+	*/
+	clear(filter?: LogFilter): number;
+	/** Entries currently retained. */
+	size(): number;
+	/**
+	* Drop up to `max` entries, OLDEST first, whose level is at or below
+	* `threshold`. Returns how many were removed.
+	*
+	* This is what lets a total-memory cap be enforced without losing the entries
+	* that matter: sweeping `debug` reclaims almost all of the space (debug is the
+	* overwhelming majority of any busy buffer) while `warn` and `error` are never
+	* touched. Losing the one error line that explains an incident, in order to keep
+	* a thousand debug lines about frame timings, would be the wrong trade.
+	*
+	* Oldest-first because recent context is what an operator is looking at.
+	*/
+	pruneOldestAtOrBelow(threshold: LogLevel, max: number): number;
 }

package/dist/logging/logging-gate.d.ts

@@ -1,32 +1,76 @@
-import { LogLevel } from '@camstack/types';
+/**
+* The in-memory MIRROR of the logging settings document, read on the log path.
+*
+* ## Why a mirror and not the settings store
+*
+* The document (`system.getLoggingSettings` / `setLoggingSettings`) is the
+* durable AUTHORITY. It is a row in `system-settings`, reachable only through
+* an async cap call — and this gate is consulted once per emitted log line. A
+* hot path cannot await a store, so the store is mirrored here and the mirror
+* is refreshed OFF the hot path, on a write and once at boot.
+*
+* ## Cost when nothing is set
+*
+* {@link LoggingGate.restrictsDestinations} is a plain boolean FIELD, and it is
+* the FIRST statement of {@link LoggingGate.allowsDestination} — before the
+* entry is touched at all. A default hub sets no level, the field stays
+* `false`, and every line costs one boolean read and a return: no rank lookup,
+* no property access, no allocation. `logging-gate.spec.ts` pins this with an
+* entry whose `level` getter THROWS, so moving the guard below a field access
+* fails the spec instead of taxing every line the hub emits.
+*
+* ## A failed read changes nothing (D49)
+*
+* Nothing here reads the store. The only way the mirror moves is an explicit
+* {@link LoggingGate.setDestinationFloor}, and the service that owns the
+* document calls it ONLY with a value it actually read. A store read that
+* fails leaves the mirror exactly as it was: it neither raises a level nor
+* lowers one, and a diagnostic armed before the failure stays armed.
+*
+* ## What the floor governs, and what it deliberately does not
+*
+* The floor gates the fan-out to DESTINATIONS (console, rotated files, Loki,
+* the hub forwarder). It does NOT gate the in-memory ring buffer: the ring
+* keeps everything it has room for and prunes by level only under pressure,
+* which the plan
+* (`docs/design/plans/2026-08-26-per-component-logging.md`) settles as the
+* better policy — an admission level for the ring would make the log viewer go
+* blind exactly when an operator raises the level to quieten a disk.
+*
+* A destination's own level still applies on top. The two compose as
+* "most restrictive wins", which is a hierarchy and not a second authority:
+* the floor is node-wide, the destination level is that destination's own, and
+* neither can be read as overriding the other.
+*/
+import { type LogLevel } from "@camstack/types";
 /** What a hub emits when nothing is configured anywhere. */
 export declare const DEFAULT_LOG_LEVEL: LogLevel;
 /**
- * The only thing the gate needs off an entry — and it must not read it while
- * the gate is unrestricted. Deliberately structural so the spec can hand in an
- * object whose getter throws.
- */
+* The only thing the gate needs off an entry — and it must not read it while
+* the gate is unrestricted. Deliberately structural so the spec can hand in an
+* object whose getter throws.
+*/
 export interface LevelBearing {
-    readonly level: LogLevel;
+	readonly level: LogLevel;
 }
 export declare class LoggingGate {
-    /** The ONLY field an unrestricted log path reads. */
-    private restricted;
-    private floorRank;
-    private floor;
-    /** The effective node-wide level currently mirrored. */
-    get destinationFloor(): LogLevel;
-    /** True only when the mirrored level is stricter than the default. */
-    get restrictsDestinations(): boolean;
-    /**
-     * May this entry be fanned out to the log destinations?
-     *
-     * The boolean field is read FIRST. Do not move it below anything.
-     */
-    allowsDestination(entry: LevelBearing): boolean;
-    /**
-     * Refresh the mirror. Called off the hot path — on an operator write and
-     * once at boot — and never with a value that was not actually read.
-     */
-    setDestinationFloor(level: LogLevel): void;
+	/** The ONLY field an unrestricted log path reads. */
+	private restricted;
+	private floorRank;
+	private floor;
+	/** The effective node-wide level currently mirrored. */
+	get destinationFloor(): LogLevel;
+	/** True only when the mirrored level is stricter than the default. */
+	get restrictsDestinations(): boolean;
+	/**
+	* May this entry be fanned out to the log destinations?
+	*
+	* The boolean field is read FIRST. Do not move it below anything.
+	*/
+	allowsDestination(entry: LevelBearing): boolean;
+	/**
+	* Refresh the mirror. Called off the hot path — on an operator write and
+	* once at boot — and never with a value that was not actually read.
+	*/
+	setDestinationFloor(level: LogLevel): void;
 }

package/dist/logging/logging-gate.singleton.d.ts

@@ -1,4 +1,15 @@
-import { LoggingGate } from './logging-gate.js';
+/**
+* Process-wide holder for the {@link LoggingGate}.
+*
+* Two call sites that never meet need the SAME instance: `LogManager` reads it
+* on every emitted line, and the `system` cap provider — which `trpc.router.ts`
+* rebuilds PER REQUEST — refreshes it whenever the document is written. A gate
+* built inside that per-request factory would be refreshed and collected,
+* which is the shape of a knob that never does anything.
+*
+* Same idiom as `http-request-census.singleton.ts`.
+*/
+import { LoggingGate } from "./logging-gate.js";
 /** The process-wide logging gate. Created unrestricted on first use. */
 export declare function getLoggingGate(): LoggingGate;
 /** Test-only: drop the instance so a spec starts from an unrestricted gate. */