@objectstack/service-cluster-redis 17.0.0-rc.0 → 17.0.0-rc.1

package/CHANGELOG.md

@@ -1,5 +1,212 @@
 # @objectstack/service-cluster-redis
 
+## 17.0.0-rc.1
+
+### Patch Changes
+
+- 2e836de: chore(packaging): CHANGELOG.md ships in every npm tarball (#4261)
+
+  The AGENTS.md post-task checklist requires breaking changesets to carry their
+  FROM → TO migration because "this text ships to consumers as `CHANGELOG.md`
+  inside the npm package and is what an upgrading agent greps after the tombstone
+  error." That delivery path was severed for 68 of the 69 publishable packages:
+  npm packs `package.json` / `README*` / `LICENSE*` unconditionally but — unlike
+  older npm versions — not `CHANGELOG.md`, and the canonical
+  `"files": ["dist", "README.md"]` whitelist never named it. Measured on npm
+  10.9.7: `npm pack --dry-run` on `@objectstack/types` shipped 3 files while its
+  70KB `CHANGELOG.md` stayed behind. Only `@objectstack/spec` listed it
+  explicitly.
+
+  The tombstone-error scenario is precisely the one where the repo is out of
+  reach — the upgrading agent has `node_modules` and nothing else — so the
+  migration text has to ride in the tarball. Every publishable package now
+  declares `CHANGELOG.md` in `files`, and the canonical whitelist is
+  `["dist", "README.md", "CHANGELOG.md"]`.
+
+  The other half is the gate: `check:published-files` gains a fifth invariant,
+  COMPLETE — a whitelist that fails to cover `CHANGELOG.md` fails the
+  always-required lint job, so the next package cannot silently sever the path
+  again. `@objectstack/spec`'s per-package EXTRA_ENTRIES exemption dissolves
+  into the canonical set.
+
+  Consumer-visible change: one more file per install (the package's changelog,
+  e.g. 70.8KB for `@objectstack/types`), and `grep -r "removed key"
+node_modules/@objectstack/*/CHANGELOG.md` now finds the migration it was
+  promised.
+
+- cc2de0e: chore(packaging): 20 packages stop publishing their sources, tests and build tooling (#4248)
+
+  These 20 packages declared no `files` field, so npm fell back to packing the
+  whole package directory. `npm pack --dry-run` on `@objectstack/plugin-webhooks`
+  listed **21 files** — 15 under `src/`, three of them unit tests
+  (`auto-enqueuer.test.ts`, `bootstrap-declared-webhooks.test.ts`, …), plus the
+  build-time `scripts/i18n-extract.config.ts`. `dist/` lands on top of that at
+  publish time rather than instead of it, so consumers were installing the
+  TypeScript sources and the test suite alongside the artifact they asked for.
+
+  Each now declares `"files": ["dist", "README.md"]`, matching the 29 packages
+  that already did. Nothing a consumer imports moves: every `main` / `types` /
+  `exports` target in all 20 already resolved inside `dist/`, which the new
+  `check:published-files` guard verifies rather than assumes. The visible change
+  is a smaller install and a smaller dependency-scanning surface — `npm pack` on
+  `@objectstack/plugin-webhooks` now yields 2 files plus `dist/`.
+
+  The other half of the fix is the gate. Half the packages declaring `files` and
+  half not was the #3786 shape — a hand-copied convention with nothing enforcing
+  it, where whoever forgets the line gets no signal at all. `check:published-files`
+  (new, wired into the always-required `lint` job) holds every non-private
+  workspace package to four invariants: `files` is **declared**; it is
+  **sufficient** (covers every entry point, so tightening a whitelist cannot ship
+  a package that fails to resolve); it is **minimal** (admits no test, test-harness
+  config or build script); and anything beyond `dist` + `README.md` is
+  **registered** with a reason, reconciled in both directions so a stale exemption
+  is an error rather than dead text. `@objectstack/spec` is the one package with
+  registered extras — its `.zod.ts` sources, JSON Schemas, liveness ledgers and
+  `CHANGELOG.md` are product, not build input.
+
+  This also closes an assumption #4206 was resting on. Excluding `<pkg>/scripts/**`
+  from the docs-drift implementation test is sound only while no package publishes
+  `scripts/` as runtime code; that held, but it held because someone read all three
+  offenders by hand. It is now checked on every PR.
+
+- Updated dependencies [6a67d7a]
+- Updated dependencies [0ecc656]
+- Updated dependencies [06772eb]
+- Updated dependencies [270650f]
+- Updated dependencies [3aef718]
+- Updated dependencies [1ea6bce]
+- Updated dependencies [c1dcacd]
+- Updated dependencies [ad303ed]
+- Updated dependencies [32ccb23]
+- Updated dependencies [f5a4ef0]
+- Updated dependencies [2d3e255]
+- Updated dependencies [7d7521f]
+- Updated dependencies [5dc4d02]
+- Updated dependencies [05154a1]
+- Updated dependencies [9b6fe7c]
+- Updated dependencies [8c711fb]
+- Updated dependencies [09e4547]
+- Updated dependencies [91f4c78]
+- Updated dependencies [820eff9]
+- Updated dependencies [8d895ff]
+- Updated dependencies [f6472d7]
+- Updated dependencies [78caf51]
+- Updated dependencies [62a789b]
+- Updated dependencies [789ad63]
+- Updated dependencies [2af1988]
+- Updated dependencies [2e836de]
+- Updated dependencies [12a19a8]
+- Updated dependencies [41dcda3]
+- Updated dependencies [c8124e5]
+- Updated dependencies [a1a4140]
+- Updated dependencies [217e2e6]
+- Updated dependencies [86a71d1]
+- Updated dependencies [d5c75e2]
+- Updated dependencies [03d26f7]
+- Updated dependencies [4384921]
+- Updated dependencies [3c628ce]
+- Updated dependencies [7cb922e]
+- Updated dependencies [1d22114]
+- Updated dependencies [b5f9397]
+- Updated dependencies [ed77493]
+- Updated dependencies [58a03d2]
+- Updated dependencies [dc530b4]
+- Updated dependencies [e59786e]
+- Updated dependencies [bcf1112]
+- Updated dependencies [9774b78]
+- Updated dependencies [b07d829]
+- Updated dependencies [a648e96]
+- Updated dependencies [a47ac06]
+- Updated dependencies [e4c61a7]
+- Updated dependencies [cc60165]
+- Updated dependencies [081aa6f]
+- Updated dependencies [91f4c78]
+- Updated dependencies [e8d0c21]
+- Updated dependencies [c1d44f7]
+- Updated dependencies [ab9fb5c]
+- Updated dependencies [f985b3f]
+- Updated dependencies [9a4932a]
+- Updated dependencies [f9fc874]
+- Updated dependencies [011b386]
+- Updated dependencies [7777e8f]
+- Updated dependencies [507b92a]
+- Updated dependencies [7309c81]
+- Updated dependencies [20bc1ec]
+- Updated dependencies [90c2b15]
+- Updated dependencies [42eeb7d]
+- Updated dependencies [01e124d]
+- Updated dependencies [7ce02eb]
+- Updated dependencies [a13827e]
+- Updated dependencies [7733604]
+- Updated dependencies [40e420f]
+- Updated dependencies [d13004a]
+- Updated dependencies [be7360c]
+- Updated dependencies [cc2de0e]
+- Updated dependencies [5b47ab5]
+- Updated dependencies [b09d8d9]
+- Updated dependencies [b09d8d9]
+- Updated dependencies [8675db6]
+- Updated dependencies [b09d8d9]
+- Updated dependencies [3eb1b2b]
+- Updated dependencies [59b85c0]
+- Updated dependencies [6e357ed]
+- Updated dependencies [d6938bf]
+- Updated dependencies [31e0be9]
+- Updated dependencies [4bfd455]
+- Updated dependencies [ffd2ce2]
+- Updated dependencies [62f8017]
+- Updated dependencies [a831df1]
+- Updated dependencies [f752ee3]
+- Updated dependencies [a1b61e0]
+- Updated dependencies [cd6b9f2]
+- Updated dependencies [2cb6d3c]
+- Updated dependencies [af2a095]
+- Updated dependencies [ec796d5]
+- Updated dependencies [e87fea1]
+- Updated dependencies [c65e529]
+- Updated dependencies [3ca34c1]
+- Updated dependencies [239c3a3]
+- Updated dependencies [94a0bbc]
+- Updated dependencies [d6bfb3d]
+- Updated dependencies [a2266a6]
+- Updated dependencies [d25a0ec]
+- Updated dependencies [667b83e]
+- Updated dependencies [627b188]
+- Updated dependencies [8d4eae7]
+- Updated dependencies [65a3a84]
+- Updated dependencies [ccd9397]
+- Updated dependencies [bca935b]
+- Updated dependencies [c54c822]
+- Updated dependencies [8dcc0f5]
+- Updated dependencies [75b9e51]
+- Updated dependencies [0a2f233]
+- Updated dependencies [8621cdd]
+- Updated dependencies [6f23667]
+- Updated dependencies [5d21a48]
+- Updated dependencies [19365b7]
+- Updated dependencies [b7ed26d]
+- Updated dependencies [b3a3d83]
+- Updated dependencies [7a55913]
+- Updated dependencies [35accbf]
+- Updated dependencies [6038de7]
+- Updated dependencies [eb95d97]
+- Updated dependencies [e4c2dc8]
+- Updated dependencies [1bd2795]
+- Updated dependencies [8186a70]
+- Updated dependencies [a329cca]
+- Updated dependencies [6eec18c]
+- Updated dependencies [4d7bebf]
+- Updated dependencies [821ac7a]
+- Updated dependencies [8f81731]
+- Updated dependencies [8b50cb3]
+- Updated dependencies [8c2db68]
+- Updated dependencies [22b5e54]
+- Updated dependencies [0166bd5]
+- Updated dependencies [9b702dc]
+- Updated dependencies [ab16331]
+  - @objectstack/spec@17.0.0-rc.1
+  - @objectstack/service-cluster@17.0.0-rc.1
+
 ## 17.0.0-rc.0
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/service-cluster-redis",
-  "version": "17.0.0-rc.0",
+  "version": "17.0.0-rc.1",
   "license": "Apache-2.0",
   "description": "Redis cluster driver for ObjectStack — implements IPubSub/ILock/IKV/ICounter against Redis using ioredis.",
   "type": "module",
@@ -15,8 +15,8 @@
   },
   "dependencies": {
     "ioredis": "^5.11.1",
-    "@objectstack/service-cluster": "17.0.0-rc.0",
-    "@objectstack/spec": "17.0.0-rc.0"
+    "@objectstack/service-cluster": "17.0.0-rc.1",
+    "@objectstack/spec": "17.0.0-rc.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",
@@ -38,8 +38,14 @@
     "url": "https://github.com/objectstack-ai/objectstack.git",
     "directory": "packages/services/service-cluster-redis"
   },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "scripts": {
     "build": "tsup",
-    "test": "vitest run"
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   }
 }

