`@suaveplan/api-logger-worker-proxy` — worker-side proxy to main-process logger

Package: @suaveplan/api-logger-worker-proxy Status: PROPOSED Type: new-package Stage: 3 (Worker isolation infrastructure)

Why

Per design doc §5.2a, every capability ships a proxy surface. Logging is special in two ways: (a) it's bidirectional — the worker emits log calls that travel to the main-process logger AND the main host MAY disable worker logs during shutdown so the worker doesn't keep producing records after the sink closes; (b) it's high-volume — even with batching, a sustained worker producing a record per request can quickly saturate the proxy. So this package combines an outbound proxy (worker → main) with a control channel (main → worker, "stop logging now"), plus batching + backpressure to bound the wire cost.

What changes

Net-new package.

ADDED exports:

./client — createLoggerProxyClient(port): WorkerProxyOf<LoggerLike>. info / warn / error / debug / trace calls marshalled to main; pre-tagged with plugin name + version per design doc §5.1.
./batching — batched send (flushIntervalMs default 50, maxBatchSize default 100); flush on error / fatal level immediately. Bounded outstanding-batch budget enforces backpressure.
./control-channel — main → worker disable / enable messages. After disable, worker-side log.info(...) becomes a no-op (records dropped); after enable, normal flow resumes. Used by main host during plugin shutdown so the worker stops producing during dispose.
./error-codes — LOGGER_PROXY_* codes (LOGGER_PROXY_PORT_CLOSED, LOGGER_PROXY_BACKPRESSURE_DROP, LOGGER_PROXY_DISABLED).
./testing — paired MessageChannel + stub main-side sink.

Out of scope

Concrete log sinks — @suaveplan/logger's job (and api-audit-* for audit records).
Trace correlation — span/trace ids are populated main-side; this package preserves them but doesn't compute them.
Log format — main-side logger owns the wire/disk format.

Source mapping

Genesis-original. Design doc sections: §5.2a (worker-RPC variants), §5.1 (pre-tagged logger in PluginContext), §12.3 (logs emitted on span close).

Requirement	Design doc section
Proxy over `LoggerLike` from `@suaveplan/logger`	§5.1
Bidirectional control channel (main can disable worker logs)	Implied by §5.5 disposal (logger disposed last)
Batching to bound wire cost	§5.2a (backpressure)
Pre-tagged with plugin name + version	§5.1

Verification approach

src/client/client.test.ts — every level round-trips; record carries plugin tags.
src/batching/batching.test.ts — batch fills before flush interval → flush; idle → flush at interval; error level flushes immediately.
src/batching/backpressure.test.ts — bounded budget enforced; over-budget records emit LOGGER_PROXY_BACKPRESSURE_DROP counter rather than throwing (logging should be best-effort, not application-breaking).
src/control-channel/control-channel.test.ts — main sends disable → worker log.info becomes no-op; enable restores.

Migration impact

None — additive only.

3.2 KiB Raw Blame History

@suaveplan/api-logger-worker-proxy — worker-side proxy to main-process logger

Why