@objectstack/service-cluster 9.4.0 → 9.5.1

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/service-cluster@9.4.0 build /home/runner/work/framework/framework/packages/services/service-cluster
+> @objectstack/service-cluster@9.5.1 build /home/runner/work/framework/framework/packages/services/service-cluster
 > tsup
 
 CLI Building entry: src/index.ts, src/testing.ts
@@ -10,19 +10,19 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-ESM dist/index.js       12.66 KB
+ESM dist/index.js       13.87 KB
 ESM dist/testing.js     8.60 KB
-ESM dist/index.js.map   33.85 KB
+ESM dist/index.js.map   38.10 KB
 ESM dist/testing.js.map 18.62 KB
-ESM ⚡️ Build success in 672ms
-CJS dist/index.cjs       13.98 KB
+ESM ⚡️ Build success in 1055ms
+CJS dist/index.cjs       15.26 KB
 CJS dist/testing.cjs     11.60 KB
-CJS dist/index.cjs.map   37.23 KB
+CJS dist/index.cjs.map   41.16 KB
 CJS dist/testing.cjs.map 14.18 KB
-CJS ⚡️ Build success in 802ms
+CJS ⚡️ Build success in 1088ms
 DTS Build start
-DTS ⚡️ Build success in 22707ms
-DTS dist/index.d.ts    8.05 KB
+DTS ⚡️ Build success in 19642ms
+DTS dist/index.d.ts    9.12 KB
 DTS dist/testing.d.ts  794.00 B
-DTS dist/index.d.cts   8.05 KB
+DTS dist/index.d.cts   9.12 KB
 DTS dist/testing.d.cts 794.00 B

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @objectstack/service-cluster
 
+## 9.5.1
+
+### Patch Changes
+
+- Updated dependencies [ee72aae]
+  - @objectstack/spec@9.5.1
+  - @objectstack/core@9.5.1
+
+## 9.5.0
+
+### Patch Changes
+
+- Updated dependencies [d08551c]
+- Updated dependencies [707aeed]
+- Updated dependencies [7a103d4]
+- Updated dependencies [4b01250]
+  - @objectstack/spec@9.5.0
+  - @objectstack/core@9.5.0
+
 ## 9.4.0
 
 ### Patch Changes

package/dist/index.cjs

@@ -337,6 +337,25 @@ function generateNodeId() {
   return `node-${ts}-${rand}`;
 }
 
