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

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

@@ -257,10 +257,12 @@ export 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;

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

@@ -66,6 +66,7 @@ export class BroadcastChannelConnector extends BaseAsyncConnector {
             ? Math.floor(config.inboxCapacity)
             : DEFAULT_INBOX_CAPACITY;
         this.inbox = new BoundedAsyncQueue(preferredCapacity);
+        this.inboxCapacity = preferredCapacity;
         this.connectorId = BroadcastChannelConnector.generateConnectorId();
         this.channel = new BroadcastChannel(this.channelName);
         logger.debug('broadcast_channel_connector_created', {
@@ -125,15 +126,27 @@ export class BroadcastChannelConnector extends BaseAsyncConnector {
                 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 {
@@ -144,8 +157,10 @@ export class BroadcastChannelConnector extends BaseAsyncConnector {
                 }
             }
         };
-        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;
@@ -217,15 +232,25 @@ export class BroadcastChannelConnector extends BaseAsyncConnector {
             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;
             }
@@ -248,7 +273,11 @@ export class BroadcastChannelConnector extends BaseAsyncConnector {
         });
     }
     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', {
@@ -302,6 +331,28 @@ export class BroadcastChannelConnector extends BaseAsyncConnector {
         }
         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/esm/naylence/fame/connector/broadcast-channel-listener.js

@@ -338,6 +338,7 @@ export class BroadcastChannelListener extends TransportListener {
                         type: BROADCAST_CHANNEL_CONNECTOR_TYPE,
                         channelName: this._channelName,
                         inboxCapacity: this._inboxCapacity,
+                        passive: true,
                     };
         }
         try {
@@ -398,6 +399,7 @@ export 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/esm/version.js

@@ -1,7 +1,7 @@
 // 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
  */
-export const VERSION = '0.3.5-test.954';
+export const VERSION = '0.3.5-test.956';

package/dist/node/index.cjs

@@ -14,12 +14,12 @@ var fastify = require('fastify');
 var websocketPlugin = require('@fastify/websocket');
 
 // 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.
@@ -837,7 +837,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)) {
@@ -998,7 +998,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,
         });
@@ -1015,7 +1015,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,
@@ -1069,7 +1069,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',
             });
@@ -1077,7 +1077,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,
             });
@@ -1089,7 +1089,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',
             });
@@ -1099,7 +1099,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',
             });
@@ -1112,14 +1112,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,
@@ -1138,11 +1138,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,
@@ -1157,7 +1157,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
@@ -1167,7 +1167,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,
                             });
@@ -1178,7 +1178,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),
                             });
@@ -2271,6 +2271,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
@@ -2396,8 +2397,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;
@@ -2408,11 +2418,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).
@@ -2432,6 +2458,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;
     }
     /**
@@ -2452,6 +2484,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.
@@ -9299,10 +9335,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;
@@ -9797,6 +9835,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', {
@@ -9856,15 +9895,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 {
@@ -9875,8 +9926,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;
@@ -9948,15 +10001,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;
             }
@@ -9979,7 +10042,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', {
@@ -10033,6 +10100,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) {
@@ -36171,6 +36260,7 @@ class BroadcastChannelListener extends TransportListener {
                         type: BROADCAST_CHANNEL_CONNECTOR_TYPE,
                         channelName: this._channelName,
                         inboxCapacity: this._inboxCapacity,
+                        passive: true,
                     };
         }
         try {
@@ -36231,6 +36321,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) {