@reddb-io/cli 1.23.2 → 1.24.0

package/README.md

@@ -357,12 +357,15 @@ Same storage format. Start embedded, scale to server, expose to agents — zero
 
 ## ⚡ Performance
 
-> **Where RedDB wins:** benchmarks show measurable wins over Postgres and Mongo today:
->
-> - `typed_insert` — **16× faster** than PostgreSQL on typed single-row inserts
-> - `disk_usage` — **1.5× faster** than MongoDB on compact-write workloads
->
-> See [`docs/perf/wins.md`](docs/perf/wins.md) for reproducible benchmarks and [`docs/perf/when-not-reddb.md`](docs/perf/when-not-reddb.md) for the honest gaps where we're still behind.
+> **Performance evidence:** the April/May 2026 results in
+> [`docs/perf/wins.md`](docs/perf/wins.md) are historical and have not been
+> revalidated against the current SDK paths. In particular, the old
+> `typed_insert` label does not establish sequential single-row latency.
+> [Issue #2270](https://github.com/reddb-io/reddb/issues/2270) and the
+> [September competitive audit](.red/researches/2026-09-07-reddb-surrealdb-competitive-audit.md)
+> document current diagnostic evidence and the remaining gaps.
+> [ADR 0076](.red/adr/0076-competitive-leadership-evidence-gate.md) requires
+> equivalent guarantees and a demonstrated 20% margin before claiming a lead.
 
 RedDB uses multiple optimization techniques for fast queries at scale:
 

package/drivers/js/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@reddb-io/sdk",
-  "version": "1.23.2",
-  "description": "Official embedded RedDB SDK — launches a local red binary over stdio JSON-RPC. Use @reddb-io/client for remote HTTP, gRPC, and RedWire.",
+  "version": "1.24.0",
+  "description": "Official embedded RedDB SDK — launches a local red binary over stdio JSON-RPC. The binary arrives as a per-platform optionalDependency — no install script. Use @reddb-io/client for remote HTTP, gRPC, and RedWire.",
   "type": "module",
   "main": "src/index.js",
   "exports": {
@@ -14,13 +14,11 @@
   "files": [
     "src/",
     "index.d.ts",
-    "postinstall.js",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "postinstall": "node postinstall.js",
-    "test": "node --test test/ask.test.mjs test/cache.test.mjs test/db-helpers.test.mjs test/embedded-only.test.mjs test/helpers.test.mjs test/insert-ids.test.mjs test/kv.test.mjs test/params.test.mjs test/postinstall.test.mjs test/queue.test.mjs test/redwire.params.test.mjs test/transaction.test.mjs test/url.test.mjs && node test/smoke.test.mjs && node test/conformance.test.mjs && node test/readme-examples.test.mjs"
+    "test": "node --test test/ask.test.mjs test/cache.test.mjs test/db-helpers.test.mjs test/embedded-only.test.mjs test/helpers.test.mjs test/insert-ids.test.mjs test/kv.test.mjs test/params.test.mjs test/platform-binary.test.mjs test/native-engine.test.mjs test/queue.test.mjs test/redwire.params.test.mjs test/transaction.test.mjs test/url.test.mjs && node test/smoke.test.mjs && node test/conformance.test.mjs && node test/readme-examples.test.mjs"
   },
   "engines": {
     "node": ">=18"

package/drivers/js/src/binary.js

@@ -4,7 +4,8 @@
  * SDK lookup (`resolveSdkBinary`):
  *   1. `REDDB_BIN` env var (the canonical override per ADR 0006).
  *   2. `REDDB_BINARY_PATH` env var (legacy alias, deprecation window).
- *   3. `<package>/bin/red[.exe]` — where postinstall.js dropped it.
+ *   3. The `@reddb-io/red-<platform>` package npm installed for this host
+ *      (see `platform-binary.js`).
  *   4. Otherwise throw an actionable error.
  *
  *   PATH is **never** consulted. The wire-format coupling between the
@@ -13,19 +14,12 @@
  *
  * CLI lookup (`resolveCliBinary`):
  *   1. `REDDB_BIN` env var.
- *   2. `<package>/bin/red[.exe]`.
+ *   2. The `@reddb-io/red-<platform>` package.
  *   3. PATH-resolved bare `red[.exe]` — appropriate for the CLI which
  *      *targets* PATH.
  */
 
-import { existsSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
-import { dirname, resolve, join } from 'node:path'
-
-import { resolveBin } from './internal/bin-resolver/index.js'
-
-const HERE = dirname(fileURLToPath(import.meta.url))
-const PACKAGE_ROOT = resolve(HERE, '..')
+import { platformPackageNames, resolvePlatformBinary } from './platform-binary.js'
 
 function defaultBinaryName() {
   if (typeof process !== 'undefined' && process.platform === 'win32') {
@@ -36,15 +30,27 @@ function defaultBinaryName() {
 
 /** SDK runtime lookup. Throws actionable error when binary cannot be located. */
 export function resolveSdkBinary() {
+  const override = process.env?.REDDB_BIN
+  if (typeof override === 'string' && override !== '') {
+    return override
+  }
   const legacy = process.env?.REDDB_BINARY_PATH
-  if (typeof legacy === 'string' && legacy !== '' && !process.env?.REDDB_BIN) {
+  if (typeof legacy === 'string' && legacy !== '') {
     return legacy
   }
-  return resolveBin({
-    name: defaultBinaryName(),
-    packageRoot: PACKAGE_ROOT,
-    envVar: 'REDDB_BIN',
-  })
+  const packaged = resolvePlatformBinary()
+  if (packaged) {
+    return packaged
+  }
+  const wanted = platformPackageNames()[0]
+  throw new Error(
+    `reddb: binary "${defaultBinaryName()}" not found.\n` +
+      `  expected:    the ${wanted} package (an optionalDependency of @reddb-io/sdk)\n` +
+      `  override:    set REDDB_BIN=/path/to/${defaultBinaryName()}\n` +
+      `  fix:         reinstall without --no-optional / --omit=optional, and make sure\n` +
+      `               ${process.platform}/${process.arch} is a supported platform;\n` +
+      `               or build it: cargo build --release --bin red`,
+  )
 }
 
 /** CLI runtime lookup. Allowed to fall back to PATH per ADR 0006. */
@@ -53,14 +59,5 @@ export function resolveCliBinary() {
   if (typeof override === 'string' && override !== '') {
     return override
   }
-  const local = join(PACKAGE_ROOT, 'bin', defaultBinaryName())
-  if (existsSync(local)) {
-    return local
-  }
-  return defaultBinaryName()
-}
-
-/** Used by postinstall.js to know where to drop the downloaded binary. */
-export function packageBinaryDir() {
-  return join(PACKAGE_ROOT, 'bin')
+  return resolvePlatformBinary() ?? defaultBinaryName()
 }

package/drivers/js/src/cache.js

@@ -2,13 +2,9 @@
  * Cache client — exposes cache.{get,put,exists,invalidate,invalidatePrefix,
  * invalidateTags,flushNamespace} via the underlying HTTP transport.
  *
- * NOTE: These methods require server-side HTTP endpoints under /cache/ns/*.
- * flushNamespace routes to the existing POST /admin/blob_cache/flush_namespace.
- * All others target endpoints planned for a future server release.
- *
- * Requires an HTTP or gRPC transport. On embedded (stdio JSON-RPC), every
- * method throws `UNSUPPORTED_TRANSPORT` before issuing the RPC call —
- * the engine's stdio handler doesn't implement `cache.*`.
+ * The HTTP data-plane endpoints under /cache/ns/* authorize the caller's
+ * tenant and cache namespace. Invalidation is local to the addressed server.
+ * Use the HTTP transport for remote cache operations.
  *
  * Values are base64-encoded in transit so binary payloads survive JSON.
  */
@@ -123,7 +119,7 @@ export class CacheClient {
 
   /**
    * Remove all entries in a namespace.
-   * Routes to POST /admin/blob_cache/flush_namespace (live endpoint).
+   * Uses the caller-scoped POST /cache/ns/:namespace/flush endpoint.
    * @param {string} namespace
    * @returns {Promise<void>}
    */

package/drivers/js/src/config.js

@@ -62,5 +62,5 @@ function keyedValueLiteral(value) {
 }
 
 function keyedStringLiteral(value) {
-  return `'${String(value).replace(/'/g, "''")}'`
+  return `'${String(value).replace(/\\/g, '\\\\').replace(/'/g, "''")}'`
 }

package/drivers/js/src/db-helpers.js

@@ -91,5 +91,5 @@ function sqlIdentifier(value) {
 }
 
 function sqlString(value) {
-  return `'${String(value).replace(/'/g, "''")}'`
+  return `'${String(value).replace(/\\/g, '\\\\').replace(/'/g, "''")}'`
 }

package/drivers/js/src/documents.js

@@ -127,5 +127,5 @@ function sqlValueLiteral(value) {
 }
 
 function sqlString(value) {
-  return `'${String(value).replace(/'/g, "''")}'`
+  return `'${String(value).replace(/\\/g, '\\\\').replace(/'/g, "''")}'`
 }

package/drivers/js/src/http.js

@@ -27,8 +27,8 @@
  *   cache.exists            → GET    /cache/ns/:ns/:key/exists
  *   cache.invalidate        → DELETE /cache/ns/:ns/:key
  *   cache.invalidate_prefix → DELETE /cache/ns/:ns?prefix=...
- *   cache.invalidate_tags   → DELETE /cache/ns/:ns/tags  (body: {tags})
- *   cache.flush_namespace   → POST   /admin/blob_cache/flush_namespace
+ *   cache.invalidate_tags   → POST   /cache/ns/:ns/invalidate-tags (body: {tags})
+ *   cache.flush_namespace   → POST   /cache/ns/:ns/flush
  *
  * Auth: every request after construction carries `Authorization:
  * Bearer <token>` (when set). `setToken(token)` updates it in
@@ -195,11 +195,11 @@ const ROUTES = {
     init: { method: 'DELETE' },
   }),
   'cache.invalidate_tags': (base, { namespace, tags }) => ({
-    url: `${base}/cache/ns/${encodeURIComponent(namespace)}/tags`,
-    init: { method: 'DELETE', body: JSON.stringify({ tags }) },
+    url: `${base}/cache/ns/${encodeURIComponent(namespace)}/invalidate-tags`,
+    init: { method: 'POST', body: JSON.stringify({ tags }) },
   }),
   'cache.flush_namespace': (base, { namespace }) => ({
-    url: `${base}/admin/blob_cache/flush_namespace`,
-    init: { method: 'POST', body: JSON.stringify({ namespace }) },
+    url: `${base}/cache/ns/${encodeURIComponent(namespace)}/flush`,
+    init: { method: 'POST' },
   }),
 }

package/drivers/js/src/index.js

@@ -19,6 +19,7 @@
  */
 
 import { spawnRed } from './spawn.js'
+import { NativeRpcClient, openNativeEngine, resolveNativeAddon } from './native-engine.js'
 import { resolveSdkBinary } from './binary.js'
 import { RpcClient, RedDBError } from './protocol.js'
 import { parseUri } from './url.js'
@@ -83,6 +84,15 @@ export async function connect(uri, options = {}) {
         'auth is only meaningful for remote connections; embedded modes inherit caller privileges.',
       )
     }
+    // In-process addon when one is installed for this host (and the caller
+    // did not ask for a specific binary); otherwise the `red rpc --stdio`
+    // subprocess. Both serve the same JSON-RPC protocol.
+    const addon = options.binary ? null : resolveNativeAddon()
+    if (addon) {
+      const client = new NativeRpcClient(openNativeEngine(parsed.path || undefined, addon))
+      await client.call('version', {})
+      return new RedDB(client, { transport: 'embedded' })
+    }
     const args = embeddedArgs(parsed)
     const binary = options.binary ?? resolveSdkBinary()
     const child = await spawnRed(binary, args)

package/drivers/js/src/kv.js

@@ -120,16 +120,16 @@ function kvIdentifier(value) {
 function kvKeySegment(value) {
   const key = String(value)
   if (/^[A-Za-z0-9_]+$/.test(key)) return key
-  return `'${key.replace(/'/g, "''")}'`
+  return `'${key.replace(/\\/g, '\\\\').replace(/'/g, "''")}'`
 }
 
 function kvValueLiteral(value) {
   if (typeof value === 'number' || typeof value === 'boolean') return String(value)
   if (value == null) return 'NULL'
-  if (typeof value === 'object') return `'${JSON.stringify(value).replace(/'/g, "''")}'`
-  return `'${String(value).replace(/'/g, "''")}'`
+  if (typeof value === 'object') return `'${JSON.stringify(value).replace(/\\/g, '\\\\').replace(/'/g, "''")}'`
+  return `'${String(value).replace(/\\/g, '\\\\').replace(/'/g, "''")}'`
 }
 
 function kvTagLiteral(value) {
-  return `'${String(value).replace(/'/g, "''")}'`
+  return `'${String(value).replace(/\\/g, '\\\\').replace(/'/g, "''")}'`
 }

package/drivers/js/src/native-engine.js

@@ -0,0 +1,120 @@
+/**
+ * In-process embedded engine (the `reddb.node` Node addon).
+ *
+ * Embedded mode used to spawn `red rpc --stdio` and speak JSON-RPC over the
+ * child's pipes. The addon serves the same protocol — same methods, same
+ * transaction/cursor semantics — as a function call, so there is no
+ * subprocess and no separate `red` binary involved.
+ *
+ * The addon ships inside the `@reddb-io/red-<platform>` package next to
+ * `bin/red` (see `platform-binary.js` for how that package is found).
+ * `REDDB_NATIVE_ADDON=/path/to/reddb.node` overrides the lookup.
+ */
+
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+
+import { RedDBError } from './protocol.js'
+import { platformPackageNames } from './platform-binary.js'
+
+const require = createRequire(import.meta.url)
+
+/**
+ * @returns {string | null} path to `reddb.node`, or null when no addon is
+ *   installed for this host.
+ */
+export function resolveNativeAddon({
+  resolve = (id) => require.resolve(id),
+  env = process.env,
+  names = platformPackageNames(),
+} = {}) {
+  const override = env.REDDB_NATIVE_ADDON
+  if (typeof override === 'string' && override !== '') return override
+  for (const name of names) {
+    let manifest
+    try {
+      manifest = resolve(`${name}/package.json`)
+    } catch {
+      continue
+    }
+    const addon = join(dirname(manifest), 'reddb.node')
+    if (existsSync(addon)) return addon
+  }
+  return null
+}
+
+/**
+ * Open an embedded engine through the addon.
+ * @param {string | undefined} path database file, or undefined for in-memory
+ * @param {string} addonPath
+ */
+export function openNativeEngine(path, addonPath) {
+  const { Engine } = require(addonPath)
+  return Engine.open(path)
+}
+
+/**
+ * JSON-RPC client over an in-process engine. Same surface as `RpcClient`
+ * (`call`, `close`), so `RedDB` cannot tell the transports apart.
+ *
+ * Requests are chained so they reach the engine in call order even when the
+ * caller does not await each one: the engine's thread pool would otherwise
+ * be free to reorder them, which a transaction (`tx.begin`, then writes)
+ * must never see. The stdio pipe gave this ordering for free.
+ */
+export class NativeRpcClient {
+  /** @param {{ call(request: string): Promise<string>, close(): void }} engine */
+  constructor(engine) {
+    this.engine = engine
+    this.nextId = 1
+    this.closed = false
+    this.closeReason = null
+    this.tail = Promise.resolve()
+  }
+
+  call(method, params = {}) {
+    if (this.closed) {
+      return Promise.reject(
+        new RedDBError('CLIENT_CLOSED', `client is closed: ${this.closeReason ?? 'unknown'}`),
+      )
+    }
+    const id = this.nextId++
+    const request = JSON.stringify({ jsonrpc: '2.0', id, method, params })
+    const run = this.tail.then(() => this.engine.call(request))
+    this.tail = run.then(
+      () => undefined,
+      () => undefined,
+    )
+    return run.then((line) => {
+      const envelope = JSON.parse(line)
+      if (method === 'close') this.#shutdown('close requested')
+      if (envelope.error) {
+        throw new RedDBError(
+          envelope.error.code ?? 'UNKNOWN',
+          envelope.error.message ?? 'unknown error',
+          envelope.error.data,
+        )
+      }
+      return envelope.result
+    })
+  }
+
+  /** Send `close` (discarding any open transaction), then release the file lock. */
+  async close() {
+    if (this.closed) return
+    try {
+      await this.call('close', {})
+    } catch {
+      // best effort — the engine may already be shut down
+    }
+    this.#shutdown('close requested')
+    this.engine.close()
+  }
+
+  #shutdown(reason) {
+    if (this.closed) return
+    this.closed = true
+    this.closeReason = reason
+  }
+}

package/drivers/js/src/platform-binary.js

@@ -0,0 +1,62 @@
+/**
+ * Locate the `red` binary shipped as a per-platform npm package.
+ *
+ * `@reddb-io/cli` and `@reddb-io/sdk` declare every `@reddb-io/red-<key>`
+ * package as an `optionalDependency`; the package manager installs only the
+ * one matching the host's `os` / `cpu` / `libc`, so there is no install
+ * script and no download. `<key>` is `<process.platform>-<process.arch>`,
+ * plus `-musl` for the static Linux builds. `scripts/npm-platform-packages.mjs`
+ * owns the publish side; a contract test keeps the two key tables identical.
+ */
+
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+
+const require = createRequire(import.meta.url)
+
+/** `glibc` | `musl` on Linux, `null` elsewhere. */
+export function detectLibc(platform = process.platform) {
+  if (platform !== 'linux') return null
+  const header = process.report?.getReport?.()?.header
+  return header?.glibcVersionRuntime ? 'glibc' : 'musl'
+}
+
+/**
+ * Package names to try, best match first. On Linux the other libc variant is
+ * a fallback: package managers that ignore `libc` install both, and the
+ * static (musl) binary runs on glibc hosts too.
+ */
+export function platformPackageNames({
+  platform = process.platform,
+  arch = process.arch,
+  libc = detectLibc(platform),
+} = {}) {
+  const base = `@reddb-io/red-${platform}-${arch}`
+  if (platform !== 'linux') return [base]
+  return libc === 'musl' ? [`${base}-musl`, base] : [base, `${base}-musl`]
+}
+
+/**
+ * @returns {string | null} absolute path to the binary, or null when no
+ *   platform package for this host is installed.
+ */
+export function resolvePlatformBinary({
+  platform = process.platform,
+  arch = process.arch,
+  libc = detectLibc(platform),
+  resolve = (id) => require.resolve(id),
+} = {}) {
+  const binName = platform === 'win32' ? 'red.exe' : 'red'
+  for (const name of platformPackageNames({ platform, arch, libc })) {
+    let manifest
+    try {
+      manifest = resolve(`${name}/package.json`)
+    } catch {
+      continue
+    }
+    const binary = join(dirname(manifest), 'bin', binName)
+    if (existsSync(binary)) return binary
+  }
+  return null
+}

package/drivers/js/src/queue.js

@@ -127,7 +127,7 @@ function queueValueLiteral(value) {
 }
 
 function queueStringLiteral(value) {
-  return `'${String(value).replace(/'/g, "''")}'`
+  return `'${String(value).replace(/\\/g, '\\\\').replace(/'/g, "''")}'`
 }
 
 function queuePayloads(result) {

package/drivers/js/src/vault.js

@@ -23,9 +23,13 @@ export class VaultClient {
   }
 
   unseal(key, options = {}) {
+    return this.reveal(key, options)
+  }
+
+  reveal(key, options = {}) {
     const collection = options.collection ?? this.collection
     return this.client.call('query', {
-      sql: `UNSEAL VAULT ${keyedIdentifier(collection)}.${keyedIdentifier(key)}`,
+      sql: `VAULT REVEAL ${keyedIdentifier(collection)}.${keyedIdentifier(key)}`,
     })
   }
 }
@@ -54,5 +58,5 @@ function keyedValueLiteral(value) {
 }
 
 function keyedStringLiteral(value) {
-  return `'${String(value).replace(/'/g, "''")}'`
+  return `'${String(value).replace(/\\/g, '\\\\').replace(/'/g, "''")}'`
 }

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "@reddb-io/cli",
-  "version": "1.23.2",
-  "description": "CLI launcher for RedDB. The JS/TS app driver is published as @reddb-io/sdk.",
+  "version": "1.24.0",
+  "description": "CLI launcher for RedDB. The red binary arrives as a per-platform optionalDependency (no install script). The JS/TS app driver is published as @reddb-io/sdk.",
   "type": "commonjs",
   "bin": {
     "reddb-cli": "./drivers/js/src/cli.js"
   },
   "files": [
     "drivers/js/src/",
-    "drivers/js/cli-postinstall.js",
     "drivers/js/package.json"
   ],
   "engines": {
@@ -34,8 +33,17 @@
     "@changesets/changelog-github": "^0.7.0",
     "@changesets/cli": "^2.31.0"
   },
+  "optionalDependencies": {
+    "@reddb-io/red-linux-x64": "1.24.0",
+    "@reddb-io/red-linux-x64-musl": "1.24.0",
+    "@reddb-io/red-linux-arm64": "1.24.0",
+    "@reddb-io/red-linux-arm64-musl": "1.24.0",
+    "@reddb-io/red-linux-arm": "1.24.0",
+    "@reddb-io/red-darwin-x64": "1.24.0",
+    "@reddb-io/red-darwin-arm64": "1.24.0",
+    "@reddb-io/red-win32-x64": "1.24.0"
+  },
   "scripts": {
-    "postinstall": "node drivers/js/cli-postinstall.js",
     "test": "node scripts/docs-analytics-boundaries.test.mjs && node --test scripts/connection-quality.test.mjs && node drivers/js/test/smoke.test.mjs",
     "typecheck": "cargo check --workspace --locked",
     "lint": "cargo fmt --all -- --check && cargo clippy --workspace --locked -- -D warnings",

package/drivers/js/cli-postinstall.js

@@ -1,150 +0,0 @@
-/**
- * cli-postinstall.js — install/upgrade/skip for `@reddb-io/cli`.
- *
- * Asymmetry vs SDK postinstall (`drivers/js/postinstall.js`):
- *   - SDK always downloads — wire format is version-coupled to the driver.
- *   - CLI compares this package's version against `red --version` on PATH:
- *       absent  → install
- *       older   → upgrade (overwrite + one-line log)
- *       equal   → skip
- *       newer   → skip ("PATH binary is newer; leaving in place")
- *       garbage → install (warn, treat as absent)
- *
- * See ADR 0007 for the rationale.
- *
- * Override hooks (env vars):
- *   REDDB_SKIP_POSTINSTALL=1      do nothing
- *   REDDB_BIN=/path/to/red        skip — caller already has a binary
- *   REDDB_POSTINSTALL_VERSION=…   pull a different release tag
- *   REDDB_POSTINSTALL_REPO=…      pull from a fork (default: reddb-io/reddb)
- */
-
-import { createRequire } from 'node:module'
-import { fileURLToPath } from 'node:url'
-import { dirname, join, sep } from 'node:path'
-import { existsSync, mkdirSync, writeFileSync, chmodSync } from 'node:fs'
-import { execSync } from 'node:child_process'
-
-import { fetchReleaseAsset } from './src/internal/asset-fetcher/index.js'
-import { compareInstalled } from './src/internal/version-compare/index.js'
-
-const HERE = dirname(fileURLToPath(import.meta.url))
-const require = createRequire(import.meta.url)
-// CLI manifest lives at the repo root (../../package.json), and that is the
-// `@reddb-io/cli` package — not the SDK manifest next to this file.
-const pkg = require('../../package.json')
-
-const DEFAULT_REPO = 'reddb-io/reddb'
-
-if (process.env.REDDB_SKIP_POSTINSTALL === '1') {
-  process.stdout.write('reddb-cli: postinstall skipped (REDDB_SKIP_POSTINSTALL=1)\n')
-  process.exit(0)
-}
-
-if (typeof process.env.REDDB_BIN === 'string' && process.env.REDDB_BIN !== '') {
-  process.stdout.write(
-    `reddb-cli: postinstall skipped (REDDB_BIN=${process.env.REDDB_BIN})\n`,
-  )
-  process.exit(0)
-}
-
-// Workspace-local install detection — see the matching block in
-// drivers/js/postinstall.js for the rationale.
-if (!HERE.includes(`${sep}node_modules${sep}`)) {
-  process.stdout.write(
-    'reddb-cli: skipping postinstall — running from a workspace checkout (no node_modules/).\n' +
-    '          Build `red` locally if you need it:\n' +
-    '            cargo build --release --bin red\n' +
-    '            export REDDB_BIN="$PWD/target/release/red"\n' +
-    '          Set REDDB_SKIP_POSTINSTALL=1 to silence this message.\n',
-  )
-  process.exit(0)
-}
-
-main().catch((err) => {
-  process.stderr.write(formatFailure(err))
-  process.exit(0)
-})
-
-function formatFailure(err) {
-  const repo = process.env.REDDB_POSTINSTALL_REPO || DEFAULT_REPO
-  if (err && err.code === 'UNSUPPORTED_PLATFORM') {
-    return (
-      `reddb-cli: no prebuilt red binary for ${process.platform}/${process.arch}.\n` +
-      `          Options:\n` +
-      `            - build from source: https://github.com/${repo}#build-from-source\n` +
-      `            - or set REDDB_BIN=/path/to/red.\n`
-    )
-  }
-  if (err && err.code === 'ASSET_NOT_FOUND') {
-    return (
-      `reddb-cli: release asset not found at ${err.url}\n` +
-      `          The GitHub Release for this CLI version likely has not been\n` +
-      `          published yet. To unblock:\n` +
-      `            1. Use the installer (latest stable red on PATH):\n` +
-      `                 curl -fsSL https://raw.githubusercontent.com/${repo}/main/install.sh | bash\n` +
-      `            2. Or pull a specific tag and rebuild:\n` +
-      `                 REDDB_POSTINSTALL_VERSION=v1.0.5 npm rebuild @reddb-io/cli\n` +
-      `            3. Or point the launcher at an existing binary:\n` +
-      `                 export REDDB_BIN=/path/to/red\n` +
-      `          Releases: https://github.com/${repo}/releases\n`
-    )
-  }
-  return (
-    `reddb-cli: postinstall could not download the binary (${err && err.message}).\n` +
-    `          The package itself still installs. To use the CLI:\n` +
-    `            - run the installer: curl -fsSL https://raw.githubusercontent.com/${repo}/main/install.sh | bash\n` +
-    `            - or download manually from https://github.com/${repo}/releases\n` +
-    `            - or set REDDB_BIN=/path/to/red.\n`
-  )
-}
-
-async function main() {
-  const verdict = compareInstalled({
-    packageVersion: pkg.version,
-    exec: () => execSync('red --version', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }),
-  })
-
-  if (verdict.action === 'skip') {
-    process.stdout.write(`reddb-cli: ${verdict.reason} — skipping download\n`)
-    return
-  }
-
-  const repo = process.env.REDDB_POSTINSTALL_REPO || DEFAULT_REPO
-  const tag = process.env.REDDB_POSTINSTALL_VERSION
-    ? normalizeTag(process.env.REDDB_POSTINSTALL_VERSION)
-    : `v${pkg.version}`
-
-  const binDir = join(HERE, 'bin')
-  const binaryPath = join(binDir, defaultBinaryName())
-
-  if (verdict.action === 'install') {
-    process.stdout.write(`reddb-cli: ${verdict.reason} — installing red ${tag}\n`)
-  } else {
-    // upgrade
-    process.stdout.write(`reddb-cli: ${verdict.reason} — upgrading red to ${tag}\n`)
-  }
-
-  const body = await fetchReleaseAsset({
-    repo,
-    tag,
-    platform: process.platform,
-    arch: process.arch,
-    binName: 'red',
-  })
-  mkdirSync(binDir, { recursive: true })
-  writeFileSync(binaryPath, body)
-  if (process.platform !== 'win32') {
-    chmodSync(binaryPath, 0o755)
-  }
-  process.stdout.write(`reddb-cli: installed binary at ${binaryPath}\n`)
-}
-
-function defaultBinaryName() {
-  return process.platform === 'win32' ? 'red.exe' : 'red'
-}
-
-function normalizeTag(value) {
-  const v = String(value).trim()
-  return v.startsWith('v') ? v : `v${v}`
-}

package/drivers/js/src/internal/asset-fetcher/asset-name.js

@@ -1,37 +0,0 @@
-/**
- * Resolve the GitHub release asset filename for a given Node
- * `process.platform` / `process.arch` pair and binary base name.
- *
- * Mapping is the existing scheme from `drivers/js/postinstall.js`:
- *   linux  + x64       → <bin>-linux-x86_64
- *   linux  + arm64     → <bin>-linux-aarch64
- *   linux  + arm/armv7l→ <bin>-linux-armv7
- *   darwin + x64       → <bin>-macos-x86_64
- *   darwin + arm64     → <bin>-macos-aarch64
- *   win32  + x64       → <bin>-windows-x86_64.exe
- *
- * Throws `UnsupportedPlatformError` for any other combination.
- */
-
-export class UnsupportedPlatformError extends Error {
-  constructor(platform, arch) {
-    super(`unsupported platform/arch combination: ${platform}/${arch}`)
-    this.name = 'UnsupportedPlatformError'
-    this.code = 'UNSUPPORTED_PLATFORM'
-    this.platform = platform
-    this.arch = arch
-  }
-}
-
-export function composeAssetName({ platform, arch, binName }) {
-  if (typeof binName !== 'string' || binName === '') {
-    throw new TypeError('composeAssetName: `binName` must be a non-empty string')
-  }
-  if (platform === 'linux' && arch === 'x64') return `${binName}-linux-x86_64`
-  if (platform === 'linux' && arch === 'arm64') return `${binName}-linux-aarch64`
-  if (platform === 'linux' && (arch === 'arm' || arch === 'armv7l')) return `${binName}-linux-armv7`
-  if (platform === 'darwin' && arch === 'x64') return `${binName}-macos-x86_64`
-  if (platform === 'darwin' && arch === 'arm64') return `${binName}-macos-aarch64`
-  if (platform === 'win32' && arch === 'x64') return `${binName}-windows-x86_64.exe`
-  throw new UnsupportedPlatformError(platform, arch)
-}

package/drivers/js/src/internal/asset-fetcher/checksum.js

@@ -1,23 +0,0 @@
-import { createHash } from 'node:crypto'
-
-export class ChecksumMismatchError extends Error {
-  constructor(expected, actual) {
-    super(`checksum mismatch: expected sha256=${expected}, got sha256=${actual}`)
-    this.name = 'ChecksumMismatchError'
-    this.code = 'CHECKSUM_MISMATCH'
-    this.expected = expected
-    this.actual = actual
-  }
-}
-
-export function sha256Hex(buf) {
-  return createHash('sha256').update(buf).digest('hex')
-}
-
-export function verifySha256(buf, expected) {
-  const expectedNorm = String(expected).trim().toLowerCase()
-  const actual = sha256Hex(buf)
-  if (actual !== expectedNorm) {
-    throw new ChecksumMismatchError(expectedNorm, actual)
-  }
-}

package/drivers/js/src/internal/asset-fetcher/download.js

@@ -1,89 +0,0 @@
-import { request as httpsRequest } from 'node:https'
-import { request as httpRequest } from 'node:http'
-
-const MAX_REDIRECTS = 5
-
-export class AssetNotFoundError extends Error {
-  constructor(url) {
-    super(`asset not found (HTTP 404) at ${url}`)
-    this.name = 'AssetNotFoundError'
-    this.code = 'ASSET_NOT_FOUND'
-    this.url = url
-  }
-}
-
-export class HttpError extends Error {
-  constructor(status, url) {
-    super(`HTTP ${status} fetching ${url}`)
-    this.name = 'HttpError'
-    this.code = 'HTTP_ERROR'
-    this.status = status
-    this.url = url
-  }
-}
-
-export class TooManyRedirectsError extends Error {
-  constructor(url) {
-    super(`too many redirects (>${MAX_REDIRECTS}) starting at ${url}`)
-    this.name = 'TooManyRedirectsError'
-    this.code = 'TOO_MANY_REDIRECTS'
-    this.url = url
-  }
-}
-
-function pickRequest(url) {
-  return url.startsWith('http://') ? httpRequest : httpsRequest
-}
-
-function resolveLocation(currentUrl, location) {
-  if (/^https?:\/\//i.test(location)) return location
-  return new URL(location, currentUrl).toString()
-}
-
-export function downloadFollowingRedirects(url, { userAgent, originalUrl } = {}, depth = 0) {
-  const startUrl = originalUrl || url
-  if (depth > MAX_REDIRECTS) {
-    return Promise.reject(new TooManyRedirectsError(startUrl))
-  }
-  const request = pickRequest(url)
-  return new Promise((resolve, reject) => {
-    const req = request(
-      url,
-      {
-        method: 'GET',
-        headers: {
-          'User-Agent': userAgent || 'reddb-internal-asset-fetcher',
-          Accept: 'application/octet-stream',
-        },
-      },
-      (res) => {
-        const status = res.statusCode || 0
-        if (status >= 300 && status < 400 && res.headers.location) {
-          res.resume()
-          const next = resolveLocation(url, res.headers.location)
-          downloadFollowingRedirects(next, { userAgent, originalUrl: startUrl }, depth + 1).then(
-            resolve,
-            reject,
-          )
-          return
-        }
-        if (status === 404) {
-          res.resume()
-          reject(new AssetNotFoundError(startUrl))
-          return
-        }
-        if (status < 200 || status >= 300) {
-          res.resume()
-          reject(new HttpError(status, url))
-          return
-        }
-        const chunks = []
-        res.on('data', (chunk) => chunks.push(chunk))
-        res.on('end', () => resolve(Buffer.concat(chunks)))
-        res.on('error', reject)
-      },
-    )
-    req.on('error', reject)
-    req.end()
-  })
-}

package/drivers/js/src/internal/asset-fetcher/index.js

@@ -1,52 +0,0 @@
-/**
- * @reddb-io/internal-asset-fetcher — fetch a `red`/`red_client` binary
- * from a GitHub release.
- *
- * Public surface: one function.
- *
- *   fetchReleaseAsset({ repo, tag, platform, arch, binName, sha256? }) → Buffer
- *
- * Steps:
- *   1. Map (platform, arch, binName) → asset filename.
- *   2. Compose the GitHub download URL: `https://github.com/<repo>/releases/download/<tag>/<asset>`.
- *   3. Follow up to 5 redirects, returning the final body as a Buffer.
- *   4. If `sha256` was supplied, verify before returning.
- *
- * Errors carry distinct `.code` values so callers can differentiate:
- *   - UNSUPPORTED_PLATFORM   — no asset for this platform/arch
- *   - ASSET_NOT_FOUND        — HTTP 404 (release/tag/asset name wrong)
- *   - CHECKSUM_MISMATCH      — body downloaded but sha256 mismatched
- *   - HTTP_ERROR             — any other non-2xx status
- *   - TOO_MANY_REDIRECTS     — redirect chain longer than 5 hops
- *
- * Internal modules (`./asset-name.js`, `./download.js`, `./checksum.js`)
- * are not part of the public contract — only `fetchReleaseAsset` is.
- * They are imported directly in tests for focused coverage.
- */
-
-import { composeAssetName } from './asset-name.js'
-import { downloadFollowingRedirects } from './download.js'
-import { verifySha256 } from './checksum.js'
-
-export async function fetchReleaseAsset({ repo, tag, platform, arch, binName, sha256 } = {}) {
-  if (typeof repo !== 'string' || repo === '') {
-    throw new TypeError('fetchReleaseAsset: `repo` must be a non-empty string (e.g. "reddb-io/reddb")')
-  }
-  if (typeof tag !== 'string' || tag === '') {
-    throw new TypeError('fetchReleaseAsset: `tag` must be a non-empty string (e.g. "v0.2.9")')
-  }
-  if (typeof platform !== 'string' || platform === '') {
-    throw new TypeError('fetchReleaseAsset: `platform` must be a non-empty string')
-  }
-  if (typeof arch !== 'string' || arch === '') {
-    throw new TypeError('fetchReleaseAsset: `arch` must be a non-empty string')
-  }
-
-  const assetName = composeAssetName({ platform, arch, binName })
-  const url = `https://github.com/${repo}/releases/download/${tag}/${assetName}`
-  const body = await downloadFollowingRedirects(url)
-  if (sha256) {
-    verifySha256(body, sha256)
-  }
-  return body
-}

package/drivers/js/src/internal/bin-resolver/index.js

@@ -1,57 +0,0 @@
-/**
- * @reddb-io/internal-bin-resolver — runtime lookup for a pinned binary.
- *
- * Precedence:
- *   1. `process.env[envVar]` if set and non-empty → returned verbatim.
- *      No existence probe: the env var is the user's "I know what I'm
- *      doing" override.
- *   2. `<packageRoot>/bin/<name>` if it exists.
- *   3. Otherwise throw an actionable error naming the env var, the
- *      expected local path, and a one-line `pnpm install` hint.
- *
- * `PATH` is deliberately never consulted. SDK/client wire formats are
- * version-coupled to the binary; silent fallback to a stale `PATH`
- * binary fails as misframed RPC, not "command not found". See ADR 0006.
- */
-
-import { existsSync } from 'node:fs'
-import { join } from 'node:path'
-
-/**
- * @param {{ name: string, packageRoot: string, envVar: string }} opts
- * @returns {string} absolute path to the binary
- * @throws {Error} when neither env override nor local binary is usable
- */
-export function resolveBin(opts) {
-  if (!opts || typeof opts !== 'object') {
-    throw new TypeError('resolveBin: options object required')
-  }
-  const { name, packageRoot, envVar } = opts
-  if (typeof name !== 'string' || name === '') {
-    throw new TypeError('resolveBin: `name` must be a non-empty string')
-  }
-  if (typeof packageRoot !== 'string' || packageRoot === '') {
-    throw new TypeError('resolveBin: `packageRoot` must be a non-empty string')
-  }
-  if (typeof envVar !== 'string' || envVar === '') {
-    throw new TypeError('resolveBin: `envVar` must be a non-empty string')
-  }
-
-  const override = process.env?.[envVar]
-  if (typeof override === 'string' && override !== '') {
-    return override
-  }
-
-  const local = join(packageRoot, 'bin', name)
-  if (existsSync(local)) {
-    return local
-  }
-
-  throw new Error(
-    `reddb: binary "${name}" not found.\n` +
-      `  expected at: ${local}\n` +
-      `  override:    set ${envVar}=/path/to/${name}\n` +
-      `  fix:         re-run \`pnpm install\` (the postinstall script downloads it),\n` +
-      `               or check the postinstall log for a download error.`,
-  )
-}

package/drivers/js/src/internal/version-compare/index.js

@@ -1,163 +0,0 @@
-/**
- * @reddb-io/internal-version-compare — install/upgrade/skip verdict for
- * the CLI postinstall.
- *
- * Asymmetry vs SDK/client (per ADR 0006):
- *   - SDK/client postinstalls *always* download a pinned binary because
- *     the wire format is version-coupled to the driver.
- *   - The CLI is a launcher. Users typically already have `red` on PATH
- *     and would resent each `npm i -g @reddb-io/cli` re-downloading.
- *     We compare versions and only fetch when strictly newer.
- *
- * Verdict table:
- *   exec throws                            → action='install'  (no binary detected)
- *   exec returns unparseable output        → action='install'  (warn, fetch fresh)
- *   PATH version  <  packageVersion        → action='upgrade'
- *   PATH version  >= packageVersion        → action='skip'
- *
- * Prerelease ordering follows semver 2.0.0 §11: a normal release ranks
- * above any prerelease of the same MAJOR.MINOR.PATCH.
- */
-
-const SEMVER_RE = /\b(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?\b/
-
-/**
- * Extract a semver-shaped version string from arbitrary `red --version`
- * output. Accepts `reddb 0.2.9`, bare `0.2.9`, or `red 1.0.0-rc.1`.
- *
- * @param {string} text
- * @returns {string|null} normalised `MAJOR.MINOR.PATCH[-prerelease]` or null
- */
-export function parseVersion(text) {
-  if (typeof text !== 'string') return null
-  const m = text.match(SEMVER_RE)
-  if (!m) return null
-  const [, maj, min, pat, pre] = m
-  return pre ? `${maj}.${min}.${pat}-${pre}` : `${maj}.${min}.${pat}`
-}
-
-/**
- * semver 2.0.0 ordering. Returns -1 / 0 / 1.
- *
- * Throws TypeError if either side is not parseable — this is a
- * programmer error, not a runtime fallback path.
- */
-export function compareSemver(a, b) {
-  const pa = parseVersion(a)
-  const pb = parseVersion(b)
-  if (pa === null) throw new TypeError(`compareSemver: invalid version "${a}"`)
-  if (pb === null) throw new TypeError(`compareSemver: invalid version "${b}"`)
-
-  const [coreA, preA] = splitCore(pa)
-  const [coreB, preB] = splitCore(pb)
-
-  for (let i = 0; i < 3; i++) {
-    if (coreA[i] !== coreB[i]) return coreA[i] < coreB[i] ? -1 : 1
-  }
-
-  // Cores equal — apply §11: no-prerelease ranks above any prerelease.
-  if (preA === null && preB === null) return 0
-  if (preA === null) return 1
-  if (preB === null) return -1
-
-  return comparePrerelease(preA, preB)
-}
-
-function splitCore(v) {
-  const dash = v.indexOf('-')
-  const core = dash === -1 ? v : v.slice(0, dash)
-  const pre = dash === -1 ? null : v.slice(dash + 1)
-  const parts = core.split('.').map((n) => Number(n))
-  return [parts, pre]
-}
-
-function comparePrerelease(a, b) {
-  const sa = a.split('.')
-  const sb = b.split('.')
-  const len = Math.min(sa.length, sb.length)
-  for (let i = 0; i < len; i++) {
-    const c = compareIdentifier(sa[i], sb[i])
-    if (c !== 0) return c
-  }
-  if (sa.length === sb.length) return 0
-  return sa.length < sb.length ? -1 : 1
-}
-
-function compareIdentifier(a, b) {
-  const aNum = /^\d+$/.test(a)
-  const bNum = /^\d+$/.test(b)
-  if (aNum && bNum) {
-    const na = Number(a)
-    const nb = Number(b)
-    return na === nb ? 0 : na < nb ? -1 : 1
-  }
-  if (aNum) return -1 // numeric < alphanumeric per §11
-  if (bNum) return 1
-  return a === b ? 0 : a < b ? -1 : 1
-}
-
-/**
- * Decide what the CLI postinstall should do.
- *
- * @param {{ packageVersion: string, exec: () => string }} opts
- *   `exec` is called with no arguments and is expected to return the
- *   stdout of `red --version` (sync). It may throw — that signals "no
- *   PATH binary detected" and routes to action='install'.
- * @returns {{ action: 'install'|'upgrade'|'skip', reason: string }}
- */
-export function compareInstalled(opts) {
-  if (!opts || typeof opts !== 'object') {
-    throw new TypeError('compareInstalled: options object required')
-  }
-  const { packageVersion, exec } = opts
-  if (typeof packageVersion !== 'string' || packageVersion === '') {
-    throw new TypeError('compareInstalled: `packageVersion` must be a non-empty string')
-  }
-  if (typeof exec !== 'function') {
-    throw new TypeError('compareInstalled: `exec` must be a function')
-  }
-  if (parseVersion(packageVersion) === null) {
-    throw new TypeError(`compareInstalled: \`packageVersion\` "${packageVersion}" is not parseable semver`)
-  }
-
-  let raw
-  try {
-    raw = exec()
-  } catch (err) {
-    return {
-      action: 'install',
-      reason: `no PATH \`red\` binary detected (${err.message || 'exec failed'})`,
-    }
-  }
-
-  const installed = parseVersion(typeof raw === 'string' ? raw : '')
-  if (installed === null) {
-    return {
-      action: 'install',
-      reason: `unparseable PATH \`red --version\` output (${truncate(String(raw))})`,
-    }
-  }
-
-  const cmp = compareSemver(installed, packageVersion)
-  if (cmp < 0) {
-    return {
-      action: 'upgrade',
-      reason: `PATH \`red\` ${installed} is older than package ${packageVersion}`,
-    }
-  }
-  if (cmp > 0) {
-    return {
-      action: 'skip',
-      reason: `PATH \`red\` ${installed} is newer than package ${packageVersion}`,
-    }
-  }
-  return {
-    action: 'skip',
-    reason: `PATH \`red\` already at ${installed}`,
-  }
-}
-
-function truncate(s) {
-  const oneLine = s.replace(/\s+/g, ' ').trim()
-  return oneLine.length > 80 ? `${oneLine.slice(0, 77)}...` : oneLine
-}