+// src/split-brain-guard.ts
+var IN_PROCESS_DRIVERS = /* @__PURE__ */ new Set(["memory"]);
+function isTrue(v) {
+  return String(v).trim().toLowerCase() === "true";
+}
+function declaresMultiNode(env = process.env) {
+  if (isTrue(env.OS_EXPECT_MULTI_NODE)) return true;
+  const replicas = Number(env.OS_CLUSTER_REPLICAS);
+  return Number.isFinite(replicas) && replicas > 1;
+}
+function assertClusterDriverSafeForTopology(driver, env = process.env) {
+  if (!declaresMultiNode(env)) return;
+  if (!IN_PROCESS_DRIVERS.has(driver)) return;
+  if (isTrue(env.OS_ALLOW_MEMORY_CLUSTER_MULTINODE)) return;
+  throw new Error(
+    `ClusterServicePlugin: multi-node deployment declared (OS_EXPECT_MULTI_NODE / OS_CLUSTER_REPLICAS>1) but the cluster driver is in-process "${driver}" -- its locks/counters/pub-sub do not coordinate across processes, so multiple replicas silently split-brain. Configure a remote cluster driver (e.g. @objectstack/service-cluster-redis) or a DB-backed driver. To override (replicas declared but cluster primitives unused cross-node), set OS_ALLOW_MEMORY_CLUSTER_MULTINODE=true. See cloud ADR-0010.`
+  );
+}
+
 // src/cluster-service-plugin.ts
 var ClusterServicePlugin = class {
   constructor(options = {}) {
@@ -354,6 +373,7 @@ var ClusterServicePlugin = class {
       this.cluster = defineCluster(_nullishCoalesce(this.options.config, () => ( {})));
       this.owned = true;
     }
+    assertClusterDriverSafeForTopology(this.cluster.driver);
     ctx.registerService("cluster", this.cluster);
     ctx.logger.info(
       `ClusterServicePlugin: registered "${this.cluster.driver}" driver (node=${this.cluster.nodeId})`
@@ -440,5 +460,7 @@ var MetadataClusterBridgePlugin = class {
 
 
 
-exports.ClusterServicePlugin = ClusterServicePlugin; exports.ComposedClusterService = ComposedClusterService; exports.MemoryCounter = MemoryCounter; exports.MemoryKV = MemoryKV; exports.MemoryLock = MemoryLock; exports.MemoryPubSub = MemoryPubSub; exports.MetadataClusterBridgePlugin = MetadataClusterBridgePlugin; exports.VersionMismatchError = VersionMismatchError; exports.defineCluster = defineCluster; exports.registerClusterDriver = registerClusterDriver;
+
+
+exports.ClusterServicePlugin = ClusterServicePlugin; exports.ComposedClusterService = ComposedClusterService; exports.MemoryCounter = MemoryCounter; exports.MemoryKV = MemoryKV; exports.MemoryLock = MemoryLock; exports.MemoryPubSub = MemoryPubSub; exports.MetadataClusterBridgePlugin = MetadataClusterBridgePlugin; exports.VersionMismatchError = VersionMismatchError; exports.assertClusterDriverSafeForTopology = assertClusterDriverSafeForTopology; exports.declaresMultiNode = declaresMultiNode; exports.defineCluster = defineCluster; exports.registerClusterDriver = registerClusterDriver;
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["/home/runner/work/framework/framework/packages/services/service-cluster/dist/index.cjs","../src/cluster.ts","../src/memory/pubsub.ts","../src/memory/lock.ts","../src/memory/kv.ts","../src/memory/counter.ts","../src/cluster-service-plugin.ts","../src/metadata-cluster-bridge-plugin.ts"],"names":[],"mappings":"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","file":"/home/runner/work/framework/framework/packages/services/service-cluster/dist/index.cjs","sourcesContent":[null,"// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type {\n    IClusterService,\n    IPubSub,\n    ILock,\n    IKV,\n    ICounter,\n} from '@objectstack/spec/contracts';\nimport type { ClusterCapabilityConfigInput } from '@objectstack/spec/kernel';\nimport { ClusterCapabilityConfigSchema } from '@objectstack/spec/kernel';\n\nimport { MemoryPubSub } from './memory/pubsub.js';\nimport { MemoryLock } from './memory/lock.js';\nimport { MemoryKV } from './memory/kv.js';\nimport { MemoryCounter } from './memory/counter.js';\n\n/**\n * Compose four cluster primitives into a single `IClusterService` facade.\n * Useful for custom driver authors who want to mix and match.\n */\nexport class ComposedClusterService implements IClusterService {\n    constructor(\n        public readonly nodeId: string,\n        public readonly driver: string,\n        public readonly pubsub: IPubSub,\n        public readonly lock: ILock,\n        public readonly kv: IKV,\n        public readonly counter: ICounter,\n    ) { }\n\n    async close(): Promise<void> {\n        // Reverse order, swallow errors so a slow close doesn't block siblings.\n        const closers = [this.counter, this.kv, this.lock, this.pubsub];\n        for (const c of closers) {\n            try {\n                await c.close();\n            } catch (err) {\n                // eslint-disable-next-line no-console\n                console.error('[ClusterService] close error:', err);\n            }\n        }\n    }\n}\n\n/**\n * Build an `IClusterService` from a `ClusterCapabilityConfig`. The only\n * driver shipped from this package is `memory`; other drivers (postgres,\n * redis, nats) live in dedicated packages and register themselves via\n * `registerClusterDriver()`.\n *\n * @example\n *   const cluster = defineCluster({ driver: 'memory' });\n *   await cluster.pubsub.publish('metadata.changed', { id: 'x' });\n */\nexport function defineCluster(\n    config: ClusterCapabilityConfigInput = {},\n): IClusterService {\n    const parsed = ClusterCapabilityConfigSchema.parse(config);\n    const nodeId = parsed.nodeId ?? generateNodeId();\n\n    if (parsed.driver === 'memory') {\n        return new ComposedClusterService(\n            nodeId,\n            'memory',\n            new MemoryPubSub({ nodeId }),\n            new MemoryLock({ defaultTtlMs: parsed.lockTtlMs }),\n            new MemoryKV(),\n            new MemoryCounter(),\n        );\n    }\n\n    const factory = driverRegistry.get(parsed.driver);\n    if (!factory) {\n        throw new Error(\n            `Cluster driver \"${parsed.driver}\" is not registered. ` +\n                `Did you forget to import @objectstack/service-cluster-${parsed.driver} ` +\n                `or call registerClusterDriver()? ` +\n                `See content/docs/concepts/cluster-semantics.mdx §6.`,\n        );\n    }\n    return factory({ ...parsed, nodeId });\n}\n\n// ---------------------------------------------------------------------------\n// Driver registry (for postgres/redis/nats/custom drivers)\n// ---------------------------------------------------------------------------\n\nexport interface DriverFactoryConfig {\n    driver: string;\n    nodeId: string;\n    url?: string;\n    useExistingPool?: boolean;\n    heartbeatMs?: number;\n    lockTtlMs?: number;\n    tenantIsolation?: string;\n    driverOptions?: Record<string, unknown>;\n}\n\nexport type ClusterDriverFactory = (config: DriverFactoryConfig) => IClusterService;\n\nconst driverRegistry = new Map<string, ClusterDriverFactory>();\n\n/**\n * Register a custom cluster driver. Driver packages (e.g.\n * `@objectstack/service-cluster-postgres`) should call this at module\n * load time so `defineCluster({ driver: 'postgres' })` resolves them.\n */\nexport function registerClusterDriver(\n    name: string,\n    factory: ClusterDriverFactory,\n): void {\n    if (name === 'memory') {\n        throw new Error('The \"memory\" driver is reserved.');\n    }\n    driverRegistry.set(name, factory);\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\nfunction generateNodeId(): string {\n    // Avoid the `crypto` import dance for a single use; this is dev-only\n    // randomness and the driver upgrades replace it.\n    const rand = Math.random().toString(36).slice(2, 10);\n    const ts = Date.now().toString(36);\n    return `node-${ts}-${rand}`;\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type {\n    IPubSub,\n    PubSubHandler,\n    PublishOptions,\n    SubscribeOptions,\n    Unsubscribe,\n} from '@objectstack/spec/contracts';\n\n/**\n * In-memory PubSub for single-process deployments and tests.\n *\n * Behavior:\n *   - Synchronous fan-out: every subscriber's handler is invoked in the\n *     same tick that `publish()` resolves. Handler errors are swallowed\n *     and logged via `onError` (so one bad subscriber can't poison the bus).\n *   - At-least-once semantics held vacuously (a single in-process delivery).\n *   - No cross-process delivery — use the redis/postgres/nats driver for\n *     real multi-node setups.\n */\nexport interface MemoryPubSubOptions {\n    /** Optional error sink for handler exceptions. Defaults to console.error. */\n    onError?: (err: unknown, channel: string) => void;\n    /** Optional node id surfaced as `fromNode` on every message. */\n    nodeId?: string;\n}\n\ninterface Subscription {\n    channel: string;\n    handler: PubSubHandler<unknown>;\n}\n\nexport class MemoryPubSub implements IPubSub {\n    private readonly subs = new Map<string, Set<Subscription>>();\n    private readonly onError: (err: unknown, channel: string) => void;\n    private readonly nodeId?: string;\n    private closed = false;\n\n    constructor(opts: MemoryPubSubOptions = {}) {\n        this.onError =\n            opts.onError ??\n            ((err, channel) => {\n                // eslint-disable-next-line no-console\n                console.error(`[MemoryPubSub] handler error on channel \"${channel}\":`, err);\n            });\n        this.nodeId = opts.nodeId;\n    }\n\n    async publish<T = unknown>(\n        channel: string,\n        payload: T,\n        _opts?: PublishOptions,\n    ): Promise<void> {\n        if (this.closed) throw new Error('MemoryPubSub is closed');\n        const bucket = this.subs.get(channel);\n        if (!bucket || bucket.size === 0) return;\n        const publishedAt = Date.now();\n        // Snapshot so handler-driven unsubscribes during dispatch are safe.\n        const snapshot = Array.from(bucket);\n        for (const sub of snapshot) {\n            try {\n                const result = sub.handler({\n                    channel,\n                    payload,\n                    publishedAt,\n                    fromNode: this.nodeId,\n                });\n                if (result && typeof (result as Promise<void>).then === 'function') {\n                    (result as Promise<void>).catch((err) => this.onError(err, channel));\n                }\n            } catch (err) {\n                this.onError(err, channel);\n            }\n        }\n    }\n\n    subscribe<T = unknown>(\n        channel: string,\n        handler: PubSubHandler<T>,\n        _opts?: SubscribeOptions,\n    ): Unsubscribe {\n        if (this.closed) throw new Error('MemoryPubSub is closed');\n        let bucket = this.subs.get(channel);\n        if (!bucket) {\n            bucket = new Set();\n            this.subs.set(channel, bucket);\n        }\n        const sub: Subscription = { channel, handler: handler as PubSubHandler<unknown> };\n        bucket.add(sub);\n        let disposed = false;\n        return () => {\n            if (disposed) return;\n            disposed = true;\n            const b = this.subs.get(channel);\n            if (!b) return;\n            b.delete(sub);\n            if (b.size === 0) this.subs.delete(channel);\n        };\n    }\n\n    async close(): Promise<void> {\n        this.closed = true;\n        this.subs.clear();\n    }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type {\n    ILock,\n    LockAcquireOptions,\n    LockHandle,\n} from '@objectstack/spec/contracts';\n\n/**\n * In-memory lock for single-process deployments and tests.\n *\n * Behavior:\n *   - Per-key FIFO wait queue (so `waitMs > 0` callers receive the lock\n *     in arrival order).\n *   - TTL is honored: if a holder doesn't renew before `ttlMs` elapses,\n *     the lock is auto-released and the next waiter wakes.\n *   - Fencing tokens are process-local monotonic bigints.\n */\n\nconst DEFAULT_TTL_MS = 15_000;\n\nexport interface MemoryLockOptions {\n    /** Default TTL for `acquire` when caller doesn't supply one. */\n    defaultTtlMs?: number;\n}\n\ninterface Holder {\n    fencingToken: bigint;\n    expiresAt: number;\n    released: boolean;\n    timer?: NodeJS.Timeout;\n}\n\ninterface Waiter {\n    resolve: (h: LockHandle | null) => void;\n    deadline: number;\n    opts: LockAcquireOptions;\n    timer?: NodeJS.Timeout;\n}\n\nexport class MemoryLock implements ILock {\n    private readonly holders = new Map<string, Holder>();\n    private readonly queues = new Map<string, Waiter[]>();\n    private readonly defaultTtlMs: number;\n    private fenceSeq = 0n;\n    private closed = false;\n\n    constructor(opts: MemoryLockOptions = {}) {\n        this.defaultTtlMs = opts.defaultTtlMs ?? DEFAULT_TTL_MS;\n    }\n\n    async acquire(key: string, opts: LockAcquireOptions = {}): Promise<LockHandle | null> {\n        if (this.closed) throw new Error('MemoryLock is closed');\n        const ttlMs = opts.ttlMs ?? this.defaultTtlMs;\n        const waitMs = opts.waitMs ?? 0;\n\n        if (!this.holders.has(key)) {\n            return this.grant(key, ttlMs);\n        }\n        if (waitMs <= 0) return null;\n\n        return new Promise<LockHandle | null>((resolve) => {\n            const deadline = Date.now() + waitMs;\n            const waiter: Waiter = { resolve, deadline, opts };\n            const queue = this.queues.get(key) ?? [];\n            queue.push(waiter);\n            this.queues.set(key, queue);\n            waiter.timer = setTimeout(() => {\n                const q = this.queues.get(key);\n                if (q) {\n                    const idx = q.indexOf(waiter);\n                    if (idx >= 0) q.splice(idx, 1);\n                }\n                resolve(null);\n            }, waitMs);\n        });\n    }\n\n    async withLock<T>(\n        key: string,\n        fn: (h: LockHandle) => Promise<T>,\n        opts?: LockAcquireOptions,\n    ): Promise<T | null> {\n        const handle = await this.acquire(key, opts);\n        if (!handle) return null;\n        try {\n            return await fn(handle);\n        } finally {\n            await handle.release();\n        }\n    }\n\n    async close(): Promise<void> {\n        this.closed = true;\n        for (const [, holder] of this.holders) {\n            if (holder.timer) clearTimeout(holder.timer);\n            holder.released = true;\n        }\n        this.holders.clear();\n        for (const [, q] of this.queues) {\n            for (const w of q) {\n                if (w.timer) clearTimeout(w.timer);\n                w.resolve(null);\n            }\n        }\n        this.queues.clear();\n    }\n\n    private grant(key: string, ttlMs: number): LockHandle {\n        const fencingToken = ++this.fenceSeq;\n        const holder: Holder = {\n            fencingToken,\n            expiresAt: Date.now() + ttlMs,\n            released: false,\n        };\n        holder.timer = setTimeout(() => this.expire(key, holder), ttlMs);\n        this.holders.set(key, holder);\n\n        const self = this;\n        const handle: LockHandle = {\n            key,\n            fencingToken,\n            isHeld: () => !holder.released && self.holders.get(key) === holder,\n            async renew(extendMs?: number) {\n                if (holder.released || self.holders.get(key) !== holder) {\n                    throw new Error(`Lock \"${key}\" no longer held (fence=${fencingToken})`);\n                }\n                const next = extendMs ?? ttlMs;\n                holder.expiresAt = Date.now() + next;\n                if (holder.timer) clearTimeout(holder.timer);\n                holder.timer = setTimeout(() => self.expire(key, holder), next);\n            },\n            async release() {\n                if (holder.released || self.holders.get(key) !== holder) return;\n                holder.released = true;\n                if (holder.timer) clearTimeout(holder.timer);\n                self.holders.delete(key);\n                self.handoff(key);\n            },\n        };\n        return handle;\n    }\n\n    private expire(key: string, holder: Holder): void {\n        if (holder.released) return;\n        if (this.holders.get(key) !== holder) return;\n        holder.released = true;\n        this.holders.delete(key);\n        this.handoff(key);\n    }\n\n    private handoff(key: string): void {\n        const queue = this.queues.get(key);\n        if (!queue || queue.length === 0) return;\n        const next = queue.shift()!;\n        if (next.timer) clearTimeout(next.timer);\n        if (Date.now() > next.deadline) {\n            next.resolve(null);\n            this.handoff(key);\n            return;\n        }\n        const ttlMs = next.opts.ttlMs ?? this.defaultTtlMs;\n        next.resolve(this.grant(key, ttlMs));\n        if (queue.length === 0) this.queues.delete(key);\n    }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { IKV, KVEntry, KVSetOptions } from '@objectstack/spec/contracts';\n\ninterface Entry<T = unknown> {\n    value: T;\n    version: bigint;\n    expiresAt?: number;\n    timer?: NodeJS.Timeout;\n}\n\n/**\n * In-memory coordination KV. Supports optimistic concurrency via\n * `ifVersion` and TTL via `ttl` (seconds).\n *\n * NOT a cache, NOT a database — intended for small cluster bookkeeping.\n */\nexport class MemoryKV implements IKV {\n    private readonly store = new Map<string, Entry>();\n    private closed = false;\n\n    async get<T = unknown>(key: string): Promise<KVEntry<T> | undefined> {\n        const e = this.store.get(key);\n        if (!e) return undefined;\n        if (e.expiresAt && Date.now() >= e.expiresAt) {\n            this.store.delete(key);\n            return undefined;\n        }\n        return {\n            key,\n            value: e.value as T,\n            version: e.version,\n            expiresAt: e.expiresAt,\n        };\n    }\n\n    async set<T = unknown>(\n        key: string,\n        value: T,\n        opts: KVSetOptions = {},\n    ): Promise<KVEntry<T>> {\n        if (this.closed) throw new Error('MemoryKV is closed');\n        const existing = this.store.get(key);\n        const existingVersion = existing\n            ? existing.expiresAt && Date.now() >= existing.expiresAt\n                ? 0n\n                : existing.version\n            : 0n;\n        if (opts.ifVersion !== undefined && opts.ifVersion !== existingVersion) {\n            throw new VersionMismatchError(key, opts.ifVersion, existingVersion);\n        }\n        if (existing?.timer) clearTimeout(existing.timer);\n        const version = existingVersion + 1n;\n        const expiresAt = opts.ttl && opts.ttl > 0 ? Date.now() + opts.ttl * 1000 : undefined;\n        const entry: Entry<T> = { value, version, expiresAt };\n        if (expiresAt) {\n            entry.timer = setTimeout(() => {\n                const current = this.store.get(key);\n                if (current === (entry as Entry<unknown>)) this.store.delete(key);\n            }, expiresAt - Date.now());\n        }\n        this.store.set(key, entry as Entry<unknown>);\n        return { key, value, version, expiresAt };\n    }\n\n    async delete(key: string, opts: { ifVersion?: bigint } = {}): Promise<boolean> {\n        const e = this.store.get(key);\n        if (!e) return false;\n        if (e.expiresAt && Date.now() >= e.expiresAt) {\n            this.store.delete(key);\n            return false;\n        }\n        if (opts.ifVersion !== undefined && opts.ifVersion !== e.version) {\n            throw new VersionMismatchError(key, opts.ifVersion, e.version);\n        }\n        if (e.timer) clearTimeout(e.timer);\n        this.store.delete(key);\n        return true;\n    }\n\n    async cas<T = unknown>(\n        key: string,\n        expectedVersion: bigint,\n        next: T,\n        opts: Omit<KVSetOptions, 'ifVersion'> = {},\n    ): Promise<KVEntry<T> | undefined> {\n        try {\n            return await this.set(key, next, { ...opts, ifVersion: expectedVersion });\n        } catch (err) {\n            if (err instanceof VersionMismatchError) return undefined;\n            throw err;\n        }\n    }\n\n    async close(): Promise<void> {\n        this.closed = true;\n        for (const [, e] of this.store) {\n            if (e.timer) clearTimeout(e.timer);\n        }\n        this.store.clear();\n    }\n}\n\nexport class VersionMismatchError extends Error {\n    constructor(\n        public readonly key: string,\n        public readonly expected: bigint,\n        public readonly actual: bigint,\n    ) {\n        super(\n            `KV version mismatch on \"${key}\": expected v${expected}, found v${actual}`,\n        );\n        this.name = 'VersionMismatchError';\n    }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { ICounter, CounterIncrOptions } from '@objectstack/spec/contracts';\n\n/**\n * In-memory monotonic counter. Single-process only — for cross-node id\n * allocation, use the postgres or redis driver.\n */\nexport class MemoryCounter implements ICounter {\n    private readonly counters = new Map<string, bigint>();\n    private closed = false;\n\n    async incr(key: string, opts: CounterIncrOptions = {}): Promise<bigint> {\n        if (this.closed) throw new Error('MemoryCounter is closed');\n        const by = BigInt(opts.by ?? 1);\n        const current = this.counters.get(key) ?? 0n;\n        const next = current + by;\n        this.counters.set(key, next);\n        return next;\n    }\n\n    async peek(key: string): Promise<bigint> {\n        return this.counters.get(key) ?? 0n;\n    }\n\n    async reset(key: string, value: bigint = 0n): Promise<void> {\n        if (this.closed) throw new Error('MemoryCounter is closed');\n        if (value === 0n) this.counters.delete(key);\n        else this.counters.set(key, value);\n    }\n\n    async close(): Promise<void> {\n        this.closed = true;\n        this.counters.clear();\n    }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport type { IClusterService } from '@objectstack/spec/contracts';\nimport type { ClusterCapabilityConfigInput } from '@objectstack/spec/kernel';\nimport { defineCluster } from './cluster.js';\n\n/**\n * Options for `ClusterServicePlugin`.\n *\n * Pass either a pre-built `cluster` instance (advanced — for tests or\n * custom drivers), or a `config` object that will be passed to\n * `defineCluster()`. If both are omitted, a memory-driver cluster is\n * created with auto-generated nodeId.\n */\nexport interface ClusterServicePluginOptions {\n    /** Pre-built cluster service. Wins over `config` when both provided. */\n    cluster?: IClusterService;\n    /** Config forwarded to `defineCluster()` when `cluster` is absent. */\n    config?: ClusterCapabilityConfigInput;\n}\n\n/**\n * Registers an `IClusterService` under the well-known service name\n * `'cluster'`. Plugins consume it via:\n *\n * ```ts\n * import type { IClusterService } from '@objectstack/spec/contracts';\n * const cluster = ctx.getService<IClusterService>('cluster');\n * await cluster.pubsub.publish('metadata.changed', payload);\n * ```\n *\n * The plugin closes the cluster on kernel shutdown.\n *\n * @example default memory driver\n *   kernel.use(new ClusterServicePlugin());\n *\n * @example explicit config\n *   kernel.use(new ClusterServicePlugin({ config: { driver: 'memory', nodeId: 'web-1' } }));\n */\nexport class ClusterServicePlugin implements Plugin {\n    name = 'com.objectstack.service.cluster';\n    version = '1.0.0';\n    type = 'standard';\n\n    private readonly options: ClusterServicePluginOptions;\n    private cluster?: IClusterService;\n    private owned = false;\n\n    constructor(options: ClusterServicePluginOptions = {}) {\n        this.options = options;\n    }\n\n    async init(ctx: PluginContext): Promise<void> {\n        if (this.options.cluster) {\n            this.cluster = this.options.cluster;\n            this.owned = false;\n        } else {\n            this.cluster = defineCluster(this.options.config ?? {});\n            this.owned = true;\n        }\n        ctx.registerService('cluster', this.cluster);\n        ctx.logger.info(\n            `ClusterServicePlugin: registered \"${this.cluster.driver}\" driver (node=${this.cluster.nodeId})`,\n        );\n\n        ctx.hook('kernel:shutdown', async () => {\n            if (this.owned && this.cluster) {\n                try {\n                    await this.cluster.close();\n                } catch (err) {\n                    ctx.logger.error('ClusterServicePlugin: close error', err as Error);\n                }\n            }\n        });\n    }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport type { IClusterService } from '@objectstack/spec/contracts';\n\n/**\n * Bridges the cluster pub/sub bus to the metadata service so that\n * metadata mutations on one node invalidate registry caches on peer\n * nodes. Implements the \"first real consumer\" of the cluster API.\n *\n * Implementation detail: this plugin lives in `@objectstack/service-cluster`\n * (not in `@objectstack/metadata`) to avoid forcing every metadata\n * consumer to pull the cluster service. The metadata package only needs\n * the `IPubSub` interface, which lives in `@objectstack/spec/contracts`.\n *\n * Activates only when both services are present and the metadata service\n * exposes `attachClusterPubSub()`. Late binding is achieved via the\n * `kernel:ready` lifecycle hook.\n *\n * Channel: `metadata.changed` — payload shape defined by\n * `ClusterMetadataChangedPayload` in `@objectstack/metadata`.\n *\n * See `content/docs/concepts/cluster-semantics.mdx` §5.\n */\nexport class MetadataClusterBridgePlugin implements Plugin {\n    name = 'com.objectstack.service.metadata-cluster-bridge';\n    version = '1.0.0';\n    type = 'standard';\n\n    private detach?: () => void;\n\n    async init(ctx: PluginContext): Promise<void> {\n        ctx.hook('kernel:ready', async () => {\n            let cluster: IClusterService | undefined;\n            let md: unknown;\n            try {\n                cluster = ctx.getService<IClusterService>('cluster');\n            } catch {\n                ctx.logger.debug(\n                    'MetadataClusterBridgePlugin: no \"cluster\" service registered, skipping',\n                );\n                return;\n            }\n            try {\n                md = ctx.getService<unknown>('metadata');\n            } catch {\n                ctx.logger.debug(\n                    'MetadataClusterBridgePlugin: no \"metadata\" service registered, skipping',\n                );\n                return;\n            }\n\n            const attach = (md as { attachClusterPubSub?: unknown })\n                .attachClusterPubSub;\n            if (typeof attach !== 'function') {\n                ctx.logger.warn(\n                    'MetadataClusterBridgePlugin: metadata service does not expose attachClusterPubSub(); cross-node cache invalidation disabled',\n                );\n                return;\n            }\n\n            try {\n                this.detach = (attach as (\n                    pubsub: IClusterService['pubsub'],\n                    nodeId: string,\n                ) => () => void).call(md, cluster.pubsub, cluster.nodeId);\n                ctx.logger.info(\n                    `MetadataClusterBridgePlugin: bridged metadata.changed → cluster.pubsub (node=${cluster.nodeId})`,\n                );\n            } catch (err) {\n                ctx.logger.error(\n                    'MetadataClusterBridgePlugin: attach failed',\n                    err as Error,\n                );\n            }\n        });\n\n        ctx.hook('kernel:shutdown', async () => {\n            try {\n                this.detach?.();\n            } catch (err) {\n                ctx.logger.error(\n                    'MetadataClusterBridgePlugin: detach error',\n                    err as Error,\n                );\n            }\n            this.detach = undefined;\n        });\n    }\n}\n"]}
+{"version":3,"sources":["/home/runner/work/framework/framework/packages/services/service-cluster/dist/index.cjs","../src/cluster.ts","../src/memory/pubsub.ts","../src/memory/lock.ts","../src/memory/kv.ts","../src/memory/counter.ts","../src/split-brain-guard.ts","../src/cluster-service-plugin.ts","../src/metadata-cluster-bridge-plugin.ts"],"names":[],"mappings":"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","file":"/home/runner/work/framework/framework/packages/services/service-cluster/dist/index.cjs","sourcesContent":[null,"// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type {\n    IClusterService,\n    IPubSub,\n    ILock,\n    IKV,\n    ICounter,\n} from '@objectstack/spec/contracts';\nimport type { ClusterCapabilityConfigInput } from '@objectstack/spec/kernel';\nimport { ClusterCapabilityConfigSchema } from '@objectstack/spec/kernel';\n\nimport { MemoryPubSub } from './memory/pubsub.js';\nimport { MemoryLock } from './memory/lock.js';\nimport { MemoryKV } from './memory/kv.js';\nimport { MemoryCounter } from './memory/counter.js';\n\n/**\n * Compose four cluster primitives into a single `IClusterService` facade.\n * Useful for custom driver authors who want to mix and match.\n */\nexport class ComposedClusterService implements IClusterService {\n    constructor(\n        public readonly nodeId: string,\n        public readonly driver: string,\n        public readonly pubsub: IPubSub,\n        public readonly lock: ILock,\n        public readonly kv: IKV,\n        public readonly counter: ICounter,\n    ) { }\n\n    async close(): Promise<void> {\n        // Reverse order, swallow errors so a slow close doesn't block siblings.\n        const closers = [this.counter, this.kv, this.lock, this.pubsub];\n        for (const c of closers) {\n            try {\n                await c.close();\n            } catch (err) {\n                // eslint-disable-next-line no-console\n                console.error('[ClusterService] close error:', err);\n            }\n        }\n    }\n}\n\n/**\n * Build an `IClusterService` from a `ClusterCapabilityConfig`. The only\n * driver shipped from this package is `memory`; other drivers (postgres,\n * redis, nats) live in dedicated packages and register themselves via\n * `registerClusterDriver()`.\n *\n * @example\n *   const cluster = defineCluster({ driver: 'memory' });\n *   await cluster.pubsub.publish('metadata.changed', { id: 'x' });\n */\nexport function defineCluster(\n    config: ClusterCapabilityConfigInput = {},\n): IClusterService {\n    const parsed = ClusterCapabilityConfigSchema.parse(config);\n    const nodeId = parsed.nodeId ?? generateNodeId();\n\n    if (parsed.driver === 'memory') {\n        return new ComposedClusterService(\n            nodeId,\n            'memory',\n            new MemoryPubSub({ nodeId }),\n            new MemoryLock({ defaultTtlMs: parsed.lockTtlMs }),\n            new MemoryKV(),\n            new MemoryCounter(),\n        );\n    }\n\n    const factory = driverRegistry.get(parsed.driver);\n    if (!factory) {\n        throw new Error(\n            `Cluster driver \"${parsed.driver}\" is not registered. ` +\n                `Did you forget to import @objectstack/service-cluster-${parsed.driver} ` +\n                `or call registerClusterDriver()? ` +\n                `See content/docs/concepts/cluster-semantics.mdx §6.`,\n        );\n    }\n    return factory({ ...parsed, nodeId });\n}\n\n// ---------------------------------------------------------------------------\n// Driver registry (for postgres/redis/nats/custom drivers)\n// ---------------------------------------------------------------------------\n\nexport interface DriverFactoryConfig {\n    driver: string;\n    nodeId: string;\n    url?: string;\n    useExistingPool?: boolean;\n    heartbeatMs?: number;\n    lockTtlMs?: number;\n    tenantIsolation?: string;\n    driverOptions?: Record<string, unknown>;\n}\n\nexport type ClusterDriverFactory = (config: DriverFactoryConfig) => IClusterService;\n\nconst driverRegistry = new Map<string, ClusterDriverFactory>();\n\n/**\n * Register a custom cluster driver. Driver packages (e.g.\n * `@objectstack/service-cluster-postgres`) should call this at module\n * load time so `defineCluster({ driver: 'postgres' })` resolves them.\n */\nexport function registerClusterDriver(\n    name: string,\n    factory: ClusterDriverFactory,\n): void {\n    if (name === 'memory') {\n        throw new Error('The \"memory\" driver is reserved.');\n    }\n    driverRegistry.set(name, factory);\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\nfunction generateNodeId(): string {\n    // Avoid the `crypto` import dance for a single use; this is dev-only\n    // randomness and the driver upgrades replace it.\n    const rand = Math.random().toString(36).slice(2, 10);\n    const ts = Date.now().toString(36);\n    return `node-${ts}-${rand}`;\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type {\n    IPubSub,\n    PubSubHandler,\n    PublishOptions,\n    SubscribeOptions,\n    Unsubscribe,\n} from '@objectstack/spec/contracts';\n\n/**\n * In-memory PubSub for single-process deployments and tests.\n *\n * Behavior:\n *   - Synchronous fan-out: every subscriber's handler is invoked in the\n *     same tick that `publish()` resolves. Handler errors are swallowed\n *     and logged via `onError` (so one bad subscriber can't poison the bus).\n *   - At-least-once semantics held vacuously (a single in-process delivery).\n *   - No cross-process delivery — use the redis/postgres/nats driver for\n *     real multi-node setups.\n */\nexport interface MemoryPubSubOptions {\n    /** Optional error sink for handler exceptions. Defaults to console.error. */\n    onError?: (err: unknown, channel: string) => void;\n    /** Optional node id surfaced as `fromNode` on every message. */\n    nodeId?: string;\n}\n\ninterface Subscription {\n    channel: string;\n    handler: PubSubHandler<unknown>;\n}\n\nexport class MemoryPubSub implements IPubSub {\n    private readonly subs = new Map<string, Set<Subscription>>();\n    private readonly onError: (err: unknown, channel: string) => void;\n    private readonly nodeId?: string;\n    private closed = false;\n\n    constructor(opts: MemoryPubSubOptions = {}) {\n        this.onError =\n            opts.onError ??\n            ((err, channel) => {\n                // eslint-disable-next-line no-console\n                console.error(`[MemoryPubSub] handler error on channel \"${channel}\":`, err);\n            });\n        this.nodeId = opts.nodeId;\n    }\n\n    async publish<T = unknown>(\n        channel: string,\n        payload: T,\n        _opts?: PublishOptions,\n    ): Promise<void> {\n        if (this.closed) throw new Error('MemoryPubSub is closed');\n        const bucket = this.subs.get(channel);\n        if (!bucket || bucket.size === 0) return;\n        const publishedAt = Date.now();\n        // Snapshot so handler-driven unsubscribes during dispatch are safe.\n        const snapshot = Array.from(bucket);\n        for (const sub of snapshot) {\n            try {\n                const result = sub.handler({\n                    channel,\n                    payload,\n                    publishedAt,\n                    fromNode: this.nodeId,\n                });\n                if (result && typeof (result as Promise<void>).then === 'function') {\n                    (result as Promise<void>).catch((err) => this.onError(err, channel));\n                }\n            } catch (err) {\n                this.onError(err, channel);\n            }\n        }\n    }\n\n    subscribe<T = unknown>(\n        channel: string,\n        handler: PubSubHandler<T>,\n        _opts?: SubscribeOptions,\n    ): Unsubscribe {\n        if (this.closed) throw new Error('MemoryPubSub is closed');\n        let bucket = this.subs.get(channel);\n        if (!bucket) {\n            bucket = new Set();\n            this.subs.set(channel, bucket);\n        }\n        const sub: Subscription = { channel, handler: handler as PubSubHandler<unknown> };\n        bucket.add(sub);\n        let disposed = false;\n        return () => {\n            if (disposed) return;\n            disposed = true;\n            const b = this.subs.get(channel);\n            if (!b) return;\n            b.delete(sub);\n            if (b.size === 0) this.subs.delete(channel);\n        };\n    }\n\n    async close(): Promise<void> {\n        this.closed = true;\n        this.subs.clear();\n    }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type {\n    ILock,\n    LockAcquireOptions,\n    LockHandle,\n} from '@objectstack/spec/contracts';\n\n/**\n * In-memory lock for single-process deployments and tests.\n *\n * Behavior:\n *   - Per-key FIFO wait queue (so `waitMs > 0` callers receive the lock\n *     in arrival order).\n *   - TTL is honored: if a holder doesn't renew before `ttlMs` elapses,\n *     the lock is auto-released and the next waiter wakes.\n *   - Fencing tokens are process-local monotonic bigints.\n */\n\nconst DEFAULT_TTL_MS = 15_000;\n\nexport interface MemoryLockOptions {\n    /** Default TTL for `acquire` when caller doesn't supply one. */\n    defaultTtlMs?: number;\n}\n\ninterface Holder {\n    fencingToken: bigint;\n    expiresAt: number;\n    released: boolean;\n    timer?: NodeJS.Timeout;\n}\n\ninterface Waiter {\n    resolve: (h: LockHandle | null) => void;\n    deadline: number;\n    opts: LockAcquireOptions;\n    timer?: NodeJS.Timeout;\n}\n\nexport class MemoryLock implements ILock {\n    private readonly holders = new Map<string, Holder>();\n    private readonly queues = new Map<string, Waiter[]>();\n    private readonly defaultTtlMs: number;\n    private fenceSeq = 0n;\n    private closed = false;\n\n    constructor(opts: MemoryLockOptions = {}) {\n        this.defaultTtlMs = opts.defaultTtlMs ?? DEFAULT_TTL_MS;\n    }\n\n    async acquire(key: string, opts: LockAcquireOptions = {}): Promise<LockHandle | null> {\n        if (this.closed) throw new Error('MemoryLock is closed');\n        const ttlMs = opts.ttlMs ?? this.defaultTtlMs;\n        const waitMs = opts.waitMs ?? 0;\n\n        if (!this.holders.has(key)) {\n            return this.grant(key, ttlMs);\n        }\n        if (waitMs <= 0) return null;\n\n        return new Promise<LockHandle | null>((resolve) => {\n            const deadline = Date.now() + waitMs;\n            const waiter: Waiter = { resolve, deadline, opts };\n            const queue = this.queues.get(key) ?? [];\n            queue.push(waiter);\n            this.queues.set(key, queue);\n            waiter.timer = setTimeout(() => {\n                const q = this.queues.get(key);\n                if (q) {\n                    const idx = q.indexOf(waiter);\n                    if (idx >= 0) q.splice(idx, 1);\n                }\n                resolve(null);\n            }, waitMs);\n        });\n    }\n\n    async withLock<T>(\n        key: string,\n        fn: (h: LockHandle) => Promise<T>,\n        opts?: LockAcquireOptions,\n    ): Promise<T | null> {\n        const handle = await this.acquire(key, opts);\n        if (!handle) return null;\n        try {\n            return await fn(handle);\n        } finally {\n            await handle.release();\n        }\n    }\n\n    async close(): Promise<void> {\n        this.closed = true;\n        for (const [, holder] of this.holders) {\n            if (holder.timer) clearTimeout(holder.timer);\n            holder.released = true;\n        }\n        this.holders.clear();\n        for (const [, q] of this.queues) {\n            for (const w of q) {\n                if (w.timer) clearTimeout(w.timer);\n                w.resolve(null);\n            }\n        }\n        this.queues.clear();\n    }\n\n    private grant(key: string, ttlMs: number): LockHandle {\n        const fencingToken = ++this.fenceSeq;\n        const holder: Holder = {\n            fencingToken,\n            expiresAt: Date.now() + ttlMs,\n            released: false,\n        };\n        holder.timer = setTimeout(() => this.expire(key, holder), ttlMs);\n        this.holders.set(key, holder);\n\n        const self = this;\n        const handle: LockHandle = {\n            key,\n            fencingToken,\n            isHeld: () => !holder.released && self.holders.get(key) === holder,\n            async renew(extendMs?: number) {\n                if (holder.released || self.holders.get(key) !== holder) {\n                    throw new Error(`Lock \"${key}\" no longer held (fence=${fencingToken})`);\n                }\n                const next = extendMs ?? ttlMs;\n                holder.expiresAt = Date.now() + next;\n                if (holder.timer) clearTimeout(holder.timer);\n                holder.timer = setTimeout(() => self.expire(key, holder), next);\n            },\n            async release() {\n                if (holder.released || self.holders.get(key) !== holder) return;\n                holder.released = true;\n                if (holder.timer) clearTimeout(holder.timer);\n                self.holders.delete(key);\n                self.handoff(key);\n            },\n        };\n        return handle;\n    }\n\n    private expire(key: string, holder: Holder): void {\n        if (holder.released) return;\n        if (this.holders.get(key) !== holder) return;\n        holder.released = true;\n        this.holders.delete(key);\n        this.handoff(key);\n    }\n\n    private handoff(key: string): void {\n        const queue = this.queues.get(key);\n        if (!queue || queue.length === 0) return;\n        const next = queue.shift()!;\n        if (next.timer) clearTimeout(next.timer);\n        if (Date.now() > next.deadline) {\n            next.resolve(null);\n            this.handoff(key);\n            return;\n        }\n        const ttlMs = next.opts.ttlMs ?? this.defaultTtlMs;\n        next.resolve(this.grant(key, ttlMs));\n        if (queue.length === 0) this.queues.delete(key);\n    }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { IKV, KVEntry, KVSetOptions } from '@objectstack/spec/contracts';\n\ninterface Entry<T = unknown> {\n    value: T;\n    version: bigint;\n    expiresAt?: number;\n    timer?: NodeJS.Timeout;\n}\n\n/**\n * In-memory coordination KV. Supports optimistic concurrency via\n * `ifVersion` and TTL via `ttl` (seconds).\n *\n * NOT a cache, NOT a database — intended for small cluster bookkeeping.\n */\nexport class MemoryKV implements IKV {\n    private readonly store = new Map<string, Entry>();\n    private closed = false;\n\n    async get<T = unknown>(key: string): Promise<KVEntry<T> | undefined> {\n        const e = this.store.get(key);\n        if (!e) return undefined;\n        if (e.expiresAt && Date.now() >= e.expiresAt) {\n            this.store.delete(key);\n            return undefined;\n        }\n        return {\n            key,\n            value: e.value as T,\n            version: e.version,\n            expiresAt: e.expiresAt,\n        };\n    }\n\n    async set<T = unknown>(\n        key: string,\n        value: T,\n        opts: KVSetOptions = {},\n    ): Promise<KVEntry<T>> {\n        if (this.closed) throw new Error('MemoryKV is closed');\n        const existing = this.store.get(key);\n        const existingVersion = existing\n            ? existing.expiresAt && Date.now() >= existing.expiresAt\n                ? 0n\n                : existing.version\n            : 0n;\n        if (opts.ifVersion !== undefined && opts.ifVersion !== existingVersion) {\n            throw new VersionMismatchError(key, opts.ifVersion, existingVersion);\n        }\n        if (existing?.timer) clearTimeout(existing.timer);\n        const version = existingVersion + 1n;\n        const expiresAt = opts.ttl && opts.ttl > 0 ? Date.now() + opts.ttl * 1000 : undefined;\n        const entry: Entry<T> = { value, version, expiresAt };\n        if (expiresAt) {\n            entry.timer = setTimeout(() => {\n                const current = this.store.get(key);\n                if (current === (entry as Entry<unknown>)) this.store.delete(key);\n            }, expiresAt - Date.now());\n        }\n        this.store.set(key, entry as Entry<unknown>);\n        return { key, value, version, expiresAt };\n    }\n\n    async delete(key: string, opts: { ifVersion?: bigint } = {}): Promise<boolean> {\n        const e = this.store.get(key);\n        if (!e) return false;\n        if (e.expiresAt && Date.now() >= e.expiresAt) {\n            this.store.delete(key);\n            return false;\n        }\n        if (opts.ifVersion !== undefined && opts.ifVersion !== e.version) {\n            throw new VersionMismatchError(key, opts.ifVersion, e.version);\n        }\n        if (e.timer) clearTimeout(e.timer);\n        this.store.delete(key);\n        return true;\n    }\n\n    async cas<T = unknown>(\n        key: string,\n        expectedVersion: bigint,\n        next: T,\n        opts: Omit<KVSetOptions, 'ifVersion'> = {},\n    ): Promise<KVEntry<T> | undefined> {\n        try {\n            return await this.set(key, next, { ...opts, ifVersion: expectedVersion });\n        } catch (err) {\n            if (err instanceof VersionMismatchError) return undefined;\n            throw err;\n        }\n    }\n\n    async close(): Promise<void> {\n        this.closed = true;\n        for (const [, e] of this.store) {\n            if (e.timer) clearTimeout(e.timer);\n        }\n        this.store.clear();\n    }\n}\n\nexport class VersionMismatchError extends Error {\n    constructor(\n        public readonly key: string,\n        public readonly expected: bigint,\n        public readonly actual: bigint,\n    ) {\n        super(\n            `KV version mismatch on \"${key}\": expected v${expected}, found v${actual}`,\n        );\n        this.name = 'VersionMismatchError';\n    }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { ICounter, CounterIncrOptions } from '@objectstack/spec/contracts';\n\n/**\n * In-memory monotonic counter. Single-process only — for cross-node id\n * allocation, use the postgres or redis driver.\n */\nexport class MemoryCounter implements ICounter {\n    private readonly counters = new Map<string, bigint>();\n    private closed = false;\n\n    async incr(key: string, opts: CounterIncrOptions = {}): Promise<bigint> {\n        if (this.closed) throw new Error('MemoryCounter is closed');\n        const by = BigInt(opts.by ?? 1);\n        const current = this.counters.get(key) ?? 0n;\n        const next = current + by;\n        this.counters.set(key, next);\n        return next;\n    }\n\n    async peek(key: string): Promise<bigint> {\n        return this.counters.get(key) ?? 0n;\n    }\n\n    async reset(key: string, value: bigint = 0n): Promise<void> {\n        if (this.closed) throw new Error('MemoryCounter is closed');\n        if (value === 0n) this.counters.delete(key);\n        else this.counters.set(key, value);\n    }\n\n    async close(): Promise<void> {\n        this.closed = true;\n        this.counters.clear();\n    }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Split-brain guard (ADR-0010, path A).\n *\n * The `memory` cluster driver keeps PubSub/Lock/KV/Counter state **per\n * process**. On a single node that is correct; across multiple replicas\n * each process holds its own state, so:\n *   - `ILock` is acquired locally by every replica -> no mutual exclusion;\n *   - `ICounter`/`IKV` versions diverge per replica;\n *   - `IPubSub` does not fan out across processes.\n *\n * This fails silently -- single-node tests and dev pass, only production\n * multi-replica corrupts. The guard turns that silent corruption into a\n * loud startup error when the operator has *declared* a multi-node\n * topology yet wired an in-process driver.\n *\n * Detection is deliberately conservative (path A): it keys off an\n * explicit operator declaration, not active peer discovery (that is the\n * optional path B in ADR-0010). It cannot know at boot whether the\n * cluster primitives are actually used cross-node, so it offers an\n * escape hatch for the rare \"replicas declared but primitives unused\"\n * case.\n */\n\n/** In-process drivers whose state does not coordinate across replicas. */\nconst IN_PROCESS_DRIVERS = new Set(['memory']);\n\n/** Environment inputs the guard reads. */\nexport interface SplitBrainGuardEnv {\n    /** `'true'` -> operator declares a multi-node deployment. */\n    OS_EXPECT_MULTI_NODE?: string;\n    /** Replica count; `> 1` -> multi-node. */\n    OS_CLUSTER_REPLICAS?: string;\n    /** `'true'` -> bypass the guard (replicas declared but primitives unused cross-node). */\n    OS_ALLOW_MEMORY_CLUSTER_MULTINODE?: string;\n}\n\nfunction isTrue(v: string | undefined): boolean {\n    return String(v).trim().toLowerCase() === 'true';\n}\n\n/**\n * True when the operator has declared a multi-node topology via\n * `OS_EXPECT_MULTI_NODE=true` or `OS_CLUSTER_REPLICAS` greater than 1.\n */\nexport function declaresMultiNode(env: SplitBrainGuardEnv = process.env): boolean {\n    if (isTrue(env.OS_EXPECT_MULTI_NODE)) return true;\n    const replicas = Number(env.OS_CLUSTER_REPLICAS);\n    return Number.isFinite(replicas) && replicas > 1;\n}\n\n/**\n * Throw if a multi-node topology is declared while the resolved cluster\n * `driver` is in-process (`memory`), unless explicitly allowed via\n * `OS_ALLOW_MEMORY_CLUSTER_MULTINODE=true`.\n *\n * Call this at startup *before* registering the cluster service so a\n * misconfiguration fails fast.\n */\nexport function assertClusterDriverSafeForTopology(\n    driver: string,\n    env: SplitBrainGuardEnv = process.env,\n): void {\n    if (!declaresMultiNode(env)) return;\n    if (!IN_PROCESS_DRIVERS.has(driver)) return;\n    if (isTrue(env.OS_ALLOW_MEMORY_CLUSTER_MULTINODE)) return;\n\n    throw new Error(\n        `ClusterServicePlugin: multi-node deployment declared ` +\n            `(OS_EXPECT_MULTI_NODE / OS_CLUSTER_REPLICAS>1) but the cluster driver is ` +\n            `in-process \"${driver}\" -- its locks/counters/pub-sub do not coordinate across ` +\n            `processes, so multiple replicas silently split-brain. Configure a remote cluster ` +\n            `driver (e.g. @objectstack/service-cluster-redis) or a DB-backed driver. To override ` +\n            `(replicas declared but cluster primitives unused cross-node), set ` +\n            `OS_ALLOW_MEMORY_CLUSTER_MULTINODE=true. See cloud ADR-0010.`,\n    );\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport type { IClusterService } from '@objectstack/spec/contracts';\nimport type { ClusterCapabilityConfigInput } from '@objectstack/spec/kernel';\nimport { defineCluster } from './cluster.js';\nimport { assertClusterDriverSafeForTopology } from './split-brain-guard.js';\n\n/**\n * Options for `ClusterServicePlugin`.\n *\n * Pass either a pre-built `cluster` instance (advanced — for tests or\n * custom drivers), or a `config` object that will be passed to\n * `defineCluster()`. If both are omitted, a memory-driver cluster is\n * created with auto-generated nodeId.\n */\nexport interface ClusterServicePluginOptions {\n    /** Pre-built cluster service. Wins over `config` when both provided. */\n    cluster?: IClusterService;\n    /** Config forwarded to `defineCluster()` when `cluster` is absent. */\n    config?: ClusterCapabilityConfigInput;\n}\n\n/**\n * Registers an `IClusterService` under the well-known service name\n * `'cluster'`. Plugins consume it via:\n *\n * ```ts\n * import type { IClusterService } from '@objectstack/spec/contracts';\n * const cluster = ctx.getService<IClusterService>('cluster');\n * await cluster.pubsub.publish('metadata.changed', payload);\n * ```\n *\n * The plugin closes the cluster on kernel shutdown.\n *\n * @example default memory driver\n *   kernel.use(new ClusterServicePlugin());\n *\n * @example explicit config\n *   kernel.use(new ClusterServicePlugin({ config: { driver: 'memory', nodeId: 'web-1' } }));\n */\nexport class ClusterServicePlugin implements Plugin {\n    name = 'com.objectstack.service.cluster';\n    version = '1.0.0';\n    type = 'standard';\n\n    private readonly options: ClusterServicePluginOptions;\n    private cluster?: IClusterService;\n    private owned = false;\n\n    constructor(options: ClusterServicePluginOptions = {}) {\n        this.options = options;\n    }\n\n    async init(ctx: PluginContext): Promise<void> {\n        if (this.options.cluster) {\n            this.cluster = this.options.cluster;\n            this.owned = false;\n        } else {\n            this.cluster = defineCluster(this.options.config ?? {});\n            this.owned = true;\n        }\n        // Split-brain guard (ADR-0010): fail fast if a multi-node topology is\n        // declared but the resolved driver is in-process. Runs before\n        // registration so a misconfiguration never half-wires the service.\n        assertClusterDriverSafeForTopology(this.cluster.driver);\n\n        ctx.registerService('cluster', this.cluster);\n        ctx.logger.info(\n            `ClusterServicePlugin: registered \"${this.cluster.driver}\" driver (node=${this.cluster.nodeId})`,\n        );\n\n        ctx.hook('kernel:shutdown', async () => {\n            if (this.owned && this.cluster) {\n                try {\n                    await this.cluster.close();\n                } catch (err) {\n                    ctx.logger.error('ClusterServicePlugin: close error', err as Error);\n                }\n            }\n        });\n    }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport type { IClusterService } from '@objectstack/spec/contracts';\n\n/**\n * Bridges the cluster pub/sub bus to the metadata service so that\n * metadata mutations on one node invalidate registry caches on peer\n * nodes. Implements the \"first real consumer\" of the cluster API.\n *\n * Implementation detail: this plugin lives in `@objectstack/service-cluster`\n * (not in `@objectstack/metadata`) to avoid forcing every metadata\n * consumer to pull the cluster service. The metadata package only needs\n * the `IPubSub` interface, which lives in `@objectstack/spec/contracts`.\n *\n * Activates only when both services are present and the metadata service\n * exposes `attachClusterPubSub()`. Late binding is achieved via the\n * `kernel:ready` lifecycle hook.\n *\n * Channel: `metadata.changed` — payload shape defined by\n * `ClusterMetadataChangedPayload` in `@objectstack/metadata`.\n *\n * See `content/docs/concepts/cluster-semantics.mdx` §5.\n */\nexport class MetadataClusterBridgePlugin implements Plugin {\n    name = 'com.objectstack.service.metadata-cluster-bridge';\n    version = '1.0.0';\n    type = 'standard';\n\n    private detach?: () => void;\n\n    async init(ctx: PluginContext): Promise<void> {\n        ctx.hook('kernel:ready', async () => {\n            let cluster: IClusterService | undefined;\n            let md: unknown;\n            try {\n                cluster = ctx.getService<IClusterService>('cluster');\n            } catch {\n                ctx.logger.debug(\n                    'MetadataClusterBridgePlugin: no \"cluster\" service registered, skipping',\n                );\n                return;\n            }\n            try {\n                md = ctx.getService<unknown>('metadata');\n            } catch {\n                ctx.logger.debug(\n                    'MetadataClusterBridgePlugin: no \"metadata\" service registered, skipping',\n                );\n                return;\n            }\n\n            const attach = (md as { attachClusterPubSub?: unknown })\n                .attachClusterPubSub;\n            if (typeof attach !== 'function') {\n                ctx.logger.warn(\n                    'MetadataClusterBridgePlugin: metadata service does not expose attachClusterPubSub(); cross-node cache invalidation disabled',\n                );\n                return;\n            }\n\n            try {\n                this.detach = (attach as (\n                    pubsub: IClusterService['pubsub'],\n                    nodeId: string,\n                ) => () => void).call(md, cluster.pubsub, cluster.nodeId);\n                ctx.logger.info(\n                    `MetadataClusterBridgePlugin: bridged metadata.changed → cluster.pubsub (node=${cluster.nodeId})`,\n                );\n            } catch (err) {\n                ctx.logger.error(\n                    'MetadataClusterBridgePlugin: attach failed',\n                    err as Error,\n                );\n            }\n        });\n\n        ctx.hook('kernel:shutdown', async () => {\n            try {\n                this.detach?.();\n            } catch (err) {\n                ctx.logger.error(\n                    'MetadataClusterBridgePlugin: detach error',\n                    err as Error,\n                );\n            }\n            this.detach = undefined;\n        });\n    }\n}\n"]}

package/dist/index.d.cts

@@ -173,6 +173,30 @@ declare class ClusterServicePlugin implements Plugin {
     init(ctx: PluginContext): Promise<void>;
 }
 
+/** Environment inputs the guard reads. */
+interface SplitBrainGuardEnv {
+    /** `'true'` -> operator declares a multi-node deployment. */
+    OS_EXPECT_MULTI_NODE?: string;
+    /** Replica count; `> 1` -> multi-node. */
+    OS_CLUSTER_REPLICAS?: string;
+    /** `'true'` -> bypass the guard (replicas declared but primitives unused cross-node). */
+    OS_ALLOW_MEMORY_CLUSTER_MULTINODE?: string;
+}
+/**
+ * True when the operator has declared a multi-node topology via
+ * `OS_EXPECT_MULTI_NODE=true` or `OS_CLUSTER_REPLICAS` greater than 1.
+ */
+declare function declaresMultiNode(env?: SplitBrainGuardEnv): boolean;
+/**
+ * Throw if a multi-node topology is declared while the resolved cluster
+ * `driver` is in-process (`memory`), unless explicitly allowed via
+ * `OS_ALLOW_MEMORY_CLUSTER_MULTINODE=true`.
+ *
+ * Call this at startup *before* registering the cluster service so a
+ * misconfiguration fails fast.
+ */
+declare function assertClusterDriverSafeForTopology(driver: string, env?: SplitBrainGuardEnv): void;
+
 /**
  * Bridges the cluster pub/sub bus to the metadata service so that
  * metadata mutations on one node invalidate registry caches on peer
@@ -200,4 +224,4 @@ declare class MetadataClusterBridgePlugin implements Plugin {
     init(ctx: PluginContext): Promise<void>;
 }
 
-export { type ClusterDriverFactory, ClusterServicePlugin, type ClusterServicePluginOptions, ComposedClusterService, type DriverFactoryConfig, MemoryCounter, MemoryKV, MemoryLock, type MemoryLockOptions, MemoryPubSub, type MemoryPubSubOptions, MetadataClusterBridgePlugin, VersionMismatchError, defineCluster, registerClusterDriver };
+export { type ClusterDriverFactory, ClusterServicePlugin, type ClusterServicePluginOptions, ComposedClusterService, type DriverFactoryConfig, MemoryCounter, MemoryKV, MemoryLock, type MemoryLockOptions, MemoryPubSub, type MemoryPubSubOptions, MetadataClusterBridgePlugin, type SplitBrainGuardEnv, VersionMismatchError, assertClusterDriverSafeForTopology, declaresMultiNode, defineCluster, registerClusterDriver };

package/dist/index.d.ts

@@ -173,6 +173,30 @@ declare class ClusterServicePlugin implements Plugin {
     init(ctx: PluginContext): Promise<void>;
 }
 
+/** Environment inputs the guard reads. */
+interface SplitBrainGuardEnv {
+    /** `'true'` -> operator declares a multi-node deployment. */
+    OS_EXPECT_MULTI_NODE?: string;
+    /** Replica count; `> 1` -> multi-node. */
+    OS_CLUSTER_REPLICAS?: string;
+    /** `'true'` -> bypass the guard (replicas declared but primitives unused cross-node). */
+    OS_ALLOW_MEMORY_CLUSTER_MULTINODE?: string;
+}
+/**
+ * True when the operator has declared a multi-node topology via
+ * `OS_EXPECT_MULTI_NODE=true` or `OS_CLUSTER_REPLICAS` greater than 1.
+ */
+declare function declaresMultiNode(env?: SplitBrainGuardEnv): boolean;
+/**
+ * Throw if a multi-node topology is declared while the resolved cluster
+ * `driver` is in-process (`memory`), unless explicitly allowed via
+ * `OS_ALLOW_MEMORY_CLUSTER_MULTINODE=true`.
+ *
+ * Call this at startup *before* registering the cluster service so a
+ * misconfiguration fails fast.
+ */
+declare function assertClusterDriverSafeForTopology(driver: string, env?: SplitBrainGuardEnv): void;
+
 /**
  * Bridges the cluster pub/sub bus to the metadata service so that
  * metadata mutations on one node invalidate registry caches on peer
@@ -200,4 +224,4 @@ declare class MetadataClusterBridgePlugin implements Plugin {
     init(ctx: PluginContext): Promise<void>;
 }
 
-export { type ClusterDriverFactory, ClusterServicePlugin, type ClusterServicePluginOptions, ComposedClusterService, type DriverFactoryConfig, MemoryCounter, MemoryKV, MemoryLock, type MemoryLockOptions, MemoryPubSub, type MemoryPubSubOptions, MetadataClusterBridgePlugin, VersionMismatchError, defineCluster, registerClusterDriver };
+export { type ClusterDriverFactory, ClusterServicePlugin, type ClusterServicePluginOptions, ComposedClusterService, type DriverFactoryConfig, MemoryCounter, MemoryKV, MemoryLock, type MemoryLockOptions, MemoryPubSub, type MemoryPubSubOptions, MetadataClusterBridgePlugin, type SplitBrainGuardEnv, VersionMismatchError, assertClusterDriverSafeForTopology, declaresMultiNode, defineCluster, registerClusterDriver };

package/dist/index.js

@@ -337,6 +337,25 @@ function generateNodeId() {
   return `node-${ts}-${rand}`;
 }
 
+// src/split-brain-guard.ts
+var IN_PROCESS_DRIVERS = /* @__PURE__ */ new Set(["memory"]);
+function isTrue(v) {
+  return String(v).trim().toLowerCase() === "true";
+}
+function declaresMultiNode(env = process.env) {
+  if (isTrue(env.OS_EXPECT_MULTI_NODE)) return true;
+  const replicas = Number(env.OS_CLUSTER_REPLICAS);
+  return Number.isFinite(replicas) && replicas > 1;
+}
+function assertClusterDriverSafeForTopology(driver, env = process.env) {
+  if (!declaresMultiNode(env)) return;
+  if (!IN_PROCESS_DRIVERS.has(driver)) return;
+  if (isTrue(env.OS_ALLOW_MEMORY_CLUSTER_MULTINODE)) return;
+  throw new Error(
+    `ClusterServicePlugin: multi-node deployment declared (OS_EXPECT_MULTI_NODE / OS_CLUSTER_REPLICAS>1) but the cluster driver is in-process "${driver}" -- its locks/counters/pub-sub do not coordinate across processes, so multiple replicas silently split-brain. Configure a remote cluster driver (e.g. @objectstack/service-cluster-redis) or a DB-backed driver. To override (replicas declared but cluster primitives unused cross-node), set OS_ALLOW_MEMORY_CLUSTER_MULTINODE=true. See cloud ADR-0010.`
+  );
+}
+
 // src/cluster-service-plugin.ts
 var ClusterServicePlugin = class {
   constructor(options = {}) {
@@ -354,6 +373,7 @@ var ClusterServicePlugin = class {
       this.cluster = defineCluster(this.options.config ?? {});
       this.owned = true;
     }
+    assertClusterDriverSafeForTopology(this.cluster.driver);
     ctx.registerService("cluster", this.cluster);
     ctx.logger.info(
       `ClusterServicePlugin: registered "${this.cluster.driver}" driver (node=${this.cluster.nodeId})`
@@ -438,6 +458,8 @@ export {
   MemoryPubSub,
   MetadataClusterBridgePlugin,
   VersionMismatchError,
+  assertClusterDriverSafeForTopology,
+  declaresMultiNode,
   defineCluster,
   registerClusterDriver
 };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/cluster.ts","../src/memory/pubsub.ts","../src/memory/lock.ts","../src/memory/kv.ts","../src/memory/counter.ts","../src/cluster-service-plugin.ts","../src/metadata-cluster-bridge-plugin.ts"],"sourcesContent":["// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type {\n    IClusterService,\n    IPubSub,\n    ILock,\n    IKV,\n    ICounter,\n} from '@objectstack/spec/contracts';\nimport type { ClusterCapabilityConfigInput } from '@objectstack/spec/kernel';\nimport { ClusterCapabilityConfigSchema } from '@objectstack/spec/kernel';\n\nimport { MemoryPubSub } from './memory/pubsub.js';\nimport { MemoryLock } from './memory/lock.js';\nimport { MemoryKV } from './memory/kv.js';\nimport { MemoryCounter } from './memory/counter.js';\n\n/**\n * Compose four cluster primitives into a single `IClusterService` facade.\n * Useful for custom driver authors who want to mix and match.\n */\nexport class ComposedClusterService implements IClusterService {\n    constructor(\n        public readonly nodeId: string,\n        public readonly driver: string,\n        public readonly pubsub: IPubSub,\n        public readonly lock: ILock,\n        public readonly kv: IKV,\n        public readonly counter: ICounter,\n    ) { }\n\n    async close(): Promise<void> {\n        // Reverse order, swallow errors so a slow close doesn't block siblings.\n        const closers = [this.counter, this.kv, this.lock, this.pubsub];\n        for (const c of closers) {\n            try {\n                await c.close();\n            } catch (err) {\n                // eslint-disable-next-line no-console\n                console.error('[ClusterService] close error:', err);\n            }\n        }\n    }\n}\n\n/**\n * Build an `IClusterService` from a `ClusterCapabilityConfig`. The only\n * driver shipped from this package is `memory`; other drivers (postgres,\n * redis, nats) live in dedicated packages and register themselves via\n * `registerClusterDriver()`.\n *\n * @example\n *   const cluster = defineCluster({ driver: 'memory' });\n *   await cluster.pubsub.publish('metadata.changed', { id: 'x' });\n */\nexport function defineCluster(\n    config: ClusterCapabilityConfigInput = {},\n): IClusterService {\n    const parsed = ClusterCapabilityConfigSchema.parse(config);\n    const nodeId = parsed.nodeId ?? generateNodeId();\n\n    if (parsed.driver === 'memory') {\n        return new ComposedClusterService(\n            nodeId,\n            'memory',\n            new MemoryPubSub({ nodeId }),\n            new MemoryLock({ defaultTtlMs: parsed.lockTtlMs }),\n            new MemoryKV(),\n            new MemoryCounter(),\n        );\n    }\n\n    const factory = driverRegistry.get(parsed.driver);\n    if (!factory) {\n        throw new Error(\n            `Cluster driver \"${parsed.driver}\" is not registered. ` +\n                `Did you forget to import @objectstack/service-cluster-${parsed.driver} ` +\n                `or call registerClusterDriver()? ` +\n                `See content/docs/concepts/cluster-semantics.mdx §6.`,\n        );\n    }\n    return factory({ ...parsed, nodeId });\n}\n\n// ---------------------------------------------------------------------------\n// Driver registry (for postgres/redis/nats/custom drivers)\n// ---------------------------------------------------------------------------\n\nexport interface DriverFactoryConfig {\n    driver: string;\n    nodeId: string;\n    url?: string;\n    useExistingPool?: boolean;\n    heartbeatMs?: number;\n    lockTtlMs?: number;\n    tenantIsolation?: string;\n    driverOptions?: Record<string, unknown>;\n}\n\nexport type ClusterDriverFactory = (config: DriverFactoryConfig) => IClusterService;\n\nconst driverRegistry = new Map<string, ClusterDriverFactory>();\n\n/**\n * Register a custom cluster driver. Driver packages (e.g.\n * `@objectstack/service-cluster-postgres`) should call this at module\n * load time so `defineCluster({ driver: 'postgres' })` resolves them.\n */\nexport function registerClusterDriver(\n    name: string,\n    factory: ClusterDriverFactory,\n): void {\n    if (name === 'memory') {\n        throw new Error('The \"memory\" driver is reserved.');\n    }\n    driverRegistry.set(name, factory);\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\nfunction generateNodeId(): string {\n    // Avoid the `crypto` import dance for a single use; this is dev-only\n    // randomness and the driver upgrades replace it.\n    const rand = Math.random().toString(36).slice(2, 10);\n    const ts = Date.now().toString(36);\n    return `node-${ts}-${rand}`;\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type {\n    IPubSub,\n    PubSubHandler,\n    PublishOptions,\n    SubscribeOptions,\n    Unsubscribe,\n} from '@objectstack/spec/contracts';\n\n/**\n * In-memory PubSub for single-process deployments and tests.\n *\n * Behavior:\n *   - Synchronous fan-out: every subscriber's handler is invoked in the\n *     same tick that `publish()` resolves. Handler errors are swallowed\n *     and logged via `onError` (so one bad subscriber can't poison the bus).\n *   - At-least-once semantics held vacuously (a single in-process delivery).\n *   - No cross-process delivery — use the redis/postgres/nats driver for\n *     real multi-node setups.\n */\nexport interface MemoryPubSubOptions {\n    /** Optional error sink for handler exceptions. Defaults to console.error. */\n    onError?: (err: unknown, channel: string) => void;\n    /** Optional node id surfaced as `fromNode` on every message. */\n    nodeId?: string;\n}\n\ninterface Subscription {\n    channel: string;\n    handler: PubSubHandler<unknown>;\n}\n\nexport class MemoryPubSub implements IPubSub {\n    private readonly subs = new Map<string, Set<Subscription>>();\n    private readonly onError: (err: unknown, channel: string) => void;\n    private readonly nodeId?: string;\n    private closed = false;\n\n    constructor(opts: MemoryPubSubOptions = {}) {\n        this.onError =\n            opts.onError ??\n            ((err, channel) => {\n                // eslint-disable-next-line no-console\n                console.error(`[MemoryPubSub] handler error on channel \"${channel}\":`, err);\n            });\n        this.nodeId = opts.nodeId;\n    }\n\n    async publish<T = unknown>(\n        channel: string,\n        payload: T,\n        _opts?: PublishOptions,\n    ): Promise<void> {\n        if (this.closed) throw new Error('MemoryPubSub is closed');\n        const bucket = this.subs.get(channel);\n        if (!bucket || bucket.size === 0) return;\n        const publishedAt = Date.now();\n        // Snapshot so handler-driven unsubscribes during dispatch are safe.\n        const snapshot = Array.from(bucket);\n        for (const sub of snapshot) {\n            try {\n                const result = sub.handler({\n                    channel,\n                    payload,\n                    publishedAt,\n                    fromNode: this.nodeId,\n                });\n                if (result && typeof (result as Promise<void>).then === 'function') {\n                    (result as Promise<void>).catch((err) => this.onError(err, channel));\n                }\n            } catch (err) {\n                this.onError(err, channel);\n            }\n        }\n    }\n\n    subscribe<T = unknown>(\n        channel: string,\n        handler: PubSubHandler<T>,\n        _opts?: SubscribeOptions,\n    ): Unsubscribe {\n        if (this.closed) throw new Error('MemoryPubSub is closed');\n        let bucket = this.subs.get(channel);\n        if (!bucket) {\n            bucket = new Set();\n            this.subs.set(channel, bucket);\n        }\n        const sub: Subscription = { channel, handler: handler as PubSubHandler<unknown> };\n        bucket.add(sub);\n        let disposed = false;\n        return () => {\n            if (disposed) return;\n            disposed = true;\n            const b = this.subs.get(channel);\n            if (!b) return;\n            b.delete(sub);\n            if (b.size === 0) this.subs.delete(channel);\n        };\n    }\n\n    async close(): Promise<void> {\n        this.closed = true;\n        this.subs.clear();\n    }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type {\n    ILock,\n    LockAcquireOptions,\n    LockHandle,\n} from '@objectstack/spec/contracts';\n\n/**\n * In-memory lock for single-process deployments and tests.\n *\n * Behavior:\n *   - Per-key FIFO wait queue (so `waitMs > 0` callers receive the lock\n *     in arrival order).\n *   - TTL is honored: if a holder doesn't renew before `ttlMs` elapses,\n *     the lock is auto-released and the next waiter wakes.\n *   - Fencing tokens are process-local monotonic bigints.\n */\n\nconst DEFAULT_TTL_MS = 15_000;\n\nexport interface MemoryLockOptions {\n    /** Default TTL for `acquire` when caller doesn't supply one. */\n    defaultTtlMs?: number;\n}\n\ninterface Holder {\n    fencingToken: bigint;\n    expiresAt: number;\n    released: boolean;\n    timer?: NodeJS.Timeout;\n}\n\ninterface Waiter {\n    resolve: (h: LockHandle | null) => void;\n    deadline: number;\n    opts: LockAcquireOptions;\n    timer?: NodeJS.Timeout;\n}\n\nexport class MemoryLock implements ILock {\n    private readonly holders = new Map<string, Holder>();\n    private readonly queues = new Map<string, Waiter[]>();\n    private readonly defaultTtlMs: number;\n    private fenceSeq = 0n;\n    private closed = false;\n\n    constructor(opts: MemoryLockOptions = {}) {\n        this.defaultTtlMs = opts.defaultTtlMs ?? DEFAULT_TTL_MS;\n    }\n\n    async acquire(key: string, opts: LockAcquireOptions = {}): Promise<LockHandle | null> {\n        if (this.closed) throw new Error('MemoryLock is closed');\n        const ttlMs = opts.ttlMs ?? this.defaultTtlMs;\n        const waitMs = opts.waitMs ?? 0;\n\n        if (!this.holders.has(key)) {\n            return this.grant(key, ttlMs);\n        }\n        if (waitMs <= 0) return null;\n\n        return new Promise<LockHandle | null>((resolve) => {\n            const deadline = Date.now() + waitMs;\n            const waiter: Waiter = { resolve, deadline, opts };\n            const queue = this.queues.get(key) ?? [];\n            queue.push(waiter);\n            this.queues.set(key, queue);\n            waiter.timer = setTimeout(() => {\n                const q = this.queues.get(key);\n                if (q) {\n                    const idx = q.indexOf(waiter);\n                    if (idx >= 0) q.splice(idx, 1);\n                }\n                resolve(null);\n            }, waitMs);\n        });\n    }\n\n    async withLock<T>(\n        key: string,\n        fn: (h: LockHandle) => Promise<T>,\n        opts?: LockAcquireOptions,\n    ): Promise<T | null> {\n        const handle = await this.acquire(key, opts);\n        if (!handle) return null;\n        try {\n            return await fn(handle);\n        } finally {\n            await handle.release();\n        }\n    }\n\n    async close(): Promise<void> {\n        this.closed = true;\n        for (const [, holder] of this.holders) {\n            if (holder.timer) clearTimeout(holder.timer);\n            holder.released = true;\n        }\n        this.holders.clear();\n        for (const [, q] of this.queues) {\n            for (const w of q) {\n                if (w.timer) clearTimeout(w.timer);\n                w.resolve(null);\n            }\n        }\n        this.queues.clear();\n    }\n\n    private grant(key: string, ttlMs: number): LockHandle {\n        const fencingToken = ++this.fenceSeq;\n        const holder: Holder = {\n            fencingToken,\n            expiresAt: Date.now() + ttlMs,\n            released: false,\n        };\n        holder.timer = setTimeout(() => this.expire(key, holder), ttlMs);\n        this.holders.set(key, holder);\n\n        const self = this;\n        const handle: LockHandle = {\n            key,\n            fencingToken,\n            isHeld: () => !holder.released && self.holders.get(key) === holder,\n            async renew(extendMs?: number) {\n                if (holder.released || self.holders.get(key) !== holder) {\n                    throw new Error(`Lock \"${key}\" no longer held (fence=${fencingToken})`);\n                }\n                const next = extendMs ?? ttlMs;\n                holder.expiresAt = Date.now() + next;\n                if (holder.timer) clearTimeout(holder.timer);\n                holder.timer = setTimeout(() => self.expire(key, holder), next);\n            },\n            async release() {\n                if (holder.released || self.holders.get(key) !== holder) return;\n                holder.released = true;\n                if (holder.timer) clearTimeout(holder.timer);\n                self.holders.delete(key);\n                self.handoff(key);\n            },\n        };\n        return handle;\n    }\n\n    private expire(key: string, holder: Holder): void {\n        if (holder.released) return;\n        if (this.holders.get(key) !== holder) return;\n        holder.released = true;\n        this.holders.delete(key);\n        this.handoff(key);\n    }\n\n    private handoff(key: string): void {\n        const queue = this.queues.get(key);\n        if (!queue || queue.length === 0) return;\n        const next = queue.shift()!;\n        if (next.timer) clearTimeout(next.timer);\n        if (Date.now() > next.deadline) {\n            next.resolve(null);\n            this.handoff(key);\n            return;\n        }\n        const ttlMs = next.opts.ttlMs ?? this.defaultTtlMs;\n        next.resolve(this.grant(key, ttlMs));\n        if (queue.length === 0) this.queues.delete(key);\n    }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { IKV, KVEntry, KVSetOptions } from '@objectstack/spec/contracts';\n\ninterface Entry<T = unknown> {\n    value: T;\n    version: bigint;\n    expiresAt?: number;\n    timer?: NodeJS.Timeout;\n}\n\n/**\n * In-memory coordination KV. Supports optimistic concurrency via\n * `ifVersion` and TTL via `ttl` (seconds).\n *\n * NOT a cache, NOT a database — intended for small cluster bookkeeping.\n */\nexport class MemoryKV implements IKV {\n    private readonly store = new Map<string, Entry>();\n    private closed = false;\n\n    async get<T = unknown>(key: string): Promise<KVEntry<T> | undefined> {\n        const e = this.store.get(key);\n        if (!e) return undefined;\n        if (e.expiresAt && Date.now() >= e.expiresAt) {\n            this.store.delete(key);\n            return undefined;\n        }\n        return {\n            key,\n            value: e.value as T,\n            version: e.version,\n            expiresAt: e.expiresAt,\n        };\n    }\n\n    async set<T = unknown>(\n        key: string,\n        value: T,\n        opts: KVSetOptions = {},\n    ): Promise<KVEntry<T>> {\n        if (this.closed) throw new Error('MemoryKV is closed');\n        const existing = this.store.get(key);\n        const existingVersion = existing\n            ? existing.expiresAt && Date.now() >= existing.expiresAt\n                ? 0n\n                : existing.version\n            : 0n;\n        if (opts.ifVersion !== undefined && opts.ifVersion !== existingVersion) {\n            throw new VersionMismatchError(key, opts.ifVersion, existingVersion);\n        }\n        if (existing?.timer) clearTimeout(existing.timer);\n        const version = existingVersion + 1n;\n        const expiresAt = opts.ttl && opts.ttl > 0 ? Date.now() + opts.ttl * 1000 : undefined;\n        const entry: Entry<T> = { value, version, expiresAt };\n        if (expiresAt) {\n            entry.timer = setTimeout(() => {\n                const current = this.store.get(key);\n                if (current === (entry as Entry<unknown>)) this.store.delete(key);\n            }, expiresAt - Date.now());\n        }\n        this.store.set(key, entry as Entry<unknown>);\n        return { key, value, version, expiresAt };\n    }\n\n    async delete(key: string, opts: { ifVersion?: bigint } = {}): Promise<boolean> {\n        const e = this.store.get(key);\n        if (!e) return false;\n        if (e.expiresAt && Date.now() >= e.expiresAt) {\n            this.store.delete(key);\n            return false;\n        }\n        if (opts.ifVersion !== undefined && opts.ifVersion !== e.version) {\n            throw new VersionMismatchError(key, opts.ifVersion, e.version);\n        }\n        if (e.timer) clearTimeout(e.timer);\n        this.store.delete(key);\n        return true;\n    }\n\n    async cas<T = unknown>(\n        key: string,\n        expectedVersion: bigint,\n        next: T,\n        opts: Omit<KVSetOptions, 'ifVersion'> = {},\n    ): Promise<KVEntry<T> | undefined> {\n        try {\n            return await this.set(key, next, { ...opts, ifVersion: expectedVersion });\n        } catch (err) {\n            if (err instanceof VersionMismatchError) return undefined;\n            throw err;\n        }\n    }\n\n    async close(): Promise<void> {\n        this.closed = true;\n        for (const [, e] of this.store) {\n            if (e.timer) clearTimeout(e.timer);\n        }\n        this.store.clear();\n    }\n}\n\nexport class VersionMismatchError extends Error {\n    constructor(\n        public readonly key: string,\n        public readonly expected: bigint,\n        public readonly actual: bigint,\n    ) {\n        super(\n            `KV version mismatch on \"${key}\": expected v${expected}, found v${actual}`,\n        );\n        this.name = 'VersionMismatchError';\n    }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { ICounter, CounterIncrOptions } from '@objectstack/spec/contracts';\n\n/**\n * In-memory monotonic counter. Single-process only — for cross-node id\n * allocation, use the postgres or redis driver.\n */\nexport class MemoryCounter implements ICounter {\n    private readonly counters = new Map<string, bigint>();\n    private closed = false;\n\n    async incr(key: string, opts: CounterIncrOptions = {}): Promise<bigint> {\n        if (this.closed) throw new Error('MemoryCounter is closed');\n        const by = BigInt(opts.by ?? 1);\n        const current = this.counters.get(key) ?? 0n;\n        const next = current + by;\n        this.counters.set(key, next);\n        return next;\n    }\n\n    async peek(key: string): Promise<bigint> {\n        return this.counters.get(key) ?? 0n;\n    }\n\n    async reset(key: string, value: bigint = 0n): Promise<void> {\n        if (this.closed) throw new Error('MemoryCounter is closed');\n        if (value === 0n) this.counters.delete(key);\n        else this.counters.set(key, value);\n    }\n\n    async close(): Promise<void> {\n        this.closed = true;\n        this.counters.clear();\n    }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport type { IClusterService } from '@objectstack/spec/contracts';\nimport type { ClusterCapabilityConfigInput } from '@objectstack/spec/kernel';\nimport { defineCluster } from './cluster.js';\n\n/**\n * Options for `ClusterServicePlugin`.\n *\n * Pass either a pre-built `cluster` instance (advanced — for tests or\n * custom drivers), or a `config` object that will be passed to\n * `defineCluster()`. If both are omitted, a memory-driver cluster is\n * created with auto-generated nodeId.\n */\nexport interface ClusterServicePluginOptions {\n    /** Pre-built cluster service. Wins over `config` when both provided. */\n    cluster?: IClusterService;\n    /** Config forwarded to `defineCluster()` when `cluster` is absent. */\n    config?: ClusterCapabilityConfigInput;\n}\n\n/**\n * Registers an `IClusterService` under the well-known service name\n * `'cluster'`. Plugins consume it via:\n *\n * ```ts\n * import type { IClusterService } from '@objectstack/spec/contracts';\n * const cluster = ctx.getService<IClusterService>('cluster');\n * await cluster.pubsub.publish('metadata.changed', payload);\n * ```\n *\n * The plugin closes the cluster on kernel shutdown.\n *\n * @example default memory driver\n *   kernel.use(new ClusterServicePlugin());\n *\n * @example explicit config\n *   kernel.use(new ClusterServicePlugin({ config: { driver: 'memory', nodeId: 'web-1' } }));\n */\nexport class ClusterServicePlugin implements Plugin {\n    name = 'com.objectstack.service.cluster';\n    version = '1.0.0';\n    type = 'standard';\n\n    private readonly options: ClusterServicePluginOptions;\n    private cluster?: IClusterService;\n    private owned = false;\n\n    constructor(options: ClusterServicePluginOptions = {}) {\n        this.options = options;\n    }\n\n    async init(ctx: PluginContext): Promise<void> {\n        if (this.options.cluster) {\n            this.cluster = this.options.cluster;\n            this.owned = false;\n        } else {\n            this.cluster = defineCluster(this.options.config ?? {});\n            this.owned = true;\n        }\n        ctx.registerService('cluster', this.cluster);\n        ctx.logger.info(\n            `ClusterServicePlugin: registered \"${this.cluster.driver}\" driver (node=${this.cluster.nodeId})`,\n        );\n\n        ctx.hook('kernel:shutdown', async () => {\n            if (this.owned && this.cluster) {\n                try {\n                    await this.cluster.close();\n                } catch (err) {\n                    ctx.logger.error('ClusterServicePlugin: close error', err as Error);\n                }\n            }\n        });\n    }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport type { IClusterService } from '@objectstack/spec/contracts';\n\n/**\n * Bridges the cluster pub/sub bus to the metadata service so that\n * metadata mutations on one node invalidate registry caches on peer\n * nodes. Implements the \"first real consumer\" of the cluster API.\n *\n * Implementation detail: this plugin lives in `@objectstack/service-cluster`\n * (not in `@objectstack/metadata`) to avoid forcing every metadata\n * consumer to pull the cluster service. The metadata package only needs\n * the `IPubSub` interface, which lives in `@objectstack/spec/contracts`.\n *\n * Activates only when both services are present and the metadata service\n * exposes `attachClusterPubSub()`. Late binding is achieved via the\n * `kernel:ready` lifecycle hook.\n *\n * Channel: `metadata.changed` — payload shape defined by\n * `ClusterMetadataChangedPayload` in `@objectstack/metadata`.\n *\n * See `content/docs/concepts/cluster-semantics.mdx` §5.\n */\nexport class MetadataClusterBridgePlugin implements Plugin {\n    name = 'com.objectstack.service.metadata-cluster-bridge';\n    version = '1.0.0';\n    type = 'standard';\n\n    private detach?: () => void;\n\n    async init(ctx: PluginContext): Promise<void> {\n        ctx.hook('kernel:ready', async () => {\n            let cluster: IClusterService | undefined;\n            let md: unknown;\n            try {\n                cluster = ctx.getService<IClusterService>('cluster');\n            } catch {\n                ctx.logger.debug(\n                    'MetadataClusterBridgePlugin: no \"cluster\" service registered, skipping',\n                );\n                return;\n            }\n            try {\n                md = ctx.getService<unknown>('metadata');\n            } catch {\n                ctx.logger.debug(\n                    'MetadataClusterBridgePlugin: no \"metadata\" service registered, skipping',\n                );\n                return;\n            }\n\n            const attach = (md as { attachClusterPubSub?: unknown })\n                .attachClusterPubSub;\n            if (typeof attach !== 'function') {\n                ctx.logger.warn(\n                    'MetadataClusterBridgePlugin: metadata service does not expose attachClusterPubSub(); cross-node cache invalidation disabled',\n                );\n                return;\n            }\n\n            try {\n                this.detach = (attach as (\n                    pubsub: IClusterService['pubsub'],\n                    nodeId: string,\n                ) => () => void).call(md, cluster.pubsub, cluster.nodeId);\n                ctx.logger.info(\n                    `MetadataClusterBridgePlugin: bridged metadata.changed → cluster.pubsub (node=${cluster.nodeId})`,\n                );\n            } catch (err) {\n                ctx.logger.error(\n                    'MetadataClusterBridgePlugin: attach failed',\n                    err as Error,\n                );\n            }\n        });\n\n        ctx.hook('kernel:shutdown', async () => {\n            try {\n                this.detach?.();\n            } catch (err) {\n                ctx.logger.error(\n                    'MetadataClusterBridgePlugin: detach error',\n                    err as Error,\n                );\n            }\n            this.detach = undefined;\n        });\n    }\n}\n"],"mappings":";AAUA,SAAS,qCAAqC;;;ACuBvC,IAAM,eAAN,MAAsC;AAAA,EAMzC,YAAY,OAA4B,CAAC,GAAG;AAL5C,SAAiB,OAAO,oBAAI,IAA+B;AAG3D,SAAQ,SAAS;AAGb,SAAK,UACD,KAAK,YACJ,CAAC,KAAK,YAAY;AAEf,cAAQ,MAAM,4CAA4C,OAAO,MAAM,GAAG;AAAA,IAC9E;AACJ,SAAK,SAAS,KAAK;AAAA,EACvB;AAAA,EAEA,MAAM,QACF,SACA,SACA,OACa;AACb,QAAI,KAAK,OAAQ,OAAM,IAAI,MAAM,wBAAwB;AACzD,UAAM,SAAS,KAAK,KAAK,IAAI,OAAO;AACpC,QAAI,CAAC,UAAU,OAAO,SAAS,EAAG;AAClC,UAAM,cAAc,KAAK,IAAI;AAE7B,UAAM,WAAW,MAAM,KAAK,MAAM;AAClC,eAAW,OAAO,UAAU;AACxB,UAAI;AACA,cAAM,SAAS,IAAI,QAAQ;AAAA,UACvB;AAAA,UACA;AAAA,UACA;AAAA,UACA,UAAU,KAAK;AAAA,QACnB,CAAC;AACD,YAAI,UAAU,OAAQ,OAAyB,SAAS,YAAY;AAChE,UAAC,OAAyB,MAAM,CAAC,QAAQ,KAAK,QAAQ,KAAK,OAAO,CAAC;AAAA,QACvE;AAAA,MACJ,SAAS,KAAK;AACV,aAAK,QAAQ,KAAK,OAAO;AAAA,MAC7B;AAAA,IACJ;AAAA,EACJ;AAAA,EAEA,UACI,SACA,SACA,OACW;AACX,QAAI,KAAK,OAAQ,OAAM,IAAI,MAAM,wBAAwB;AACzD,QAAI,SAAS,KAAK,KAAK,IAAI,OAAO;AAClC,QAAI,CAAC,QAAQ;AACT,eAAS,oBAAI,IAAI;AACjB,WAAK,KAAK,IAAI,SAAS,MAAM;AAAA,IACjC;AACA,UAAM,MAAoB,EAAE,SAAS,QAA2C;AAChF,WAAO,IAAI,GAAG;AACd,QAAI,WAAW;AACf,WAAO,MAAM;AACT,UAAI,SAAU;AACd,iBAAW;AACX,YAAM,IAAI,KAAK,KAAK,IAAI,OAAO;AAC/B,UAAI,CAAC,EAAG;AACR,QAAE,OAAO,GAAG;AACZ,UAAI,EAAE,SAAS,EAAG,MAAK,KAAK,OAAO,OAAO;AAAA,IAC9C;AAAA,EACJ;AAAA,EAEA,MAAM,QAAuB;AACzB,SAAK,SAAS;AACd,SAAK,KAAK,MAAM;AAAA,EACpB;AACJ;;;ACtFA,IAAM,iBAAiB;AAqBhB,IAAM,aAAN,MAAkC;AAAA,EAOrC,YAAY,OAA0B,CAAC,GAAG;AAN1C,SAAiB,UAAU,oBAAI,IAAoB;AACnD,SAAiB,SAAS,oBAAI,IAAsB;AAEpD,SAAQ,WAAW;AACnB,SAAQ,SAAS;AAGb,SAAK,eAAe,KAAK,gBAAgB;AAAA,EAC7C;AAAA,EAEA,MAAM,QAAQ,KAAa,OAA2B,CAAC,GAA+B;AAClF,QAAI,KAAK,OAAQ,OAAM,IAAI,MAAM,sBAAsB;AACvD,UAAM,QAAQ,KAAK,SAAS,KAAK;AACjC,UAAM,SAAS,KAAK,UAAU;AAE9B,QAAI,CAAC,KAAK,QAAQ,IAAI,GAAG,GAAG;AACxB,aAAO,KAAK,MAAM,KAAK,KAAK;AAAA,IAChC;AACA,QAAI,UAAU,EAAG,QAAO;AAExB,WAAO,IAAI,QAA2B,CAAC,YAAY;AAC/C,YAAM,WAAW,KAAK,IAAI,IAAI;AAC9B,YAAM,SAAiB,EAAE,SAAS,UAAU,KAAK;AACjD,YAAM,QAAQ,KAAK,OAAO,IAAI,GAAG,KAAK,CAAC;AACvC,YAAM,KAAK,MAAM;AACjB,WAAK,OAAO,IAAI,KAAK,KAAK;AAC1B,aAAO,QAAQ,WAAW,MAAM;AAC5B,cAAM,IAAI,KAAK,OAAO,IAAI,GAAG;AAC7B,YAAI,GAAG;AACH,gBAAM,MAAM,EAAE,QAAQ,MAAM;AAC5B,cAAI,OAAO,EAAG,GAAE,OAAO,KAAK,CAAC;AAAA,QACjC;AACA,gBAAQ,IAAI;AAAA,MAChB,GAAG,MAAM;AAAA,IACb,CAAC;AAAA,EACL;AAAA,EAEA,MAAM,SACF,KACA,IACA,MACiB;AACjB,UAAM,SAAS,MAAM,KAAK,QAAQ,KAAK,IAAI;AAC3C,QAAI,CAAC,OAAQ,QAAO;AACpB,QAAI;AACA,aAAO,MAAM,GAAG,MAAM;AAAA,IAC1B,UAAE;AACE,YAAM,OAAO,QAAQ;AAAA,IACzB;AAAA,EACJ;AAAA,EAEA,MAAM,QAAuB;AACzB,SAAK,SAAS;AACd,eAAW,CAAC,EAAE,MAAM,KAAK,KAAK,SAAS;AACnC,UAAI,OAAO,MAAO,cAAa,OAAO,KAAK;AAC3C,aAAO,WAAW;AAAA,IACtB;AACA,SAAK,QAAQ,MAAM;AACnB,eAAW,CAAC,EAAE,CAAC,KAAK,KAAK,QAAQ;AAC7B,iBAAW,KAAK,GAAG;AACf,YAAI,EAAE,MAAO,cAAa,EAAE,KAAK;AACjC,UAAE,QAAQ,IAAI;AAAA,MAClB;AAAA,IACJ;AACA,SAAK,OAAO,MAAM;AAAA,EACtB;AAAA,EAEQ,MAAM,KAAa,OAA2B;AAClD,UAAM,eAAe,EAAE,KAAK;AAC5B,UAAM,SAAiB;AAAA,MACnB;AAAA,MACA,WAAW,KAAK,IAAI,IAAI;AAAA,MACxB,UAAU;AAAA,IACd;AACA,WAAO,QAAQ,WAAW,MAAM,KAAK,OAAO,KAAK,MAAM,GAAG,KAAK;AAC/D,SAAK,QAAQ,IAAI,KAAK,MAAM;AAE5B,UAAM,OAAO;AACb,UAAM,SAAqB;AAAA,MACvB;AAAA,MACA;AAAA,MACA,QAAQ,MAAM,CAAC,OAAO,YAAY,KAAK,QAAQ,IAAI,GAAG,MAAM;AAAA,MAC5D,MAAM,MAAM,UAAmB;AAC3B,YAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,GAAG,MAAM,QAAQ;AACrD,gBAAM,IAAI,MAAM,SAAS,GAAG,2BAA2B,YAAY,GAAG;AAAA,QAC1E;AACA,cAAM,OAAO,YAAY;AACzB,eAAO,YAAY,KAAK,IAAI,IAAI;AAChC,YAAI,OAAO,MAAO,cAAa,OAAO,KAAK;AAC3C,eAAO,QAAQ,WAAW,MAAM,KAAK,OAAO,KAAK,MAAM,GAAG,IAAI;AAAA,MAClE;AAAA,MACA,MAAM,UAAU;AACZ,YAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,GAAG,MAAM,OAAQ;AACzD,eAAO,WAAW;AAClB,YAAI,OAAO,MAAO,cAAa,OAAO,KAAK;AAC3C,aAAK,QAAQ,OAAO,GAAG;AACvB,aAAK,QAAQ,GAAG;AAAA,MACpB;AAAA,IACJ;AACA,WAAO;AAAA,EACX;AAAA,EAEQ,OAAO,KAAa,QAAsB;AAC9C,QAAI,OAAO,SAAU;AACrB,QAAI,KAAK,QAAQ,IAAI,GAAG,MAAM,OAAQ;AACtC,WAAO,WAAW;AAClB,SAAK,QAAQ,OAAO,GAAG;AACvB,SAAK,QAAQ,GAAG;AAAA,EACpB;AAAA,EAEQ,QAAQ,KAAmB;AAC/B,UAAM,QAAQ,KAAK,OAAO,IAAI,GAAG;AACjC,QAAI,CAAC,SAAS,MAAM,WAAW,EAAG;AAClC,UAAM,OAAO,MAAM,MAAM;AACzB,QAAI,KAAK,MAAO,cAAa,KAAK,KAAK;AACvC,QAAI,KAAK,IAAI,IAAI,KAAK,UAAU;AAC5B,WAAK,QAAQ,IAAI;AACjB,WAAK,QAAQ,GAAG;AAChB;AAAA,IACJ;AACA,UAAM,QAAQ,KAAK,KAAK,SAAS,KAAK;AACtC,SAAK,QAAQ,KAAK,MAAM,KAAK,KAAK,CAAC;AACnC,QAAI,MAAM,WAAW,EAAG,MAAK,OAAO,OAAO,GAAG;AAAA,EAClD;AACJ;;;ACpJO,IAAM,WAAN,MAA8B;AAAA,EAA9B;AACH,SAAiB,QAAQ,oBAAI,IAAmB;AAChD,SAAQ,SAAS;AAAA;AAAA,EAEjB,MAAM,IAAiB,KAA8C;AACjE,UAAM,IAAI,KAAK,MAAM,IAAI,GAAG;AAC5B,QAAI,CAAC,EAAG,QAAO;AACf,QAAI,EAAE,aAAa,KAAK,IAAI,KAAK,EAAE,WAAW;AAC1C,WAAK,MAAM,OAAO,GAAG;AACrB,aAAO;AAAA,IACX;AACA,WAAO;AAAA,MACH;AAAA,MACA,OAAO,EAAE;AAAA,MACT,SAAS,EAAE;AAAA,MACX,WAAW,EAAE;AAAA,IACjB;AAAA,EACJ;AAAA,EAEA,MAAM,IACF,KACA,OACA,OAAqB,CAAC,GACH;AACnB,QAAI,KAAK,OAAQ,OAAM,IAAI,MAAM,oBAAoB;AACrD,UAAM,WAAW,KAAK,MAAM,IAAI,GAAG;AACnC,UAAM,kBAAkB,WAClB,SAAS,aAAa,KAAK,IAAI,KAAK,SAAS,YACzC,KACA,SAAS,UACb;AACN,QAAI,KAAK,cAAc,UAAa,KAAK,cAAc,iBAAiB;AACpE,YAAM,IAAI,qBAAqB,KAAK,KAAK,WAAW,eAAe;AAAA,IACvE;AACA,QAAI,UAAU,MAAO,cAAa,SAAS,KAAK;AAChD,UAAM,UAAU,kBAAkB;AAClC,UAAM,YAAY,KAAK,OAAO,KAAK,MAAM,IAAI,KAAK,IAAI,IAAI,KAAK,MAAM,MAAO;AAC5E,UAAM,QAAkB,EAAE,OAAO,SAAS,UAAU;AACpD,QAAI,WAAW;AACX,YAAM,QAAQ,WAAW,MAAM;AAC3B,cAAM,UAAU,KAAK,MAAM,IAAI,GAAG;AAClC,YAAI,YAAa,MAA0B,MAAK,MAAM,OAAO,GAAG;AAAA,MACpE,GAAG,YAAY,KAAK,IAAI,CAAC;AAAA,IAC7B;AACA,SAAK,MAAM,IAAI,KAAK,KAAuB;AAC3C,WAAO,EAAE,KAAK,OAAO,SAAS,UAAU;AAAA,EAC5C;AAAA,EAEA,MAAM,OAAO,KAAa,OAA+B,CAAC,GAAqB;AAC3E,UAAM,IAAI,KAAK,MAAM,IAAI,GAAG;AAC5B,QAAI,CAAC,EAAG,QAAO;AACf,QAAI,EAAE,aAAa,KAAK,IAAI,KAAK,EAAE,WAAW;AAC1C,WAAK,MAAM,OAAO,GAAG;AACrB,aAAO;AAAA,IACX;AACA,QAAI,KAAK,cAAc,UAAa,KAAK,cAAc,EAAE,SAAS;AAC9D,YAAM,IAAI,qBAAqB,KAAK,KAAK,WAAW,EAAE,OAAO;AAAA,IACjE;AACA,QAAI,EAAE,MAAO,cAAa,EAAE,KAAK;AACjC,SAAK,MAAM,OAAO,GAAG;AACrB,WAAO;AAAA,EACX;AAAA,EAEA,MAAM,IACF,KACA,iBACA,MACA,OAAwC,CAAC,GACV;AAC/B,QAAI;AACA,aAAO,MAAM,KAAK,IAAI,KAAK,MAAM,EAAE,GAAG,MAAM,WAAW,gBAAgB,CAAC;AAAA,IAC5E,SAAS,KAAK;AACV,UAAI,eAAe,qBAAsB,QAAO;AAChD,YAAM;AAAA,IACV;AAAA,EACJ;AAAA,EAEA,MAAM,QAAuB;AACzB,SAAK,SAAS;AACd,eAAW,CAAC,EAAE,CAAC,KAAK,KAAK,OAAO;AAC5B,UAAI,EAAE,MAAO,cAAa,EAAE,KAAK;AAAA,IACrC;AACA,SAAK,MAAM,MAAM;AAAA,EACrB;AACJ;AAEO,IAAM,uBAAN,cAAmC,MAAM;AAAA,EAC5C,YACoB,KACA,UACA,QAClB;AACE;AAAA,MACI,2BAA2B,GAAG,gBAAgB,QAAQ,YAAY,MAAM;AAAA,IAC5E;AANgB;AACA;AACA;AAKhB,SAAK,OAAO;AAAA,EAChB;AACJ;;;AC1GO,IAAM,gBAAN,MAAwC;AAAA,EAAxC;AACH,SAAiB,WAAW,oBAAI,IAAoB;AACpD,SAAQ,SAAS;AAAA;AAAA,EAEjB,MAAM,KAAK,KAAa,OAA2B,CAAC,GAAoB;AACpE,QAAI,KAAK,OAAQ,OAAM,IAAI,MAAM,yBAAyB;AAC1D,UAAM,KAAK,OAAO,KAAK,MAAM,CAAC;AAC9B,UAAM,UAAU,KAAK,SAAS,IAAI,GAAG,KAAK;AAC1C,UAAM,OAAO,UAAU;AACvB,SAAK,SAAS,IAAI,KAAK,IAAI;AAC3B,WAAO;AAAA,EACX;AAAA,EAEA,MAAM,KAAK,KAA8B;AACrC,WAAO,KAAK,SAAS,IAAI,GAAG,KAAK;AAAA,EACrC;AAAA,EAEA,MAAM,MAAM,KAAa,QAAgB,IAAmB;AACxD,QAAI,KAAK,OAAQ,OAAM,IAAI,MAAM,yBAAyB;AAC1D,QAAI,UAAU,GAAI,MAAK,SAAS,OAAO,GAAG;AAAA,QACrC,MAAK,SAAS,IAAI,KAAK,KAAK;AAAA,EACrC;AAAA,EAEA,MAAM,QAAuB;AACzB,SAAK,SAAS;AACd,SAAK,SAAS,MAAM;AAAA,EACxB;AACJ;;;AJdO,IAAM,yBAAN,MAAwD;AAAA,EAC3D,YACoB,QACA,QACA,QACA,MACA,IACA,SAClB;AANkB;AACA;AACA;AACA;AACA;AACA;AAAA,EAChB;AAAA,EAEJ,MAAM,QAAuB;AAEzB,UAAM,UAAU,CAAC,KAAK,SAAS,KAAK,IAAI,KAAK,MAAM,KAAK,MAAM;AAC9D,eAAW,KAAK,SAAS;AACrB,UAAI;AACA,cAAM,EAAE,MAAM;AAAA,MAClB,SAAS,KAAK;AAEV,gBAAQ,MAAM,iCAAiC,GAAG;AAAA,MACtD;AAAA,IACJ;AAAA,EACJ;AACJ;AAYO,SAAS,cACZ,SAAuC,CAAC,GACzB;AACf,QAAM,SAAS,8BAA8B,MAAM,MAAM;AACzD,QAAM,SAAS,OAAO,UAAU,eAAe;AAE/C,MAAI,OAAO,WAAW,UAAU;AAC5B,WAAO,IAAI;AAAA,MACP;AAAA,MACA;AAAA,MACA,IAAI,aAAa,EAAE,OAAO,CAAC;AAAA,MAC3B,IAAI,WAAW,EAAE,cAAc,OAAO,UAAU,CAAC;AAAA,MACjD,IAAI,SAAS;AAAA,MACb,IAAI,cAAc;AAAA,IACtB;AAAA,EACJ;AAEA,QAAM,UAAU,eAAe,IAAI,OAAO,MAAM;AAChD,MAAI,CAAC,SAAS;AACV,UAAM,IAAI;AAAA,MACN,mBAAmB,OAAO,MAAM,8EAC6B,OAAO,MAAM;AAAA,IAG9E;AAAA,EACJ;AACA,SAAO,QAAQ,EAAE,GAAG,QAAQ,OAAO,CAAC;AACxC;AAmBA,IAAM,iBAAiB,oBAAI,IAAkC;AAOtD,SAAS,sBACZ,MACA,SACI;AACJ,MAAI,SAAS,UAAU;AACnB,UAAM,IAAI,MAAM,kCAAkC;AAAA,EACtD;AACA,iBAAe,IAAI,MAAM,OAAO;AACpC;AAMA,SAAS,iBAAyB;AAG9B,QAAM,OAAO,KAAK,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,GAAG,EAAE;AACnD,QAAM,KAAK,KAAK,IAAI,EAAE,SAAS,EAAE;AACjC,SAAO,QAAQ,EAAE,IAAI,IAAI;AAC7B;;;AKxFO,IAAM,uBAAN,MAA6C;AAAA,EAShD,YAAY,UAAuC,CAAC,GAAG;AARvD,gBAAO;AACP,mBAAU;AACV,gBAAO;AAIP,SAAQ,QAAQ;AAGZ,SAAK,UAAU;AAAA,EACnB;AAAA,EAEA,MAAM,KAAK,KAAmC;AAC1C,QAAI,KAAK,QAAQ,SAAS;AACtB,WAAK,UAAU,KAAK,QAAQ;AAC5B,WAAK,QAAQ;AAAA,IACjB,OAAO;AACH,WAAK,UAAU,cAAc,KAAK,QAAQ,UAAU,CAAC,CAAC;AACtD,WAAK,QAAQ;AAAA,IACjB;AACA,QAAI,gBAAgB,WAAW,KAAK,OAAO;AAC3C,QAAI,OAAO;AAAA,MACP,qCAAqC,KAAK,QAAQ,MAAM,kBAAkB,KAAK,QAAQ,MAAM;AAAA,IACjG;AAEA,QAAI,KAAK,mBAAmB,YAAY;AACpC,UAAI,KAAK,SAAS,KAAK,SAAS;AAC5B,YAAI;AACA,gBAAM,KAAK,QAAQ,MAAM;AAAA,QAC7B,SAAS,KAAK;AACV,cAAI,OAAO,MAAM,qCAAqC,GAAY;AAAA,QACtE;AAAA,MACJ;AAAA,IACJ,CAAC;AAAA,EACL;AACJ;;;ACpDO,IAAM,8BAAN,MAAoD;AAAA,EAApD;AACH,gBAAO;AACP,mBAAU;AACV,gBAAO;AAAA;AAAA,EAIP,MAAM,KAAK,KAAmC;AAC1C,QAAI,KAAK,gBAAgB,YAAY;AACjC,UAAI;AACJ,UAAI;AACJ,UAAI;AACA,kBAAU,IAAI,WAA4B,SAAS;AAAA,MACvD,QAAQ;AACJ,YAAI,OAAO;AAAA,UACP;AAAA,QACJ;AACA;AAAA,MACJ;AACA,UAAI;AACA,aAAK,IAAI,WAAoB,UAAU;AAAA,MAC3C,QAAQ;AACJ,YAAI,OAAO;AAAA,UACP;AAAA,QACJ;AACA;AAAA,MACJ;AAEA,YAAM,SAAU,GACX;AACL,UAAI,OAAO,WAAW,YAAY;AAC9B,YAAI,OAAO;AAAA,UACP;AAAA,QACJ;AACA;AAAA,MACJ;AAEA,UAAI;AACA,aAAK,SAAU,OAGE,KAAK,IAAI,QAAQ,QAAQ,QAAQ,MAAM;AACxD,YAAI,OAAO;AAAA,UACP,qFAAgF,QAAQ,MAAM;AAAA,QAClG;AAAA,MACJ,SAAS,KAAK;AACV,YAAI,OAAO;AAAA,UACP;AAAA,UACA;AAAA,QACJ;AAAA,MACJ;AAAA,IACJ,CAAC;AAED,QAAI,KAAK,mBAAmB,YAAY;AACpC,UAAI;AACA,aAAK,SAAS;AAAA,MAClB,SAAS,KAAK;AACV,YAAI,OAAO;AAAA,UACP;AAAA,UACA;AAAA,QACJ;AAAA,MACJ;AACA,WAAK,SAAS;AAAA,IAClB,CAAC;AAAA,EACL;AACJ;","names":[]}
+{"version":3,"sources":["../src/cluster.ts","../src/memory/pubsub.ts","../src/memory/lock.ts","../src/memory/kv.ts","../src/memory/counter.ts","../src/split-brain-guard.ts","../src/cluster-service-plugin.ts","../src/metadata-cluster-bridge-plugin.ts"],"sourcesContent":["// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type {\n    IClusterService,\n    IPubSub,\n    ILock,\n    IKV,\n    ICounter,\n} from '@objectstack/spec/contracts';\nimport type { ClusterCapabilityConfigInput } from '@objectstack/spec/kernel';\nimport { ClusterCapabilityConfigSchema } from '@objectstack/spec/kernel';\n\nimport { MemoryPubSub } from './memory/pubsub.js';\nimport { MemoryLock } from './memory/lock.js';\nimport { MemoryKV } from './memory/kv.js';\nimport { MemoryCounter } from './memory/counter.js';\n\n/**\n * Compose four cluster primitives into a single `IClusterService` facade.\n * Useful for custom driver authors who want to mix and match.\n */\nexport class ComposedClusterService implements IClusterService {\n    constructor(\n        public readonly nodeId: string,\n        public readonly driver: string,\n        public readonly pubsub: IPubSub,\n        public readonly lock: ILock,\n        public readonly kv: IKV,\n        public readonly counter: ICounter,\n    ) { }\n\n    async close(): Promise<void> {\n        // Reverse order, swallow errors so a slow close doesn't block siblings.\n        const closers = [this.counter, this.kv, this.lock, this.pubsub];\n        for (const c of closers) {\n            try {\n                await c.close();\n            } catch (err) {\n                // eslint-disable-next-line no-console\n                console.error('[ClusterService] close error:', err);\n            }\n        }\n    }\n}\n\n/**\n * Build an `IClusterService` from a `ClusterCapabilityConfig`. The only\n * driver shipped from this package is `memory`; other drivers (postgres,\n * redis, nats) live in dedicated packages and register themselves via\n * `registerClusterDriver()`.\n *\n * @example\n *   const cluster = defineCluster({ driver: 'memory' });\n *   await cluster.pubsub.publish('metadata.changed', { id: 'x' });\n */\nexport function defineCluster(\n    config: ClusterCapabilityConfigInput = {},\n): IClusterService {\n    const parsed = ClusterCapabilityConfigSchema.parse(config);\n    const nodeId = parsed.nodeId ?? generateNodeId();\n\n    if (parsed.driver === 'memory') {\n        return new ComposedClusterService(\n            nodeId,\n            'memory',\n            new MemoryPubSub({ nodeId }),\n            new MemoryLock({ defaultTtlMs: parsed.lockTtlMs }),\n            new MemoryKV(),\n            new MemoryCounter(),\n        );\n    }\n\n    const factory = driverRegistry.get(parsed.driver);\n    if (!factory) {\n        throw new Error(\n            `Cluster driver \"${parsed.driver}\" is not registered. ` +\n                `Did you forget to import @objectstack/service-cluster-${parsed.driver} ` +\n                `or call registerClusterDriver()? ` +\n                `See content/docs/concepts/cluster-semantics.mdx §6.`,\n        );\n    }\n    return factory({ ...parsed, nodeId });\n}\n\n// ---------------------------------------------------------------------------\n// Driver registry (for postgres/redis/nats/custom drivers)\n// ---------------------------------------------------------------------------\n\nexport interface DriverFactoryConfig {\n    driver: string;\n    nodeId: string;\n    url?: string;\n    useExistingPool?: boolean;\n    heartbeatMs?: number;\n    lockTtlMs?: number;\n    tenantIsolation?: string;\n    driverOptions?: Record<string, unknown>;\n}\n\nexport type ClusterDriverFactory = (config: DriverFactoryConfig) => IClusterService;\n\nconst driverRegistry = new Map<string, ClusterDriverFactory>();\n\n/**\n * Register a custom cluster driver. Driver packages (e.g.\n * `@objectstack/service-cluster-postgres`) should call this at module\n * load time so `defineCluster({ driver: 'postgres' })` resolves them.\n */\nexport function registerClusterDriver(\n    name: string,\n    factory: ClusterDriverFactory,\n): void {\n    if (name === 'memory') {\n        throw new Error('The \"memory\" driver is reserved.');\n    }\n    driverRegistry.set(name, factory);\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\nfunction generateNodeId(): string {\n    // Avoid the `crypto` import dance for a single use; this is dev-only\n    // randomness and the driver upgrades replace it.\n    const rand = Math.random().toString(36).slice(2, 10);\n    const ts = Date.now().toString(36);\n    return `node-${ts}-${rand}`;\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type {\n    IPubSub,\n    PubSubHandler,\n    PublishOptions,\n    SubscribeOptions,\n    Unsubscribe,\n} from '@objectstack/spec/contracts';\n\n/**\n * In-memory PubSub for single-process deployments and tests.\n *\n * Behavior:\n *   - Synchronous fan-out: every subscriber's handler is invoked in the\n *     same tick that `publish()` resolves. Handler errors are swallowed\n *     and logged via `onError` (so one bad subscriber can't poison the bus).\n *   - At-least-once semantics held vacuously (a single in-process delivery).\n *   - No cross-process delivery — use the redis/postgres/nats driver for\n *     real multi-node setups.\n */\nexport interface MemoryPubSubOptions {\n    /** Optional error sink for handler exceptions. Defaults to console.error. */\n    onError?: (err: unknown, channel: string) => void;\n    /** Optional node id surfaced as `fromNode` on every message. */\n    nodeId?: string;\n}\n\ninterface Subscription {\n    channel: string;\n    handler: PubSubHandler<unknown>;\n}\n\nexport class MemoryPubSub implements IPubSub {\n    private readonly subs = new Map<string, Set<Subscription>>();\n    private readonly onError: (err: unknown, channel: string) => void;\n    private readonly nodeId?: string;\n    private closed = false;\n\n    constructor(opts: MemoryPubSubOptions = {}) {\n        this.onError =\n            opts.onError ??\n            ((err, channel) => {\n                // eslint-disable-next-line no-console\n                console.error(`[MemoryPubSub] handler error on channel \"${channel}\":`, err);\n            });\n        this.nodeId = opts.nodeId;\n    }\n\n    async publish<T = unknown>(\n        channel: string,\n        payload: T,\n        _opts?: PublishOptions,\n    ): Promise<void> {\n        if (this.closed) throw new Error('MemoryPubSub is closed');\n        const bucket = this.subs.get(channel);\n        if (!bucket || bucket.size === 0) return;\n        const publishedAt = Date.now();\n        // Snapshot so handler-driven unsubscribes during dispatch are safe.\n        const snapshot = Array.from(bucket);\n        for (const sub of snapshot) {\n            try {\n                const result = sub.handler({\n                    channel,\n                    payload,\n                    publishedAt,\n                    fromNode: this.nodeId,\n                });\n                if (result && typeof (result as Promise<void>).then === 'function') {\n                    (result as Promise<void>).catch((err) => this.onError(err, channel));\n                }\n            } catch (err) {\n                this.onError(err, channel);\n            }\n        }\n    }\n\n    subscribe<T = unknown>(\n        channel: string,\n        handler: PubSubHandler<T>,\n        _opts?: SubscribeOptions,\n    ): Unsubscribe {\n        if (this.closed) throw new Error('MemoryPubSub is closed');\n        let bucket = this.subs.get(channel);\n        if (!bucket) {\n            bucket = new Set();\n            this.subs.set(channel, bucket);\n        }\n        const sub: Subscription = { channel, handler: handler as PubSubHandler<unknown> };\n        bucket.add(sub);\n        let disposed = false;\n        return () => {\n            if (disposed) return;\n            disposed = true;\n            const b = this.subs.get(channel);\n            if (!b) return;\n            b.delete(sub);\n            if (b.size === 0) this.subs.delete(channel);\n        };\n    }\n\n    async close(): Promise<void> {\n        this.closed = true;\n        this.subs.clear();\n    }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type {\n    ILock,\n    LockAcquireOptions,\n    LockHandle,\n} from '@objectstack/spec/contracts';\n\n/**\n * In-memory lock for single-process deployments and tests.\n *\n * Behavior:\n *   - Per-key FIFO wait queue (so `waitMs > 0` callers receive the lock\n *     in arrival order).\n *   - TTL is honored: if a holder doesn't renew before `ttlMs` elapses,\n *     the lock is auto-released and the next waiter wakes.\n *   - Fencing tokens are process-local monotonic bigints.\n */\n\nconst DEFAULT_TTL_MS = 15_000;\n\nexport interface MemoryLockOptions {\n    /** Default TTL for `acquire` when caller doesn't supply one. */\n    defaultTtlMs?: number;\n}\n\ninterface Holder {\n    fencingToken: bigint;\n    expiresAt: number;\n    released: boolean;\n    timer?: NodeJS.Timeout;\n}\n\ninterface Waiter {\n    resolve: (h: LockHandle | null) => void;\n    deadline: number;\n    opts: LockAcquireOptions;\n    timer?: NodeJS.Timeout;\n}\n\nexport class MemoryLock implements ILock {\n    private readonly holders = new Map<string, Holder>();\n    private readonly queues = new Map<string, Waiter[]>();\n    private readonly defaultTtlMs: number;\n    private fenceSeq = 0n;\n    private closed = false;\n\n    constructor(opts: MemoryLockOptions = {}) {\n        this.defaultTtlMs = opts.defaultTtlMs ?? DEFAULT_TTL_MS;\n    }\n\n    async acquire(key: string, opts: LockAcquireOptions = {}): Promise<LockHandle | null> {\n        if (this.closed) throw new Error('MemoryLock is closed');\n        const ttlMs = opts.ttlMs ?? this.defaultTtlMs;\n        const waitMs = opts.waitMs ?? 0;\n\n        if (!this.holders.has(key)) {\n            return this.grant(key, ttlMs);\n        }\n        if (waitMs <= 0) return null;\n\n        return new Promise<LockHandle | null>((resolve) => {\n            const deadline = Date.now() + waitMs;\n            const waiter: Waiter = { resolve, deadline, opts };\n            const queue = this.queues.get(key) ?? [];\n            queue.push(waiter);\n            this.queues.set(key, queue);\n            waiter.timer = setTimeout(() => {\n                const q = this.queues.get(key);\n                if (q) {\n                    const idx = q.indexOf(waiter);\n                    if (idx >= 0) q.splice(idx, 1);\n                }\n                resolve(null);\n            }, waitMs);\n        });\n    }\n\n    async withLock<T>(\n        key: string,\n        fn: (h: LockHandle) => Promise<T>,\n        opts?: LockAcquireOptions,\n    ): Promise<T | null> {\n        const handle = await this.acquire(key, opts);\n        if (!handle) return null;\n        try {\n            return await fn(handle);\n        } finally {\n            await handle.release();\n        }\n    }\n\n    async close(): Promise<void> {\n        this.closed = true;\n        for (const [, holder] of this.holders) {\n            if (holder.timer) clearTimeout(holder.timer);\n            holder.released = true;\n        }\n        this.holders.clear();\n        for (const [, q] of this.queues) {\n            for (const w of q) {\n                if (w.timer) clearTimeout(w.timer);\n                w.resolve(null);\n            }\n        }\n        this.queues.clear();\n    }\n\n    private grant(key: string, ttlMs: number): LockHandle {\n        const fencingToken = ++this.fenceSeq;\n        const holder: Holder = {\n            fencingToken,\n            expiresAt: Date.now() + ttlMs,\n            released: false,\n        };\n        holder.timer = setTimeout(() => this.expire(key, holder), ttlMs);\n        this.holders.set(key, holder);\n\n        const self = this;\n        const handle: LockHandle = {\n            key,\n            fencingToken,\n            isHeld: () => !holder.released && self.holders.get(key) === holder,\n            async renew(extendMs?: number) {\n                if (holder.released || self.holders.get(key) !== holder) {\n                    throw new Error(`Lock \"${key}\" no longer held (fence=${fencingToken})`);\n                }\n                const next = extendMs ?? ttlMs;\n                holder.expiresAt = Date.now() + next;\n                if (holder.timer) clearTimeout(holder.timer);\n                holder.timer = setTimeout(() => self.expire(key, holder), next);\n            },\n            async release() {\n                if (holder.released || self.holders.get(key) !== holder) return;\n                holder.released = true;\n                if (holder.timer) clearTimeout(holder.timer);\n                self.holders.delete(key);\n                self.handoff(key);\n            },\n        };\n        return handle;\n    }\n\n    private expire(key: string, holder: Holder): void {\n        if (holder.released) return;\n        if (this.holders.get(key) !== holder) return;\n        holder.released = true;\n        this.holders.delete(key);\n        this.handoff(key);\n    }\n\n    private handoff(key: string): void {\n        const queue = this.queues.get(key);\n        if (!queue || queue.length === 0) return;\n        const next = queue.shift()!;\n        if (next.timer) clearTimeout(next.timer);\n        if (Date.now() > next.deadline) {\n            next.resolve(null);\n            this.handoff(key);\n            return;\n        }\n        const ttlMs = next.opts.ttlMs ?? this.defaultTtlMs;\n        next.resolve(this.grant(key, ttlMs));\n        if (queue.length === 0) this.queues.delete(key);\n    }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { IKV, KVEntry, KVSetOptions } from '@objectstack/spec/contracts';\n\ninterface Entry<T = unknown> {\n    value: T;\n    version: bigint;\n    expiresAt?: number;\n    timer?: NodeJS.Timeout;\n}\n\n/**\n * In-memory coordination KV. Supports optimistic concurrency via\n * `ifVersion` and TTL via `ttl` (seconds).\n *\n * NOT a cache, NOT a database — intended for small cluster bookkeeping.\n */\nexport class MemoryKV implements IKV {\n    private readonly store = new Map<string, Entry>();\n    private closed = false;\n\n    async get<T = unknown>(key: string): Promise<KVEntry<T> | undefined> {\n        const e = this.store.get(key);\n        if (!e) return undefined;\n        if (e.expiresAt && Date.now() >= e.expiresAt) {\n            this.store.delete(key);\n            return undefined;\n        }\n        return {\n            key,\n            value: e.value as T,\n            version: e.version,\n            expiresAt: e.expiresAt,\n        };\n    }\n\n    async set<T = unknown>(\n        key: string,\n        value: T,\n        opts: KVSetOptions = {},\n    ): Promise<KVEntry<T>> {\n        if (this.closed) throw new Error('MemoryKV is closed');\n        const existing = this.store.get(key);\n        const existingVersion = existing\n            ? existing.expiresAt && Date.now() >= existing.expiresAt\n                ? 0n\n                : existing.version\n            : 0n;\n        if (opts.ifVersion !== undefined && opts.ifVersion !== existingVersion) {\n            throw new VersionMismatchError(key, opts.ifVersion, existingVersion);\n        }\n        if (existing?.timer) clearTimeout(existing.timer);\n        const version = existingVersion + 1n;\n        const expiresAt = opts.ttl && opts.ttl > 0 ? Date.now() + opts.ttl * 1000 : undefined;\n        const entry: Entry<T> = { value, version, expiresAt };\n        if (expiresAt) {\n            entry.timer = setTimeout(() => {\n                const current = this.store.get(key);\n                if (current === (entry as Entry<unknown>)) this.store.delete(key);\n            }, expiresAt - Date.now());\n        }\n        this.store.set(key, entry as Entry<unknown>);\n        return { key, value, version, expiresAt };\n    }\n\n    async delete(key: string, opts: { ifVersion?: bigint } = {}): Promise<boolean> {\n        const e = this.store.get(key);\n        if (!e) return false;\n        if (e.expiresAt && Date.now() >= e.expiresAt) {\n            this.store.delete(key);\n            return false;\n        }\n        if (opts.ifVersion !== undefined && opts.ifVersion !== e.version) {\n            throw new VersionMismatchError(key, opts.ifVersion, e.version);\n        }\n        if (e.timer) clearTimeout(e.timer);\n        this.store.delete(key);\n        return true;\n    }\n\n    async cas<T = unknown>(\n        key: string,\n        expectedVersion: bigint,\n        next: T,\n        opts: Omit<KVSetOptions, 'ifVersion'> = {},\n    ): Promise<KVEntry<T> | undefined> {\n        try {\n            return await this.set(key, next, { ...opts, ifVersion: expectedVersion });\n        } catch (err) {\n            if (err instanceof VersionMismatchError) return undefined;\n            throw err;\n        }\n    }\n\n    async close(): Promise<void> {\n        this.closed = true;\n        for (const [, e] of this.store) {\n            if (e.timer) clearTimeout(e.timer);\n        }\n        this.store.clear();\n    }\n}\n\nexport class VersionMismatchError extends Error {\n    constructor(\n        public readonly key: string,\n        public readonly expected: bigint,\n        public readonly actual: bigint,\n    ) {\n        super(\n            `KV version mismatch on \"${key}\": expected v${expected}, found v${actual}`,\n        );\n        this.name = 'VersionMismatchError';\n    }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { ICounter, CounterIncrOptions } from '@objectstack/spec/contracts';\n\n/**\n * In-memory monotonic counter. Single-process only — for cross-node id\n * allocation, use the postgres or redis driver.\n */\nexport class MemoryCounter implements ICounter {\n    private readonly counters = new Map<string, bigint>();\n    private closed = false;\n\n    async incr(key: string, opts: CounterIncrOptions = {}): Promise<bigint> {\n        if (this.closed) throw new Error('MemoryCounter is closed');\n        const by = BigInt(opts.by ?? 1);\n        const current = this.counters.get(key) ?? 0n;\n        const next = current + by;\n        this.counters.set(key, next);\n        return next;\n    }\n\n    async peek(key: string): Promise<bigint> {\n        return this.counters.get(key) ?? 0n;\n    }\n\n    async reset(key: string, value: bigint = 0n): Promise<void> {\n        if (this.closed) throw new Error('MemoryCounter is closed');\n        if (value === 0n) this.counters.delete(key);\n        else this.counters.set(key, value);\n    }\n\n    async close(): Promise<void> {\n        this.closed = true;\n        this.counters.clear();\n    }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Split-brain guard (ADR-0010, path A).\n *\n * The `memory` cluster driver keeps PubSub/Lock/KV/Counter state **per\n * process**. On a single node that is correct; across multiple replicas\n * each process holds its own state, so:\n *   - `ILock` is acquired locally by every replica -> no mutual exclusion;\n *   - `ICounter`/`IKV` versions diverge per replica;\n *   - `IPubSub` does not fan out across processes.\n *\n * This fails silently -- single-node tests and dev pass, only production\n * multi-replica corrupts. The guard turns that silent corruption into a\n * loud startup error when the operator has *declared* a multi-node\n * topology yet wired an in-process driver.\n *\n * Detection is deliberately conservative (path A): it keys off an\n * explicit operator declaration, not active peer discovery (that is the\n * optional path B in ADR-0010). It cannot know at boot whether the\n * cluster primitives are actually used cross-node, so it offers an\n * escape hatch for the rare \"replicas declared but primitives unused\"\n * case.\n */\n\n/** In-process drivers whose state does not coordinate across replicas. */\nconst IN_PROCESS_DRIVERS = new Set(['memory']);\n\n/** Environment inputs the guard reads. */\nexport interface SplitBrainGuardEnv {\n    /** `'true'` -> operator declares a multi-node deployment. */\n    OS_EXPECT_MULTI_NODE?: string;\n    /** Replica count; `> 1` -> multi-node. */\n    OS_CLUSTER_REPLICAS?: string;\n    /** `'true'` -> bypass the guard (replicas declared but primitives unused cross-node). */\n    OS_ALLOW_MEMORY_CLUSTER_MULTINODE?: string;\n}\n\nfunction isTrue(v: string | undefined): boolean {\n    return String(v).trim().toLowerCase() === 'true';\n}\n\n/**\n * True when the operator has declared a multi-node topology via\n * `OS_EXPECT_MULTI_NODE=true` or `OS_CLUSTER_REPLICAS` greater than 1.\n */\nexport function declaresMultiNode(env: SplitBrainGuardEnv = process.env): boolean {\n    if (isTrue(env.OS_EXPECT_MULTI_NODE)) return true;\n    const replicas = Number(env.OS_CLUSTER_REPLICAS);\n    return Number.isFinite(replicas) && replicas > 1;\n}\n\n/**\n * Throw if a multi-node topology is declared while the resolved cluster\n * `driver` is in-process (`memory`), unless explicitly allowed via\n * `OS_ALLOW_MEMORY_CLUSTER_MULTINODE=true`.\n *\n * Call this at startup *before* registering the cluster service so a\n * misconfiguration fails fast.\n */\nexport function assertClusterDriverSafeForTopology(\n    driver: string,\n    env: SplitBrainGuardEnv = process.env,\n): void {\n    if (!declaresMultiNode(env)) return;\n    if (!IN_PROCESS_DRIVERS.has(driver)) return;\n    if (isTrue(env.OS_ALLOW_MEMORY_CLUSTER_MULTINODE)) return;\n\n    throw new Error(\n        `ClusterServicePlugin: multi-node deployment declared ` +\n            `(OS_EXPECT_MULTI_NODE / OS_CLUSTER_REPLICAS>1) but the cluster driver is ` +\n            `in-process \"${driver}\" -- its locks/counters/pub-sub do not coordinate across ` +\n            `processes, so multiple replicas silently split-brain. Configure a remote cluster ` +\n            `driver (e.g. @objectstack/service-cluster-redis) or a DB-backed driver. To override ` +\n            `(replicas declared but cluster primitives unused cross-node), set ` +\n            `OS_ALLOW_MEMORY_CLUSTER_MULTINODE=true. See cloud ADR-0010.`,\n    );\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport type { IClusterService } from '@objectstack/spec/contracts';\nimport type { ClusterCapabilityConfigInput } from '@objectstack/spec/kernel';\nimport { defineCluster } from './cluster.js';\nimport { assertClusterDriverSafeForTopology } from './split-brain-guard.js';\n\n/**\n * Options for `ClusterServicePlugin`.\n *\n * Pass either a pre-built `cluster` instance (advanced — for tests or\n * custom drivers), or a `config` object that will be passed to\n * `defineCluster()`. If both are omitted, a memory-driver cluster is\n * created with auto-generated nodeId.\n */\nexport interface ClusterServicePluginOptions {\n    /** Pre-built cluster service. Wins over `config` when both provided. */\n    cluster?: IClusterService;\n    /** Config forwarded to `defineCluster()` when `cluster` is absent. */\n    config?: ClusterCapabilityConfigInput;\n}\n\n/**\n * Registers an `IClusterService` under the well-known service name\n * `'cluster'`. Plugins consume it via:\n *\n * ```ts\n * import type { IClusterService } from '@objectstack/spec/contracts';\n * const cluster = ctx.getService<IClusterService>('cluster');\n * await cluster.pubsub.publish('metadata.changed', payload);\n * ```\n *\n * The plugin closes the cluster on kernel shutdown.\n *\n * @example default memory driver\n *   kernel.use(new ClusterServicePlugin());\n *\n * @example explicit config\n *   kernel.use(new ClusterServicePlugin({ config: { driver: 'memory', nodeId: 'web-1' } }));\n */\nexport class ClusterServicePlugin implements Plugin {\n    name = 'com.objectstack.service.cluster';\n    version = '1.0.0';\n    type = 'standard';\n\n    private readonly options: ClusterServicePluginOptions;\n    private cluster?: IClusterService;\n    private owned = false;\n\n    constructor(options: ClusterServicePluginOptions = {}) {\n        this.options = options;\n    }\n\n    async init(ctx: PluginContext): Promise<void> {\n        if (this.options.cluster) {\n            this.cluster = this.options.cluster;\n            this.owned = false;\n        } else {\n            this.cluster = defineCluster(this.options.config ?? {});\n            this.owned = true;\n        }\n        // Split-brain guard (ADR-0010): fail fast if a multi-node topology is\n        // declared but the resolved driver is in-process. Runs before\n        // registration so a misconfiguration never half-wires the service.\n        assertClusterDriverSafeForTopology(this.cluster.driver);\n\n        ctx.registerService('cluster', this.cluster);\n        ctx.logger.info(\n            `ClusterServicePlugin: registered \"${this.cluster.driver}\" driver (node=${this.cluster.nodeId})`,\n        );\n\n        ctx.hook('kernel:shutdown', async () => {\n            if (this.owned && this.cluster) {\n                try {\n                    await this.cluster.close();\n                } catch (err) {\n                    ctx.logger.error('ClusterServicePlugin: close error', err as Error);\n                }\n            }\n        });\n    }\n}\n","// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.\n\nimport type { Plugin, PluginContext } from '@objectstack/core';\nimport type { IClusterService } from '@objectstack/spec/contracts';\n\n/**\n * Bridges the cluster pub/sub bus to the metadata service so that\n * metadata mutations on one node invalidate registry caches on peer\n * nodes. Implements the \"first real consumer\" of the cluster API.\n *\n * Implementation detail: this plugin lives in `@objectstack/service-cluster`\n * (not in `@objectstack/metadata`) to avoid forcing every metadata\n * consumer to pull the cluster service. The metadata package only needs\n * the `IPubSub` interface, which lives in `@objectstack/spec/contracts`.\n *\n * Activates only when both services are present and the metadata service\n * exposes `attachClusterPubSub()`. Late binding is achieved via the\n * `kernel:ready` lifecycle hook.\n *\n * Channel: `metadata.changed` — payload shape defined by\n * `ClusterMetadataChangedPayload` in `@objectstack/metadata`.\n *\n * See `content/docs/concepts/cluster-semantics.mdx` §5.\n */\nexport class MetadataClusterBridgePlugin implements Plugin {\n    name = 'com.objectstack.service.metadata-cluster-bridge';\n    version = '1.0.0';\n    type = 'standard';\n\n    private detach?: () => void;\n\n    async init(ctx: PluginContext): Promise<void> {\n        ctx.hook('kernel:ready', async () => {\n            let cluster: IClusterService | undefined;\n            let md: unknown;\n            try {\n                cluster = ctx.getService<IClusterService>('cluster');\n            } catch {\n                ctx.logger.debug(\n                    'MetadataClusterBridgePlugin: no \"cluster\" service registered, skipping',\n                );\n                return;\n            }\n            try {\n                md = ctx.getService<unknown>('metadata');\n            } catch {\n                ctx.logger.debug(\n                    'MetadataClusterBridgePlugin: no \"metadata\" service registered, skipping',\n                );\n                return;\n            }\n\n            const attach = (md as { attachClusterPubSub?: unknown })\n                .attachClusterPubSub;\n            if (typeof attach !== 'function') {\n                ctx.logger.warn(\n                    'MetadataClusterBridgePlugin: metadata service does not expose attachClusterPubSub(); cross-node cache invalidation disabled',\n                );\n                return;\n            }\n\n            try {\n                this.detach = (attach as (\n                    pubsub: IClusterService['pubsub'],\n                    nodeId: string,\n                ) => () => void).call(md, cluster.pubsub, cluster.nodeId);\n                ctx.logger.info(\n                    `MetadataClusterBridgePlugin: bridged metadata.changed → cluster.pubsub (node=${cluster.nodeId})`,\n                );\n            } catch (err) {\n                ctx.logger.error(\n                    'MetadataClusterBridgePlugin: attach failed',\n                    err as Error,\n                );\n            }\n        });\n\n        ctx.hook('kernel:shutdown', async () => {\n            try {\n                this.detach?.();\n            } catch (err) {\n                ctx.logger.error(\n                    'MetadataClusterBridgePlugin: detach error',\n                    err as Error,\n                );\n            }\n            this.detach = undefined;\n        });\n    }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/service-cluster",
-  "version": "9.4.0",
+  "version": "9.5.1",
   "license": "Apache-2.0",
   "description": "Cluster Service for ObjectStack — pluggable PubSub/Lock/KV/Counter primitives. Memory driver included; postgres/redis drivers ship separately.",
   "type": "module",
@@ -19,8 +19,8 @@
     }
   },
   "dependencies": {
-    "@objectstack/core": "9.4.0",
-    "@objectstack/spec": "9.4.0"
+    "@objectstack/core": "9.5.1",
+    "@objectstack/spec": "9.5.1"
   },
   "devDependencies": {
     "@types/node": "^25.9.2",

package/src/cluster-service-plugin.ts

@@ -4,6 +4,7 @@ import type { Plugin, PluginContext } from '@objectstack/core';
 import type { IClusterService } from '@objectstack/spec/contracts';
 import type { ClusterCapabilityConfigInput } from '@objectstack/spec/kernel';
 import { defineCluster } from './cluster.js';
+import { assertClusterDriverSafeForTopology } from './split-brain-guard.js';
 
 /**
  * Options for `ClusterServicePlugin`.
@@ -59,6 +60,11 @@ export class ClusterServicePlugin implements Plugin {
             this.cluster = defineCluster(this.options.config ?? {});
             this.owned = true;
         }
+        // Split-brain guard (ADR-0010): fail fast if a multi-node topology is
+        // declared but the resolved driver is in-process. Runs before
+        // registration so a misconfiguration never half-wires the service.
+        assertClusterDriverSafeForTopology(this.cluster.driver);
+
         ctx.registerService('cluster', this.cluster);
         ctx.logger.info(
             `ClusterServicePlugin: registered "${this.cluster.driver}" driver (node=${this.cluster.nodeId})`,

package/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.
  */
@@ -29,6 +39,12 @@ export {
     type ClusterServicePluginOptions,
 } from './cluster-service-plugin.js';
 
+export {
+    assertClusterDriverSafeForTopology,
+    declaresMultiNode,
+    type SplitBrainGuardEnv,
+} from './split-brain-guard.js';
+
 export { MetadataClusterBridgePlugin } from './metadata-cluster-bridge-plugin.js';
 
 // Re-export contracts for convenience.

package/src/split-brain-guard.test.ts

@@ -0,0 +1,61 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+import {
+    declaresMultiNode,
+    assertClusterDriverSafeForTopology,
+} from './split-brain-guard.js';
+
+describe('declaresMultiNode', () => {
+    it('false when nothing declared', () => {
+        expect(declaresMultiNode({})).toBe(false);
+    });
+    it('true for OS_EXPECT_MULTI_NODE=true (case-insensitive, trimmed)', () => {
+        expect(declaresMultiNode({ OS_EXPECT_MULTI_NODE: 'true' })).toBe(true);
+        expect(declaresMultiNode({ OS_EXPECT_MULTI_NODE: ' TRUE ' })).toBe(true);
+    });
+    it('false for OS_EXPECT_MULTI_NODE=false / other', () => {
+        expect(declaresMultiNode({ OS_EXPECT_MULTI_NODE: 'false' })).toBe(false);
+        expect(declaresMultiNode({ OS_EXPECT_MULTI_NODE: '1' })).toBe(false);
+    });
+    it('replicas: >1 true, <=1 false, non-numeric false', () => {
+        expect(declaresMultiNode({ OS_CLUSTER_REPLICAS: '3' })).toBe(true);
+        expect(declaresMultiNode({ OS_CLUSTER_REPLICAS: '1' })).toBe(false);
+        expect(declaresMultiNode({ OS_CLUSTER_REPLICAS: '0' })).toBe(false);
+        expect(declaresMultiNode({ OS_CLUSTER_REPLICAS: 'abc' })).toBe(false);
+    });
+});
+
+describe('assertClusterDriverSafeForTopology', () => {
+    it('no throw: single-node + memory (the common case)', () => {
+        expect(() => assertClusterDriverSafeForTopology('memory', {})).not.toThrow();
+    });
+    it('no throw: multi-node + remote driver', () => {
+        expect(() =>
+            assertClusterDriverSafeForTopology('redis', { OS_EXPECT_MULTI_NODE: 'true' }),
+        ).not.toThrow();
+    });
+    it('THROWS: multi-node (OS_EXPECT_MULTI_NODE) + memory', () => {
+        expect(() =>
+            assertClusterDriverSafeForTopology('memory', { OS_EXPECT_MULTI_NODE: 'true' }),
+        ).toThrow(/split-brain/);
+    });
+    it('THROWS: multi-node (replicas>1) + memory, cites ADR-0010', () => {
+        expect(() =>
+            assertClusterDriverSafeForTopology('memory', { OS_CLUSTER_REPLICAS: '2' }),
+        ).toThrow(/ADR-0010/);
+    });
+    it('escape hatch: multi-node + memory + OS_ALLOW_MEMORY_CLUSTER_MULTINODE=true', () => {
+        expect(() =>
+            assertClusterDriverSafeForTopology('memory', {
+                OS_EXPECT_MULTI_NODE: 'true',
+                OS_ALLOW_MEMORY_CLUSTER_MULTINODE: 'true',
+            }),
+        ).not.toThrow();
+    });
+    it('does not guard unknown custom drivers (author responsibility)', () => {
+        expect(() =>
+            assertClusterDriverSafeForTopology('mycustom', { OS_EXPECT_MULTI_NODE: 'true' }),
+        ).not.toThrow();
+    });
+});

package/src/split-brain-guard.ts

@@ -0,0 +1,78 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Split-brain guard (ADR-0010, path A).
+ *
+ * The `memory` cluster driver keeps PubSub/Lock/KV/Counter state **per
+ * process**. On a single node that is correct; across multiple replicas
+ * each process holds its own state, so:
+ *   - `ILock` is acquired locally by every replica -> no mutual exclusion;
+ *   - `ICounter`/`IKV` versions diverge per replica;
+ *   - `IPubSub` does not fan out across processes.
+ *
+ * This fails silently -- single-node tests and dev pass, only production
+ * multi-replica corrupts. The guard turns that silent corruption into a
+ * loud startup error when the operator has *declared* a multi-node
+ * topology yet wired an in-process driver.
+ *
+ * Detection is deliberately conservative (path A): it keys off an
+ * explicit operator declaration, not active peer discovery (that is the
+ * optional path B in ADR-0010). It cannot know at boot whether the
+ * cluster primitives are actually used cross-node, so it offers an
+ * escape hatch for the rare "replicas declared but primitives unused"
+ * case.
+ */
+
+/** In-process drivers whose state does not coordinate across replicas. */
+const IN_PROCESS_DRIVERS = new Set(['memory']);
+
+/** Environment inputs the guard reads. */
+export interface SplitBrainGuardEnv {
+    /** `'true'` -> operator declares a multi-node deployment. */
+    OS_EXPECT_MULTI_NODE?: string;
+    /** Replica count; `> 1` -> multi-node. */
+    OS_CLUSTER_REPLICAS?: string;
+    /** `'true'` -> bypass the guard (replicas declared but primitives unused cross-node). */
+    OS_ALLOW_MEMORY_CLUSTER_MULTINODE?: string;
+}
+
+function isTrue(v: string | undefined): boolean {
+    return String(v).trim().toLowerCase() === 'true';
+}
+
+/**
+ * True when the operator has declared a multi-node topology via
+ * `OS_EXPECT_MULTI_NODE=true` or `OS_CLUSTER_REPLICAS` greater than 1.
+ */
+export function declaresMultiNode(env: SplitBrainGuardEnv = process.env): boolean {
+    if (isTrue(env.OS_EXPECT_MULTI_NODE)) return true;
+    const replicas = Number(env.OS_CLUSTER_REPLICAS);
+    return Number.isFinite(replicas) && replicas > 1;
+}
+
+/**
+ * Throw if a multi-node topology is declared while the resolved cluster
+ * `driver` is in-process (`memory`), unless explicitly allowed via
+ * `OS_ALLOW_MEMORY_CLUSTER_MULTINODE=true`.
+ *
+ * Call this at startup *before* registering the cluster service so a
+ * misconfiguration fails fast.
+ */
+export function assertClusterDriverSafeForTopology(
+    driver: string,
+    env: SplitBrainGuardEnv = process.env,
+): void {
+    if (!declaresMultiNode(env)) return;
+    if (!IN_PROCESS_DRIVERS.has(driver)) return;
+    if (isTrue(env.OS_ALLOW_MEMORY_CLUSTER_MULTINODE)) return;
+
+    throw new Error(
+        `ClusterServicePlugin: multi-node deployment declared ` +
+            `(OS_EXPECT_MULTI_NODE / OS_CLUSTER_REPLICAS>1) but the cluster driver is ` +
+            `in-process "${driver}" -- its locks/counters/pub-sub do not coordinate across ` +
+            `processes, so multiple replicas silently split-brain. Configure a remote cluster ` +
+            `driver (e.g. @objectstack/service-cluster-redis) or a DB-backed driver. To override ` +
+            `(replicas declared but cluster primitives unused cross-node), set ` +
+            `OS_ALLOW_MEMORY_CLUSTER_MULTINODE=true. See cloud ADR-0010.`,
+    );
+}