@naylence/runtime 0.3.5-test.954 → 0.3.5-test.956

package/dist/browser/index.mjs

@@ -96,12 +96,12 @@ installProcessEnvShim();
 // --- END ENV SHIM ---
 
 // This file is auto-generated during build - do not edit manually
-// Generated from package.json version: 0.3.5-test.954
+// Generated from package.json version: 0.3.5-test.956
 /**
  * The package version, injected at build time.
  * @internal
  */
-const VERSION = '0.3.5-test.954';
+const VERSION = '0.3.5-test.956';
 
 /**
  * Fame protocol specific error classes with WebSocket close codes and proper inheritance.
@@ -919,7 +919,7 @@ class TaskCancelledError extends Error {
  * Provides functionality similar to Python's asyncio TaskSpawner with proper
  * error handling, cancellation, and graceful shutdown capabilities.
  */
-const logger$1b = getLogger('naylence.fame.util.task_spawner');
+const logger$1c = getLogger('naylence.fame.util.task_spawner');
 function firstDefined(source, keys) {
     for (const key of keys) {
         if (Object.prototype.hasOwnProperty.call(source, key)) {
@@ -1080,7 +1080,7 @@ class TaskSpawner {
         const taskId = `task-${++this._taskCounter}`;
         const taskName = normalizedOptions.name || `unnamed-${taskId}`;
         const timeout = normalizedOptions.timeout ?? this._config.defaultTimeout;
-        logger$1b.debug('starting_background_task', {
+        logger$1c.debug('starting_background_task', {
             task_name: taskName,
             task_id: taskId,
         });
@@ -1097,7 +1097,7 @@ class TaskSpawner {
         task.promise
             .then(() => {
             if (!this._suppressCompletionLogging) {
-                logger$1b.debug('task_completed_successfully', {
+                logger$1c.debug('task_completed_successfully', {
                     task_name: taskName,
                     task_id: taskId,
                     duration_ms: Date.now() - task.startTime,
@@ -1151,7 +1151,7 @@ class TaskSpawner {
             error.name === 'AbortError' ||
             error.message === 'Task cancelled' ||
             error.message === 'Aborted') {
-            logger$1b.debug('task_cancelled', {
+            logger$1c.debug('task_cancelled', {
                 task_name: taskName,
                 note: 'Task cancelled as requested',
             });
@@ -1159,7 +1159,7 @@ class TaskSpawner {
         }
         // Handle timeout
         if (error instanceof TaskTimeoutError) {
-            logger$1b.warning('task_timed_out', {
+            logger$1c.warning('task_timed_out', {
                 task_name: taskName,
                 error: error.message,
             });
@@ -1171,7 +1171,7 @@ class TaskSpawner {
         // Handle known WebSocket shutdown race condition (similar to Python version)
         if (error.message.includes("await wasn't used with future") ||
             error.message.includes('WebSocket closed during receive')) {
-            logger$1b.debug('task_shutdown_race_condition_handled', {
+            logger$1c.debug('task_shutdown_race_condition_handled', {
                 task_name: taskName,
                 note: 'Normal WebSocket close timing during shutdown - not an error',
             });
@@ -1181,7 +1181,7 @@ class TaskSpawner {
         if (error.name === 'FameTransportClose' ||
             error.message.includes('normal closure') ||
             error.message.includes('Connection closed')) {
-            logger$1b.debug('task_shutdown_completed_normally', {
+            logger$1c.debug('task_shutdown_completed_normally', {
                 task_name: taskName,
                 note: 'Task closed normally during shutdown',
             });
@@ -1194,14 +1194,14 @@ class TaskSpawner {
         // Log retriable errors as warnings (they'll be retried by upstream logic)
         // Log non-retriable errors as errors (fatal failures)
         if (isRetriableError) {
-            logger$1b.warning('background_task_failed', {
+            logger$1c.warning('background_task_failed', {
                 task_name: taskName,
                 error: error.message,
                 retriable: true,
             });
         }
         else {
-            logger$1b.error('background_task_failed', {
+            logger$1c.error('background_task_failed', {
                 task_name: taskName,
                 error: error.message,
                 stack: error.stack,
@@ -1220,11 +1220,11 @@ class TaskSpawner {
     async shutdownTasks(options = {}) {
         const { gracePeriod, cancelHanging, joinTimeout } = normalizeShutdownOptions(options);
         if (this._tasks.size === 0) {
-            logger$1b.debug('shutdown_tasks_no_tasks_to_shutdown');
+            logger$1c.debug('shutdown_tasks_no_tasks_to_shutdown');
             return;
         }
         this._suppressCompletionLogging = true;
-        logger$1b.debug('shutting_down_tasks', {
+        logger$1c.debug('shutting_down_tasks', {
             task_count: this._tasks.size,
             task_names: Array.from(this._tasks.values()).map((t) => t.name),
             grace_period_ms: gracePeriod,
@@ -1239,7 +1239,7 @@ class TaskSpawner {
         if (cancelHanging) {
             const stillRunning = tasks.filter((task) => task.getState() === TaskState.RUNNING && !completed.has(task));
             if (stillRunning.length > 0) {
-                logger$1b.debug('tasks_did_not_complete_within_grace_period', {
+                logger$1c.debug('tasks_did_not_complete_within_grace_period', {
                     hanging_count: stillRunning.length,
                 });
                 // Wait for them to finish with individual timeouts
@@ -1249,7 +1249,7 @@ class TaskSpawner {
                     }
                     catch (error) {
                         if (error instanceof TaskTimeoutError) {
-                            logger$1b.warning('task_did_not_shutdown', {
+                            logger$1c.warning('task_did_not_shutdown', {
                                 task_name: task.name || task.id,
                                 join_timeout_ms: joinTimeout,
                             });
@@ -1260,7 +1260,7 @@ class TaskSpawner {
                         }
                         else if (!(error instanceof TaskCancelledError)) {
                             /* istanbul ignore next - unreachable defensive branch */
-                            logger$1b.error('task_raised_during_cancellation', {
+                            logger$1c.error('task_raised_during_cancellation', {
                                 task_name: task.name || task.id,
                                 error: error instanceof Error ? error.message : String(error),
                             });
@@ -2353,6 +2353,7 @@ function validateKeyCorrelationTtlSec(ttlSec) {
  * condition/promise and ensure at most one notifier coroutine exists for a
  * flow at any time.
  */
+const logger$1b = getLogger('naylence.fame.flow.flow_controller');
 /**
  * Simple condition variable implementation for TypeScript/Node.js
  * Similar to Python's asyncio.Condition
@@ -2478,8 +2479,17 @@ class FlowController {
         // clamp into [0, initialWindow]
         const newBalance = Math.max(0, Math.min(this.initialWindow, prev + delta));
         this.credits.set(flowId, newBalance);
+        const crossedZero = prev <= 0 && newBalance > 0;
+        logger$1b.debug('flow_controller_add_credits', {
+            flow_id: flowId,
+            delta,
+            prev_balance: prev,
+            new_balance: newBalance,
+            initial_window: this.initialWindow,
+            crossed_zero: crossedZero,
+        });
         // wake waiters only if we crossed the zero boundary
-        if (prev <= 0 && newBalance > 0) {
+        if (crossedZero) {
             this.wakeWaiters(flowId);
         }
         return newBalance;
@@ -2490,11 +2500,27 @@ class FlowController {
     async acquire(flowId) {
         this.ensureFlow(flowId);
         const condition = this.conditions.get(flowId);
+        logger$1b.debug('flow_controller_acquire_attempt', {
+            flow_id: flowId,
+            current_balance: this.credits.get(flowId),
+        });
         while (this.credits.get(flowId) <= 0) {
+            logger$1b.debug('flow_controller_waiting_for_credit', {
+                flow_id: flowId,
+            });
             await condition.wait();
+            logger$1b.debug('flow_controller_woke_with_credit', {
+                flow_id: flowId,
+                balance_after_wake: this.credits.get(flowId),
+            });
         }
         const current = this.credits.get(flowId);
         this.credits.set(flowId, current - 1);
+        logger$1b.debug('flow_controller_credit_consumed', {
+            flow_id: flowId,
+            prev_balance: current,
+            remaining_balance: current - 1,
+        });
     }
     /**
      * Consume *credits* immediately (non-blocking).
@@ -2514,6 +2540,12 @@ class FlowController {
         const current = this.credits.get(flowId);
         const remaining = Math.max(current - credits, 0);
         this.credits.set(flowId, remaining);
+        logger$1b.debug('flow_controller_consume', {
+            flow_id: flowId,
+            requested: credits,
+            prev_balance: current,
+            remaining_balance: remaining,
+        });
         return remaining;
     }
     /**
@@ -2534,6 +2566,10 @@ class FlowController {
         this.windowIds.delete(flowId);
         this.credits.set(flowId, this.initialWindow);
         this.wakeWaiters(flowId);
+        logger$1b.debug('flow_controller_flow_reset', {
+            flow_id: flowId,
+            reset_balance: this.initialWindow,
+        });
     }
     /**
      * Return `[windowId, flags]` for the next outbound envelope.
@@ -9381,10 +9417,12 @@ class BaseAsyncConnector extends TaskSpawner {
             throw new FameTransportClose('Connection closed', 1006);
         }
         // Apply flow control if enabled and not a credit update
-        if (this._fcEnabled &&
-            !(envelope.frame &&
-                'flow_id' in envelope.frame &&
-                'credits' in envelope.frame)) {
+        const isCreditUpdateFrame = Boolean(envelope.frame &&
+            (envelope.frame.type === 'CreditUpdate' ||
+                envelope.frame.type === 'credit_update' ||
+                ('flowId' in envelope.frame && 'credits' in envelope.frame) ||
+                ('flow_id' in envelope.frame && 'credits' in envelope.frame)));
+        if (this._fcEnabled && !isCreditUpdateFrame) {
             const flowId = envelope.flowId || this._connectorFlowId;
             envelope.flowId = flowId;
             const t0 = this._metrics ? performance.now() : 0;
@@ -9879,6 +9917,7 @@ let BroadcastChannelConnector$2 = class BroadcastChannelConnector extends BaseAs
             ? Math.floor(config.inboxCapacity)
             : DEFAULT_INBOX_CAPACITY$7;
         this.inbox = new BoundedAsyncQueue(preferredCapacity);
+        this.inboxCapacity = preferredCapacity;
         this.connectorId = BroadcastChannelConnector.generateConnectorId();
         this.channel = new BroadcastChannel(this.channelName);
         logger$_.debug('broadcast_channel_connector_created', {
@@ -9938,15 +9977,27 @@ let BroadcastChannelConnector$2 = class BroadcastChannelConnector extends BaseAs
                 if (typeof this.inbox.tryEnqueue === 'function') {
                     const accepted = this.inbox.tryEnqueue(payload);
                     if (accepted) {
+                        this.logInboxSnapshot('broadcast_channel_inbox_enqueued', {
+                            source: 'listener',
+                            enqueue_strategy: 'try',
+                            payload_length: payload.byteLength,
+                        });
                         return;
                     }
                 }
                 this.inbox.enqueue(payload);
+                this.logInboxSnapshot('broadcast_channel_inbox_enqueued', {
+                    source: 'listener',
+                    enqueue_strategy: 'enqueue',
+                    payload_length: payload.byteLength,
+                });
             }
             catch (error) {
                 if (error instanceof QueueFullError) {
                     logger$_.warning('broadcast_channel_receive_queue_full', {
                         channel: this.channelName,
+                        inbox_capacity: this.inboxCapacity,
+                        inbox_remaining_capacity: this.inbox.remainingCapacity,
                     });
                 }
                 else {
@@ -9957,8 +10008,10 @@ let BroadcastChannelConnector$2 = class BroadcastChannelConnector extends BaseAs
                 }
             }
         };
-        this.channel.addEventListener('message', this.onMsg);
-        this.listenerRegistered = true;
+        if (!config.passive) {
+            this.channel.addEventListener('message', this.onMsg);
+            this.listenerRegistered = true;
+        }
         // Setup visibility change monitoring
         this.visibilityChangeHandler = () => {
             const isHidden = document.hidden;
@@ -10030,15 +10083,25 @@ let BroadcastChannelConnector$2 = class BroadcastChannelConnector extends BaseAs
             if (typeof this.inbox.tryEnqueue === 'function') {
                 const accepted = this.inbox.tryEnqueue(item);
                 if (accepted) {
+                    this.logInboxSnapshot('broadcast_channel_push_enqueued', {
+                        enqueue_strategy: 'try',
+                        item_type: this._describeInboxItem(item),
+                    });
                     return;
                 }
             }
             this.inbox.enqueue(item);
+            this.logInboxSnapshot('broadcast_channel_push_enqueued', {
+                enqueue_strategy: 'enqueue',
+                item_type: this._describeInboxItem(item),
+            });
         }
         catch (error) {
             if (error instanceof QueueFullError) {
                 logger$_.warning('broadcast_channel_push_queue_full', {
                     channel: this.channelName,
+                    inbox_capacity: this.inboxCapacity,
+                    inbox_remaining_capacity: this.inbox.remainingCapacity,
                 });
                 throw error;
             }
@@ -10061,7 +10124,11 @@ let BroadcastChannelConnector$2 = class BroadcastChannelConnector extends BaseAs
         });
     }
     async _transportReceive() {
-        return await this.inbox.dequeue();
+        const item = await this.inbox.dequeue();
+        this.logInboxSnapshot('broadcast_channel_inbox_dequeued', {
+            item_type: this._describeInboxItem(item),
+        });
+        return item;
     }
     async _transportClose(code, reason) {
         logger$_.debug('broadcast_channel_transport_closing', {
@@ -10115,6 +10182,28 @@ let BroadcastChannelConnector$2 = class BroadcastChannelConnector extends BaseAs
         }
         return rawOrEnvelope;
     }
+    _describeInboxItem(item) {
+        if (item instanceof Uint8Array) {
+            return 'bytes';
+        }
+        if (item.envelope) {
+            return 'channel_message';
+        }
+        if (item.frame) {
+            return 'envelope';
+        }
+        return 'unknown';
+    }
+    logInboxSnapshot(event, extra = {}) {
+        logger$_.debug(event, {
+            channel: this.channelName,
+            connector_id: this.connectorId,
+            connector_state: this.state,
+            inbox_capacity: this.inboxCapacity,
+            inbox_remaining_capacity: this.inbox.remainingCapacity,
+            ...extra,
+        });
+    }
     _shouldSkipDuplicateAck(senderId, payload) {
         const dedupKey = this._extractAckDedupKey(payload);
         if (!dedupKey) {
@@ -29941,6 +30030,7 @@ class BroadcastChannelListener extends TransportListener {
                         type: BROADCAST_CHANNEL_CONNECTOR_TYPE,
                         channelName: this._channelName,
                         inboxCapacity: this._inboxCapacity,
+                        passive: true,
                     };
         }
         try {
@@ -30001,6 +30091,7 @@ class BroadcastChannelListener extends TransportListener {
             type: BROADCAST_CHANNEL_CONNECTOR_TYPE,
             channelName: this._channelName,
             inboxCapacity: this._inboxCapacity,
+            passive: true,
         };
         const channelCandidate = candidate.channelName ?? candidate['channel_name'];
         if (typeof channelCandidate === 'string' && channelCandidate.trim().length > 0) {

package/dist/cjs/naylence/fame/channel/flow-controller.js

@@ -25,6 +25,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FlowController = void 0;
 const core_1 = require("@naylence/core");
+const logging_js_1 = require("../util/logging.js");
+const logger = (0, logging_js_1.getLogger)('naylence.fame.flow.flow_controller');
 /**
  * Simple condition variable implementation for TypeScript/Node.js
  * Similar to Python's asyncio.Condition
@@ -150,8 +152,17 @@ class FlowController {
         // clamp into [0, initialWindow]
         const newBalance = Math.max(0, Math.min(this.initialWindow, prev + delta));
         this.credits.set(flowId, newBalance);
+        const crossedZero = prev <= 0 && newBalance > 0;
+        logger.debug('flow_controller_add_credits', {
+            flow_id: flowId,
+            delta,
+            prev_balance: prev,
+            new_balance: newBalance,
+            initial_window: this.initialWindow,
+            crossed_zero: crossedZero,
+        });
         // wake waiters only if we crossed the zero boundary
-        if (prev <= 0 && newBalance > 0) {
+        if (crossedZero) {
             this.wakeWaiters(flowId);
         }
         return newBalance;
@@ -162,11 +173,27 @@ class FlowController {
     async acquire(flowId) {
         this.ensureFlow(flowId);
         const condition = this.conditions.get(flowId);
+        logger.debug('flow_controller_acquire_attempt', {
+            flow_id: flowId,
+            current_balance: this.credits.get(flowId),
+        });
         while (this.credits.get(flowId) <= 0) {
+            logger.debug('flow_controller_waiting_for_credit', {
+                flow_id: flowId,
+            });
             await condition.wait();
+            logger.debug('flow_controller_woke_with_credit', {
+                flow_id: flowId,
+                balance_after_wake: this.credits.get(flowId),
+            });
         }
         const current = this.credits.get(flowId);
         this.credits.set(flowId, current - 1);
+        logger.debug('flow_controller_credit_consumed', {
+            flow_id: flowId,
+            prev_balance: current,
+            remaining_balance: current - 1,
+        });
     }
     /**
      * Consume *credits* immediately (non-blocking).
@@ -186,6 +213,12 @@ class FlowController {
         const current = this.credits.get(flowId);
         const remaining = Math.max(current - credits, 0);
         this.credits.set(flowId, remaining);
+        logger.debug('flow_controller_consume', {
+            flow_id: flowId,
+            requested: credits,
+            prev_balance: current,
+            remaining_balance: remaining,
+        });
         return remaining;
     }
     /**
@@ -206,6 +239,10 @@ class FlowController {
         this.windowIds.delete(flowId);
         this.credits.set(flowId, this.initialWindow);
         this.wakeWaiters(flowId);
+        logger.debug('flow_controller_flow_reset', {
+            flow_id: flowId,
+            reset_balance: this.initialWindow,
+        });
     }
     /**
      * Return `[windowId, flags]` for the next outbound envelope.

package/dist/cjs/naylence/fame/connector/base-async-connector.js

@@ -261,10 +261,12 @@ class BaseAsyncConnector extends task_spawner_js_1.TaskSpawner {
             throw new errors_js_1.FameTransportClose('Connection closed', 1006);
         }
         // Apply flow control if enabled and not a credit update
-        if (this._fcEnabled &&
-            !(envelope.frame &&
-                'flow_id' in envelope.frame &&
-                'credits' in envelope.frame)) {
+        const isCreditUpdateFrame = Boolean(envelope.frame &&
+            (envelope.frame.type === 'CreditUpdate' ||
+                envelope.frame.type === 'credit_update' ||
+                ('flowId' in envelope.frame && 'credits' in envelope.frame) ||
+                ('flow_id' in envelope.frame && 'credits' in envelope.frame)));
+        if (this._fcEnabled && !isCreditUpdateFrame) {
             const flowId = envelope.flowId || this._connectorFlowId;
             envelope.flowId = flowId;
             const t0 = this._metrics ? performance.now() : 0;

package/dist/cjs/naylence/fame/connector/broadcast-channel-connector.browser.js

@@ -69,6 +69,7 @@ class BroadcastChannelConnector extends base_async_connector_js_1.BaseAsyncConne
             ? Math.floor(config.inboxCapacity)
             : DEFAULT_INBOX_CAPACITY;
         this.inbox = new bounded_async_queue_js_1.BoundedAsyncQueue(preferredCapacity);
+        this.inboxCapacity = preferredCapacity;
         this.connectorId = BroadcastChannelConnector.generateConnectorId();
         this.channel = new BroadcastChannel(this.channelName);
         logger.debug('broadcast_channel_connector_created', {
@@ -128,15 +129,27 @@ class BroadcastChannelConnector extends base_async_connector_js_1.BaseAsyncConne
                 if (typeof this.inbox.tryEnqueue === 'function') {
                     const accepted = this.inbox.tryEnqueue(payload);
                     if (accepted) {
+                        this.logInboxSnapshot('broadcast_channel_inbox_enqueued', {
+                            source: 'listener',
+                            enqueue_strategy: 'try',
+                            payload_length: payload.byteLength,
+                        });
                         return;
                     }
                 }
                 this.inbox.enqueue(payload);
+                this.logInboxSnapshot('broadcast_channel_inbox_enqueued', {
+                    source: 'listener',
+                    enqueue_strategy: 'enqueue',
+                    payload_length: payload.byteLength,
+                });
             }
             catch (error) {
                 if (error instanceof bounded_async_queue_js_1.QueueFullError) {
                     logger.warning('broadcast_channel_receive_queue_full', {
                         channel: this.channelName,
+                        inbox_capacity: this.inboxCapacity,
+                        inbox_remaining_capacity: this.inbox.remainingCapacity,
                     });
                 }
                 else {
@@ -147,8 +160,10 @@ class BroadcastChannelConnector extends base_async_connector_js_1.BaseAsyncConne
                 }
             }
         };
-        this.channel.addEventListener('message', this.onMsg);
-        this.listenerRegistered = true;
+        if (!config.passive) {
+            this.channel.addEventListener('message', this.onMsg);
+            this.listenerRegistered = true;
+        }
         // Setup visibility change monitoring
         this.visibilityChangeHandler = () => {
             const isHidden = document.hidden;
@@ -220,15 +235,25 @@ class BroadcastChannelConnector extends base_async_connector_js_1.BaseAsyncConne
             if (typeof this.inbox.tryEnqueue === 'function') {
                 const accepted = this.inbox.tryEnqueue(item);
                 if (accepted) {
+                    this.logInboxSnapshot('broadcast_channel_push_enqueued', {
+                        enqueue_strategy: 'try',
+                        item_type: this._describeInboxItem(item),
+                    });
                     return;
                 }
             }
             this.inbox.enqueue(item);
+            this.logInboxSnapshot('broadcast_channel_push_enqueued', {
+                enqueue_strategy: 'enqueue',
+                item_type: this._describeInboxItem(item),
+            });
         }
         catch (error) {
             if (error instanceof bounded_async_queue_js_1.QueueFullError) {
                 logger.warning('broadcast_channel_push_queue_full', {
                     channel: this.channelName,
+                    inbox_capacity: this.inboxCapacity,
+                    inbox_remaining_capacity: this.inbox.remainingCapacity,
                 });
                 throw error;
             }
@@ -251,7 +276,11 @@ class BroadcastChannelConnector extends base_async_connector_js_1.BaseAsyncConne
         });
     }
     async _transportReceive() {
-        return await this.inbox.dequeue();
+        const item = await this.inbox.dequeue();
+        this.logInboxSnapshot('broadcast_channel_inbox_dequeued', {
+            item_type: this._describeInboxItem(item),
+        });
+        return item;
     }
     async _transportClose(code, reason) {
         logger.debug('broadcast_channel_transport_closing', {
@@ -305,6 +334,28 @@ class BroadcastChannelConnector extends base_async_connector_js_1.BaseAsyncConne
         }
         return rawOrEnvelope;
     }
+    _describeInboxItem(item) {
+        if (item instanceof Uint8Array) {
+            return 'bytes';
+        }
+        if (item.envelope) {
+            return 'channel_message';
+        }
+        if (item.frame) {
+            return 'envelope';
+        }
+        return 'unknown';
+    }
+    logInboxSnapshot(event, extra = {}) {
+        logger.debug(event, {
+            channel: this.channelName,
+            connector_id: this.connectorId,
+            connector_state: this.state,
+            inbox_capacity: this.inboxCapacity,
+            inbox_remaining_capacity: this.inbox.remainingCapacity,
+            ...extra,
+        });
+    }
     _shouldSkipDuplicateAck(senderId, payload) {
         const dedupKey = this._extractAckDedupKey(payload);
         if (!dedupKey) {

package/dist/cjs/naylence/fame/connector/broadcast-channel-listener.js

@@ -342,6 +342,7 @@ class BroadcastChannelListener extends transport_listener_js_1.TransportListener
                         type: broadcast_channel_connector_js_1.BROADCAST_CHANNEL_CONNECTOR_TYPE,
                         channelName: this._channelName,
                         inboxCapacity: this._inboxCapacity,
+                        passive: true,
                     };
         }
         try {
@@ -402,6 +403,7 @@ class BroadcastChannelListener extends transport_listener_js_1.TransportListener
             type: broadcast_channel_connector_js_1.BROADCAST_CHANNEL_CONNECTOR_TYPE,
             channelName: this._channelName,
             inboxCapacity: this._inboxCapacity,
+            passive: true,
         };
         const channelCandidate = candidate.channelName ?? candidate['channel_name'];
         if (typeof channelCandidate === 'string' && channelCandidate.trim().length > 0) {

package/dist/cjs/version.js

@@ -1,10 +1,10 @@
 "use strict";
 // This file is auto-generated during build - do not edit manually
-// Generated from package.json version: 0.3.5-test.954
+// Generated from package.json version: 0.3.5-test.956
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 /**
  * The package version, injected at build time.
  * @internal
  */
-exports.VERSION = '0.3.5-test.954';
+exports.VERSION = '0.3.5-test.956';

package/dist/esm/naylence/fame/channel/flow-controller.js

@@ -22,6 +22,8 @@
  * flow at any time.
  */
 import { FlowFlags } from '@naylence/core';
+import { getLogger } from '../util/logging.js';
+const logger = getLogger('naylence.fame.flow.flow_controller');
 /**
  * Simple condition variable implementation for TypeScript/Node.js
  * Similar to Python's asyncio.Condition
@@ -147,8 +149,17 @@ export class FlowController {
         // clamp into [0, initialWindow]
         const newBalance = Math.max(0, Math.min(this.initialWindow, prev + delta));
         this.credits.set(flowId, newBalance);
+        const crossedZero = prev <= 0 && newBalance > 0;
+        logger.debug('flow_controller_add_credits', {
+            flow_id: flowId,
+            delta,
+            prev_balance: prev,
+            new_balance: newBalance,
+            initial_window: this.initialWindow,
+            crossed_zero: crossedZero,
+        });
         // wake waiters only if we crossed the zero boundary
-        if (prev <= 0 && newBalance > 0) {
+        if (crossedZero) {
             this.wakeWaiters(flowId);
         }
         return newBalance;
@@ -159,11 +170,27 @@ export class FlowController {
     async acquire(flowId) {
         this.ensureFlow(flowId);
         const condition = this.conditions.get(flowId);
+        logger.debug('flow_controller_acquire_attempt', {
+            flow_id: flowId,
+            current_balance: this.credits.get(flowId),
+        });
         while (this.credits.get(flowId) <= 0) {
+            logger.debug('flow_controller_waiting_for_credit', {
+                flow_id: flowId,
+            });
             await condition.wait();
+            logger.debug('flow_controller_woke_with_credit', {
+                flow_id: flowId,
+                balance_after_wake: this.credits.get(flowId),
+            });
         }
         const current = this.credits.get(flowId);
         this.credits.set(flowId, current - 1);
+        logger.debug('flow_controller_credit_consumed', {
+            flow_id: flowId,
+            prev_balance: current,
+            remaining_balance: current - 1,
+        });
     }
     /**
      * Consume *credits* immediately (non-blocking).
@@ -183,6 +210,12 @@ export class FlowController {
         const current = this.credits.get(flowId);
         const remaining = Math.max(current - credits, 0);
         this.credits.set(flowId, remaining);
+        logger.debug('flow_controller_consume', {
+            flow_id: flowId,
+            requested: credits,
+            prev_balance: current,
+            remaining_balance: remaining,
+        });
         return remaining;
     }
     /**
@@ -203,6 +236,10 @@ export class FlowController {
         this.windowIds.delete(flowId);
         this.credits.set(flowId, this.initialWindow);
         this.wakeWaiters(flowId);
+        logger.debug('flow_controller_flow_reset', {
+            flow_id: flowId,
+            reset_balance: this.initialWindow,
+        });
     }
     /**
      * Return `[windowId, flags]` for the next outbound envelope.