package/.turbo/turbo-build.log

@@ -1,22 +0,0 @@
-
-> @objectstack/service-cluster-redis@17.0.0-rc.0 build /home/runner/work/objectstack/objectstack/packages/services/service-cluster-redis
-> tsup
-
-CLI Building entry: src/index.ts
-CLI Using tsconfig: tsconfig.json
-CLI tsup v8.5.1
-CLI Using tsup config: /home/runner/work/objectstack/objectstack/packages/services/service-cluster-redis/tsup.config.ts
-CLI Target: es2020
-CLI Cleaning output folder
-ESM Build start
-CJS Build start
-ESM dist/index.js     13.20 KB
-ESM dist/index.js.map 37.77 KB
-ESM ⚡️ Build success in 733ms
-CJS dist/index.cjs     14.57 KB
-CJS dist/index.cjs.map 35.25 KB
-CJS ⚡️ Build success in 740ms
-DTS Build start
-DTS ⚡️ Build success in 10919ms
-DTS dist/index.d.ts  9.99 KB
-DTS dist/index.d.cts 9.99 KB

package/src/client.ts

@@ -1,75 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { Redis, type RedisOptions } from 'ioredis';
-
-/**
- * Options accepted by {@link createRedisClient}.
- *
- * Either pass `url` (e.g. `redis://user:pass@host:6379/0`) or a full
- * ioredis `options` bag. The two are merged with `options` taking
- * precedence so callers can override individual fields parsed from the
- * URL.
- *
- * This factory is intended to be the single Redis-client construction
- * point across ObjectStack — `service-cluster-redis` uses it for the
- * driver, and `service-cache` will eventually share the same connection
- * pool via {@link CreateRedisOptions.existing}.
- */
-export interface CreateRedisOptions {
-    /** Connection URL. Ignored when `existing` is provided. */
-    url?: string;
-    /** Extra ioredis options merged on top of `url`. */
-    options?: RedisOptions;
-    /**
-     * Bring-your-own client. When provided, this exact instance is
-     * returned and `url`/`options` are ignored — useful for sharing one
-     * pool across cluster + cache.
-     */
-    existing?: Redis;
-    /**
-     * If true, the returned client is created in lazyConnect mode so the
-     * TCP connection happens on first command rather than at construction.
-     * Default: true (matches ObjectStack's "fail at usage, not boot" stance).
-     */
-    lazyConnect?: boolean;
-}
-
-/**
- * Construct (or reuse) an ioredis client with ObjectStack defaults.
- *
- * Defaults applied when `existing` is absent:
- *   - `lazyConnect: true` — don't crash boot if Redis is briefly down
- *   - `maxRetriesPerRequest: 3` — bound the failure window before surfacing
- *   - `enableAutoPipelining: true` — modest throughput boost for batch workloads
- *
- * @example
- *   const client = createRedisClient({ url: 'redis://localhost:6379' });
- *
- * @example reuse one pool across services
- *   const shared = createRedisClient({ url });
- *   const clusterClient = createRedisClient({ existing: shared });
- *   const cacheClient   = createRedisClient({ existing: shared });
- */
-export function createRedisClient(opts: CreateRedisOptions = {}): Redis {
-    if (opts.existing) return opts.existing;
-
-    const base: RedisOptions = {
-        lazyConnect: opts.lazyConnect ?? true,
-        maxRetriesPerRequest: 3,
-        enableAutoPipelining: true,
-    };
-
-    if (opts.url) {
-        return new Redis(opts.url, { ...base, ...opts.options });
-    }
-    return new Redis({ ...base, ...opts.options });
-}
-
-/**
- * Duplicate a Redis client so that pub/sub commands (which monopolize
- * the connection) don't block regular commands. Mirrors the standard
- * ioredis "two clients" pattern.
- */
-export function duplicateForPubSub(client: Redis): Redis {
-    return client.duplicate();
-}

