@blamejs/blamejs-shop 0.0.44

package/lib/vendor/blamejs/lib/local-db-thin.js

@@ -0,0 +1,321 @@
+"use strict";
+/**
+ * b.localDb.thin — lightweight node:sqlite wrapper for desktop-daemon-
+ * shaped local state.
+ *
+ * The framework's full b.db is the right tool when the workload needs
+ * vault-sealed columns, the audit chain, sealed-by-default schema
+ * governance, framework-schema bootstrap, derived-hash lookup, sealed-
+ * fields rotation, and the cross-cutting "encrypted at rest" envelope.
+ * That stack costs vault keys, a tmpfs sealed-file dance, schema
+ * declarations, and a startup audit chain — overkill for a daemon
+ * keeping a hundred-row local registry on the operator's laptop.
+ *
+ * b.localDb.thin keeps the parts a daemon does need:
+ *
+ *   - A node:sqlite handle opened in WAL mode with sane busy-timeout.
+ *   - Boot-time `PRAGMA integrity_check` (cheap + closes the partial-
+ *     write data-loss class).
+ *   - Optional corrupt-rename-and-recreate recovery: if the file fails
+ *     integrity_check or open() raises SQLITE_CORRUPT, rename it to
+ *     `<file>.corrupt-<unix-ms>` and start fresh against the operator-
+ *     supplied schema.
+ *   - LRU-bounded prepared-statement cache (matches b.db's shape so
+ *     long-running daemons with diverse query shapes don't leak
+ *     statement handles).
+ *   - Audit hooks on open / recover / close so operators can wire
+ *     the same incident review pipeline they already have for b.db.
+ *
+ * What it deliberately does NOT do:
+ *
+ *   - No vault, no field encryption, no per-row keys, no SHA3 derived
+ *     hashes — operators with PHI / PCI go straight to b.db.
+ *   - No audit chain — there is no server-side compliance posture for
+ *     a desktop daemon's sqlite cache.
+ *   - No schema governance — `schemaSql` is the operator's `CREATE
+ *     TABLE IF NOT EXISTS ...` script, run verbatim at open.
+ *   - No background flush / no encrypted-at-rest tmpfs — the file is
+ *     opened in place. Operators wanting at-rest encryption use full
+ *     b.db.
+ *
+ * Public surface:
+ *   localDbThin.thin({
+ *     file:       string,                // required absolute path
+ *     schemaSql:  string,                // required CREATE TABLE / INDEX script
+ *     recovery:   "refuse" | "rename-and-recreate",  // default: "refuse"
+ *     pragmas:    object,                // optional extra PRAGMA overrides
+ *     audit:      boolean,               // default: true
+ *   }) -> { db, prepare, run, query, close, file }
+ *
+ * Audit emits:
+ *   localdb.thin.opened     { file }
+ *   localdb.thin.recovered  { file, renamedTo }
+ *   localdb.thin.closed     { file }
+ */
+
+var nodeFs   = require("node:fs");
+var nodePath = require("node:path");
+var lazyRequire = require("./lazy-require");
+var validateOpts = require("./validate-opts");
+var safeSql = require("./safe-sql");
+var { LocalDbThinError } = require("./framework-error");
+
+var audit = lazyRequire(function () { return require("./audit"); });
+
+// LRU prepared-statement cache cap — same magnitude as lib/db.js's full
+// variant. Daemons issuing more than this many distinct SQL strings
+// likely have a string-concat bug rather than a legitimate need.
+var PREPARE_CACHE_MAX = 256;                                                       // allow:raw-byte-literal — distinct-statement cache cap
+
+var ALLOWED_RECOVERY = ["refuse", "rename-and-recreate"];
+
+// Bare NUL byte, expressed via String.fromCharCode so the source file
+// itself stays pure ASCII (the codebase-patterns gate also guarantees
+// this won't be confused with a literal embedded NUL during diffs).
+var NUL_BYTE = String.fromCharCode(0);
+
+function _validateOpts(opts) {
+  validateOpts.requireObject(opts, "localDb.thin", LocalDbThinError, "localdb-thin/bad-opts");
+  validateOpts.requireNonEmptyString(opts.file, "file", LocalDbThinError, "localdb-thin/bad-file");
+  // `file` is operator-supplied (daemon's chosen storage nodePath), not
+  // request-driven input. Reject NUL bytes defensively — Node's path
+  // routines silently truncate at the first NUL, which would let a
+  // typo open a different file than the operator intended.
+  if (opts.file.indexOf(NUL_BYTE) !== -1) {
+    throw new LocalDbThinError("localdb-thin/bad-file",
+      "localDb.thin: file path must not contain NUL bytes");
+  }
+  validateOpts.requireNonEmptyString(opts.schemaSql, "schemaSql",
+    LocalDbThinError, "localdb-thin/bad-schema-sql");
+  var recovery = opts.recovery || "refuse";
+  if (ALLOWED_RECOVERY.indexOf(recovery) === -1) {
+    throw new LocalDbThinError("localdb-thin/bad-recovery",
+      "localDb.thin: recovery must be one of " + ALLOWED_RECOVERY.join(", ") +
+      " (got '" + recovery + "')");
+  }
+  if (opts.pragmas !== undefined &&
+      (typeof opts.pragmas !== "object" || Array.isArray(opts.pragmas))) {
+    throw new LocalDbThinError("localdb-thin/bad-pragmas",
+      "localDb.thin: pragmas must be an object mapping pragma name -> value");
+  }
+}
+
+function _runPragmas(database, extra) {
+  database.exec("PRAGMA journal_mode=WAL");
+  database.exec("PRAGMA synchronous=NORMAL");
+  database.exec("PRAGMA busy_timeout=5000");
+  database.exec("PRAGMA foreign_keys=ON");
+  database.exec("PRAGMA secure_delete=ON");
+  try { database.exec("PRAGMA trusted_schema=OFF"); } catch (_e) { /* sqlite < 3.31 */ }
+  try { database.exec("PRAGMA cell_size_check=ON"); } catch (_e) { /* sqlite < 3.26 */ }
+  if (extra && typeof extra === "object") {
+    var keys = Object.keys(extra);
+    for (var i = 0; i < keys.length; i += 1) {
+      var name = keys[i];
+      // PRAGMA names are operator-supplied keys; reject anything that
+      // isn't a bare SQL identifier so this never becomes a SQL-injection
+      // vector even at config time. Composes the same identifier shape
+      // safeSql.validateIdentifier enforces elsewhere.
+      if (!safeSql.DEFAULT_IDENTIFIER_RE.test(name) ||
+          name.length > safeSql.MAX_IDENTIFIER_LENGTH) {
+        throw new LocalDbThinError("localdb-thin/bad-pragma-name",
+          "localDb.thin: pragma name '" + name + "' must be a bare identifier");
+      }
+      var value = extra[name];
+      if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
+        throw new LocalDbThinError("localdb-thin/bad-pragma-value",
+          "localDb.thin: pragma '" + name + "' value must be string|number|boolean");
+      }
+      database.exec("PRAGMA " + name + "=" + String(value));
+    }
+  }
+}
+
+function _integrityOk(database) {
+  try {
+    var rows = database.prepare("PRAGMA integrity_check").all();
+    return rows.length === 1 && rows[0] && rows[0].integrity_check === "ok";
+  } catch (_e) {
+    return false;
+  }
+}
+
+function thin(opts) {
+  _validateOpts(opts);
+
+  var auditOn  = opts.audit !== false;
+  // opts.file is operator-config (daemon-author chosen storage nodePath),
+  // not request-driven input. Validation above already rejected non-
+  // strings and NUL bytes. The operator picks the file location; the
+  // wrapper opens it as-is.
+  var file = opts.file;
+  var recovery = opts.recovery || "refuse";
+
+  function _safeEmitAudit(action, metadata) {
+    if (!auditOn) return;
+    try { audit().safeEmit({ action: action, outcome: "success", metadata: metadata || {} }); }
+    catch (_e) { /* drop-silent — audit best-effort */ }
+  }
+
+  // node:sqlite is required lazily so a process never importing localDb
+  // doesn't pay the cost of resolving it at module load.
+  var nodeSqlite = require("node:sqlite");
+  var DatabaseSync = nodeSqlite.DatabaseSync;
+  if (typeof DatabaseSync !== "function") {
+    throw new LocalDbThinError("localdb-thin/sqlite-missing",
+      "localDb.thin: node:sqlite is unavailable on this Node build (requires Node 24.14+)");
+  }
+
+  // Ensure parent directory exists — operators commonly point this at
+  // an OS app-data path that may not exist on first daemon launch.
+  try { nodeFs.mkdirSync(nodePath.dirname(file), { recursive: true }); } catch (_e) { /* best-effort */ }
+
+  var database = null;
+  var renamedTo = null;
+
+  function _attemptOpen() {
+    var db = new DatabaseSync(file);
+    _runPragmas(db, opts.pragmas);
+    if (!_integrityOk(db)) {
+      try { db.close(); } catch (_e) { /* best-effort */ }
+      throw new LocalDbThinError("localdb-thin/corrupt",
+        "localDb.thin: PRAGMA integrity_check failed for '" + file + "'");
+    }
+    db.exec(opts.schemaSql);
+    return db;
+  }
+
+  try {
+    database = _attemptOpen();
+  } catch (e) {
+    var corrupt = (e && e.code === "localdb-thin/corrupt") ||
+                  (e && typeof e.message === "string" &&
+                   /SQLITE_CORRUPT|malformed|not a database/i.test(e.message));
+    if (corrupt && recovery === "rename-and-recreate") {
+      var stamp = String(Date.now());
+      renamedTo = file + ".corrupt-" + stamp;
+      // Bounded rename retry — Windows holds a file lock for several
+      // hundred ms after DatabaseSync.close() returns under load
+      // (CI runner contention amplifies this). Linux/macOS land on
+      // the first attempt. Capped at ~2s total so a genuinely-stuck
+      // handle still surfaces as recovery-failed rather than hanging.
+      var renamed = false;
+      var lastRenameErr = null;
+      for (var attempt = 0; attempt < 20 && !renamed; attempt += 1) {
+        try {
+          if (nodeFs.existsSync(file)) nodeFs.renameSync(file, renamedTo);
+          renamed = true;
+        } catch (re) {
+          lastRenameErr = re;
+          if (re && (re.code === "EBUSY" || re.code === "EPERM")) {
+            // Synchronous spin — don't reach for setTimeout in a
+            // boot-time nodePath. 100ms × 20 = 2s upper bound.
+            var until = Date.now() + 100;
+            while (Date.now() < until) { /* spin */ }
+            continue;
+          }
+          throw new LocalDbThinError("localdb-thin/recovery-failed",
+            "localDb.thin: rename of corrupt file failed: " + ((re && re.message) || String(re)));
+        }
+      }
+      if (!renamed) {
+        throw new LocalDbThinError("localdb-thin/recovery-failed",
+          "localDb.thin: rename of corrupt file failed: " +
+          ((lastRenameErr && lastRenameErr.message) || "unknown"));
+      }
+      // Also move WAL/SHM siblings if present so the fresh DB doesn't
+      // re-attach a half-open journal.
+      ["-wal", "-shm"].forEach(function (suffix) {
+        var sibling = file + suffix;
+        if (nodeFs.existsSync(sibling)) {
+          try { nodeFs.renameSync(sibling, sibling + ".corrupt-" + stamp); }
+          catch (_se) { /* best-effort */ }
+        }
+      });
+      database = _attemptOpen();
+      _safeEmitAudit("localdb.thin.recovered", { file: file, renamedTo: renamedTo });
+    } else if (corrupt) {
+      throw new LocalDbThinError("localdb-thin/corrupt",
+        "localDb.thin: file '" + file + "' is corrupt; pass recovery: 'rename-and-recreate' to auto-recover");
+    } else if (e && e.isLocalDbThinError) {
+      // Bad-pragma / bad-shape errors bubble up from _runPragmas with
+      // their own typed code already attached — re-throw verbatim
+      // rather than re-wrapping behind open-failed.
+      throw e;
+    } else {
+      throw new LocalDbThinError("localdb-thin/open-failed",
+        "localDb.thin: open of '" + file + "' failed: " + ((e && e.message) || String(e)));
+    }
+  }
+
+  _safeEmitAudit("localdb.thin.opened", { file: file });
+
+  // ---- Prepared-statement cache ----
+  var prepareCache = new Map();
+  var closed = false;
+
+  function _ensureOpen() {
+    if (closed) {
+      throw new LocalDbThinError("localdb-thin/closed",
+        "localDb.thin: handle is closed");
+    }
+  }
+
+  function prepare(sql) {
+    _ensureOpen();
+    validateOpts.requireNonEmptyString(sql, "sql",
+      LocalDbThinError, "localdb-thin/bad-sql");
+    if (prepareCache.has(sql)) {
+      // Touch for LRU
+      var hit = prepareCache.get(sql);
+      prepareCache.delete(sql);
+      prepareCache.set(sql, hit);
+      return hit;
+    }
+    var stmt = database.prepare(sql);
+    prepareCache.set(sql, stmt);
+    if (prepareCache.size > PREPARE_CACHE_MAX) {
+      var oldest = prepareCache.keys().next().value;
+      prepareCache.delete(oldest);
+    }
+    return stmt;
+  }
+
+  function run(sql /* , ...params */) {
+    _ensureOpen();
+    var params = Array.prototype.slice.call(arguments, 1);
+    var stmt = prepare(sql);
+    return stmt.run.apply(stmt, params);
+  }
+
+  function query(sql /* , ...params */) {
+    _ensureOpen();
+    var params = Array.prototype.slice.call(arguments, 1);
+    var stmt = prepare(sql);
+    return stmt.all.apply(stmt, params);
+  }
+
+  function close() {
+    if (closed) return;
+    closed = true;
+    prepareCache.clear();
+    try { database.close(); } catch (_e) { /* best-effort */ }
+    _safeEmitAudit("localdb.thin.closed", { file: file });
+  }
+
+  return {
+    db:           database,
+    prepare:      prepare,
+    run:          run,
+    query:        query,
+    close:        close,
+    file:         file,
+    recovered:    !!renamedTo,
+    recoveredTo:  renamedTo,
+  };
+}
+
+module.exports = {
+  thin:               thin,
+  LocalDbThinError:   LocalDbThinError,
+};

