@blamejs/core 0.6.25 → 0.6.27

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.6.x
 
+- **0.6.27** (2026-05-02) — Redis backend for `b.queue` so multi-replica apps can share a single queue without each needing to be cluster leader. **Bespoke RESP2 client** (`lib/redis-client.js`) — zero npm runtime deps. TCP via `node:net` + TLS via `node:tls` (`rediss://` auto-detected), legacy single-arg AUTH + ACL `AUTH user pass`, `SELECT db`, pipelining, exponential-backoff reconnect, EVAL helper. **`b.queue` protocol "redis"** (`lib/queue-redis.js`) — full enqueue/lease/extendLease/complete/fail/sweepExpired/size/purge/dlqList/dlqRetry/dlqSize parity with the local backend. Atomicity comes from server-side Lua scripts so concurrent consumers can't double-lease and a sweep can't race a complete. Storage layout: per-job HASH (sealed payload + lastError via `cryptoField.sealRow("_blamejs_jobs", row)` — same crypto config as the local backend), per-queue ready ZSET scored by availableAt, per-queue inflight ZSET scored by leaseExpiresAt, per-queue dlq ZSET scored by finishedAt, plus a queues SET so sweepExpired walks every known queue without a global secondary index. Cron-repeat handled in `complete()` JS — re-enqueues the next firing as a fresh jobId with availableAt=next-cron-fire. **`b.queue.bootFromEnv({ env })`** — env-driven init mirroring `b.network.bootFromEnv` and `b.logStream.bootFromEnv`. Reads `BLAMEJS_QUEUE_PROTOCOL` (`local`|`redis`), `BLAMEJS_QUEUE_REDIS_URL`, `BLAMEJS_QUEUE_REDIS_PASSWORD`, `BLAMEJS_QUEUE_REDIS_USERNAME`, `BLAMEJS_QUEUE_REDIS_TLS`, `BLAMEJS_QUEUE_REDIS_KEY_PREFIX`. Operators flip from local to Redis without a code change; both wiki docker-compose configs declare the new env knobs. Removed `redis` from `DEFERRED_PROTOCOLS`. **Out of scope for v1** (deferred to follow-up patches with explicit re-open conditions): Redis Cluster (slot-routing), Sentinel (managed primary failover), priority ordering on the Redis backend (queue-local supports `priority` opt; Redis backend orders strictly by availableAt for v1), flow children with `dependsOn` cascade. **Wiki**: queue-cache page documents the Redis backend opts schema, bootFromEnv, and the layout. **Tests**: 24 RESP2 protocol parser unit tests (`test/layer-0-primitives/redis-client.test.js`) cover URL parsing, command encoding (binary-safe), every reply type (simple string / error / integer / bulk / nil bulk / nested array / pipelined / incomplete-mid-frame). Live Redis round-trip tests (`test/layer-0-primitives/queue-redis.test.js`) cover enqueue+lease, availableAt scheduling, visibility-timeout sweep, fail+retry path, DLQ list/retry/size, extendLease, purge, and concurrent-leaser no-double-lease — skip cleanly when `BLAMEJS_TEST_REDIS_URL` is not set so the smoke suite passes on dev boxes without a Redis container. Smoke 6780 OK.
+- **0.6.26** (2026-05-02) — `blamejs restore` and `blamejs audit verify-chain` subcommands wrap the existing `b.restore` and `b.audit.verifyChain` primitives so operators can drive them from runbooks without writing app code. **`blamejs restore`**: `list` (enumerate bundles in storage), `inspect` (manifest summary without touching live data), `apply` (live in-place restore with rollback preserved), `rollback` (revert to most-recent OR named restore point), `list-rollbacks` (enumerate preserved rollback points). Two ways to identify a bundle — `--bundle <dir>` matches the shape `blamejs backup extract` produces (parent dir is treated as storage root, basename as bundle id), or `--storage-root <root> --bundle-id <id>` for multi-bundle stores. `apply` honors `--max-pulled-bytes` / `--max-pulled-files` (defaults 4 GiB / 100K), `--rollback-root` (default `<data-dir>.rollbacks`), `--no-audit`, and `BLAMEJS_BACKUP_PASSPHRASE` env. **`blamejs audit verify-chain`**: walks the live audit chain end-to-end, reports tampering with `breakAt` / `breakRowId` / expected-vs-actual prevHash; honours `--max-rows` to bound long walks; default table is `audit_log`. **Wiki CLI snapshot test now validates subcommand pairs**, not just top commands. Walks every wiki + README invocation of the form `blamejs <cmd> <sub>` and verifies that <sub> exists in the perCommand[<cmd>].subcommands list parsed from `lib/cli.js`. Surfaced one real drift on first run: `examples/wiki/seeders/prod/pages/backup-restore.js` documented `blamejs audit verify-signing` after vault rotation, but no such subcommand existed (only `verify-bundle`); fixed by shipping the new `verify-chain` subcommand and updating the wiki to reference it. Two top-level command gaps surfaced and fixed: `blamejs restore` (now real) and `blamejs network status` (was prose-promised in `network-config.js`; reworded to point at `b.network.snapshot()` for /healthz / custom diagnostics routes since wiring a CLI command for it is operator-side work). README CLI table updated with `restore` row and the two new audit subcommands.
 - **0.6.25** (2026-05-02) — `b.logStream` gains an AWS CloudWatch Logs sink AND framework-level env wiring. **CloudWatch sink**: `protocol: "cloudwatch"` POSTs `PutLogEvents` over HTTPS with SigV4 signing (service `logs`); operator pre-creates the log group + log stream (the framework does NOT auto-create). Honors IAM role + STS session-token credentials. Respects all three CloudWatch caps automatically: 10,000 events / 1 MiB total payload / 256 KiB-per-event. Per-event oversize dropped at `emit()`-time with `onDrop` fired (truncated message in the drop notification). Per-batch oversize split mid-flush. Permanent AWS errors (`ResourceNotFoundException` / `AccessDeniedException` / `InvalidParameterException` / `UnrecognizedClientException` / `SerializationException`) skip the retry budget. `InvalidSequenceTokenException` (legacy CW accounts) extracts the expected token from the error message and retries with it once. `lib/object-store/sigv4.js` `signRequest()` is now service-agnostic — accepts `opts.service` (default still `"s3"` for back-compat). Removed `cloudwatch` from `DEFERRED_PROTOCOLS`. **`b.logStream.bootFromEnv({ env })`**: framework-level env-driven init mirroring `b.network.bootFromEnv`. Reads `BLAMEJS_LOG_STREAM_PROTOCOL` (`local`/`webhook`/`otlp`/`cloudwatch`), `BLAMEJS_LOG_STREAM_URL`, `BLAMEJS_LOG_STREAM_TOKEN`, `BLAMEJS_LOG_STREAM_SERVICE_NAME`, `BLAMEJS_LOG_STREAM_SERVICE_VERSION`, `BLAMEJS_LOG_STREAM_CLOUDWATCH_LOG_GROUP`, `BLAMEJS_LOG_STREAM_CLOUDWATCH_LOG_STREAM`, `BLAMEJS_LOG_STREAM_PATH`, plus standard AWS_*. Operators get a working log-stream sink without writing build-app code. Wiki app's `build-app.js` replaced its inline env-reading with one `b.logStream.bootFromEnv()` call; both docker-compose configs declare the new env knobs. **Wiki env-snapshot test**: parallel to api-snapshot.json — walks `process.env.X` / `env.X` / `safeEnv.readVar("X")` reads in the wiki app + framework `lib/`, walks docker-compose env declarations, captures the union as `examples/wiki/env-snapshot.json`, fails the e2e gate when env vars are added/removed without updating the snapshot OR when source-only / compose-only gaps appear (env knob declared but unread, env read but undocumented). The validator immediately surfaced 13 real gaps in the wiki app: 5 `WIKI_*` env vars read by source but missing from docker-compose (`WIKI_VAULT_MODE`, `WIKI_DB_AT_REST`, `WIKI_AUDIT_SIGNING_MODE`, `WIKI_BIND`, `WIKI_SITE_URL`), 2 framework env vars (`BLAMEJS_AUDIT_SIGNING_MODE`, `BLAMEJS_TMPDIR`) read by `lib/db.js` via `safeEnv.readVar` but never declared in the wiki's compose configs, and 6 dead env knobs in compose that nothing read. All 13 fixed. Update workflow: `BLAMEJS_UPDATE_ENV_SNAPSHOT=1 node examples/wiki/test/validate-env-snapshot.js` (mirrors the api-snapshot UX). Wiki observability page documents the new sink alongside webhook + otlp; README "What ships in the box" calls out all four log-stream sinks. Tests cover endpoint resolution, event-byte accounting, batch sorting + sequence-token round-trip, permanent-error classifier, validation, round-trip via mock CloudWatch, STS session-token propagation, ResourceNotFoundException no-retry path, 256 KiB per-event hard cap, dispatcher integration, AND batch splitting on the 1-MiB cap (5 quarter-MB events POST as 4 + 1 batches).
 - **0.6.24** (2026-05-02) — `b.logStream` gains an OTLP/HTTP-JSON sink. `protocol: "otlp"` now forwards log records to any OpenTelemetry collector via the OTel Logs Data Model — `resourceLogs` → `scopeLogs` → `logRecords` envelope with `severityNumber` (debug=5/info=9/warn=13/error=17), `severityText`, `timeUnixNano` (string-encoded for JSON-safe 64-bit), `body.stringValue`, and OTel-typed attributes. Operator config: `{ url, serviceName, serviceVersion, resourceAttributes, auth, headers, batchSize, retry, onDrop, ... }` — same back-pressure semantics as the webhook sink (per-sink ring buffer, batched flush on size or maxBatchAgeMs, exponential-backoff retry, drop-on-overflow with operator-supplied onDrop callback). URL convention: `/v1/logs` is auto-appended when the operator passes the collector root. JSON not protobuf — operators benchmarking >100K logs/s ship the OTel Collector locally so the framework hands JSON to a sidecar that forwards via gRPC. Removed `otlp` from `DEFERRED_PROTOCOLS`. Wiki observability page documents the new sink with a `b.logStream.init` example pointing at an OTel collector. Tests cover URL resolution, attribute encoding (string / int / float / bool / array / nested object), severity mapping, round-trip via mock collector, auth header pass-through, retry on 5xx + drop on retry-exhaustion, buffer overflow, dispatcher integration. Verified 0 leaks across 291 commits via `gitleaks`.
 - **0.6.23** (2026-05-02) — v0.6.22 follow-up cleanup. The cron-repeat call site in queue-local.js was passing both `availableAt` AND `delaySeconds` (the former was the precise next-fire ms; the latter was a redundant `Math.floor((nextMs - nowMs) / 1000)` computation that only existed to work around the bug v0.6.22 fixed). Dropped — the cron repeat now passes `availableAt` alone, matching the queue's documented precedence rule. The enqueue() docstring gains a 20-line "SCHEDULING PRECEDENCE" header documenting that `opts.availableAt` wins over `opts.delaySeconds` when both are passed, why the framework chose that direction, and which callers should use which form. New round-trip preservation regression test (`testEnqueueRoundTripsAvailableAt`) covers three precise targets, the delaySeconds-only path, and the both-opts-set case — gates against any future "I'll just rederive it from the floored seconds" mistake. Audited the rest of the framework for the same `(absolute-time, relative-time)` opt-overlap shape (cache.set, session.rotate, apiKey, dualControl): queue is the only primitive carrying both forms, so a generalized `b.time.resolveTimePoint` primitive would be premature with one call site.