package/src/counter.ts

@@ -1,63 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-import type { Redis } from 'ioredis';
-import type { ICounter, CounterIncrOptions } from '@objectstack/spec/contracts';
-
-export interface RedisCounterOptions {
-    client: Redis;
-    keyPrefix?: string;
-}
-
-/**
- * Redis-backed monotonic counter using INCRBY. Each counter key lives at
- * `{prefix}ctr:{key}` so the same Redis instance can host multiple
- * tenants without collision.
- *
- * Values are stored as ASCII decimals (Redis convention). We surface
- * them as `bigint` to match the contract — INCRBY accepts up to a
- * signed 64-bit range, well beyond Number.MAX_SAFE_INTEGER.
- */
-export class RedisCounter implements ICounter {
-    private readonly client: Redis;
-    private readonly keyPrefix: string;
-    private closed = false;
-
-    constructor(opts: RedisCounterOptions) {
-        this.client = opts.client;
-        this.keyPrefix = opts.keyPrefix ?? 'os:';
-    }
-
-    async incr(key: string, opts: CounterIncrOptions = {}): Promise<bigint> {
-        if (this.closed) throw new Error('RedisCounter is closed');
-        const by = opts.by ?? 1;
-        const next = await this.client.incrby(this.ctrKey(key), by);
-        return BigInt(next);
-    }
-
-    async peek(key: string): Promise<bigint> {
-        const raw = await this.client.get(this.ctrKey(key));
-        if (raw === null) return 0n;
-        try {
-            return BigInt(raw);
-        } catch {
-            return 0n;
-        }
-    }
-
-    async reset(key: string, value: bigint = 0n): Promise<void> {
-        if (this.closed) throw new Error('RedisCounter is closed');
-        if (value === 0n) {
-            await this.client.del(this.ctrKey(key));
-            return;
-        }
-        await this.client.set(this.ctrKey(key), value.toString());
-    }
-
-    async close(): Promise<void> {
-        this.closed = true;
-    }
-
-    private ctrKey(key: string): string {
-        return `${this.keyPrefix}ctr:${key}`;
-    }
-}

package/src/index.ts

