chore(services): remove BullMQ vaporware, reframe cluster packages as Redis-free-first

.changeset/cluster-pkg-cleanup.md

@@ -0,0 +1,4 @@
+---
+---
+
+chore(services): remove BullMQ vaporware + reframe cluster packages Redis-first → Redis-free. Deletes a throw-only `BullMQQueueAdapter` stub (every method raised "not yet implemented (M10.43)"; no external consumers) and corrects misleading docs in service-queue/service-cluster/service-cluster-redis. No functional change to any working code path — empty changeset, no package version impact.

packages/services/service-cluster-redis/README.md

@@ -0,0 +1,59 @@
+# @objectstack/service-cluster-redis
+
+Redis driver for `@objectstack/service-cluster` — implements the cluster
+primitives `IPubSub` / `ILock` / `IKV` / `ICounter` against Redis using
+[`ioredis`](https://github.com/redis/ioredis).
+
+## Status: community-optional reference driver
+
+This package is the **reference remote driver** that proves the
+`registerClusterDriver()` SPI. It is **not** on the ObjectStack Cloud or
+ObjectOS EE deployment path — both run **Redis-free** (single-node-affinity
+routing + DB-backed queue/coordination). It is maintained as long as the
+cluster driver SPI is stable, but it is **not operated or supported by
+ObjectStack** as part of the managed/enterprise runtime.
+
+Reach for it only when you self-host **multiple replicas that must share
+cluster primitives** with low latency — e.g. sub-second cross-process pub/sub
+or high-frequency cross-process locks. For most deployments the default
+`memory` driver (single process) or the DB-backed queue is sufficient; see
+`@objectstack/service-cluster` for when a remote driver is actually needed.
+
+## Installation
+
+```bash
+pnpm add @objectstack/service-cluster @objectstack/service-cluster-redis ioredis
+```
+
+## Usage
+
+Importing the package once at process start self-registers the `'redis'`
+driver, which `defineCluster({ driver: 'redis' })` then resolves.
+
+```typescript
+import { ObjectKernel } from '@objectstack/core';
+import { ClusterServicePlugin } from '@objectstack/service-cluster';
+import '@objectstack/service-cluster-redis'; // self-registers the 'redis' driver
+
+const kernel = new ObjectKernel();
+kernel.use(new ClusterServicePlugin({
+  config: {
+    driver: 'redis',
+    url: process.env.REDIS_URL ?? 'redis://localhost:6379',
+    nodeId: 'web-1',
+  },
+}));
+await kernel.bootstrap();
+```
+
+You can also build the service directly with `defineCluster({ driver: 'redis', url, nodeId })`,
+or pass a shared ioredis client via `driverOptions.client`.
+
+## License
+
+Apache-2.0. See [LICENSING.md](../../../LICENSING.md).
+
+## See Also
+
+- [@objectstack/service-cluster](../service-cluster) — primitives, SPI, and the
+  default in-process `memory` driver

packages/services/service-cluster/src/index.ts

@@ -4,9 +4,19 @@
  * @objectstack/service-cluster
  *
  * Pluggable cluster primitives (PubSub / Lock / KV / Counter) for
- * ObjectStack. The default `memory` driver is exported here; remote
- * drivers (postgres/redis/nats) ship as sibling packages and register
- * themselves via `registerClusterDriver()`.
+ * ObjectStack. The default `memory` driver is exported here and is the
+ * only driver needed for single-process runtimes.
+ *
+ * A remote driver is required only when running multiple processes that
+ * must share these primitives. Remote drivers ship as sibling packages
+ * and register via `registerClusterDriver()`; `@objectstack/service-cluster-redis`
+ * is the reference remote driver. (Postgres/NATS drivers are not built —
+ * add one on demand against the same SPI.)
+ *
+ * NOTE: the `memory` driver is per-process. Running multiple replicas on
+ * the memory driver silently splits state (each process holds its own
+ * locks/counters; pub/sub does not fan out across processes). Use a
+ * remote driver for any multi-replica deployment.
  *
  * See `content/docs/concepts/cluster-semantics.mdx` for the protocol.
  */