@bookedsolid/rea 0.2.1 → 0.4.0

package/dist/gateway/audit/rotator.js

@@ -0,0 +1,289 @@
+/**
+ * Audit rotation (G1). Size- and age-based rotation for `.rea/audit.jsonl`
+ * that preserves hash-chain continuity across the rotation boundary.
+ *
+ * ## Triggers
+ *
+ * Rotation fires when EITHER threshold is crossed:
+ *
+ * - `max_bytes` — the current `audit.jsonl` is at or above this many bytes.
+ *   Default when the policy block is present but `max_bytes` is unset:
+ *   `DEFAULT_MAX_BYTES` (50 MiB).
+ * - `max_age_days` — the first record's `timestamp` is older than this many
+ *   days. Default when unset: `DEFAULT_MAX_AGE_DAYS` (30).
+ *
+ * Back-compat: if the `audit.rotation` policy block is ABSENT entirely,
+ * rotation is DISABLED. Defaults only apply when the operator has opted in
+ * by declaring the block (even empty). This is deliberate — we do not want
+ * a 0.2.x install to observe new file-movement behavior on 0.3.0 upgrade
+ * without being asked.
+ *
+ * ## Rotation marker
+ *
+ * On rotation, the current file is renamed to `audit-YYYYMMDD-HHMMSS.jsonl`
+ * in the same directory. A fresh `audit.jsonl` is created containing EXACTLY
+ * one record: a rotation marker.
+ *
+ *     tool_name:          'audit.rotation'
+ *     server_name:        'rea'
+ *     status:             'allowed'
+ *     tier:               'read'
+ *     autonomy_level:     'system'
+ *     prev_hash:          hash of the LAST record in the rotated file
+ *     metadata.rotated_from: the rotated filename (basename)
+ *     metadata.rotated_at:   ISO-8601 instant of rotation
+ *
+ * The marker's `prev_hash` is the chain bridge — an operator verifying the
+ * chain with `rea audit verify --since <rotated-file>` walks rotated →
+ * marker → current and every transition must line up.
+ *
+ * ## Concurrency
+ *
+ * `maybeRotate` is called BEFORE the per-append lock is acquired. It takes
+ * its own short-lived lock on `.rea/` to perform the rename + marker write
+ * atomically. Callers that beat the rotator to the lock simply append to
+ * the (now fresh) file — correctness is preserved because the rotation
+ * marker is a legitimate chain anchor.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { Tier, InvocationStatus } from '../../policy/types.js';
+import { computeHash, readLastRecord, withAuditLock } from '../../audit/fs.js';
+/** 50 MiB. Only applied when the operator has declared `audit.rotation`. */
+export const DEFAULT_MAX_BYTES = 50 * 1024 * 1024;
+/** 30 days. Only applied when the operator has declared `audit.rotation`. */
+export const DEFAULT_MAX_AGE_DAYS = 30;
+export const ROTATION_TOOL_NAME = 'audit.rotation';
+export const ROTATION_SERVER_NAME = 'rea';
+/**
+ * Compute the effective rotation thresholds from policy. If the operator has
+ * NOT declared an `audit.rotation` block, BOTH thresholds are undefined and
+ * rotation is disabled (back-compat with 0.2.x).
+ *
+ * If the block IS declared but individual knobs are missing, apply the
+ * documented defaults.
+ */
+function effectiveThresholds(policy) {
+    const rot = policy?.audit?.rotation;
+    if (rot === undefined) {
+        return { maxBytes: undefined, maxAgeMs: undefined };
+    }
+    // An explicit `audit.rotation: {}` block opts in to both defaults.
+    const maxBytes = rot.max_bytes ?? DEFAULT_MAX_BYTES;
+    const maxAgeDays = rot.max_age_days ?? DEFAULT_MAX_AGE_DAYS;
+    return { maxBytes, maxAgeMs: maxAgeDays * 24 * 60 * 60 * 1000 };
+}
+/**
+ * Build the rotation timestamp filename. UTC for sortability.
+ * Format: `audit-YYYYMMDD-HHMMSS.jsonl`. Collisions (two rotations in the
+ * same second) are resolved by appending `-1`, `-2`, etc.
+ */
+export function rotationFilename(at) {
+    const y = at.getUTCFullYear().toString().padStart(4, '0');
+    const m = (at.getUTCMonth() + 1).toString().padStart(2, '0');
+    const d = at.getUTCDate().toString().padStart(2, '0');
+    const hh = at.getUTCHours().toString().padStart(2, '0');
+    const mm = at.getUTCMinutes().toString().padStart(2, '0');
+    const ss = at.getUTCSeconds().toString().padStart(2, '0');
+    return `audit-${y}${m}${d}-${hh}${mm}${ss}.jsonl`;
+}
+/**
+ * Probe the first record's timestamp WITHOUT loading the whole file into
+ * memory as a JSON blob. We read up to the first newline and parse just
+ * that line. Returns `undefined` if the file is empty / unreadable / the
+ * first line isn't valid JSON with a usable `timestamp` field.
+ */
+async function readFirstTimestamp(auditFile) {
+    let fh;
+    try {
+        fh = await fs.open(auditFile, 'r');
+        // 64 KiB is enough for the first record under any realistic schema.
+        const buf = Buffer.alloc(64 * 1024);
+        const { bytesRead } = await fh.read(buf, 0, buf.length, 0);
+        if (bytesRead === 0)
+            return undefined;
+        const chunk = buf.slice(0, bytesRead).toString('utf8');
+        const newline = chunk.indexOf('\n');
+        const firstLine = newline === -1 ? chunk : chunk.slice(0, newline);
+        if (firstLine.length === 0)
+            return undefined;
+        const parsed = JSON.parse(firstLine);
+        if (typeof parsed.timestamp !== 'string')
+            return undefined;
+        const ts = Date.parse(parsed.timestamp);
+        if (Number.isNaN(ts))
+            return undefined;
+        return new Date(ts);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fh)
+            await fh.close();
+    }
+}
+/**
+ * Decide whether the current audit file has crossed any rotation threshold.
+ * Exported for testing.
+ */
+export async function shouldRotate(auditFile, thresholds, now = new Date()) {
+    if (thresholds.maxBytes === undefined && thresholds.maxAgeMs === undefined) {
+        return false;
+    }
+    let size;
+    try {
+        const stat = await fs.stat(auditFile);
+        if (!stat.isFile())
+            return false;
+        size = stat.size;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return false;
+        throw err;
+    }
+    // Empty files never rotate — rotating an empty file would create a chain
+    // anchored on genesis with a dangling predecessor.
+    if (size === 0)
+        return false;
+    if (thresholds.maxBytes !== undefined && size >= thresholds.maxBytes) {
+        return true;
+    }
+    if (thresholds.maxAgeMs !== undefined) {
+        const firstTs = await readFirstTimestamp(auditFile);
+        if (firstTs !== undefined) {
+            const ageMs = now.getTime() - firstTs.getTime();
+            if (ageMs >= thresholds.maxAgeMs)
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Pick a rotation filename that doesn't collide with an existing file.
+ * Returns the absolute path.
+ */
+async function pickRotationPath(reaDir, at) {
+    const base = rotationFilename(at);
+    const baseNoExt = base.replace(/\.jsonl$/, '');
+    let candidate = path.join(reaDir, base);
+    let suffix = 1;
+    while (true) {
+        try {
+            await fs.access(candidate);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                return candidate;
+            }
+            throw err;
+        }
+        candidate = path.join(reaDir, `${baseNoExt}-${suffix}.jsonl`);
+        suffix += 1;
+        if (suffix > 1000) {
+            throw new Error(`Unable to pick rotation filename in ${reaDir} — 1000 collisions`);
+        }
+    }
+}
+/**
+ * Perform the rotation unconditionally. Assumes the caller has already
+ * determined rotation is warranted and holds (or is about to acquire) any
+ * outer locks. `performRotation` takes its own lock on `.rea/` to make the
+ * rename + marker write atomic w.r.t. other append-path lockers.
+ *
+ * Returns `{ rotated: false }` if the audit file is empty or missing — an
+ * empty file is a no-op by design (see `rea audit rotate` empty-case).
+ */
+export async function performRotation(auditFile, now = new Date()) {
+    const reaDir = path.dirname(auditFile);
+    // Ensure the parent exists so withAuditLock can place a lock file. The
+    // caller normally creates this; we mkdir defensively for the force-rotate
+    // path (`rea audit rotate` on a green-field install).
+    await fs.mkdir(reaDir, { recursive: true });
+    return withAuditLock(auditFile, async () => {
+        // Re-check the file under the lock. Another writer may have rotated
+        // between the caller's decision and our lock acquisition.
+        let size;
+        try {
+            const stat = await fs.stat(auditFile);
+            if (!stat.isFile())
+                return { rotated: false };
+            size = stat.size;
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return { rotated: false };
+            throw err;
+        }
+        if (size === 0)
+            return { rotated: false };
+        // Pull the last record's hash BEFORE renaming — so we can anchor the
+        // marker's prev_hash on the old chain's tail. readLastRecord also
+        // performs partial-write recovery under our lock (idempotent).
+        const { hash: tailHash } = await readLastRecord(auditFile);
+        const rotatedPath = await pickRotationPath(reaDir, now);
+        await fs.rename(auditFile, rotatedPath);
+        // Write the rotation marker into a fresh audit.jsonl. The marker's
+        // prev_hash is the old tail's hash — operators can walk rotated →
+        // marker and the chain holds.
+        const markerBase = {
+            timestamp: now.toISOString(),
+            session_id: 'system',
+            tool_name: ROTATION_TOOL_NAME,
+            server_name: ROTATION_SERVER_NAME,
+            tier: Tier.Read,
+            status: InvocationStatus.Allowed,
+            autonomy_level: 'system',
+            duration_ms: 0,
+            prev_hash: tailHash,
+            metadata: {
+                rotated_from: path.basename(rotatedPath),
+                rotated_at: now.toISOString(),
+            },
+        };
+        const markerHash = computeHash(markerBase);
+        const marker = { ...markerBase, hash: markerHash };
+        const line = JSON.stringify(marker) + '\n';
+        await fs.writeFile(auditFile, line, { flag: 'w' });
+        return { rotated: true, rotatedTo: rotatedPath };
+    });
+}
+/**
+ * Called by the append path BEFORE acquiring its own lock. Cheap when no
+ * rotation is due (one stat, maybe one 64 KiB read for age check); idempotent
+ * when rotation IS due (performRotation re-checks under the lock).
+ *
+ * Never throws. On any error, logs to stderr and returns `rotated: false`
+ * — a broken rotator must NOT break the audit append.
+ */
+export async function maybeRotate(auditFile, policy, now = new Date()) {
+    try {
+        const thresholds = effectiveThresholds(policy);
+        if (thresholds.maxBytes === undefined && thresholds.maxAgeMs === undefined) {
+            return { rotated: false };
+        }
+        const due = await shouldRotate(auditFile, thresholds, now);
+        if (!due)
+            return { rotated: false };
+        return await performRotation(auditFile, now);
+    }
+    catch (err) {
+        console.error('[rea] AUDIT ROTATION FAILED:', err instanceof Error ? err.message : String(err));
+        return { rotated: false };
+    }
+}
+/**
+ * CLI-invoked force rotation (`rea audit rotate`). Unlike `maybeRotate` this
+ * DOES ignore thresholds — the operator asked explicitly — but empty files
+ * are still a no-op because rotating an empty chain produces a marker with
+ * no predecessor.
+ */
+export async function forceRotate(auditFile, now = new Date()) {
+    return performRotation(auditFile, now);
+}
+/**
+ * Exposed for tests/callers that already know the policy shape. Tests that
+ * want to stub thresholds can call `performRotation` directly.
+ */
+export { effectiveThresholds as _effectiveThresholds };

package/dist/gateway/circuit-breaker.d.ts

@@ -1,9 +1,24 @@
 export type CircuitState = 'closed' | 'open' | 'half-open';
+/**
+ * Callback invoked on every circuit state transition (G5). The constructor
+ * can wire this to a structured logger and/or a metrics gauge so state
+ * changes are observable without requiring the breaker itself to depend on
+ * those modules.
+ */
+export type CircuitStateChangeListener = (event: {
+    server: string;
+    from: CircuitState;
+    to: CircuitState;
+    reason: 'failure_threshold' | 'cooldown_elapsed' | 'recovered' | 'half_open_failed';
+    retryAt?: string;
+}) => void;
 export interface CircuitBreakerOptions {
     /** Consecutive failures before opening the circuit. Default: 5 */
     failureThreshold?: number;
     /** Milliseconds to wait in open state before moving to half-open. Default: 30_000 */
     cooldownMs?: number;
+    /** Optional listener for state transitions. See {@link CircuitStateChangeListener}. */
+    onStateChange?: CircuitStateChangeListener;
 }
 export interface CircuitStatus {
     state: CircuitState;
@@ -29,7 +44,9 @@ interface CircuitEntry {
 export declare class CircuitBreaker {
     private circuits;
     private defaultOptions;
+    private readonly onStateChange;
     constructor(defaults?: CircuitBreakerOptions);
+    private notify;
     private getOrCreate;
     /**
      * Returns null if the call may proceed, or a CircuitStatus if the circuit is open.

package/dist/gateway/circuit-breaker.js

@@ -10,11 +10,23 @@
 export class CircuitBreaker {
     circuits = new Map();
     defaultOptions;
+    onStateChange;
     constructor(defaults = {}) {
         this.defaultOptions = {
             failureThreshold: defaults.failureThreshold ?? 5,
             cooldownMs: defaults.cooldownMs ?? 30_000,
         };
+        this.onStateChange = defaults.onStateChange;
+    }
+    notify(event) {
+        if (this.onStateChange === undefined)
+            return;
+        try {
+            this.onStateChange(event);
+        }
+        catch {
+            // Listeners must never break the breaker. Swallow.
+        }
     }
     getOrCreate(serverName) {
         let entry = this.circuits.get(serverName);
@@ -43,7 +55,12 @@ export class CircuitBreaker {
             if (elapsed >= entry.cooldownMs) {
                 entry.state = 'half-open';
                 entry.consecutiveFailures = 0;
-                console.error(`[rea] circuit-breaker: "${serverName}" transitioned open → half-open (probing recovery)`);
+                this.notify({
+                    server: serverName,
+                    from: 'open',
+                    to: 'half-open',
+                    reason: 'cooldown_elapsed',
+                });
                 return null;
             }
             const retryAt = new Date((entry.openedAt ?? 0) + entry.cooldownMs).toISOString();
@@ -61,7 +78,12 @@ export class CircuitBreaker {
             entry.state = 'closed';
             entry.consecutiveFailures = 0;
             entry.openedAt = null;
-            console.error(`[rea] circuit-breaker: "${serverName}" recovered — circuit closed`);
+            this.notify({
+                server: serverName,
+                from: 'half-open',
+                to: 'closed',
+                reason: 'recovered',
+            });
         }
         else if (entry.state === 'closed') {
             entry.consecutiveFailures = 0;
@@ -71,13 +93,20 @@ export class CircuitBreaker {
         const entry = this.getOrCreate(serverName);
         if (entry.state === 'open')
             return;
+        const previous = entry.state;
         entry.consecutiveFailures++;
         const shouldOpen = entry.state === 'half-open' || entry.consecutiveFailures >= entry.failureThreshold;
         if (shouldOpen) {
             entry.state = 'open';
             entry.openedAt = Date.now();
             const retryAt = new Date(entry.openedAt + entry.cooldownMs).toISOString();
-            console.error(`[rea] circuit-breaker: "${serverName}" OPENED after ${entry.consecutiveFailures} failure(s) — will retry at ${retryAt}`);
+            this.notify({
+                server: serverName,
+                from: previous,
+                to: 'open',
+                reason: previous === 'half-open' ? 'half_open_failed' : 'failure_threshold',
+                retryAt,
+            });
         }
     }
     getCircuit(serverName) {

package/dist/gateway/downstream-pool.d.ts

@@ -7,6 +7,7 @@
  */
 import { DownstreamConnection, type DownstreamToolInfo } from './downstream.js';
 import type { Registry } from '../registry/types.js';
+import type { Logger } from './log.js';
 export interface PrefixedTool extends DownstreamToolInfo {
     /** Server name, not prefixed. */
     server: string;
@@ -15,7 +16,7 @@ export interface PrefixedTool extends DownstreamToolInfo {
 }
 export declare class DownstreamPool {
     private readonly connections;
-    constructor(registry: Registry);
+    constructor(registry: Registry, logger?: Logger);
     get size(): number;
     connectAll(): Promise<void>;
     /**

package/dist/gateway/downstream-pool.js

@@ -8,11 +8,11 @@
 import { DownstreamConnection } from './downstream.js';
 export class DownstreamPool {
     connections = new Map();
-    constructor(registry) {
+    constructor(registry, logger) {
         for (const server of registry.servers) {
             if (!server.enabled)
                 continue;
-            this.connections.set(server.name, new DownstreamConnection(server));
+            this.connections.set(server.name, new DownstreamConnection(server, logger));
         }
     }
     get size() {

package/dist/gateway/downstream.d.ts

@@ -36,6 +36,7 @@
  * a transport error could double-post. We leave the decision to the caller.
  */
 import type { RegistryServer } from '../registry/types.js';
+import type { Logger } from './log.js';
 export interface DownstreamToolInfo {
     name: string;
     description?: string;
@@ -43,15 +44,44 @@ export interface DownstreamToolInfo {
 }
 /**
  * Build the child env by layering:
- *   allowlist → registry env_passthrough → registry env.
+ *   allowlist → registry env_passthrough → interpolated registry env.
  * Later entries win. Missing host values are skipped so `process.env[name]`
  * being undefined does not serialize as the literal string "undefined".
  *
+ * The explicit `env:` map may contain `${VAR}` placeholders (see
+ * `registry/interpolate.ts` for the exact grammar). Placeholders referencing
+ * unset host vars are returned via the `missing` array — the caller MUST
+ * refuse to spawn the server if `missing.length > 0`, otherwise the child
+ * receives unresolved `${...}` strings which are nearly always wrong.
+ *
  * Exported for testing.
  */
-export declare function buildChildEnv(config: RegistryServer, hostEnv?: NodeJS.ProcessEnv): Record<string, string>;
+export interface BuiltChildEnv {
+    /** Fully resolved env to pass to the child transport. */
+    env: Record<string, string>;
+    /**
+     * Names of `${VAR}` references that were not set in `hostEnv`. When
+     * non-empty, the caller MUST NOT spawn the child — mark the connection
+     * unhealthy and log each entry.
+     */
+    missing: string[];
+    /**
+     * Keys in `env` whose value is secret-bearing (either because the key
+     * name matches the secret-name heuristic, or because one of its
+     * interpolated `${VAR}` references did). Callers MUST NOT log the
+     * corresponding values.
+     */
+    secretKeys: string[];
+}
+export declare function buildChildEnv(config: RegistryServer, hostEnv?: NodeJS.ProcessEnv): BuiltChildEnv;
 export declare class DownstreamConnection {
     private readonly config;
+    /**
+     * Optional structured logger (G5). When omitted, connection lifecycle
+     * events are simply not logged — keeping the class usable in unit tests
+     * that don't care about observability.
+     */
+    private readonly logger?;
     private client;
     /**
      * Whether a reconnect has already been attempted in the CURRENT failure
@@ -63,7 +93,13 @@ export declare class DownstreamConnection {
     /** Epoch ms of the last successful reconnect. Used by the flapping guard. */
     private lastReconnectAt;
     private health;
-    constructor(config: RegistryServer);
+    constructor(config: RegistryServer, 
+    /**
+     * Optional structured logger (G5). When omitted, connection lifecycle
+     * events are simply not logged — keeping the class usable in unit tests
+     * that don't care about observability.
+     */
+    logger?: Logger | undefined);
     get name(): string;
     get isHealthy(): boolean;
     connect(): Promise<void>;

package/dist/gateway/downstream.js

@@ -37,6 +37,7 @@
  */
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { interpolateEnv } from '../registry/interpolate.js';
 /**
  * Neutral env vars every child inherits. These are the ones shells/toolchains
  * need to function but carry no secrets in a well-configured environment.
@@ -66,14 +67,6 @@ const DEFAULT_ENV_ALLOWLIST = [
  * handle it.
  */
 const RECONNECT_FLAP_WINDOW_MS = 30_000;
-/**
- * Build the child env by layering:
- *   allowlist → registry env_passthrough → registry env.
- * Later entries win. Missing host values are skipped so `process.env[name]`
- * being undefined does not serialize as the literal string "undefined".
- *
- * Exported for testing.
- */
 export function buildChildEnv(config, hostEnv = process.env) {
     const out = {};
     for (const name of DEFAULT_ENV_ALLOWLIST) {
@@ -88,14 +81,21 @@ export function buildChildEnv(config, hostEnv = process.env) {
                 out[name] = v;
         }
     }
+    // Interpolate placeholders in config.env BEFORE layering it on top.
+    // `interpolateEnv` is pure — no I/O, throws only on malformed syntax
+    // (unterminated brace, empty `${}`, illegal var name). Missing host
+    // vars are reported via `result.missing`; the caller decides whether
+    // to refuse the spawn.
+    const interp = interpolateEnv(config.env, hostEnv);
     // Explicit config.env wins — operator typed these values deliberately.
-    for (const [k, v] of Object.entries(config.env)) {
+    for (const [k, v] of Object.entries(interp.resolved)) {
         out[k] = v;
     }
-    return out;
+    return { env: out, missing: interp.missing, secretKeys: interp.secretKeys };
 }
 export class DownstreamConnection {
     config;
+    logger;
     client = null;
     /**
      * Whether a reconnect has already been attempted in the CURRENT failure
@@ -107,8 +107,15 @@ export class DownstreamConnection {
     /** Epoch ms of the last successful reconnect. Used by the flapping guard. */
     lastReconnectAt = 0;
     health = 'healthy';
-    constructor(config) {
+    constructor(config, 
+    /**
+     * Optional structured logger (G5). When omitted, connection lifecycle
+     * events are simply not logged — keeping the class usable in unit tests
+     * that don't care about observability.
+     */
+    logger) {
         this.config = config;
+        this.logger = logger;
     }
     get name() {
         return this.config.name;
@@ -119,10 +126,40 @@ export class DownstreamConnection {
     async connect() {
         if (this.client !== null)
             return;
+        // Resolve env BEFORE spawning. If any `${VAR}` reference in the registry's
+        // explicit env: map is unset at startup, refuse to spawn this server:
+        //   - log a clear, secret-safe error (only the var name appears; the
+        //     resolved value would not exist anyway since it's missing)
+        //   - mark this connection unhealthy so the pool skips it
+        //   - leave every other server's spawn path untouched (the gateway as a
+        //     whole keeps coming up)
+        //
+        // Malformed syntax (unterminated brace, `${}`, illegal identifier) throws
+        // from interpolateEnv — that's a load-time error and we propagate it so
+        // the operator sees it at startup with server context attached.
+        let built;
+        try {
+            built = buildChildEnv(this.config);
+        }
+        catch (err) {
+            this.health = 'unhealthy';
+            throw new Error(`failed to resolve env for downstream "${this.config.name}": ${err instanceof Error ? err.message : err}`);
+        }
+        if (built.missing.length > 0) {
+            this.health = 'unhealthy';
+            // One line per missing var so grep/jq users can find the exact gap.
+            // We intentionally do NOT log the env key name's VALUE (there is none —
+            // it's unresolved) nor any other env values.
+            for (const missingVar of built.missing) {
+                console.error(`[rea-gateway] refusing to start downstream "${this.config.name}": ` +
+                    `env references ${'${'}${missingVar}${'}'} but process.env.${missingVar} is not set`);
+            }
+            throw new Error(`downstream "${this.config.name}" refused to start — missing env: ${built.missing.join(', ')}`);
+        }
         const transport = new StdioClientTransport({
             command: this.config.command,
             args: this.config.args,
-            env: buildChildEnv(this.config),
+            env: built.env,
         });
         const client = new Client({ name: `rea-gateway-client:${this.config.name}`, version: '0.2.0' }, { capabilities: {} });
         try {
@@ -157,11 +194,16 @@ export class DownstreamConnection {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            const withinFlapWindow = this.lastReconnectAt !== 0 &&
-                Date.now() - this.lastReconnectAt < RECONNECT_FLAP_WINDOW_MS;
+            const withinFlapWindow = this.lastReconnectAt !== 0 && Date.now() - this.lastReconnectAt < RECONNECT_FLAP_WINDOW_MS;
             if (!this.reconnectAttempted && !withinFlapWindow) {
                 this.reconnectAttempted = true;
                 this.health = 'degraded';
+                this.logger?.warn({
+                    event: 'downstream.reconnect_attempt',
+                    server_name: this.config.name,
+                    message: `downstream "${this.config.name}" will reconnect once after error`,
+                    reason: message,
+                });
                 try {
                     await this.close();
                     await this.connect();
@@ -170,14 +212,31 @@ export class DownstreamConnection {
                     // stamp the reconnect time so flap-guard can refuse rapid repeats.
                     this.reconnectAttempted = false;
                     this.lastReconnectAt = Date.now();
+                    this.logger?.info({
+                        event: 'downstream.reconnected',
+                        server_name: this.config.name,
+                        message: `downstream "${this.config.name}" reconnected successfully`,
+                    });
                     return result;
                 }
                 catch (reconnectErr) {
                     this.health = 'unhealthy';
+                    this.logger?.error({
+                        event: 'downstream.reconnect_failed',
+                        server_name: this.config.name,
+                        message: `downstream "${this.config.name}" unhealthy after one reconnect`,
+                        error: reconnectErr instanceof Error ? reconnectErr.message : String(reconnectErr),
+                    });
                     throw new Error(`downstream "${this.config.name}" unhealthy after one reconnect: ${reconnectErr instanceof Error ? reconnectErr.message : reconnectErr}`);
                 }
             }
             this.health = 'unhealthy';
+            this.logger?.error({
+                event: 'downstream.call_failed',
+                server_name: this.config.name,
+                message: `downstream "${this.config.name}" call failed`,
+                error: message,
+            });
             throw new Error(`downstream "${this.config.name}" call failed: ${message}`);
         }
     }