package/README.md

@@ -41,7 +41,7 @@ var b = require("@blamejs/core");
 
 The framework bundles the surface a typical Node app reaches for. Every primitive listed is callable today; nothing is a stub.
 
-- **Data layer** — SQLite with sealed-by-default columns (`b.db`), migrations, seeders, atomic-file writes; bring-your-own external Postgres / MySQL / etc. with pool tuning + role-aware connect + read-replica routing (`b.externalDb`); declarative role-narrowed views and Postgres row-level-security migrations (`b.db.declareView`, `b.db.declareRowPolicy`); S3 / R2 / B2 / GCS / Azure object store with multipart upload + SSE + bucket ops (`b.storage`, `b.objectStore`); durable queue with priority + cron + flows (`b.queue`, `b.jobs`); cluster-shared cache (`b.cache`).
+- **Data layer** — SQLite with sealed-by-default columns (`b.db`), migrations, seeders, atomic-file writes; bring-your-own external Postgres / MySQL / etc. with pool tuning + role-aware connect + read-replica routing (`b.externalDb`); declarative role-narrowed views and Postgres row-level-security migrations (`b.db.declareView`, `b.db.declareRowPolicy`); S3 / R2 / B2 / GCS / Azure object store with multipart upload + SSE + bucket ops (`b.storage`, `b.objectStore`); durable queue with priority + cron + flows on the local SQLite backend OR a shared Redis backend for multi-replica deploys (`b.queue`, `b.jobs`); cluster-shared cache (`b.cache`).
 - **Identity & access** — passwords (Argon2id) + policy primitive (NIST 800-63B / PCI-DSS 4.0 / HIPAA-AAL2 profiles, HaveIBeenPwned k-anonymity breach check, length / context / dictionary / complexity rules, rotation + history) (`b.auth.password`); passkeys (WebAuthn), TOTP, JWT (PQ-default), OAuth, sessions with optional IP / UA fingerprint drift detection + anomaly scoring, brute-force lockout (`b.auth.*`, `b.session`); RBAC + optional per-role DB binding + role-spec `requireMfa` + per-route MFA freshness window + ABAC predicate registry (`b.permissions`); API keys with rotation (`b.apiKey`); break-glass column gates with second-factor + audit (`b.breakGlass`); two-person-rule approval workflow with m-of-n quorum + cooling-off lock + approver-role gate + cancellation (`b.dualControl`).
 - **Crypto** — envelope-versioned PQC at rest (ML-KEM-1024 + P-384 hybrid, XChaCha20-Poly1305, SHAKE256), vault sealing, field-level crypto + cryptographic erasure (`b.cryptoField.eraseRow`), signed webhooks (SLH-DSA-SHAKE-256f), ECIES API encryption (`b.crypto`, `b.vault`, `b.webhook`); pure-JS mTLS CA, PQC TLS gates inbound + outbound (`b.mtlsCa`, `b.pqcGate`, `b.pqcAgent`).
 - **HTTP** — router with schema-validated routes + OpenAPI publication; full middleware stack (CSRF, CORS, rate-limit, security headers, CSP nonce, body parser, compression, SSE, request log, request-time DB role binding via `b.middleware.dbRoleFor`, in-process CIDR fence via `b.middleware.networkAllowlist`) wired by `createApp`; HTTP/1.1 + HTTP/2 outbound client with SSRF gate, scheme + userinfo + per-host (wildcard / per-method) destination allowlist, redirects, multipart, interceptors, progress, encrypted cookie jar (`b.httpClient`, `b.ssrfGuard`, `b.safeUrl`); operator-tunable network configurability — env-driven NTP / NTS (RFC 8915 authenticated time), DNS with IPv6 / DoH / DoT / cache / lookup timeout, outbound HTTP proxy (`HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`), runtime DPI trust-store CA additions, application-level heartbeats, TCP socket defaults (`b.network`).