@@ -1,111 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * @objectstack/service-cluster-redis
- *
- * Redis driver for `@objectstack/service-cluster`. Import this package
- * once at process start to register the `'redis'` driver:
- *
- * ```ts
- * import '@objectstack/service-cluster-redis';
- * import { defineCluster } from '@objectstack/service-cluster';
- *
- * const cluster = defineCluster({
- *     driver: 'redis',
- *     url: 'redis://localhost:6379',
- *     nodeId: 'web-1',
- * });
- * ```
- *
- * The driver also exports raw constructors so callers who already own
- * an ioredis client can compose primitives by hand.
- */
-
-import type { Redis } from 'ioredis';
-import {
-    ComposedClusterService,
-    registerClusterDriver,
-    type DriverFactoryConfig,
-} from '@objectstack/service-cluster';
-import { createRedisClient } from './client.js';
-import { RedisPubSub } from './pubsub.js';
-import { RedisLock } from './lock.js';
-import { RedisKV } from './kv.js';
-import { RedisCounter } from './counter.js';
-
-// Re-exports for advanced composition.
-export { createRedisClient, duplicateForPubSub, type CreateRedisOptions } from './client.js';
-export { RedisPubSub, type RedisPubSubOptions } from './pubsub.js';
-export { RedisLock, type RedisLockOptions } from './lock.js';
-export { RedisKV, VersionMismatchError, type RedisKVOptions } from './kv.js';
-export { RedisCounter, type RedisCounterOptions } from './counter.js';
-
-/**
- * Driver-specific options accepted under `driverOptions` in
- * `ClusterCapabilityConfig`. All are optional — supply a `client` to
- * share a Redis pool with other services (e.g. `service-cache`).
- */
-export interface RedisDriverOptions {
-    /** Pre-built ioredis client. When provided, `url` is ignored. */
-    client?: Redis;
-    /** Key prefix applied to every Redis key (default: 'os:'). */
-    keyPrefix?: string;
-    /** Default lock TTL in ms. Overridden by `LockAcquireOptions.ttlMs`. */
-    lockTtlMs?: number;
-    /** Pub/sub subscriber error sink. */
-    onError?: (err: unknown, channel: string) => void;
-}
-
-/**
- * Factory consumed by `defineCluster({ driver: 'redis' })`. Builds an
- * `IClusterService` backed by Redis. Owns the underlying ioredis client
- * iff it created it (i.e. when caller didn't pass `driverOptions.client`).
- */
-function redisDriverFactory(config: DriverFactoryConfig) {
-    const driverOpts = (config.driverOptions ?? {}) as RedisDriverOptions;
-    const ownsClient = !driverOpts.client;
-    const client =
-        driverOpts.client ??
-        createRedisClient({ url: config.url });
-
-    const keyPrefix = driverOpts.keyPrefix ?? 'os:';
-    const ttlMs = config.lockTtlMs ?? driverOpts.lockTtlMs;
-
-    const pubsub = new RedisPubSub({
-        client,
-        nodeId: config.nodeId,
-        keyPrefix,
-        onError: driverOpts.onError,
-    });
-    const lock = new RedisLock({
-        client,
-        keyPrefix,
-        defaultTtlMs: ttlMs,
-        nodeId: config.nodeId,
-    });
-    const kv = new RedisKV({ client, keyPrefix });
-    const counter = new RedisCounter({ client, keyPrefix });
-
-    const facade = new ComposedClusterService(
-        config.nodeId,
-        'redis',
-        pubsub,
-        lock,
-        kv,
-        counter,
-    );
-
-    // Wrap close() so we also tear down the publisher client if we own it.
-    const originalClose = facade.close.bind(facade);
-    facade.close = async () => {
-        await originalClose();
-        if (ownsClient) {
-            try { await client.quit(); } catch { /* swallow */ }
-        }
-    };
-
-    return facade;
-}
-
-// Module-load registration — importing this package is enough.
-registerClusterDriver('redis', redisDriverFactory);

package/src/kv.ts

@@ -1,187 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-import type { Redis } from 'ioredis';
-import type { IKV, KVEntry, KVSetOptions } from '@objectstack/spec/contracts';
-
-/**
- * Stored payload shape: `{v: <value>, ver: <bigint as string>}`.
- * Versions are stored as strings because Redis values are bytes and
- * bigints can exceed JSON-safe-integer range.
- */
-interface StoredKV {
-    v: unknown;
-    ver: string;
-}
-
-export class VersionMismatchError extends Error {
-    constructor(
-        public readonly key: string,
-        public readonly expected: bigint,
-        public readonly actual: bigint,
-    ) {
-        super(
-            `KV version mismatch on "${key}": expected v${expected}, found v${actual}`,
-        );
-        this.name = 'VersionMismatchError';
-    }
-}
-
-export interface RedisKVOptions {
-    client: Redis;
-    keyPrefix?: string;
-}
-
-/**
- * Redis-backed coordination KV with optimistic concurrency via WATCH/MULTI.
- *
- * Each `set()` performs:
- *   1. WATCH key
- *   2. GET key            → read current version
- *   3. compare to ifVersion (if provided)
- *   4. MULTI / SET / [PEXPIRE] / EXEC
- *
- * If a competing writer modifies the key between WATCH and EXEC the
- * transaction aborts and we throw `VersionMismatchError`, matching
- * memory driver semantics.
- *
- * **Not** a cache — uses small JSON envelopes and per-key versioning.
- * Use service-cache for high-throughput caching.
- */
-export class RedisKV implements IKV {
-    private readonly client: Redis;
-    private readonly keyPrefix: string;
-    private closed = false;
-
-    constructor(opts: RedisKVOptions) {
-        this.client = opts.client;
-        this.keyPrefix = opts.keyPrefix ?? 'os:';
-    }
-
-    async get<T = unknown>(key: string): Promise<KVEntry<T> | undefined> {
-        const raw = await this.client.get(this.kvKey(key));
-        if (raw === null) return undefined;
-        const parsed = this.parse(raw);
-        if (!parsed) return undefined;
-        const pttl = await this.client.pttl(this.kvKey(key));
-        const expiresAt = pttl > 0 ? Date.now() + pttl : undefined;
-        return {
-            key,
-            value: parsed.v as T,
-            version: BigInt(parsed.ver),
-            expiresAt,
-        };
-    }
-
-    async set<T = unknown>(
-        key: string,
-        value: T,
-        opts: KVSetOptions = {},
-    ): Promise<KVEntry<T>> {
-        if (this.closed) throw new Error('RedisKV is closed');
-        const physical = this.kvKey(key);
-        const ttlMs = opts.ttl && opts.ttl > 0 ? opts.ttl * 1000 : undefined;
-
-        // Optimistic-concurrency loop — Redis WATCH aborts the MULTI on
-        // any intervening write.
-        // eslint-disable-next-line no-constant-condition
-        while (true) {
-            await this.client.watch(physical);
-            const raw = await this.client.get(physical);
-            const existing = raw ? this.parse(raw) : undefined;
-            const existingVersion = existing ? BigInt(existing.ver) : 0n;
-
-            if (opts.ifVersion !== undefined && opts.ifVersion !== existingVersion) {
-                await this.client.unwatch();
-                throw new VersionMismatchError(key, opts.ifVersion, existingVersion);
-            }
-
-            const newVersion = existingVersion + 1n;
-            const payload: StoredKV = { v: value, ver: newVersion.toString() };
-            const encoded = JSON.stringify(payload);
-
-            const multi = this.client.multi();
-            if (ttlMs) {
-                multi.set(physical, encoded, 'PX', ttlMs);
-            } else {
-                multi.set(physical, encoded);
-            }
-            const result = await multi.exec();
-            // exec() returns null when WATCH detected a concurrent change.
-            if (result === null) continue;
-
-            return {
-                key,
-                value,
-                version: newVersion,
-                expiresAt: ttlMs ? Date.now() + ttlMs : undefined,
-            };
-        }
-    }
-
-    async delete(key: string, opts: { ifVersion?: bigint } = {}): Promise<boolean> {
-        if (this.closed) throw new Error('RedisKV is closed');
-        const physical = this.kvKey(key);
-
-        if (opts.ifVersion === undefined) {
-            const removed = await this.client.del(physical);
-            return removed > 0;
-        }
-
-        // eslint-disable-next-line no-constant-condition
-        while (true) {
-            await this.client.watch(physical);
-            const raw = await this.client.get(physical);
-            if (!raw) {
-                await this.client.unwatch();
-                return false;
-            }
-            const parsed = this.parse(raw);
-            if (!parsed) {
-                await this.client.unwatch();
-                return false;
-            }
-            const currentVersion = BigInt(parsed.ver);
-            if (opts.ifVersion !== currentVersion) {
-                await this.client.unwatch();
-                throw new VersionMismatchError(key, opts.ifVersion, currentVersion);
-            }
-            const multi = this.client.multi();
-            multi.del(physical);
-            const result = await multi.exec();
-            if (result === null) continue;
-            return (result[0]?.[1] as number) > 0;
-        }
-    }
-
-    async cas<T = unknown>(
-        key: string,
-        expectedVersion: bigint,
-        next: T,
-        opts: Omit<KVSetOptions, 'ifVersion'> = {},
-    ): Promise<KVEntry<T> | undefined> {
-        try {
-            return await this.set(key, next, { ...opts, ifVersion: expectedVersion });
-        } catch (err) {
-            if (err instanceof VersionMismatchError) return undefined;
-            throw err;
-        }
-    }
-
-    async close(): Promise<void> {
-        this.closed = true;
-    }
-
-    private kvKey(key: string): string {
-        return `${this.keyPrefix}kv:${key}`;
-    }
-
-    private parse(raw: string): StoredKV | undefined {
-        try {
-            const obj = JSON.parse(raw) as StoredKV;
-            if (typeof obj.ver !== 'string') return undefined;
-            return obj;
-        } catch {
-            return undefined;
-        }
-    }
-}

