@winkjs/composer 0.5.1 → 0.7.0

package/src/core/env-vars.js

@@ -4,6 +4,8 @@
 
 import os from 'os';
 
+import { classifyAddress, localhostRefusalDetail } from './utils/address/index.js';
+
 // ============================================================================
 // ENVIRONMENT VARIABLE DEFINITIONS
 // ============================================================================
@@ -16,14 +18,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.
@@ -41,7 +65,7 @@ const ENV_VARS = {
     // `processMessage` (file replays, testHarness, the headless driver):
     // for them the yield tick is the only planned chance for sink flush
     // timers and socket I/O to run. 500 ms is half the tightest background
-    // timer it must not starve (QUESTDB_IDLE_FLUSH_CHECK_MS, 1000).
+    // timer it must not starve (QUESTDB_FLUSH_INTERVAL_MS, default 1000).
     // Per-flow override: `.yield( { threshold } )`. Infinity = never yield.
     yieldTimeThresholdMs: rawYieldMs === '' ? NaN : Number( rawYieldMs ),
 
@@ -67,12 +91,26 @@ const ENV_VARS = {
     mqttSourceDedupWindowMs: parseInt( process.env.MQTT_SOURCE_DEDUP_WINDOW_MS ?? '120000', 10 ),
     mqttSourceDedupMaxEntries: parseInt( process.env.MQTT_SOURCE_DEDUP_MAX_ENTRIES ?? '65536', 10 ),
 
-    // QuestDB Configuration
-    questdbIlpUrl: ( process.env.QUESTDB_ILP_URL ?? 'localhost:9000' ).trim(),
-    questdbPgUrl: ( process.env.QUESTDB_PG_URL ?? 'localhost:8812' ).trim(),
-    questdbFlushMode: ( process.env.QUESTDB_FLUSH_MODE ?? 'auto' ).trim(),
-    questdbIdleFlushAfterMs: parseInt( process.env.QUESTDB_IDLE_FLUSH_AFTER_MS ?? '5000', 10 ),
-    questdbIdleFlushCheckMs: parseInt( process.env.QUESTDB_IDLE_FLUSH_CHECK_MS ?? '1000', 10 ),
+    // QuestDB Configuration. The address defaults are loopback literals,
+    // never the name `localhost` (ADR-030). A name can resolve to two
+    // addresses, `::1` and `127.0.0.1`, and QuestDB may listen on only
+    // one; the run-5 soak lost its write path for four hours that way.
+    // The `hostPort` and `mqttUrl` validators below refuse `localhost`
+    // outright, so a deployment that sets it stops here, at import.
+    questdbIlpUrl: ( process.env.QUESTDB_ILP_URL ?? '127.0.0.1:9000' ).trim(),
+    questdbPgUrl: ( process.env.QUESTDB_PG_URL ?? '127.0.0.1:8812' ).trim(),
+    // The five legacy flush variables (deprecated, ADR-029; removed in
+    // 0.8.0). Each carries a value only when set, so the adapter's
+    // DEPRECATED_OPTION line names only what an operator actually set.
+    // QUESTDB_IDLE_FLUSH_CHECK_MS maps to QUESTDB_FLUSH_INTERVAL_MS and
+    // QUESTDB_AUTO_FLUSH_ROWS to QUESTDB_FLUSH_ROWS; the other three
+    // are accepted and ignored.
+    questdbFlushMode: process.env.QUESTDB_FLUSH_MODE ?
+        process.env.QUESTDB_FLUSH_MODE.trim() : undefined,
+    questdbIdleFlushAfterMs: process.env.QUESTDB_IDLE_FLUSH_AFTER_MS ?
+        parseInt( process.env.QUESTDB_IDLE_FLUSH_AFTER_MS, 10 ) : undefined,
+    questdbIdleFlushCheckMs: process.env.QUESTDB_IDLE_FLUSH_CHECK_MS ?
+        parseInt( process.env.QUESTDB_IDLE_FLUSH_CHECK_MS, 10 ) : undefined,
     // Optional QuestDB settings (undefined if not set)
     questdbAutoFlushRows: process.env.QUESTDB_AUTO_FLUSH_ROWS ?
         parseInt( process.env.QUESTDB_AUTO_FLUSH_ROWS, 10 ) : undefined,
@@ -83,6 +121,31 @@ const ENV_VARS = {
     questdbRetryTimeout: process.env.QUESTDB_RETRY_TIMEOUT ?
         parseInt( process.env.QUESTDB_RETRY_TIMEOUT, 10 ) : undefined,
 
+    // QuestDB flush settings owned by composer (ADR-029). Each carries a
+    // value only when the operator set one. The adapter's option
+    // resolver supplies the defaults and derives the ceiling and the
+    // deadline from the values that won, so a fixed default here would
+    // fight a threshold raised in the flow's config.
+    questdbFlushRows: process.env.QUESTDB_FLUSH_ROWS ?
+        parseInt( process.env.QUESTDB_FLUSH_ROWS, 10 ) : undefined,
+    questdbFlushIntervalMs: process.env.QUESTDB_FLUSH_INTERVAL_MS ?
+        parseInt( process.env.QUESTDB_FLUSH_INTERVAL_MS, 10 ) : undefined,
+    questdbBufferCeilingRows: process.env.QUESTDB_BUFFER_CEILING_ROWS ?
+        parseInt( process.env.QUESTDB_BUFFER_CEILING_ROWS, 10 ) : undefined,
+    questdbFlushDeadlineMs: process.env.QUESTDB_FLUSH_DEADLINE_MS ?
+        parseInt( process.env.QUESTDB_FLUSH_DEADLINE_MS, 10 ) : undefined,
+
+    // QuestDB transport settings (ADR-029). QUESTDB_STDLIB_HTTP takes
+    // the client's own words for `stdlib_http`, `on` or `off`. The
+    // adapter's option resolver maps them to a boolean and supplies the
+    // default, so each field here carries a value only when set.
+    questdbStdlibHttp: process.env.QUESTDB_STDLIB_HTTP ?
+        process.env.QUESTDB_STDLIB_HTTP.trim() : undefined,
+    questdbRequestTimeout: process.env.QUESTDB_REQUEST_TIMEOUT ?
+        parseInt( process.env.QUESTDB_REQUEST_TIMEOUT, 10 ) : undefined,
+    questdbInitBufSize: process.env.QUESTDB_INIT_BUF_SIZE ?
+        parseInt( process.env.QUESTDB_INIT_BUF_SIZE, 10 ) : undefined,
+
     // QuestDB Credentials
     questdbDatabase: ( process.env.QUESTDB_DATABASE ?? 'qdb' ).trim(),
     questdbUser: ( process.env.QUESTDB_USER ?? 'admin' ).trim(),
@@ -109,6 +172,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}"`;
@@ -123,17 +202,24 @@ const validators = {
         return null;
     },
 
+    // host:port, with the port required. Accepts a name, an IPv4
+    // literal, or a bracketed IPv6 literal (`[::1]:8812`). Refuses
+    // `localhost` in every spelling (ADR-030); the shared helper is the
+    // one check the adapter schema and factory layers use too.
     hostPort: function ( value ) {
         if ( !value ) return 'Cannot be empty';
-        // Match host:port pattern (host can be hostname or IP)
-        const hostPortRegex = /^[\w.\-]+:\d+$/;
-        if ( !hostPortRegex.test( value ) ) {
+        const address = classifyAddress( value, 'hostPort' );
+        if ( ( address.kind === 'unparsed' ) || ( address.port === undefined ) ) {
             return `Must be host:port format, got: "${value}"`;
         }
+        if ( address.kind === 'localhost' ) {
+            return localhostRefusalDetail( address );
+        }
         return null;
     },
 
     questdbFlushMode: function ( value ) {
+        if ( value === undefined ) return null;
         const validModes = [ 'auto', 'manual' ];
         if ( !validModes.includes( value ) ) {
             return `Must be one of ${validModes.join( ', ' )}, got: "${value}"`;
@@ -141,6 +227,15 @@ const validators = {
         return null;
     },
 
+    questdbStdlibHttp: function ( value ) {
+        if ( value === undefined ) return null;
+        const validWords = [ 'on', 'off' ];
+        if ( !validWords.includes( value ) ) {
+            return `Must be one of ${validWords.join( ', ' )}, got: "${value}"`;
+        }
+        return null;
+    },
+
     positiveIntOrUndefined: function ( value, originalEnv ) {
         if ( value === undefined ) return null;
         if ( isNaN( value ) || value <= 0 ) {
@@ -156,6 +251,14 @@ const validators = {
         return null;
     },
 
+    nonNegativeIntOrUndefined: function ( value, originalEnv ) {
+        if ( value === undefined ) return null;
+        if ( isNaN( value ) || value < 0 ) {
+            return `Must be non-negative integer, got: "${originalEnv}"`;
+        }
+        return null;
+    },
+
     nonNegativeNumberOrInfinity: function ( value, originalEnv ) {
         if ( isNaN( value ) || value < 0 ) {
             return `Must be a non-negative number or Infinity, got: "${originalEnv}"`;
@@ -170,11 +273,18 @@ const validators = {
         return null;
     },
 
+    // A broker URL. The scheme check comes first; then `localhost` is
+    // refused (ADR-030). A URL the parser cannot read is left to the
+    // MQTT library, which reports its own error.
     mqttUrl: function ( value ) {
         if ( !value ) return 'Cannot be empty';
         if ( !value.startsWith( 'mqtt://' ) && !value.startsWith( 'mqtts://' ) ) {
             return `Must start with 'mqtt://' or 'mqtts://', got: "${value}"`;
         }
+        const address = classifyAddress( value, 'url' );
+        if ( address.kind === 'localhost' ) {
+            return localhostRefusalDetail( address );
+        }
         return null;
     }
 };
@@ -185,7 +295,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' },
@@ -201,12 +314,19 @@ const validationConfig = [
     { field: 'questdbIlpUrl', validator: validators.hostPort, label: 'QUESTDB_ILP_URL' },
     { field: 'questdbPgUrl', validator: validators.hostPort, label: 'QUESTDB_PG_URL' },
     { field: 'questdbFlushMode', validator: validators.questdbFlushMode, label: 'QUESTDB_FLUSH_MODE' },
-    { field: 'questdbIdleFlushAfterMs', validator: validators.nonNegativeInt, originalEnv: 'QUESTDB_IDLE_FLUSH_AFTER_MS' },
-    { field: 'questdbIdleFlushCheckMs', validator: validators.positiveInt, originalEnv: 'QUESTDB_IDLE_FLUSH_CHECK_MS' },
+    { field: 'questdbIdleFlushAfterMs', validator: validators.nonNegativeIntOrUndefined, originalEnv: 'QUESTDB_IDLE_FLUSH_AFTER_MS' },
+    { field: 'questdbIdleFlushCheckMs', validator: validators.positiveIntOrUndefined, originalEnv: 'QUESTDB_IDLE_FLUSH_CHECK_MS' },
     { field: 'questdbAutoFlushRows', validator: validators.positiveIntOrUndefined, originalEnv: 'QUESTDB_AUTO_FLUSH_ROWS' },
     { field: 'questdbAutoFlushIntervalMs', validator: validators.positiveIntOrUndefined, originalEnv: 'QUESTDB_AUTO_FLUSH_INTERVAL_MS' },
     { field: 'questdbMaxBufSize', validator: validators.positiveIntOrUndefined, originalEnv: 'QUESTDB_MAX_BUF_SIZE' },
     { field: 'questdbRetryTimeout', validator: validators.positiveIntOrUndefined, originalEnv: 'QUESTDB_RETRY_TIMEOUT' },
+    { field: 'questdbFlushRows', validator: validators.positiveIntOrUndefined, originalEnv: 'QUESTDB_FLUSH_ROWS' },
+    { field: 'questdbFlushIntervalMs', validator: validators.positiveIntOrUndefined, originalEnv: 'QUESTDB_FLUSH_INTERVAL_MS' },
+    { field: 'questdbBufferCeilingRows', validator: validators.positiveIntOrUndefined, originalEnv: 'QUESTDB_BUFFER_CEILING_ROWS' },
+    { field: 'questdbFlushDeadlineMs', validator: validators.positiveIntOrUndefined, originalEnv: 'QUESTDB_FLUSH_DEADLINE_MS' },
+    { field: 'questdbStdlibHttp', validator: validators.questdbStdlibHttp, label: 'QUESTDB_STDLIB_HTTP' },
+    { field: 'questdbRequestTimeout', validator: validators.positiveIntOrUndefined, originalEnv: 'QUESTDB_REQUEST_TIMEOUT' },
+    { field: 'questdbInitBufSize', validator: validators.positiveIntOrUndefined, originalEnv: 'QUESTDB_INIT_BUF_SIZE' },
     // QuestDB Credentials
     { field: 'questdbDatabase', validator: validators.nonEmptyString, label: 'QUESTDB_DATABASE' },
     { field: 'questdbUser', validator: validators.nonEmptyString, label: 'QUESTDB_USER' }
@@ -223,7 +343,14 @@ const validate = function () {
     for ( const config of validationConfig ) {
         const value = ENV_VARS[ config.field ];
         const originalEnv = config.originalEnv ? process.env[ config.originalEnv ] : value;
-        const label = config.label || config.field.toUpperCase().replace( /([a-z])([A-Z])/g, '$1_$2' );
+        // The label is the variable name as the operator typed it. A row
+        // that records the variable uses it; otherwise the name is
+        // derived from the field, inserting the underscores BEFORE
+        // uppercasing (the other order finds no boundaries and printed
+        // QUESTDBRETRYTIMEOUT until 2026-09-05).
+        const label = config.label ||
+            config.originalEnv ||
+            config.field.replace( /([a-z])([A-Z])/g, '$1_$2' ).toUpperCase();
 
         const error = config.validator( value, originalEnv || value, label );
         if ( error ) {
@@ -233,8 +360,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-031 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.