@@ -76,8 +76,9 @@ blamejs seed          run | status                                --db <path> --
 blamejs dev           --command <cmd> [--watch <dir>...]
 blamejs api-snapshot  capture | compare                           --file <path>
 blamejs api-key       issue | revoke | list | rotate | verify     --data-dir <path> --namespace <ns>
-blamejs audit         archive | export | verify | purge           --data-dir <path>
+blamejs audit         archive | export | verify-bundle | verify-chain | purge   --data-dir <path>
 blamejs backup        inspect | verify | extract                  --bundle <path>
+blamejs restore       list | inspect | apply | rollback | list-rollbacks         --data-dir <path> --bundle <dir>
 blamejs mtls          status | show-cert | init | issue | issue-p12  --data-dir <path>
 blamejs vault         status | seal | unseal | rotate             --data-dir <path>
 blamejs security      assert                                      --data-dir <path>

package/lib/cli.js

@@ -38,14 +38,18 @@ var fs = require("node:fs");
 var os = require("node:os");
 var path = require("path");
 var apiSnapshot = require("./api-snapshot");
+var auditChain = require("./audit-chain");
 var auditTools = require("./audit-tools");
+var backup = require("./backup");
 var cliHelpers = require("./cli-helpers");
 var constants = require("./constants");
 var crypto = require("./crypto");
 var dev = require("./dev");
 var migrations = require("./migrations");
 var requestHelpers = require("./request-helpers");