package/src/lock.ts

@@ -1,205 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-import type { Redis } from 'ioredis';
-import type {
-    ILock,
-    LockAcquireOptions,
-    LockHandle,
-} from '@objectstack/spec/contracts';
-
-const DEFAULT_TTL_MS = 15_000;
-const POLL_INTERVAL_MS = 50;
-
-/**
- * Lua script for safe release: only DEL when the value matches our
- * fencing token. Prevents a delayed release from kicking out the
- * legitimate next holder.
- */
-const RELEASE_SCRIPT = `
-if redis.call("GET", KEYS[1]) == ARGV[1] then
-    return redis.call("DEL", KEYS[1])
-else
-    return 0
-end
-`;
-
-/**
- * Lua script for renew: PEXPIRE only when we still hold the lock.
- * Returns 1 on success, 0 if the lock was lost.
- */
-const RENEW_SCRIPT = `
-if redis.call("GET", KEYS[1]) == ARGV[1] then
-    return redis.call("PEXPIRE", KEYS[1], ARGV[2])
-else
-    return 0
-end
-`;
-
-export interface RedisLockOptions {
-    client: Redis;
-    /** Counter client for fencing-token allocation. Same Redis is fine. */
-    counterClient?: Redis;
-    keyPrefix?: string;
-    defaultTtlMs?: number;
-    /** Stable node id baked into lock values for debugging. */
-    nodeId?: string;
-}
-
-/**
- * Redis-backed distributed lock with TTL fencing.
- *
- * Algorithm (single-instance Redis, NOT Redlock — adequate for
- * typical ObjectStack deployments with one Redis primary):
- *
- *   acquire = SET key {nodeId}:{token} NX PX ttl
- *   release = Lua: GET == expected ? DEL : 0
- *   renew   = Lua: GET == expected ? PEXPIRE : 0
- *
- * Fencing tokens come from a Redis counter (INCR on `{prefix}fence:{key}`)
- * so that two clients in a split-brain see strictly increasing tokens
- * downstream.
- *
- * For multi-master Redis (Sentinel failover, etc.) consider switching to
- * a Redlock variant — not implemented yet.
- */
-export class RedisLock implements ILock {
-    private readonly client: Redis;
-    private readonly counterClient: Redis;
-    private readonly keyPrefix: string;
-    private readonly defaultTtlMs: number;
-    private readonly nodeId: string;
-    private closed = false;
-
-    constructor(opts: RedisLockOptions) {
-        this.client = opts.client;
-        this.counterClient = opts.counterClient ?? opts.client;
-        this.keyPrefix = opts.keyPrefix ?? 'os:';
-        this.defaultTtlMs = opts.defaultTtlMs ?? DEFAULT_TTL_MS;
-        this.nodeId = opts.nodeId ?? 'node';
-    }
-
-    async acquire(key: string, opts: LockAcquireOptions = {}): Promise<LockHandle | null> {
-        if (this.closed) throw new Error('RedisLock is closed');
-        const ttlMs = opts.ttlMs ?? this.defaultTtlMs;
-        const waitMs = opts.waitMs ?? 0;
-        const deadline = Date.now() + waitMs;
-        const lockKey = this.lockKey(key);
-
-        // Allocate a fresh fencing token up-front.
-        const fencingToken = BigInt(
-            await this.counterClient.incr(this.fenceKey(key)),
-        );
-        const value = `${this.nodeId}:${fencingToken}`;
-
-        // First attempt — fast path.
-        if (await this.trySet(lockKey, value, ttlMs)) {
-            return this.makeHandle(key, lockKey, value, fencingToken, ttlMs);
-        }
-        if (waitMs <= 0) return null;
-
-        // Polling loop: simple, correct, good enough for typical
-        // contention. Future: pub/sub-driven wakeup on release.
-        while (Date.now() < deadline) {
-            await sleep(Math.min(POLL_INTERVAL_MS, Math.max(1, deadline - Date.now())));
-            if (await this.trySet(lockKey, value, ttlMs)) {
-                return this.makeHandle(key, lockKey, value, fencingToken, ttlMs);
-            }
-        }
-        return null;
-    }
-
-    async withLock<T>(
-        key: string,
-        fn: (h: LockHandle) => Promise<T>,
-        opts?: LockAcquireOptions,
-    ): Promise<T | null> {
-        const handle = await this.acquire(key, opts);
-        if (!handle) return null;
-        try {
-            return await fn(handle);
-        } finally {
-            await handle.release();
-        }
-    }
-
-    async close(): Promise<void> {
-        this.closed = true;
-    }
-
-    private async trySet(lockKey: string, value: string, ttlMs: number): Promise<boolean> {
-        // SET key value NX PX ttlMs — atomic acquire.
-        const res = await this.client.set(lockKey, value, 'PX', ttlMs, 'NX');
-        return res === 'OK';
-    }
-
-    private makeHandle(
-        logicalKey: string,
-        lockKey: string,
-        value: string,
-        fencingToken: bigint,
-        ttlMs: number,
-    ): LockHandle {
-        const self = this;
-        let released = false;
-        let currentTtl = ttlMs;
-        // Local expiry timer — mirrors memory driver so `isHeld()` flips
-        // on TTL without a Redis roundtrip. Not authoritative (clocks may
-        // drift), but matches contract test expectations.
-        let timer: NodeJS.Timeout | undefined = setTimeout(() => {
-            released = true;
-        }, ttlMs);
-
-        return {
-            key: logicalKey,
-            fencingToken,
-            isHeld(): boolean {
-                return !released;
-            },
-            async renew(extendMs?: number): Promise<void> {
-                if (released) {
-                    throw new Error(`Lock "${logicalKey}" already released`);
-                }
-                const next = extendMs ?? currentTtl;
-                const result = await self.client.eval(
-                    RENEW_SCRIPT,
-                    1,
-                    lockKey,
-                    value,
-                    String(next),
-                );
-                if (result !== 1) {
-                    released = true;
-                    if (timer) { clearTimeout(timer); timer = undefined; }
-                    throw new Error(
-                        `Lock "${logicalKey}" no longer held (fence=${fencingToken})`,
-                    );
-                }
-                currentTtl = next;
-                if (timer) clearTimeout(timer);
-                timer = setTimeout(() => { released = true; }, next);
-            },
-            async release(): Promise<void> {
-                if (released) return;
-                released = true;
-                if (timer) { clearTimeout(timer); timer = undefined; }
-                try {
-                    await self.client.eval(RELEASE_SCRIPT, 1, lockKey, value);
-                } catch {
-                    /* swallow — release is best-effort */
-                }
-            },
-        };
-    }
-
-    private lockKey(key: string): string {
-        return `${this.keyPrefix}lock:${key}`;
-    }
-
-    private fenceKey(key: string): string {
-        return `${this.keyPrefix}fence:${key}`;
-    }
-}
-
-function sleep(ms: number): Promise<void> {
-    return new Promise((r) => setTimeout(r, ms));
-}

