@feltdb/core 0.5.1 → 0.5.3

package/dist/cell.js

@@ -0,0 +1,1090 @@
+/**
+ * Durable Cell: independently-versioned mutation boundary
+ *
+ * A Cell is the smallest durable authority boundary in FeltDB.
+ * Each cell owns its own version, state, and mutation serialization.
+ */
+import { Collection } from './collection.js';
+export const NO_CHANGE = Symbol('FELTDB_NO_CHANGE');
+export const AUTHORITY_CONFLICT = Symbol('FELTDB_AUTHORITY_CONFLICT');
+/**
+ * CellImpl implements the Cell interface with authority and lifecycle support.
+ * Uses per-cell locking to serialize mutations and authority transitions.
+ * Epoch-based fencing prevents stale authority from mutating.
+ *
+ * Replication: CellImpl can also track replica state separately.
+ * A replica is read-only: replication transfers knowledge, not authority.
+ */
+export class CellImpl {
+    constructor(jsDb, cellId) {
+        this.mutationQueue = [];
+        this.isLocked = false;
+        this.changeHandlers = [];
+        this.isReplica = false;
+        this.id = cellId;
+        this.jsDb = jsDb;
+        this.cellCollection = new Collection(jsDb, '_cells', undefined, undefined, false);
+        this.replicaCollection = new Collection(jsDb, '_replicas', undefined, undefined, false);
+        this.failureObservationCollection = new Collection(jsDb, '_failure_observations', undefined, undefined, false);
+    }
+    setReplica(isReplica) {
+        this.isReplica = isReplica;
+    }
+    isReplicaCell() {
+        return this.isReplica;
+    }
+    async applyReplication(snapshot) {
+        return this.acquireLock(async () => {
+            const current = await this.getUnlocked();
+            // Replication can only move forward
+            if (current && current.version > snapshot.version) {
+                throw new Error(`REPLICATION_CONFLICT: cannot apply version ${snapshot.version}, current is ${current.version}`);
+            }
+            // Same version must have identical state
+            if (current && current.version === snapshot.version) {
+                if (JSON.stringify(current.value) !== JSON.stringify(snapshot.value)) {
+                    const conflictReason = `version ${snapshot.version} has divergent state`;
+                    await this.replicaCollection.insert({
+                        cellId: this.id,
+                        version: current.version,
+                        value: current.value,
+                        updatedAt: current.updatedAt,
+                        authority: current.authority,
+                        placement: current.placement,
+                        lease: current.lease,
+                        divergent: true,
+                        conflictReason,
+                    }, this.encodeKey());
+                    throw new Error(`REPLICATION_CONFLICT: ${conflictReason}`);
+                }
+                // Identical state at same version is idempotent, no-op
+                await this.clearDivergenceMarker();
+                return;
+            }
+            // Apply replication: update the replicated state
+            // For PR 6A, we store replica state as regular cell state but marked as replica
+            const replicaState = {
+                id: snapshot.cellId,
+                version: snapshot.version,
+                value: snapshot.value,
+                updatedAt: snapshot.updatedAt,
+                authority: {
+                    owner: snapshot.authority.owner,
+                    epoch: snapshot.authority.epoch,
+                    lifecycle: snapshot.authority.lifecycle,
+                },
+                placement: {
+                    nodeId: snapshot.placement.nodeId,
+                },
+                lease: snapshot.lease,
+            };
+            const key = this.encodeKey();
+            if (!current) {
+                // New replica: insert the first version
+                await this.cellCollection.insert(replicaState, key);
+            }
+            else {
+                // Update existing replica to new version
+                // Use version comparison for CAS (pass current version and epoch)
+                const result = await this.cellCollection.updateIfVersion(key, current.version, replicaState, current.authority.epoch);
+                if (!result.updated) {
+                    // Concurrent replication delivery - just log and move forward
+                    // This is expected in concurrent scenarios
+                }
+            }
+            // A successfully applied canonical snapshot repairs any older divergence
+            // marker and makes the replica eligible for later evaluation again.
+            await this.clearDivergenceMarker();
+        });
+    }
+    /** Removing an absent repair marker is an idempotent replication cleanup. */
+    async clearDivergenceMarker() {
+        try {
+            await this.replicaCollection.delete(this.encodeKey());
+        }
+        catch (error) {
+            if (error instanceof Error && /^Delete failed: record not found$/i.test(error.message)) {
+                return;
+            }
+            throw error;
+        }
+    }
+    encodeKey() {
+        const hash = this.hashId(this.id);
+        return `${hash}`;
+    }
+    hashId(id) {
+        let hash = 0;
+        for (let i = 0; i < id.length; i++) {
+            const char = id.charCodeAt(i);
+            hash = ((hash << 5) - hash) + char;
+            hash = hash & hash;
+        }
+        return Math.abs(hash).toString(16);
+    }
+    async get() {
+        const key = this.encodeKey();
+        const state = await this.cellCollection.get(key);
+        if (!state)
+            return null;
+        return this.snapshotFromState(state);
+    }
+    async set(value, options) {
+        return this.acquireLock(async () => {
+            // Replicas are read-only
+            if (this.isReplica) {
+                throw new Error(`REPLICA_READ_ONLY: Cell ${this.id} is a read-only replica`);
+            }
+            const current = await this.getUnlocked();
+            // Check retirement
+            if (current?.authority.lifecycle === 'retired') {
+                throw new Error(`Cell ${this.id} is retired`);
+            }
+            // Capture current epoch for atomic fencing
+            // This epoch will be verified by backend CAS atomically with state mutation
+            const expectedEpoch = current?.authority.epoch ?? 0;
+            // Validate provided epoch if specified (optional, for explicit fencing)
+            if (options?.authorityEpoch !== undefined && current) {
+                if (options.authorityEpoch !== expectedEpoch) {
+                    throw new Error(`AUTHORITY_CONFLICT: expected epoch ${expectedEpoch}, got ${options.authorityEpoch}`);
+                }
+            }
+            // Validate lease if specified
+            if (options?.leaseId !== undefined) {
+                if (!current?.lease) {
+                    throw new Error(`LEASE_INVALID: no active lease`);
+                }
+                if (current.lease.leaseId !== options.leaseId) {
+                    throw new Error(`LEASE_INVALID: lease ID mismatch`);
+                }
+                if (current.lease.expiresAt <= Date.now()) {
+                    throw new Error(`LEASE_EXPIRED: lease has expired`);
+                }
+                if (current.lease.epoch !== expectedEpoch) {
+                    throw new Error(`LEASE_INVALID: lease epoch does not match authority epoch`);
+                }
+            }
+            const expectedVersion = current?.version ?? 0;
+            const authority = current?.authority ?? { owner: null, epoch: 0, lifecycle: 'active' };
+            const placement = current?.placement ?? { nodeId: null };
+            const lease = current?.lease ?? null;
+            const newState = {
+                id: this.id,
+                version: expectedVersion + 1,
+                value,
+                updatedAt: new Date().toISOString(),
+                authority,
+                placement,
+                lease,
+            };
+            const key = this.encodeKey();
+            if (expectedVersion === 0) {
+                await this.cellCollection.insert(newState, key);
+            }
+            else {
+                // Pass captured epoch to backend CAS for atomic verification
+                const result = await this.cellCollection.updateIfVersion(key, expectedVersion, newState, expectedEpoch, options?.leaseId);
+                if (!result.updated) {
+                    throw new Error(`Cell ${this.id} version conflict`);
+                }
+            }
+            this.emitChange({
+                cellId: this.id,
+                version: newState.version,
+                value,
+                timestamp: newState.updatedAt,
+                epoch: newState.authority.epoch,
+            });
+            return this.snapshotFromState(newState);
+        });
+    }
+    async update(updater, options) {
+        return this.acquireLock(async () => {
+            // Replicas are read-only
+            if (this.isReplica) {
+                throw new Error(`REPLICA_READ_ONLY: Cell ${this.id} is a read-only replica`);
+            }
+            const current = await this.getUnlocked();
+            // Check retirement
+            if (current?.authority.lifecycle === 'retired') {
+                throw new Error(`Cell ${this.id} is retired`);
+            }
+            // Capture current epoch for atomic fencing
+            // This epoch will be verified by backend CAS atomically with state mutation
+            const expectedEpoch = current?.authority.epoch ?? 0;
+            // Validate provided epoch if specified (optional, for explicit fencing)
+            if (options?.authorityEpoch !== undefined && current) {
+                if (options.authorityEpoch !== expectedEpoch) {
+                    throw new Error(`AUTHORITY_CONFLICT: expected epoch ${expectedEpoch}, got ${options.authorityEpoch}`);
+                }
+            }
+            // Validate lease if specified
+            if (options?.leaseId !== undefined) {
+                if (!current?.lease) {
+                    throw new Error(`LEASE_INVALID: no active lease`);
+                }
+                if (current.lease.leaseId !== options.leaseId) {
+                    throw new Error(`LEASE_INVALID: lease ID mismatch`);
+                }
+                if (current.lease.expiresAt <= Date.now()) {
+                    throw new Error(`LEASE_EXPIRED: lease has expired`);
+                }
+                if (current.lease.epoch !== expectedEpoch) {
+                    throw new Error(`LEASE_INVALID: lease epoch does not match authority epoch`);
+                }
+            }
+            const currentValue = current?.value ?? null;
+            const currentVersion = current?.version ?? 0;
+            const nextValue = updater(currentValue);
+            if (nextValue === NO_CHANGE) {
+                if (current)
+                    return this.snapshotFromState(current);
+                throw new Error(`Cell ${this.id} update returned NO_CHANGE but cell does not exist`);
+            }
+            const authority = current?.authority ?? { owner: null, epoch: 0, lifecycle: 'active' };
+            const placement = current?.placement ?? { nodeId: null };
+            const lease = current?.lease ?? null;
+            const newState = {
+                id: this.id,
+                version: currentVersion + 1,
+                value: nextValue,
+                updatedAt: new Date().toISOString(),
+                authority,
+                placement,
+                lease,
+            };
+            const key = this.encodeKey();
+            if (currentVersion === 0) {
+                await this.cellCollection.insert(newState, key);
+            }
+            else {
+                // Pass captured epoch to backend CAS for atomic verification
+                const result = await this.cellCollection.updateIfVersion(key, currentVersion, newState, expectedEpoch, options?.leaseId);
+                if (!result.updated) {
+                    throw new Error(`Cell ${this.id} conflict during update`);
+                }
+            }
+            this.emitChange({
+                cellId: this.id,
+                version: newState.version,
+                value: nextValue,
+                timestamp: newState.updatedAt,
+                epoch: newState.authority.epoch,
+            });
+            return this.snapshotFromState(newState);
+        });
+    }
+    async transact(fn) {
+        return this.acquireLock(async () => {
+            const tx = {
+                get: () => this.getUnlocked(),
+                set: (value, options) => this.setUnlocked(value, options),
+                update: (updater, options) => this.updateUnlocked(updater, options),
+            };
+            return fn(tx);
+        });
+    }
+    async transitionAuthority(options) {
+        return this.acquireLock(async () => {
+            // Replicas are read-only
+            if (this.isReplica) {
+                throw new Error(`REPLICA_READ_ONLY: Cell ${this.id} is a read-only replica`);
+            }
+            const current = await this.getUnlocked();
+            if (!current) {
+                throw new Error(`Cell ${this.id} does not exist`);
+            }
+            // Check retirement
+            if (current.authority.lifecycle === 'retired') {
+                throw new Error(`Cell ${this.id} is retired`);
+            }
+            // Verify epoch
+            if (current.authority.epoch !== options.expectedEpoch) {
+                throw new Error(`AUTHORITY_CONFLICT: expected epoch ${options.expectedEpoch}, got ${current.authority.epoch}`);
+            }
+            // Validate lifecycle transition if provided
+            if (options.lifecycle !== undefined) {
+                this.validateLifecycleTransition(current.authority.lifecycle, options.lifecycle);
+            }
+            // Create new authority state with incremented epoch
+            const newAuthority = {
+                owner: options.owner !== undefined ? options.owner : current.authority.owner,
+                epoch: current.authority.epoch + 1,
+                lifecycle: options.lifecycle !== undefined ? options.lifecycle : current.authority.lifecycle,
+            };
+            // Authority transition increments version, clears lease (old epoch invalid)
+            const newState = {
+                id: this.id,
+                version: current.version + 1,
+                value: current.value,
+                updatedAt: new Date().toISOString(),
+                authority: newAuthority,
+                placement: current.placement,
+                lease: null,
+            };
+            const key = this.encodeKey();
+            // Pass current epoch to backend CAS for atomic verification
+            const result = await this.cellCollection.updateIfVersion(key, current.version, newState, current.authority.epoch);
+            if (!result.updated) {
+                throw new Error(`AUTHORITY_CONFLICT: epoch changed during transition`);
+            }
+            // Emit change event for authority transition
+            this.emitChange({
+                cellId: this.id,
+                version: newState.version,
+                value: current.value,
+                timestamp: newState.updatedAt,
+                epoch: newState.authority.epoch,
+            });
+            return this.snapshotFromState(newState);
+        });
+    }
+    async delegate(options) {
+        return this.acquireLock(async () => {
+            // Replicas are read-only
+            if (this.isReplica) {
+                throw new Error(`REPLICA_READ_ONLY: Cell ${this.id} is a read-only replica`);
+            }
+            const current = await this.getUnlocked();
+            if (!current) {
+                throw new Error(`Cell ${this.id} does not exist`);
+            }
+            // Check retirement
+            if (current.authority.lifecycle === 'retired') {
+                throw new Error(`Cell ${this.id} is retired`);
+            }
+            // Verify epoch
+            if (current.authority.epoch !== options.expectedEpoch) {
+                throw new Error(`AUTHORITY_CONFLICT: expected epoch ${options.expectedEpoch}, got ${current.authority.epoch}`);
+            }
+            // Verify from owner
+            if (current.authority.owner !== options.from) {
+                throw new Error(`AUTHORITY_CONFLICT: expected owner ${options.from}, got ${current.authority.owner}`);
+            }
+            // Create new authority with transferred owner and incremented epoch
+            const newAuthority = {
+                owner: options.to,
+                epoch: current.authority.epoch + 1,
+                lifecycle: current.authority.lifecycle,
+            };
+            // Delegation increments version, clears lease (old epoch invalid)
+            const newState = {
+                id: this.id,
+                version: current.version + 1,
+                value: current.value,
+                updatedAt: new Date().toISOString(),
+                authority: newAuthority,
+                placement: current.placement,
+                lease: null,
+            };
+            const key = this.encodeKey();
+            // Pass current epoch to backend CAS for atomic verification
+            const result = await this.cellCollection.updateIfVersion(key, current.version, newState, current.authority.epoch);
+            if (!result.updated) {
+                throw new Error(`AUTHORITY_CONFLICT: authority changed during delegation`);
+            }
+            // Emit change event for delegation
+            this.emitChange({
+                cellId: this.id,
+                version: newState.version,
+                value: current.value,
+                timestamp: newState.updatedAt,
+                epoch: newState.authority.epoch,
+            });
+            return this.snapshotFromState(newState);
+        });
+    }
+    async updatePlacement(options) {
+        return this.acquireLock(async () => {
+            // Replicas are read-only
+            if (this.isReplica) {
+                throw new Error(`REPLICA_READ_ONLY: Cell ${this.id} is a read-only replica`);
+            }
+            const current = await this.getUnlocked();
+            if (!current) {
+                throw new Error(`Cell ${this.id} does not exist`);
+            }
+            // Check retirement
+            if (current.authority.lifecycle === 'retired') {
+                throw new Error(`Cell ${this.id} is retired`);
+            }
+            // Capture current epoch for atomic fencing during placement update
+            const expectedEpoch = current.authority.epoch;
+            // Create new placement
+            const newPlacement = {
+                nodeId: options.nodeId,
+            };
+            // Placement update increments version but does NOT change epoch, authority, or lease
+            const newState = {
+                id: this.id,
+                version: current.version + 1,
+                value: current.value,
+                updatedAt: new Date().toISOString(),
+                authority: current.authority,
+                placement: newPlacement,
+                lease: current.lease,
+            };
+            const key = this.encodeKey();
+            // Pass current epoch to backend CAS for atomic verification
+            const result = await this.cellCollection.updateIfVersion(key, current.version, newState, expectedEpoch);
+            if (!result.updated) {
+                throw new Error(`Cell ${this.id} conflict during placement update`);
+            }
+            // Emit change event for placement update
+            this.emitChange({
+                cellId: this.id,
+                version: newState.version,
+                value: current.value,
+                timestamp: newState.updatedAt,
+                epoch: newState.authority.epoch,
+            });
+            return this.snapshotFromState(newState);
+        });
+    }
+    async acquireLease(options) {
+        return this.acquireLock(async () => {
+            // Replicas are read-only
+            if (this.isReplica) {
+                throw new Error(`REPLICA_READ_ONLY: Cell ${this.id} is a read-only replica`);
+            }
+            const current = await this.getUnlocked();
+            if (!current) {
+                throw new Error(`Cell ${this.id} does not exist`);
+            }
+            // Cannot acquire lease on retired cell
+            if (current.authority.lifecycle === 'retired') {
+                throw new Error(`Cell ${this.id} is retired`);
+            }
+            // Cannot acquire lease on suspended cell
+            if (current.authority.lifecycle === 'suspended') {
+                throw new Error(`Cell ${this.id} is suspended`);
+            }
+            // Check if existing lease is still valid
+            if (current.lease && current.lease.expiresAt > Date.now()) {
+                throw new Error(`LEASE_CONFLICT: lease already held by ${current.lease.holder}`);
+            }
+            // Capture current epoch
+            const expectedEpoch = current.authority.epoch;
+            // Generate new lease ID
+            const leaseId = `${this.id}:${Date.now()}:${Math.random().toString(36).slice(2)}`;
+            // Create new lease
+            const newLease = {
+                holder: options.holder,
+                leaseId,
+                epoch: expectedEpoch,
+                expiresAt: Date.now() + options.durationMs,
+            };
+            // Lease acquisition increments version
+            const newState = {
+                id: this.id,
+                version: current.version + 1,
+                value: current.value,
+                updatedAt: new Date().toISOString(),
+                authority: current.authority,
+                placement: current.placement,
+                lease: newLease,
+            };
+            const key = this.encodeKey();
+            const result = await this.cellCollection.updateIfVersion(key, current.version, newState, expectedEpoch);
+            if (!result.updated) {
+                throw new Error(`Cell ${this.id} conflict during lease acquisition`);
+            }
+            this.emitChange({
+                cellId: this.id,
+                version: newState.version,
+                value: current.value,
+                timestamp: newState.updatedAt,
+                epoch: newState.authority.epoch,
+            });
+            return this.snapshotFromState(newState);
+        });
+    }
+    async renewLease(options) {
+        return this.acquireLock(async () => {
+            // Replicas are read-only
+            if (this.isReplica) {
+                throw new Error(`REPLICA_READ_ONLY: Cell ${this.id} is a read-only replica`);
+            }
+            const current = await this.getUnlocked();
+            if (!current) {
+                throw new Error(`Cell ${this.id} does not exist`);
+            }
+            if (!current.lease) {
+                throw new Error(`Cell ${this.id} has no active lease`);
+            }
+            // Verify lease ID matches
+            if (current.lease.leaseId !== options.leaseId) {
+                throw new Error(`LEASE_CONFLICT: lease ID mismatch`);
+            }
+            // Verify lease has not expired
+            if (current.lease.expiresAt <= Date.now()) {
+                throw new Error(`LEASE_EXPIRED: lease has expired`);
+            }
+            // Verify epoch has not changed (lease must be within same authority epoch)
+            if (current.lease.epoch !== current.authority.epoch) {
+                throw new Error(`AUTHORITY_CONFLICT: authority epoch changed since lease acquisition`);
+            }
+            const expectedEpoch = current.authority.epoch;
+            // Extend lease expiration
+            const renewedLease = {
+                holder: current.lease.holder,
+                leaseId: current.lease.leaseId,
+                epoch: current.lease.epoch,
+                expiresAt: Date.now() + options.durationMs,
+            };
+            // Lease renewal increments version
+            const newState = {
+                id: this.id,
+                version: current.version + 1,
+                value: current.value,
+                updatedAt: new Date().toISOString(),
+                authority: current.authority,
+                placement: current.placement,
+                lease: renewedLease,
+            };
+            const key = this.encodeKey();
+            const result = await this.cellCollection.updateIfVersion(key, current.version, newState, expectedEpoch);
+            if (!result.updated) {
+                throw new Error(`Cell ${this.id} conflict during lease renewal`);
+            }
+            this.emitChange({
+                cellId: this.id,
+                version: newState.version,
+                value: current.value,
+                timestamp: newState.updatedAt,
+                epoch: newState.authority.epoch,
+            });
+            return this.snapshotFromState(newState);
+        });
+    }
+    async releaseLease(options) {
+        return this.acquireLock(async () => {
+            // Replicas are read-only
+            if (this.isReplica) {
+                throw new Error(`REPLICA_READ_ONLY: Cell ${this.id} is a read-only replica`);
+            }
+            const current = await this.getUnlocked();
+            if (!current) {
+                throw new Error(`Cell ${this.id} does not exist`);
+            }
+            if (!current.lease) {
+                throw new Error(`Cell ${this.id} has no active lease`);
+            }
+            // Verify lease ID matches
+            if (current.lease.leaseId !== options.leaseId) {
+                throw new Error(`LEASE_CONFLICT: lease ID mismatch`);
+            }
+            const expectedEpoch = current.authority.epoch;
+            // Clear the lease
+            const newState = {
+                id: this.id,
+                version: current.version + 1,
+                value: current.value,
+                updatedAt: new Date().toISOString(),
+                authority: current.authority,
+                placement: current.placement,
+                lease: null,
+            };
+            const key = this.encodeKey();
+            const result = await this.cellCollection.updateIfVersion(key, current.version, newState, expectedEpoch);
+            if (!result.updated) {
+                throw new Error(`Cell ${this.id} conflict during lease release`);
+            }
+            this.emitChange({
+                cellId: this.id,
+                version: newState.version,
+                value: current.value,
+                timestamp: newState.updatedAt,
+                epoch: newState.authority.epoch,
+            });
+            return this.snapshotFromState(newState);
+        });
+    }
+    async promote(options) {
+        return this.acquireLock(async () => {
+            const current = await this.getUnlocked();
+            if (!current) {
+                throw new Error(`Cell ${this.id} does not exist`);
+            }
+            return this.promoteSnapshot(current, options);
+        });
+    }
+    async promoteSnapshot(current, options) {
+        // Check retirement
+        if (current.authority.lifecycle === 'retired') {
+            throw new Error(`Cell ${this.id} is retired`);
+        }
+        // Verify expected version
+        if (current.version !== options.expectedVersion) {
+            throw new Error(`PROMOTION_CONFLICT: expected version ${options.expectedVersion}, got ${current.version}`);
+        }
+        // Verify expected epoch
+        if (current.authority.epoch !== options.expectedEpoch) {
+            throw new Error(`PROMOTION_CONFLICT: expected epoch ${options.expectedEpoch}, got ${current.authority.epoch}`);
+        }
+        // Promotion atomically transitions:
+        // - owner (A → B)
+        // - epoch (7 → 8)
+        // - placement (if provided)
+        // - clears lease (old epoch invalid)
+        // - advances version because promotion is a durable concurrency mutation
+        // - keeps lifecycle the same
+        const newAuthority = {
+            owner: options.newOwner,
+            epoch: current.authority.epoch + 1,
+            lifecycle: current.authority.lifecycle,
+        };
+        const newPlacement = {
+            nodeId: options.newNodeId !== undefined ? options.newNodeId : current.placement.nodeId,
+        };
+        const newState = {
+            id: this.id,
+            version: current.version + 1,
+            value: current.value,
+            updatedAt: new Date().toISOString(),
+            authority: newAuthority,
+            placement: newPlacement,
+            lease: null,
+        };
+        const key = this.encodeKey();
+        // Promotion consumes an active lease as part of the same CAS that changes
+        // authority and clears it. An expired lease is not an active predicate.
+        const expectedLeaseId = current.lease && current.lease.expiresAt > Date.now()
+            ? current.lease.leaseId
+            : undefined;
+        const result = await this.cellCollection.updateIfVersion(key, current.version, newState, current.authority.epoch, expectedLeaseId, true, current);
+        if (!result.updated) {
+            if (result.conflictCode === 'REPLICATION_CONFLICT') {
+                throw new Error(`REPLICATION_CONFLICT: divergent replica cannot be promoted`);
+            }
+            throw new Error(`PROMOTION_CONFLICT: cell state changed during promotion`);
+        }
+        // Emit change event for promotion
+        this.emitChange({
+            cellId: this.id,
+            version: newState.version,
+            value: current.value,
+            timestamp: newState.updatedAt,
+            epoch: newState.authority.epoch,
+        });
+        return this.snapshotFromState(newState);
+    }
+    async observeHealth(observation) {
+        // Observation does NOT use cell locking; it's a separate, concurrent observation stream
+        // Multiple observers can race; newer observations must win via CAS
+        const key = `observation_${this.id}_${observation.nodeId}`;
+        // Get current observation if one exists
+        const current = await this.failureObservationCollection.get(key);
+        // If current observation is newer, don't overwrite
+        if (current && current.observedAt > observation.observedAt) {
+            return; // Silently reject stale observation
+        }
+        // Use CAS to ensure two concurrent observers don't silently overwrite each other
+        if (current) {
+            const currentVersion = current.__version ?? 1;
+            const result = await this.failureObservationCollection.updateIfVersion(key, currentVersion, observation, 0);
+            if (!result.updated) {
+                // Another observer won the race; that's fine, failure detection is best-effort
+                return;
+            }
+        }
+        else {
+            // First observation for this node
+            await this.failureObservationCollection.insert(observation, key);
+        }
+    }
+    async evaluateFailure(options) {
+        // Evaluation is deterministic and read-only: no cell modifications whatsoever
+        const key = `observation_${this.id}_${options.nodeId}`;
+        const observation = await this.failureObservationCollection.get(key);
+        if (!observation) {
+            // No observation recorded; assume healthy
+            return {
+                status: 'healthy',
+                authorityEpoch: options.nodeId === (await this.getUnlocked())?.authority.owner ?
+                    (await this.getUnlocked())?.authority.epoch ?? 0 : 0,
+                nodeId: options.nodeId,
+            };
+        }
+        // Check if observation is for a stale epoch
+        const current = await this.getUnlocked();
+        if (current && observation.authorityEpoch < current.authority.epoch) {
+            // Observation is from an old epoch; ignore it
+            return {
+                status: 'healthy',
+                authorityEpoch: current.authority.epoch,
+                nodeId: options.nodeId,
+            };
+        }
+        // Determine age of observation
+        const ageMs = options.now - observation.lastSeenAt;
+        // Deterministic classification
+        let status;
+        if (ageMs < options.suspectAfterMs) {
+            status = 'healthy';
+        }
+        else if (ageMs < options.failedAfterMs) {
+            status = 'suspect';
+        }
+        else {
+            status = 'failed';
+        }
+        return {
+            status,
+            authorityEpoch: observation.authorityEpoch,
+            nodeId: options.nodeId,
+            ageMs,
+        };
+    }
+    async attemptAutomaticFailover(options) {
+        // Automatic failover: bridge from failure detection to controlled promotion
+        // Critical invariant: failure detection itself never grants authority.
+        // Only the durable backend CAS (in promote) is the final authority.
+        // Step 1: Check if this is a replica
+        if (!this.isReplica) {
+            return {
+                attempted: false,
+                promoted: false,
+                reason: 'Not a replica',
+                diagnostics: {
+                    isReplica: false,
+                    eligibilityChecksPassed: false,
+                    promotionAttempted: false,
+                    promotionSucceeded: false,
+                },
+            };
+        }
+        // One authoritative Cell read is shared by eligibility and promotion. The
+        // caller may pass the observation it just recorded, avoiding another HTTP
+        // round trip; legacy callers still load it durably here.
+        const current = options.replicaSnapshot
+            ?? await this.getUnlocked();
+        if (!current) {
+            return {
+                attempted: false,
+                promoted: false,
+                reason: 'Replica state not found',
+                diagnostics: {
+                    isReplica: true,
+                    eligibilityChecksPassed: false,
+                    promotionAttempted: false,
+                    promotionSucceeded: false,
+                },
+            };
+        }
+        const observationKey = `observation_${this.id}_${options.failureEvaluationOptions.nodeId}`;
+        const observation = options.failureObservation
+            ?? await this.failureObservationCollection.get(observationKey);
+        const failureEval = this.evaluateFailureSnapshot(options.failureEvaluationOptions, observation, current);
+        if (failureEval.status !== 'failed') {
+            return {
+                attempted: false,
+                promoted: false,
+                reason: `Current authority not failed (status: ${failureEval.status})`,
+                diagnostics: {
+                    isReplica: true,
+                    failureStatus: failureEval.status,
+                    eligibilityChecksPassed: false,
+                    promotionAttempted: false,
+                    promotionSucceeded: false,
+                },
+            };
+        }
+        // Step 4: Check lifecycle (retired cells cannot be promoted)
+        if (current.authority.lifecycle === 'retired') {
+            return {
+                attempted: false,
+                promoted: false,
+                reason: 'Cell is retired',
+                diagnostics: {
+                    isReplica: true,
+                    failureStatus: failureEval.status,
+                    eligibilityChecksPassed: false,
+                    promotionAttempted: false,
+                    promotionSucceeded: false,
+                },
+            };
+        }
+        // Step 5: Verify replica authority epoch matches observed authority epoch
+        // This ensures the replica has the same authority state as what was observed as failed
+        if (current.authority.epoch !== failureEval.authorityEpoch) {
+            // Replica is from a different epoch (stale or ahead)
+            return {
+                attempted: false,
+                promoted: false,
+                reason: `Replica authority epoch mismatch: replica=${current.authority.epoch}, observed=${failureEval.authorityEpoch}`,
+                diagnostics: {
+                    isReplica: true,
+                    failureStatus: failureEval.status,
+                    eligibilityChecksPassed: false,
+                    promotionAttempted: false,
+                    promotionSucceeded: false,
+                },
+            };
+        }
+        // Step 6: All eligibility checks passed; attempt atomic promotion
+        try {
+            await this.promoteSnapshot(current, {
+                expectedVersion: current.version,
+                expectedEpoch: current.authority.epoch,
+                newOwner: options.newOwner,
+                newNodeId: current.placement.nodeId,
+            });
+            return {
+                attempted: true,
+                promoted: true,
+                diagnostics: {
+                    isReplica: true,
+                    failureStatus: failureEval.status,
+                    eligibilityChecksPassed: true,
+                    promotionAttempted: true,
+                    promotionSucceeded: true,
+                },
+            };
+        }
+        catch (err) {
+            // Promotion failed (likely CAS conflict due to concurrent writer)
+            return {
+                attempted: true,
+                promoted: false,
+                reason: `Promotion failed: ${err instanceof Error ? err.message : String(err)}`,
+                diagnostics: {
+                    isReplica: true,
+                    failureStatus: failureEval.status,
+                    eligibilityChecksPassed: true,
+                    promotionAttempted: true,
+                    promotionSucceeded: false,
+                },
+            };
+        }
+    }
+    evaluateFailureSnapshot(options, observation, current) {
+        if (!observation) {
+            return {
+                status: 'healthy',
+                authorityEpoch: options.nodeId === current.authority.owner ? current.authority.epoch : 0,
+                nodeId: options.nodeId,
+            };
+        }
+        if (observation.authorityEpoch < current.authority.epoch) {
+            return { status: 'healthy', authorityEpoch: current.authority.epoch, nodeId: options.nodeId };
+        }
+        const ageMs = options.now - observation.lastSeenAt;
+        const status = ageMs < options.suspectAfterMs
+            ? 'healthy'
+            : ageMs < options.failedAfterMs ? 'suspect' : 'failed';
+        return { status, authorityEpoch: observation.authorityEpoch, nodeId: options.nodeId, ageMs };
+    }
+    validateLifecycleTransition(current, next) {
+        const validTransitions = {
+            active: ['suspended', 'retired'],
+            suspended: ['active', 'retired'],
+            retired: [],
+        };
+        if (!validTransitions[current].includes(next)) {
+            throw new Error(`Invalid lifecycle transition: ${current} → ${next}`);
+        }
+    }
+    async getUnlocked() {
+        const key = this.encodeKey();
+        const state = await this.cellCollection.get(key);
+        if (!state)
+            return null;
+        return this.snapshotFromState(state);
+    }
+    async setUnlocked(value, options) {
+        const current = await this.getUnlocked();
+        if (current?.authority.lifecycle === 'retired') {
+            throw new Error(`Cell ${this.id} is retired`);
+        }
+        const expectedEpoch = current?.authority.epoch ?? 0;
+        if (options?.authorityEpoch !== undefined && current) {
+            if (options.authorityEpoch !== expectedEpoch) {
+                throw new Error(`AUTHORITY_CONFLICT: expected epoch ${expectedEpoch}, got ${options.authorityEpoch}`);
+            }
+        }
+        // Validate lease if specified
+        if (options?.leaseId !== undefined) {
+            if (!current?.lease) {
+                throw new Error(`LEASE_INVALID: no active lease`);
+            }
+            if (current.lease.leaseId !== options.leaseId) {
+                throw new Error(`LEASE_INVALID: lease ID mismatch`);
+            }
+            if (current.lease.expiresAt <= Date.now()) {
+                throw new Error(`LEASE_EXPIRED: lease has expired`);
+            }
+            if (current.lease.epoch !== expectedEpoch) {
+                throw new Error(`LEASE_INVALID: lease epoch does not match authority epoch`);
+            }
+        }
+        const expectedVersion = current?.version ?? 0;
+        const authority = current?.authority ?? { owner: null, epoch: 0, lifecycle: 'active' };
+        const placement = current?.placement ?? { nodeId: null };
+        const lease = current?.lease ?? null;
+        const newState = {
+            id: this.id,
+            version: expectedVersion + 1,
+            value,
+            updatedAt: new Date().toISOString(),
+            authority,
+            placement,
+            lease,
+        };
+        const key = this.encodeKey();
+        if (expectedVersion === 0) {
+            await this.cellCollection.insert(newState, key);
+        }
+        else {
+            const result = await this.cellCollection.updateIfVersion(key, expectedVersion, newState, expectedEpoch);
+            if (!result.updated) {
+                throw new Error(`Cell ${this.id} version conflict`);
+            }
+        }
+        this.emitChange({
+            cellId: this.id,
+            version: newState.version,
+            value,
+            timestamp: newState.updatedAt,
+            epoch: newState.authority.epoch,
+        });
+        return this.snapshotFromState(newState);
+    }
+    async updateUnlocked(updater, options) {
+        const current = await this.getUnlocked();
+        if (current?.authority.lifecycle === 'retired') {
+            throw new Error(`Cell ${this.id} is retired`);
+        }
+        const expectedEpoch = current?.authority.epoch ?? 0;
+        if (options?.authorityEpoch !== undefined && current) {
+            if (options.authorityEpoch !== expectedEpoch) {
+                throw new Error(`AUTHORITY_CONFLICT: expected epoch ${expectedEpoch}, got ${options.authorityEpoch}`);
+            }
+        }
+        // Validate lease if specified
+        if (options?.leaseId !== undefined) {
+            if (!current?.lease) {
+                throw new Error(`LEASE_INVALID: no active lease`);
+            }
+            if (current.lease.leaseId !== options.leaseId) {
+                throw new Error(`LEASE_INVALID: lease ID mismatch`);
+            }
+            if (current.lease.expiresAt <= Date.now()) {
+                throw new Error(`LEASE_EXPIRED: lease has expired`);
+            }
+            if (current.lease.epoch !== expectedEpoch) {
+                throw new Error(`LEASE_INVALID: lease epoch does not match authority epoch`);
+            }
+        }
+        const currentValue = current?.value ?? null;
+        const currentVersion = current?.version ?? 0;
+        const nextValue = updater(currentValue);
+        if (nextValue === NO_CHANGE) {
+            if (current)
+                return this.snapshotFromState(current);
+            throw new Error(`Cell ${this.id} update returned NO_CHANGE but cell does not exist`);
+        }
+        const authority = current?.authority ?? { owner: null, epoch: 0, lifecycle: 'active' };
+        const placement = current?.placement ?? { nodeId: null };
+        const lease = current?.lease ?? null;
+        const newState = {
+            id: this.id,
+            version: currentVersion + 1,
+            value: nextValue,
+            updatedAt: new Date().toISOString(),
+            authority,
+            placement,
+            lease,
+        };
+        const key = this.encodeKey();
+        if (currentVersion === 0) {
+            await this.cellCollection.insert(newState, key);
+        }
+        else {
+            const result = await this.cellCollection.updateIfVersion(key, currentVersion, newState, expectedEpoch);
+            if (!result.updated) {
+                throw new Error(`Cell ${this.id} conflict during update`);
+            }
+        }
+        this.emitChange({
+            cellId: this.id,
+            version: newState.version,
+            value: nextValue,
+            timestamp: newState.updatedAt,
+            epoch: newState.authority.epoch,
+        });
+        return this.snapshotFromState(newState);
+    }
+    snapshotFromState(state) {
+        return {
+            id: this.id,
+            version: state.version,
+            value: state.value,
+            updatedAt: state.updatedAt,
+            authority: state.authority,
+            placement: state.placement,
+            lease: state.lease,
+        };
+    }
+    on(event, handler) {
+        if (event === 'change') {
+            this.changeHandlers.push(handler);
+        }
+    }
+    off(event, handler) {
+        if (event === 'change') {
+            const idx = this.changeHandlers.indexOf(handler);
+            if (idx >= 0)
+                this.changeHandlers.splice(idx, 1);
+        }
+    }
+    emitChange(event) {
+        for (const handler of this.changeHandlers) {
+            try {
+                handler(event);
+            }
+            catch (err) {
+                console.error(`Error in cell change handler: ${err}`);
+            }
+        }
+    }
+    acquireLock(fn) {
+        return new Promise((resolve, reject) => {
+            const task = async () => {
+                try {
+                    const result = await fn();
+                    resolve(result);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            };
+            this.mutationQueue.push(task);
+            if (!this.isLocked) {
+                this.processQueue();
+            }
+        });
+    }
+    async processQueue() {
+        if (this.isLocked) {
+            return;
+        }
+        if (this.mutationQueue.length === 0) {
+            return;
+        }
+        this.isLocked = true;
+        const task = this.mutationQueue.shift();
+        if (task) {
+            try {
+                await task();
+            }
+            catch (err) {
+                // Task already rejected its promise
+            }
+            finally {
+                this.isLocked = false;
+                this.processQueue();
+            }
+        }
+    }
+}