package/lib/vendor/blamejs/lib/log-stream-cloudwatch.js

@@ -0,0 +1,369 @@
+"use strict";
+/**
+ * AWS CloudWatch Logs sink — PutLogEvents over HTTPS with SigV4.
+ *
+ * Operator config:
+ *
+ *   {
+ *     region:           "us-east-1"
+ *     accessKeyId:      env("AWS_ACCESS_KEY_ID")
+ *     secretAccessKey:  env("AWS_SECRET_ACCESS_KEY")
+ *     sessionToken:     env("AWS_SESSION_TOKEN")    // optional, STS creds
+ *     logGroupName:     "my-app-logs"               // operator pre-creates
+ *     logStreamName:    "instance-1"                // operator pre-creates
+ *     endpoint:         "https://logs.us-east-1.amazonaws.com"   // optional
+ *     batchSize:        100                          // CW caps at 10K events / 1 MiB per call
+ *     maxBatchAgeMs:    C.TIME.seconds(5)
+ *     timeoutMs:        C.TIME.seconds(30)
+ *     retry:            { maxAttempts, baseDelayMs, ... }
+ *     bufferLimit:      10000
+ *     onDrop:           function ({ reason, batch, error }) { ... }
+ *   }
+ *
+ * Wire format (Logs_20140328 PutLogEvents — JSON-1.1 over HTTPS):
+ *
+ *   POST /
+ *   X-Amz-Target: Logs_20140328.PutLogEvents
+ *   Content-Type: application/x-amz-json-1.1
+ *   Authorization: AWS4-HMAC-SHA256 Credential=... SignedHeaders=... Signature=...
+ *   Body: { logGroupName, logStreamName, logEvents: [{ timestamp, message }, ...] }
+ *
+ * AWS quirks the framework handles:
+ *   - Events MUST be sorted by timestamp ascending — sink sorts before send.
+ *   - Per-batch caps: 10,000 events AND <= 1 MiB total payload. Operator
+ *     batchSize is enforced; the framework also splits batches when the
+ *     1 MiB ceiling is reached mid-build.
+ *   - Per-event 256 KiB hard cap. Oversized events are dropped at emit-time
+ *     with onDrop fired.
+ *   - sequenceToken is optional in modern CloudWatch (post-2023). If a
+ *     legacy account requires it, CloudWatch returns
+ *     InvalidSequenceTokenException with the expected token; the
+ *     framework retries with that token transparently.
+ *   - ResourceNotFoundException -> permanent error (operator forgot to
+ *     create the log group or stream); surfaced via onDrop with a
+ *     clear error.
+ *
+ * SigV4 signing reuses lib/object-store/sigv4.js with service: "logs".
+ */
+var C = require("./constants");
+var nodeCrypto = require("node:crypto");
+var safeAsync = require("./safe-async");
+var safeJson = require("./safe-json");
+var sigv4 = require("./object-store/sigv4");
+var retryHelper = require("./retry");
+var { LogStreamError } = require("./framework-error");
+var httpClient = require("./http-client");
+
+var MAX_RESPONSE_BYTES = C.BYTES.mib(1);
+// AWS PutLogEvents hard limit: 10K events per batch (Logs_20140328 docs).
+var CW_MAX_EVENTS_PER_BATCH = C.BYTES.bytes(10000);
+var CW_MAX_BATCH_BYTES      = C.BYTES.mib(1);
+var CW_MAX_EVENT_BYTES      = C.BYTES.kib(256);
+var CW_EVENT_OVERHEAD_BYTES = C.BYTES.bytes(26);
+// Truncated-message preview embedded in onDrop callbacks for oversize
+// events — short enough to fit in a single log line so operators can
+// spot the producer that emitted the over-cap record.
+var DROP_PREVIEW_BYTES = C.BYTES.bytes(200);
+
+var DEFAULTS = {
+  batchSize:     100,
+  maxBatchAgeMs: C.TIME.seconds(5),
+  timeoutMs:     C.TIME.seconds(30),
+  // Ring-buffer cap (event count, not bytes); routed through C.BYTES
+  // identity passthrough so the file's literal arithmetic has a single
+  // source of truth.
+  bufferLimit:   C.BYTES.bytes(10000),
+};
+
+var _err = LogStreamError.factory;
+
+function _resolveEndpoint(cfg) {
+  if (cfg.endpoint) return cfg.endpoint.replace(/\/+$/, "") + "/";
+  return "https://logs." + cfg.region + ".amazonaws.com/";
+}
+
+function _eventByteSize(message) {
+  return Buffer.byteLength(message, "utf8") + CW_EVENT_OVERHEAD_BYTES;
+}
+
+function _serializeBatch(events, cfg, sequenceToken) {
+  events.sort(function (a, b) { return a.timestamp - b.timestamp; });
+  var body = {
+    logGroupName:  cfg.logGroupName,
+    logStreamName: cfg.logStreamName,
+    logEvents:     events,
+  };
+  if (sequenceToken) body.sequenceToken = sequenceToken;
+  return Buffer.from(JSON.stringify(body), "utf8");
+}
+
+function _signedHeaders(cfg, body, target) {
+  target = target || "Logs_20140328.PutLogEvents";
+  var url = _resolveEndpoint(cfg);
+  var payloadHash = nodeCrypto.createHash("sha256").update(body).digest("hex");
+  var unsigned = {
+    "Content-Type": "application/x-amz-json-1.1",
+    "X-Amz-Target": target,
+  };
+  var signed = sigv4.signRequest({
+    method:           "POST",
+    url:              url,
+    headers:          unsigned,
+    payloadHash:      payloadHash,
+    region:           cfg.region,
+    service:          "logs",
+    accessKeyId:      cfg.accessKeyId,
+    secretAccessKey:  cfg.secretAccessKey,
+    sessionToken:     cfg.sessionToken || null,
+    allowedProtocols: cfg.allowedProtocols,
+  });
+  return signed.headers;
+}
+
+// CloudWatch CreateLogGroup / CreateLogStream wrappers. Operator opts in
+// via cfg.autoCreate = true; default stays "operator pre-creates via
+// Terraform / CDK / aws cli" so the framework doesn't paper over an
+// IAM-misconfigured deployment with surprising side effects.
+async function _ensureLogGroupAndStream(cfg) {
+  // CreateLogGroup — idempotent on the wire (we treat
+  // ResourceAlreadyExistsException as success).
+  var groupBody = Buffer.from(JSON.stringify({ logGroupName: cfg.logGroupName }), "utf8");
+  var groupHeaders = _signedHeaders(cfg, groupBody, "Logs_20140328.CreateLogGroup");
+  try {
+    await _post(cfg, groupBody, groupHeaders);
+  } catch (e) {
+    var msg = (e && e.message) || "";
+    if (!/ResourceAlreadyExistsException/.test(msg)) {
+      throw _err("AUTOCREATE_FAILED",
+        "log-stream cloudwatch autoCreate: CreateLogGroup failed: " + msg);
+    }
+  }
+  // CreateLogStream — same idempotency treatment.
+  var streamBody = Buffer.from(JSON.stringify({
+    logGroupName:  cfg.logGroupName,
+    logStreamName: cfg.logStreamName,
+  }), "utf8");
+  var streamHeaders = _signedHeaders(cfg, streamBody, "Logs_20140328.CreateLogStream");
+  try {
+    await _post(cfg, streamBody, streamHeaders);
+  } catch (e) {
+    var msg2 = (e && e.message) || "";
+    if (!/ResourceAlreadyExistsException/.test(msg2)) {
+      throw _err("AUTOCREATE_FAILED",
+        "log-stream cloudwatch autoCreate: CreateLogStream failed: " + msg2);
+    }
+  }
+}
+
+function _post(cfg, body, headers) {
+  return httpClient.request({
+    method:           "POST",
+    url:              _resolveEndpoint(cfg),
+    headers:          headers,
+    body:             body,
+    idleTimeoutMs:    cfg.timeoutMs,
+    maxResponseBytes: MAX_RESPONSE_BYTES,
+    errorClass:       LogStreamError,
+    allowedProtocols: cfg.allowedProtocols,
+    allowInternal:    cfg.allowInternal,
+  });
+}
+
+function _isPermanentAwsError(err) {
+  if (!err) return false;
+  var msg = err.message || "";
+  if (/ResourceNotFoundException/.test(msg)) return true;
+  if (/InvalidParameterException/.test(msg)) return true;
+  if (/UnrecognizedClientException/.test(msg)) return true;
+  if (/AccessDeniedException/.test(msg)) return true;
+  if (/SerializationException/.test(msg)) return true;
+  return false;
+}
+
+function create(config) {
+  if (!config || !config.region) {
+    throw _err("BAD_OPT", "log-stream cloudwatch requires { region }");
+  }
+  if (!config.accessKeyId || !config.secretAccessKey) {
+    throw _err("BAD_OPT",
+      "log-stream cloudwatch requires { accessKeyId, secretAccessKey } " +
+      "(IAM role or env-supplied STS credentials)");
+  }
+  if (!config.logGroupName || !config.logStreamName) {
+    throw _err("BAD_OPT",
+      "log-stream cloudwatch requires { logGroupName, logStreamName }. " +
+      "Operator pre-creates both via aws / CDK / Terraform by default; " +
+      "pass { autoCreate: true } to have the framework issue " +
+      "CreateLogGroup + CreateLogStream on first emit (idempotent — " +
+      "ResourceAlreadyExistsException treated as success).");
+  }
+  var cfg = Object.assign({}, DEFAULTS, config);
+  var onDrop = typeof cfg.onDrop === "function" ? cfg.onDrop : null;
+  var _emitDrop = safeAsync.makeDropCallback(onDrop);
+  var buffer = [];
+  var dropCount = 0;
+  var inFlight = false;
+  var closed = false;
+  var sequenceToken = null;
+  var flushScheduler = safeAsync.makeScheduledFlush(cfg.maxBatchAgeMs, function () { return _flush(); });
+
+  function _takeBatch() {
+    var batch = [];
+    var totalBytes = 0;
+    while (buffer.length > 0) {
+      var nextEvent = buffer[0];
+      var size = _eventByteSize(nextEvent.message);
+      if (batch.length > 0 &&
+          (batch.length >= cfg.batchSize ||
+           batch.length >= CW_MAX_EVENTS_PER_BATCH ||
+           totalBytes + size > CW_MAX_BATCH_BYTES)) {
+        break;
+      }
+      batch.push(buffer.shift());
+      totalBytes += size;
+    }
+    return batch;
+  }
+
+  // autoCreate handshake — runs once per process before the first
+  // PutLogEvents. Promise cached so concurrent emits don't fire
+  // duplicate CreateLogGroup / CreateLogStream calls.
+  var autoCreatePromise = null;
+  function _ensureAutoCreated() {
+    if (!cfg.autoCreate) return Promise.resolve();
+    if (!autoCreatePromise) autoCreatePromise = _ensureLogGroupAndStream(cfg);
+    return autoCreatePromise;
+  }
+
+  async function _flush() {
+    if (inFlight) return;
+    if (buffer.length === 0) return;
+    inFlight = true;
+    try {
+      try { await _ensureAutoCreated(); }
+      catch (acErr) {
+        // autoCreate failure is permanent — every subsequent batch
+        // would hit the same error. Drop the queue with the
+        // operator-supplied onDrop callback so they see exactly which
+        // events were lost AND why, then bail.
+        var allBuffered = buffer.splice(0, buffer.length);
+        dropCount += allBuffered.length;
+        _emitDrop("autocreate-failed", allBuffered, acErr);
+        return;
+      }
+      while (buffer.length > 0 && !closed) {
+        var batch = _takeBatch();
+        if (batch.length === 0) break;
+        try {
+          await retryHelper.withRetry(function () {
+            return _send(batch);
+          }, Object.assign({
+            isPermanent: _isPermanentAwsError,
+          }, cfg.retry || {}));
+        } catch (e) {
+          dropCount += batch.length;
+          _emitDrop("retry-exhausted", batch, e);
+          break;
+        }
+      }
+    } finally {
+      inFlight = false;
+      if (buffer.length > 0) flushScheduler.schedule();
+    }
+  }
+
+  async function _send(batch) {
+    var body = _serializeBatch(batch, cfg, sequenceToken);
+    var headers = _signedHeaders(cfg, body);
+    var res;
+    try {
+      res = await _post(cfg, body, headers);
+    } catch (e) {
+      var match = /expected sequenceToken is:\s*(\S+)/.exec(e.message || "");
+      if (match) {
+        sequenceToken = match[1];
+        var retryBody = _serializeBatch(batch, cfg, sequenceToken);
+        var retryHeaders = _signedHeaders(cfg, retryBody);
+        res = await _post(cfg, retryBody, retryHeaders);
+      } else {
+        throw e;
+      }
+    }
+    if (res && res.body) {
+      try {
+        var parsed = safeJson.parse(res.body.toString("utf8"), { maxBytes: MAX_RESPONSE_BYTES });
+        if (parsed && parsed.nextSequenceToken) sequenceToken = parsed.nextSequenceToken;
+      } catch (_e) { /* response body not JSON; modern CW returns empty */ }
+    }
+    return res;
+  }
+
+  function emit(record) {
+    if (closed) return Promise.resolve({ accepted: false, reason: "sink closed" });
+    var message;
+    if (typeof record.message === "string") {
+      message = record.message;
+    } else {
+      message = JSON.stringify(record);
+    }
+    var size = _eventByteSize(message);
+    if (size > CW_MAX_EVENT_BYTES) {
+      _emitDrop("event-too-large", [{
+        timestamp: record.ts || Date.now(),
+        message:   message.slice(0, DROP_PREVIEW_BYTES) + "...[truncated for drop event]",
+      }], new Error("event exceeds 256 KiB CloudWatch hard cap (was " + size + " bytes)"));
+      dropCount += 1;
+      return Promise.resolve({ accepted: false, reason: "event too large" });
+    }
+    if (buffer.length >= cfg.bufferLimit) {
+      var dropped = buffer.shift();
+      dropCount += 1;
+      _emitDrop("overflow", [dropped], null);
+    }
+    buffer.push({
+      timestamp: record.ts || Date.now(),
+      message:   message,
+    });
+    if (buffer.length >= cfg.batchSize) {
+      _flush().catch(function () {});
+    } else {
+      flushScheduler.schedule();
+    }
+    return Promise.resolve({ accepted: true, queued: buffer.length });
+  }
+
+  async function close() {
+    closed = true;
+    flushScheduler.cancel();
+    await _flush();
+  }
+
+  function stats() {
+    return {
+      queued:        buffer.length,
+      dropped:       dropCount,
+      inFlight:      inFlight,
+      sequenceToken: sequenceToken,
+      endpoint:      _resolveEndpoint(cfg),
+    };
+  }
+
+  return {
+    protocol: "cloudwatch",
+    emit:     emit,
+    close:    close,
+    stats:    stats,
+    flush:    _flush,
+  };
+}
+
+module.exports = {
+  create:                create,
+  _resolveEndpoint:      _resolveEndpoint,
+  _eventByteSize:        _eventByteSize,
+  _serializeBatch:       _serializeBatch,
+  _isPermanentAwsError:  _isPermanentAwsError,
+  CW_MAX_EVENTS_PER_BATCH: CW_MAX_EVENTS_PER_BATCH,
+  CW_MAX_BATCH_BYTES:    CW_MAX_BATCH_BYTES,
+  CW_MAX_EVENT_BYTES:    CW_MAX_EVENT_BYTES,
+};