package/src/pubsub.ts

@@ -1,188 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-import type { Redis } from 'ioredis';
-import type {
-    IPubSub,
-    PubSubHandler,
-    PublishOptions,
-    SubscribeOptions,
-    Unsubscribe,
-} from '@objectstack/spec/contracts';
-import { duplicateForPubSub } from './client.js';
-
-/**
- * Wire-format envelope sent over Redis. Adds `fromNode` and
- * `publishedAt` so subscribers see the same surface as the memory
- * driver. The user payload is nested under `p` to avoid colliding with
- * reserved keys.
- */
-interface RedisPubSubEnvelope {
-    n?: string;
-    t: number;
-    p: unknown;
-}
-
-export interface RedisPubSubOptions {
-    /** Already-connected client used for PUBLISH. */
-    client: Redis;
-    /** Optional node id surfaced as `fromNode` on every delivered message. */
-    nodeId?: string;
-    /** Key namespace prefix applied to every channel (default: 'os:'). */
-    keyPrefix?: string;
-    /** Error sink for subscriber handler exceptions. */
-    onError?: (err: unknown, channel: string) => void;
-}
-
-/**
- * Redis pub/sub implementation of {@link IPubSub}.
- *
- * Uses two ioredis clients under the hood:
- *   - `publisher` (caller-provided) — runs PUBLISH commands
- *   - `subscriber` (auto-duplicated) — held in subscribe mode, can't run
- *     regular commands per Redis protocol
- *
- * Delivery semantics match Redis pub/sub: at-most-once, fire-and-forget,
- * no persistence. For at-least-once + replay use the planned `streams`
- * adapter (separate driver).
- *
- * Channel names are prefixed with `keyPrefix` before being sent to
- * Redis, so the same Redis instance can host multiple isolated
- * ObjectStack deployments.
- */
-export class RedisPubSub implements IPubSub {
-    private readonly publisher: Redis;
-    private readonly subscriber: Redis;
-    private readonly nodeId?: string;
-    private readonly keyPrefix: string;
-    private readonly onError: (err: unknown, channel: string) => void;
-    private readonly subs = new Map<string, Set<PubSubHandler<unknown>>>();
-    private closed = false;
-
-    constructor(opts: RedisPubSubOptions) {
-        this.publisher = opts.client;
-        this.subscriber = duplicateForPubSub(opts.client);
-        this.nodeId = opts.nodeId;
-        this.keyPrefix = opts.keyPrefix ?? 'os:';
-        this.onError =
-            opts.onError ??
-            ((err, channel) => {
-                // eslint-disable-next-line no-console
-                console.error(`[RedisPubSub] handler error on "${channel}":`, err);
-            });
-
-        this.subscriber.on('message', (raw: string, data: string) => {
-            this.dispatch(raw, data);
-        });
-    }
-
-    /**
-     * Durability contract (P1-5): this awaits the Redis `PUBLISH` command (so the
-     * message left this node), but Redis pub/sub is **at-most-once** — there is no
-     * delivery guarantee to subscribers and no replay for a node that was down or
-     * slow at publish time. This is acceptable **only** for events that are pure
-     * cache-invalidation hints, never the source of truth.
-     *
-     * In particular `metadata.changed` is such a hint: the durable record of every
-     * metadata mutation is the transactional write to `sys_metadata`
-     * (+ `sys_metadata_history`). A subscriber that misses the event keeps serving
-     * its cached schema until its next reload and **loses no data** — it self-heals
-     * on restart / reload against the DB. Do not route any state that must be
-     * delivered exactly-once through this channel; use a durable outbox instead.
-     */
-    async publish<T = unknown>(
-        channel: string,
-        payload: T,
-        _opts?: PublishOptions,
-    ): Promise<void> {
-        if (this.closed) throw new Error('RedisPubSub is closed');
-        const envelope: RedisPubSubEnvelope = {
-            n: this.nodeId,
-            t: Date.now(),
-            p: payload,
-        };
-        await this.publisher.publish(this.prefixed(channel), JSON.stringify(envelope));
-    }
-
-    subscribe<T = unknown>(
-        channel: string,
-        handler: PubSubHandler<T>,
-        _opts?: SubscribeOptions,
-    ): Unsubscribe {
-        if (this.closed) throw new Error('RedisPubSub is closed');
-        const prefixed = this.prefixed(channel);
-        let bucket = this.subs.get(prefixed);
-        if (!bucket) {
-            bucket = new Set();
-            this.subs.set(prefixed, bucket);
-            // Fire-and-forget; if subscribe fails the next publish will
-            // simply not deliver — caller can resubscribe.
-            void this.subscriber.subscribe(prefixed).catch((err) => {
-                this.onError(err, channel);
-            });
-        }
-        const wrapped = handler as PubSubHandler<unknown>;
-        bucket.add(wrapped);
-
-        let disposed = false;
-        return () => {
-            if (disposed) return;
-            disposed = true;
-            const b = this.subs.get(prefixed);
-            if (!b) return;
-            b.delete(wrapped);
-            if (b.size === 0) {
-                this.subs.delete(prefixed);
-                void this.subscriber.unsubscribe(prefixed).catch(() => { /* swallow */ });
-            }
-        };
-    }
-
-    async close(): Promise<void> {
-        if (this.closed) return;
-        this.closed = true;
-        this.subs.clear();
-        try { await this.subscriber.quit(); } catch { /* swallow */ }
-        // We don't quit `publisher` — caller owns it.
-    }
-
-    private prefixed(channel: string): string {
-        return `${this.keyPrefix}ps:${channel}`;
-    }
-
-    private dispatch(prefixedChannel: string, data: string): void {
-        const bucket = this.subs.get(prefixedChannel);
-        if (!bucket || bucket.size === 0) return;
-
-        let envelope: RedisPubSubEnvelope;
-        try {
-            envelope = JSON.parse(data) as RedisPubSubEnvelope;
-        } catch (err) {
-            this.onError(err, prefixedChannel);
-            return;
-        }
-
-        // Strip our keyPrefix so the handler sees the logical channel.
-        const logical = prefixedChannel.startsWith(`${this.keyPrefix}ps:`)
-            ? prefixedChannel.slice(`${this.keyPrefix}ps:`.length)
-            : prefixedChannel;
-
-        const snapshot = Array.from(bucket);
-        for (const handler of snapshot) {
-            try {
-                const result = handler({
-                    channel: logical,
-                    payload: envelope.p,
-                    publishedAt: envelope.t,
-                    fromNode: envelope.n,
-                });
-                if (result && typeof (result as Promise<void>).then === 'function') {
-                    (result as Promise<void>).catch((err) =>
-                        this.onError(err, logical),
-                    );
-                }
-            } catch (err) {
-                this.onError(err, logical);
-            }
-        }
-    }
-}