+var restore = require("./restore");
 var restoreBundle = require("./restore-bundle");
+var restoreRollback = require("./restore-rollback");
 var seeders = require("./seeders");
 var vaultPassphraseOps = require("./vault/passphrase-ops");
 
@@ -512,6 +516,7 @@ var AUDIT_USAGE = [
   "  archive        Bundle audit rows older than --before into a verified archive",
   "  export         Auditor evidence bundle for a date range",
   "  verify-bundle  Round-trip integrity check on an archive or export bundle",
+  "  verify-chain   Walk the live audit chain end-to-end; reports tampering",
   "  purge          Delete live rows already captured in a verified archive",
   "",
   "Common flags:",
@@ -527,12 +532,17 @@ var AUDIT_USAGE = [
   "  --to <date>            Latest recordedAt (inclusive)",
   "  --action <name>        Restrict to a single audit action",
   "",
+  "verify-chain flags:",
+  "  --db <path>            SQLite database path (required)",
+  "  --table <name>         Audit table name (default audit_log)",
+  "  --max-rows <N>         Stop after walking N rows (default: walk all)",
+  "",
   "purge flags:",
   "  --confirm              REQUIRED — operator acknowledgement of destructive op",
   "",
   "Exit codes:",
-  "  0  success",
-  "  1  operation failed",
+  "  0  success (or chain verified ok)",
+  "  1  operation failed (or chain tampered)",
   "  2  bad invocation",
 ].join("\n");
 
@@ -561,6 +571,7 @@ async function _runAudit(args, ctx) {
   }
   var sub = args.pos[0];
   var passphrase = _resolvePassphrase(args, ctx);
+  // verify-chain reads the live DB, no bundle passphrase needed.
   var passRequired = sub === "archive" || sub === "export" ||
                      sub === "verify-bundle" || sub === "purge";
   if (passRequired && !passphrase) {
@@ -633,6 +644,56 @@ async function _runAudit(args, ctx) {
     }
   }
 
+  if (sub === "verify-chain") {
+    var dbPathV = args.flags.db;
+    if (!dbPathV || dbPathV === true) {
+      _writeLine(ctx.stderr, "blamejs audit verify-chain: --db <path> is required");
+      return 2;
+    }
+    dbPathV = _resolvePath(String(dbPathV), ctx.cwd);
+    var tableV = args.flags.table ? String(args.flags.table) : "audit_log";
+    var maxRows = args.flags["max-rows"];
+    var maxRowsN = maxRows === undefined ? undefined : Number(maxRows);
+    if (maxRowsN !== undefined && (!Number.isFinite(maxRowsN) || maxRowsN < 1)) {
+      _writeLine(ctx.stderr, "blamejs audit verify-chain: --max-rows must be a positive integer");
+      return 2;
+    }
+    var dbV;
+    try { dbV = _openSqlite(dbPathV); }
+    catch (e) {
+      _writeLine(ctx.stderr, "blamejs audit verify-chain: cannot open db at " + dbPathV +
+        ": " + ((e && e.message) || String(e)));
+      return 1;
+    }
+    try {
+      var queryAllAsync = async function (sql, params) {
+        var stmt = dbV.prepare(sql);
+        return Array.isArray(params) ? stmt.all.apply(stmt, params) : stmt.all();
+      };
+      var vc = await auditChain.verifyChain(queryAllAsync, tableV,
+        maxRowsN ? { maxRows: maxRowsN } : {});
+      if (vc.ok) {
+        _writeLine(ctx.stdout, "OK — chain verified" +
+          " (table=" + vc.table +
+          ", rowsVerified=" + vc.rowsVerified + ")");
+        return 0;
+      }
+      _writeLine(ctx.stderr, "FAIL — " + vc.reason +
+        " (table=" + vc.table +
+        ", rowsVerified=" + vc.rowsVerified +
+        ", breakAt=" + vc.breakAt +
+        ", breakRowId=" + vc.breakRowId + ")");
+      _writeLine(ctx.stderr, "  expected prevHash: " + vc.expected);
+      _writeLine(ctx.stderr, "  actual:            " + vc.actual);
+      return 1;
+    } catch (e) {
+      _writeLine(ctx.stderr, "blamejs audit verify-chain: " + ((e && e.message) || String(e)));
+      return 1;
+    } finally {
+      try { dbV.close(); } catch (_e) { /* close best-effort */ }
+    }
+  }
+
   if (sub === "purge") {
     var inP = _resolveOutPath(args.flags.archive || args.flags.in, ctx);
     if (!inP) {
@@ -661,6 +722,282 @@ async function _runAudit(args, ctx) {
   return 2;
 }
 
+// ---- Subcommand: restore ----
+//
+// Operator workflow on top of b.restore: list bundles in storage,
+// inspect a specific one, do a live in-place restore (with rollback
+// preservation), and roll back to a previous restore point. Wraps the
+// restore primitive's run / inspect / list / rollback / list-rollbacks
+// surface; uses b.backup.localStorage as the storage adapter (the same
+// adapter that wrote the bundles).
+//
+// Two ways to identify a bundle for inspect / apply:
+//   --bundle <dir>            point at an extracted bundle directory
+//                             (parent dir is treated as storage root,
+//                              dir basename as bundle id — matches the
+//                              shape `blamejs backup extract` produces)
+//   --storage-root <root> --bundle-id <id>   use a multi-bundle root
+
+var RESTORE_USAGE = [
+  "Usage: blamejs restore <subcommand> [flags]",
+  "",
+  "Subcommands:",
+  "  list              List bundles available in storage",
+  "  inspect           Read a bundle manifest summary (no live changes)",
+  "  apply             Live in-place restore with rollback preserved",
+  "  rollback          Revert the most-recent (or named) restore",
+  "  list-rollbacks    List preserved rollback points",
+  "",
+  "Common flags:",
+  "  --data-dir <path>      Live data directory (apply / rollback / list-rollbacks)",
+  "  --storage-root <path>  Directory containing bundle subdirs (list)",
+  "  --bundle <dir>         Extracted bundle directory (inspect / apply)",
+  "  --bundle-id <id>       Alternative: pass id with --storage-root",
+  "  --rollback-root <path> Override rollback dir (default <data-dir>.rollbacks)",
+  "  --passphrase <string>  Bundle passphrase (or env BLAMEJS_BACKUP_PASSPHRASE)",
+  "",
+  "apply flags:",
+  "  --max-pulled-bytes <N> Refuse a bundle whose pulled bytes exceed N (default 4 GiB)",
+  "  --max-pulled-files <N> Refuse a bundle whose pulled file count exceeds N (default 100K)",
+  "  --no-audit             Suppress audit emission (default ON)",
+  "",
+  "rollback flags:",
+  "  --rollback <pathOrId>  Specific rollback point to restore (default: most recent)",
+  "",
+  "Exit codes:",
+  "  0  success",
+  "  1  operation failed",
+  "  2  bad invocation",
+].join("\n");
+
+// Resolve {storageRoot, bundleId} from either --bundle <dir> OR
+// --storage-root <root> --bundle-id <id>. Returns null + writes an
+// error on the report when neither shape works.
+function _resolveRestoreBundleSelector(args, ctx, report, requireBundle) {
+  var bundleFlag = args.flags.bundle;
+  var storageRootFlag = args.flags["storage-root"];
+  var bundleIdFlag = args.flags["bundle-id"];
+  if (bundleFlag && bundleFlag !== true) {
+    var bundlePath = _resolvePath(String(bundleFlag), ctx.cwd);
+    return {
+      storageRoot: path.dirname(bundlePath),
+      bundleId:    path.basename(bundlePath),
+    };
+  }
+  if (storageRootFlag && storageRootFlag !== true) {
+    var sr = _resolvePath(String(storageRootFlag), ctx.cwd);
+    if (requireBundle) {
+      if (!bundleIdFlag || bundleIdFlag === true) {
+        report.error("--bundle-id is required when using --storage-root", 2);
+        return null;
+      }
+      return { storageRoot: sr, bundleId: String(bundleIdFlag) };
+    }
+    return { storageRoot: sr, bundleId: null };
+  }
+  if (requireBundle) {
+    report.error("--bundle <dir> OR --storage-root <root> --bundle-id <id> is required", 2);
+  } else {
+    report.error("--storage-root <root> is required", 2);
+  }
+  return null;
+}
+
+async function _runRestore(args, ctx) {
+  if (args.pos.length === 0) {
+    return cliHelpers.makeReporter(ctx, "blamejs restore").usage(RESTORE_USAGE);
+  }
+  var sub = args.pos[0];
+  var report = cliHelpers.makeReporter(ctx, "blamejs restore " + sub);
+  if (sub === "help" || args.flags.help || args.flags.h) {
+    return report.helpStdout(RESTORE_USAGE);
+  }
+  if (["list", "inspect", "apply", "rollback", "list-rollbacks"].indexOf(sub) === -1) {
+    cliHelpers.makeReporter(ctx, "blamejs restore").error("unknown subcommand '" + sub + "'", 2);
+    return cliHelpers.makeReporter(ctx, "blamejs restore").usage(RESTORE_USAGE);
+  }
+
+  // list / inspect / apply all need a storage root + (for inspect/apply) a bundle id.
+  // rollback / list-rollbacks only need data-dir.
+  var dataDirFlag = args.flags["data-dir"];
+  function _requireDataDir() {
+    if (!dataDirFlag || dataDirFlag === true) {
+      report.error("--data-dir <path> is required", 2);
+      return null;
+    }
+    return _resolvePath(String(dataDirFlag), ctx.cwd);
+  }
+
+  if (sub === "list") {
+    var sel = _resolveRestoreBundleSelector(args, ctx, report, false);
+    if (!sel) return 2;
+    try {
+      var storage = backup.localStorage({ root: sel.storageRoot });
+      var bundles = await storage.listBundles();
+      if (bundles.length === 0) {
+        report.write("no bundles in " + sel.storageRoot);
+        return report.ok();
+      }
+      report.write("bundles in " + sel.storageRoot + ": " + bundles.length);
+      for (var i = 0; i < bundles.length; i++) {
+        var b = bundles[i];
+        report.write("  " + b.bundleId +
+          "  size=" + (b.size != null ? b.size + "B" : "?") +
+          "  createdAt=" + (b.createdAt || "?"));
+      }
+      return report.ok();
+    } catch (e) {
+      return report.error((e && e.message) || String(e));
+    }
+  }
+
+  if (sub === "inspect") {
+    var selI = _resolveRestoreBundleSelector(args, ctx, report, true);
+    if (!selI) return 2;
+    try {
+      var storageI = backup.localStorage({ root: selI.storageRoot });
+      // restore.create needs a passphrase + dataDir even for inspect because
+      // its closure captures them; pass placeholders since inspect doesn't
+      // touch them.
+      var rI = restore.create({
+        dataDir: path.join(os.tmpdir(), "blamejs-restore-inspect-noop"),
+        storage: storageI,
+        passphrase: "inspect-only-not-used",
+        audit: false,
+      });
+      var manifest = await rI.inspect(selI.bundleId);
+      var totalBytesI = 0;
+      for (var ix = 0; ix < manifest.files.length; ix++) {
+        totalBytesI += manifest.files[ix].encryptedSize || 0;
+      }
+      report.write("bundle:        " + selI.bundleId);
+      report.write("storage root:  " + selI.storageRoot);
+      report.write("manifest:      v" + (manifest.manifestVersion || manifest.version || "unknown"));
+      report.write("created:       " + (manifest.createdAt || "unknown"));
+      report.write("files:         " + manifest.files.length);
+      report.write("encrypted size: " + totalBytesI + " bytes");
+      return report.ok();
+    } catch (e) {
+      return report.error((e && e.message) || String(e));
+    }
+  }
+
+  if (sub === "apply") {
+    var dd = _requireDataDir();
+    if (!dd) return 2;
+    var selA = _resolveRestoreBundleSelector(args, ctx, report, true);
+    if (!selA) return 2;
+    var pp = cliHelpers.resolvePassphrase(args, ctx, {
+      flag: "passphrase", envVar: "BLAMEJS_BACKUP_PASSPHRASE",
+    });
+    if (!pp) {
+      return report.error("--passphrase or BLAMEJS_BACKUP_PASSPHRASE is required", 2);
+    }
+    var rollbackRootA = args.flags["rollback-root"]
+      ? _resolvePath(String(args.flags["rollback-root"]), ctx.cwd) : undefined;
+    var maxBytes = args.flags["max-pulled-bytes"];
+    var maxFiles = args.flags["max-pulled-files"];
+    if (maxBytes !== undefined && (!Number.isFinite(Number(maxBytes)) || Number(maxBytes) <= 0)) {
+      return report.error("--max-pulled-bytes must be a positive number", 2);
+    }
+    if (maxFiles !== undefined && (!Number.isFinite(Number(maxFiles)) || Number(maxFiles) <= 0)) {
+      return report.error("--max-pulled-files must be a positive number", 2);
+    }
+    try {
+      var storageA = backup.localStorage({ root: selA.storageRoot });
+      var rA = restore.create({
+        dataDir:         dd,
+        storage:         storageA,
+        passphrase:      pp,
+        rollbackRoot:    rollbackRootA,
+        audit:           args.flags["no-audit"] !== true,
+        maxPulledBytes:  maxBytes !== undefined ? Number(maxBytes) : undefined,
+        maxPulledFiles:  maxFiles !== undefined ? Number(maxFiles) : undefined,
+      });
+      var summary = await rA.run({ bundleId: selA.bundleId });
+      report.write("OK — restored");
+      report.write("  bundle:       " + summary.bundleId);
+      report.write("  files:        " + summary.fileCount);
+      report.write("  bytes:        " + summary.totalBytes);
+      report.write("  rollback at:  " + summary.rollbackPath);
+      report.write("  duration ms:  " + summary.durationMs);
+      report.write("");
+      report.write("Stop and start the app fresh against " + dd + " to pick up the restored state.");
+      report.write("Roll back with: blamejs restore rollback --data-dir " + dd);
+      return report.ok();
+    } catch (e) {
+      return report.error((e && e.message) || String(e));
+    }
+  }
+
+  if (sub === "rollback") {
+    var ddR = _requireDataDir();
+    if (!ddR) return 2;
+    var rollbackRootR = args.flags["rollback-root"]
+      ? _resolvePath(String(args.flags["rollback-root"]), ctx.cwd)
+      : (ddR + ".rollbacks");
+    var rollbackTarget = args.flags.rollback;
+    var targetPath = null;
+    if (rollbackTarget && rollbackTarget !== true) {
+      // operator can pass either a full path or just the basename inside rollback-root
+      var rt = String(rollbackTarget);
+      targetPath = path.isAbsolute(rt) ? rt : path.resolve(rollbackRootR, rt);
+    } else {
+      // Default to most-recent rollback point (mirrors restore.create().rollback()).
+      var ptsR;
+      try { ptsR = restoreRollback.list({ rollbackRoot: rollbackRootR }); }
+      catch (e) {
+        return report.error("listing rollbacks at " + rollbackRootR + ": " + ((e && e.message) || String(e)));
+      }
+      if (!ptsR || ptsR.length === 0) {
+        return report.error("no rollback points at " + rollbackRootR + " — pass --rollback <pathOrId> explicitly", 2);
+      }
+      targetPath = ptsR[0].rollbackPath;
+    }
+    try {
+      var rR = await restoreRollback.rollback({
+        dataDir:      ddR,
+        rollbackPath: targetPath,
+        rollbackRoot: rollbackRootR,
+      });
+      report.write("OK — rolled back");
+      report.write("  data dir:     " + ddR);
+      report.write("  used:         " + (targetPath || "most-recent rollback point"));
+      report.write("  discarded at: " + (rR.discardedAt || "(unknown)"));
+      return report.ok();
+    } catch (e) {
+      return report.error((e && e.message) || String(e));
+    }
+  }
+
+  if (sub === "list-rollbacks") {
+    var ddL = _requireDataDir();
+    if (!ddL) return 2;
+    var rollbackRootL = args.flags["rollback-root"]
+      ? _resolvePath(String(args.flags["rollback-root"]), ctx.cwd)
+      : (ddL + ".rollbacks");
+    try {
+      var pts = restoreRollback.list({ rollbackRoot: rollbackRootL });
+      if (pts.length === 0) {
+        report.write("no rollback points at " + rollbackRootL);
+        return report.ok();
+      }
+      report.write("rollback points at " + rollbackRootL + ": " + pts.length);
+      for (var p = 0; p < pts.length; p++) {
+        var pt = pts[p];
+        report.write("  " + (pt.rollbackPath || pt) +
+          (pt.recordedAt ? "  recordedAt=" + pt.recordedAt : "") +
+          (pt.bundleId ? "  bundleId=" + pt.bundleId : ""));
+      }
+      return report.ok();
+    } catch (e) {
+      return report.error((e && e.message) || String(e));
+    }
+  }
+
+  return 2;
+}
+
 // ---- Top-level help ----
 
 // ---- Subcommand: api-key ----
@@ -1860,6 +2197,7 @@ var TOP_USAGE = [
   "  api-key           Issue / revoke / list / rotate / verify API keys for a namespace",
   "  audit             Operator tooling on top of the audit chain (archive / export / verify / purge)",
   "  backup            Inspect / verify / extract a backup bundle from disk",
+  "  restore           Live in-place restore from a bundle (list / inspect / apply / rollback / list-rollbacks)",
   "  mtls              Inspect or generate the in-box mTLS CA + leaf certs (status / show-cert / init / issue / issue-p12)",
   "  vault             Seal / unseal / rotate the on-disk vault keypair (plaintext ↔ wrapped)",
   "  security          Run b.security.assertProduction against the live framework",
@@ -1919,6 +2257,7 @@ async function main(argv, opts) {
     if (subTopic === "api-key")      { _writeLine(ctx.stdout, API_KEY_USAGE);      return 0; }
     if (subTopic === "audit")        { _writeLine(ctx.stdout, AUDIT_USAGE);        return 0; }
     if (subTopic === "backup")       { _writeLine(ctx.stdout, BACKUP_USAGE);       return 0; }
+    if (subTopic === "restore")      { _writeLine(ctx.stdout, RESTORE_USAGE);      return 0; }
     if (subTopic === "mtls")         { _writeLine(ctx.stdout, MTLS_USAGE);         return 0; }
     if (subTopic === "vault")        { _writeLine(ctx.stdout, VAULT_USAGE);        return 0; }
     if (subTopic === "security")     { _writeLine(ctx.stdout, SECURITY_USAGE);     return 0; }
@@ -1940,6 +2279,7 @@ async function main(argv, opts) {
   if (cmd === "api-key")      return await _runApiKey(rest, ctx);
   if (cmd === "audit")        return await _runAudit(rest, ctx);
   if (cmd === "backup")       return await _runBackup(rest, ctx);
+  if (cmd === "restore")      return await _runRestore(rest, ctx);
   if (cmd === "mtls")         return await _runMtls(rest, ctx);
   if (cmd === "vault")        return await _runVault(rest, ctx);
   if (cmd === "security")     return await _runSecurity(rest, ctx);
@@ -1966,6 +2306,7 @@ module.exports = {
   API_KEY_USAGE:       API_KEY_USAGE,
   AUDIT_USAGE:         AUDIT_USAGE,
   BACKUP_USAGE:        BACKUP_USAGE,
+  RESTORE_USAGE:       RESTORE_USAGE,
   MTLS_USAGE:          MTLS_USAGE,
   VAULT_USAGE:         VAULT_USAGE,
 };

package/lib/framework-error.js

@@ -118,6 +118,13 @@ function defineClass(name, opts) {
 var ObjectStoreError      = defineClass("ObjectStoreError",      { withStatusCode: true });
 var LogStreamError        = defineClass("LogStreamError",        { withStatusCode: true });
 var QueueError            = defineClass("QueueError");
+// RedisError covers transport (CONNECT/CONNECT_TIMEOUT/SOCKET/WRITE),
+// protocol parsing (PROTOCOL/BAD_URL/BAD_OPTS), command-level
+// (REDIS_REPLY/COMMAND_TIMEOUT), and lifecycle (CLOSED/RECONNECT_GAVE_UP).
+// Transient by default — operators wrap calls in retry/breaker. Bad-opts
+// and bad-URL paths surface as alwaysPermanent code names so retry sees
+// them and skips immediately rather than hammering a misconfig.
+var RedisError            = defineClass("RedisError");
 var ExternalDbError       = defineClass("ExternalDbError");
 var ClusterError          = defineClass("ClusterError");
 var ClusterProviderError  = defineClass("ClusterProviderError");
@@ -173,6 +180,7 @@ module.exports = {
   ObjectStoreError:       ObjectStoreError,
   LogStreamError:         LogStreamError,
   QueueError:             QueueError,
+  RedisError:             RedisError,
   ExternalDbError:        ExternalDbError,
   ClusterError:           ClusterError,
   ClusterProviderError:   ClusterProviderError,