@winkjs/composer 0.5.1 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@winkjs/composer",
-    "version": "0.5.1",
+    "version": "0.6.0",
     "description": "Composable Streaming Intelligence — turn streaming data into actionable insights, from edge to cloud",
     "keywords": [
         "streaming",
@@ -27,7 +27,7 @@
     },
     "scripts": {
         "pretest": "npm run lint",
-        "test": "mocha --recursive \"src/**/*.specs.js\" --ignore \"src/**/slow-*.specs.js\"",
+        "test": "c8 --reporter=text-summary --check-coverage --statements 100 --branches 100 --functions 100 --lines 100 mocha --recursive \"src/**/*.specs.js\" --ignore \"src/**/slow-*.specs.js\"",
         "test:hardening": "node --expose-gc node_modules/mocha/bin/mocha.js --recursive \"src/**/slow-*.specs.js\" --timeout 300000 --exit",
         "test:coverage": "c8 --reporter=html mocha --recursive \"src/**/*.specs.js\" --ignore \"src/**/slow-*.specs.js\"",
         "lint": "eslint \"src/**/*.js\""

package/src/core/batch/aoo-encoder.js

@@ -43,13 +43,13 @@
 export const createAooEncoder = function ( { maxRows, fieldOrder, codec } ) {
     // Input validation - fail fast on misconfiguration
     if ( !Array.isArray( fieldOrder ) || fieldOrder.length === 0 ) {
-        throw new Error( 'fieldOrder must be non-empty array of field names' );
+        throw new Error( 'winkComposer/batch: fieldOrder must be non-empty array of field names' );
     }
     if ( !maxRows || maxRows <= 0 ) {
-        throw new Error( 'maxRows must be positive integer' );
+        throw new Error( 'winkComposer/batch: maxRows must be positive integer' );
     }
     if ( !codec || typeof codec.pack !== 'function' ) {
-        throw new Error( 'codec must have pack() method');
+        throw new Error( 'winkComposer/batch: codec must have pack() method' );
     }
 
     // Pre-allocate row objects with stable shape.
@@ -98,7 +98,7 @@ export const createAooEncoder = function ( { maxRows, fieldOrder, codec } ) {
     const encode = function ( producerId, seq, srcRows, count ) {
         // Validate count doesn't exceed pre-allocated capacity
         if ( count > maxRows ) {
-            throw new Error( `Cannot encode ${count} rows, max capacity is ${maxRows}` );
+            throw new Error( `winkComposer/batch: Cannot encode ${count} rows, max capacity is ${maxRows}` );
         }
 
         // Copy source data into pre-allocated row objects

package/src/core/batch/sliding-window.js

@@ -7,10 +7,10 @@
 export const createWindow = function ( capacity, fieldOrder ) {
     // Input validation
     if ( !capacity || capacity <= 0 ) {
-        throw new Error( 'capacity must be positive integer' );
+        throw new Error( 'winkComposer/batch: capacity must be positive integer' );
     }
     if ( !Array.isArray( fieldOrder ) || fieldOrder.length === 0 ) {
-        throw new Error( 'fieldOrder must be non-empty array' );
+        throw new Error( 'winkComposer/batch: fieldOrder must be non-empty array' );
     }
 
     // Pre-allocate all row objects with stable shape

package/src/core/codec/index.js

@@ -1,11 +1,11 @@
 // src/core/codec/index.js
 
 /**
- * @fileoverview Universal codec for WinkComposer and Dashboard
+ * @fileoverview Universal codec for winkComposer and Dashboard
  *
  * Provides efficient message serialization for MQTT transport with support
  * for both MessagePack (binary, efficient) and JSON (text, debuggable).
- * Works identically in Node.js (WinkComposer) and browsers (Dashboard).
+ * Works identically in Node.js (winkComposer) and browsers (Dashboard).
  *
  * Design principles:
  * - Zero dependencies on Node.js-specific APIs
@@ -53,7 +53,7 @@ const toUint8 = function ( bytes ) {
         return new Uint8Array( bytes.buffer, bytes.byteOffset, bytes.byteLength );
     }
 
-    throw new TypeError( 'Expected BufferSource' );
+    throw new TypeError( 'winkComposer/codec: Expected BufferSource' );
 };
 
 /**
@@ -126,7 +126,7 @@ export const createCodec = function ( format = 'msgpack' ) {
         } );
     }
 
-    throw new TypeError( `Unknown format: ${format}` );
+    throw new TypeError( `winkComposer/codec: Unknown format: ${format}` );
 };
 
 // Pre-created codecs for convenience

package/src/core/emitter-manager/mqtt/emitter.js

@@ -107,6 +107,11 @@
  *   so a disconnected shutdown with pending messages is a real loss and
  *   is reported as one (this differs from the wal-backed design, which
  *   held them for the next session).
+ * - `CALLBACK_FAILED`  — a user callback (`onDeliveryFailure`,
+ *   `onCritical`, `onBackpressure`) itself threw or rejected. The
+ *   shared callback guard contains the fault (ADR-018): the emitter
+ *   keeps publishing and each fault becomes one classified console
+ *   line. Fix the callback; the line names it and carries the detail.
  *
  * @module mqtt-emitter
  */
@@ -123,6 +128,8 @@ import {
     DEFAULT_MAX_QUEUE_SIZE,
     MQTT_INFLIGHT_ID_LIMIT
 } from './constants.js';
+import { wrapCallback } from '../../utils/callback-guard/index.js';
+import { logger } from '../../logger/index.js';
 
 /**
  * Pre-flight reject threshold on store pressure.
@@ -185,7 +192,7 @@ const ERR_SHUTTING_DOWN = {
  * @returns {TypeError}
  */
 const invalidConfig = function ( message ) {
-    const err = new TypeError( message );
+    const err = new TypeError( 'winkComposer/mqttEmitter: ' + message );
     err.code = 'INVALID_CONFIG';
     return err;
 };
@@ -306,6 +313,29 @@ export const createEmitter = function ( config ) {
     assertOptionalCallback( config.onCritical, 'onCritical' );
     assertOptionalCallback( config.onBackpressure, 'onBackpressure' );
 
+    // The three notification callbacks are armed by the shared
+    // callback guard. They were validated raw above and are wrapped
+    // once here. The wrap matters because all three run inside
+    // mqtt.js's publish ack chain, where a user throw would land in
+    // the client library (ADR-018). Each wrap is null when the
+    // callback is absent, so every no-handler path below keeps its
+    // exact meaning. That includes the deliberate unhandled-rejection
+    // escape hatch for an unhandled delivery failure.
+    const reportCallbackFault = function ( severity, name, detail ) {
+        logger.error(
+            `winkComposer/mqttEmitter: user callback ${name} failed [CALLBACK_FAILED]: ${detail}`
+        );
+    };
+    const onDeliveryFailure = wrapCallback( config.onDeliveryFailure, {
+        name: 'onDeliveryFailure', severity: 'red', report: reportCallbackFault
+    } );
+    const onCritical = wrapCallback( config.onCritical, {
+        name: 'onCritical', severity: 'red', report: reportCallbackFault
+    } );
+    const onBackpressure = wrapCallback( config.onBackpressure, {
+        name: 'onBackpressure', severity: 'yellow', report: reportCallbackFault
+    } );
+
     // First-connack grace: explicit config → MQTT_CONNECT_GRACE_MS env
     // fallback → 500 ms default (ADR-018 precedence; the fallback lives
     // here in the factory body, never as a schema sigil). `??` keeps an
@@ -349,8 +379,8 @@ export const createEmitter = function ( config ) {
     // (same clamp the LevelDB store applied, kept with the same warning).
     const requestedQueueSize = config.maxQueueSize || DEFAULT_MAX_QUEUE_SIZE;
     if ( requestedQueueSize > MQTT_INFLIGHT_ID_LIMIT ) {
-        console.warn(
-            `WinkComposer/mqtt-emitter: maxQueueSize ${requestedQueueSize} exceeds the MQTT ` +
+        logger.warn(
+            `winkComposer/mqttEmitter: maxQueueSize ${requestedQueueSize} exceeds the MQTT ` +
             `packet-id ceiling — clamped to ${MQTT_INFLIGHT_ID_LIMIT}`
         );
     }
@@ -413,12 +443,12 @@ export const createEmitter = function ( config ) {
     const checkBackpressure = function () {
         const pressure = getPressure();
 
-        if ( ( pressure > QUEUE_CRITICAL_THRESHOLD ) && config.onCritical ) {
-            config.onCritical( 'QUEUE_CRITICAL', pressure );
+        if ( ( pressure > QUEUE_CRITICAL_THRESHOLD ) && onCritical ) {
+            onCritical( 'QUEUE_CRITICAL', pressure );
         }
 
-        if ( config.onBackpressure ) {
-            config.onBackpressure( pressure );
+        if ( onBackpressure ) {
+            onBackpressure( pressure );
         }
     };
 
@@ -522,12 +552,12 @@ export const createEmitter = function ( config ) {
                     if ( err ) {
                         state.stats.publishErrors += 1;
                         const deliveryErr = new Error(
-                            `MQTT publish failed (topic=${topic}): ${err.message || err.code || 'unknown'}`
+                            `winkComposer/mqttEmitter: publish failed (topic=${topic}): ${err.message || err.code || 'unknown'}`
                         );
                         deliveryErr.code = 'DELIVERY_FAILED';
                         deliveryErr.cause = err;
-                        if ( config.onDeliveryFailure ) {
-                            config.onDeliveryFailure( deliveryErr, { topic } );
+                        if ( onDeliveryFailure ) {
+                            onDeliveryFailure( deliveryErr, { topic } );
                         } else {
                             // No handler — surface as unhandledRejection so the
                             // process logs loudly and (Node 15+) exits. Mirrors
@@ -652,7 +682,7 @@ export const createEmitter = function ( config ) {
         // an incomplete drain must not read as a clean one (ADR-018).
         if ( undeliveredCount > 0 ) {
             const err = new Error(
-                `WinkComposer/mqtt-emitter: shutdown closed with ${undeliveredCount} message(s) unacknowledged`
+                `winkComposer/mqttEmitter: shutdown closed with ${undeliveredCount} message(s) unacknowledged`
             );
             err.code = 'SHUTDOWN_TIMEOUT';
             err.dropped = { count: undeliveredCount };
@@ -698,21 +728,21 @@ export const createEmitter = function ( config ) {
         }
         state.hasConnectedOnce = true;
         if ( config.debug ) {
-            console.log( `Connected to ${redactedBrokerUrl}` );
+            logger.info( `winkComposer/mqttEmitter: Connected to ${redactedBrokerUrl}` );
         }
     } );
 
     client.on( 'offline', () => {
         state.connected = false;
         if ( config.debug ) {
-            console.log( `Offline - ${state.unacked} messages in flight` );
+            logger.info( `winkComposer/mqttEmitter: Offline - ${state.unacked} messages in flight` );
         }
     } );
 
     client.on( 'error', ( err ) => {
         state.stats.errors += 1;
         if ( config.debug ) {
-            console.error( `MQTT error: ${err.message}` );
+            logger.error( `winkComposer/mqttEmitter: client error: ${err.message}` );
         }
     } );
 

package/src/core/emitter-manager/terminal/assert-columns.js

@@ -84,7 +84,7 @@ const assertColumnFacts = function ( columns ) {
                 !Number.isFinite( colSpec.resolution ) ||
                 colSpec.resolution <= 0 ) {
                 const err = new Error(
-                    `WinkComposer/terminal: column '${colName}' has type 'float64' ` +
+                    `winkComposer/terminal: column '${colName}' has type 'float64' ` +
                     `but resolution is '${colSpec.resolution}'; ` +
                     'expected positive finite number (or omit the field to use the global precision)'
                 );

package/src/core/emitter-manager/terminal/index.js

@@ -281,15 +281,15 @@ export const createEmitter = function ( config = {} ) {
             const ts = new Date().toLocaleTimeString();
             const header = `${linePrefix}── ${ts} ── ${topic} ──`;
 
-            console.log( header );
+            console.log( header ); // eslint-disable-line no-console -- product output, not diagnostics
 
             if ( verbose ) {
-                console.log( formatVerbose( msg, formatValue ) );
+                console.log( formatVerbose( msg, formatValue ) ); // eslint-disable-line no-console -- product output, not diagnostics
             } else {
-                console.log( formatCompact( msg, formatValue ) );
+                console.log( formatCompact( msg, formatValue ) ); // eslint-disable-line no-console -- product output, not diagnostics
             }
 
-            console.log();  // Blank line for readability
+            console.log();  // eslint-disable-line no-console -- product output: blank line for readability
 
             return RESULT_OK;
         },

package/src/core/env-vars.js

@@ -16,14 +16,36 @@ import os from 'os';
 // to nothing intended.
 const rawYieldMs = ( process.env.YIELD_TIME_THRESHOLD_MS ?? '500' ).trim();
 
+// The log-level default depends on NODE_ENV, and the ENV_VARS object
+// literal cannot read its own nodeEnv entry while it is being built.
+// So NODE_ENV is resolved once here and used in both places (the same
+// hoisting precedent as rawYieldMs above). Production defaults to
+// 'info' so an edge box does not fill its journal with debug lines;
+// everything else defaults to 'debug' for development visibility.
+// ADR-028 records the logger architecture.
+const rawNodeEnv = ( process.env.NODE_ENV ?? 'development' ).trim();
+
 const ENV_VARS = {
     // Core Configuration
     edgeDeviceId: ( process.env.EDGE_DEVICE_ID ?? os.hostname() ).trim(),
-    nodeEnv: ( process.env.NODE_ENV ?? 'development' ).trim(),
+    nodeEnv: rawNodeEnv,
+
+    // Logging (ADR-028). 'logger' picks the transport the facade
+    // writes through; 'logLevel' picks the lowest level that prints.
+    logger: ( process.env.COMPOSER_LOGGER ?? 'console' ).trim(),
+    logLevel: ( process.env.COMPOSER_LOG_LEVEL ?? ( ( rawNodeEnv === 'production' ) ? 'info' : 'debug' ) ).trim(),
 
     // Partition Management (see ADR-016)
     maxPartitionsAllowed: parseInt( process.env.COMPOSER_MAX_PARTITIONS_ALLOWED ?? '10000', 10 ),
 
+    // Fault containment (ADR-018 — the flow runtime owns per-message
+    // dispatch failure). This many CONSECUTIVE message failures stop
+    // the flow in the terminal 'errored' phase; one success resets
+    // the count. The same value caps a partition's consecutive
+    // creation failures before it is quarantined. A run of failures
+    // means something systemic; one bad message costs only itself.
+    messageFailureThreshold: parseInt( process.env.COMPOSER_MESSAGE_FAILURE_THRESHOLD ?? '5', 10 ),
+
     // STORAGE_DIR retired 2026-07-09 — the emitter's LevelDB store
     // (removed by ADR-021) was the only thing that ever wrote there.
     // A future WAL adapter defines its own disk-path configuration.
@@ -109,6 +131,22 @@ const validators = {
         return null;
     },
 
+    logger: function ( value ) {
+        const validTransports = [ 'console', 'json', 'silent' ];
+        if ( !validTransports.includes( value ) ) {
+            return `Must be one of ${validTransports.join( ', ' )}, got: "${value}"`;
+        }
+        return null;
+    },
+
+    logLevel: function ( value ) {
+        const validLevels = [ 'debug', 'info', 'warn', 'error' ];
+        if ( !validLevels.includes( value ) ) {
+            return `Must be one of ${validLevels.join( ', ' )}, got: "${value}"`;
+        }
+        return null;
+    },
+
     mqttMsgExpiry: function ( value, originalEnv ) {
         if ( isNaN( value ) || value <= 0 ) {
             return `Must be positive integer, got: "${originalEnv}"`;
@@ -185,7 +223,10 @@ const validators = {
 const validationConfig = [
     { field: 'edgeDeviceId', validator: validators.edgeDeviceId },
     { field: 'nodeEnv', validator: validators.nodeEnv },
+    { field: 'logger', validator: validators.logger, label: 'COMPOSER_LOGGER' },
+    { field: 'logLevel', validator: validators.logLevel, label: 'COMPOSER_LOG_LEVEL' },
     { field: 'maxPartitionsAllowed', validator: validators.positiveInt, originalEnv: 'COMPOSER_MAX_PARTITIONS_ALLOWED' },
+    { field: 'messageFailureThreshold', validator: validators.positiveInt, originalEnv: 'COMPOSER_MESSAGE_FAILURE_THRESHOLD' },
     { field: 'yieldTimeThresholdMs', validator: validators.nonNegativeNumberOrInfinity, originalEnv: 'YIELD_TIME_THRESHOLD_MS' },
     { field: 'mqttBrokerUrl', validator: validators.mqttUrl, label: 'MQTT_BROKER_URL' },
     { field: 'mqttMsgExpiry', validator: validators.mqttMsgExpiry, originalEnv: 'MQTT_MSG_EXPIRY' },
@@ -233,8 +274,8 @@ const validate = function () {
 
     // Fail fast with clear error message
     if ( errors.length > 0 ) {
-        console.error( 'composer: Environment variable validation failed:' );
-        errors.forEach( ( err ) => console.error( `   - ${err}` ) );
+        console.error( 'winkComposer/envVars: Environment variable validation failed:' ); // eslint-disable-line no-console -- bootstrap failure runs before any logger can exist
+        errors.forEach( ( err ) => console.error( `   - ${err}` ) ); // eslint-disable-line no-console -- bootstrap failure runs before any logger can exist
         process.exit( 1 ); // eslint-disable-line no-process-exit
     }
 }; // validate()

package/src/core/logger/index.js

@@ -0,0 +1,174 @@
+// core/logger/index.js
+
+/**
+ * @fileoverview The framework's logging facade. Every production
+ * log line goes through one small object with four methods: debug,
+ * info, warn, and error. Each method takes a message string and an
+ * optional flat fields object. The transport behind the facade —
+ * where a record actually goes — is picked once at startup from
+ * COMPOSER_LOGGER, and the lowest level that prints is picked from
+ * COMPOSER_LOG_LEVEL. ADR-028 records the design.
+ *
+ * Three guarantees shape the code:
+ *
+ * - **Zero cost when suppressed.** Levels below the threshold are
+ *   resolved at build time: every suppressed method IS one shared
+ *   empty function. No comparison, no allocation, no argument
+ *   inspection happens on a suppressed call. JavaScript still
+ *   evaluates the arguments themselves, so a hot-path call site
+ *   guards a fields literal with the precomputed `debugOn` or
+ *   `infoOn` boolean instead of relying on the no-op.
+ * - **A log call never throws.** Logging exists to report faults,
+ *   so it must not create them. A broken transport, a bad level
+ *   name, or unserializable fields each degrade to a working
+ *   console line. The last-resort line interpolates nothing.
+ * - **Stream identity.** The console transport mirrors each level
+ *   to the same console method a raw call would have used, and the
+ *   json transport keeps the same stderr/stdout split. A line
+ *   never moves between streams because the facade arrived.
+ *
+ * There is deliberately no file transport: journald, kubelet, and
+ * logrotate own files in every deployment shape (ADR-028 records
+ * the rejection and the escape hatches).
+ */
+
+import { ENV_VARS } from '../env-vars.js';
+
+// Level order: a method emits when its rank is at or above the
+// configured threshold. Internal constant keys — a plain literal.
+const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
+
+// Which console method carries each level. error and warn go to
+// stderr, info and debug to stdout — the same split raw calls had.
+const CONSOLE_METHODS = { debug: 'log', info: 'log', warn: 'warn', error: 'error' };
+
+// The one shared no-op every suppressed method resolves to.
+const NO_OP = function () { /* the shared suppressed-level sink */ };
+
+/**
+ * Stringify a fields object without ever throwing. Circular or
+ * otherwise unserializable fields become a quoted placeholder, so
+ * the surrounding line stays valid.
+ *
+ * @param {*} value - The fields value to render.
+ * @returns {string} JSON text, or the placeholder literal.
+ */
+const safeStringify = function ( value ) {
+    try {
+        return JSON.stringify( value );
+    } catch {
+        return '"[unserializable fields]"';
+    }
+}; // safeStringify()
+
+const consoleTransport = {
+    emit: function ( level, msg, fields ) {
+        const line = ( fields === undefined ) ? msg : ( msg + ' ' + safeStringify( fields ) );
+        console[ CONSOLE_METHODS[ level ] ]( line ); // eslint-disable-line no-console -- the console transport IS the console boundary
+    }
+};
+
+const jsonTransport = {
+    emit: function ( level, msg, fields ) {
+        let line;
+        try {
+            // JSON.stringify drops a fields key holding undefined,
+            // so the no-fields record needs no separate branch.
+            line = JSON.stringify( { level, msg, fields } );
+        } catch {
+            line = JSON.stringify( { level, msg, fields: '[unserializable fields]' } );
+        }
+        console[ CONSOLE_METHODS[ level ] ]( line ); // eslint-disable-line no-console -- the json transport IS the console boundary
+    }
+};
+
+const silentTransport = {
+    emit: NO_OP
+};
+
+// The env-selectable transports. The mqtt transport joins this map
+// when ADR-029 lands.
+const transports = {
+    console: consoleTransport,
+    json: jsonTransport,
+    silent: silentTransport
+};
+
+/**
+ * Create an in-memory transport for specs. Each instance records
+ * `{ level, msg, fields }` per emission and can be reset. Never
+ * selectable through COMPOSER_LOGGER.
+ *
+ * @returns {object} `{ emit, records, reset }`.
+ */
+const createMemoryTransport = function () {
+    const records = [];
+    return {
+        records,
+        reset: function () {
+            records.length = 0;
+        },
+        emit: function ( level, msg, fields ) {
+            records.push( { level, msg, fields } );
+        }
+    };
+}; // createMemoryTransport()
+
+/**
+ * Build a logger over a transport at a level. Methods are
+ * precompiled here: suppressed levels become the shared no-op, and
+ * active levels close over the transport. Invalid inputs fall back
+ * to a working console logger with one warning line — building a
+ * logger never throws, because logging must not crash its host.
+ *
+ * @param {object} transport - An object with `emit( level, msg, fields )`.
+ * @param {string} levelName - One of debug, info, warn, error.
+ * @returns {object} `{ debug, info, warn, error, debugOn, infoOn, level }`.
+ */
+const buildLogger = function ( transport, levelName ) {
+    let safeTransport = transport;
+    if ( !transport || typeof transport.emit !== 'function' ) {
+        console.warn( 'winkComposer/logger: transport has no emit function — falling back to console' ); // eslint-disable-line no-console -- init fallback runs before a working transport exists
+        safeTransport = consoleTransport;
+    }
+
+    let safeLevel = levelName;
+    if ( LEVELS[ safeLevel ] === undefined ) {
+        console.warn( 'winkComposer/logger: unknown log level — falling back to info' ); // eslint-disable-line no-console -- init fallback runs before a working transport exists
+        safeLevel = 'info';
+    }
+
+    const threshold = LEVELS[ safeLevel ];
+
+    const makeMethod = function ( name ) {
+        if ( LEVELS[ name ] < threshold ) {
+            return NO_OP;
+        }
+        return function ( msg, fields ) {
+            try {
+                safeTransport.emit( name, msg, fields );
+            } catch {
+                // Last resort, interpolation-free: a broken
+                // transport must not crash the host process.
+                console.error( 'winkComposer/logger: transport emit failed — record dropped' ); // eslint-disable-line no-console -- last resort when the transport itself threw
+            }
+        };
+    };
+
+    return {
+        debug: makeMethod( 'debug' ),
+        info: makeMethod( 'info' ),
+        warn: makeMethod( 'warn' ),
+        error: makeMethod( 'error' ),
+        debugOn: ( threshold <= LEVELS.debug ),
+        infoOn: ( threshold <= LEVELS.info ),
+        level: safeLevel
+    };
+}; // buildLogger()
+
+// The default instance every production module imports. ENV_VARS
+// validated both values at startup, so the fallbacks above are a
+// second line of defense, not the expected path.
+const logger = buildLogger( transports[ ENV_VARS.logger ], ENV_VARS.logLevel );
+
+export { logger, buildLogger, createMemoryTransport, transports };

package/src/core/mqtt-protocol.js

@@ -1,7 +1,7 @@
 // core/mqtt-protocol.js
 
 /**
- * @fileoverview Shared MQTT protocol invariants for WinkComposer.
+ * @fileoverview Shared MQTT protocol invariants for winkComposer.
  *
  * These are design decisions, NOT deployment-configurable values.
  * Both source and emitter depend on identical values for interoperability:
@@ -18,7 +18,7 @@
 // ============================================================================
 
 /**
- * MQTT v5 user property keys for WinkComposer metadata.
+ * MQTT v5 user property keys for winkComposer metadata.
  * Publisher (emitter) writes these; subscriber (source) reads them.
  *
  * @type {Object}

package/src/core/partition-manager/get-stats.js

@@ -0,0 +1,31 @@
+// core/partition-manager/get-stats.js
+
+/**
+ * @fileoverview Read-only statistics snapshot for the partition
+ * manager. Lets an operator count dropped messages and partitions
+ * instead of scraping log lines (logger-facade epic, Story 6). The
+ * counter itself is initialized in init.js and maintained at the
+ * drop site in update.js; this file only reads.
+ */
+
+/**
+ * Build a snapshot of the partition manager's counters. Cold path:
+ * allocates one small object per call and is never called per
+ * message.
+ *
+ * @param {Object} composerState - State object created by init().
+ * @returns {{droppedUnknownSpecialization: number,
+ *   totalPartitionsCreated: number, activePartitions: number}}
+ *   Messages dropped for an unknown specialization; partition
+ *   creations attempted, accepted or cap-rejected (ADR-016); and
+ *   partitions currently held.
+ */
+const getStats = function ( composerState ) {
+    return {
+        droppedUnknownSpecialization: composerState.droppedUnknownSpecialization,
+        totalPartitionsCreated: composerState.totalPartitionsCreated,
+        activePartitions: composerState.partitionSpecializations.size
+    };
+}; // getStats()
+
+export default getStats;

package/src/core/partition-manager/index.js

@@ -3,5 +3,6 @@ export { default as update } from './update.js';
 export { default as reset } from './reset.js';
 export { default as recompute } from './recompute.js';
 export { default as publishTo } from './publish-to.js';
+export { default as getStats } from './get-stats.js';
 // Re-export everything from introspection.js
 export * from './introspect.js';

package/src/core/partition-manager/init.js

@@ -18,6 +18,21 @@ const init = function ( flow ) {
     // rejection count. See ADR-016.
     composerState.totalPartitionsCreated = 0;
 
+    // Messages dropped because their specialization field named no
+    // known specialization (the update.js drop site). A lifetime
+    // counter, read through getStats() — operators count drops
+    // instead of scraping log lines.
+    composerState.droppedUnknownSpecialization = 0;
+
+    // Per-partition creation-failure ledgers (ADR-018 fault
+    // containment): keyed by each partition's specializedGraphs
+    // object, holding { failures, quarantined }. A WeakMap on object
+    // identity — specialization names are user-controlled strings, so
+    // no in-object key is collision-safe, and the ledger dies with its
+    // partition entry automatically. Entries allocate only when a
+    // creation fails; the healthy hot path never touches this.
+    composerState.creationFailures = new WeakMap();
+
     // Yield state (ADR-024): update() sets `yieldPending` when the time
     // threshold is crossed; the flow runtime clears it and takes the
     // event-loop breath after running the message's pipeline.