package/src/redis.contract.test.ts

@@ -1,163 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * Driver contract tests for the Redis cluster driver, run against
- * `ioredis-mock` so they execute without a real Redis instance in CI.
- *
- * The same suites can be invoked against a live Redis by setting
- * `RUN_REAL_REDIS=1` and providing `REDIS_URL` — see the conditional
- * `describe.skipIf` blocks at the bottom.
- */
-
-// @ts-expect-error — ioredis-mock has no published types
-import RedisMock from 'ioredis-mock';
-import { describe, expect, it, vi } from 'vitest';
-import {
-    runLockContract,
-    runKVContract,
-    runCounterContract,
-} from '@objectstack/service-cluster/testing';
-// Load the driver entrypoint at module eval — importing it registers the
-// 'redis' cluster driver as a side-effect, which `defineCluster({ driver:
-// 'redis' })` then resolves. Doing this here (not via `await import()` inside
-// the timed test bodies) keeps the one-time cold module-load cost out of the
-// per-test 5s timeout — the wiring tests below were flaky on slow CI for
-// exactly that reason (the first test paid the full import cost and timed out).
-import './index.js';
-import { defineCluster } from '@objectstack/service-cluster';
-
-import { RedisPubSub } from './pubsub.js';
-import { RedisLock } from './lock.js';
-import { RedisKV } from './kv.js';
-import { RedisCounter } from './counter.js';
-
-// ioredis-mock shares state across instances by default, so each
-// primitive gets a unique key-prefix per test to ensure isolation.
-let suffix = 0;
-const uniquePrefix = () => `t${++suffix}:`;
-const makeClient = () => new RedisMock();
-
-runLockContract('redis(mock)', async () =>
-    new RedisLock({ client: makeClient(), keyPrefix: uniquePrefix() }),
-);
-runKVContract('redis(mock)', async () =>
-    new RedisKV({ client: makeClient(), keyPrefix: uniquePrefix() }),
-);
-runCounterContract('redis(mock)', async () =>
-    new RedisCounter({ client: makeClient(), keyPrefix: uniquePrefix() }),
-);
-
-// PubSub: Redis delivery is async (network roundtrip even for mock), so
-// we can't reuse the synchronous contract suite. Cover the same surface
-// here with explicit waits.
-describe('IPubSub contract — redis(mock)', () => {
-    const flush = () => new Promise<void>((r) => setTimeout(r, 10));
-
-    it('delivers published messages to subscribers', async () => {
-        const bus = new RedisPubSub({ client: makeClient(), keyPrefix: uniquePrefix() });
-        const received: unknown[] = [];
-        bus.subscribe<{ n: number }>('ch', (msg) => { received.push(msg.payload); });
-        await flush();                                         // let SUBSCRIBE register
-        await bus.publish('ch', { n: 1 });
-        await bus.publish('ch', { n: 2 });
-        await flush();
-        expect(received).toEqual([{ n: 1 }, { n: 2 }]);
-        await bus.close();
-    });
-
-    it('does not deliver to other channels', async () => {
-        const bus = new RedisPubSub({ client: makeClient(), keyPrefix: uniquePrefix() });
-        const h = vi.fn();
-        bus.subscribe('a', h);
-        await flush();
-        await bus.publish('b', { x: 1 });
-        await flush();
-        expect(h).not.toHaveBeenCalled();
-        await bus.close();
-    });
-
-    it('supports multiple subscribers per channel', async () => {
-        const bus = new RedisPubSub({ client: makeClient(), keyPrefix: uniquePrefix() });
-        const a = vi.fn();
-        const b = vi.fn();
-        bus.subscribe('ch', a);
-        bus.subscribe('ch', b);
-        await flush();
-        await bus.publish('ch', 'hi');
-        await flush();
-        expect(a).toHaveBeenCalledTimes(1);
-        expect(b).toHaveBeenCalledTimes(1);
-        await bus.close();
-    });
-
-    it('unsubscribe stops delivery and is idempotent', async () => {
-        const bus = new RedisPubSub({ client: makeClient(), keyPrefix: uniquePrefix() });
-        const h = vi.fn();
-        const off = bus.subscribe('ch', h);
-        await flush();
-        await bus.publish('ch', 1);
-        await flush();
-        off();
-        off();
-        await bus.publish('ch', 2);
-        await flush();
-        expect(h).toHaveBeenCalledTimes(1);
-        await bus.close();
-    });
-
-    it('isolates handler errors from siblings', async () => {
-        const bus = new RedisPubSub({ client: makeClient(), keyPrefix: uniquePrefix() });
-        bus.subscribe('ch', () => { throw new Error('boom'); });
-        const ok = vi.fn();
-        bus.subscribe('ch', ok);
-        await flush();
-        await expect(bus.publish('ch', 1)).resolves.toBeUndefined();
-        await flush();
-        expect(ok).toHaveBeenCalledTimes(1);
-        await bus.close();
-    });
-
-    it('close rejects further publishes', async () => {
-        const bus = new RedisPubSub({ client: makeClient(), keyPrefix: uniquePrefix() });
-        await bus.close();
-        await expect(bus.publish('ch', 1)).rejects.toThrow(/closed/);
-    });
-});
-
-describe('Redis driver — wiring', () => {
-    it('exports a registerable driver and defineCluster picks it up', async () => {
-        const client = makeClient();
-        const cluster = defineCluster({
-            driver: 'redis',
-            nodeId: 'mock-node',
-            driverOptions: { client, keyPrefix: uniquePrefix() },
-        });
-        expect(cluster.driver).toBe('redis');
-        expect(cluster.nodeId).toBe('mock-node');
-
-        expect(await cluster.counter.incr('seq')).toBe(1n);
-        expect(await cluster.counter.incr('seq')).toBe(2n);
-
-        await cluster.kv.set('k', { hello: 'world' });
-        const got = await cluster.kv.get<{ hello: string }>('k');
-        expect(got?.value).toEqual({ hello: 'world' });
-
-        const handle = await cluster.lock.acquire('foo');
-        expect(handle).not.toBeNull();
-        expect(handle!.fencingToken).toBeGreaterThan(0n);
-        await handle!.release();
-
-        await cluster.close();
-    });
-
-    it('does NOT quit caller-owned client on close', async () => {
-        const client = makeClient();
-        const cluster = defineCluster({
-            driver: 'redis',
-            nodeId: 'mock-node-2',
-            driverOptions: { client, keyPrefix: uniquePrefix() },
-        });
-        await cluster.close();
-        await expect(client.set('post-close', '1')).resolves.toBe('OK');
-    });
-});

package/tsconfig.json

@@ -1,10 +0,0 @@
-{
-  "extends": "../../../tsconfig.json",
-  "compilerOptions": {
-    "outDir": "dist",
-    "rootDir": "src",
-    "types": ["node"]
-  },
-  "include": ["src"],
-  "exclude": ["node_modules", "dist"]
-}

package/tsup.config.ts

@@ -1,14 +0,0 @@
-// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { defineConfig } from 'tsup';
-
-export default defineConfig({
-    entry: ['src/index.ts'],
-    splitting: true,
-    sourcemap: true,
-    clean: true,
-    dts: !process.env.OS_SKIP_DTS,
-    format: ['esm', 'cjs'],
-    target: 'es2020',
-    external: ['vitest', 'ioredis'],
-});